infrasynth-backend-kit/README.md

# InfraSynth Base

Reusable, multi-tenant Django infrastructure kit — the one shared package every InfraSynth app depends on.

```bash
pip install -e ".[dev]"          # install the kit + dev tooling
docker compose up -d db redis    # postgres + redis
python manage.py migrate         # create the schema
python manage.py runserver       # http://localhost:8000/api/v1/schema/docs/
```

Then `pytest` (single-command test suite), `ruff check .`, and `mypy infrasynth/`.

---

## What this is

One pip package (`infrasynth-base`) providing ten Django apps so no app ever reimplements auth, tenancy, entitlements, audit, files, notifications, webhooks, workflows, scheduling, or the API envelope:

| Module | Responsibility |
|---|---|
| `infrasynth.shared` | Zero-Django primitives: protocols, enums, `Result`, Fernet crypto, settings helper |
| `infrasynth.api` | DRF envelope, camelCase, cursor pagination, request-id, exceptions, throttling, idempotency, webhook hardening |
| `infrasynth.tenancy` | `Tenant`, membership, invitations, platform staff, `current_tenant`, scoped managers, middleware |
| `infrasynth.security` | JWT cookie + API-key auth, roles/grants/revokes, 2FA (TOTP), ALTCHA, login brute-force guard, password policy |
| `infrasynth.audit` | Passive create/update/delete tracking, API interaction log, security events, retention purge |
| `infrasynth.features` | Operational feature flags with tenant/user/group overrides, rollout %, environment targeting |
| `infrasynth.billing` | App catalog, plans, entitlements, subscriptions, invoices, gateways, entitlement lifecycle jobs |
| `infrasynth.files` | Storage abstraction (S3/GCS/local/Cloudinary), signed URLs, processing pipelines, pluggable virus scanning |
| `infrasynth.notifications` | Multi-channel delivery with failover, retries, rate limits, and log retention |
| `infrasynth.webhooks` | Outbound delivery with HMAC + retry, verified inbound processing, event registry |
| `infrasynth.workflows` | State-machine engine, voting/approval strategies, validators |
| `infrasynth.scheduler` | Celery job dashboard + on-demand execution |

**Every app is multi-tenant.** One deployment, one schema, row-level isolation via a non-null `tenant_id`, a fail-closed `TenantManager`, and cross-tenant access that returns `404`. See `../TENANCY.md` (binding).

**There is no license server.** Access is an in-process *entitlement* (`is_entitled` / `check_limit`), enforced server-side. See `../ENTITLEMENTS.md` (binding).

---

## Configuration

Every knob is a namespaced dict with a safe default, read through `infrasynth.shared.settings_utils.get_setting`:

```python
INFRASYNTH_SECURITY = {"COOKIE_SECURE": True, "IP_BLACKLIST_THRESHOLD": 100}
INFRASYNTH_TENANCY = {"REQUIRE_TENANT_BY_DEFAULT": True, "TENANT_CLAIM": "tenant"}
INFRASYNTH_BILLING = {"GRACE_PERIOD_DAYS": 5, "DEFAULT_CURRENCY": "USD"}
INFRASYNTH_NOTIFICATIONS = {"CHANNELS": {"email": {"primary": "myapp.channels.SlackChannel"}}}
```

The full, commented reference lives in `config/settings/base.py`. Real settings files **never** live in this package — apps supply their own and pin the kit.

---

## Extending without forking

Integrate through settings, signals, registries, ABCs, and feature flags — never a local patch:

```python
# myapp/channels.py
from infrasynth.notifications.channels.base import BaseChannel
from infrasynth.shared.results import Result

class SlackChannel(BaseChannel):
    channel_type = "slack"
    def send(self, recipient, subject, body, is_html=True, attachments=None):
        ...
        return Result.ok(True)
    def health_check(self) -> bool:
        return True
    @classmethod
    def from_config(cls, config): return cls(**config)
```

Registries are populated in `apps.py:ready()`: `FeatureRegistry`, `EventRegistry`, `VariableResolverRegistry`, `DataValidatorRegistry`, `PipelineStepRegistry`.

### Extension points, per module

Every module is swappable through settings/registries — no kit edits, no forks:

| Module | How a consumer extends it |
|---|---|
| `shared` | Use the primitives directly (`Result`, `encrypt/decrypt`, `get_setting`, protocols) |
| `api` | Override `renderer/pagination/exception handler` per view; add idempotency with `@idempotent` |
| `tenancy` | `TenantService`, scoped managers, `tenant_context`; configure `INFRASYNTH_TENANCY` |
| `security` | `AUTH_BACKEND_CLASS`; `TWO_FACTOR_SERVICE`/`TWO_FACTOR_RECOVERY_SERVICE`; `PasswordPolicyValidator`; custom permission classes; `infrasynth.gates` |
| `audit` | `EXCLUDED_MODELS`/`EXCLUDED_FIELDS`/`SENSITIVE_KEYS`/`STORE_IN_DB`; listen to `security_event_occurred` |
| `features` | `FeatureRegistry.register(...)` or `INFRASYNTH_FEATURES["FLAGS"]`; `FeatureFlagOverride` rows |
| `billing` | Gateway via `PaymentGateway.gateway_class`; `INVOICE_PDF_BUILDER`; `Entitlement`/`plan` |
| `files` | `register_storage_backend(...)` or `STORAGE_BACKENDS[name]["CLASS"]`; `PipelineStepRegistry.register(...)`; `PIPELINE_EXECUTOR`; `VIRUS_SCANNER` |
| `notifications` | `INFRASYNTH_NOTIFICATIONS["CHANNELS"]` dotted paths; `VariableResolverRegistry` |
| `webhooks` | `EventRegistry`; `InboundEndpoint.handler` dotted path; signature algorithm setting |
| `workflows` | `DataValidatorRegistry`; node/transition data; `WorkflowAwareModel` |
| `scheduler` | `ScheduledTask.task_path` dotted path (any Celery task or callable) |

A consuming app never imports another app's models directly — it uses the
services, registries, signals, and `infrasynth.gates` documented here.

---

## Gating your own endpoints (no kit edits)

`infrasynth.gates` is the composable, per-endpoint access layer. A view declares
exactly what it needs; the default is **gate nothing**:

```python
from rest_framework.permissions import AllowAny, IsAuthenticated
from infrasynth.gates import (
    GatePermission, gated,
    TwoFactorGate, AltchaGate, EntitlementGate, FeatureGate, PermissionGate,
)

# Public form: proof-of-work, no login.
class SignupView(APIView):
    permission_classes = [AllowAny, GatePermission]
    infrasynth_gates = [AltchaGate()]

# Sensitive action: step-up 2FA + commercial right + codename.
class PayoutView(APIView):
    permission_classes = [IsAuthenticated, GatePermission]
    infrasynth_gates = [
        TwoFactorGate(),                                # passes users without 2FA;
        EntitlementGate("billing", feature="payouts"),  # use require_configured=True to demand setup
        PermissionGate("billing.payout"),
    ]

class TicketViewSet(ModelViewSet):
    permission_classes = [IsAuthenticated, GatePermission]
    infrasynth_gates = [FeatureGate("ticketing")]       # 404 when the flag is off

    @gated(TwoFactorGate())
    @action(detail=True, methods=["post"])
    def close(self, request, pk=None): ...
```

- Gates run in order; the first denial raises the matching namespaced error
  (`AUTH_*`, `ENTITLEMENT_*`, `VALIDATION_*`, `NOT_FOUND`) so the envelope gets
  the right code and status. No gates declared ⇒ the permission is a no-op.
- `GatePermission` is in `DEFAULT_PERMISSION_CLASSES`; the kit's own
  `HybridPermission`/`IsAuthenticatedAndPermitted` also evaluate declared gates,
  so you only add it explicitly on views that use plain DRF permissions.
- `AltchaGate` accepts the solution in a JSON `altcha` object, flat body/query
  keys, or the `X-Altcha: <challenge_id>:<solution>:<number>` header; clients get
  a challenge from `/api/v1/auth/altcha/challenge/`.
- `TwoFactorGate` verifies a JWT `2fa` claim (minted at verification and carried
  across workspace selection) or a verified session. Users without 2FA pass by
  default; `require_configured=True` denies them with `AUTH_2FA_SETUP_REQUIRED`.

Every gate is also a plain class implementing `check(request, view) -> GateResult`,
so an app can ship its own (e.g. an IP allow-list) and pass it to `@gated(...)`.

---

## Stable import paths

Consumers import from the public modules, never internal helpers:

| Need | Import |
|---|---|
| Gating | `from infrasynth.gates import GatePermission, AltchaGate, …` |
| Permissions/auth | `from infrasynth.security.permissions import HybridPermission` |
| JWT/API-key auth | `from infrasynth.security.auth.cookies import CookieJWTAuthentication` |
| Authorization | `from infrasynth.security.services import AuthorizationService` |
| Tenant context/scoping | `from infrasynth.tenancy.managers import TenantManager` |
| Entitlements | `from infrasynth.billing.entitlements import EntitlementService` |
| Feature flags | `from infrasynth.features.services import FeatureService` |
| Storage | `from infrasynth.files.storage import get_storage_backend` |
| Errors/envelope | `from infrasynth.shared.exceptions import EntitlementError` |
| Wire format | `from infrasynth.api.renderers import EnvelopeJSONRenderer` |


---

## Scheduled work

`CELERY_BEAT_SCHEDULE` ships with the kit: notification retries/log purge, billing sync + lifecycle + renewal invoices, and audit retention. Run `celery -A config beat` and `celery -A config worker`.

---

## Quality bar

- `ruff check` + `ruff format --check` + `mypy infrasynth/` are CI gates.
- `pytest` runs the full suite; coverage is enforced in CI (see `pyproject.toml`).
- A change to kit behavior belongs **here**, then consuming apps bump their pin — see `../AGENTS.backend-packages.md` §9.