svc-infra 0.1.618__tar.gz → 0.1.672__tar.gz

{svc_infra-0.1.618 → svc_infra-0.1.672}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.618
+Version: 0.1.672
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic
@@ -24,10 +24,13 @@ Provides-Extra: mysql
 Provides-Extra: pg
 Provides-Extra: pg2
 Provides-Extra: redshift
+Provides-Extra: s3
 Provides-Extra: snowflake
 Provides-Extra: sqlite
 Requires-Dist: adyen (>=13.4.0,<14.0.0)
 Requires-Dist: ai-infra (>=0.1.63,<0.2.0)
+Requires-Dist: aioboto3 (>=13.0.0,<14.0.0) ; extra == "s3"
+Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
 Requires-Dist: aiosqlite (>=0.20.0,<0.21.0) ; extra == "sqlite"
 Requires-Dist: alembic (>=1.13.2,<2.0.0)
 Requires-Dist: asyncpg (>=0.30.0,<0.31.0) ; extra == "pg"
@@ -77,25 +80,50 @@ Description-Content-Type: text/markdown
 # 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)](docs/)
+[![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
 
-| Helper | What it covers | Guide |
+| Area | What it covers | Guide |
 | --- | --- | --- |
-| API | FastAPI bootstrap, envelopes, middleware, docs wiring | [FastAPI guide](docs/api.md) |
-| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth settings](docs/auth.md) |
-| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database guide](docs/database.md) |
-| Jobs | JobQueue, scheduler, CLI worker | [Jobs quickstart](docs/jobs.md) |
-| Cache | cashews decorators, namespace management, TTL helpers | [Cache guide](docs/cache.md) |
-| Observability | Prometheus middleware, Grafana automation, OTEL hooks | [Observability guide](docs/observability.md) |
-| Ops | Probes, breaker, SLOs & dashboards | [SLOs & Ops](docs/ops.md) |
-| Webhooks | Subscription store, signing, retry worker | [Webhooks framework](docs/webhooks.md) |
-| Security | Password policy, lockout, signed cookies, headers | [Security hardening](docs/security.md) |
-| Contributing | Dev setup and quality gates | [Contributing guide](docs/contributing.md) |
-| Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](docs/data-lifecycle.md) |
+| Getting Started | Overview and entry points | [This page](src/svc_infra/docs/getting-started.md) |
+| Environment | Feature switches and env vars | [Environment](src/svc_infra/docs/environment.md) |
+| API | FastAPI bootstrap, middleware, docs wiring | [API guide](src/svc_infra/docs/api.md) |
+| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth](src/svc_infra/docs/auth.md) |
+| Security | Password policy, lockout, signed cookies, headers | [Security](src/svc_infra/docs/security.md) |
+| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database](src/svc_infra/docs/database.md) |
+| Storage | File storage with S3, local, memory backends | [Storage](src/svc_infra/docs/storage.md) |
+| Documents | Generic document management with metadata | [Documents](src/svc_infra/docs/documents.md) |
+| Tenancy | Multi-tenant boundaries and helpers | [Tenancy](src/svc_infra/docs/tenancy.md) |
+| Idempotency | Idempotent endpoints and middleware | [Idempotency](src/svc_infra/docs/idempotency.md) |
+| Rate Limiting | Middleware, dependency limiter, headers | [Rate limiting](src/svc_infra/docs/rate-limiting.md) |
+| Cache | cashews decorators, namespace management, TTL helpers | [Cache](src/svc_infra/docs/cache.md) |
+| Jobs | JobQueue, scheduler, CLI worker | [Jobs](src/svc_infra/docs/jobs.md) |
+| Observability | Prometheus, Grafana, OpenTelemetry | [Observability](src/svc_infra/docs/observability.md) |
+| Ops | Probes, breakers, SLOs & dashboards | [Ops](src/svc_infra/docs/ops.md) |
+| Webhooks | Subscription store, signing, retry worker | [Webhooks](src/svc_infra/docs/webhooks.md) |
+| CLI | Command groups for sql/mongo/obs/docs/dx/sdk/jobs | [CLI](src/svc_infra/docs/cli.md) |
+| Docs & SDKs | Publishing docs, generating SDKs | [Docs & SDKs](src/svc_infra/docs/docs-and-sdks.md) |
+| Acceptance | Acceptance harness and flows | [Acceptance](src/svc_infra/docs/acceptance.md), [Matrix](src/svc_infra/docs/acceptance-matrix.md) |
+| Contributing | Dev setup and quality gates | [Contributing](src/svc_infra/docs/contributing.md) |
+| Repo Review | Checklist for releasing/PRs | [Repo review](src/svc_infra/docs/repo-review.md) |
+| Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](src/svc_infra/docs/data-lifecycle.md) |
+
+## Quick Start with Template Example
+
+See **ALL** svc-infra features working together in a complete example:
+
+```bash
+# One-time setup (from repo root)
+make setup-template    # Scaffolds models, runs migrations
+
+# Run the example server
+make run-template      # Starts at http://localhost:8001
+```
+
+See [`examples/README.md`](examples/README.md) for full documentation and manual setup options.
 
 ## Minimal FastAPI bootstrap
 
@@ -123,9 +151,10 @@ async def handle_webhook(payload = Depends(require_signature(lambda: ["current",
 - **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:docs/jobs.md†L11-L48】
+- **Storage** – choose backend with `STORAGE_BACKEND` (local, s3, memory) and configure with `STORAGE_S3_BUCKET`, `STORAGE_S3_REGION`, `STORAGE_BASE_PATH`, or auto-detect from `RAILWAY_VOLUME_MOUNT_PATH` / AWS credentials. 【F:src/svc_infra/storage/settings.py】【F:src/svc_infra/docs/storage.md】
+- **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: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:docs/security.md†L24-L70】
+- **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-0.1.672/README.md

@@ -0,0 +1,80 @@
+# 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](src/svc_infra/docs/getting-started.md) |
+| Environment | Feature switches and env vars | [Environment](src/svc_infra/docs/environment.md) |
+| API | FastAPI bootstrap, middleware, docs wiring | [API guide](src/svc_infra/docs/api.md) |
+| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth](src/svc_infra/docs/auth.md) |
+| Security | Password policy, lockout, signed cookies, headers | [Security](src/svc_infra/docs/security.md) |
+| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database](src/svc_infra/docs/database.md) |
+| Storage | File storage with S3, local, memory backends | [Storage](src/svc_infra/docs/storage.md) |
+| Documents | Generic document management with metadata | [Documents](src/svc_infra/docs/documents.md) |
+| Tenancy | Multi-tenant boundaries and helpers | [Tenancy](src/svc_infra/docs/tenancy.md) |
+| Idempotency | Idempotent endpoints and middleware | [Idempotency](src/svc_infra/docs/idempotency.md) |
+| Rate Limiting | Middleware, dependency limiter, headers | [Rate limiting](src/svc_infra/docs/rate-limiting.md) |
+| Cache | cashews decorators, namespace management, TTL helpers | [Cache](src/svc_infra/docs/cache.md) |
+| Jobs | JobQueue, scheduler, CLI worker | [Jobs](src/svc_infra/docs/jobs.md) |
+| Observability | Prometheus, Grafana, OpenTelemetry | [Observability](src/svc_infra/docs/observability.md) |
+| Ops | Probes, breakers, SLOs & dashboards | [Ops](src/svc_infra/docs/ops.md) |
+| Webhooks | Subscription store, signing, retry worker | [Webhooks](src/svc_infra/docs/webhooks.md) |
+| CLI | Command groups for sql/mongo/obs/docs/dx/sdk/jobs | [CLI](src/svc_infra/docs/cli.md) |
+| Docs & SDKs | Publishing docs, generating SDKs | [Docs & SDKs](src/svc_infra/docs/docs-and-sdks.md) |
+| Acceptance | Acceptance harness and flows | [Acceptance](src/svc_infra/docs/acceptance.md), [Matrix](src/svc_infra/docs/acceptance-matrix.md) |
+| Contributing | Dev setup and quality gates | [Contributing](src/svc_infra/docs/contributing.md) |
+| Repo Review | Checklist for releasing/PRs | [Repo review](src/svc_infra/docs/repo-review.md) |
+| Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](src/svc_infra/docs/data-lifecycle.md) |
+
+## Quick Start with Template Example
+
+See **ALL** svc-infra features working together in a complete example:
+
+```bash
+# One-time setup (from repo root)
+make setup-template    # Scaffolds models, runs migrations
+
+# Run the example server
+make run-template      # Starts at http://localhost:8001
+```
+
+See [`examples/README.md`](examples/README.md) for full documentation and manual setup options.
+
+## 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】
+- **Storage** – choose backend with `STORAGE_BACKEND` (local, s3, memory) and configure with `STORAGE_S3_BUCKET`, `STORAGE_S3_REGION`, `STORAGE_BASE_PATH`, or auto-detect from `RAILWAY_VOLUME_MOUNT_PATH` / AWS credentials. 【F:src/svc_infra/storage/settings.py】【F:src/svc_infra/docs/storage.md】
+- **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-0.1.618 → svc_infra-0.1.672}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "svc-infra"
-version = "0.1.618"
+version = "0.1.672"
 description = "Infrastructure for building and deploying prod-ready services"
 authors = ["Ali Khatami <aliikhatami94@gmail.com>"]
 license = "MIT"
@@ -13,7 +13,7 @@ include = [
     "src/svc_infra/obs/templates/**/*",
     "src/svc_infra/obs/grafana/templates/**/*",
     "src/svc_infra/obs/grafana/dashboards/**/*",
-    "docs/**/*"
+    "src/svc_infra/docs/**/*"
 ]
 
 classifiers = [
@@ -68,6 +68,10 @@ redshift-connector = { version = "^2.0.918", optional = true }
 duckdb = { version = "^1.1.3", optional = true }
 # (Removed hard psycopg2)
 
+# Storage
+aiofiles = "^24.1.0"
+aioboto3 = { version = "^13.0.0", optional = true }
+
 # Other infra deps
 mcp = "^1.13.0"
 ai-infra = "^0.1.63"
@@ -102,6 +106,7 @@ snowflake = ["snowflake-connector-python"]
 redshift = ["redshift-connector"]
 duckdb = ["duckdb"]
 metrics = ["prometheus-client"]
+s3 = ["aioboto3"]
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.2"
@@ -112,6 +117,8 @@ types-requests = "^2.32.0.20241016"
 pytest-mock = "^3.15.1"
 httpx = "^0.28.1"
 fakeredis = "^2.27.0"
+moto = {extras = ["s3"], version = "^5.0.0"}
+aiosqlite = "^0.20.0"  # Required for acceptance tests using SQLite
 
 [tool.poetry.scripts]
 svc-infra = "svc_infra.cli:main"
@@ -122,15 +129,20 @@ python_files = ["test_*.py", "*_test.py"]
 python_classes = ["Test*",]
 python_functions = ["test_*"]
 markers = [
+    "acceptance: End-to-end acceptance tests running against the acceptance app or BASE_URL",
+    "unit: Unit tests",
     "security: Security and auth hardening tests",
     "ratelimit: Rate limiting and abuse protection tests",
     "concurrency: Idempotency and concurrency control tests",
     "jobs: Background jobs and scheduling tests",
     "webhooks: Webhooks framework tests",
+    "billing: Billing primitives tests",
     "tenancy: Tenancy isolation and enforcement tests",
     "data_lifecycle: Data lifecycle (fixtures, retention, erasure, backups)",
     "ops: SLOs & Ops tests (probes, breaker, instrumentation)",
     "dx: Developer experience and quality gates tests",
+    "admin: Admin scope and impersonation tests",
+    "storage: File storage system tests",
 ]
 filterwarnings = [
     "ignore:The `route` decorator is deprecated:DeprecationWarning:starlette.*",

svc_infra-0.1.672/src/svc_infra/api/fastapi/admin/__init__.py

@@ -0,0 +1,3 @@
+from .add import add_admin, admin_router
+
+__all__ = ["add_admin", "admin_router"]

svc_infra-0.1.672/src/svc_infra/api/fastapi/admin/add.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import base64
+import hmac
+import inspect
+import json
+import logging
+import os
+import time
+from hashlib import sha256
+from types import SimpleNamespace
+from typing import Any, Callable, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
+
+from ....app.env import get_current_environment
+from ....security.permissions import RequirePermission
+from ..auth.security import Identity, Principal, _current_principal
+from ..auth.state import get_auth_state
+from ..db.sql.session import SqlSessionDep
+from ..dual.protected import roles_router
+
+logger = logging.getLogger(__name__)
+
+
+def _b64u(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _b64u_decode(s: str) -> bytes:
+    pad = "=" * ((4 - len(s) % 4) % 4)
+    return base64.urlsafe_b64decode(s + pad)
+
+
+def _sign(payload: dict, *, secret: str) -> str:
+    body = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    sig = hmac.new(secret.encode("utf-8"), body, sha256).digest()
+    return _b64u(body) + "." + _b64u(sig)
+
+
+def _verify(token: str, *, secret: str) -> dict:
+    try:
+        b64_body, b64_sig = token.split(".", 1)
+        body = _b64u_decode(b64_body)
+        exp_sig = _b64u_decode(b64_sig)
+        got_sig = hmac.new(secret.encode("utf-8"), body, sha256).digest()
+        if not hmac.compare_digest(exp_sig, got_sig):
+            raise ValueError("bad_signature")
+        payload = json.loads(body)
+        if int(payload.get("exp", 0)) < int(time.time()):
+            raise ValueError("expired")
+        return payload
+    except Exception as e:
+        raise ValueError("invalid_token") from e
+
+
+def admin_router(*, dependencies: Optional[list[Any]] = None, **kwargs) -> APIRouter:
+    """Role-gated admin router for coarse access control.
+
+    Use permission guards inside endpoints for fine-grained control.
+    """
+
+    return roles_router("admin", **kwargs)
+
+
+def add_admin(
+    app,
+    *,
+    base_path: str = "/admin",
+    enable_impersonation: bool = True,
+    secret: Optional[str] = None,
+    ttl_seconds: int = 15 * 60,
+    cookie_name: str = "impersonation",
+    impersonation_user_getter: Optional[Callable[[Any, str], Any]] = None,
+) -> None:
+    """Wire admin surfaces with sensible defaults.
+
+    - Mounts an admin router under base_path.
+    - Optionally enables impersonation start/stop endpoints guarded by permissions.
+    - Registers a dependency override to honor impersonation cookie globally (idempotent).
+
+    impersonation_user_getter: optional callable (request, user_id) -> user object.
+      If omitted, defaults to loading from SQLAlchemy User model returned by get_auth_state().
+    """
+
+    # Idempotency: only mount once per app instance
+    if getattr(app.state, "_admin_added", False):
+        return
+
+    env = get_current_environment()
+    _secret = (
+        secret or os.getenv("ADMIN_IMPERSONATION_SECRET") or os.getenv("APP_SECRET") or "dev-secret"
+    )
+    _ttl = int(os.getenv("ADMIN_IMPERSONATION_TTL", str(ttl_seconds)))
+    _cookie = os.getenv("ADMIN_IMPERSONATION_COOKIE", cookie_name)
+
+    r = admin_router(prefix=base_path, tags=["admin"])  # role-gated
+
+    async def _default_user_getter(request: Request, user_id: str, session: SqlSessionDep):
+        try:
+            UserModel, _, _ = get_auth_state()
+        except Exception:
+            # Fallback: simple shim if auth state not configured
+            return SimpleNamespace(id=user_id)
+        obj = await session.get(UserModel, user_id)
+        if not obj:
+            raise HTTPException(404, "user_not_found")
+        return obj
+
+    user_getter = impersonation_user_getter
+
+    @r.post(
+        "/impersonate/start", status_code=204, dependencies=[RequirePermission("admin.impersonate")]
+    )
+    async def start_impersonation(
+        body: dict, request: Request, response: Response, session: SqlSessionDep, identity: Identity
+    ):
+        target_id = (body or {}).get("user_id")
+        reason = (body or {}).get("reason", "")
+        if not target_id:
+            raise HTTPException(422, "user_id_required")
+        # Load target for validation (custom getter or default)
+        _res = (
+            user_getter(request, target_id)
+            if user_getter
+            else _default_user_getter(request, target_id, session)
+        )
+        target = await _res if inspect.isawaitable(_res) else _res
+        actor: Principal = identity
+        payload = {
+            "actor_id": getattr(getattr(actor, "user", None), "id", None),
+            "target_id": str(getattr(target, "id", target_id)),
+            "iat": int(time.time()),
+            "exp": int(time.time()) + _ttl,
+            "nonce": _b64u(os.urandom(8)),
+        }
+        token = _sign(payload, secret=_secret)
+        response.set_cookie(
+            key=_cookie,
+            value=token,
+            httponly=True,
+            samesite="lax",
+            secure=(env in ("prod", "production")),
+            path="/",
+            max_age=_ttl,
+        )
+        logger.info(
+            "admin.impersonation.started",
+            extra={
+                "actor_id": payload["actor_id"],
+                "target_id": payload["target_id"],
+                "reason": reason,
+                "expires_in": _ttl,
+            },
+        )
+        # Re-compose override now to wrap any late overrides set by tests/harness
+        try:
+            _compose_override()
+        except Exception:
+            pass
+
+    @r.post("/impersonate/stop", status_code=204)
+    async def stop_impersonation(response: Response):
+        response.delete_cookie(_cookie, path="/")
+        logger.info("admin.impersonation.stopped")
+
+    app.include_router(r)
+
+    # Dependency override: wrap the base principal to honor impersonation cookie.
+    # Compose with any existing override (e.g., acceptance app/test harness) and
+    # re-compose at startup to capture late overrides.
+    def _compose_override():
+        existing = app.dependency_overrides.get(_current_principal)
+        if existing and getattr(existing, "_is_admin_impersonation_override", False):
+            dep_provider = getattr(existing, "_admin_impersonation_base", _current_principal)
+        else:
+            dep_provider = existing or _current_principal
+
+        async def _override_current_principal(
+            base: Principal = Depends(dep_provider),
+            request: Request = None,
+            session: SqlSessionDep = None,
+        ) -> Principal:
+            token = request.cookies.get(_cookie) if request else None
+            if not token:
+                return base
+            try:
+                payload = _verify(token, secret=_secret)
+            except Exception:
+                return base
+            # Load target user
+            target_id = payload.get("target_id")
+            if not target_id:
+                return base
+            # Preserve actor roles/claims so permissions remain that of the actor
+            actor_user = getattr(base, "user", None)
+            actor_roles = getattr(actor_user, "roles", []) or []
+            _res = (
+                user_getter(request, target_id)
+                if user_getter
+                else _default_user_getter(request, target_id, session)
+            )
+            target = await _res if inspect.isawaitable(_res) else _res
+            # Swap user but keep actor for audit if needed
+            setattr(base, "actor", getattr(base, "user", None))
+            # If target lacks roles, inherit actor roles to maintain permission checks
+            try:
+                if not getattr(target, "roles", None):
+                    setattr(target, "roles", actor_roles)
+            except Exception:
+                # Best-effort; if target object is immutable, fallback by wrapping
+                target = SimpleNamespace(id=getattr(target, "id", target_id), roles=actor_roles)
+            base.user = target
+            base.via = "impersonated"
+            return base
+
+        app.dependency_overrides[_current_principal] = _override_current_principal
+        _override_current_principal._is_admin_impersonation_override = True  # type: ignore[attr-defined]
+        _override_current_principal._admin_impersonation_base = dep_provider  # type: ignore[attr-defined]
+
+    # Compose now (best-effort) and again on startup to wrap any later overrides
+    _compose_override()
+    try:
+        app.add_event_handler("startup", _compose_override)
+    except Exception:
+        # Best-effort; if app doesn't support event handlers, we already composed once
+        pass
+    app.state._admin_added = True
+
+
+# no extra helpers

{svc_infra-0.1.618 → svc_infra-0.1.672}/src/svc_infra/api/fastapi/apf_payments/setup.py

@@ -7,7 +7,6 @@ from fastapi import FastAPI
 
 from svc_infra.apf_payments.provider.registry import get_provider_registry
 from svc_infra.api.fastapi.apf_payments.router import build_payments_routers
-from svc_infra.api.fastapi.docs.scoped import add_prefixed_docs
 
 logger = logging.getLogger(__name__)
 
@@ -51,7 +50,6 @@ def add_payments(
     - Reuses your OpenAPI defaults (security + responses) via DualAPIRouter factories.
     """
     _maybe_register_default_providers(register_default_providers, adapters)
-    add_prefixed_docs(app, prefix=prefix, title="Payments")
 
     for r in build_payments_routers(prefix=prefix):
         app.include_router(

{svc_infra-0.1.618 → svc_infra-0.1.672}/src/svc_infra/api/fastapi/auth/add.py

@@ -17,7 +17,6 @@ from svc_infra.api.fastapi.paths.prefix import AUTH_PREFIX, USER_PREFIX
 from svc_infra.app.env import CURRENT_ENVIRONMENT, DEV_ENV, LOCAL_ENV
 from svc_infra.db.sql.apikey import bind_apikey_model
 
-from ..docs.scoped import add_prefixed_docs
 from .policy import AuthPolicy, DefaultAuthPolicy
 from .providers import providers_from_settings
 from .settings import get_auth_settings
@@ -293,9 +292,6 @@ def add_auth_users(
             https_only=bool(getattr(settings_obj, "session_cookie_secure", False)),
         )
 
-    add_prefixed_docs(app, prefix=user_prefix, title="Users")
-    add_prefixed_docs(app, prefix=auth_prefix, title="Auth")
-
     if enable_password:
         setup_password_authentication(
             app,

{svc_infra-0.1.618 → svc_infra-0.1.672}/src/svc_infra/api/fastapi/auth/routers/oauth_router.py

@@ -373,9 +373,8 @@ async def _update_provider_account(
 def _determine_final_redirect_url(request: Request, provider: str, post_login_redirect: str) -> str:
     """Determine the final redirect URL after successful authentication."""
     st = get_auth_settings()
-    redirect_url = str(
-        getattr(st, "post_login_redirect", post_login_redirect) or post_login_redirect
-    )
+    # Prioritize the parameter passed to the router over settings
+    redirect_url = str(post_login_redirect or getattr(st, "post_login_redirect", "/"))
     allow_hosts = parse_redirect_allow_hosts(getattr(st, "redirect_allow_hosts_raw", None))
     require_https = bool(getattr(st, "session_cookie_secure", False))
 
@@ -669,7 +668,23 @@ def _create_oauth_router(
             ip_hash=None,
         )
 
-        # Create response with auth + refresh cookies
+        # Generate JWT token for the response
+        strategy = auth_backend.get_strategy()
+        jwt_token = await strategy.write_token(user)
+
+        # If redirecting to a different origin, append token as URL fragment for frontend to extract
+        # This handles cross-port scenarios like localhost:8000 -> localhost:3000
+        parsed_redirect = urlparse(redirect_url)
+        request_origin = f"{request.url.scheme}://{request.url.netloc}"
+        redirect_origin = f"{parsed_redirect.scheme}://{parsed_redirect.netloc}"
+
+        if redirect_origin and redirect_origin != request_origin:
+            # Cross-origin redirect: append token as URL fragment
+            # Fragment is not sent to server, only accessible to client-side JS
+            separator = "#" if not parsed_redirect.fragment else "&"
+            redirect_url = f"{redirect_url}{separator}access_token={jwt_token}"
+
+        # Create response with auth + refresh cookies (for same-origin requests)
         resp = RedirectResponse(url=redirect_url, status_code=status.HTTP_302_FOUND)
         await _set_cookie_on_response(resp, auth_backend, user, refresh_raw=raw_refresh)
 

svc_infra-0.1.672/src/svc_infra/api/fastapi/billing/router.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Annotated, Optional
+
+from fastapi import APIRouter, Depends, Response, status
+
+from svc_infra.api.fastapi.db.sql.session import SqlSessionDep
+from svc_infra.api.fastapi.middleware.idempotency import require_idempotency_key
+from svc_infra.api.fastapi.tenancy.context import TenantId
+from svc_infra.billing.async_service import AsyncBillingService
+from svc_infra.billing.schemas import UsageAckOut, UsageAggregateRow, UsageAggregatesOut, UsageIn
+
+router = APIRouter(prefix="/_billing", tags=["Billing"])
+
+
+def get_service(tenant_id: TenantId, session: SqlSessionDep) -> AsyncBillingService:
+    return AsyncBillingService(session=session, tenant_id=tenant_id)
+
+
+@router.post(
+    "/usage",
+    name="billing_record_usage",
+    status_code=status.HTTP_202_ACCEPTED,
+    response_model=UsageAckOut,
+    dependencies=[Depends(require_idempotency_key)],
+)
+async def record_usage(
+    data: UsageIn, svc: Annotated[AsyncBillingService, Depends(get_service)], response: Response
+):
+    at = data.at or datetime.now(tz=timezone.utc)
+    evt_id = await svc.record_usage(
+        metric=data.metric,
+        amount=int(data.amount),
+        at=at,
+        idempotency_key=data.idempotency_key,
+        metadata=data.metadata,
+    )
+    # For 202, no Location header is required, but we can surface the id in the body
+    return UsageAckOut(id=evt_id, accepted=True)
+
+
+@router.get(
+    "/usage",
+    name="billing_list_aggregates",
+    response_model=UsageAggregatesOut,
+)
+async def list_aggregates(
+    metric: str,
+    date_from: Optional[datetime] = None,
+    date_to: Optional[datetime] = None,
+    svc: Annotated[AsyncBillingService, Depends(get_service)] = None,
+):
+    rows = await svc.list_daily_aggregates(metric=metric, date_from=date_from, date_to=date_to)
+    items = [
+        UsageAggregateRow(
+            period_start=r.period_start,
+            granularity=r.granularity,
+            metric=r.metric,
+            total=int(r.total),
+        )
+        for r in rows
+    ]
+    return UsageAggregatesOut(items=items, next_cursor=None)

svc_infra-0.1.672/src/svc_infra/api/fastapi/billing/setup.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from .router import router as billing_router
+
+
+def add_billing(app: FastAPI, *, prefix: str = "/_billing") -> None:
+    # Mount under the chosen prefix; default is /_billing
+    if prefix and prefix != "/_billing":
+        # If a custom prefix is desired, clone router with new prefix
+        from fastapi import APIRouter
+
+        custom = APIRouter(prefix=prefix, tags=["Billing"])
+        for route in billing_router.routes:
+            custom.routes.append(route)
+        app.include_router(custom)
+    else:
+        app.include_router(billing_router)