svc-infra 0.1.600__py3-none-any.whl → 0.1.664__py3-none-any.whl

svc_infra/docs/acceptance-matrix.md

@@ -0,0 +1,88 @@
+# Acceptance Matrix (A-IDs)
+
+This document maps Acceptance scenarios (A-IDs) to endpoints, CLIs, fixtures, and seed data. Use it to drive the CI promotion gate and local `make accept` runs.
+
+## A0. Harness
+- Stack: docker-compose.test.yml (api, db, redis)
+- Makefile targets: accept, compose_up, wait, seed, down
+- Tests bootstrap: tests/acceptance/conftest.py (BASE_URL), _auth.py, _seed.py, _http.py
+
+## A1. Security & Auth
+- A1-01 Register → Verify → Login → /auth/me
+  - Endpoints: POST /auth/register, POST /auth/verify, POST /auth/login, GET /auth/me
+  - Fixtures: admin, user
+- A1-02 Password policy & breach check
+  - Endpoints: POST /auth/register
+- A1-03 Lockout escalation and cooldown
+  - Endpoints: POST /auth/login
+- A1-04 RBAC/ABAC enforced
+  - Endpoints: GET /admin/*, resource GET with owner guard
+- A1-05 Session list & revoke
+  - Endpoints: GET/DELETE /auth/sessions
+- A1-06 API keys lifecycle
+  - Endpoints: POST/GET/DELETE /auth/api-keys, usage via Authorization header
+- A1-07 MFA lifecycle
+  - Endpoints: /auth/mfa/*
+
+## A2. Rate Limiting
+- A2-01 Global limit → 429 with Retry-After
+- A2-02 Per-route & tenant override honored
+- A2-03 Window reset
+
+## A3. Idempotency & Concurrency
+- A3-01 Same Idempotency-Key → identical 2xx
+- A3-02 Conflicting payload + same key → 409
+- A3-03 Optimistic lock mismatch → 409; success increments version
+
+## A4. Jobs & Scheduling
+- A4-01 Custom job consumed
+- A4-02 Backoff & DLQ
+- A4-03 Cron tick observed
+
+## A5. Webhooks
+- A5-01 Producer → delivery (HMAC verified)
+- A5-02 Retry stops on success
+- A5-03 Secret rotation window accepts old+new
+
+## A6. Tenancy
+- A6-01 tenant_id injected on create; list scoped
+- A6-02 Cross-tenant → 404/403
+- A6-03 Per-tenant quotas enforced
+
+## A7. Data Lifecycle
+- A7-01 Soft delete hides; undelete restores
+- A7-02 GDPR erasure steps with audit
+- A7-03 Retention purge soft→hard
+- A7-04 Backup verification healthy
+
+## A8. SLOs & Ops
+- A8-01 Metrics http_server_* and db_pool_* present
+- A8-02 Maintenance mode 503; circuit breaker trips/recover
+- A8-03 Liveness/readiness under DB up/down
+
+## A9. OpenAPI & Error Contracts
+- A9-01 /openapi.json valid; examples present
+- A9-02 Problem+JSON conforms
+- A9-03 Spectral + API Doctor pass
+
+## A10. CLI & DX
+- A10-01 DB migrate/rollback/seed
+- A10-02 Jobs runner consumes a sample job
+- A10-03 SDK smoke-import and /ping
+
+## A22. Storage System
+- A22-01 Local backend file upload and retrieval
+  - Endpoints: POST /_storage/upload, GET /_storage/download/{filename}
+  - Assertions: Upload returns URL, download returns matching content
+- A22-02 S3 backend operations (memory backend in acceptance)
+  - Endpoints: POST /_storage/upload, GET /_storage/download/{filename}
+  - Assertions: Upload succeeds, download returns correct content
+- A22-03 Storage backend auto-detection
+  - Endpoints: GET /_storage/backend-info, POST /_storage/upload
+  - Assertions: Backend detected (MemoryBackend), app.state.storage configured
+- A22-04 File deletion and cleanup
+  - Endpoints: POST /_storage/upload, DELETE /_storage/files/{filename}, GET /_storage/download/{filename}
+  - Assertions: Upload succeeds, delete returns 204, subsequent GET returns 404
+- A22-05 Metadata and listing
+  - Endpoints: POST /_storage/upload, GET /_storage/list, GET /_storage/metadata/{filename}
+  - Assertions: Metadata stored and retrievable, list returns correct keys, prefix filtering works

svc_infra/docs/acceptance.md

@@ -0,0 +1,44 @@
+# Pre-Deploy Acceptance (Promotion Gate)
+
+This guide describes the acceptance harness that runs post-build against an ephemeral stack. Artifacts are promoted only if acceptance checks pass.
+
+## Stack
+- docker-compose.test.yml: api (uvicorn serving tests.acceptance.app), optional db/redis (via profiles), and a tester container to run pytest inside
+- Makefile targets: accept, compose_up, wait, seed, down
+- Health probes: /healthz (liveness), /readyz (readiness), /startupz (startup)
+
+## Workflow
+1. Build image
+2. docker compose up -d (test stack)
+3. CLI DB checks & seed: run `sql setup-and-migrate`, `sql current`, `sql downgrade -1`, `sql upgrade head` against an ephemeral SQLite DB, then call `sql seed tests.acceptance._seed:acceptance_seed` (no-op by default)
+4. Run pytest inside tester: docker compose run --rm tester (Makefile wires this)
+5. OpenAPI lint & API Doctor
+6. Teardown
+
+## Supply-chain & Matrix (v1 scope)
+- SBOM: generate and upload as artifact; image scan (Trivy/Grype) with severity gate.
+- Provenance: sign/attest images (cosign/SLSA) on best-effort basis.
+- Backend matrix: run acceptance against two stacks via COMPOSE_PROFILES:
+	1) in-memory stores (default), 2) Redis + Postgres (COMPOSE_PROFILES=pg-redis).
+
+## Additional Acceptance Checks (fast wins)
+- Headers/CORS: assert HSTS, X-Content-Type-Options, Referrer-Policy, X-Frame-Options/SameSite; OPTIONS preflight behavior.
+- Resilience: restart DB/Redis during request; expect breaker trip and recovery.
+- DR drill: restore a tiny SQL dump then run smoke.
+- OpenAPI invariants: no orphan routes; servers block correctness for versions; 100% examples for public JSON; stable operationIds; reject /auth/{id} path via lint rule.
+- CLI contracts: `svc-infra --help` and key subcommands exit 0 and print expected flags.
+
+## Local usage
+- make accept (runs the full flow locally)
+- make down (tears down the stack)
+- To run tests manually: docker compose run --rm tester
+- To target a different backend: COMPOSE_PROFILES=pg-redis make accept
+
+## Files
+- tests/acceptance/conftest.py: BASE_URL, httpx client, fixtures
+- tests/acceptance/_auth.py: login/register helpers
+- tests/acceptance/_seed.py: seed users/tenants/api keys
+- tests/acceptance/_http.py: HTTP helpers
+
+## Scenarios
+See docs/acceptance-matrix.md for A-IDs and mapping to endpoints.

svc_infra/docs/admin.md

@@ -0,0 +1,425 @@
+# Admin Scope & Operations
+
+This guide covers the admin subsystem: admin-only routes, permissions, impersonation, and operational guardrails.
+
+## Overview
+
+The admin module provides:
+- **Admin router pattern**: Role-gated endpoints under `/admin` with fine-grained permission checks
+- **Impersonation**: Controlled user impersonation for support and debugging with full audit trails
+- **Permission alignment**: `admin.impersonate` permission integrated with the RBAC system
+- **Easy integration**: One-line setup via `add_admin(app, ...)`
+
+## Quick Start
+
+### Basic Setup
+
+```python
+from fastapi import FastAPI
+from svc_infra.api.fastapi.admin import add_admin
+
+app = FastAPI()
+
+# Mount admin endpoints with defaults
+add_admin(app)
+
+# Endpoints are now available:
+# POST /admin/impersonate/start
+# POST /admin/impersonate/stop
+```
+
+### Custom User Loader
+
+If you have a custom user model or retrieval logic:
+
+```python
+from fastapi import Request
+
+async def my_user_getter(request: Request, user_id: str):
+    # Your custom user loading logic
+    user = await my_user_service.get_user(user_id)
+    if not user:
+        raise HTTPException(404, "user_not_found")
+    return user
+
+add_admin(app, impersonation_user_getter=my_user_getter)
+```
+
+### Configuration
+
+Environment variables:
+
+- `ADMIN_IMPERSONATION_SECRET`: Secret for signing impersonation tokens (falls back to `APP_SECRET` or `"dev-secret"`)
+- `ADMIN_IMPERSONATION_TTL`: Token TTL in seconds (default: 900 = 15 minutes)
+- `ADMIN_IMPERSONATION_COOKIE`: Cookie name (default: `"impersonation"`)
+
+Function parameters:
+
+```python
+add_admin(
+    app,
+    base_path="/admin",              # Base path for admin routes
+    enable_impersonation=True,        # Enable impersonation endpoints
+    secret=None,                      # Override token signing secret
+    ttl_seconds=15 * 60,              # Token TTL (15 minutes)
+    cookie_name="impersonation",      # Cookie name
+    impersonation_user_getter=None,   # Custom user loader
+)
+```
+
+## Permissions & RBAC
+
+### Admin Role
+
+The `admin` role includes the following permissions by default:
+
+- `user.read`, `user.write`: User management
+- `billing.read`, `billing.write`: Billing operations
+- `security.session.list`, `security.session.revoke`: Session management
+- `admin.impersonate`: User impersonation
+
+### Permission Guards
+
+Admin endpoints use layered guards:
+
+1. **Role gate** at router level: `RequireRoles("admin")`
+2. **Permission gate** at endpoint level: `RequirePermission("admin.impersonate")`
+
+This ensures both coarse-grained role membership and fine-grained permission enforcement.
+
+### Custom Admin Routes
+
+```python
+from svc_infra.api.fastapi.admin import admin_router
+from svc_infra.security.permissions import RequirePermission
+
+# Create an admin-only router
+router = admin_router(prefix="/admin", tags=["admin"])
+
+@router.get("/analytics", dependencies=[RequirePermission("analytics.read")])
+async def admin_analytics():
+    return {"data": "..."}
+
+app.include_router(router)
+```
+
+## Impersonation
+
+### Use Cases
+
+- **Customer support**: Debug issues as the affected user
+- **Testing**: Verify permission boundaries and user-specific behavior
+- **Compliance**: Audit access patterns under controlled conditions
+
+### Workflow
+
+#### 1. Start Impersonation
+
+```bash
+POST /admin/impersonate/start
+Content-Type: application/json
+
+{
+  "user_id": "u-12345",
+  "reason": "Investigating billing issue #789"
+}
+```
+
+**Requirements:**
+- Authenticated user must have `admin` role
+- User must have `admin.impersonate` permission
+- `reason` field is mandatory
+
+**Response:** `204 No Content` with impersonation cookie set
+
+#### 2. Make Requests as Impersonated User
+
+All subsequent requests will be made as the target user while preserving the admin's permissions for authorization checks:
+
+```bash
+GET /api/v1/profile
+Cookie: impersonation=<token>
+
+# Returns the impersonated user's profile
+```
+
+**Behavior:**
+- `request.user` reflects the impersonated user
+- `request.user.roles` inherits the actor's roles (admin maintains permissions)
+- `principal.via` is set to `"impersonated"` for tracking
+
+#### 3. Stop Impersonation
+
+```bash
+POST /admin/impersonate/stop
+
+# Response: 204 No Content
+# Cookie deleted, subsequent requests use original identity
+```
+
+### Security Guardrails
+
+#### Short TTL
+- Default: 15 minutes
+- No sliding refresh: token expires after TTL regardless of activity
+- Rationale: Minimize blast radius of compromised impersonation sessions
+
+#### Explicit Reason
+- Required for every impersonation start
+- Logged in audit trail for compliance and forensics
+
+#### Audit Trail
+Every impersonation action is logged with:
+- `admin.impersonation.started`: actor, target, reason, expiry
+- `admin.impersonation.stopped`: termination reason (manual/expired)
+
+Example log entry:
+```json
+{
+  "message": "admin.impersonation.started",
+  "actor_id": "u-admin-42",
+  "target_id": "u-12345",
+  "reason": "Investigating billing issue #789",
+  "expires_in": 900,
+  "timestamp": "2025-11-01T12:00:00Z"
+}
+```
+
+#### Token Security
+- HMAC-SHA256 signed tokens with nonce
+- Includes: actor_id, target_id, issued_at, expires_at, nonce
+- Tamper detection via signature verification
+- Cookie attributes:
+  - `httponly=true`: No JavaScript access
+  - `samesite=lax`: CSRF protection
+  - `secure=true` in production: HTTPS only
+
+#### Permission Preservation
+- Impersonated requests maintain the actor's permissions
+- Prevents privilege escalation by impersonating a higher-privileged user
+- Target user context for data scoping, actor permissions for authorization
+
+### Operational Recommendations
+
+#### Development
+```python
+# Relaxed for local testing
+add_admin(
+    app,
+    secret="dev-secret",
+    ttl_seconds=60 * 60,  # 1 hour for convenience
+)
+```
+
+#### Production
+```python
+# Strict settings
+add_admin(
+    app,
+    secret=os.environ["ADMIN_IMPERSONATION_SECRET"],  # Strong secret from vault
+    ttl_seconds=15 * 60,  # 15 minutes max
+)
+```
+
+**Best practices:**
+- Rotate `ADMIN_IMPERSONATION_SECRET` periodically
+- Monitor impersonation logs for anomalies
+- Set up alerts for frequent impersonation by the same actor
+- Consider org/tenant scoping for multi-tenant systems
+- Document allowed impersonation reasons in your runbook
+
+## Monitoring & Observability
+
+### Metrics
+
+Label admin routes with `route_class=admin` for SLO tracking:
+
+```python
+from svc_infra.obs.add import add_observability
+
+def route_classifier(path: str) -> str:
+    if path.startswith("/admin"):
+        return "admin"
+    # ... other classifications
+    return "public"
+
+add_observability(app, route_classifier=route_classifier)
+```
+
+### Audit Log Queries
+
+Search for impersonation events:
+```python
+# Example: Query structured logs
+logs.filter(message="admin.impersonation.started") \
+    .filter(actor_id="u-admin-42") \
+    .order_by(timestamp.desc()) \
+    .limit(100)
+```
+
+Compliance report:
+```python
+# Generate monthly impersonation summary
+impersonations = audit_log.filter(
+    event_type__in=["admin.impersonation.started", "admin.impersonation.stopped"],
+    timestamp__gte=start_of_month,
+)
+report = impersonations.group_by("actor_id").agg(count="id", targets=unique("target_id"))
+```
+
+## Testing
+
+### Unit Tests
+
+```python
+import pytest
+from svc_infra.api.fastapi.admin import add_admin
+
+@pytest.mark.admin
+def test_impersonation_requires_permission():
+    app = make_test_app()
+    add_admin(app, impersonation_user_getter=lambda req, uid: User(id=uid))
+
+    # Without admin role → 403
+    client = TestClient(app)
+    r = client.post("/admin/impersonate/start", json={"user_id": "u-2", "reason": "test"})
+    assert r.status_code == 403
+```
+
+### Acceptance Tests
+
+```python
+@pytest.mark.acceptance
+@pytest.mark.admin
+def test_impersonation_lifecycle(admin_client):
+    # Start impersonation
+    r = admin_client.post(
+        "/admin/impersonate/start",
+        json={"user_id": "u-target", "reason": "acceptance test"}
+    )
+    assert r.status_code == 204
+
+    # Verify impersonated context
+    profile = admin_client.get("/api/v1/profile")
+    assert profile.json()["id"] == "u-target"
+
+    # Stop impersonation
+    r = admin_client.post("/admin/impersonate/stop")
+    assert r.status_code == 204
+```
+
+Run admin tests:
+```bash
+pytest -m admin
+```
+
+## Troubleshooting
+
+### Impersonation Not Working
+
+**Symptom:** Impersonation cookie set but requests still use original identity
+
+**Check:**
+1. Cookie is being sent: verify `Cookie: impersonation=<token>` in request headers
+2. Token is valid: check signature and expiry
+3. User getter succeeds: ensure `impersonation_user_getter` doesn't raise exceptions
+4. Dependency override is active: `add_admin` registers a global override on startup
+
+**Debug:**
+```python
+# Enable debug logging
+import logging
+logging.getLogger("svc_infra.api.fastapi.admin").setLevel(logging.DEBUG)
+```
+
+### Permission Denied
+
+**Symptom:** 403 when calling `/admin/impersonate/start`
+
+**Check:**
+1. User has `admin` role: verify `user.roles` includes `"admin"`
+2. Permission registered: ensure `admin.impersonate` is in the permission registry
+3. Permission assigned to role: check `PERMISSION_REGISTRY["admin"]` includes `"admin.impersonate"`
+
+### Token Expired Too Soon
+
+**Symptom:** Impersonation session ends before expected TTL
+
+**Possible causes:**
+1. TTL misconfigured: check `ADMIN_IMPERSONATION_TTL` environment variable
+2. Server time skew: verify system clock is synchronized (NTP)
+3. Cookie attributes: ensure `max_age` matches TTL
+
+## Security Considerations
+
+### Threat Model
+
+| Threat | Mitigation |
+|--------|-----------|
+| Token theft (XSS) | `httponly=true` cookie prevents JavaScript access |
+| Token theft (network) | `secure=true` requires HTTPS in production |
+| CSRF attacks | `samesite=lax` prevents cross-site cookie sending |
+| Privilege escalation | Actor permissions preserved during impersonation |
+| Prolonged access | Short TTL (15 min default) with no refresh |
+| Abuse detection | Audit logs with reason, actor, and target tracking |
+| Insider threat | Required reason and comprehensive audit trail |
+
+### Compliance
+
+**SOC 2 / ISO 27001:**
+- Audit trail requirement: ✅ All impersonation events logged
+- Access justification: ✅ Mandatory `reason` field
+- Time-bound access: ✅ Short TTL with no renewal
+- Least privilege: ✅ Permission-based access control
+
+**GDPR / Data Protection:**
+- Lawful basis: Support/debugging under legitimate interest or contract performance
+- Data minimization: Only necessary user context loaded
+- Transparency: Log access for data subject access requests (DSAR)
+- Documentation: This guide serves as basis for DPA documentation
+
+## API Reference
+
+### `add_admin(app, **kwargs)`
+
+Wire admin endpoints and impersonation to a FastAPI app.
+
+**Parameters:**
+- `app` (FastAPI): Target application
+- `base_path` (str): Admin router base path (default: `"/admin"`)
+- `enable_impersonation` (bool): Enable impersonation endpoints (default: `True`)
+- `secret` (str | None): Token signing secret (default: env `ADMIN_IMPERSONATION_SECRET`)
+- `ttl_seconds` (int): Token TTL (default: `900` = 15 minutes)
+- `cookie_name` (str): Cookie name (default: `"impersonation"`)
+- `impersonation_user_getter` (Callable | None): Custom user loader `(request, user_id) -> user`
+
+**Returns:** None (modifies app in place)
+
+**Idempotency:** Safe to call multiple times; only wires once per app instance
+
+### `admin_router(**kwargs)`
+
+Create an admin-only router with role gate.
+
+**Parameters:** Same as `APIRouter` (FastAPI)
+
+**Returns:** APIRouter with `RequireRoles("admin")` dependency
+
+**Example:**
+```python
+from svc_infra.api.fastapi.admin import admin_router
+
+router = admin_router(prefix="/admin/reports", tags=["admin-reports"])
+
+@router.get("/summary")
+async def admin_summary():
+    return {"total_users": 1234}
+```
+
+## Further Reading
+
+- [ADR 0011: Admin scope and impersonation](../src/svc_infra/docs/adr/0011-admin-scope-and-impersonation.md)
+- [Security & Auth Hardening](./security.md)
+- [Permissions & RBAC](./security.md#permissions-and-rbac)
+- [Audit Logging](./security.md#audit-logging)
+- [Observability](./observability.md)

svc_infra/docs/adr/0002-background-jobs-and-scheduling.md

@@ -0,0 +1,40 @@
+# ADR 0002: Background Jobs & Scheduling
+
+Date: 2025-10-15
+
+Status: Accepted
+
+## Context
+We need production-grade background job processing and simple scheduling with a one-call setup. The library already includes in-memory queue/scheduler for tests/local. We need a production backend and a minimal runner.
+
+## Decision
+- JobQueue protocol defines enqueue/reserve/ack/fail with retry and exponential backoff (base seconds * attempts). Jobs have: id, name, payload, available_at, attempts, max_attempts, backoff_seconds, last_error.
+- Backends:
+  - InMemoryJobQueue for tests/local.
+  - RedisJobQueue for production using Redis primitives with visibility timeout and atomic operations.
+- Scheduler:
+  - InMemoryScheduler providing interval-based scheduling via next_run_at. Cron parsing is out of scope initially; a simple YAML loader can be added later.
+- Runner:
+  - A CLI loop `svc-infra jobs run` will tick the scheduler and process jobs in a loop with small sleep/backoff.
+- Configuration:
+  - One-call `easy_jobs()` returns (queue, scheduler). Picks backend via `JOBS_DRIVER` env (memory|redis). Redis URL via `REDIS_URL`.
+
+## Alternatives Considered
+- Using RQ/Huey/Celery: heavier dependency and less control over API ergonomic goals; we prefer thin primitives aligned with svc-infra patterns.
+- SQL-backed queue first: we will consider later; Redis is sufficient for v1.
+
+## Consequences
+- Enables outbox/webhook processors on a reliable queue.
+- Minimal cognitive load: consistent APIs, ENV-driven.
+- Future work: SQL queue, cron YAML loader, metrics, concurrency controls.
+
+## Redis Data Model (initial)
+- List `jobs:ready` holds ready job IDs; a ZSET `jobs:delayed` with score=available_at keeps delayed jobs; a HASH per job `job:{id}` stores fields.
+- Reserve uses RPOPLPUSH from `jobs:ready` to `jobs:processing` or BRPOPLPUSH with timeout; sets `visible_at` on job as now+vt and increments `attempts`.
+- Ack removes job from `jobs:processing` and deletes `job:{id}`.
+- Fail increments attempts and computes next available_at = now + backoff_seconds * attempts; moves job to delayed ZSET.
+- A housekeeping step periodically moves due jobs from delayed ZSET to ready list. Reserve also checks ZSET for due jobs opportunistically.
+
+## Testing Strategy
+- Unit tests cover enqueue/reserve/ack/fail, visibility timeout behavior, and DLQ after max_attempts.
+- Runner tests cover one iteration loop processing.

svc_infra/docs/adr/0003-webhooks-framework.md

@@ -0,0 +1,24 @@
+# ADR 0003: Webhooks Framework
+
+Date: 2025-10-15
+
+Status: Accepted
+
+## Context
+Services need a consistent way to publish domain events to external consumers via webhooks, verify inbound signatures, and handle retries with backoff. We already have an outbox pattern, a job queue, and a webhook delivery worker.
+
+## Decision
+- Event Schema: minimal fields {topic, payload, version, created_at}. Versioning included to evolve payloads.
+- Signing: HMAC-SHA256 over canonical JSON payload; header `X-Signature` carries hex digest. Future: include timestamp and v1 signature header variant.
+- Outbox → Job Queue: Producer writes events to Outbox; outbox tick enqueues delivery jobs; worker performs HTTP POST with signature.
+- Subscriptions: In-memory subscription store maps topic → {url, secret}. Persistence deferred.
+- Verification: Provide helper for verifying incoming webhook requests by recomputing the HMAC.
+- Retry: Already handled by JobQueue backoff; DLQ after max attempts.
+
+## Consequences
+- Clear boundary: producers don't call HTTP directly; they publish to Outbox.
+- Deterministic signing & verification across producer/consumer.
+- Extensibility: timestamped signed headers, secret rotation, persisted subscriptions are future extensions.
+
+## Testing
+- Unit tests for verification helper and end-to-end publish→outbox→queue→delivery using in-memory components and a fake HTTP client.

svc_infra/docs/adr/0004-tenancy-model.md

@@ -0,0 +1,42 @@
+# ADR-0004: Tenancy Model and Enforcement
+
+Date: 2025-10-15
+
+Status: Proposed
+
+## Context
+
+The framework needs a consistent, ergonomic multi-tenant story across modules (API scaffolding, SQL/Mongo persistence, auth/security, payments, jobs, webhooks). Existing patterns already reference `tenant_id` in many places (payments models and service, audit/session models, SQL/Mongo scaffolds). However, enforcement and app ergonomics were not unified.
+
+## Decision
+
+Adopt a default "soft-tenant" isolation model via a `tenant_id` column and centralized enforcement primitives:
+
+- Resolution: `resolve_tenant_id` and `require_tenant_id` FastAPI dependencies in `api.fastapi.tenancy.context`. Resolution order: override hook → identity (user/api_key) → `X-Tenant-Id` header → `request.state.tenant_id`.
+- Enforcement in SQL: `TenantSqlService(SqlService)` that scopes list/get/update/delete/search/count with a `where` clause and injects `tenant_id` on create when the model supports it. Repository methods accept optional `where` filters.
+- Router ergonomics: `make_tenant_crud_router_plus_sql` which requires `TenantId` and uses `TenantSqlService` under the hood. This keeps route code simple while enforcing scoping.
+- Extensibility: `set_tenant_resolver` hook to override resolution logic per app; `tenant_field` parameter to support custom column names. Future: schema-per-tenant or db-per-tenant via alternate repository/service implementations.
+
+## Alternatives considered
+
+1) Enforce tenancy at the ORM layer (SQLAlchemy events/session) – rejected for clarity and testability; we prefer explicit service/dep composition.
+2) Global middleware that rewrites queries – rejected due to SQLAlchemy complexity and opacity.
+3) Only rely on developers to remember filters – rejected due to footguns.
+
+## Consequences
+
+- Clear default behavior with escape hatches. Minimal changes for consumers using CRUD builders and SqlService.
+- Requires models to include an optional or required `tenant_id` column for scoping.
+- Non-SQL stores should add equivalent wrappers; Mongo scaffolds already include `tenant_id` fields and can mirror these patterns later.
+
+## Implementation Notes
+
+- New modules: `api.fastapi.tenancy.context`, `db.sql.tenant`. Repository updated to accept `where` filters.
+- CRUD router extended with `make_tenant_crud_router_plus_sql` to require `TenantId`.
+- Tests added: `tests/tenancy/*` for resolution and service scoping.
+
+## Open Items
+
+- Per-tenant quotas & rate limit overrides (tie into rate limit dependency/middleware via a resolver that returns per-tenant config).
+- Export tenant CLI (dump/import data for a specific tenant).
+- Docs: isolation guidance (column vs schema vs db), migration guidance.