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

svc_infra/security/add.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from typing import Iterable, 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

@@ -0,0 +1,212 @@
+"""Audit log append & chain verification utilities.
+
+Provides helpers to append a new AuditLog entry maintaining a hash-chain
+integrity model and to verify an existing sequence for tampering.
+
+Design notes:
+ - Each event stores prev_hash (previous event's hash or 64 zeros for genesis).
+ - Hash = sha256(prev_hash + canonical_json_payload).
+ - Verification recomputes expected hash for each event and compares.
+ - If a middle event is altered, that event and all subsequent events will
+   fail verification (because their prev_hash links break transitively).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, List, Optional, Protocol, Sequence, Tuple
+
+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[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(timezone.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,
+    event_type: str,
+    resource_ref: Optional[str] = None,
+    metadata: dict | None = None,
+    ts: Optional[datetime] = None,
+    prev_event: Optional[AuditLog] = None,
+) -> AuditLog:
+    """Append an audit event returning the persisted row.
+
+    If prev_event is not supplied, it attempts to fetch the latest event for
+    the tenant (or global chain when tenant_id is None).
+    """
+    metadata = metadata or {}
+    ts = ts or datetime.now(timezone.utc)
+
+    prev_hash: Optional[str] = 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
+        try:
+            stmt = (
+                select(AuditLog)
+                .where(AuditLog.tenant_id == tenant_id)
+                .order_by(AuditLog.id.desc())
+                .limit(1)
+            )
+            result = await db.execute(stmt)
+            prev = result.scalars().first()
+            if prev:
+                prev_hash = prev.hash
+        except Exception:  # pragma: no cover - defensive for minimal fakes
+            pass
+
+    new_hash = compute_audit_hash(
+        prev_hash,
+        ts=ts,
+        actor_id=actor_id,
+        tenant_id=tenant_id,
+        event_type=event_type,
+        resource_ref=resource_ref,
+        metadata=metadata,
+    )
+
+    row = AuditLog(
+        ts=ts,
+        actor_id=actor_id,
+        tenant_id=tenant_id,
+        event_type=event_type,
+        resource_ref=resource_ref,
+        event_metadata=metadata,
+        prev_hash=prev_hash or "0" * 64,
+        hash=new_hash,
+    )
+    if hasattr(db, "add"):
+        try:
+            db.add(row)
+        except Exception:  # pragma: no cover - minimal shim safety
+            pass
+        if hasattr(db, "flush"):
+            try:
+                await db.flush()
+            except Exception:  # pragma: no cover
+                pass
+    return row
+
+
+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] = []
+    prev_hash = "0" * 64
+    for idx, ev in enumerate(events):
+        expected = compute_audit_hash(
+            prev_hash if ev.prev_hash == prev_hash else ev.prev_hash,
+            ts=ev.ts,
+            actor_id=ev.actor_id,
+            tenant_id=ev.tenant_id,
+            event_type=ev.event_type,
+            resource_ref=ev.resource_ref,
+            metadata=ev.event_metadata,
+        )
+        # prev_hash stored should equal previous event hash (or zeros for genesis)
+        if (idx == 0 and ev.prev_hash != "0" * 64) or (
+            idx > 0 and ev.prev_hash != events[idx - 1].hash
+        ):
+            broken.append(idx)
+        if ev.hash != expected:
+            broken.append(idx)
+        prev_hash = ev.hash
+    ok = not broken
+    return ok, sorted(set(broken))
+
+
+__all__ = [
+    "append_audit_event",
+    "verify_audit_chain",
+    "AuditEvent",
+    "AuditLogStore",
+    "InMemoryAuditLogStore",
+]

svc_infra/security/audit_service.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional, Sequence, Tuple
+
+try:  # optional SQLAlchemy import for environments without SA
+    from sqlalchemy import select
+except Exception:  # pragma: no cover
+    select = None  # type: ignore[assignment]
+
+from .audit import append_audit_event, verify_audit_chain
+from .models import AuditLog
+
+
+async def append_event(
+    db: Any,
+    *,
+    actor_id=None,
+    tenant_id: Optional[str] = None,
+    event_type: str,
+    resource_ref: Optional[str] = None,
+    metadata: dict | None = None,
+    prev_event: Optional[AuditLog] = None,
+) -> AuditLog:
+    """Append an AuditLog event using the shared append utility.
+
+    If prev_event is not provided, attempts to look up the last event for the tenant.
+    """
+    return await append_audit_event(
+        db,
+        actor_id=actor_id,
+        tenant_id=tenant_id,
+        event_type=event_type,
+        resource_ref=resource_ref,
+        metadata=metadata,
+        prev_event=prev_event,
+    )
+
+
+async def verify_chain_for_tenant(
+    db: Any, *, tenant_id: Optional[str] = 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,
+    to simplify unit tests with fake DBs.
+    """
+    events: Sequence[AuditLog] = []
+    if select is not None and hasattr(db, "execute"):
+        try:
+            stmt = select(AuditLog)
+            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)
+            events = list(result.scalars().all())
+        except Exception:  # pragma: no cover
+            events = []
+    elif hasattr(db, "added"):
+        try:
+            pool = getattr(db, "added")
+            # Preserve insertion order for in-memory fake DBs where primary keys may be None
+            events = [
+                e
+                for e in pool
+                if isinstance(e, AuditLog)
+                and (tenant_id is None or e.tenant_id == tenant_id)
+            ]
+        except Exception:  # pragma: no cover
+            events = []
+
+    return verify_audit_chain(list(events))
+
+
+__all__ = ["append_event", "verify_chain_for_tenant"]

svc_infra/security/headers.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+SECURE_DEFAULTS = {
+    "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload",
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "Referrer-Policy": "strict-origin-when-cross-origin",
+    "X-XSS-Protection": "0",
+    # 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'"
+    ),
+}
+
+
+class SecurityHeadersMiddleware:
+    def __init__(self, app, overrides: dict[str, str] | None = None):
+        self.app = app
+        self.overrides = overrides or {}
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        async def _send(message):
+            if message.get("type") == "http.response.start":
+                headers = message.setdefault("headers", [])
+                existing = {k.decode(): v.decode() for k, v in headers}
+                merged = {**SECURE_DEFAULTS, **existing, **self.overrides}
+                # rebuild headers list
+                new_headers = []
+                for k, v in merged.items():
+                    new_headers.append((k.encode(), v.encode()))
+                message["headers"] = new_headers
+            await send(message)
+
+        await self.app(scope, receive, _send)
+
+
+__all__ = ["SecurityHeadersMiddleware", "SECURE_DEFAULTS"]

svc_infra/security/hibp.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import hashlib
+import logging
+import time
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from svc_infra.http import new_httpx_client
+
+logger = logging.getLogger(__name__)
+
+
+def sha1_hex(data: str) -> str:
+    return hashlib.sha1(data.encode("utf-8")).hexdigest().upper()
+
+
+@dataclass
+class CacheEntry:
+    body: str
+    expires_at: float
+
+
+class HIBPClient:
+    """Minimal HaveIBeenPwned range API client with simple in-memory cache.
+
+    - Uses k-anonymity range query: send first 5 chars of SHA1 hash, receive suffix list.
+    - Caches prefix responses for TTL to avoid repeated network calls.
+    - Synchronous implementation to allow use in sync validators.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str = "https://api.pwnedpasswords.com",
+        ttl_seconds: int = 3600,
+        timeout: float = 5.0,
+        user_agent: str = "svc-infra/hibp",
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.ttl_seconds = ttl_seconds
+        self.timeout = timeout
+        self.user_agent = user_agent
+        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) -> Optional[str]:
+        now = time.time()
+        ent = self._cache.get(prefix)
+        if ent and ent.expires_at > now:
+            return ent.body
+        return None
+
+    def _set_cache(self, prefix: str, body: str) -> None:
+        self._cache[prefix] = CacheEntry(
+            body=body, expires_at=time.time() + self.ttl_seconds
+        )
+
+    def range_query(self, prefix: str) -> str:
+        cached = self._get_cached(prefix)
+        if cached is not None:
+            return cached
+        url = f"{self.base_url}/range/{prefix}"
+        resp = self._http.get(url)
+        resp.raise_for_status()
+        body = resp.text
+        self._set_cache(prefix, body)
+        return body
+
+    def is_breached(self, password: str) -> bool:
+        full = sha1_hex(password)
+        prefix, suffix = full[:5], full[5:]
+        try:
+            body = self.range_query(prefix)
+        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():
+            # Lines formatted as "SUFFIX:COUNT"
+            if not line:
+                continue
+            parts = line.split(":")
+            if len(parts) != 2:
+                continue
+            sfx = parts[0].strip().upper()
+            if sfx == suffix:
+                # Count > 0 implies breached
+                try:
+                    return int(parts[1].strip()) > 0
+                except ValueError:
+                    return True
+        return False
+
+
+__all__ = ["HIBPClient", "sha1_hex"]