svc-infra 0.1.595__py3-none-any.whl → 1.1.0__py3-none-any.whl

svc_infra/apf_payments/service.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-from typing import Optional
-
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -19,6 +17,7 @@ from .models import (
     PaySetupIntent,
     PaySubscription,
 )
+from .provider.base import ProviderAdapter
 from .provider.registry import get_provider_registry
 from .schemas import (
     BalanceSnapshotOut,
@@ -77,18 +76,18 @@ class PaymentsService:
         session: AsyncSession,
         *,
         tenant_id: str,
-        provider_name: Optional[str] = None,
+        provider_name: str | None = None,
     ):
         if not tenant_id:
             raise ValueError("tenant_id is required for PaymentsService")
         self.session = session
         self.tenant_id = tenant_id
         self._provider_name = (provider_name or _default_provider_name()).lower()
-        self._adapter = None  # resolved on first use
+        self._adapter: ProviderAdapter | None = None  # resolved on first use
 
     # --- internal helpers -----------------------------------------------------
 
-    def _get_adapter(self):
+    def _get_adapter(self) -> ProviderAdapter:
         if self._adapter is not None:
             return self._adapter
         reg = get_provider_registry()
@@ -143,7 +142,7 @@ class PaymentsService:
 
     # --- Intents --------------------------------------------------------------
 
-    async def create_intent(self, user_id: Optional[str], data: IntentCreateIn) -> IntentOut:
+    async def create_intent(self, user_id: str | None, data: IntentCreateIn) -> IntentOut:
         adapter = self._get_adapter()
         out = await adapter.create_intent(data, user_id=user_id)
         self.session.add(
@@ -491,7 +490,8 @@ class PaymentsService:
 
     async def capture_intent(self, provider_intent_id: str, data: CaptureIn) -> IntentOut:
         out = await self._get_adapter().capture_intent(
-            provider_intent_id, amount=int(data.amount) if data.amount is not None else None
+            provider_intent_id,
+            amount=int(data.amount) if data.amount is not None else None,
         )
         pi = await self.session.scalar(
             select(PayIntent).where(PayIntent.provider_intent_id == provider_intent_id)
@@ -623,8 +623,8 @@ class PaymentsService:
 
     # --- Disputes -------------------------------------------------------------
     async def list_disputes(
-        self, *, status: Optional[str], limit: int, cursor: Optional[str]
-    ) -> tuple[list[DisputeOut], Optional[str]]:
+        self, *, status: str | None, limit: int, cursor: str | None
+    ) -> tuple[list[DisputeOut], str | None]:
         return await self._get_adapter().list_disputes(status=status, limit=limit, cursor=cursor)
 
     async def get_dispute(self, provider_dispute_id: str) -> DisputeOut:
@@ -668,8 +668,8 @@ class PaymentsService:
 
     # --- Payouts --------------------------------------------------------------
     async def list_payouts(
-        self, *, limit: int, cursor: Optional[str]
-    ) -> tuple[list[PayoutOut], Optional[str]]:
+        self, *, limit: int, cursor: str | None
+    ) -> tuple[list[PayoutOut], str | None]:
         return await self._get_adapter().list_payouts(limit=limit, cursor=cursor)
 
     async def get_payout(self, provider_payout_id: str) -> PayoutOut:
@@ -699,7 +699,7 @@ class PaymentsService:
 
     # --- Webhook replay -------------------------------------------------------
     async def replay_webhooks(
-        self, since: Optional[str], until: Optional[str], event_ids: list[str]
+        self, since: str | None, until: str | None, event_ids: list[str]
     ) -> int:
         from datetime import datetime
 
@@ -730,7 +730,10 @@ class PaymentsService:
         adapter = self._get_adapter()
         try:
             return await adapter.list_customers(
-                provider=f.provider, user_id=f.user_id, limit=f.limit or 50, cursor=f.cursor
+                provider=f.provider,
+                user_id=f.user_id,
+                limit=f.limit or 50,
+                cursor=f.cursor,
             )
         except NotImplementedError:
             # Fallback to local DB listing
@@ -813,7 +816,10 @@ class PaymentsService:
         cursor: str | None,
     ) -> tuple[list[PriceOut], str | None]:
         return await self._get_adapter().list_prices(
-            provider_product_id=provider_product_id, active=active, limit=limit, cursor=cursor
+            provider_product_id=provider_product_id,
+            active=active,
+            limit=limit,
+            cursor=cursor,
         )
 
     async def update_price(self, provider_price_id: str, data: PriceUpdateIn) -> PriceOut:
@@ -838,7 +844,10 @@ class PaymentsService:
         cursor: str | None,
     ) -> tuple[list[SubscriptionOut], str | None]:
         return await self._get_adapter().list_subscriptions(
-            customer_provider_id=customer_provider_id, status=status, limit=limit, cursor=cursor
+            customer_provider_id=customer_provider_id,
+            status=status,
+            limit=limit,
+            cursor=cursor,
         )
 
     # ---- Payment Methods (get/update) ----
@@ -868,7 +877,9 @@ class PaymentsService:
         self, *, provider_payment_intent_id: str | None, limit: int, cursor: str | None
     ) -> tuple[list[RefundOut], str | None]:
         return await self._get_adapter().list_refunds(
-            provider_payment_intent_id=provider_payment_intent_id, limit=limit, cursor=cursor
+            provider_payment_intent_id=provider_payment_intent_id,
+            limit=limit,
+            cursor=cursor,
         )
 
     async def get_refund(self, provider_refund_id: str) -> RefundOut:

svc_infra/apf_payments/settings.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
 import os
-from typing import Optional
 
 from pydantic import BaseModel, SecretStr
 
 STRIPE_KEY = os.getenv("STRIPE_SECRET") or os.getenv("STRIPE_API_KEY")
 STRIPE_WH = os.getenv("STRIPE_WH_SECRET")
-PROVIDER = (os.getenv("APF_PAYMENTS_PROVIDER") or os.getenv("PAYMENTS_PROVIDER", "stripe")).lower()
+PROVIDER = (
+    os.getenv("APF_PAYMENTS_PROVIDER") or os.getenv("PAYMENTS_PROVIDER", "stripe") or "stripe"
+).lower()
 
 AIYDAN_KEY = os.getenv("AIYDAN_API_KEY")
 AIYDAN_CLIENT_KEY = os.getenv("AIYDAN_CLIENT_KEY")
@@ -19,23 +20,23 @@ AIYDAN_WH = os.getenv("AIYDAN_WH_SECRET")
 
 class StripeConfig(BaseModel):
     secret_key: SecretStr
-    webhook_secret: Optional[SecretStr] = None
+    webhook_secret: SecretStr | None = None
 
 
 class AiydanConfig(BaseModel):
     api_key: SecretStr
-    client_key: Optional[SecretStr] = None
-    merchant_account: Optional[str] = None
-    hmac_key: Optional[SecretStr] = None
-    base_url: Optional[str] = None
-    webhook_secret: Optional[SecretStr] = None
+    client_key: SecretStr | None = None
+    merchant_account: str | None = None
+    hmac_key: SecretStr | None = None
+    base_url: str | None = None
+    webhook_secret: SecretStr | None = None
 
 
 class PaymentsSettings(BaseModel):
     default_provider: str = PROVIDER
 
     # optional multi-tenant/provider map hook can be added later
-    stripe: Optional[StripeConfig] = (
+    stripe: StripeConfig | None = (
         StripeConfig(
             secret_key=SecretStr(STRIPE_KEY),
             webhook_secret=SecretStr(STRIPE_WH) if STRIPE_WH else None,
@@ -43,7 +44,7 @@ class PaymentsSettings(BaseModel):
         if STRIPE_KEY
         else None
     )
-    aiydan: Optional[AiydanConfig] = (
+    aiydan: AiydanConfig | None = (
         AiydanConfig(
             api_key=SecretStr(AIYDAN_KEY),
             client_key=SecretStr(AIYDAN_CLIENT_KEY) if AIYDAN_CLIENT_KEY else None,
@@ -57,7 +58,7 @@ class PaymentsSettings(BaseModel):
     )
 
 
-_SETTINGS: Optional[PaymentsSettings] = None
+_SETTINGS: PaymentsSettings | None = None
 
 
 def get_payments_settings() -> PaymentsSettings:

svc_infra/api/__init__.py

@@ -0,0 +1,61 @@
+"""svc-infra API module.
+
+Re-exports key API utilities from svc_infra.api.fastapi for convenient imports.
+"""
+
+from __future__ import annotations
+
+# Re-export from fastapi submodule
+from svc_infra.api.fastapi import (
+    APIVersionSpec,
+    # Dual routers
+    DualAPIRouter,
+    # Service setup
+    ServiceInfo,
+    add_dependency_health,
+    add_health_routes,
+    # Health checks
+    add_startup_probe,
+    check_database,
+    check_redis,
+    check_url,
+    cursor_window,
+    dualize_protected,
+    dualize_public,
+    dualize_user,
+    easy_service_api,
+    easy_service_app,
+    setup_caching,
+    setup_service_api,
+    sort_by,
+    text_filter,
+    # Pagination
+    use_pagination,
+)
+
+__all__ = [
+    # Dual routers
+    "DualAPIRouter",
+    "dualize_protected",
+    "dualize_public",
+    "dualize_user",
+    # Service setup
+    "ServiceInfo",
+    "APIVersionSpec",
+    "setup_service_api",
+    "easy_service_api",
+    "easy_service_app",
+    "setup_caching",
+    # Health checks
+    "add_startup_probe",
+    "add_health_routes",
+    "add_dependency_health",
+    "check_database",
+    "check_redis",
+    "check_url",
+    # Pagination
+    "use_pagination",
+    "text_filter",
+    "sort_by",
+    "cursor_window",
+]

svc_infra/api/fastapi/__init__.py

@@ -4,7 +4,25 @@ from svc_infra.api.fastapi.dual import (
     dualize_public,
     dualize_user,
 )
+from svc_infra.api.fastapi.object_router import (
+    DEFAULT_EXCEPTION_MAP,
+    STATUS_TITLES,
+    endpoint,
+    endpoint_exclude,
+    map_exception_to_http,
+    router_from_object,
+    router_from_object_with_websocket,
+    websocket_endpoint,
+)
 from svc_infra.api.fastapi.openapi.models import APIVersionSpec, ServiceInfo
+from svc_infra.health import (
+    add_dependency_health,
+    add_health_routes,
+    add_startup_probe,
+    check_database,
+    check_redis,
+    check_url,
+)
 
 from .cache.add import setup_caching
 from .ease import easy_service_api, easy_service_app
@@ -18,6 +36,13 @@ __all__ = [
     "dualize_protected",
     "ServiceInfo",
     "APIVersionSpec",
+    # Health
+    "add_startup_probe",
+    "add_health_routes",
+    "add_dependency_health",
+    "check_database",
+    "check_redis",
+    "check_url",
     # Ease
     "setup_service_api",
     "easy_service_api",
@@ -28,4 +53,13 @@ __all__ = [
     "text_filter",
     "sort_by",
     "cursor_window",
+    # Object Router
+    "router_from_object",
+    "router_from_object_with_websocket",
+    "endpoint",
+    "endpoint_exclude",
+    "websocket_endpoint",
+    "map_exception_to_http",
+    "DEFAULT_EXCEPTION_MAP",
+    "STATUS_TITLES",
 ]

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,240 @@
+from __future__ import annotations
+
+import base64
+import hmac
+import inspect
+import json
+import logging
+import os
+import time
+from collections.abc import Callable
+from hashlib import sha256
+from types import SimpleNamespace
+from typing import Any, cast
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
+
+from ....app.env import get_current_environment, require_secret
+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 cast("dict[Any, Any]", payload)
+    except Exception as e:
+        raise ValueError("invalid_token") from e
+
+
+def admin_router(*, dependencies: list[Any] | None = None, **kwargs) -> APIRouter:
+    """Role-gated admin router for coarse access control.
+
+    Use permission guards inside endpoints for fine-grained control.
+    """
+
+    return cast("APIRouter", roles_router("admin", **kwargs))
+
+
+def add_admin(
+    app,
+    *,
+    base_path: str = "/admin",
+    enable_impersonation: bool = True,
+    secret: str | None = None,
+    ttl_seconds: int = 15 * 60,
+    cookie_name: str = "impersonation",
+    impersonation_user_getter: Callable[[Any, str], Any] | None = 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 = require_secret(
+        secret or os.getenv("ADMIN_IMPERSONATION_SECRET") or os.getenv("APP_SECRET"),
+        "ADMIN_IMPERSONATION_SECRET or APP_SECRET",
+        dev_default="dev-only-admin-impersonation-secret-not-for-production",
+    )
+    _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 cast("Any", 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(
+            request: Request,
+            session: SqlSessionDep,
+            base: Principal = Depends(dep_provider),
+        ) -> 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
+            base.actor = getattr(base, "user", None)  # type: ignore[attr-defined]
+            # If target lacks roles, inherit actor roles to maintain permission checks
+            try:
+                if not getattr(target, "roles", None):
+                    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