supython 0.1.0__py3-none-any.whl

supython/secretset.py

@@ -0,0 +1,347 @@
+"""Symmetric secret rotation manifest.
+
+Multi-secret lifecycle for symmetric secrets (storage signed URLs, OAuth state).
+Mirrors the JWT keyset pattern: ``secrets.json`` manifest + ``secrets/*.secret``
+files. The manifest tracks metadata (kid, status, created_at, retired_at);
+secret values live in individual files with ``0o600`` permissions.
+"""
+
+import json
+import logging
+import os
+import secrets
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Literal
+
+from .settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_SECRETS_DIR = Path("./.supython/secrets")
+
+SecretName = Literal["storage_signed_url", "oauth_state"]
+SecretStatus = Literal["active", "verifying", "retired"]
+
+
+@dataclass(frozen=True)
+class SecretEntry:
+    kid: str
+    name: SecretName
+    secret_path: Path
+    created_at: datetime
+    retired_at: datetime | None
+    status: SecretStatus
+
+
+def _now() -> datetime:
+    return datetime.now(tz=timezone.utc)
+
+
+def secrets_dir() -> Path:
+    s = get_settings()
+    return s.secrets_dir if s.secrets_dir is not None else _DEFAULT_SECRETS_DIR
+
+
+def manifest_path() -> Path:
+    return get_settings().secrets_manifest_path
+
+
+def has_manifest() -> bool:
+    return manifest_path().exists()
+
+
+def _to_iso(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _from_iso(value: str | None) -> datetime | None:
+    if value is None:
+        return None
+    return datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+
+
+def _entry_to_dict(entry: SecretEntry) -> dict[str, Any]:
+    return {
+        "kid": entry.kid,
+        "status": entry.status,
+        "created_at": _to_iso(entry.created_at),
+        "retired_at": _to_iso(entry.retired_at) if entry.retired_at else None,
+    }
+
+
+def _entry_from_dict(data: dict[str, Any], name: SecretName, sdir: Path) -> SecretEntry:
+    return SecretEntry(
+        kid=data["kid"],
+        name=name,
+        secret_path=sdir / f"{name}.{data['kid']}.secret",
+        created_at=_from_iso(data["created_at"]) or _now(),
+        retired_at=_from_iso(data.get("retired_at")),
+        status=data.get("status", "verifying"),
+    )
+
+
+def load_manifest() -> dict[str, Any] | None:
+    path = manifest_path()
+    if not path.exists():
+        return None
+    with path.open("r") as f:
+        return json.load(f)
+
+
+def write_manifest(manifest: dict[str, Any]) -> None:
+    path = manifest_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    tmp_path.write_text(json.dumps(manifest, sort_keys=True, indent=2) + "\n")
+    os.replace(tmp_path, path)
+
+
+def list_secrets(name: SecretName) -> list[SecretEntry]:
+    manifest = load_manifest()
+    if manifest is None:
+        return []
+    section = manifest.get(name)
+    if section is None:
+        return []
+    sdir = secrets_dir()
+    return [_entry_from_dict(d, name, sdir) for d in section.get("keys", [])]
+
+
+def active_secret(name: SecretName) -> SecretEntry | None:
+    manifest = load_manifest()
+    if manifest is None:
+        return None
+    section = manifest.get(name)
+    if section is None:
+        return None
+    active_kid = section.get("active")
+    if active_kid is None:
+        return None
+    for entry in list_secrets(name):
+        if entry.kid == active_kid:
+            return entry
+    return None
+
+
+def get_entry(name: SecretName, kid: str) -> SecretEntry | None:
+    for entry in list_secrets(name):
+        if entry.kid == kid:
+            return entry
+    return None
+
+
+def import_legacy_single_secret(name: SecretName) -> SecretEntry | None:
+    """Seed the manifest from a legacy env var when the manifest is absent.
+
+    Returns ``None`` if the manifest already exists or if the legacy env var
+    is empty / shorter than 32 characters.
+    """
+    if has_manifest():
+        return None
+    s = get_settings()
+    if name == "storage_signed_url":
+        legacy = s.storage_signed_url_secret
+    elif name == "oauth_state":
+        legacy = s.oauth_state_secret
+    else:
+        return None
+    if not legacy or len(legacy) < 32:
+        return None
+
+    sdir = secrets_dir()
+    sdir.mkdir(parents=True, exist_ok=True)
+    kid = "v1"
+    secret_path = sdir / f"{name}.{kid}.secret"
+    secret_path.write_text(legacy)
+    if os.name == "posix":
+        secret_path.chmod(0o600)
+
+    entry = SecretEntry(
+        kid=kid,
+        name=name,
+        secret_path=secret_path,
+        created_at=_now(),
+        retired_at=None,
+        status="active",
+    )
+    manifest = load_manifest() or {}
+    manifest[name] = {
+        "active": kid,
+        "keys": [_entry_to_dict(entry)],
+    }
+    write_manifest(manifest)
+    return entry
+
+
+def rotate(name: SecretName) -> SecretEntry:
+    """Generate a new secret, write file, append to manifest as ``verifying``.
+
+    On first call (no manifest), imports the legacy single secret before
+    appending the new one.
+    """
+    if not has_manifest():
+        import_legacy_single_secret(name)
+
+    sdir = secrets_dir()
+    sdir.mkdir(parents=True, exist_ok=True)
+
+    kid = secrets.token_urlsafe(8)
+    secret_path = sdir / f"{name}.{kid}.secret"
+    secret_value = secrets.token_urlsafe(48)
+    secret_path.write_text(secret_value)
+    if os.name == "posix":
+        secret_path.chmod(0o600)
+
+    entry = SecretEntry(
+        kid=kid,
+        name=name,
+        secret_path=secret_path,
+        created_at=_now(),
+        retired_at=None,
+        status="verifying",
+    )
+
+    manifest = load_manifest() or {}
+    section = manifest.get(name)
+    if section is None:
+        section = {"active": None, "keys": []}
+        manifest[name] = section
+
+    if not any(k["kid"] == kid for k in section["keys"]):
+        section["keys"].append(_entry_to_dict(entry))
+
+    if section.get("active") is None:
+        section["active"] = kid
+        for k in section["keys"]:
+            if k["kid"] == kid:
+                k["status"] = "active"
+                k["retired_at"] = None
+
+    write_manifest(manifest)
+    return entry
+
+
+def activate(name: SecretName, kid: str) -> None:
+    """Promote ``kid`` to ``active``; previous active becomes ``retired``."""
+    manifest = load_manifest()
+    if manifest is None:
+        raise FileNotFoundError(f"secret manifest not found: {manifest_path()}")
+    section = manifest.get(name)
+    if section is None:
+        raise KeyError(f"secret name not in manifest: {name!r}")
+    target = next((k for k in section["keys"] if k["kid"] == kid), None)
+    if target is None:
+        raise KeyError(f"kid not in {name} secret set: {kid!r}")
+    previous = section.get("active")
+    now_iso = _to_iso(_now())
+    for k in section["keys"]:
+        if k["kid"] == previous and previous != kid:
+            k["status"] = "retired"
+            k["retired_at"] = now_iso
+    target["status"] = "active"
+    target["retired_at"] = None
+    section["active"] = kid
+    write_manifest(manifest)
+
+
+def prune(name: SecretName, *, force_all: bool = False) -> list[str]:
+    """Drop retired secrets past grace; delete ``.secret`` files; return removed kids."""
+    manifest = load_manifest()
+    if manifest is None:
+        return []
+    section = manifest.get(name)
+    if section is None:
+        return []
+    grace = get_settings().secret_rotation_grace_seconds
+    now = _now()
+    sdir = secrets_dir()
+    removed: list[str] = []
+    surviving: list[dict[str, Any]] = []
+    for k in section["keys"]:
+        if k.get("status") != "retired":
+            surviving.append(k)
+            continue
+        retired_at = _from_iso(k.get("retired_at"))
+        elapsed = (now - retired_at).total_seconds() if retired_at else 0.0
+        if force_all or (retired_at is not None and elapsed >= grace):
+            secret_path = sdir / f"{name}.{k['kid']}.secret"
+            try:
+                secret_path.unlink()
+            except FileNotFoundError:
+                pass
+            removed.append(k["kid"])
+        else:
+            surviving.append(k)
+    section["keys"] = surviving
+    if section.get("active") in removed:
+        section["active"] = None
+    write_manifest(manifest)
+    return removed
+
+
+def read_secret_value(entry: SecretEntry) -> str:
+    return entry.secret_path.read_text().strip()
+
+
+@lru_cache(maxsize=None)
+def load_signing_secret(name: SecretName) -> str | None:
+    """Return the active secret value, or ``None`` when callers should fall back.
+
+    Returns ``None`` when the manifest is absent **or** has no section for
+    ``name`` so callers can use the legacy env-var path per-``SecretName``.
+    This lets one secret family migrate to the manifest while another keeps
+    running on its env var (the §18 "each secret family still rotates
+    independently" decision).
+
+    Raises ``RuntimeError`` only when the section exists but its ``active``
+    pointer is absent or dangles to a kid that is not in the section's
+    ``keys`` list — that state is operator error, surfaced by ``supython
+    doctor``.
+    """
+    manifest = load_manifest()
+    if manifest is None:
+        return None
+    section = manifest.get(name)
+    if section is None:
+        return None
+    active_kid = section.get("active")
+    if active_kid is None:
+        raise RuntimeError(f"no active secret for {name!r}")
+    entry = get_entry(name, active_kid)
+    if entry is None:
+        raise RuntimeError(
+            f"active kid {active_kid!r} for {name!r} not present in manifest"
+        )
+    return read_secret_value(entry)
+
+
+@lru_cache(maxsize=None)
+def load_verification_secrets(name: SecretName) -> list[tuple[str, str | None]]:
+    """Return ``(secret_value, kid)`` for active + retired-within-grace.
+
+    Returns ``[]`` when the manifest is absent.
+    """
+    manifest = load_manifest()
+    if manifest is None:
+        return []
+    grace = get_settings().secret_rotation_grace_seconds
+    now = _now()
+    result: list[tuple[str, str | None]] = []
+    for entry in list_secrets(name):
+        if entry.status == "active":
+            result.append((read_secret_value(entry), entry.kid))
+        elif entry.status == "retired":
+            retired_at = entry.retired_at
+            elapsed = (now - retired_at).total_seconds() if retired_at else 0.0
+            if retired_at is not None and elapsed < grace:
+                result.append((read_secret_value(entry), entry.kid))
+    return result
+
+
+def clear_cache() -> None:
+    """Clear cached loaders; call after manifest mutations."""
+    load_signing_secret.cache_clear()
+    load_verification_secrets.cache_clear()

supython/security_headers.py

@@ -0,0 +1,78 @@
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from .settings import Settings, get_settings
+
+logger = logging.getLogger(__name__)
+
+
+def _hsts_effective(settings: Settings) -> bool:
+    # Explicit override wins; otherwise auto-on for https site_url, off for http.
+    if settings.security_hsts_enabled is not None:
+        return settings.security_hsts_enabled
+    return settings.site_url.lower().startswith("https://")
+
+
+def _build_always_headers(settings: Settings) -> list[tuple[bytes, bytes]]:
+    headers: list[tuple[bytes, bytes]] = [
+        (b"x-content-type-options", b"nosniff"),
+        (b"x-frame-options", settings.security_frame_options.encode("ascii")),
+        (b"referrer-policy", settings.security_referrer_policy.encode("ascii")),
+    ]
+    if _hsts_effective(settings):
+        parts = [f"max-age={settings.security_hsts_max_age}"]
+        if settings.security_hsts_include_subdomains:
+            parts.append("includeSubDomains")
+        if settings.security_hsts_preload:
+            parts.append("preload")
+        headers.append(
+            (b"strict-transport-security", "; ".join(parts).encode("ascii"))
+        )
+    return headers
+
+
+class SecurityHeadersMiddleware:
+    def __init__(self, app: Any, settings: Settings | None = None) -> None:
+        self.app = app
+        self._settings = settings or get_settings()
+        self._always = _build_always_headers(self._settings)
+        self._csp = (
+            self._settings.security_csp.encode("ascii")
+            if self._settings.security_csp
+            else b""
+        )
+        self._csp_exempt = tuple(
+            p.strip()
+            for p in self._settings.security_csp_exempt_paths.split(",")
+            if p.strip()
+        )
+
+    async def __call__(
+        self,
+        scope: dict[str, Any],
+        receive: Callable[[], Awaitable[dict[str, Any]]],
+        send: Callable[[dict[str, Any]], Awaitable[None]],
+    ) -> None:
+        if scope["type"] != "http" or not self._settings.security_headers_enabled:
+            await self.app(scope, receive, send)
+            return
+
+        path = scope.get("path", "")
+        apply_csp = bool(self._csp) and not any(
+            path == p or path.startswith(p + "/") for p in self._csp_exempt
+        )
+
+        async def _send(message: dict[str, Any]) -> None:
+            if message["type"] == "http.response.start":
+                existing: list[tuple[bytes, bytes]] = list(message.get("headers", []))
+                present = {name.lower() for name, _ in existing}
+                for name, value in self._always:
+                    if name not in present:
+                        existing.append((name, value))
+                if apply_csp and b"content-security-policy" not in present:
+                    existing.append((b"content-security-policy", self._csp))
+                message["headers"] = existing
+            await send(message)
+
+        await self.app(scope, receive, _send)

supython/settings.py

@@ -0,0 +1,244 @@
+from functools import lru_cache
+from pathlib import Path
+from typing import Annotated, Literal
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        case_sensitive=False,
+    )
+
+    database_url: str = "postgresql://supython:supython@localhost:54322/supython"
+    db_statement_timeout_ms: int = 30000
+    db_pool_min_size: int = 1
+    db_pool_max_size: int = 10
+    db_allowed_roles: Annotated[frozenset[str], NoDecode] = frozenset[str](
+        {"anon", "authenticated"}
+    )
+    jwt_alg: Literal["RS256", "ES256"] = "RS256"
+    jwt_aud: str = "authenticated"
+
+    jwt_private_key: str | None = None
+    jwt_private_key_path: Path | None = None
+    jwt_kid: str | None = None
+    jwt_jwks_path: Path = Path("./.supython/jwks.json")
+    jwt_keys_dir: Path | None = None
+    jwt_keyset_manifest_path: Path = Path("./.supython/keyset.json")
+    jwt_rotation_grace_seconds: int = 3600
+
+    secrets_dir: Path | None = None
+    secrets_manifest_path: Path = Path("./.supython/secrets.json")
+    secret_rotation_grace_seconds: int = 3600
+
+    @field_validator(
+        "jwt_private_key",
+        "jwt_kid",
+        "secrets_dir",
+        "storage_signed_url_secret",
+        "oauth_state_secret",
+        "storage_s3_endpoint",
+        "settings_module",
+        mode="before",
+    )
+    @classmethod
+    def _empty_str_to_none(cls, v: object) -> object:
+        if isinstance(v, str) and not v.strip():
+            return None
+        return v
+
+    @field_validator("db_allowed_roles", mode="before")
+    @classmethod
+    def _split_db_allowed_roles(cls, v: object) -> object:
+        if isinstance(v, str):
+            return frozenset(part.strip() for part in v.split(",") if part.strip())
+        return v
+
+    @field_validator("security_hsts_enabled", mode="before")
+    @classmethod
+    def _empty_bool_to_none(cls, v: object) -> object:
+        if isinstance(v, str) and not v.strip():
+            return None
+        return v
+
+    @field_validator(
+        "jwt_private_key_path", "jwt_keys_dir", "backup_docker_container", mode="before"
+    )
+    @classmethod
+    def _empty_path_to_none(cls, v: object) -> object:
+        if isinstance(v, str) and not v.strip():
+            return None
+        return v
+
+    access_token_ttl: int = 3600
+    refresh_token_ttl: int = 60 * 60 * 24 * 30
+
+    recover_token_ttl: int = 3600
+    magic_link_token_ttl: int = 15 * 60
+    otp_token_ttl: int = 10 * 60
+    auth_rate_limit_enabled: bool = True
+    auth_rate_limit_window_seconds: int = 60
+    auth_rate_limit_token_per_window: int = 10
+    auth_rate_limit_signup_per_window: int = 5
+    auth_rate_limit_recover_per_window: int = 3
+    auth_rate_limit_otp_per_window: int = 5
+    auth_rate_limit_magiclink_per_window: int = 5
+
+    authenticator_password: str = "authenticator"
+
+    email_backend: Literal["console", "smtp"] = "console"
+    email_from: str = "supython@localhost"
+    smtp_host: str = "localhost"
+    smtp_port: int = 587
+    smtp_username: str = ""
+    smtp_password: str = ""
+    smtp_starttls: bool = True
+
+    google_client_id: str = ""
+    google_client_secret: str = ""
+    github_client_id: str = ""
+    github_client_secret: str = ""
+    oauth_state_secret: str | None = Field(default=None, min_length=32)
+    oauth_state_max_age: int = 600
+
+    # PostgREST
+    postgrest_url: str = "http://localhost:54321"
+    site_url: str = "http://localhost:8000"
+
+    # CORS: comma-separated allowed browser origins. Empty = no wildcard.
+    # Example: CORS_ORIGINS=https://app.example.com,http://localhost:5173
+    cors_origins: str = ""
+
+    # Storage (v0.3)
+    storage_backend: Literal["local", "s3"] = "local"
+    storage_local_root: str = "./storage"
+
+    storage_s3_endpoint: str | None = None
+    storage_s3_region: str = "us-east-1"
+    storage_s3_bucket: str = ""
+    storage_s3_access_key_id: str = ""
+    storage_s3_secret_access_key: str = ""
+
+    storage_signed_url_secret: str | None = Field(default=None, min_length=32)
+    storage_signed_url_default_ttl: int = 3600
+    storage_max_upload_bytes: int = 50 * 1024 * 1024
+
+    # Security headers
+    security_headers_enabled: bool = True
+
+    # HSTS: None = auto (on iff site_url starts with https://). True/False
+    # explicitly forces. Dev defaults are safe because site_url defaults to
+    # http://localhost:8000, so HSTS is off out of the box.
+    security_hsts_enabled: bool | None = None
+    security_hsts_max_age: int = 31536000
+    security_hsts_include_subdomains: bool = True
+    security_hsts_preload: bool = False
+
+    security_frame_options: str = "DENY"
+    security_referrer_policy: str = "strict-origin-when-cross-origin"
+    security_csp: str = (
+        "default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'"
+    )
+    # Comma-separated path prefixes that skip CSP. Default exempts FastAPI's
+    # auto docs (inline scripts + jsdelivr CDN bundle) and the bundled admin
+    # SPA (Vue + Naive UI inject inline styles, Monaco uses blob: workers) —
+    # both would be broken by the strict `default-src 'none'` policy.
+    security_csp_exempt_paths: str = "/docs,/redoc,/openapi.json,/admin"
+
+    # Input size guards (v0.7 — Security round 2)
+    # Global cap on request body size for non-streaming write routes. Sized
+    # generously for JSON/form payloads so it never trips legitimate auth or
+    # control-plane traffic, while still rejecting "1 GB password" abuse
+    # before it reaches argon2.
+    security_max_body_bytes: int = 1 * 1024 * 1024
+    # Path prefixes whose bodies are governed by their own per-feature caps
+    # (storage_max_upload_bytes, functions_max_body_bytes) rather than the
+    # global cap. Keeps streaming uploads working without bloating the
+    # global default.
+    security_body_limit_exempt_paths: str = "/storage/v1/object,/functions"
+
+    # Functions (v0.3)
+    functions_dir: str = "./functions"
+    functions_hot_reload: bool = True
+    functions_max_body_bytes: int = 5 * 1024 * 1024
+    functions_max_handler_seconds: float = 30.0
+
+    # Realtime (v0.4)
+    realtime_enabled: bool = True
+    realtime_notify_channel: str = "realtime:changes"
+    realtime_max_connections: int = 1000
+    realtime_max_subs_per_conn: int = 100
+    # Server-side timeout: close socket with 1001 if no heartbeat arrives within this window.
+    # Client SDK sends heartbeats every 25 s; default gives 5 s of grace.
+    realtime_heartbeat_timeout_seconds: int = 30
+    realtime_broker_queue_size: int = 1000
+    realtime_rls_check_timeout_s: float = 1.0
+    realtime_broadcast_self_default: bool = False
+
+    # Jobs (v0.5)
+    jobs_enabled: bool = True
+    jobs_backend: Literal["pg"] = "pg"
+    jobs_cron_backend: Literal["pg_cron", "inproc", "off"] = "pg_cron"
+    jobs_queue_default: str = "default"
+    jobs_poll_interval_s: float = 1.0
+    jobs_concurrency: int = 5
+    jobs_default_max_attempts: int = 3
+    jobs_backoff_base_s: float = 5.0
+    jobs_backoff_max_s: float = 300.0
+    jobs_visibility_timeout_s: float = 300.0
+    jobs_visibility_reclaim_batch: int = 10
+    jobs_drain_timeout_s: float = 30.0
+    jobs_dev_inprocess: bool = False
+    arq_redis_url: str = "redis://localhost:6379"
+    dramatiq_broker_url: str = "redis://localhost:6379"
+
+    # Backups (v1.1.4)
+    backups_dir: str = "./backups"
+    backup_timeout_s: int = 1800
+    # "host"   — invoke pg_dump from the worker's PATH (production: bundle it
+    #            in the worker image; bare-metal: install postgresql-client).
+    # "docker" — exec pg_dump inside the running postgres container (dev with
+    #            docker-compose; uses the postgres image's bundled binary so
+    #            the version always matches the server and no host install
+    #            is needed).
+    backup_via: Literal["host", "docker"] = "docker"
+    # No default: scaffolded projects pre-fill this in .env (`<project>-db`),
+    # and `_build_args` raises a clear error when docker mode is selected
+    # without a container name configured.
+    backup_docker_container: str | None = None
+
+    log_level: str = "INFO"
+    log_json: bool = True
+
+    # Comma-separated dotted module paths to import at boot, e.g.
+    # `myapp.jobs,myapp.hooks`. Imports happen before FastAPI app
+    # construction (so @job / @cron / @on decorators register) and again
+    # before the job worker starts. Env var: `EXTENSIONS=…`.
+    extensions: Annotated[list[str], NoDecode] = []
+
+    @field_validator("extensions", mode="before")
+    @classmethod
+    def _split_extensions(cls, v: object) -> object:
+        if isinstance(v, str):
+            return [part.strip() for part in v.split(",") if part.strip()]
+        return v
+
+    # Django-style Python config module declaring EXTENSIONS, EXTRA_ROUTERS,
+    # EXTRA_MIDDLEWARE. Loaded before FastAPI app construction. The scaffold's
+    # manage.py shim sets this for you. Env var: `SUPYTHON_SETTINGS_MODULE=…`.
+    # Prefix differs from `EXTENSIONS=` deliberately: parallels Django's
+    # `DJANGO_SETTINGS_MODULE` and avoids collision with unrelated tooling.
+    settings_module: str | None = Field(
+        default=None,
+        validation_alias="SUPYTHON_SETTINGS_MODULE",
+    )
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()