austial-security 0.2.0__tar.gz

austial_security-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.db
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store

austial_security-0.2.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.5
+Name: austial-security
+Version: 0.2.0
+Summary: Security primitives -- secure headers, rate limiting, idempotency, CSRF, PII redaction, envelope encryption.
+Requires-Python: >=3.11
+Requires-Dist: austial-common
+Requires-Dist: austial-core
+Requires-Dist: cryptography>=43.0.0

austial_security-0.2.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "austial-security"
+dynamic = ["version"]
+description = "Security primitives -- secure headers, rate limiting, idempotency, CSRF, PII redaction, envelope encryption."
+requires-python = ">=3.11"
+dependencies = [
+    "austial-common",
+    "austial-core",
+    "cryptography>=43.0.0",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/austial"]
+
+[tool.uv.sources]
+austial-common = { workspace = true }
+austial-core = { workspace = true }
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+root = "../.."

austial_security-0.2.0/src/austial/security/__init__.py

@@ -0,0 +1,73 @@
+"""``austial.security`` -- baseline security primitives for Austial apps.
+
+Ships:
+
+- ``SecurityModule.for_root(config)`` -- DI wiring.
+- ``SecureHeadersMiddleware`` -- CSP, HSTS, ``X-Content-Type-Options``,
+  ``Referrer-Policy``, ``X-Frame-Options``, ``Permissions-Policy``.
+- ``RateLimitGuard`` + ``@RateLimit(limit, period_seconds)`` -- fixed-window
+  rate limiting keyed on ``(client_ip, route)`` by default, with a pluggable
+  ``RateLimitStore`` (in-memory reference impl included).
+- ``IdempotencyKeyGuard`` -- ``Idempotency-Key`` replay/conflict handling for
+  ``POST``/``PUT``/``PATCH``/``DELETE``, backed by a pluggable
+  ``IdempotencyStore``.
+- ``CsrfInterceptor`` -- double-submit cookie CSRF check for cookie-authenticated
+  flows; skipped when a bearer token is present.
+- ``PIIRedactor`` -- masks email, phone, PAN, Aadhaar, passport, IBAN and
+  Luhn-verified card numbers.
+- ``EnvelopeEncryptor`` -- AES-256-GCM app-level column encryption with an
+  embedded KEK version.
+
+Aligned with OWASP ASVS V5 (validation), V6 (secrets/crypto), V8 (data protection),
+V9 (transport), and OWASP API Top-10 API4 (unrestricted resource consumption),
+API6 (unrestricted access to business flows), API8 (security misconfiguration).
+"""
+
+from austial.security.config import SecurityConfig
+from austial.security.csrf_interceptor import (
+    CSRF_COOKIE_NAME,
+    CSRF_HEADER_NAME,
+    CsrfInterceptor,
+)
+from austial.security.decorators import RATE_LIMIT_METADATA, RateLimit, get_rate_limit
+from austial.security.envelope_encryptor import EnvelopeEncryptor
+from austial.security.errors import (
+    EncryptionKeyError,
+    IdempotencyConflictError,
+    RateLimitExceededError,
+)
+from austial.security.idempotency_guard import IdempotencyKeyGuard
+from austial.security.idempotency_store import (
+    IdempotencyRecord,
+    IdempotencyStore,
+    InMemoryIdempotencyStore,
+)
+from austial.security.pii_redactor import PIIRedactor
+from austial.security.rate_limit_guard import RateLimitGuard
+from austial.security.rate_limit_store import InMemoryRateLimitStore, RateLimitStore
+from austial.security.secure_headers_middleware import SecureHeadersMiddleware
+from austial.security.security_module import SecurityModule
+
+__all__ = [
+    "CSRF_COOKIE_NAME",
+    "CSRF_HEADER_NAME",
+    "CsrfInterceptor",
+    "EncryptionKeyError",
+    "EnvelopeEncryptor",
+    "IdempotencyConflictError",
+    "IdempotencyKeyGuard",
+    "IdempotencyRecord",
+    "IdempotencyStore",
+    "InMemoryIdempotencyStore",
+    "InMemoryRateLimitStore",
+    "PIIRedactor",
+    "RATE_LIMIT_METADATA",
+    "RateLimit",
+    "RateLimitExceededError",
+    "RateLimitGuard",
+    "RateLimitStore",
+    "SecureHeadersMiddleware",
+    "SecurityConfig",
+    "SecurityModule",
+    "get_rate_limit",
+]

austial_security-0.2.0/src/austial/security/config.py

@@ -0,0 +1,31 @@
+"""``SecurityConfig`` -- configuration passed to ``SecurityModule.for_root(...)``.
+
+Held in its own module so ``EnvelopeEncryptor``/``RateLimitGuard``/etc. can read
+individual fields without importing the module wiring.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class SecurityConfig:
+    """Every field has a safe default; only ``encryption_keys`` + ``active_encryption_key``
+    must be supplied for the ``EnvelopeEncryptor`` to be usable."""
+
+    csp: str = "default-src 'self'; frame-ancestors 'none'; upgrade-insecure-requests"
+    hsts_max_age: int = 31536000
+    permissions_policy: str = "geolocation=(), microphone=(), camera=()"
+    encryption_keys: dict[str, bytes] = field(default_factory=dict)
+    active_encryption_key: str | None = None
+    default_rate_limit: tuple[int, int] = (60, 60)
+    idempotency_ttl_seconds: int = 86400
+    trusted_proxy_hops: int = 0
+    """How many reverse proxies you operate in front of the app, for client-IP resolution.
+
+    ``0`` (default): ``X-Forwarded-For`` is ignored and the socket peer is the client -- correct when
+    the app is exposed directly, and safe by default because the header is client-controlled. ``n > 0``:
+    the client is the ``n``-th entry counted from the *right* of ``X-Forwarded-For`` (each trusted proxy
+    appends the address it received the request from, so the right-most ``n`` entries are trustworthy
+    and everything to their left is attacker-controlled)."""

austial_security-0.2.0/src/austial/security/csrf_interceptor.py

@@ -0,0 +1,94 @@
+"""``CsrfInterceptor`` -- double-submit cookie CSRF check for cookie-authenticated
+flows.
+
+The pattern:
+
+- The server sets a random token in the ``csrf_token`` cookie at session start.
+- Every state-changing request must echo the same token back in the
+  ``X-CSRF-Token`` header.
+- The interceptor compares the two values in constant time and rejects on any
+  mismatch.
+
+Bearer-token flows are exempt: an ``Authorization: Bearer ...`` header cannot
+be attached cross-origin without the caller possessing the credential outright,
+which defeats the CSRF threat model. Read-only methods (``GET``/``HEAD``/
+``OPTIONS``) are exempt as well; they should not carry side effects.
+
+Raises ``ForbiddenException`` (HTTP 403) on a mismatch so a proxy or WAF can
+distinguish CSRF failures from generic 401s.
+"""
+
+from __future__ import annotations
+
+import hmac
+from typing import Any
+
+from austial.common.exceptions import ForbiddenException
+from austial.common.guards.base import ExecutionContext
+from austial.common.interceptors.base import CallHandler, NestInterceptor
+
+CSRF_HEADER_NAME = "X-CSRF-Token"
+CSRF_COOKIE_NAME = "csrf_token"
+_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+
+class CsrfInterceptor(NestInterceptor):
+    """Enforce the double-submit cookie invariant before the handler runs.
+
+    Product code sets the cookie itself (usually at login); this interceptor is
+    the read-side check."""
+
+    def __init__(
+        self,
+        *,
+        header_name: str = CSRF_HEADER_NAME,
+        cookie_name: str = CSRF_COOKIE_NAME,
+    ) -> None:
+        self._header = header_name
+        self._cookie = cookie_name
+
+    async def intercept(self, context: ExecutionContext, next: CallHandler) -> Any:
+        request = context.get_request()
+        method = getattr(request, "method", "GET").upper()
+
+        if method in _SAFE_METHODS:
+            return await next.handle()
+
+        # Bearer-authenticated request => skip CSRF (not the relevant threat model).
+        auth = _header(getattr(request, "headers", {}) or {}, "Authorization")
+        if auth and auth.lower().startswith("bearer "):
+            return await next.handle()
+
+        header_token = _header(getattr(request, "headers", {}) or {}, self._header)
+        cookie_token = _cookie(request, self._cookie)
+
+        if not header_token or not cookie_token:
+            raise ForbiddenException("CSRF token missing")
+
+        if not hmac.compare_digest(header_token, cookie_token):
+            raise ForbiddenException("CSRF token mismatch")
+
+        return await next.handle()
+
+
+def _header(headers: Any, name: str) -> str | None:
+    try:
+        value = headers.get(name)
+    except AttributeError:
+        return None
+    if value:
+        return value
+    try:
+        return headers.get(name.lower())
+    except AttributeError:
+        return None
+
+
+def _cookie(request: Any, name: str) -> str | None:
+    cookies = getattr(request, "cookies", None)
+    if cookies is None:
+        return None
+    try:
+        return cookies.get(name)
+    except AttributeError:
+        return None

austial_security-0.2.0/src/austial/security/decorators.py

@@ -0,0 +1,40 @@
+"""Decorators: ``@RateLimit(limit, period_seconds)``.
+
+Attaches per-route metadata that ``RateLimitGuard`` reads to override
+``SecurityConfig.default_rate_limit`` for that handler.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from austial.core.metadata import get_metadata, set_metadata
+
+RATE_LIMIT_METADATA = "austial:security:rate_limit"
+
+
+def RateLimit(limit: int, period_seconds: int) -> Callable:  # noqa: N802 - decorator naming
+    """Override the rate-limit budget for a single handler or controller.
+
+    ``limit`` is the maximum number of requests inside a fixed window of
+    ``period_seconds`` seconds. Raises ``ValueError`` at decoration time on a
+    non-positive value so misconfiguration surfaces at import."""
+
+    if limit <= 0:
+        raise ValueError("RateLimit limit must be positive")
+    if period_seconds <= 0:
+        raise ValueError("RateLimit period_seconds must be positive")
+
+    def decorator(target):
+        set_metadata(RATE_LIMIT_METADATA, (limit, period_seconds))(target)
+        return target
+
+    return decorator
+
+
+def get_rate_limit(target, default: tuple[int, int]) -> tuple[int, int]:
+    """Return the rate-limit tuple attached to ``target`` (or ``default``)."""
+    value = get_metadata(RATE_LIMIT_METADATA, target, None)
+    if value is None:
+        return default
+    return value

austial_security-0.2.0/src/austial/security/envelope_encryptor.py

@@ -0,0 +1,93 @@
+"""``EnvelopeEncryptor`` -- app-level column encryption with AES-256-GCM.
+
+The wire format is a URL-safe base64 encoding of::
+
+    b"v1:<key_version>:" || nonce (12 bytes) || ciphertext || tag (16 bytes)
+
+The key version prefix lets a rotation swap the active KEK without a bulk
+re-encrypt: old rows keep decrypting with their embedded version, new writes
+use ``SecurityConfig.active_encryption_key``.
+
+Callers pass a ``dict[str, bytes]`` of ``version -> 32-byte key``. A key that
+is not exactly 32 bytes is rejected at construction (``EncryptionKeyError``).
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from austial.common.decorators.injectable import Injectable
+from austial.security.errors import EncryptionKeyError
+
+_VERSION_PREFIX = b"v1:"
+
+
+@Injectable()
+class EnvelopeEncryptor:
+    """Symmetric app-level encryption for individual column values.
+
+    ``encrypt`` writes with ``active_key``. ``decrypt`` reads whichever version
+    the ciphertext advertises so historical rows stay readable across a key
+    rotation."""
+
+    def __init__(self, keys: dict[str, bytes], active_key: str | None) -> None:
+        if not keys:
+            raise EncryptionKeyError("At least one encryption key must be supplied")
+        if active_key is None:
+            raise EncryptionKeyError("active_encryption_key must be supplied")
+        if active_key not in keys:
+            raise EncryptionKeyError(f"active_encryption_key '{active_key}' is not present in keys")
+        for version, material in keys.items():
+            if not isinstance(material, (bytes, bytearray)) or len(material) != 32:
+                raise EncryptionKeyError(f"Key '{version}' must be exactly 32 bytes (AES-256)")
+        self._keys: dict[str, bytes] = {v: bytes(m) for v, m in keys.items()}
+        self._active_key = active_key
+
+    def encrypt(self, plaintext: str) -> str:
+        if not isinstance(plaintext, str):
+            raise TypeError("plaintext must be str")
+        aesgcm = AESGCM(self._keys[self._active_key])
+        nonce = os.urandom(12)
+        ciphertext_with_tag = aesgcm.encrypt(nonce, plaintext.encode("utf-8"), None)
+        header = _VERSION_PREFIX + self._active_key.encode("ascii") + b":"
+        blob = header + nonce + ciphertext_with_tag
+        return base64.urlsafe_b64encode(blob).decode("ascii")
+
+    def decrypt(self, ciphertext: str) -> str:
+        try:
+            blob = base64.urlsafe_b64decode(ciphertext.encode("ascii"))
+        except (ValueError, TypeError) as exc:
+            raise EncryptionKeyError("Ciphertext is not valid base64") from exc
+
+        if not blob.startswith(_VERSION_PREFIX):
+            raise EncryptionKeyError("Ciphertext is missing the version prefix")
+        remainder = blob[len(_VERSION_PREFIX) :]
+        try:
+            version_end = remainder.index(b":")
+        except ValueError as exc:
+            raise EncryptionKeyError("Ciphertext version delimiter not found") from exc
+
+        version = remainder[:version_end].decode("ascii", errors="replace")
+        payload = remainder[version_end + 1 :]
+        if len(payload) < 12 + 16:  # nonce + minimum-sized tag
+            raise EncryptionKeyError("Ciphertext payload is truncated")
+
+        key = self._keys.get(version)
+        if key is None:
+            raise EncryptionKeyError(f"Unknown encryption key version '{version}'")
+
+        nonce, ciphertext_bytes = payload[:12], payload[12:]
+        aesgcm = AESGCM(key)
+        try:
+            plaintext = aesgcm.decrypt(nonce, ciphertext_bytes, None)
+        except InvalidTag as exc:
+            raise EncryptionKeyError("Ciphertext failed authentication") from exc
+        return plaintext.decode("utf-8")
+
+    @property
+    def active_key(self) -> str:
+        return self._active_key

austial_security-0.2.0/src/austial/security/errors.py

@@ -0,0 +1,31 @@
+"""Security-specific exceptions.
+
+Extend Austial's typed HTTP exceptions so ``AllExceptionsFilter`` maps them to
+the correct status codes without a translation layer.
+"""
+
+from __future__ import annotations
+
+from austial.common.exceptions import ConflictException, TooManyRequestsException
+
+
+class RateLimitExceededError(TooManyRequestsException):
+    """Raised by ``RateLimitGuard`` when a caller exceeds their allowance
+    inside the current fixed window (HTTP 429)."""
+
+    def __init__(self, message: str = "Rate limit exceeded", *, retry_after: int | None = None):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class IdempotencyConflictError(ConflictException):
+    """Raised by ``IdempotencyKeyGuard`` when the same ``Idempotency-Key`` is
+    replayed with a different request body inside the TTL (HTTP 409)."""
+
+    def __init__(self, message: str = "Idempotency key reused with different request"):
+        super().__init__(message)
+
+
+class EncryptionKeyError(ValueError):
+    """Raised by ``EnvelopeEncryptor`` when the active KEK is missing, a key
+    length is wrong, or a stored ciphertext references an unknown key version."""

austial_security-0.2.0/src/austial/security/idempotency_guard.py

@@ -0,0 +1,124 @@
+"""``IdempotencyKeyGuard`` -- enforces ``Idempotency-Key`` on write methods.
+
+For ``POST``/``PUT``/``PATCH``/``DELETE`` the guard reads the header
+``Idempotency-Key``:
+
+- Missing header: guard is a no-op (allow through). Product code can require it
+  by decorating the route with a companion validator.
+- Header present, no cached record: allow through; the framework's response
+  interceptor stores the outcome (product code calls
+  ``store.put(IdempotencyRecord(...))`` from a middleware/interceptor once the
+  handler returns).
+- Header present, cached record with the same body hash: replay the cached
+  response by short-circuiting the pipeline. This is done by attaching the
+  record to ``request.state.idempotent_replay``; the response interceptor is
+  expected to render it.
+- Header present, cached record with a *different* body hash: 409 conflict.
+
+Read-only methods (``GET``/``HEAD``/``OPTIONS``) are allowed unconditionally --
+they are already idempotent by definition and rarely mutate state.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from austial.common.decorators.injectable import Injectable
+from austial.common.guards.base import CanActivate, ExecutionContext
+from austial.security.errors import IdempotencyConflictError
+from austial.security.idempotency_store import IdempotencyStore
+
+_WRITE_METHODS = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+
+@Injectable()
+class IdempotencyKeyGuard(CanActivate):
+    def __init__(self, store: IdempotencyStore) -> None:
+        self._store = store
+
+    async def can_activate(self, context: ExecutionContext) -> bool:
+        request = context.get_request()
+        method = getattr(request, "method", "GET").upper()
+        if method not in _WRITE_METHODS:
+            return True
+
+        headers = getattr(request, "headers", {}) or {}
+        key = _header(headers, "Idempotency-Key")
+        if not key:
+            return True
+
+        request_hash = await self._hash_request(request, method)
+        cached = self._store.get(key)
+        if cached is None:
+            # cache miss: allow through; product code stores after handler runs
+            request.state.idempotency_key = key
+            request.state.idempotency_request_hash = request_hash
+            return True
+
+        if cached.request_hash != request_hash:
+            raise IdempotencyConflictError(
+                f"Idempotency-Key '{key}' has already been used with a different request payload"
+            )
+
+        # cache hit: signal replay
+        request.state.idempotent_replay = cached
+        return True
+
+    async def _hash_request(self, request: Any, method: str) -> str:
+        path = getattr(getattr(request, "url", None), "path", "") or getattr(request, "path", "/")
+        body_bytes = await _body(request)
+        digest = hashlib.sha256()
+        digest.update(method.encode("ascii"))
+        digest.update(b"\0")
+        digest.update(path.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(body_bytes)
+        return digest.hexdigest()
+
+
+def _header(headers: Any, name: str) -> str | None:
+    try:
+        value = headers.get(name)
+    except AttributeError:
+        return None
+    if value:
+        return value
+    try:
+        return headers.get(name.lower())
+    except AttributeError:
+        return None
+
+
+async def _body(request: Any) -> bytes:
+    """Read the request body. Starlette exposes ``await request.body()``; a test
+    double may attach ``body_bytes`` directly or provide a dict."""
+    # cached body written by prior guards/middleware
+    cached = getattr(getattr(request, "state", None), "raw_body", None)
+    if isinstance(cached, (bytes, bytearray)):
+        return bytes(cached)
+
+    body_attr = getattr(request, "body", None)
+    if callable(body_attr):
+        result = body_attr()
+        if hasattr(result, "__await__"):
+            result = await result
+        if isinstance(result, (bytes, bytearray)):
+            return bytes(result)
+        if isinstance(result, str):
+            return result.encode("utf-8")
+    if isinstance(body_attr, (bytes, bytearray)):
+        return bytes(body_attr)
+    if isinstance(body_attr, str):
+        return body_attr.encode("utf-8")
+
+    body_bytes = getattr(request, "body_bytes", None)
+    if isinstance(body_bytes, (bytes, bytearray)):
+        return bytes(body_bytes)
+
+    payload = getattr(request, "json_body", None)
+    if payload is not None:
+        return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+    return b""

austial_security-0.2.0/src/austial/security/idempotency_store.py

@@ -0,0 +1,70 @@
+"""``IdempotencyStore`` protocol + ``InMemoryIdempotencyStore`` reference impl.
+
+An idempotency record captures the response produced for a mutation so the
+guard can replay it verbatim if the client retries with the same
+``Idempotency-Key``. Records expire after ``ttl_seconds``; a replay with a
+different request body while the record is still alive is a conflict.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from austial.common.decorators.injectable import Injectable
+
+
+@dataclass(frozen=True, slots=True)
+class IdempotencyRecord:
+    """Snapshot of a response bound to an ``Idempotency-Key``."""
+
+    key: str
+    request_hash: str
+    status_code: int
+    body: Any
+    stored_at: float
+
+
+@runtime_checkable
+class IdempotencyStore(Protocol):
+    """Pluggable backend for ``IdempotencyKeyGuard``."""
+
+    def get(self, key: str) -> IdempotencyRecord | None:
+        """Return the record for ``key`` if it is still within TTL, else ``None``."""
+        ...
+
+    def put(self, record: IdempotencyRecord) -> None:
+        """Persist a record (overwriting any earlier record for the same key)."""
+        ...
+
+
+@Injectable()
+class InMemoryIdempotencyStore:
+    """Thread-safe, process-local record cache with lazy TTL expiry."""
+
+    def __init__(self, ttl_seconds: int = 86400) -> None:
+        self._lock = threading.Lock()
+        self._ttl = ttl_seconds
+        self._records: dict[str, IdempotencyRecord] = {}
+
+    def get(self, key: str) -> IdempotencyRecord | None:
+        now = time.time()
+        with self._lock:
+            record = self._records.get(key)
+            if record is None:
+                return None
+            if now - record.stored_at > self._ttl:
+                self._records.pop(key, None)
+                return None
+            return record
+
+    def put(self, record: IdempotencyRecord) -> None:
+        with self._lock:
+            self._records[record.key] = record
+
+    def reset(self) -> None:
+        """Clear all records. Useful in tests."""
+        with self._lock:
+            self._records.clear()