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

svc_infra/apf_payments/service.py

@@ -19,6 +19,7 @@ from .models import (
     PaySetupIntent,
     PaySubscription,
 )
+from .provider.base import ProviderAdapter
 from .provider.registry import get_provider_registry
 from .schemas import (
     BalanceSnapshotOut,
@@ -84,11 +85,11 @@ class 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 +144,9 @@ class PaymentsService:
 
     # --- Intents --------------------------------------------------------------
 
-    async def create_intent(self, user_id: Optional[str], data: IntentCreateIn) -> IntentOut:
+    async def create_intent(
+        self, user_id: Optional[str], data: IntentCreateIn
+    ) -> IntentOut:
         adapter = self._get_adapter()
         out = await adapter.create_intent(data, user_id=user_id)
         self.session.add(
@@ -214,7 +217,9 @@ class PaymentsService:
 
     # --- Webhooks -------------------------------------------------------------
 
-    async def handle_webhook(self, provider: str, signature: str | None, payload: bytes) -> dict:
+    async def handle_webhook(
+        self, provider: str, signature: str | None, payload: bytes
+    ) -> dict:
         adapter = self._get_adapter()
         parsed = await adapter.verify_and_parse_webhook(signature, payload)
         self.session.add(
@@ -312,7 +317,9 @@ class PaymentsService:
                     )
                 )
 
-    async def attach_payment_method(self, data: PaymentMethodAttachIn) -> PaymentMethodOut:
+    async def attach_payment_method(
+        self, data: PaymentMethodAttachIn
+    ) -> PaymentMethodOut:
         out = await self._get_adapter().attach_payment_method(data)
         # Upsert locally for quick listing
         pm = PayPaymentMethod(
@@ -329,7 +336,9 @@ class PaymentsService:
         self.session.add(pm)
         return out
 
-    async def list_payment_methods(self, provider_customer_id: str) -> list[PaymentMethodOut]:
+    async def list_payment_methods(
+        self, provider_customer_id: str
+    ) -> list[PaymentMethodOut]:
         return await self._get_adapter().list_payment_methods(provider_customer_id)
 
     async def detach_payment_method(self, provider_method_id: str) -> PaymentMethodOut:
@@ -392,14 +401,18 @@ class PaymentsService:
     async def update_subscription(
         self, provider_subscription_id: str, data: SubscriptionUpdateIn
     ) -> SubscriptionOut:
-        out = await self._get_adapter().update_subscription(provider_subscription_id, data)
+        out = await self._get_adapter().update_subscription(
+            provider_subscription_id, data
+        )
         # Optionally reflect status/quantity locally (query + update if exists)
         return out
 
     async def cancel_subscription(
         self, provider_subscription_id: str, at_period_end: bool = True
     ) -> SubscriptionOut:
-        out = await self._get_adapter().cancel_subscription(provider_subscription_id, at_period_end)
+        out = await self._get_adapter().cancel_subscription(
+            provider_subscription_id, at_period_end
+        )
         return out
 
     # --- Invoices ---
@@ -444,15 +457,15 @@ class PaymentsService:
         q = select(
             func.date_trunc("day", LedgerEntry.ts).label("day"),
             LedgerEntry.currency,
-            func.sum(func.case((LedgerEntry.kind == "payment", LedgerEntry.amount), else_=0)).label(
-                "gross"
-            ),
-            func.sum(func.case((LedgerEntry.kind == "refund", LedgerEntry.amount), else_=0)).label(
-                "refunds"
-            ),
-            func.sum(func.case((LedgerEntry.kind == "fee", LedgerEntry.amount), else_=0)).label(
-                "fees"
-            ),
+            func.sum(
+                func.case((LedgerEntry.kind == "payment", LedgerEntry.amount), else_=0)
+            ).label("gross"),
+            func.sum(
+                func.case((LedgerEntry.kind == "refund", LedgerEntry.amount), else_=0)
+            ).label("refunds"),
+            func.sum(
+                func.case((LedgerEntry.kind == "fee", LedgerEntry.amount), else_=0)
+            ).label("fees"),
             func.count().label("count"),
         )
         if date_from:
@@ -465,9 +478,9 @@ class PaymentsService:
                 q = q.where(LedgerEntry.ts <= datetime.fromisoformat(date_to))
             except Exception:
                 pass
-        q = q.group_by(func.date_trunc("day", LedgerEntry.ts), LedgerEntry.currency).order_by(
-            func.date_trunc("day", LedgerEntry.ts).desc()
-        )
+        q = q.group_by(
+            func.date_trunc("day", LedgerEntry.ts), LedgerEntry.currency
+        ).order_by(func.date_trunc("day", LedgerEntry.ts).desc())
 
         rows = (await self.session.execute(q)).all()
         out: list[StatementRow] = []
@@ -489,9 +502,12 @@ class PaymentsService:
             )
         return out
 
-    async def capture_intent(self, provider_intent_id: str, data: CaptureIn) -> IntentOut:
+    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)
@@ -523,7 +539,9 @@ class PaymentsService:
                         )
         return out
 
-    async def list_intents(self, f: IntentListFilter) -> tuple[list[IntentOut], str | None]:
+    async def list_intents(
+        self, f: IntentListFilter
+    ) -> tuple[list[IntentOut], str | None]:
         return await self._get_adapter().list_intents(
             customer_provider_id=f.customer_provider_id,
             status=f.status,
@@ -535,9 +553,13 @@ class PaymentsService:
     async def add_invoice_line_item(
         self, provider_invoice_id: str, data: InvoiceLineItemIn
     ) -> InvoiceOut:
-        return await self._get_adapter().add_invoice_line_item(provider_invoice_id, data)
+        return await self._get_adapter().add_invoice_line_item(
+            provider_invoice_id, data
+        )
 
-    async def list_invoices(self, f: InvoicesListFilter) -> tuple[list[InvoiceOut], str | None]:
+    async def list_invoices(
+        self, f: InvoicesListFilter
+    ) -> tuple[list[InvoiceOut], str | None]:
         return await self._get_adapter().list_invoices(
             customer_provider_id=f.customer_provider_id,
             status=f.status,
@@ -574,7 +596,9 @@ class PaymentsService:
         )
         return out
 
-    async def confirm_setup_intent(self, provider_setup_intent_id: str) -> SetupIntentOut:
+    async def confirm_setup_intent(
+        self, provider_setup_intent_id: str
+    ) -> SetupIntentOut:
         out = await self._get_adapter().confirm_setup_intent(provider_setup_intent_id)
         row = await self.session.scalar(
             select(PaySetupIntent).where(
@@ -625,13 +649,17 @@ class PaymentsService:
     async def list_disputes(
         self, *, status: Optional[str], limit: int, cursor: Optional[str]
     ) -> tuple[list[DisputeOut], Optional[str]]:
-        return await self._get_adapter().list_disputes(status=status, limit=limit, cursor=cursor)
+        return await self._get_adapter().list_disputes(
+            status=status, limit=limit, cursor=cursor
+        )
 
     async def get_dispute(self, provider_dispute_id: str) -> DisputeOut:
         out = await self._get_adapter().get_dispute(provider_dispute_id)
         # Upsert locally
         row = await self.session.scalar(
-            select(PayDispute).where(PayDispute.provider_dispute_id == provider_dispute_id)
+            select(PayDispute).where(
+                PayDispute.provider_dispute_id == provider_dispute_id
+            )
         )
         if row:
             row.status = out.status
@@ -652,11 +680,17 @@ class PaymentsService:
             )
         return out
 
-    async def submit_dispute_evidence(self, provider_dispute_id: str, evidence: dict) -> DisputeOut:
-        out = await self._get_adapter().submit_dispute_evidence(provider_dispute_id, evidence)
+    async def submit_dispute_evidence(
+        self, provider_dispute_id: str, evidence: dict
+    ) -> DisputeOut:
+        out = await self._get_adapter().submit_dispute_evidence(
+            provider_dispute_id, evidence
+        )
         # reflect status
         row = await self.session.scalar(
-            select(PayDispute).where(PayDispute.provider_dispute_id == provider_dispute_id)
+            select(PayDispute).where(
+                PayDispute.provider_dispute_id == provider_dispute_id
+            )
         )
         if row:
             row.status = out.status
@@ -726,11 +760,16 @@ class PaymentsService:
         return len(rows)
 
     # ---- Customers ----
-    async def list_customers(self, f: CustomersListFilter) -> tuple[list[CustomerOut], str | None]:
+    async def list_customers(
+        self, f: CustomersListFilter
+    ) -> tuple[list[CustomerOut], str | None]:
         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
@@ -766,7 +805,9 @@ class PaymentsService:
             raise RuntimeError("Customer not found")
         # upsert locally
         row = await self.session.scalar(
-            select(PayCustomer).where(PayCustomer.provider_customer_id == provider_customer_id)
+            select(PayCustomer).where(
+                PayCustomer.provider_customer_id == provider_customer_id
+            )
         )
         if not row:
             self.session.add(
@@ -786,13 +827,19 @@ class PaymentsService:
     async def list_products(
         self, *, active: bool | None, limit: int, cursor: str | None
     ) -> tuple[list[ProductOut], str | None]:
-        return await self._get_adapter().list_products(active=active, limit=limit, cursor=cursor)
+        return await self._get_adapter().list_products(
+            active=active, limit=limit, cursor=cursor
+        )
 
-    async def update_product(self, provider_product_id: str, data: ProductUpdateIn) -> ProductOut:
+    async def update_product(
+        self, provider_product_id: str, data: ProductUpdateIn
+    ) -> ProductOut:
         out = await self._get_adapter().update_product(provider_product_id, data)
         # reflect DB
         row = await self.session.scalar(
-            select(PayProduct).where(PayProduct.provider_product_id == provider_product_id)
+            select(PayProduct).where(
+                PayProduct.provider_product_id == provider_product_id
+            )
         )
         if row:
             if data.name is not None:
@@ -813,10 +860,15 @@ 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:
+    async def update_price(
+        self, provider_price_id: str, data: PriceUpdateIn
+    ) -> PriceOut:
         out = await self._get_adapter().update_price(provider_price_id, data)
         row = await self.session.scalar(
             select(PayPrice).where(PayPrice.provider_price_id == provider_price_id)
@@ -838,7 +890,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 +923,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

@@ -7,7 +7,11 @@ 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")

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 (
+    # 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,
+)
+
+__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

@@ -5,6 +5,14 @@ from svc_infra.api.fastapi.dual import (
     dualize_user,
 )
 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 +26,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",

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,245 @@
+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, 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: Optional[list[Any]] = 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: 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 = 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
+            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