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

svc_infra/api/fastapi/auth/routers/session_router.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
-from datetime import datetime, timezone
-from typing import List
+from datetime import UTC, datetime
 
 from fastapi import APIRouter, HTTPException
 from sqlalchemy import select
@@ -16,9 +15,11 @@ def build_session_router() -> APIRouter:
     router = APIRouter(prefix="/sessions", tags=["sessions"])
 
     @router.get(
-        "/me", response_model=list[dict], dependencies=[RequirePermission("security.session.list")]
+        "/me",
+        response_model=list[dict],
+        dependencies=[RequirePermission("security.session.list")],
     )
-    async def list_my_sessions(identity: Identity, session: SqlSessionDep) -> List[dict]:
+    async def list_my_sessions(identity: Identity, session: SqlSessionDep) -> list[dict]:
         stmt = select(AuthSession).where(AuthSession.user_id == identity.user.id)
         rows = (await session.execute(stmt)).scalars().all()
         return [
@@ -48,7 +49,7 @@ def build_session_router() -> APIRouter:
             raise HTTPException(403, "forbidden")
         if s.revoked_at:
             return  # already revoked
-        s.revoked_at = datetime.now(timezone.utc)
+        s.revoked_at = datetime.now(UTC)
         s.revoke_reason = "user_revoked"
         # Revoke all refresh tokens for this session
         for rt in s.refresh_tokens:

svc_infra/api/fastapi/auth/security.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
-from datetime import datetime, timezone
-from typing import Annotated, Any, Callable, Optional
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Annotated, Any, cast
 
 from fastapi import Depends, HTTPException, Request
 from fastapi.security import APIKeyCookie, APIKeyHeader, OAuth2PasswordBearer
@@ -26,7 +27,12 @@ class Principal:
     """Unified identity: user via JWT/cookie or service via API key."""
 
     def __init__(
-        self, *, user=None, scopes: list[str] | None = None, via: str = "jwt", api_key=None
+        self,
+        *,
+        user=None,
+        scopes: list[str] | None = None,
+        via: str = "jwt",
+        api_key=None,
     ):
         self.user = user
         self.scopes = scopes or []
@@ -38,7 +44,7 @@ class Principal:
 async def resolve_api_key(
     request: Request,
     session: SqlSessionDep,
-) -> Optional[Principal]:
+) -> Principal | None:
     raw = (request.headers.get("x-api-key") or "").strip()
     if not raw:
         return None
@@ -51,7 +57,11 @@ async def resolve_api_key(
     apikey = None
     if prefix:
         apikey = (
-            (await session.execute(select(ApiKey).where(ApiKey.key_prefix == prefix)))
+            (
+                await session.execute(
+                    select(ApiKey).where(ApiKey.key_prefix == prefix)  # type: ignore[attr-defined]
+                )
+            )
             .scalars()
             .first()
         )
@@ -64,7 +74,7 @@ async def resolve_api_key(
         raise HTTPException(401, "invalid_api_key")
     if not apikey.active:
         raise HTTPException(401, "api_key_revoked")
-    if apikey.expires_at and datetime.now(timezone.utc) > apikey.expires_at:
+    if apikey.expires_at and datetime.now(UTC) > apikey.expires_at:
         raise HTTPException(401, "api_key_expired")
 
     apikey.mark_used()
@@ -74,7 +84,7 @@ async def resolve_api_key(
 
 async def resolve_bearer_or_cookie_principal(
     request: Request, session: SqlSessionDep
-) -> Optional[Principal]:
+) -> Principal | None:
     st = get_auth_settings()
     raw_auth = (request.headers.get("authorization") or "").strip()
     token = raw_auth.split(" ", 1)[1].strip() if raw_auth.lower().startswith("bearer ") else ""
@@ -89,7 +99,7 @@ async def resolve_bearer_or_cookie_principal(
     from fastapi_users.manager import BaseUserManager, UUIDIDMixin
     from fastapi_users_db_sqlalchemy import SQLAlchemyUserDatabase
 
-    user_db = SQLAlchemyUserDatabase(session, UserModel)
+    user_db: Any = SQLAlchemyUserDatabase(session, UserModel)
 
     class _ShimManager(UUIDIDMixin, BaseUserManager[Any, Any]):
         reset_password_token_secret = "unused"
@@ -107,7 +117,7 @@ async def resolve_bearer_or_cookie_principal(
     if not user:
         return None
 
-    db_user = await session.get(UserModel, user.id)
+    db_user = await cast("Any", session).get(UserModel, user.id)
     if not db_user:
         return None
     if not getattr(db_user, "is_active", True):
@@ -123,8 +133,8 @@ async def resolve_bearer_or_cookie_principal(
 async def _current_principal(
     request: Request,
     session: SqlSessionDep,
-    jwt_or_cookie: Optional[Principal] = Depends(resolve_bearer_or_cookie_principal),
-    ak: Optional[Principal] = Depends(resolve_api_key),
+    jwt_or_cookie: Principal | None = Depends(resolve_bearer_or_cookie_principal),
+    ak: Principal | None = Depends(resolve_api_key),
 ) -> Principal:
     if jwt_or_cookie:
         return jwt_or_cookie
@@ -136,9 +146,9 @@ async def _current_principal(
 async def _optional_principal(
     request: Request,
     session: SqlSessionDep,
-    jwt_or_cookie: Optional[Principal] = Depends(resolve_bearer_or_cookie_principal),
-    ak: Optional[Principal] = Depends(resolve_api_key),
-) -> Optional[Principal]:
+    jwt_or_cookie: Principal | None = Depends(resolve_bearer_or_cookie_principal),
+    ak: Principal | None = Depends(resolve_api_key),
+) -> Principal | None:
     return jwt_or_cookie or ak or None
 
 
@@ -154,7 +164,7 @@ AllowIdentity = Depends(_optional_principal)  # same, but optional
 # ---------- DX: small guard factories ----------
 def RequireRoles(*roles: str, resolver: Callable[[Any], list[str]] | None = None):
     async def _guard(p: Identity):
-        have = set((resolver(p.user) if resolver else getattr(p.user, "roles", []) or []))
+        have = set(resolver(p.user) if resolver else getattr(p.user, "roles", []) or [])
         if not set(roles).issubset(have):
             raise HTTPException(403, "forbidden")
         return p

svc_infra/api/fastapi/auth/sender.py

@@ -59,4 +59,9 @@ def get_sender() -> Sender:
     if not configured:
         return ConsoleSender()
 
+    # At this point, all values must be set
+    assert host is not None
+    assert user is not None
+    assert pw is not None
+    assert frm is not None
     return SMTPSender(host, st.smtp_port, user, pw, frm)

svc_infra/api/fastapi/auth/settings.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import json
-from typing import List, Optional
 
 from pydantic import AnyHttpUrl, BaseModel, Field, SecretStr
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -19,7 +18,7 @@ class JWTSettings(BaseModel):
     secret: SecretStr
     lifetime_seconds: int = 60 * 60 * 24 * 7
     # Optional older secrets accepted for verification during rotation window
-    old_secrets: List[SecretStr] = Field(default_factory=list)
+    old_secrets: list[SecretStr] = Field(default_factory=list)
 
 
 class PasswordClient(BaseModel):
@@ -29,10 +28,10 @@ class PasswordClient(BaseModel):
 
 class AuthSettings(BaseSettings):
     # ---- JWT ----
-    jwt: Optional[JWTSettings] = None
+    jwt: JWTSettings | None = None
 
     # ---- Password login ----
-    password_clients: List[PasswordClient] = Field(default_factory=list)
+    password_clients: list[PasswordClient] = Field(default_factory=list)
     require_client_secret_on_password_login: bool = False
 
     # ---- MFA / TOTP ----
@@ -50,26 +49,26 @@ class AuthSettings(BaseSettings):
     email_otp_attempts: int = 5
 
     # ---- Email/SMTP (verification, reset, etc.) ----
-    smtp_host: Optional[str] = None
+    smtp_host: str | None = None
     smtp_port: int = 587
-    smtp_username: Optional[str] = None
-    smtp_password: Optional[SecretStr] = None
-    smtp_from: Optional[str] = None
+    smtp_username: str | None = None
+    smtp_password: SecretStr | None = None
+    smtp_from: str | None = None
 
     # Dev convenience: auto-verify users without sending email
     auto_verify_in_dev: bool = True
 
     # ---- Built-in provider creds (optional) ----
-    google_client_id: Optional[str] = None
-    google_client_secret: Optional[SecretStr] = None
-    github_client_id: Optional[str] = None
-    github_client_secret: Optional[SecretStr] = None
-    ms_client_id: Optional[str] = None
-    ms_client_secret: Optional[SecretStr] = None
-    ms_tenant: Optional[str] = None
-    li_client_id: Optional[str] = None
-    li_client_secret: Optional[SecretStr] = None
-    oidc_providers: List[OIDCProvider] = Field(default_factory=list)
+    google_client_id: str | None = None
+    google_client_secret: SecretStr | None = None
+    github_client_id: str | None = None
+    github_client_secret: SecretStr | None = None
+    ms_client_id: str | None = None
+    ms_client_secret: SecretStr | None = None
+    ms_tenant: str | None = None
+    li_client_id: str | None = None
+    li_client_secret: SecretStr | None = None
+    oidc_providers: list[OIDCProvider] = Field(default_factory=list)
 
     # ---- Redirect + cookie settings ----
     post_login_redirect: AnyHttpUrl | str = "http://localhost:3000/app"
@@ -79,7 +78,7 @@ class AuthSettings(BaseSettings):
     auth_cookie_name: str = "svc_auth"
     session_cookie_secure: bool = False
     session_cookie_samesite: str = "lax"
-    session_cookie_domain: Optional[str] = None
+    session_cookie_domain: str | None = None
     session_cookie_max_age_seconds: int = 60 * 60 * 4
 
     model_config = SettingsConfigDict(

svc_infra/api/fastapi/auth/state.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
-from typing import Any, Callable, Optional
+from collections.abc import Callable
+from typing import Any
 
-_UserModel: Optional[type] = None
-_GetStrategy: Optional[Callable[[], Any]] = None
+_UserModel: type | None = None
+_GetStrategy: Callable[[], Any] | None = None
 _AuthPrefix: str = "/auth"
-_UserScopeResolver: Optional[Callable[[Any], list[str]]] = None
+_UserScopeResolver: Callable[[Any], list[str]] | None = None
 
 
 def set_auth_state(

svc_infra/api/fastapi/auth/ws_security.py

@@ -0,0 +1,275 @@
+"""WebSocket authentication primitives.
+
+This module provides lightweight JWT-based authentication for WebSocket endpoints.
+Unlike HTTP auth which requires DB access, WS auth uses JWT claims only, making it
+suitable for high-frequency real-time connections.
+
+Usage:
+    from svc_infra.api.fastapi.auth.ws_security import WSIdentity
+
+    @router.websocket("/ws")
+    async def ws_handler(websocket: WebSocket, user: WSIdentity):
+        # user.id, user.email, user.scopes available from JWT claims
+        await websocket.accept()
+        ...
+
+For router-level dependencies (protects all endpoints):
+    from svc_infra.api.fastapi.auth.ws_security import RequireWSIdentity
+
+    router = DualAPIRouter(dependencies=[RequireWSIdentity])
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Annotated, Any, cast
+
+import jwt
+from fastapi import Depends, WebSocket, WebSocketException, status
+
+from svc_infra.api.fastapi.auth.settings import get_auth_settings
+
+
+# ---------- WSPrincipal ----------
+@dataclass
+class WSPrincipal:
+    """Lightweight principal for WebSocket connections.
+
+    Unlike the HTTP `Principal` which loads the full user from DB,
+    `WSPrincipal` contains only JWT claims. This makes it suitable
+    for high-frequency real-time connections without DB overhead.
+
+    Attributes:
+        id: User ID from JWT 'sub' claim (typically UUID string)
+        email: User email from JWT 'email' claim (if present)
+        scopes: List of scopes/permissions from JWT 'scopes' claim
+        claims: Full JWT payload for custom claim access
+        via: Authentication method ('query', 'header', 'subprotocol')
+    """
+
+    id: str
+    email: str | None = None
+    scopes: list[str] = field(default_factory=list)
+    claims: dict = field(default_factory=dict)
+    via: str = "query"  # 'query' | 'header' | 'subprotocol'
+
+
+# ---------- Token extraction ----------
+def _extract_token(websocket: WebSocket) -> tuple[str | None, str]:
+    """Extract JWT token from WebSocket connection.
+
+    Tries extraction in order:
+    1. Query parameter: ?token=xxx
+    2. Authorization header: Bearer xxx
+    3. Sec-WebSocket-Protocol header (for browser clients that can't set headers)
+
+    Returns:
+        Tuple of (token, source) where source is 'query', 'header', or 'subprotocol'
+    """
+    # 1. Query parameter (most common for WebSocket)
+    token = websocket.query_params.get("token")
+    if token:
+        return token.strip(), "query"
+
+    # 2. Authorization header
+    auth_header = websocket.headers.get("authorization", "")
+    if auth_header.lower().startswith("bearer "):
+        token = auth_header.split(" ", 1)[1].strip()
+        if token:
+            return token, "header"
+
+    # 3. Sec-WebSocket-Protocol (browser workaround)
+    # Some clients send token as: Sec-WebSocket-Protocol: bearer, <token>
+    protocol = websocket.headers.get("sec-websocket-protocol", "")
+    if protocol:
+        parts = [p.strip() for p in protocol.split(",")]
+        # Look for token after 'bearer' protocol
+        for i, part in enumerate(parts):
+            if part.lower() == "bearer" and i + 1 < len(parts):
+                return parts[i + 1], "subprotocol"
+
+    return None, ""
+
+
+def _decode_jwt(token: str) -> dict:
+    """Decode and validate JWT token.
+
+    Uses the same JWT settings as HTTP auth (AUTH_JWT__SECRET).
+    Supports key rotation via old_secrets.
+
+    Returns:
+        JWT payload dict
+
+    Raises:
+        WebSocketException: If token is invalid or expired
+    """
+    settings = get_auth_settings()
+
+    if not settings.jwt:
+        raise WebSocketException(
+            code=status.WS_1008_POLICY_VIOLATION,
+            reason="JWT not configured",
+        )
+
+    secret = settings.jwt.secret.get_secret_value()
+    old_secrets = [s.get_secret_value() for s in (settings.jwt.old_secrets or [])]
+    all_secrets = [secret, *old_secrets]
+
+    last_error: Exception | None = None
+
+    for s in all_secrets:
+        try:
+            payload = jwt.decode(
+                token,
+                s,
+                algorithms=["HS256"],
+                options={"require": ["sub", "exp"]},
+            )
+            return cast("dict[Any, Any]", payload)
+        except jwt.ExpiredSignatureError:
+            raise WebSocketException(
+                code=status.WS_1008_POLICY_VIOLATION,
+                reason="Token expired",
+            )
+        except jwt.InvalidTokenError as e:
+            last_error = e
+            continue
+
+    # None of the secrets worked
+    raise WebSocketException(
+        code=status.WS_1008_POLICY_VIOLATION,
+        reason=f"Invalid token: {last_error}",
+    )
+
+
+# ---------- Resolvers ----------
+async def resolve_ws_bearer_principal(websocket: WebSocket) -> WSPrincipal | None:
+    """Extract and validate JWT from WebSocket, returning WSPrincipal or None.
+
+    This is the optional resolver - returns None if no token present.
+    Use `_ws_current_principal` for required authentication.
+
+    Token sources (in order):
+        1. Query parameter: ?token=xxx
+        2. Authorization header: Bearer xxx
+        3. Sec-WebSocket-Protocol: bearer, xxx
+    """
+    token, source = _extract_token(websocket)
+    if not token:
+        return None
+
+    payload = _decode_jwt(token)
+
+    return WSPrincipal(
+        id=str(payload.get("sub", "")),
+        email=payload.get("email"),
+        scopes=payload.get("scopes", []) or payload.get("scope", "").split(),
+        claims=payload,
+        via=source,
+    )
+
+
+async def _ws_current_principal(
+    websocket: WebSocket,
+    principal: WSPrincipal | None = Depends(resolve_ws_bearer_principal),
+) -> WSPrincipal:
+    """Require authenticated WebSocket connection.
+
+    Use this as a dependency to require authentication.
+    Closes connection with 1008 (Policy Violation) if no valid token.
+    """
+    if not principal:
+        raise WebSocketException(
+            code=status.WS_1008_POLICY_VIOLATION,
+            reason="Missing or invalid authentication",
+        )
+    return principal
+
+
+async def _ws_optional_principal(
+    websocket: WebSocket,
+    principal: WSPrincipal | None = Depends(resolve_ws_bearer_principal),
+) -> WSPrincipal | None:
+    """Optional WebSocket authentication.
+
+    Returns None if no token present, WSPrincipal if valid token.
+    """
+    return principal
+
+
+# ---------- DX: types for endpoint params ----------
+WSIdentity = Annotated[WSPrincipal, Depends(_ws_current_principal)]
+"""Annotated type for required WebSocket authentication.
+
+Usage:
+    @router.websocket("/ws")
+    async def handler(websocket: WebSocket, user: WSIdentity):
+        # user.id, user.email, user.scopes available
+        ...
+"""
+
+OptionalWSIdentity = Annotated[WSPrincipal | None, Depends(_ws_optional_principal)]
+"""Annotated type for optional WebSocket authentication.
+
+Usage:
+    @router.websocket("/ws")
+    async def handler(websocket: WebSocket, user: OptionalWSIdentity):
+        if user:
+            # authenticated
+        else:
+            # anonymous
+        ...
+"""
+
+
+# ---------- DX: constants for router-level dependencies ----------
+RequireWSIdentity = Depends(_ws_current_principal)
+"""Router-level dependency for required WebSocket authentication.
+
+Usage:
+    router = DualAPIRouter(dependencies=[RequireWSIdentity])
+"""
+
+AllowWSIdentity = Depends(_ws_optional_principal)
+"""Router-level dependency for optional WebSocket authentication.
+
+Usage:
+    router = DualAPIRouter(dependencies=[AllowWSIdentity])
+"""
+
+
+# ---------- DX: guard factories ----------
+def RequireWSScopes(*needed: str):
+    """Require specific scopes for WebSocket connection.
+
+    Usage:
+        router = DualAPIRouter(dependencies=[RequireWSScopes("chat:read", "chat:write")])
+    """
+
+    async def _guard(principal: WSIdentity) -> WSPrincipal:
+        if not set(needed).issubset(set(principal.scopes or [])):
+            raise WebSocketException(
+                code=status.WS_1008_POLICY_VIOLATION,
+                reason="Insufficient scope",
+            )
+        return principal
+
+    return Depends(_guard)
+
+
+def RequireWSAnyScope(*candidates: str):
+    """Require at least one of the specified scopes.
+
+    Usage:
+        router = DualAPIRouter(dependencies=[RequireWSAnyScope("admin", "moderator")])
+    """
+
+    async def _guard(principal: WSIdentity) -> WSPrincipal:
+        if not set(principal.scopes or []) & set(candidates):
+            raise WebSocketException(
+                code=status.WS_1008_POLICY_VIOLATION,
+                reason="Insufficient scope",
+            )
+        return principal
+
+    return Depends(_guard)

svc_infra/api/fastapi/billing/router.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Annotated
+
+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=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: datetime | None = None,
+    date_to: datetime | None = None,
+    svc: Annotated[AsyncBillingService, Depends(get_service)] = None,  # type: ignore[assignment]
+):
+    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/__init__.py

@@ -1,4 +1,8 @@
-from svc_infra.api.fastapi.db.nosql import add_mongo_db, add_mongo_health, add_mongo_resources
+from svc_infra.api.fastapi.db.nosql import (
+    add_mongo_db,
+    add_mongo_health,
+    add_mongo_resources,
+)
 from svc_infra.api.fastapi.db.sql import add_sql_db, add_sql_health, add_sql_resources
 
 __all__ = [