svc-infra 0.1.506__py3-none-any.whl → 0.1.654__py3-none-any.whl

svc_infra/docs/adr/0006-ops-slos-and-metrics.md

@@ -0,0 +1,47 @@
+# ADR-0006: Ops SLOs, SLIs, and Metrics Naming
+
+Date: 2025-10-16
+
+## Status
+Accepted
+
+## Context
+We already expose Prometheus metrics via `svc_infra.obs.add.add_observability`, which mounts the `PrometheusMiddleware` and exports:
+- `http_server_requests_total{method,route,code}`
+- `http_server_request_duration_seconds_bucket{route,method}` + _sum/_count
+- `http_server_inflight_requests{route}`
+- `http_server_response_size_bytes_bucket` + _sum/_count (where available)
+- `http_server_exceptions_total{route,exception}` (where available)
+
+We also optionally expose SQLAlchemy pool metrics and instrument `requests`/`httpx`. Logging is configured via `svc_infra.app.logging.setup_logging`.
+
+## Decision
+1. Metric naming and labels
+   - Keep `http_server_*` naming aligned with Prometheus and OpenTelemetry conventions.
+   - Labels: `route` uses normalized FastAPI route pattern (e.g., `/users/{id}`); `method` is uppercase HTTP verb; `code` is the 3-digit status.
+   - Add DB pool metrics with `db_pool_*` prefix when bound (labels: `engine`/`pool_name`).
+2. SLIs
+   - Request Success Rate: 1 - error_ratio, where errors are 5xx by default; optionally include 429/499 as errors per service config.
+   - Request Latency: p50/p90/p99 on `http_server_request_duration_seconds` by `route` and overall.
+   - Availability (Probes): uptime of `/_ops/live` and `/_ops/ready` endpoints.
+3. SLOs
+   - Default SLOs per service class:
+     - Public API: 99.9% success, p99 < 500ms.
+     - Internal API/Jobs control plane: 99.5% success, p99 < 1000ms.
+   - Error Budget: monthly window; alert on burn rates of 2h (fast) and 24h (slow). Budgets computed from success SLI.
+4. Dashboards & Alerts
+   - Provide Grafana JSON dashboard templates referencing the above metrics and labels.
+   - Include alert rules for budget burn (fast/slow).
+
+## Consequences
+- Developers can rely on consistent metrics and labels for dashboards.
+- SLO targets are explicit and can be overridden per service.
+- Future work: Emit `http_server_exceptions_total` where missing; provide helper to register per-route classes (public/internal/admin) to pick default SLOs.
+
+## Alternatives Considered
+- OpenTelemetry SDK direct instrumentation was considered but deferred to keep dependency surface minimal; we keep the naming aligned for easy migration.
+
+## References
+- `src/svc_infra/obs/metrics/asgi.py`
+- `src/svc_infra/api/fastapi/ops/add.py`
+- Google SRE Workbook: SLOs and Error Budgets

svc_infra/docs/adr/0007-docs-and-sdks.md

@@ -0,0 +1,83 @@
+# ADR 0007: Docs & SDKs — Research and Design
+
+Status: Proposed
+
+Date: 2025-10-16
+
+## Context
+
+We want a production-ready documentation and SDK experience built on our existing FastAPI scaffolding.
+Current capabilities in the codebase:
+
+- Docs endpoints and export
+  - `add_docs(app, redoc_url, swagger_url, openapi_url, export_openapi_to)` mounts Swagger, ReDoc, and OpenAPI JSON; optional export on startup.
+  - `setup_service_api(...)` renders a landing page with per-version doc cards and local-only root docs.
+  - `add_prefixed_docs(...)` exposes scoped docs (e.g., for auth/payments) with per-scope OpenAPI, Swagger, ReDoc.
+- OpenAPI conventions and enrichment pipeline
+  - Mutators pipeline (`openapi/mutators.py`) with: conventions, normalized Problem schema, pagination params/components, header params, info mutator, and auth scheme installers.
+  - Conventions define `Problem` schema and normalize examples.
+- DX checks
+  - OpenAPI Problem+JSON lint in `dx/checks.py` and CLI to validate.
+- SDK stub
+  - `add_sdk_generation_stub(app, on_generate=...)` exposes a hook endpoint to trigger SDK generation (no hard deps).
+
+Gaps for a complete v1 experience:
+
+- Enriched OpenAPI with examples and tags is not yet standardized across routers.
+- No built-in SDK generator CLI; only a stub exists. No pinned toolchain or CI integration.
+- No Postman collection generator.
+- No dark-mode toggle/themes for Swagger/ReDoc (landing page supports light/dark).
+- No smoke tests for generated SDKs.
+
+## Decision
+
+We will standardize the Docs & SDKs approach around the following:
+
+1) OpenAPI enrichment
+- Use existing mutators pipeline and add small mutators to:
+  - Inject global tags and tag descriptions for major areas (auth, payments, webhooks, ops).
+  - Attach minimal `x-codeSamples` for common operations (curl/httpie).
+  - Ensure `Problem` schema and example responses are present across 4xx/5xx.
+  - Keep pagination and header parameter mutators enabled by default.
+
+2) Docs UI
+- Continue with Swagger UI and ReDoc via `add_docs` and `setup_service_api`.
+- Add an optional dark mode toggle for Swagger UI via custom CSS and a query param (design-only; implement later).
+- Keep local-only exposure of root docs; version-specific docs always exposed under their mount path.
+
+3) SDK generation pipeline (tools and layout)
+- TypeScript: `openapi-typescript` to generate types (no runtime client) to `clients/typescript/`.
+- Python: `openapi-python-client` to generate a client package to `clients/python/`.
+- Provide a new CLI group `svc-infra sdk` with subcommands:
+  - `svc-infra sdk ts --schema openapi.json --out clients/typescript --package @org/service`
+  - `svc-infra sdk py --schema openapi.json --out clients/python --package service_sdk`
+  - `svc-infra sdk postman --schema openapi.json --out clients/postman_collection.json` (via converter)
+- Pin generator versions in a minimal tool manifest (poetry extras and npm devDeps suggestions in docs) rather than hard deps in core library.
+- Add optional CI steps to generate SDKs on release tags; artifacts uploaded; publishing pipelines documented.
+
+4) Postman collection
+- Use the Postman converter (`openapi-to-postmanv2`) to produce `clients/postman_collection.json` from the exported OpenAPI.
+
+5) Testing & verification
+- Extend `dx` checks to include: schema export presence, generator dry-run, and minimal smoke tests:
+  - TS: typecheck the generated d.ts.
+  - Python: `pip install -e` and import a sample client in a quick script.
+- Keep these checks optional (opt-in via CI config) to avoid burdening minimal users.
+
+## Consequences
+
+- Pros: Clear, tool-agnostic pipeline; no heavy runtime dependencies; easy local and CI usage; versioned artifacts.
+- Cons: Adds extra tooling expectations (node and python generators) for teams that opt in.
+- Risk: Generator/tooling churn; mitigate by pinning versions and providing stubs/fallbacks.
+
+## Implementation Notes (planned)
+
+- Provide a small `svc_infra/cli/cmds/sdk` module with Typer commands that shell out to the generators if available, with helpful error messages if missing.
+- Document usage in `docs/docs-and-sdks.md` (to be added), including examples and troubleshooting.
+- Keep all new code behind DX/CLI; core library remains free of generator dependencies.
+
+## Out of Scope (v1)
+
+- Live “try it” consoles beyond Swagger UI.
+- Multi-language example snippets beyond curl/httpie.
+- Automatic publishing to npm/PyPI (documented manual workflows first).

svc_infra/docs/adr/0008-billing-primitives.md

@@ -0,0 +1,143 @@
+# ADR 0008: Billing Primitives (Usage, Quotas, Invoicing)
+
+## Status
+
+Proposed — Research and Design complete for v1 scope.
+
+## Context
+
+We need shared billing primitives to support both usage-based and subscription features across services. Goals:
+- Capture fine-grained usage events with idempotency and tenant isolation.
+- Aggregate usage into billable buckets (hour/day/month) with rollups.
+- Enforce entitlements/quotas at runtime (hard/soft limits).
+- Produce invoice data structures and events; enable later integration with external providers (Stripe, Paddle) without coupling core DX to any vendor.
+
+Non-goals for v1: taxes/VAT, complex proration rules, refunds/credits automation, dunning flows, provider-specific webhooks/end-to-end reconciliation.
+
+## Analysis: APF Payments vs Billing Primitives
+
+What APF Payments already covers (provider-facing):
+- Subscriptions lifecycle via provider adapters and HTTP router
+  - Endpoints: create/update/cancel/get/list under `/payments/subscriptions` (see `api/fastapi/apf_payments/router.py`).
+  - Local mirror rows (e.g., `PaySubscription`) are persisted for reference, but state is owned by the provider (Stripe/Aiydan).
+- Plans as Product + Price on the provider side
+  - APF Payments exposes products (`/payments/products`) and prices (`/payments/prices`). In Stripe semantics, a “plan” is represented by a product+price pair.
+  - There is no first-class internal Plan entity in APF Payments; plan semantics are encapsulated as provider product/price metadata.
+- Invoices, invoice line items, and previews
+  - Create/finalize/void/pay invoices; add/list invoice lines; preview invoices — all via provider adapters.
+- Usage records (metered billing) at the provider
+  - Create/list/get usage records mapped to provider subscription items or prices (`/payments/usage_records`).
+- Cross-cutting:
+  - Tenant resolution, pagination, idempotency, and Problem+JSON errors are integrated.
+
+What APF Payments does not cover (gaps filled by Billing Primitives):
+- An internal, provider-agnostic Plan and Entitlement registry (keys, windows, limits).
+- Quota enforcement at runtime (soft/hard limits) against internal entitlements.
+- Internal usage ingestion and aggregation store independent of provider APIs
+  - `UsageEvent` and `UsageAggregate` tables, with idempotent ingestion and windowed rollups.
+- Internal invoice modeling and generation from aggregates (not just provider invoices)
+  - `Invoice` and `InvoiceLine` entities produced from internal totals (jobs-based lifecycle).
+- A dedicated `/_billing` router for usage ingestion and aggregate reads (tenant-scoped, RBAC-protected).
+
+Where they intersect and can complement each other:
+- You can continue to use APF Payments for provider-side subscriptions/invoices and also use Billing Primitives to meter internal features and enforce quotas.
+- Optional bridging: a provider sync hook can map internally generated invoices/lines to provider invoices or payment intents when you want unified billing.
+- Usage: internal `UsageEvent` can be mirrored to provider usage-records if desired, but internal aggregation enables analytics and quota decisions without provider round-trips.
+
+Answering “Are plans and subscriptions covered in APF Payments?”
+- Subscriptions: Yes — fully supported via `/payments/subscriptions` endpoints with adapters (Stripe/Aiydan). APF also persists a local `PaySubscription` record for reference.
+- Plans: APF Payments does not expose a standalone internal Plan model. Instead, providers represent plans as Product + Price. Billing Primitives introduces an internal `Plan` and `PlanEntitlement` registry to support provider-agnostic limits and quotas.
+
+## Decisions
+
+1) Internal-first data model with optional provider adapters
+- Persist usage, aggregates, plans, subscriptions, invoices in our SQL layer.
+- Provide interfaces for provider adapters (Stripe later) to map internal invoices/lines and sync state when enabled.
+
+2) Usage ingestion API + idempotency
+- FastAPI router exposes POST /_billing/usage capturing events: {tenant_id, metric, amount, at, idempotency_key, metadata}.
+- Enforce request idempotency via existing middleware + usage-event unique index on (tenant_id, metric, idempotency_key).
+- Emit webhook event `billing.usage_recorded` (optional).
+
+3) Aggregation job (scheduler)
+- Background job reads new UsageEvent rows, aggregates into UsageAggregate by key (tenant, metric, period_start, period_granularity).
+- Granularities: hour, day, month (config). Maintains running totals; idempotent.
+- Emits `billing.usage_aggregated` webhook.
+
+4) Entitlements and quotas
+- Define Plan and PlanEntitlement models (feature flags, quotas per window).
+- Subscriptions bind tenant -> plan, effective_at/ended_at.
+- Runtime enforcement via dependency/decorator: `require_quota("metric", window="day", soft=True)` which raises/records when limit exceeded.
+
+5) Invoicing primitives
+- Invoice and InvoiceLine models created for each billing cycle (monthly default). Lines derived from aggregates and static prices.
+- Price model: unit amount, currency, metric reference (for metered), or fixed recurring.
+- Emit `billing.invoice_created` and `billing.invoice_finalized` webhooks; provider adapter can consume and sync out.
+
+6) Observability
+- Metrics: `billing_usage_ingest_total`, `billing_aggregate_duration_ms`, `billing_invoice_generated_total`.
+- Logs: aggregation windows processed, invoice cycles.
+
+7) Security & tenancy
+- All models include tenant_id; APIs require tenant context. RBAC: billing.read/billing.write for admin/operator roles.
+
+## Data Model (SQL)
+
+Tables (minimal v1):
+- usage_events(id, tenant_id, metric, amount, at_ts, idempotency_key, metadata_json, created_at)
+  - Unique (tenant_id, metric, idempotency_key)
+- usage_aggregates(id, tenant_id, metric, period_start, granularity, total, updated_at)
+  - Unique (tenant_id, metric, period_start, granularity)
+- plans(id, key, name, description, created_at)
+- plan_entitlements(id, plan_id, key, limit_per_window, window, created_at)
+- subscriptions(id, tenant_id, plan_id, effective_at, ended_at, created_at)
+- prices(id, key, currency, unit_amount, metric, recurring_interval, created_at)
+- invoices(id, tenant_id, period_start, period_end, status, total_amount, currency, created_at)
+- invoice_lines(id, invoice_id, price_id, metric, quantity, amount, created_at)
+
+All tables will be scaffolded with our SQL helpers and tenant mixin, with Alembic templates.
+
+## APIs
+
+- POST /_billing/usage: record usage events (body as above). Returns 202 with event id.
+- GET /_billing/usage: list usage by metric and window (aggregated).
+- GET /_billing/plans, GET /_billing/subscriptions, POST /_billing/subscriptions.
+- GET /_billing/invoices, GET /_billing/invoices/{id}.
+
+Routers mounted under a `/_billing` prefix and hidden behind auth + tenant guard. OpenAPI tags: Billing.
+
+## Jobs & Webhooks
+
+- Job: `aggregate_usage` runs on schedule; creates/updates UsageAggregate rows.
+- Job: `generate_invoices` runs monthly; emits invoice events and inserts Invoice/InvoiceLine rows.
+- Webhooks: `billing.usage_recorded`, `billing.usage_aggregated`, `billing.invoice_created`, `billing.invoice_finalized` (signed via existing module).
+
+## Implementation Plan (Phased)
+
+Phase 1 (MVP):
+- Models + migrations; CRUD for Plans/Subs/Prices; Usage ingestion + idempotency; Aggregator job (daily granularity); Basic invoice generator (monthly, fixed price + metered by day sum); Webhooks emitted; Tests for ingestion, aggregation, simple invoice.
+
+Phase 2:
+- Granularity options (hourly); soft/hard quota decorator; Read APIs; Observability metrics; Docs.
+
+Phase 3 (Provider adapter optional):
+- Stripe adapter skeleton: map internal invoices/lines -> Stripe, idempotent sync; basic webhook handler to update statuses.
+
+## Alternatives Considered
+
+- Provider-first approach (Stripe-only) rejected for v1 to keep core DX portable and support non-card use-cases.
+- Event-stream aggregation (Kafka) out-of-scope for framework baseline—can be integrated later.
+
+## Risks
+
+- Complexity creep around proration and taxes—explicitly out-of-scope for v1.
+- Performance on large tenants—mitigated by granular aggregation and indexes.
+
+## Testing
+
+- Unit tests for ingestion idempotency, aggregation correctness, invoice totals.
+- E2E-ish tests using in-memory queue + sqlite.
+
+## Documentation
+
+- `docs/billing.md`: usage API, quotas, invoice lifecycle, and Stripe adapter notes.

svc_infra/docs/adr/0009-acceptance-harness.md

@@ -0,0 +1,40 @@
+# ADR 0009: Acceptance Harness & Promotion Gate (A0)
+
+Date: 2025-10-17
+Status: Proposed
+Decision: Adopt a post-build acceptance harness that brings up an ephemeral stack (Docker Compose) and gates image promotion on acceptance results.
+
+## Context
+- We need a thin but strict pre-deploy acceptance layer that runs after building images, before promotion.
+- It should validate golden paths across domains and basic operational invariants.
+- It must be easy to run locally and in CI and support a backend matrix (in-memory vs Redis+Postgres).
+- Supply-chain checks (SBOM, image scan, provenance) should be part of the gate.
+
+## Decision
+- Introduce A0 Acceptance Harness:
+  - Compose stack (api + db + redis), Makefile helpers (accept/up/wait/seed/down).
+  - Seed CLI/script to create ADMIN/USER/TENANT fixtures and API key.
+  - Acceptance tests under `tests/acceptance` with `@pytest.mark.acceptance` and BASE_URL.
+  - CI job `build-and-accept` steps: build → compose up → seed → `pytest -m "acceptance or smoke"` → OpenAPI lint + API Doctor → teardown.
+  - Supply-chain: generate SBOM, image scan (Trivy/Grype) with severity threshold; upload SBOM.
+  - Provenance: sign/attest images via cosign/SLSA (best-effort for v1).
+  - Backend matrix: two jobs (in-memory vs Redis+Postgres).
+
+## Alternatives
+- Testcontainers-only approach (simpler per-test spin-up) — good DX but slower; we can adopt later for certain suites.
+- Kubernetes-in-Docker (kind) for near-prod parity — heavier; likely a v2 improvement.
+
+## Consequences
+- Slightly longer CI time due to matrix and scans.
+- Clearer promotion safety; early detection of config/env gaps.
+
+## Implementation Notes
+- Files to add:
+  - `docker-compose.test.yml`
+  - `Makefile` targets: `accept`, `compose_up`, `wait`, `seed`, `down`
+  - `tests/acceptance/` scaffolding: `conftest.py`, `_seed.py`, `_auth.py`, `_http.py`, first tests (headers/CORS)
+  - CI: `.github/workflows/ci.yml` job `build-and-accept`
+- Env contracts:
+  - `SQL_URL`, `REDIS_URL` for backend matrix; `APP_ENV=test-accept` for toggles.
+- Evidence:
+  - CI run URL, SBOM artifact link, scan report, acceptance summary.

svc_infra/docs/adr/0010-timeouts-and-resource-limits.md

@@ -0,0 +1,54 @@
+# ADR 0010: Timeouts & Resource Limits (A2)
+
+## Context
+Services need consistent, configurable timeouts to protect against slowloris/body drip attacks, expensive handlers, slow downstreams, and long-running DB statements. Today we lack unified settings and middleware behavior; some httpx usages hard-code timeouts. We also want consistent Problem+JSON semantics for timeout errors.
+
+## Decision
+Introduce environment-driven timeouts and wire them via FastAPI middlewares and helper factories:
+
+- Request body read timeout: aborts slow body streaming (e.g., slowloris) with 408 Request Timeout.
+- Overall request timeout: caps handler execution time and returns 504 Gateway Timeout.
+- httpx client defaults: central helpers that pick a sane default timeout from env.
+- DB statement timeout: future work (PG: SET LOCAL statement_timeout; SQLite/dev: asyncio.wait_for wrapper). Scoped in follow-ups.
+ - Graceful shutdown: track in-flight HTTP requests and wait up to grace period; provide worker runner with stop/grace.
+
+## Configuration
+Environment variables (with suggested defaults):
+
+- REQUEST_BODY_TIMEOUT_SECONDS: int, default 15 (prod), 30 (non-prod)
+- REQUEST_TIMEOUT_SECONDS: int, default 30 (prod), 15 (non-prod)
+- HTTP_CLIENT_TIMEOUT_SECONDS: float, default 10.0
+
+These are read at process start. Services can override per-env.
+
+## Behavior
+- Body read timeout → 408 application/problem+json with title "Request Timeout"; optional Retry-After not included by default.
+- Handler timeout → 504 application/problem+json with title "Gateway Timeout"; include request trace_id in body if present.
+- Errors use existing problem_response helper.
+
+## Placement
+- Middlewares under svc_infra.api.fastapi.middleware.timeout
+- Wiring in svc_infra.api.fastapi.setup._setup_middlewares (after RequestId, before error catching).
+- httpx helpers under svc_infra.http.client: new_httpx_client/new_async_httpx_client with env-driven defaults.
+ - Graceful shutdown under svc_infra.api.fastapi.middleware.graceful_shutdown and svc_infra.jobs.runner.WorkerRunner.
+
+## Alternatives Considered
+- Starlette TimeoutMiddleware: version support/behavior varies; custom middleware gives us consistent Problem+JSON and finer control across environments.
+
+## Consequences
+- Adds two middlewares to every app created via setup_service_api/easy_service_app.
+- Minor overhead per request; mitigated by simple asyncio.wait_for usage.
+
+## Follow-ups
+- PG statement timeout integration; SQLite/dev wrapper.
+- Jobs/webhook runner per-job timeout.
+ - Graceful shutdown drainage hooks for servers/workers.
+- Acceptance tests A2-04..A2-06 per PLANS.
+
+## Change log
+- 2025-10-21: Finalized httpx helpers design and placement; proceed to implementation.
+
+---
+ Status: Accepted
+Date: 2025-10-21
+Related: PLANS A2 — Timeouts & Resource Limits

svc_infra/docs/adr/0011-admin-scope-and-impersonation.md

@@ -0,0 +1,73 @@
+# 0011 — Admin scope, permissions, and impersonation
+
+## Context
+- The codebase already provides RBAC/permission helpers: `RequireRoles`, `RequirePermission`, ABAC via `RequireABAC`/`owns_resource`.
+- The central permission registry maps roles → permissions (`svc_infra.security.permissions.PERMISSION_REGISTRY`). Notably, the `admin` role includes: `user.read`, `user.write`, `billing.read`, `billing.write`, and `security.session.{list,revoke}`.
+- Acceptance tests demonstrate an “admin-only” route guarded by `RequirePermission("user.write")` and temporary role override to `admin`.
+- There is no dedicated admin API surface yet, and no impersonation flow; observability docs mention an optional route classifier that can label routes like `public|internal|admin`.
+
+## Goals
+- Define a consistent approach for admin-only surfaces and permission alignment.
+- Establish minimal permissions needed for admin operations, including impersonation.
+- Outline an impersonation flow with security and audit guardrails.
+- Prepare for an easy integration helper (`add_admin`) without implementing it yet.
+
+## Non-goals
+- Implement admin endpoints or impersonation logic in this ADR.
+- Replace existing permissions/guards — this ADR aligns and extends them.
+
+## Decisions
+
+1) Permissions alignment and additions
+- Keep permissions as the canonical guard unit; roles remain a mapping to permissions.
+- Extend the registry with a dedicated permission for impersonation:
+  - `admin.impersonate`
+- Keep existing entries (`security.session.{list,revoke}` etc.) as-is.
+- Recommended role → permission mapping updates:
+  - `admin`: add `admin.impersonate` (retains existing permissions).
+  - `auditor`: keep `audit.read` (already present) and may expand in the future.
+
+2) Admin router pattern
+- Provide an admin-only router pattern that layers role and permission checks consistently:
+  - Top-level: role gate via `RequireRoles("admin")` to reflect the “admin area”.
+  - Endpoint-level: permission gates via `RequirePermission(...)` for specific operations.
+- Rationale: roles communicate the coarse-grained area; fine-grained actions are enforced by permissions.
+- A future helper `admin_router()` can wrap `roles_router("admin")` (from `api.fastapi.dual.protected`) for ergonomic mounting.
+
+3) Impersonation flow (design)
+- Endpoints:
+  - `POST /admin/impersonate/start` — body: `{ user_id, reason }`; requires `admin.impersonate`.
+  - `POST /admin/impersonate/stop` — ends the session.
+- Mechanics:
+  - When starting, issue a short-lived, signed impersonation token (or set a dedicated cookie) that encodes: original admin principal id, target user id, issued-at, expires-at, and nonce.
+  - Downstream identity resolution should reflect the impersonated user for request handling, while preserving the original admin as the "actor" for auditing.
+  - Stopping invalidates the token/cookie (server-side revocation list or versioned secret), and subsequent requests fall back to the admin’s own identity.
+- Safety guardrails:
+  - Always require `admin.impersonate`.
+  - Enforce explicit `reason` and capture request fingerprint (ip hash, user-agent) with the event.
+  - Limit scope by tenant/org if applicable; optionally block actions explicitly marked non-impersonable.
+  - Set short TTL (e.g., 15 minutes) with sliding refresh disabled.
+
+4) Audit logging
+- Emit structured audit events for impersonation lifecycle:
+  - `admin.impersonation.started` with actor, target, reason, ip hash, user-agent, and expiry.
+  - `admin.impersonation.stopped` with actor, target, and termination reason (expired/manual).
+- Implementation options (future):
+  - Minimal: log via the existing logging setup (structured logger, e.g., `logger.bind(...).info("audit", ...)`).
+  - Preferred: emit to an audit outbox/table or webhook channel for retention and cross-system visibility.
+
+5) Observability and route classification
+- Encourage passing a `route_classifier` that labels admin routes as `admin` (e.g., for `/admin` base path) so metrics/SLO dashboards can split traffic into `public|internal|admin` classes.
+
+## Consequences
+- Clear, documented permissions and flow for admin-only features.
+- Minimal surface to add later: `admin_router()` and `add_admin(app, ...)` helper that mounts admin routes and wires impersonation endpoints + audit hooks.
+- Tests to plan when implementing:
+  - Role vs permission gating behavior on /admin routes.
+  - Impersonation start/stop lifecycle and audit emission.
+  - Ownership checks that permit admin bypass where intended (e.g., session revocation).
+
+## Follow-ups
+- Update the permission registry to include `admin.impersonate` (and map into `admin`).
+- Implement `admin_router()` and the `add_admin` helper following this ADR.
+- Add admin acceptance tests and documentation for guardrails and operational guidance.

svc_infra/docs/api.md

@@ -0,0 +1,59 @@
+# FastAPI helper guide
+
+The `svc_infra.api.fastapi` package provides a one-call bootstrap (`easy_service_app`) that wires request IDs, idempotency, rate limiting, and shared docs defaults for every mounted version. 【F:src/svc_infra/api/fastapi/ease.py†L176-L220】【F:src/svc_infra/api/fastapi/setup.py†L55-L129】
+
+```python
+from svc_infra.api.fastapi.ease import easy_service_app
+
+app = easy_service_app(
+    name="Payments",
+    release="1.0.0",
+    versions=[("v1", "myapp.api.v1", None)],
+    public_cors_origins=["https://app.example.com"],
+)
+```
+
+### Environment
+
+`easy_service_app` merges explicit flags with `EasyAppOptions.from_env()` so you can flip behavior without code changes:
+
+- `ENABLE_LOGGING`, `LOG_LEVEL`, `LOG_FORMAT` – control structured logging defaults. 【F:src/svc_infra/api/fastapi/ease.py†L67-L104】
+- `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS` – opt into Prometheus/OTEL middleware and tweak metrics exposure. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】
+- `CORS_ALLOW_ORIGINS` – add allow-listed origins when you don’t pass `public_cors_origins`. 【F:src/svc_infra/api/fastapi/setup.py†L47-L88】
+
+## Quickstart
+
+Use `easy_service_app` for a batteries-included FastAPI with sensible defaults:
+
+Inputs
+- name: service display name used in docs and logs
+- release: version string (shown in docs and headers)
+- versions: list of tuples of (prefix, import_path, router_name_or_None)
+- public_cors_origins: list of allowed origins for CORS (default deny if omitted)
+
+Defaults
+- Logging: enabled with JSON or plain format based on `LOG_FORMAT`; level from `LOG_LEVEL`
+- Observability: Prometheus metrics and OTEL when `ENABLE_OBS=true`; metrics path from `METRICS_PATH` (default `/metrics`)
+- Security headers: strict defaults; CORS disabled unless allowlist provided or `CORS_ALLOW_ORIGINS` set
+- Health: `/ping`, `/healthz`, `/readyz`, `/startupz` are wired
+
+Example
+```python
+from svc_infra.api.fastapi.ease import easy_service_app
+
+app = easy_service_app(
+    name="Example API",
+    release="1.0.0",
+    versions=[("v1", "example.api.v1", None)],
+    public_cors_origins=["https://app.example.com"],
+)
+```
+
+Override with environment
+```bash
+export ENABLE_LOGGING=true
+export LOG_LEVEL=INFO
+export ENABLE_OBS=true
+export METRICS_PATH=/metrics
+export CORS_ALLOW_ORIGINS=https://app.example.com,https://admin.example.com
+```

svc_infra/docs/auth.md

@@ -0,0 +1,11 @@
+# Auth settings
+
+`svc_infra.api.fastapi.auth` wraps FastAPI Users with sensible defaults for sessions, OAuth, MFA, and API keys via `add_auth_users`. Configuration comes from `AuthSettings`, which reads environment variables with the `AUTH_` prefix. 【F:src/svc_infra/api/fastapi/auth/add.py†L240-L321】【F:src/svc_infra/api/fastapi/auth/settings.py†L23-L91】
+
+### Key environment variables
+
+- `AUTH_JWT__SECRET`, `AUTH_JWT__OLD_SECRETS` – rotate signing keys without downtime. 【F:docs/security.md†L63-L70】
+- `AUTH_SMTP_HOST`, `AUTH_SMTP_USERNAME`, `AUTH_SMTP_PASSWORD`, `AUTH_SMTP_FROM` – enable SMTP delivery; required in production. 【F:src/svc_infra/api/fastapi/auth/settings.py†L44-L60】【F:src/svc_infra/api/fastapi/auth/sender.py†L33-L59】
+- `AUTH_SESSION_COOKIE_SECURE`, `AUTH_SESSION_COOKIE_NAME`, `AUTH_SESSION_COOKIE_SAMESITE` – shape session middleware. 【F:src/svc_infra/api/fastapi/auth/settings.py†L65-L88】【F:src/svc_infra/api/fastapi/auth/add.py†L279-L303】
+- `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_PASSWORD_BREACH_CHECK` – enforce password policy. 【F:docs/security.md†L24-L35】
+- `AUTH_MFA_DEFAULT_ENABLED_FOR_NEW_USERS`, `AUTH_MFA_ENFORCE_FOR_ALL_USERS` – adjust MFA enforcement. 【F:src/svc_infra/api/fastapi/auth/settings.py†L32-L40】