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

svc_infra/security/__init__.py

@@ -0,0 +1,167 @@
+"""Security module providing authentication, authorization, and protection utilities.
+
+This module provides comprehensive security primitives:
+
+- **Middleware**: Security headers (CSP, HSTS, etc.) and CORS configuration
+- **Lockout**: Account lockout with exponential backoff for brute force protection
+- **Passwords**: Password policy validation with HIBP breach checking
+- **Sessions**: Session and refresh token management
+- **Audit**: Hash-chain audit logging for tamper detection
+- **JWT Rotation**: Seamless JWT key rotation support
+- **Permissions**: RBAC and ABAC authorization helpers
+- **Signed Cookies**: Cryptographically signed cookies with expiry
+
+Example:
+    from fastapi import FastAPI
+    from svc_infra.security import add_security
+
+    app = FastAPI()
+
+    # Add security headers and CORS
+    add_security(app, cors_origins=["https://myapp.com"])
+
+    # Use password validation
+    from svc_infra.security import validate_password, PasswordPolicy
+
+    policy = PasswordPolicy(min_length=12, require_symbol=True)
+    validate_password("MyStr0ng!Pass", policy)
+
+    # Use lockout protection
+    from svc_infra.security import get_lockout_status, LockoutConfig
+
+    status = await get_lockout_status(session, user_id=user.id, ip_hash=ip_hash)
+    if status.locked:
+        raise HTTPException(429, "Too many attempts")
+
+Environment Variables:
+    CORS_ALLOW_ORIGINS: Comma-separated list of allowed origins
+    CORS_ALLOW_CREDENTIALS: Allow credentials in CORS (true/false)
+    CORS_ALLOW_METHODS: Comma-separated list of allowed methods
+    CORS_ALLOW_HEADERS: Comma-separated list of allowed headers
+
+See Also:
+    - docs/security.md for detailed documentation
+    - svc_infra.api.fastapi.auth for authentication routes
+"""
+
+from __future__ import annotations
+
+# FastAPI integration
+from .add import add_security
+
+# Audit logging
+from .audit import (
+    AuditEvent,
+    AuditLogStore,
+    InMemoryAuditLogStore,
+    append_audit_event,
+    verify_audit_chain,
+)
+from .audit_service import append_event, verify_chain_for_tenant
+
+# Security headers middleware
+from .headers import SECURE_DEFAULTS, SecurityHeadersMiddleware
+
+# HIBP breach checking
+from .hibp import HIBPClient
+
+# JWT rotation
+from .jwt_rotation import RotatingJWTStrategy
+
+# Account lockout
+from .lockout import (
+    LockoutConfig,
+    LockoutStatus,
+    compute_lockout,
+    get_lockout_status,
+    record_attempt,
+)
+
+# Models (for type hints and direct use)
+from .models import (
+    AuditLog,
+    AuthSession,
+    FailedAuthAttempt,
+    RefreshToken,
+    RefreshTokenRevocation,
+    compute_audit_hash,
+)
+
+# Password validation
+from .passwords import (
+    PasswordPolicy,
+    PasswordValidationError,
+    configure_breached_checker,
+    validate_password,
+)
+
+# RBAC/ABAC permissions
+from .permissions import (
+    PERMISSION_REGISTRY,
+    RequireABAC,
+    RequireAnyPermission,
+    RequirePermission,
+    enforce_abac,
+    extend_role,
+    get_permissions_for_roles,
+    has_permission,
+    owns_resource,
+    principal_permissions,
+    register_role,
+)
+
+# Signed cookies
+from .signed_cookies import sign_cookie, verify_cookie
+
+__all__ = [
+    # FastAPI integration
+    "add_security",
+    # Headers middleware
+    "SecurityHeadersMiddleware",
+    "SECURE_DEFAULTS",
+    # Lockout
+    "LockoutConfig",
+    "LockoutStatus",
+    "compute_lockout",
+    "record_attempt",
+    "get_lockout_status",
+    # Password validation
+    "PasswordPolicy",
+    "PasswordValidationError",
+    "validate_password",
+    "configure_breached_checker",
+    # HIBP
+    "HIBPClient",
+    # Signed cookies
+    "sign_cookie",
+    "verify_cookie",
+    # Audit logging
+    "AuditLogStore",
+    "AuditEvent",
+    "append_audit_event",
+    "verify_audit_chain",
+    "append_event",
+    "verify_chain_for_tenant",
+    "InMemoryAuditLogStore",
+    # JWT rotation
+    "RotatingJWTStrategy",
+    # Permissions (RBAC/ABAC)
+    "PERMISSION_REGISTRY",
+    "register_role",
+    "extend_role",
+    "get_permissions_for_roles",
+    "principal_permissions",
+    "has_permission",
+    "RequirePermission",
+    "RequireAnyPermission",
+    "RequireABAC",
+    "enforce_abac",
+    "owns_resource",
+    # Models
+    "AuthSession",
+    "RefreshToken",
+    "RefreshTokenRevocation",
+    "FailedAuthAttempt",
+    "AuditLog",
+    "compute_audit_hash",
+]

svc_infra/security/add.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Mapping
+from typing import Literal, cast
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.middleware.sessions import SessionMiddleware
+
+from svc_infra.app.env import require_secret
+from svc_infra.security.headers import SECURE_DEFAULTS, SecurityHeadersMiddleware
+
+DEFAULT_SESSION_SECRET = "dev-only-session-secret-not-for-production"
+
+
+def _parse_bool(value: str | None) -> bool | None:
+    if value is None:
+        return None
+    lowered = value.strip().lower()
+    if lowered in {"1", "true", "yes", "on"}:
+        return True
+    if lowered in {"0", "false", "no", "off"}:
+        return False
+    return None
+
+
+def _normalize_origins(value: Iterable[str] | str | None) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        parts = [p.strip() for p in value.split(",")]
+    else:
+        parts = [str(v).strip() for v in value]
+    return [p for p in parts if p]
+
+
+def _resolve_cors_origins(
+    provided: Iterable[str] | str | None,
+    env: Mapping[str, str],
+) -> list[str]:
+    if provided is not None:
+        return _normalize_origins(provided)
+    return _normalize_origins(env.get("CORS_ALLOW_ORIGINS"))
+
+
+def _resolve_allow_credentials(
+    allow_credentials: bool,
+    env: Mapping[str, str],
+) -> bool:
+    env_value = _parse_bool(env.get("CORS_ALLOW_CREDENTIALS"))
+    if env_value is None:
+        return allow_credentials
+    # Allow explicit overrides via function arguments.
+    if allow_credentials is not True:
+        return allow_credentials
+    return env_value
+
+
+def _configure_cors(
+    app: FastAPI,
+    *,
+    cors_origins: Iterable[str] | str | None,
+    allow_credentials: bool,
+    env: Mapping[str, str],
+) -> None:
+    origins = _resolve_cors_origins(cors_origins, env)
+    if not origins:
+        return
+
+    allow_methods = _normalize_origins(env.get("CORS_ALLOW_METHODS")) or ["*"]
+    allow_headers = _normalize_origins(env.get("CORS_ALLOW_HEADERS")) or ["*"]
+
+    credentials = _resolve_allow_credentials(allow_credentials, env)
+
+    wildcard_origins = "*" in origins
+
+    cors_kwargs: dict[str, object] = {
+        "allow_credentials": credentials,
+        "allow_methods": allow_methods,
+        "allow_headers": allow_headers,
+        "allow_origins": ["*"] if wildcard_origins else origins,
+    }
+    origin_regex = env.get("CORS_ALLOW_ORIGIN_REGEX")
+    if wildcard_origins:
+        cors_kwargs["allow_origin_regex"] = origin_regex or ".*"
+    else:
+        if origin_regex:
+            cors_kwargs["allow_origin_regex"] = origin_regex
+
+    app.add_middleware(CORSMiddleware, **cors_kwargs)  # type: ignore[arg-type]  # CORSMiddleware accepts these kwargs
+
+
+def _configure_security_headers(
+    app: FastAPI,
+    *,
+    overrides: dict[str, str] | None,
+    enable_hsts_preload: bool | None,
+) -> None:
+    merged_overrides = dict(overrides or {})
+    if enable_hsts_preload is not None:
+        current = merged_overrides.get(
+            "Strict-Transport-Security",
+            SECURE_DEFAULTS["Strict-Transport-Security"],
+        )
+        directives = [p.strip() for p in current.split(";") if p.strip()]
+        directives = [d for d in directives if d.lower() != "preload"]
+        if enable_hsts_preload:
+            directives.append("preload")
+        merged_overrides["Strict-Transport-Security"] = "; ".join(directives)
+
+    app.add_middleware(SecurityHeadersMiddleware, overrides=merged_overrides)
+
+
+def _should_add_session_middleware(app: FastAPI) -> bool:
+    return not any(m.cls is SessionMiddleware for m in app.user_middleware)
+
+
+def _configure_session_middleware(
+    app: FastAPI,
+    *,
+    env: Mapping[str, str],
+    install: bool,
+    secret_key: str | None,
+    session_cookie: str,
+    max_age: int,
+    same_site: str,
+    https_only: bool | None,
+) -> None:
+    if not install or not _should_add_session_middleware(app):
+        return
+
+    # Use require_secret to ensure secrets are set in production
+    secret = require_secret(
+        secret_key or env.get("SESSION_SECRET"),
+        "SESSION_SECRET",
+        dev_default=DEFAULT_SESSION_SECRET,
+    )
+    https_env = _parse_bool(env.get("SESSION_COOKIE_SECURE"))
+    effective_https_only = (
+        https_only if https_only is not None else (https_env if https_env is not None else False)
+    )
+    same_site_env = env.get("SESSION_COOKIE_SAMESITE")
+    same_site_raw = same_site_env.strip() if same_site_env else same_site
+    # Validate and narrow to expected Literal type
+    same_site_value: Literal["lax", "strict", "none"] = (
+        "lax"
+        if same_site_raw not in ("lax", "strict", "none")
+        else cast("Literal['lax', 'strict', 'none']", same_site_raw)
+    )
+
+    max_age_env = env.get("SESSION_COOKIE_MAX_AGE_SECONDS")
+    try:
+        max_age_value = int(max_age_env) if max_age_env is not None else max_age
+    except ValueError:
+        max_age_value = max_age
+
+    session_cookie_env = env.get("SESSION_COOKIE_NAME")
+    session_cookie_value = session_cookie_env.strip() if session_cookie_env else session_cookie
+
+    app.add_middleware(
+        SessionMiddleware,
+        secret_key=secret,
+        session_cookie=session_cookie_value,
+        max_age=max_age_value,
+        same_site=same_site_value,
+        https_only=effective_https_only,
+    )
+
+
+def add_security(
+    app: FastAPI,
+    *,
+    cors_origins: Iterable[str] | str | None = None,
+    headers_overrides: dict[str, str] | None = None,
+    allow_credentials: bool = True,
+    env: Mapping[str, str] = os.environ,
+    enable_hsts_preload: bool | None = None,
+    install_session_middleware: bool = False,
+    session_secret_key: str | None = None,
+    session_cookie_name: str = "svc_session",
+    session_cookie_max_age_seconds: int = 4 * 3600,
+    session_cookie_samesite: str = "lax",
+    session_cookie_https_only: bool | None = None,
+) -> None:
+    """Install security middlewares with svc-infra defaults."""
+
+    _configure_security_headers(
+        app,
+        overrides=headers_overrides,
+        enable_hsts_preload=enable_hsts_preload,
+    )
+    _configure_cors(
+        app,
+        cors_origins=cors_origins,
+        allow_credentials=allow_credentials,
+        env=env,
+    )
+    _configure_session_middleware(
+        app,
+        env=env,
+        install=install_session_middleware,
+        secret_key=session_secret_key,
+        session_cookie=session_cookie_name,
+        max_age=session_cookie_max_age_seconds,
+        same_site=session_cookie_samesite,
+        https_only=session_cookie_https_only,
+    )
+
+
+__all__ = [
+    "add_security",
+]

svc_infra/security/audit.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """Audit log append & chain verification utilities.
 
 Provides helpers to append a new AuditLog entry maintaining a hash-chain
@@ -13,29 +11,104 @@ Design notes:
    fail verification (because their prev_hash links break transitively).
 """
 
-from datetime import datetime, timezone
-from typing import Any, List, Optional, Sequence, Tuple
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any, Protocol
 
 try:  # SQLAlchemy may not be present in minimal test context
     from sqlalchemy import select
     from sqlalchemy.ext.asyncio import AsyncSession
 except Exception:  # pragma: no cover
-    AsyncSession = Any  # type: ignore
-    select = None  # type: ignore
+    AsyncSession = Any  # type: ignore[misc,assignment]
+    select = None  # type: ignore[assignment]
 
 from svc_infra.security.models import AuditLog, compute_audit_hash
 
 
+@dataclass(frozen=True)
+class AuditEvent:
+    ts: datetime
+    actor_id: Any
+    tenant_id: str | None
+    event_type: str
+    resource_ref: str | None
+    metadata: dict
+
+
+class AuditLogStore(Protocol):
+    """Minimal interface for storing audit events.
+
+    This is intentionally small so applications can swap in a SQL-backed store.
+    """
+
+    def append(
+        self,
+        *,
+        actor_id: Any = None,
+        tenant_id: str | None = None,
+        event_type: str,
+        resource_ref: str | None = None,
+        metadata: dict | None = None,
+        ts: datetime | None = None,
+    ) -> AuditEvent:
+        pass
+
+    def list(
+        self,
+        *,
+        tenant_id: str | None = None,
+        limit: int | None = None,
+    ) -> list[AuditEvent]:
+        pass
+
+
+class InMemoryAuditLogStore:
+    """In-memory audit event store (useful for tests and prototypes)."""
+
+    def __init__(self):
+        self._events: list[AuditEvent] = []
+
+    def append(
+        self,
+        *,
+        actor_id: Any = None,
+        tenant_id: str | None = None,
+        event_type: str,
+        resource_ref: str | None = None,
+        metadata: dict | None = None,
+        ts: datetime | None = None,
+    ) -> AuditEvent:
+        event = AuditEvent(
+            ts=ts or datetime.now(UTC),
+            actor_id=actor_id,
+            tenant_id=tenant_id,
+            event_type=event_type,
+            resource_ref=resource_ref,
+            metadata=dict(metadata or {}),
+        )
+        self._events.append(event)
+        return event
+
+    def list(self, *, tenant_id: str | None = None, limit: int | None = None) -> list[AuditEvent]:
+        out = [e for e in self._events if tenant_id is None or e.tenant_id == tenant_id]
+        if limit is not None:
+            return out[-int(limit) :]
+        return out
+
+
 async def append_audit_event(
     db: Any,
     *,
     actor_id=None,
-    tenant_id: Optional[str] = None,
+    tenant_id: str | None = None,
     event_type: str,
-    resource_ref: Optional[str] = None,
+    resource_ref: str | None = None,
     metadata: dict | None = None,
-    ts: Optional[datetime] = None,
-    prev_event: Optional[AuditLog] = None,
+    ts: datetime | None = None,
+    prev_event: AuditLog | None = None,
 ) -> AuditLog:
     """Append an audit event returning the persisted row.
 
@@ -43,9 +116,9 @@ async def append_audit_event(
     the tenant (or global chain when tenant_id is None).
     """
     metadata = metadata or {}
-    ts = ts or datetime.now(timezone.utc)
+    ts = ts or datetime.now(UTC)
 
-    prev_hash: Optional[str] = None
+    prev_hash: str | None = None
     if prev_event is not None:
         prev_hash = prev_event.hash
     elif select is not None and hasattr(db, "execute"):  # attempt DB lookup for previous event
@@ -56,7 +129,7 @@ async def append_audit_event(
                 .order_by(AuditLog.id.desc())
                 .limit(1)
             )
-            result = await db.execute(stmt)  # type: ignore[attr-defined]
+            result = await db.execute(stmt)
             prev = result.scalars().first()
             if prev:
                 prev_hash = prev.hash
@@ -85,25 +158,25 @@ async def append_audit_event(
     )
     if hasattr(db, "add"):
         try:
-            db.add(row)  # type: ignore[attr-defined]
+            db.add(row)
         except Exception:  # pragma: no cover - minimal shim safety
             pass
         if hasattr(db, "flush"):
             try:
-                await db.flush()  # type: ignore[attr-defined]
+                await db.flush()
             except Exception:  # pragma: no cover
                 pass
     return row
 
 
-def verify_audit_chain(events: Sequence[AuditLog]) -> Tuple[bool, List[int]]:
+def verify_audit_chain(events: Sequence[AuditLog]) -> tuple[bool, list[int]]:
     """Verify a sequence of audit events.
 
     Returns (ok, broken_indices). If any event's hash doesn't match the recomputed
     expected hash (based on previous event), its index is recorded. All events are
     checked so callers can analyze extent of tampering.
     """
-    broken: List[int] = []
+    broken: list[int] = []
     prev_hash = "0" * 64
     for idx, ev in enumerate(events):
         expected = compute_audit_hash(
@@ -127,4 +200,10 @@ def verify_audit_chain(events: Sequence[AuditLog]) -> Tuple[bool, List[int]]:
     return ok, sorted(set(broken))
 
 
-__all__ = ["append_audit_event", "verify_audit_chain"]
+__all__ = [
+    "append_audit_event",
+    "verify_audit_chain",
+    "AuditEvent",
+    "AuditLogStore",
+    "InMemoryAuditLogStore",
+]

svc_infra/security/audit_service.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
-from typing import Any, List, Optional, Sequence, Tuple
+from collections.abc import Sequence
+from typing import Any
 
 try:  # optional SQLAlchemy import for environments without SA
     from sqlalchemy import select
 except Exception:  # pragma: no cover
-    select = None  # type: ignore
+    select = None  # type: ignore[assignment]
 
 from .audit import append_audit_event, verify_audit_chain
 from .models import AuditLog
@@ -15,11 +16,11 @@ async def append_event(
     db: Any,
     *,
     actor_id=None,
-    tenant_id: Optional[str] = None,
+    tenant_id: str | None = None,
     event_type: str,
-    resource_ref: Optional[str] = None,
+    resource_ref: str | None = None,
     metadata: dict | None = None,
-    prev_event: Optional[AuditLog] = None,
+    prev_event: AuditLog | None = None,
 ) -> AuditLog:
     """Append an AuditLog event using the shared append utility.
 
@@ -37,8 +38,8 @@ async def append_event(
 
 
 async def verify_chain_for_tenant(
-    db: Any, *, tenant_id: Optional[str] = None
-) -> Tuple[bool, List[int]]:
+    db: Any, *, tenant_id: str | None = None
+) -> tuple[bool, list[int]]:
     """Fetch all AuditLog events for a tenant and verify hash-chain integrity.
 
     Falls back to inspecting an in-memory 'added' list when SQLAlchemy is not available,
@@ -51,13 +52,13 @@ async def verify_chain_for_tenant(
             if tenant_id is not None:
                 stmt = stmt.where(AuditLog.tenant_id == tenant_id)
             stmt = stmt.order_by(AuditLog.id.asc())
-            result = await db.execute(stmt)  # type: ignore[attr-defined]
+            result = await db.execute(stmt)
             events = list(result.scalars().all())
         except Exception:  # pragma: no cover
             events = []
     elif hasattr(db, "added"):
         try:
-            pool = getattr(db, "added")
+            pool = db.added
             # Preserve insertion order for in-memory fake DBs where primary keys may be None
             events = [
                 e

svc_infra/security/headers.py

@@ -6,8 +6,21 @@ SECURE_DEFAULTS = {
     "X-Frame-Options": "DENY",
     "Referrer-Policy": "strict-origin-when-cross-origin",
     "X-XSS-Protection": "0",
-    # CSP kept minimal; allow config override
-    "Content-Security-Policy": "default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'",
+    # CSP with practical defaults - allows inline styles/scripts and data URIs for images
+    # Also allows cdn.jsdelivr.net for FastAPI docs (Swagger UI, ReDoc)
+    # Still secure: blocks arbitrary external scripts, prevents framing, restricts form actions
+    # Override via headers_overrides in add_security() for stricter or custom policies
+    "Content-Security-Policy": (
+        "default-src 'self'; "
+        "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
+        "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
+        "img-src 'self' data: https:; "
+        "connect-src 'self'; "
+        "font-src 'self' https://cdn.jsdelivr.net; "
+        "frame-ancestors 'none'; "
+        "base-uri 'self'; "
+        "form-action 'self'"
+    ),
 }
 
 

svc_infra/security/hibp.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 import hashlib
+import logging
 import time
 from dataclasses import dataclass
-from typing import Dict, Optional
 
-import httpx
+from svc_infra.http import new_httpx_client
+
+logger = logging.getLogger(__name__)
 
 
 def sha1_hex(data: str) -> str:
@@ -38,10 +40,14 @@ class HIBPClient:
         self.ttl_seconds = ttl_seconds
         self.timeout = timeout
         self.user_agent = user_agent
-        self._cache: Dict[str, CacheEntry] = {}
-        self._http = httpx.Client(timeout=self.timeout, headers={"User-Agent": self.user_agent})
-
-    def _get_cached(self, prefix: str) -> Optional[str]:
+        self._cache: dict[str, CacheEntry] = {}
+        # Use central factory for consistent defaults; retain explicit timeout override
+        self._http = new_httpx_client(
+            timeout_seconds=self.timeout,
+            headers={"User-Agent": self.user_agent},
+        )
+
+    def _get_cached(self, prefix: str) -> str | None:
         now = time.time()
         ent = self._cache.get(prefix)
         if ent and ent.expires_at > now:
@@ -67,8 +73,9 @@ class HIBPClient:
         prefix, suffix = full[:5], full[5:]
         try:
             body = self.range_query(prefix)
-        except Exception:
+        except Exception as e:
             # Fail-open: if HIBP unavailable, do not block users.
+            logger.warning("HIBP password check failed (fail-open): %s", e)
             return False
 
         for line in body.splitlines():