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

svc_infra/security/permissions.py

@@ -1,14 +1,19 @@
 from __future__ import annotations
 
 import inspect
-from typing import Any, Awaitable, Callable, Dict, Iterable, Set
+import threading
+from collections.abc import Awaitable, Callable, Iterable
+from typing import Any
 
 from fastapi import Depends, HTTPException
 
 from svc_infra.api.fastapi.auth.security import Identity
 
+# Thread-safe permission registry
+_PERMISSION_LOCK = threading.Lock()
+
 # Central role -> permissions mapping. Projects can extend at startup.
-PERMISSION_REGISTRY: Dict[str, Set[str]] = {
+PERMISSION_REGISTRY: dict[str, set[str]] = {
     "admin": {
         "user.read",
         "user.write",
@@ -16,20 +21,37 @@ 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"},
 }
 
 
-def get_permissions_for_roles(roles: Iterable[str]) -> Set[str]:
-    perms: Set[str] = set()
-    for r in roles:
-        perms |= PERMISSION_REGISTRY.get(r, set())
+def register_role(role: str, permissions: set[str]) -> None:
+    """Thread-safe registration of a role and its permissions."""
+    with _PERMISSION_LOCK:
+        PERMISSION_REGISTRY[role] = permissions
+
+
+def extend_role(role: str, permissions: set[str]) -> None:
+    """Thread-safe extension of an existing role's permissions."""
+    with _PERMISSION_LOCK:
+        if role in PERMISSION_REGISTRY:
+            PERMISSION_REGISTRY[role] |= permissions
+        else:
+            PERMISSION_REGISTRY[role] = permissions
+
+
+def get_permissions_for_roles(roles: Iterable[str]) -> set[str]:
+    perms: set[str] = set()
+    with _PERMISSION_LOCK:
+        for r in roles:
+            perms |= PERMISSION_REGISTRY.get(r, set())
     return perms
 
 
-def principal_permissions(principal: Identity) -> Set[str]:
+def principal_permissions(principal: Identity) -> set[str]:
     roles = getattr(principal.user, "roles", []) or []
     return get_permissions_for_roles(roles)
 
@@ -137,6 +159,8 @@ def RequireABAC(
 
 __all__ = [
     "PERMISSION_REGISTRY",
+    "register_role",
+    "extend_role",
     "get_permissions_for_roles",
     "principal_permissions",
     "has_permission",

svc_infra/security/session.py

@@ -1,13 +1,12 @@
 from __future__ import annotations
 
 import uuid
-from datetime import datetime, timedelta, timezone
-from typing import Optional
+from datetime import UTC, datetime, timedelta
 
 try:
     from sqlalchemy.ext.asyncio import AsyncSession
 except Exception:  # pragma: no cover
-    AsyncSession = object  # type: ignore
+    AsyncSession = object  # type: ignore[misc,assignment]
 
 from svc_infra.security.models import (
     AuthSession,
@@ -25,9 +24,9 @@ async def issue_session_and_refresh(
     db: AsyncSession,
     *,
     user_id: uuid.UUID,
-    tenant_id: Optional[str] = None,
-    user_agent: Optional[str] = None,
-    ip_hash: Optional[str] = None,
+    tenant_id: str | None = None,
+    user_agent: str | None = None,
+    ip_hash: str | None = None,
     ttl_minutes: int = DEFAULT_REFRESH_TTL_MINUTES,
 ) -> tuple[str, RefreshToken]:
     """Persist a new AuthSession + initial RefreshToken and return raw refresh token.
@@ -43,7 +42,7 @@ async def issue_session_and_refresh(
     db.add(session_row)
     raw = generate_refresh_token()
     token_hash = hash_refresh_token(raw)
-    expires_at = datetime.now(timezone.utc) + timedelta(minutes=ttl_minutes)
+    expires_at = datetime.now(UTC) + timedelta(minutes=ttl_minutes)
     rt = RefreshToken(
         session=session_row,
         token_hash=token_hash,
@@ -64,7 +63,7 @@ async def rotate_session_refresh(
 
     Returns: (new_raw_refresh_token, new_refresh_token_model)
     """
-    rotation_ts = datetime.now(timezone.utc)
+    rotation_ts = datetime.now(UTC)
     if current.revoked_at:
         raise ValueError("refresh token already revoked")
     if current.expires_at and current.expires_at <= rotation_ts:

svc_infra/security/signed_cookies.py

@@ -5,7 +5,7 @@ import hmac
 import json
 import time
 from hashlib import sha256
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any
 
 
 def _b64e(b: bytes) -> str:
@@ -26,19 +26,28 @@ def _now() -> int:
 
 
 def sign_cookie(
-    payload: Dict[str, Any],
+    payload: dict[str, Any],
     *,
     key: str,
-    expires_in: Optional[int] = None,
+    expires_in: int | None = None,
+    path: str | None = None,
+    domain: str | None = None,
 ) -> str:
-    """Produce a compact signed cookie value with optional expiry.
+    """Produce a compact signed cookie value with optional expiry and scope binding.
 
     Format: base64url(json).base64url(hmac)
     If expires_in is provided, 'exp' epoch seconds is injected into payload prior to signing.
+    If path or domain is provided, they are included in the signed payload to prevent
+    cookie replay attacks across different paths/domains.
     """
     body = dict(payload)
     if expires_in is not None:
         body.setdefault("exp", _now() + int(expires_in))
+    # Include scope in signature to prevent replay across paths/domains
+    if path is not None:
+        body.setdefault("_path", path)
+    if domain is not None:
+        body.setdefault("_domain", domain)
     data = json.dumps(body, separators=(",", ":"), sort_keys=True).encode()
     sig = _sign(data, key.encode())
     return f"{_b64e(data)}.{sig}"
@@ -48,12 +57,16 @@ def verify_cookie(
     value: str,
     *,
     key: str,
-    old_keys: Optional[List[str]] = None,
-) -> Tuple[bool, Optional[Dict[str, Any]]]:
+    old_keys: list[str] | None = None,
+    expected_path: str | None = None,
+    expected_domain: str | None = None,
+) -> tuple[bool, dict[str, Any] | None]:
     """Verify a signed cookie against the primary key or any old key.
 
     Returns (ok, payload). If ok is False, payload will be None.
     Rejects if exp is present and in the past.
+    If expected_path or expected_domain is provided, verifies the cookie was signed
+    for that scope (prevents replay attacks across paths/domains).
     """
     if not value or "." not in value:
         return False, None
@@ -72,6 +85,13 @@ def verify_cookie(
         # Expire when current time reaches or exceeds exp
         if "exp" in payload and _now() >= int(payload["exp"]):
             return False, None
+        # Verify scope binding if expected
+        if expected_path is not None:
+            if payload.get("_path") != expected_path:
+                return False, None
+        if expected_domain is not None:
+            if payload.get("_domain") != expected_domain:
+                return False, None
         return True, payload
     except Exception:
         return False, None

svc_infra/storage/__init__.py

@@ -0,0 +1,93 @@
+"""
+Generic file storage system for svc-infra.
+
+Provides backend-agnostic file storage with support for multiple providers:
+- Local filesystem (Railway volumes, Render, development)
+- S3-compatible (AWS S3, DigitalOcean Spaces, Wasabi, Backblaze B2, Minio)
+- Google Cloud Storage (coming soon)
+- Cloudinary (coming soon)
+- In-memory (testing)
+
+Quick Start:
+    >>> from svc_infra.storage import add_storage, easy_storage
+    >>> from fastapi import FastAPI
+    >>>
+    >>> app = FastAPI()
+    >>>
+    >>> # Auto-detect backend from environment
+    >>> storage = add_storage(app)
+    >>>
+    >>> # Or explicit backend
+    >>> backend = easy_storage(backend="s3", bucket="my-uploads")
+    >>> storage = add_storage(app, backend)
+
+Usage in Routes:
+    >>> from svc_infra.storage import get_storage, StorageBackend
+    >>> from fastapi import Depends, UploadFile
+    >>>
+    >>> @router.post("/upload")
+    >>> async def upload_file(
+    ...     file: UploadFile,
+    ...     storage: StorageBackend = Depends(get_storage),
+    ... ):
+    ...     content = await file.read()
+    ...     url = await storage.put(
+    ...         key=f"uploads/{file.filename}",
+    ...         data=content,
+    ...         content_type=file.content_type or "application/octet-stream",
+    ...         metadata={"user_id": "user_123"}
+    ...     )
+    ...     return {"url": url}
+
+Environment Variables:
+    STORAGE_BACKEND: Backend type (local, s3, gcs, cloudinary, memory)
+
+    Local:
+        STORAGE_BASE_PATH: Directory for files (default: /data/uploads)
+        STORAGE_BASE_URL: URL for file serving (default: http://localhost:8000/files)
+
+    S3:
+        STORAGE_S3_BUCKET: Bucket name (required)
+        STORAGE_S3_REGION: AWS region (default: us-east-1)
+        STORAGE_S3_ENDPOINT: Custom endpoint for S3-compatible services
+        STORAGE_S3_ACCESS_KEY: Access key (falls back to AWS_ACCESS_KEY_ID)
+        STORAGE_S3_SECRET_KEY: Secret key (falls back to AWS_SECRET_ACCESS_KEY)
+
+See Also:
+    - ADR-0012: Generic File Storage System design
+    - docs/storage.md: Comprehensive storage guide
+"""
+
+from .add import add_storage, get_storage, health_check_storage
+from .backends import LocalBackend, MemoryBackend, S3Backend
+from .base import (
+    FileNotFoundError,
+    InvalidKeyError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    StorageBackend,
+    StorageError,
+)
+from .easy import easy_storage
+from .settings import StorageSettings
+
+__all__ = [
+    # Main API
+    "add_storage",
+    "easy_storage",
+    "get_storage",
+    "health_check_storage",
+    # Base types
+    "StorageBackend",
+    "StorageSettings",
+    # Backends
+    "LocalBackend",
+    "MemoryBackend",
+    "S3Backend",
+    # Exceptions
+    "StorageError",
+    "FileNotFoundError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "InvalidKeyError",
+]

svc_infra/storage/add.py

@@ -0,0 +1,250 @@
+"""
+FastAPI integration for storage system.
+
+Provides helpers to integrate storage backends with FastAPI applications.
+"""
+
+import logging
+from contextlib import asynccontextmanager
+from typing import cast
+
+from fastapi import FastAPI, HTTPException, Query, Request
+from fastapi.responses import StreamingResponse
+
+from .base import FileNotFoundError, PermissionDeniedError, StorageBackend, StorageError
+from .easy import easy_storage
+
+logger = logging.getLogger(__name__)
+
+
+def add_storage(
+    app: FastAPI,
+    backend: StorageBackend | None = None,
+    serve_files: bool = False,
+    file_route_prefix: str = "/files",
+) -> StorageBackend:
+    """
+    Add storage backend to FastAPI application.
+
+    This function:
+    - Stores backend in app.state.storage
+    - Registers startup/shutdown hooks
+    - Optionally mounts file serving route
+    - Adds health check integration
+
+    Args:
+        app: FastAPI application instance
+        backend: Storage backend instance (auto-detected if None)
+        serve_files: If True, mount route to serve files (LocalBackend only)
+        file_route_prefix: URL prefix for file serving (default: "/files")
+
+    Returns:
+        Storage backend instance
+
+    Example:
+        >>> from fastapi import FastAPI
+        >>> from svc_infra.storage import add_storage, easy_storage
+        >>>
+        >>> app = FastAPI()
+        >>>
+        >>> # Auto-detect backend
+        >>> storage = add_storage(app)
+        >>>
+        >>> # Explicit backend
+        >>> backend = easy_storage(backend="s3", bucket="my-uploads")
+        >>> storage = add_storage(app, backend)
+        >>>
+        >>> # With file serving (LocalBackend only)
+        >>> backend = easy_storage(backend="local")
+        >>> storage = add_storage(app, backend, serve_files=True)
+
+    Note:
+        File serving is only supported for LocalBackend. For S3/GCS,
+        use presigned URLs instead.
+    """
+    # Auto-detect backend if not provided
+    if backend is None:
+        backend = easy_storage()
+
+    # Store in app state
+    app.state.storage = backend
+
+    # Get existing lifespan or create new one
+    existing_lifespan = getattr(app.router, "lifespan_context", None)
+
+    @asynccontextmanager
+    async def storage_lifespan(app: FastAPI):
+        # Startup
+        logger.info(f"Storage backend initialized: {backend.__class__.__name__}")
+
+        # Test connection for S3 backend
+        if hasattr(backend, "bucket"):
+            try:
+                # Try to list keys (limit 1 to minimize cost)
+                await backend.list_keys(limit=1)
+                logger.info(f"Successfully connected to storage: {backend.bucket}")
+            except Exception as e:
+                logger.error(f"Failed to connect to storage: {e}")
+                # Don't fail startup, let health check catch it
+
+        # Call existing lifespan if present
+        if existing_lifespan is not None:
+            async with existing_lifespan(app):
+                yield
+        else:
+            yield
+
+        # Shutdown
+        logger.info("Storage backend shutdown")
+
+    # Replace lifespan
+    app.router.lifespan_context = storage_lifespan
+
+    # Mount file serving route if requested (LocalBackend only)
+    if serve_files:
+        from .backends.local import LocalBackend
+
+        if not isinstance(backend, LocalBackend):
+            logger.warning(
+                f"File serving only supported for LocalBackend, "
+                f"got {backend.__class__.__name__}. Skipping route mount."
+            )
+        else:
+            # Create file serving route
+            @app.get(f"{file_route_prefix}/{{key:path}}")
+            async def serve_file(
+                key: str,
+                expires: str = Query(..., description="Expiration timestamp"),
+                signature: str = Query(..., description="HMAC signature"),
+                download: bool = Query(False, description="Force download"),
+            ):
+                """
+                Serve files from local storage with signature validation.
+
+                Requires valid signature generated by LocalBackend.get_url().
+                """
+                # Verify signature
+                if not backend.verify_url(key, expires, signature, download):
+                    raise HTTPException(
+                        status_code=403,
+                        detail="Invalid or expired signature",
+                    )
+
+                # Get file
+                try:
+                    data = await backend.get(key)
+                    metadata = await backend.get_metadata(key)
+
+                    # Determine content disposition
+                    if download:
+                        filename = key.split("/")[-1]
+                        content_disposition = f'attachment; filename="{filename}"'
+                    else:
+                        content_disposition = "inline"
+
+                    # Return file
+                    return StreamingResponse(
+                        iter([data]),
+                        media_type=metadata.get("content_type", "application/octet-stream"),
+                        headers={
+                            "Content-Disposition": content_disposition,
+                            "Content-Length": str(len(data)),
+                        },
+                    )
+
+                except FileNotFoundError:
+                    raise HTTPException(status_code=404, detail="File not found")
+                except PermissionDeniedError:
+                    raise HTTPException(status_code=403, detail="Permission denied")
+                except StorageError as e:
+                    logger.error(f"Storage error serving file {key}: {e}")
+                    raise HTTPException(status_code=500, detail="Storage error")
+
+            logger.info(f"File serving enabled at {file_route_prefix}")
+
+    return backend
+
+
+def get_storage(request: Request) -> StorageBackend:
+    """
+    FastAPI dependency to inject storage backend.
+
+    Use this in route handlers to access the storage backend.
+
+    Example:
+        >>> from fastapi import APIRouter, Depends, UploadFile
+        >>> from svc_infra.storage import get_storage, StorageBackend
+        >>>
+        >>> router = APIRouter()
+        >>>
+        >>> @router.post("/upload")
+        >>> async def upload_file(
+        ...     file: UploadFile,
+        ...     storage: StorageBackend = Depends(get_storage),
+        ... ):
+        ...     content = await file.read()
+        ...     url = await storage.put(
+        ...         key=f"uploads/{file.filename}",
+        ...         data=content,
+        ...         content_type=file.content_type or "application/octet-stream"
+        ...     )
+        ...     return {"url": url}
+
+    Raises:
+        RuntimeError: If storage not initialized with add_storage()
+    """
+    if not hasattr(request.app.state, "storage"):
+        raise RuntimeError(
+            "Storage not initialized. Call add_storage(app) during application setup."
+        )
+
+    return cast("StorageBackend", request.app.state.storage)
+
+
+async def health_check_storage(request: Request) -> dict:
+    """
+    Health check for storage backend.
+
+    Returns storage status and basic statistics.
+
+    Example:
+        >>> from fastapi import FastAPI
+        >>> from svc_infra.storage import add_storage, health_check_storage
+        >>>
+        >>> app = FastAPI()
+        >>> add_storage(app)
+        >>>
+        >>> @app.get("/_health/storage")
+        >>> async def storage_health(request: Request):
+        ...     return await health_check_storage(request)
+
+    Returns:
+        Dict with status and backend information
+    """
+    try:
+        storage = get_storage(request)
+
+        # Get backend type
+        backend_type = storage.__class__.__name__.replace("Backend", "").lower()
+
+        # Try a simple operation
+        await storage.list_keys(limit=1)
+
+        return {
+            "status": "healthy",
+            "backend": backend_type,
+        }
+
+    except Exception as e:
+        logger.error(f"Storage health check failed: {e}")
+        return {
+            "status": "unhealthy",
+            "error": str(e),
+        }
+
+
+__all__ = [
+    "add_storage",
+    "get_storage",
+    "health_check_storage",
+]

svc_infra/storage/backends/__init__.py

@@ -0,0 +1,11 @@
+"""Storage backend implementations."""
+
+from .local import LocalBackend
+from .memory import MemoryBackend
+from .s3 import S3Backend
+
+__all__ = [
+    "LocalBackend",
+    "MemoryBackend",
+    "S3Backend",
+]