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

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/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/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/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/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/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/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)

svc_infra/api/fastapi/cache/add.py

@@ -1,3 +1,5 @@
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
 
 from svc_infra.cache.backend import shutdown_cache
@@ -5,10 +7,12 @@ from svc_infra.cache.decorators import init_cache
 
 
 def setup_caching(app: FastAPI) -> None:
-    @app.on_event("startup")
-    async def _startup():
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
         init_cache()
+        try:
+            yield
+        finally:
+            await shutdown_cache()
 
-    @app.on_event("shutdown")
-    async def _shutdown():
-        await shutdown_cache()
+    app.router.lifespan_context = lifespan

svc_infra/api/fastapi/db/nosql/mongo/add.py

@@ -38,8 +38,8 @@ def add_mongo_db_with_url(app: FastAPI, url: str, db_name: str) -> None:
 
 
 def add_mongo_db(app: FastAPI, *, dsn_env: str = "MONGO_URL") -> None:
-    @app.on_event("startup")
-    async def _startup() -> None:
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
         if not os.getenv(dsn_env):
             raise RuntimeError(f"Missing environment variable {dsn_env} for Mongo URL")
         await init_mongo()
@@ -47,10 +47,12 @@ def add_mongo_db(app: FastAPI, *, dsn_env: str = "MONGO_URL") -> None:
         db = await acquire_db()
         if expected and db.name != expected:
             raise RuntimeError(f"Connected to Mongo DB '{db.name}', expected '{expected}'.")
+        try:
+            yield
+        finally:
+            await close_mongo()
 
-    @app.on_event("shutdown")
-    async def _shutdown() -> None:
-        await close_mongo()
+    app.router.lifespan_context = lifespan
 
 
 def add_mongo_health(
@@ -62,46 +64,50 @@ def add_mongo_health(
 
 
 def add_mongo_resources(app: FastAPI, resources: Sequence[NoSqlResource]) -> None:
-    for r in resources:
+    for resource in resources:
         repo = NoSqlRepository(
-            collection_name=r.resolved_collection(),
-            id_field=r.id_field,
-            soft_delete=r.soft_delete,
-            soft_delete_field=r.soft_delete_field,
-            soft_delete_flag_field=r.soft_delete_flag_field,
+            collection_name=resource.resolved_collection(),
+            id_field=resource.id_field,
+            soft_delete=resource.soft_delete,
+            soft_delete_field=resource.soft_delete_field,
+            soft_delete_flag_field=resource.soft_delete_flag_field,
         )
-        svc = r.service_factory(repo) if r.service_factory else NoSqlService(repo)
+        svc = resource.service_factory(repo) if resource.service_factory else NoSqlService(repo)
 
-        if r.read_schema and r.create_schema and r.update_schema:
-            Read, Create, Update = r.read_schema, r.create_schema, r.update_schema
-        elif r.document_model is not None:
+        if resource.read_schema and resource.create_schema and resource.update_schema:
+            Read, Create, Update = (
+                resource.read_schema,
+                resource.create_schema,
+                resource.update_schema,
+            )
+        elif resource.document_model is not None:
             # CRITICAL: teach Pydantic to dump ObjectId/PyObjectId
             Read, Create, Update = make_document_crud_schemas(
-                r.document_model,
-                create_exclude=r.create_exclude,
-                read_name=r.read_name,
-                create_name=r.create_name,
-                update_name=r.update_name,
-                read_exclude=r.read_exclude,
-                update_exclude=r.update_exclude,
+                resource.document_model,
+                create_exclude=resource.create_exclude,
+                read_name=resource.read_name,
+                create_name=resource.create_name,
+                update_name=resource.update_name,
+                read_exclude=resource.read_exclude,
+                update_exclude=resource.update_exclude,
                 json_encoders={ObjectId: str, PyObjectId: str},
             )
         else:
             raise RuntimeError(
-                f"Resource for collection '{r.collection}' requires either explicit schemas "
+                f"Resource for collection '{resource.collection}' requires either explicit schemas "
                 f"(read/create/update) or a 'document_model' to derive them."
             )
 
         router = make_crud_router_plus_mongo(
-            collection=r.resolved_collection(),
+            collection=resource.resolved_collection(),
             repo=repo,
             service=svc,
             read_schema=Read,
             create_schema=Create,
             update_schema=Update,
-            prefix=r.prefix,
-            tags=r.tags,
-            search_fields=r.search_fields,
+            prefix=resource.prefix,
+            tags=resource.tags,
+            search_fields=resource.search_fields,
             default_ordering=None,
             allowed_order_fields=None,
         )

svc_infra/api/fastapi/db/sql/add.py

@@ -10,7 +10,7 @@ from svc_infra.db.sql.management import make_crud_schemas
 from svc_infra.db.sql.repository import SqlRepository
 from svc_infra.db.sql.resource import SqlResource
 
-from .crud_router import make_crud_router_plus_sql
+from .crud_router import make_crud_router_plus_sql, make_tenant_crud_router_plus_sql
 from .health import _make_db_health_router
 from .session import dispose_session, initialize_session
 
@@ -37,18 +37,37 @@ def add_sql_resources(app: FastAPI, resources: Sequence[SqlResource]) -> None:
                 update_name=r.update_name,
             )
 
-        router = make_crud_router_plus_sql(
-            model=r.model,
-            service=svc,
-            read_schema=Read,
-            create_schema=Create,
-            update_schema=Update,
-            prefix=r.prefix,
-            tags=r.tags,
-            search_fields=r.search_fields,
-            default_ordering=r.ordering_default,
-            allowed_order_fields=r.allowed_order_fields,
-        )
+        if r.tenant_field:
+            # wrap service factory/instance through tenant router
+            def _factory():
+                return svc
+
+            router = make_tenant_crud_router_plus_sql(
+                model=r.model,
+                service_factory=_factory,
+                read_schema=Read,
+                create_schema=Create,
+                update_schema=Update,
+                prefix=r.prefix,
+                tenant_field=r.tenant_field,
+                tags=r.tags,
+                search_fields=r.search_fields,
+                default_ordering=r.ordering_default,
+                allowed_order_fields=r.allowed_order_fields,
+            )
+        else:
+            router = make_crud_router_plus_sql(
+                model=r.model,
+                service=svc,
+                read_schema=Read,
+                create_schema=Create,
+                update_schema=Update,
+                prefix=r.prefix,
+                tags=r.tags,
+                search_fields=r.search_fields,
+                default_ordering=r.ordering_default,
+                allowed_order_fields=r.allowed_order_fields,
+            )
         app.include_router(router)
 
 
@@ -67,16 +86,19 @@ def add_sql_db(app: FastAPI, *, url: Optional[str] = None, dsn_env: str = "SQL_U
         app.router.lifespan_context = lifespan
         return
 
-    @app.on_event("startup")
-    async def _startup() -> None:  # noqa: ANN202
+    # Use lifespan context manager instead of deprecated on_event
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
         env_url = os.getenv(dsn_env)
         if not env_url:
             raise RuntimeError(f"Missing environment variable {dsn_env} for database URL")
         initialize_session(env_url)
+        try:
+            yield
+        finally:
+            await dispose_session()
 
-    @app.on_event("shutdown")
-    async def _shutdown() -> None:  # noqa: ANN202
-        await dispose_session()
+    app.router.lifespan_context = lifespan
 
 
 def add_sql_health(