svc-infra 0.1.631__py3-none-any.whl → 0.1.632__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/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/security/permissions.py

@@ -16,6 +16,7 @@ PERMISSION_REGISTRY: Dict[str, Set[str]] = {
         "billing.write",
         "security.session.revoke",
         "security.session.list",
+        "admin.impersonate",
     },
     "support": {"user.read", "billing.read"},
     "auditor": {"user.read", "billing.read", "audit.read"},

{svc_infra-0.1.631.dist-info → svc_infra-0.1.632.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.631
+Version: 0.1.632
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic

{svc_infra-0.1.631.dist-info → svc_infra-0.1.632.dist-info}/RECORD

@@ -13,6 +13,8 @@ svc_infra/apf_payments/service.py,sha256=Y5wtT9qnL57b_A3AAIL8fruliAitxeVyMPaYLZs
 svc_infra/apf_payments/settings.py,sha256=vVWsvz_ajtVlRPH4N8ijSI4V7hUfjZFZT3h4wHRNa-s,2032
 svc_infra/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/api/fastapi/__init__.py,sha256=VVdQjak74_wTDqmvL05_C97vIFugQxPVU-3JQEFBgR8,747
+svc_infra/api/fastapi/admin/__init__.py,sha256=AmuCHI5EQRCqwM40Gs1245z7MTcYZkg5xuoaplCExko,82
+svc_infra/api/fastapi/admin/add.py,sha256=9mCfvKvwBf_sr-SkpCbF1YMNvg-KRovrM_WV3hHs8m8,8649
 svc_infra/api/fastapi/apf_payments/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/api/fastapi/apf_payments/router.py,sha256=JIMCAZ1_Vie_EfvOS999iYSDH9ZBx1Nfizud-F_b5T0,36788
 svc_infra/api/fastapi/apf_payments/setup.py,sha256=bk_LLLXyqTA-lqf0v-mdpqLEMbXB17U1IQjG-qSBejQ,2677
@@ -236,6 +238,7 @@ svc_infra/docs/adr/0007-docs-and-sdks.md,sha256=uQ-q-5omaOXPL5tW5q0_1FE9P_OmO9aD
 svc_infra/docs/adr/0008-billing-primitives.md,sha256=6em0RYeDAQScN7oSZfD_XslzrzIZZ-qykROJixCcEQs,8479
 svc_infra/docs/adr/0009-acceptance-harness.md,sha256=jDmoWn2uJTeK28YZo75YR1ym6NdgcmPOlMfupZlCCBs,2146
 svc_infra/docs/adr/0010-timeouts-and-resource-limits.md,sha256=tpOTjncKJAjTsDN8jSUOTNqEKHfhVcfooxfW0nnbnro,2815
+svc_infra/docs/adr/0011-admin-scope-and-impersonation.md,sha256=tHg0vXzyefr6qEQOes2OyQByZsK-ogDe1VQ1dQn2Ibc,4850
 svc_infra/docs/api.md,sha256=AlPL9kBS6_dM0NrOteDQ9WqalSfKf_p9_zdy1CtGJdU,2384
 svc_infra/docs/auth.md,sha256=PRl9G4UW78cT_7c4koVh5NDlheNAr02CpJT2YFbEXto,1333
 svc_infra/docs/billing.md,sha256=MArKbKhzFwMLaOMABNDRtT_2D0zGgyFZ2r54o-99v68,7884
@@ -330,7 +333,7 @@ svc_infra/security/lockout.py,sha256=KdKN9FWejuzHRKS9jXzi_f3-lNF6QZyiEDBXCej0LSY
 svc_infra/security/models.py,sha256=US5jxgeZf7C_tWW3QZRj5RTuRZE_yS6RHZBEK0ea9tA,9535
 svc_infra/security/org_invites.py,sha256=TuXEstZp5GfRQflz8OR2q6m7GpSOonSxm0QU7ojkbH0,3876
 svc_infra/security/passwords.py,sha256=zUiduHFOWYT7USzMkBntI3-LNEyVMn2A78CvaKpB7MY,2459
-svc_infra/security/permissions.py,sha256=fQm7-OcJJkWsScDcjS2gwmqaW93zQqltaHRl6bviIik,4527
+svc_infra/security/permissions.py,sha256=gQijNud6jh0yY2JIuZazAVE8i9zYhbwAR6tSjbncv5o,4556
 svc_infra/security/session.py,sha256=JkClqoZ-Moo9yqHzCREXMVSpzyjbn2Zh6zCjtWO93Ik,2848
 svc_infra/security/signed_cookies.py,sha256=2t61BgjsBaTzU46bt7IUJo7lwDRE9_eS4vmAQXJ8mlY,2219
 svc_infra/utils.py,sha256=VX1yjTx61-YvAymyRhGy18DhybiVdPddiYD_FlKTbJU,952
@@ -340,7 +343,7 @@ svc_infra/webhooks/fastapi.py,sha256=BCNvGNxukf6dC2a4i-6en-PrjBGV19YvCWOot5lXWsA
 svc_infra/webhooks/router.py,sha256=6JvAVPMEth_xxHX-IsIOcyMgHX7g1H0OVxVXKLuMp9w,1596
 svc_infra/webhooks/service.py,sha256=hh-rw0otc00vipZ998XaV5mHsk0IDGYqon0FnhaGr60,2229
 svc_infra/webhooks/signing.py,sha256=NCwdZzmravUe7HVIK_uXK0qqf12FG-_MVsgPvOw6lsM,784
-svc_infra-0.1.631.dist-info/METADATA,sha256=B-Klim62FKQqNr_a9lfHuJ3jsuWSf5HF032_SfiDDxM,8748
-svc_infra-0.1.631.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-svc_infra-0.1.631.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
-svc_infra-0.1.631.dist-info/RECORD,,
+svc_infra-0.1.632.dist-info/METADATA,sha256=qAkPSvHj4fYrc7CknZ2Mjp2-oRsp9Xlc0lQ-y9RgKNo,8748
+svc_infra-0.1.632.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+svc_infra-0.1.632.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
+svc_infra-0.1.632.dist-info/RECORD,,