svc-infra 0.1.562__py3-none-any.whl → 0.1.654__py3-none-any.whl

svc_infra/security/audit.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+"""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 datetime import datetime, timezone
+from typing import Any, List, Optional, 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
+    select = None  # type: ignore
+
+from svc_infra.security.models import AuditLog, compute_audit_hash
+
+
+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)  # type: ignore[attr-defined]
+            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)  # type: ignore[attr-defined]
+        except Exception:  # pragma: no cover - minimal shim safety
+            pass
+        if hasattr(db, "flush"):
+            try:
+                await db.flush()  # type: ignore[attr-defined]
+            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"]

svc_infra/security/audit_service.py

@@ -0,0 +1,73 @@
+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
+
+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)  # type: ignore[attr-defined]
+            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,95 @@
+from __future__ import annotations
+
+import hashlib
+import time
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from svc_infra.http import new_httpx_client
+
+
+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:
+            # Fail-open: if HIBP unavailable, do not block users.
+            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"]

svc_infra/security/jwt_rotation.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Iterable, List, Optional, Union
+
+import jwt as pyjwt
+from fastapi_users.authentication.strategy.jwt import JWTStrategy
+
+
+class RotatingJWTStrategy(JWTStrategy):
+    """JWTStrategy that can verify tokens against multiple secrets.
+
+    Signing uses the primary secret (as in base class). Verification accepts any of
+    the provided secrets: [primary] + old_secrets.
+    """
+
+    def __init__(
+        self,
+        *,
+        secret: str,
+        lifetime_seconds: int,
+        old_secrets: Optional[Iterable[str]] = None,
+        token_audience: Optional[Union[str, List[str]]] = None,
+    ):
+        super().__init__(
+            secret=secret, lifetime_seconds=lifetime_seconds, token_audience=token_audience
+        )
+        self._verify_secrets: List[str] = [secret] + list(old_secrets or [])
+
+    async def read_token(self, token: str, audience: Optional[str] = None):  # type: ignore[override]
+        # Try with current strategy's configured secret first
+        eff_aud = audience or self.token_audience
+        try:
+            return await super().read_token(token, audience=eff_aud)
+        except Exception:
+            pass
+        # Try older secrets
+        for s in self._verify_secrets[1:]:
+            try:
+                data = pyjwt.decode(
+                    token,
+                    s,
+                    algorithms=["HS256"],
+                    audience=eff_aud,
+                )
+                if data is not None:
+                    return data
+            except Exception:
+                pass
+        # If none of the secrets validated the token, raise a generic error
+        raise ValueError("Invalid token for all configured secrets")
+
+
+__all__ = ["RotatingJWTStrategy"]

svc_infra/security/lockout.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional, Sequence
+
+try:
+    from sqlalchemy import select
+    from sqlalchemy.ext.asyncio import AsyncSession
+except Exception:  # pragma: no cover - optional import for type hints
+    AsyncSession = Any  # type: ignore[misc]
+    select = None  # type: ignore
+
+from svc_infra.security.models import FailedAuthAttempt
+
+
+@dataclass
+class LockoutConfig:
+    threshold: int = 5  # failures before cooldown starts
+    window_minutes: int = 15  # look-back window for counting failures
+    base_cooldown_seconds: int = 30  # initial cooldown once threshold reached
+    max_cooldown_seconds: int = 3600  # cap exponential growth at 1 hour
+
+
+@dataclass
+class LockoutStatus:
+    locked: bool
+    next_allowed_at: Optional[datetime]
+    failure_count: int
+
+
+# ---------------- Pure calculation -----------------
+
+
+def compute_lockout(
+    fail_count: int, *, cfg: LockoutConfig, now: Optional[datetime] = None
+) -> LockoutStatus:
+    now = now or datetime.now(timezone.utc)
+    if fail_count < cfg.threshold:
+        return LockoutStatus(False, None, fail_count)
+    # cooldown factor exponent = fail_count - threshold
+    exponent = fail_count - cfg.threshold
+    cooldown = cfg.base_cooldown_seconds * (2**exponent)
+    if cooldown > cfg.max_cooldown_seconds:
+        cooldown = cfg.max_cooldown_seconds
+    return LockoutStatus(True, now + timedelta(seconds=cooldown), fail_count)
+
+
+# ---------------- Persistence helpers (async) ---------------
+
+
+async def record_attempt(
+    session: AsyncSession,
+    *,
+    user_id: Optional[uuid.UUID],
+    ip_hash: Optional[str],
+    success: bool,
+) -> None:
+    attempt = FailedAuthAttempt(user_id=user_id, ip_hash=ip_hash, success=success)
+    session.add(attempt)
+    await session.flush()
+
+
+async def get_lockout_status(
+    session: AsyncSession,
+    *,
+    user_id: Optional[uuid.UUID],
+    ip_hash: Optional[str],
+    cfg: Optional[LockoutConfig] = None,
+) -> LockoutStatus:
+    cfg = cfg or LockoutConfig()
+    now = datetime.now(timezone.utc)
+    window_start = now - timedelta(minutes=cfg.window_minutes)
+
+    q = select(FailedAuthAttempt).where(
+        FailedAuthAttempt.ts >= window_start,
+        FailedAuthAttempt.success == False,  # noqa: E712
+    )
+    if user_id:
+        q = q.where(FailedAuthAttempt.user_id == user_id)
+    if ip_hash:
+        q = q.where(FailedAuthAttempt.ip_hash == ip_hash)
+
+    rows: Sequence[FailedAuthAttempt] = (await session.execute(q)).scalars().all()
+    fail_count = len(rows)
+    return compute_lockout(fail_count, cfg=cfg, now=now)
+
+
+__all__ = [
+    "LockoutConfig",
+    "LockoutStatus",
+    "compute_lockout",
+    "record_attempt",
+    "get_lockout_status",
+]