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

svc_infra/docs/getting-started.md

@@ -0,0 +1,63 @@
+# svc-infra
+
+[![PyPI](https://img.shields.io/pypi/v/svc-infra.svg)](https://pypi.org/project/svc-infra/)
+[![Docs](https://img.shields.io/badge/docs-reference-blue)](.)
+
+svc-infra packages the shared building blocks we use to ship production FastAPI services fast—HTTP APIs with secure auth, durable persistence, background execution, cache, observability, and webhook plumbing that all share the same batteries-included defaults.
+
+## Helper index
+
+| Area | What it covers | Guide |
+| --- | --- | --- |
+| Getting Started | Overview and entry points | [This page](getting-started.md) |
+| Environment | Feature switches and env vars | [Environment](environment.md) |
+| API | FastAPI bootstrap, middleware, docs wiring | [API guide](api.md) |
+| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth](auth.md) |
+| Security | Password policy, lockout, signed cookies, headers | [Security](security.md) |
+| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database](database.md) |
+| Tenancy | Multi-tenant boundaries and helpers | [Tenancy](tenancy.md) |
+| Idempotency | Idempotent endpoints and middleware | [Idempotency](idempotency.md) |
+| Rate Limiting | Middleware, dependency limiter, headers | [Rate limiting](rate-limiting.md) |
+| Cache | cashews decorators, namespace management, TTL helpers | [Cache](cache.md) |
+| Jobs | JobQueue, scheduler, CLI worker | [Jobs](jobs.md) |
+| Observability | Prometheus, Grafana, OpenTelemetry | [Observability](observability.md) |
+| Ops | Probes, breakers, SLOs & dashboards | [Ops](ops.md) |
+| Webhooks | Subscription store, signing, retry worker | [Webhooks](webhooks.md) |
+| CLI | Command groups for sql/mongo/obs/docs/dx/sdk/jobs | [CLI](cli.md) |
+| Docs & SDKs | Publishing docs, generating SDKs | [Docs & SDKs](docs-and-sdks.md) |
+| Acceptance | Acceptance harness and flows | [Acceptance](acceptance.md), [Matrix](acceptance-matrix.md) |
+| Contributing | Dev setup and quality gates | [Contributing](contributing.md) |
+| Repo Review | Checklist for releasing/PRs | [Repo review](repo-review.md) |
+| Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](data-lifecycle.md) |
+
+## Minimal FastAPI bootstrap
+
+```python
+from fastapi import Depends
+from svc_infra.api.fastapi.ease import easy_service_app
+from svc_infra.api.fastapi.db.sql.add import add_sql_db
+from svc_infra.cache import init_cache
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.webhooks.fastapi import require_signature
+
+app = easy_service_app(name="Billing", release="1.2.3")
+add_sql_db(app)              # reads SQL_URL / DB_* envs
+init_cache()                 # honors CACHE_PREFIX / CACHE_VERSION
+queue, scheduler = easy_jobs()  # switches via JOBS_DRIVER / REDIS_URL
+
+@app.post("/webhooks/billing")
+async def handle_webhook(payload = Depends(require_signature(lambda: ["current", "next"]))):
+    queue.enqueue("process-billing-webhook", payload)
+    return {"status": "queued"}
+```
+
+## Environment switches
+
+- **API** – toggle logging/observability and docs exposure with `ENABLE_LOGGING`, `LOG_LEVEL`, `LOG_FORMAT`, `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and `CORS_ALLOW_ORIGINS`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/api/fastapi/setup.py†L47-L88】
+- **Auth** – configure JWT secrets, SMTP, cookies, and policy using the `AUTH_…` settings family (e.g., `AUTH_JWT__SECRET`, `AUTH_SMTP_HOST`, `AUTH_SESSION_COOKIE_SECURE`). 【F:src/svc_infra/api/fastapi/auth/settings.py†L23-L91】
+- **Database** – set connection URLs or components via `SQL_URL`/`SQL_URL_FILE`, `DB_DIALECT`, `DB_HOST`, `DB_USER`, `DB_PASSWORD`, plus Mongo knobs like `MONGO_URL`, `MONGO_DB`, and `MONGO_URL_FILE`. 【F:src/svc_infra/api/fastapi/db/sql/add.py†L55-L114】【F:src/svc_infra/db/sql/utils.py†L85-L206】【F:src/svc_infra/db/nosql/mongo/settings.py†L9-L13】【F:src/svc_infra/db/nosql/utils.py†L56-L113】
+- **Jobs** – choose the queue backend with `JOBS_DRIVER` and provide Redis via `REDIS_URL`; interval schedules can be declared with `JOBS_SCHEDULE_JSON`. 【F:src/svc_infra/jobs/easy.py†L11-L27】【F:src/svc_infra/docs/jobs.md†L11-L48】
+- **Cache** – namespace keys and lifetimes through `CACHE_PREFIX`, `CACHE_VERSION`, and TTL overrides `CACHE_TTL_DEFAULT`, `CACHE_TTL_SHORT`, `CACHE_TTL_LONG`. 【F:src/svc_infra/cache/README.md†L20-L173】【F:src/svc_infra/cache/ttl.py†L26-L55】
+- **Observability** – turn metrics on/off or adjust scrape paths with `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and Prometheus/Grafana flags like `SVC_INFRA_DISABLE_PROMETHEUS`, `SVC_INFRA_RATE_WINDOW`, `SVC_INFRA_DASHBOARD_REFRESH`, `SVC_INFRA_DASHBOARD_RANGE`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/obs/metrics/asgi.py†L49-L206】【F:src/svc_infra/obs/cloud_dash.py†L85-L108】
+- **Webhooks** – reuse the jobs envs (`JOBS_DRIVER`, `REDIS_URL`) for the delivery worker and queue configuration. 【F:src/svc_infra/docs/webhooks.md†L32-L53】
+- **Security** – enforce password policy, MFA, and rotation with auth prefixes such as `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_JWT__SECRET`, and `AUTH_JWT__OLD_SECRETS`. 【F:src/svc_infra/docs/security.md†L24-L70】

svc_infra/docs/idempotency.md

@@ -0,0 +1,111 @@
+# Idempotency & Concurrency Controls
+
+This guide explains how idempotency works in svc-infra and how to enable it for safe retries.
+
+## What it does
+- Prevents duplicate processing of mutating requests (POST/PATCH/DELETE).
+- Replays the previously successful response when the same `Idempotency-Key` is used.
+- Detects conflicts when the same key is reused with a different request body, returning 409.
+
+## Middleware usage
+```python
+from svc_infra.api.fastapi.middleware.idempotency import IdempotencyMiddleware
+
+app.add_middleware(IdempotencyMiddleware)  # default: in-memory store, 24h TTL
+```
+- Header name: `Idempotency-Key` (configurable via `header_name`)
+- TTL: defaults to 24 hours (`ttl_seconds`)
+
+### Redis store (recommended for multi-instance)
+```python
+import redis
+from svc_infra.api.fastapi.middleware.idempotency import IdempotencyMiddleware
+from svc_infra.api.fastapi.middleware.idempotency_store import RedisIdempotencyStore
+
+r = redis.Redis.from_url("redis://localhost:6379/0")
+store = RedisIdempotencyStore(r, prefix="idmp")
+app.add_middleware(IdempotencyMiddleware, store=store, ttl_seconds=24*3600)
+```
+
+## Per-route enforcement
+If an endpoint must require idempotency always, add the dependency:
+```python
+from fastapi import Depends
+from svc_infra.api.fastapi.middleware.idempotency import require_idempotency_key
+
+@app.post("/payments/intents", dependencies=[Depends(require_idempotency_key)])
+async def create_intent(...):
+    ...
+```
+
+## Semantics
+- First request with a key:
+  - The middleware claims the key and records a hash of the request body.
+  - On success (2xx), the response envelope is cached until TTL.
+- Replay with same key and same body:
+  - Returns the cached response with the original status and headers.
+- Replay with same key but different body:
+  - Returns 409 Conflict (don’t reuse keys for different logical operations).
+
+## Testing
+- Marker: `-m concurrency` selects concurrency tests in this repo.
+- Scenarios covered:
+  - Successful first request and replay
+  - Conflict on mismatched payload reusing the same key
+
+## Notes and pitfalls
+- Use a unique key per logical operation (e.g., `order-{id}-capture-1`).
+- TTL should exceed your max retry horizon.
+- For stronger guarantees in Redis, consider a Lua script to make the claim + response update atomic (future improvement).
+- If you also use optimistic locking, surface 409 when `If-Match` version mismatches during updates.
+
+---
+
+## Optimistic Locking
+
+Use the `If-Match` header and a version field on your models.
+
+```python
+from svc_infra.api.fastapi.middleware.optimistic_lock import require_if_match, check_version_or_409
+
+@app.patch("/resource/{rid}")
+async def update_resource(rid: str, v: str = Depends(require_if_match)):
+    current = await repo.get(...)
+    check_version_or_409(lambda: current.version, v)
+    current.version += 1
+    await repo.save(current)
+    return {...}
+```
+
+Pitfalls:
+- Always bump the version on successful updates.
+- Return 428 when `If-Match` is missing on mutating routes that require optimistic locking.
+- Consider ETag headers for GETs to complement conditional requests.
+
+---
+
+## Outbox / Inbox
+
+Outbox: record events/changes that must be delivered to external systems; a relay fetches and delivers reliably.
+
+```python
+from svc_infra.db.outbox import InMemoryOutboxStore
+
+ob = InMemoryOutboxStore()
+msg = ob.enqueue("orders.created", {"order_id": 123})
+nxt = ob.fetch_next(topics=["orders.created"])  # process
+ob.mark_processed(nxt.id)
+```
+
+Inbox: deduplicate external deliveries (e.g., webhook replays) with TTL.
+
+```python
+from svc_infra.db.inbox import InMemoryInboxStore
+
+ib = InMemoryInboxStore()
+if not ib.mark_if_new("provider-evt-abc", ttl_seconds=86400):
+    return 200  # duplicate
+```
+
+Notes:
+- In-memory stores are for tests/local dev; implement SQL/Redis for production with row locks and `SKIP LOCKED` (or Lua) as needed.

svc_infra/docs/jobs.md

@@ -0,0 +1,67 @@
+# Background Jobs & Scheduling
+
+This module provides a lightweight JobQueue abstraction with a Redis backend for production and in-memory implementations for local/tests. A simple interval scheduler and CLI runner are included.
+
+> ℹ️ Job-related environment variables are documented in [Environment Reference](environment.md).
+
+## Quickstart
+
+- Initialize in app code:
+
+```python
+from svc_infra.jobs.easy import easy_jobs
+queue, scheduler = easy_jobs()  # uses JOBS_DRIVER=memory|redis
+```
+
+- Enqueue a job:
+
+```python
+job = queue.enqueue("send_email", {"to": "user@example.com"})
+```
+
+- Process one job (async):
+
+```python
+from svc_infra.jobs.worker import process_one
+await process_one(queue, handler)
+```
+
+- Run the CLI runner:
+
+```bash
+svc-infra jobs run
+```
+
+## Redis Backend
+
+Set environment variables:
+- JOBS_DRIVER=redis
+- REDIS_URL=redis://localhost:6379/0
+
+Features:
+- Visibility timeout during processing
+- Exponential backoff on failures (base backoff_seconds * attempts)
+- DLQ after max_attempts
+
+## Scheduler
+
+An interval-based scheduler runs async callables. You can define tasks via environment JSON:
+
+- JOBS_SCHEDULE_JSON:
+
+```json
+[
+  {"name": "ping", "interval_seconds": 60, "target": "myapp.tasks:ping"}
+]
+```
+
+The `target` must be an import path of the form `module:function`. Sync functions are wrapped.
+
+## Testing
+
+- In-memory queue and scheduler enable fast, deterministic tests.
+- Redis tests use `fakeredis` and cover enqueue/reserve/ack/fail and DLQ path.
+
+## Next
+
+- Add metrics, Redis Lua for atomic multi-ops, SQL-backed queue, distributed scheduler.

svc_infra/docs/observability.md

@@ -0,0 +1,16 @@
+# Observability guide
+
+`svc_infra.obs` adds Prometheus metrics, OpenTelemetry instrumentation, and a CLI to spin up Grafana dashboards.
+
+```python
+from svc_infra.api.fastapi.ease import easy_service_app
+
+app = easy_service_app(name="Billing", release="1.2.3")  # ENABLE_OBS toggles middleware
+```
+
+### Environment
+
+- `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS` – FastAPI bootstrap toggles for metrics exposure. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】
+- `SVC_INFRA_DISABLE_PROMETHEUS` – disable the ASGI middleware entirely (used by tests/sidecars). 【F:src/svc_infra/obs/metrics/asgi.py†L49-L206】
+- `SVC_INFRA_RATE_WINDOW`, `SVC_INFRA_DASHBOARD_REFRESH`, `SVC_INFRA_DASHBOARD_RANGE` – tune the Grafana dashboards generated by the CLI. 【F:src/svc_infra/obs/cloud_dash.py†L85-L108】
+- Grafana Cloud support looks for `GRAFANA_CLOUD_URL`, `GRAFANA_CLOUD_TOKEN`, `GRAFANA_CLOUD_PROM_URL`, `GRAFANA_CLOUD_PROM_USERNAME`, `GRAFANA_CLOUD_RW_TOKEN`. 【F:src/svc_infra/obs/README.md†L37-L119】

svc_infra/docs/ops.md

@@ -0,0 +1,37 @@
+# SLOs & Ops
+
+This guide explains how to use svc-infra’s probes, circuit breaker, and metrics for SLOs.
+
+## Probes
+
+- `add_probes(app, prefix="/_ops")` exposes:
+  - `GET /_ops/live` — liveness
+  - `GET /_ops/ready` — readiness
+  - `GET /_ops/startup` — startup
+
+## Circuit breaker (placeholder)
+
+- `circuit_breaker_dependency()` returns a dependency that returns 503 when `CIRCUIT_OPEN` is truthy.
+- Use it per-route: `@app.get("/x", dependencies=[Depends(circuit_breaker_dependency())])`.
+
+## Metrics and route classification
+
+- `add_observability(app, ...)` enables Prometheus metrics and optional DB pool metrics.
+- You can pass an optional `route_classifier(base_path, method) -> class` callable. When provided, the metrics middleware encodes the resolved route label as `"{base}|{class}"`. Dashboards can split this label to filter public/internal/admin routes.
+
+## Dashboards
+
+- A minimal Grafana dashboard JSON is provided at `src/svc_infra/obs/grafana/dashboards/http-overview.json` (import into Grafana).
+- It shows:
+  - Success rate over 5 minutes
+  - p99 latency
+  - Top routes by 5xx rate
+
+## Defaults & environment
+
+- Prometheus middleware is enabled unless `SVC_INFRA_DISABLE_PROMETHEUS=1`.
+- Observability settings: `METRICS_ENABLED`, `METRICS_PATH`, and optional histogram buckets.
+
+## See also
+
+- Timeouts & Resource Limits: `./timeouts-and-resource-limits.md` — request/body/handler timeouts, outbound client timeouts, DB statement timeouts, jobs/webhooks, and graceful shutdown.

svc_infra/docs/rate-limiting.md

@@ -0,0 +1,125 @@
+# Rate Limiting & Abuse Protection
+
+This guide shows how to enable and tune the built-in rate limiter and request-size guard, and how to hook simple metrics for abuse detection.
+
+## Features
+
+- Global middleware-based rate limiting with standard headers
+- Per-route dependency for fine-grained limits
+- 429 responses include `Retry-After`
+- Pluggable store interface (in-memory provided; Redis store available)
+- Request size limit middleware returning 413
+- Metrics hooks for rate-limiting events and suspect payloads
+
+## Global middleware
+
+```python
+from svc_infra.api.fastapi.middleware.ratelimit import SimpleRateLimitMiddleware
+
+app.add_middleware(
+    SimpleRateLimitMiddleware,
+    limit=120,   # requests
+    window=60,   # seconds
+    key_fn=lambda r: r.headers.get("X-API-Key") or r.client.host,
+)
+```
+
+Responses include headers:
+- `X-RateLimit-Limit`
+- `X-RateLimit-Remaining`
+- `X-RateLimit-Reset` (epoch seconds)
+
+When exceeded, responses are 429 with `Retry-After` and the same headers.
+
+Advanced options:
+- `scope_by_tenant=True` to automatically include tenant id in the key if tenancy is configured.
+- `limit_resolver=request -> int | None` to override the limit dynamically per request (e.g., per-plan quotas).
+
+## Per-route dependency
+
+```python
+from fastapi import Depends
+from svc_infra.api.fastapi.dependencies.ratelimit import rate_limiter
+
+limiter = rate_limiter(limit=10, window=60, key_fn=lambda r: r.client.host)
+
+@app.get("/resource", dependencies=[Depends(limiter)])
+def get_resource():
+    return {"ok": True}
+```
+
+The dependency supports the same options as the middleware: `scope_by_tenant`, `limit_resolver`, and a custom `store`.
+
+## Store interface
+
+The limiter uses a store abstraction so you can inject Redis or other backends.
+
+- Default: `InMemoryRateLimitStore` (best-effort, single-process)
+- Interface: `RateLimitStore` with `incr(key, window) -> (count, limit, resetEpoch)`
+
+### Redis store
+
+Use `RedisRateLimitStore` for multi-instance deployments. It implements a fixed-window counter
+with atomic increments and sets expiry to the end of the window.
+
+```python
+import redis
+from svc_infra.api.fastapi.middleware.ratelimit_store import RedisRateLimitStore
+from svc_infra.api.fastapi.middleware.ratelimit import SimpleRateLimitMiddleware
+
+r = redis.Redis.from_url("redis://localhost:6379/0")
+store = RedisRateLimitStore(r, limit=120, prefix="rl")
+
+app.add_middleware(SimpleRateLimitMiddleware, limit=120, window=60, store=store)
+```
+
+Notes:
+- Fixed-window counters are simple and usually sufficient. For smoother limits, consider
+  sliding window or token bucket in a future iteration.
+- Use a namespace/prefix per environment/tenant if needed.
+
+## Request size guard
+
+```python
+from svc_infra.api.fastapi.middleware.request_size_limit import RequestSizeLimitMiddleware
+
+app.add_middleware(RequestSizeLimitMiddleware, max_bytes=1_000_000)
+```
+
+- Returns 413 with a Problem+JSON-like structure when `Content-Length` exceeds `max_bytes`.
+
+## Metrics hooks
+
+Hooks live in `svc_infra.obs.metrics` and are no-ops by default. Assign them to log or emit metrics.
+
+```python
+import logging
+import svc_infra.obs.metrics as metrics
+
+logger = logging.getLogger(__name__)
+
+metrics.on_rate_limit_exceeded = lambda key, limit, retry: logger.warning(
+    "rate_limited", extra={"key": key, "limit": limit, "retry_after": retry}
+)
+
+metrics.on_suspect_payload = lambda path, size: logger.warning(
+    "suspect_payload", extra={"path": path, "size": size}
+)
+```
+
+## Tuning tips
+
+- Prefer API key or user ID for `key_fn`; fall back to IP if unauthenticated.
+- Keep windows small (e.g., 60s); layer multiple limits when needed.
+- For distributed deployments, use `RedisRateLimitStore` for atomic increments.
+- Consider separate limits for read vs write routes.
+- Combine with request size limits and auth lockout for layered defense.
+
+## Related
+
+- Timeouts & Resource Limits: `./timeouts-and-resource-limits.md` — complements rate limits by bounding slow uploads, long handlers, and downstream timeouts.
+
+## Testing
+
+- Use `-m ratelimit` to select rate-limiting tests.
+- `-m security` also includes these in this repo by default.

svc_infra/docs/repo-review.md

@@ -0,0 +1,48 @@
+# svc-infra Integration Review
+
+## Executive Summary
+- `setup_service_api` remains the high-level entry point for API construction. It auto-wires common middleware (request IDs, error handling, idempotency, rate limiting) and OpenAPI customisation so downstream services only supply router packages and metadata. 【F:src/svc_infra/api/fastapi/setup.py†L1-L187】
+- Auth, SQL, jobs, cache, and observability still expose single-call helpers (`add_auth_users`, `add_sql_db`/`setup_sql`, `easy_jobs`, `init_cache`, `add_observability`) that hide wiring details while keeping flags and dependency overrides for advanced scenarios. 【F:src/svc_infra/api/fastapi/auth/add.py†L27-L329】【F:src/svc_infra/api/fastapi/db/sql/add.py†L1-L118】【F:src/svc_infra/jobs/easy.py†L1-L28】【F:src/svc_infra/cache/__init__.py†L1-L29】【F:src/svc_infra/obs/add.py†L1-L68】
+- Security primitives (lockout, session rotation, RBAC/ABAC, audit chain) are packaged as small composable functions and documented patterns, making them easy to reuse outside FastAPI while still integrating with the default auth routers. 【F:src/svc_infra/security/lockout.py†L1-L96】【F:src/svc_infra/security/session.py†L1-L98】【F:src/svc_infra/security/permissions.py†L1-L148】【F:src/svc_infra/security/audit_service.py†L1-L73】【F:docs/security.md†L1-L96】
+- Webhook utilities provide signature verification, a subscription service, and a default router, but they do not yet follow the same add-helper pattern (there is no `add_webhooks(app, ...)` or env-driven persistence wiring). This is the primary deviation from the established DX story. 【F:src/svc_infra/webhooks/fastapi.py†L1-L37】【F:src/svc_infra/webhooks/service.py†L1-L45】【F:src/svc_infra/webhooks/router.py†L1-L55】【F:docs/webhooks.md†L1-L59】
+
+## Detailed Findings
+
+### API bootstrap and middleware
+- `setup_service_api` builds a parent app and any versioned child apps, runs the OpenAPI mutation pipeline, registers default routers, and attaches middleware without extra code in downstream projects. 【F:src/svc_infra/api/fastapi/setup.py†L1-L187】
+- Scoped docs helpers automatically group endpoints when `add_auth_users` or versioned routers are mounted, so projects get organised API docs with minimal configuration. 【F:src/svc_infra/api/fastapi/auth/add.py†L269-L329】
+- Idempotency and optimistic locking remain opt-in via middleware or dependencies with clear docs; defaults are safe for local use and can be swapped for Redis-backed stores. 【F:docs/idempotency.md†L1-L110】
+
+### Authentication and security
+- `add_auth_users` continues to be the main integration surface. It mounts routers based on flags, configures session middleware from env, and exposes API-key plus OAuth support as toggles. Projects can override policy objects or provider models if needed, preserving flexibility. 【F:src/svc_infra/api/fastapi/auth/add.py†L27-L329】
+- Runtime security helpers (principal resolution, `RequireRoles`, `RequireScopes`, `RequirePermission`, ABAC predicates) make it straightforward to guard routes consistently with the dual routers that enforce doc security defaults. 【F:src/svc_infra/api/fastapi/auth/security.py†L1-L146】【F:src/svc_infra/api/fastapi/dual/protected.py†L1-L74】【F:src/svc_infra/security/permissions.py†L1-L148】
+- Low-level primitives (lockout, refresh token rotation, audit chain) remain framework agnostic so other stacks can reuse them. Documentation in `docs/security.md` is aligned with the code and offers wiring recipes. 【F:src/svc_infra/security/lockout.py†L1-L96】【F:src/svc_infra/security/session.py†L1-L98】【F:src/svc_infra/security/audit_service.py†L1-L73】【F:docs/security.md†L1-L96】
+- Recommendation: add a security bundle similar to `setup_sql` that can register `SecurityHeadersMiddleware` and strict CORS when FastAPI is not created via `setup_service_api`. 【F:src/svc_infra/security/headers.py†L1-L35】
+
+### Data and jobs
+- SQL helpers offer both granular (`add_sql_db`, `add_sql_resources`) and bundled (`setup_sql`) flows. They guard against duplicate setup and generate CRUD schemas when not provided, keeping the quick-start feel while allowing custom services. 【F:src/svc_infra/api/fastapi/db/sql/add.py†L1-L118】
+- Jobs expose `easy_jobs()` that switches between memory and Redis based on env, matching the pick-style ergonomics used in logging. Documentation explains scheduler tasks and the CLI runner. 【F:src/svc_infra/jobs/easy.py†L1-L28】【F:docs/jobs.md†L1-L65】
+- Cache decorators export both `cache_read` and the friendlier aliases (`cached`, `mutates`) so consumers can adopt them incrementally. 【F:src/svc_infra/cache/__init__.py†L1-L29】
+
+### Observability
+- `add_observability` lazily imports instrumentation, respects env flags, and returns a shutdown no-op to keep signature compatibility. It tolerates missing dependencies to avoid burdening projects that do not enable metrics. 【F:src/svc_infra/obs/add.py†L1-L68】
+- Grafana and Prometheus templates are packaged separately, but the code path aligns with the simple toggle approach used elsewhere.
+
+### Webhooks and outbox
+- Signature utilities (`require_signature`, `verify_any`) and service abstractions (`WebhookService`, `InMemoryWebhookSubscriptions`) follow the composable style, and docs describe usage alongside the shared job and outbox infrastructure. 【F:src/svc_infra/webhooks/fastapi.py†L1-L37】【F:src/svc_infra/webhooks/service.py†L1-L45】【F:docs/webhooks.md†L1-L59】
+- Gaps relative to the rest of the repo:
+  - Router dependencies always create new in-memory stores, so deployments must override dependencies manually. Providing an `add_webhooks(app, store=..., subs=...)` helper that honours env (for example `REDIS_URL`) would mirror `add_sql_db` and `add_observability`. 【F:src/svc_infra/webhooks/router.py†L1-L55】
+  - No convenience function registers the router or scheduler tick automatically; consumers must read docs to wire `make_outbox_tick` and queue processors. A top-level helper such as `setup_webhooks(app, outbox=None, inbox=None)` could bundle router inclusion and scheduler guidance.
+
+### Documentation and DX consistency
+- Feature guides (security, jobs, webhooks, idempotency) contain quickstart snippets that mirror the API surface, reinforcing the ease-of-setup story. 【F:docs/security.md†L1-L96】【F:docs/jobs.md†L1-L65】【F:docs/webhooks.md†L1-L59】【F:docs/idempotency.md†L1-L110】
+- README remains empty; adding a high-level index pointing to these guides would help teams discover the single-call helpers faster. 【F:README.md†L1-L4】
+- Consider adding a matrix listing which environment variables drive each helper (`SQL_URL`, `REDIS_URL`, `METRICS_PATH`, `AUTH_*`) to highlight parity across modules.
+
+## Actionable Suggestions
+1. **Webhook setup helper** — provide `add_webhooks` or `setup_webhooks` to mount the router, accept dependency overrides, and optionally wire scheduler tasks. Default to env-driven outbox or inbox selection to match other modules. 【F:src/svc_infra/webhooks/router.py†L1-L55】
+2. **Security bundle** — offer a helper that installs `SecurityHeadersMiddleware`, strict CORS, and optional signed-cookie settings for apps that bypass `setup_service_api`. This keeps manual FastAPI apps aligned with the default hardening posture. 【F:src/svc_infra/security/headers.py†L1-L35】
+3. **Documentation index** — populate `README.md` with links to the feature guides and highlight key add-style helpers so new projects immediately see the plug-and-play building blocks. 【F:README.md†L1-L4】
+4. **Environment reference** — add a doc or table enumerating env vars consumed by helpers (SQL_URL, REDIS_URL, METRICS_PATH, AUTH_*), emphasising how swapping values maintains flexibility across deployments.
+
+Overall, aside from the webhook ergonomics gap and missing README guidance, the codebase maintains the quick-start plus override pattern highlighted in your sample usage while exposing low-level hooks for teams that need deeper control.

svc_infra/docs/security.md

@@ -0,0 +1,176 @@
+# Security: Configuration & Examples
+
+This guide covers the security primitives built into svc-infra and how to wire them:
+
+> ℹ️ Environment variables for the auth/security helpers are catalogued in [Environment Reference](environment.md).
+
+- Password policy and breach checking
+- Account lockout (exponential backoff)
+- Sessions and refresh tokens (rotation + revocation)
+- JWT key rotation
+- Signed cookies
+- CORS and security headers
+- RBAC and ABAC
+- MFA policy hooks
+
+Module map (examples reference these):
+- `svc_infra.security.lockout` (LockoutConfig, compute_lockout, record_attempt, get_lockout_status)
+- `svc_infra.security.signed_cookies` (sign_cookie, verify_cookie)
+- `svc_infra.security.audit` and `security.audit_service` (hash-chain audit logs)
+- `svc_infra.api.fastapi.auth.gaurd` (password login with lockout checks)
+- `svc_infra.api.fastapi.auth.routers.*` (sessions, oauth routes, etc.)
+- `svc_infra.api.fastapi.auth.settings.get_auth_settings` (cookie + token settings)
+- `svc_infra.api.fastapi.middleware.security_headers` and CORS setup (strict defaults)
+
+## Password policy and breach checking
+- Enforced by validators with a configurable policy.
+- Breach checking uses the HIBP k-Anonymity range API; can be toggled via settings.
+
+Example toggles (pseudo-config):
+- `AUTH_PASSWORD_MIN_LENGTH=12`
+- `AUTH_PASSWORD_REQUIRE_SYMBOL=True`
+- `AUTH_PASSWORD_BREACH_CHECK=True`
+
+## Account lockout
+- Exponential backoff with a max cooldown cap to deter credential stuffing.
+- Attempts tracked by user_id and/or IP hash.
+- Login endpoint blocks with 429 + `Retry-After` during cooldown.
+
+Key API (from `svc_infra.security.lockout`):
+- `LockoutConfig(threshold=5, window_minutes=15, base_cooldown_seconds=30, max_cooldown_seconds=3600)`
+- `compute_lockout(fail_count, cfg)` → `LockoutStatus(locked, next_allowed_at, failure_count)`
+- `record_attempt(session, user_id, ip_hash, success)`
+- `get_lockout_status(session, user_id, ip_hash, cfg)`
+
+Login integration (simplified):
+```python
+from svc_infra.security.lockout import get_lockout_status, record_attempt
+
+# Compute ip_hash from request.client.host
+status = await get_lockout_status(session, user_id=None, ip_hash=ip_hash)
+if status.locked:
+		raise HTTPException(429, headers={"Retry-After": ..})
+
+user = await user_manager.user_db.get_by_email(email)
+if not user:
+		await record_attempt(session, user_id=None, ip_hash=ip_hash, success=False)
+		raise HTTPException(400, "LOGIN_BAD_CREDENTIALS")
+```
+
+## Sessions and refresh tokens
+- Sessions are enumerable and revocable via the sessions router.
+- Refresh tokens are rotated; old tokens are invalidated via a revocation list.
+
+Operational notes:
+- Persist sessions/tokens in a durable DB.
+- Favor short access token TTLs if refresh flow is robust.
+
+## JWT key rotation
+- Primary secret plus `old_secrets` allow seamless rotation.
+- Set environment variables:
+	- `AUTH_JWT__SECRET="..."`
+	- `AUTH_JWT__OLD_SECRETS="old1,old2"`
+
+## Signed cookies
+Module: `svc_infra.security.signed_cookies`
+
+```python
+from svc_infra.security.signed_cookies import sign_cookie, verify_cookie
+
+sig = sign_cookie({"sub": "user-123"}, secret="k1", exp_seconds=3600)
+payload = verify_cookie(sig, secret="k1", old_secrets=["k0"])  # returns dict
+```
+
+## CORS and security headers
+- Strict CORS defaults (deny by default). Provide allowlist entries.
+- Security headers middleware sets common protections (X-Frame-Options, X-Content-Type-Options, etc.).
+
+Use `svc_infra.security.add.add_security` to install the default middlewares on any
+FastAPI app. By default it adds:
+
+- `SecurityHeadersMiddleware` with practical defaults:
+  - **Content-Security-Policy**: Allows same-origin resources, inline styles/scripts, data URI images, and HTTPS images. Blocks external scripts and framing.
+  - **Strict-Transport-Security**: Forces HTTPS with long max-age and subdomain support
+  - **X-Frame-Options**: Blocks framing (DENY)
+  - **X-Content-Type-Options**: Prevents MIME sniffing (nosniff)
+  - **Referrer-Policy**: Limits referrer leakage
+  - **X-XSS-Protection**: Disabled (CSP is the modern protection)
+- A strict `CORSMiddleware` that only enables CORS when origins are provided (via
+  parameters or environment variables such as `CORS_ALLOW_ORIGINS`).
+
+The default CSP policy is:
+```
+default-src 'self';
+script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net;
+style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net;
+img-src 'self' data: https:;
+connect-src 'self';
+font-src 'self' https://cdn.jsdelivr.net;
+frame-ancestors 'none';
+base-uri 'self';
+form-action 'self'
+```
+
+This works out-of-the-box for most web applications, including FastAPI's built-in documentation (Swagger UI, ReDoc), while maintaining strong security.
+
+The helper also supports optional toggles so you can match the same cookie and
+header configuration that `setup_service_api` uses.
+
+```python
+from fastapi import FastAPI
+
+from svc_infra.security.add import add_security
+
+app = FastAPI()
+
+add_security(
+    app,
+    cors_origins=["https://app.example.com"],
+    headers_overrides={"Content-Security-Policy": "default-src 'self'; script-src 'self'"},  # Stricter CSP
+    install_session_middleware=True,  # adds Starlette's SessionMiddleware
+)
+```
+
+Environment variables (applied when parameters are omitted):
+
+| Variable | Purpose |
+| --- | --- |
+| `CORS_ALLOW_ORIGINS` | Comma-separated CORS origins (e.g. `https://app.example.com, https://admin.example.com`) |
+| `CORS_ALLOW_METHODS` | Allowed HTTP methods (defaults to `*`) |
+| `CORS_ALLOW_HEADERS` | Allowed headers (defaults to `*`) |
+| `CORS_ALLOW_ORIGIN_REGEX` | Regex used when matching origins (ignored if not set) |
+| `CORS_ALLOW_CREDENTIALS` | Toggle credentials support (`true` / `false`) |
+| `SESSION_COOKIE_NAME` | Session cookie name (defaults to `svc_session`) |
+| `SESSION_COOKIE_MAX_AGE_SECONDS` | Max age for the session cookie (defaults to `14400`) |
+| `SESSION_COOKIE_SAMESITE` | SameSite policy (`lax` by default) |
+| `SESSION_COOKIE_SECURE` | Force the session cookie to be HTTPS-only |
+| `SESSION_SECRET` | Secret key for Starlette's SessionMiddleware |
+
+When your service already uses `setup_service_api`, call `add_security` after
+building the parent app if you need additional overrides while keeping the
+defaults intact:
+
+```python
+from svc_infra.api.fastapi.setup import setup_service_api
+from svc_infra.security.add import add_security
+
+app = setup_service_api(...)
+
+add_security(
+    app,
+    headers_overrides={"Strict-Transport-Security": "max-age=63072000; includeSubDomains"},
+    enable_hsts_preload=False,
+)
+```
+
+## RBAC and ABAC
+- RBAC decorators guard endpoints by role/permission.
+- ABAC evaluates resource ownership and attributes (e.g., `owns_resource`).
+
+## MFA policy hooks
+- Policy decides when MFA is required; login returns 401 with `MFA_REQUIRED` and a pre-token when applicable.
+
+## Troubleshooting
+- 429 on login: lockout active. Check `Retry-After` and `FailedAuthAttempt` rows.
+- Token invalid post-refresh: confirm rotation + revocation writes.
+- Cookie verification errors: check signing keys/exp.