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

svc_infra/security/passwords.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Callable, Iterable, Optional
+
+COMMON_PASSWORDS = {"password", "123456", "qwerty", "letmein", "admin"}
+
+HIBP_DISABLED = False  # default enabled; can be toggled via settings at startup
+
+
+@dataclass
+class PasswordPolicy:
+    min_length: int = 12
+    require_upper: bool = True
+    require_lower: bool = True
+    require_digit: bool = True
+    require_symbol: bool = True
+    forbid_common: bool = True
+    forbid_breached: bool = True  # will toggle off if HIBP integration not configured
+    symbols_regex: str = r"[!@#$%^&*()_+=\-{}\[\]:;,.?/]"
+
+
+class PasswordValidationError(Exception):
+    def __init__(self, reasons: Iterable[str]):
+        super().__init__("Password validation failed")
+        self.reasons = list(reasons)
+
+
+UPPER = re.compile(r"[A-Z]")
+LOWER = re.compile(r"[a-z]")
+DIGIT = re.compile(r"[0-9]")
+SYMBOL = re.compile(r"[!@#$%^&*()_+=\-{}\[\]:;,.?/]")
+
+
+BreachedChecker = Callable[[str], bool]
+
+
+_breached_checker: Optional[BreachedChecker] = None
+
+
+def configure_breached_checker(checker: Optional[BreachedChecker]) -> None:
+    global _breached_checker
+    _breached_checker = checker
+
+
+def validate_password(pw: str, policy: PasswordPolicy | None = None) -> None:
+    policy = policy or PasswordPolicy()
+    reasons: list[str] = []
+    if len(pw) < policy.min_length:
+        reasons.append(f"min_length({policy.min_length})")
+    if policy.require_upper and not UPPER.search(pw):
+        reasons.append("missing_upper")
+    if policy.require_lower and not LOWER.search(pw):
+        reasons.append("missing_lower")
+    if policy.require_digit and not DIGIT.search(pw):
+        reasons.append("missing_digit")
+    if policy.require_symbol and not SYMBOL.search(pw):
+        reasons.append("missing_symbol")
+    if policy.forbid_common:
+        lowered = pw.lower()
+        # Reject if whole password matches a common one or contains it as a substring
+        if lowered in COMMON_PASSWORDS or any(
+            term in lowered for term in COMMON_PASSWORDS
+        ):
+            reasons.append("common_password")
+    if policy.forbid_breached and not HIBP_DISABLED:
+        if _breached_checker and _breached_checker(pw):
+            reasons.append("breached_password")
+    if reasons:
+        raise PasswordValidationError(reasons)
+
+
+__all__ = [
+    "PasswordPolicy",
+    "validate_password",
+    "PasswordValidationError",
+    "configure_breached_checker",
+]

svc_infra/security/permissions.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import inspect
+import threading
+from typing import Any, Awaitable, Callable, Dict, Iterable, Set
+
+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]] = {
+    "admin": {
+        "user.read",
+        "user.write",
+        "billing.read",
+        "billing.write",
+        "security.session.revoke",
+        "security.session.list",
+        "admin.impersonate",
+    },
+    "support": {"user.read", "billing.read"},
+    "auditor": {"user.read", "billing.read", "audit.read"},
+}
+
+
+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]:
+    roles = getattr(principal.user, "roles", []) or []
+    return get_permissions_for_roles(roles)
+
+
+def has_permission(principal: Identity, permission: str) -> bool:
+    return permission in principal_permissions(principal)
+
+
+def RequirePermission(*needed: str):
+    """FastAPI dependency enforcing all listed permissions are present."""
+
+    async def _guard(principal: Identity):
+        perms = principal_permissions(principal)
+        missing = [p for p in needed if p not in perms]
+        if missing:
+            raise HTTPException(403, f"missing_permissions:{','.join(missing)}")
+        return principal
+
+    return Depends(_guard)
+
+
+def RequireAnyPermission(*candidates: str):
+    async def _guard(principal: Identity):
+        perms = principal_permissions(principal)
+        if not (perms & set(candidates)):
+            raise HTTPException(403, "insufficient_permissions")
+        return principal
+
+    return Depends(_guard)
+
+
+# ------- ABAC (Attribute-Based Access Control) helpers -------
+ABACPredicate = Callable[[Identity, Any], bool | Awaitable[bool]]
+
+
+def owns_resource(attr: str = "owner_id") -> ABACPredicate:
+    def _predicate(principal: Identity, resource: Any) -> bool:
+        user = getattr(principal, "user", None)
+        uid = getattr(user, "id", None)
+        rid = getattr(resource, attr, None) or getattr(resource, "user_id", None)
+        return bool(uid is not None and rid is not None and str(uid) == str(rid))
+
+    return _predicate
+
+
+async def _maybe_await(v):
+    if inspect.isawaitable(v):
+        return await v
+    return v
+
+
+def enforce_abac(
+    principal: Identity,
+    *,
+    permission: str,
+    resource: Any,
+    predicate: ABACPredicate,
+):
+    perms = principal_permissions(principal)
+    if permission not in perms:
+        raise HTTPException(403, f"missing_permissions:{permission}")
+    ok = False
+    # allow sync or async predicate
+    res = predicate(principal, resource)
+    if inspect.isawaitable(res):
+        # Fast path for sync contexts: raise clear guidance
+        raise RuntimeError(
+            "enforce_abac received an async predicate in a sync context; use RequireABAC for FastAPI dependencies."
+        )
+    else:
+        ok = bool(res)
+    if not ok:
+        raise HTTPException(403, "forbidden")
+    return principal
+
+
+def RequireABAC(
+    *,
+    permission: str,
+    predicate: ABACPredicate,
+    resource_getter: Callable[..., Any],
+):
+    """FastAPI dependency: enforce permission and attribute check using a resource provider.
+
+    Example:
+        def load_doc(): ...
+        @router.get("/docs/{doc_id}", dependencies=[RequireABAC(permission="doc.read", predicate=owns_resource(), resource_getter=load_doc)])
+        async def get_doc(identity: Identity, doc = Depends(load_doc)):
+            ...
+    Note: Using the provider in both the dependency and endpoint will call it twice. For heavy
+    providers, wire only in the dependency and re-fetch via the dependency override or request.state.
+    """
+
+    async def _guard(principal: Identity, resource: Any = Depends(resource_getter)):
+        perms = principal_permissions(principal)
+        if permission not in perms:
+            raise HTTPException(403, f"missing_permissions:{permission}")
+        ok = await _maybe_await(predicate(principal, resource))
+        if not ok:
+            raise HTTPException(403, "forbidden")
+        return principal
+
+    return Depends(_guard)
+
+
+__all__ = [
+    "PERMISSION_REGISTRY",
+    "register_role",
+    "extend_role",
+    "get_permissions_for_roles",
+    "principal_permissions",
+    "has_permission",
+    "RequirePermission",
+    "RequireAnyPermission",
+    "RequireABAC",
+    "enforce_abac",
+    "owns_resource",
+]

svc_infra/security/session.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+try:
+    from sqlalchemy.ext.asyncio import AsyncSession
+except Exception:  # pragma: no cover
+    AsyncSession = object  # type: ignore[misc,assignment]
+
+from svc_infra.security.models import (
+    AuthSession,
+    RefreshToken,
+    RefreshTokenRevocation,
+    generate_refresh_token,
+    hash_refresh_token,
+    rotate_refresh_token,
+)
+
+DEFAULT_REFRESH_TTL_MINUTES = 60 * 24 * 7  # 7 days
+
+
+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,
+    ttl_minutes: int = DEFAULT_REFRESH_TTL_MINUTES,
+) -> tuple[str, RefreshToken]:
+    """Persist a new AuthSession + initial RefreshToken and return raw refresh token.
+
+    Returns: (raw_refresh_token, RefreshToken model instance)
+    """
+    session_row = AuthSession(
+        user_id=user_id,
+        tenant_id=tenant_id,
+        user_agent=user_agent,
+        ip_hash=ip_hash,
+    )
+    db.add(session_row)
+    raw = generate_refresh_token()
+    token_hash = hash_refresh_token(raw)
+    expires_at = datetime.now(timezone.utc) + timedelta(minutes=ttl_minutes)
+    rt = RefreshToken(
+        session=session_row,
+        token_hash=token_hash,
+        expires_at=expires_at,
+    )
+    db.add(rt)
+    await db.flush()
+    return raw, rt
+
+
+async def rotate_session_refresh(
+    db: AsyncSession,
+    *,
+    current: RefreshToken,
+    ttl_minutes: int = DEFAULT_REFRESH_TTL_MINUTES,
+) -> tuple[str, RefreshToken]:
+    """Rotate a session's refresh token: mark current rotated, create new, add revocation record.
+
+    Returns: (new_raw_refresh_token, new_refresh_token_model)
+    """
+    rotation_ts = datetime.now(timezone.utc)
+    if current.revoked_at:
+        raise ValueError("refresh token already revoked")
+    if current.expires_at and current.expires_at <= rotation_ts:
+        raise ValueError("refresh token expired")
+    new_raw, new_hash, expires_at = rotate_refresh_token(
+        current.token_hash, ttl_minutes=ttl_minutes
+    )
+    current.rotated_at = rotation_ts
+    current.revoked_at = rotation_ts
+    current.revoke_reason = "rotated"
+    if current.expires_at is None or current.expires_at > rotation_ts:
+        current.expires_at = rotation_ts
+    # create revocation entry for old hash
+    db.add(
+        RefreshTokenRevocation(
+            token_hash=current.token_hash,
+            revoked_at=rotation_ts,
+            reason="rotated",
+        )
+    )
+    new_row = RefreshToken(
+        session=current.session,
+        token_hash=new_hash,
+        expires_at=expires_at,
+    )
+    db.add(new_row)
+    await db.flush()
+    return new_raw, new_row
+
+
+__all__ = ["issue_session_and_refresh", "rotate_session_refresh"]

svc_infra/security/signed_cookies.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import base64
+import hmac
+import json
+import time
+from hashlib import sha256
+from typing import Any, Dict, List, Optional, Tuple
+
+
+def _b64e(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
+
+
+def _b64d(s: str) -> bytes:
+    pad = "=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode((s + pad).encode())
+
+
+def _sign(data: bytes, key: bytes) -> str:
+    return _b64e(hmac.new(key, data, sha256).digest())
+
+
+def _now() -> int:
+    return int(time.time())
+
+
+def sign_cookie(
+    payload: Dict[str, Any],
+    *,
+    key: str,
+    expires_in: Optional[int] = None,
+    path: Optional[str] = None,
+    domain: Optional[str] = None,
+) -> str:
+    """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}"
+
+
+def verify_cookie(
+    value: str,
+    *,
+    key: str,
+    old_keys: Optional[List[str]] = None,
+    expected_path: Optional[str] = None,
+    expected_domain: Optional[str] = None,
+) -> Tuple[bool, Optional[Dict[str, Any]]]:
+    """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
+    body_b64, sig = value.split(".", 1)
+    try:
+        data = _b64d(body_b64)
+        expected = _sign(data, key.encode())
+        if not hmac.compare_digest(sig, expected):
+            # try old keys
+            for k in old_keys or []:
+                if hmac.compare_digest(sig, _sign(data, k.encode())):
+                    break
+            else:
+                return False, None
+        payload = json.loads(data.decode())
+        # 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
+
+
+__all__ = ["sign_cookie", "verify_cookie"]

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",
+]