supython 0.1.0__py3-none-any.whl

supython/keyset.py

@@ -0,0 +1,279 @@
+"""JWT key rotation manifest.
+
+Multi-kid keyset lifecycle: tracks per-kid PEM files in a directory
+(``settings.jwt_keys_dir``, default ``./.supython/keys/``) governed by a
+JSON manifest (``settings.jwt_keyset_manifest_path``, default
+``./.supython/keyset.json``). The manifest is the source of truth for
+the active signing kid; ``settings.jwt_kid`` (the ``JWT_KID`` env var)
+remains as an explicit override for read-only-FS deployments.
+
+When the manifest is absent, ``jwks.load_signing_key`` /
+``load_verification_keyset`` continue to behave as in Phase 5 (single
+key from ``JWT_PRIVATE_KEY_PATH`` / ``JWT_PRIVATE_KEY``). The first
+``supython keygen rotate`` invocation calls
+``import_legacy_single_key`` to seed the manifest from the legacy
+single-key environment.
+"""
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Literal
+
+from cryptography.hazmat.primitives import serialization
+
+from . import jwks
+from .settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_KEYS_DIR = Path("./.supython/keys")
+
+KeyStatus = Literal["active", "verifying", "retired"]
+
+
+@dataclass(frozen=True)
+class KeyEntry:
+    kid: str
+    alg: str
+    pem_path: Path
+    created_at: datetime
+    retired_at: datetime | None
+    status: KeyStatus
+
+
+def _now() -> datetime:
+    return datetime.now(tz=timezone.utc)
+
+
+def keys_dir() -> Path:
+    s = get_settings()
+    return s.jwt_keys_dir if s.jwt_keys_dir is not None else _DEFAULT_KEYS_DIR
+
+
+def manifest_path() -> Path:
+    return get_settings().jwt_keyset_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: KeyEntry) -> dict[str, Any]:
+    return {
+        "kid": entry.kid,
+        "alg": entry.alg,
+        "created_at": _to_iso(entry.created_at),
+        "retired_at": _to_iso(entry.retired_at) if entry.retired_at else None,
+        "status": entry.status,
+    }
+
+
+def _entry_from_dict(data: dict[str, Any], kdir: Path) -> KeyEntry:
+    return KeyEntry(
+        kid=data["kid"],
+        alg=data["alg"],
+        pem_path=kdir / f"{data['kid']}.pem",
+        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_keys() -> list[KeyEntry]:
+    manifest = load_manifest()
+    if manifest is None:
+        return []
+    kdir = keys_dir()
+    return [_entry_from_dict(d, kdir) for d in manifest.get("keys", [])]
+
+
+def get_entry(kid: str) -> KeyEntry | None:
+    for entry in list_keys():
+        if entry.kid == kid:
+            return entry
+    return None
+
+
+def active_kid() -> str | None:
+    """Return the kid the auth process should sign with.
+
+    ``JWT_KID`` env var wins over the manifest so a deployment with a
+    read-only filesystem can pin a kid without touching the manifest.
+    """
+    s = get_settings()
+    if s.jwt_kid is not None:
+        return s.jwt_kid
+    manifest = load_manifest()
+    if manifest is None:
+        return None
+    return manifest.get("active")
+
+
+def add_key(
+    alg: Literal["RS256", "ES256"] = "RS256",
+    *,
+    status: KeyStatus = "verifying",
+    activate_immediately: bool = False,
+) -> KeyEntry:
+    """Generate a new keypair, persist its PEM, and append it to the manifest.
+
+    When the manifest has no active kid yet, the new key is promoted to
+    ``active`` regardless of ``status`` so the keyset is always usable.
+    """
+    kdir = keys_dir()
+    kdir.mkdir(parents=True, exist_ok=True)
+
+    key = jwks.generate_private_key(alg)
+    signer = jwks.signing_key_from_private_key(key, alg)
+    pem_path = kdir / f"{signer.kid}.pem"
+    if not pem_path.exists():
+        jwks.write_private_key_pem(pem_path, jwks.private_key_to_pem(key), force=False)
+
+    manifest = load_manifest() or {"active": None, "keys": []}
+
+    if not any(e["kid"] == signer.kid for e in manifest["keys"]):
+        entry = KeyEntry(
+            kid=signer.kid,
+            alg=alg,
+            pem_path=pem_path,
+            created_at=_now(),
+            retired_at=None,
+            status=status,
+        )
+        manifest["keys"].append(_entry_to_dict(entry))
+
+    if activate_immediately or manifest.get("active") is None:
+        manifest["active"] = signer.kid
+        for e in manifest["keys"]:
+            if e["kid"] == signer.kid:
+                e["status"] = "active"
+                e["retired_at"] = None
+
+    write_manifest(manifest)
+    record = next(e for e in manifest["keys"] if e["kid"] == signer.kid)
+    return _entry_from_dict(record, kdir)
+
+
+def activate(kid: str) -> None:
+    """Flip the active signing kid; previously-active kid becomes ``retired``."""
+    manifest = load_manifest()
+    if manifest is None:
+        raise FileNotFoundError(f"keyset manifest not found: {manifest_path()}")
+    target = next((e for e in manifest["keys"] if e["kid"] == kid), None)
+    if target is None:
+        raise KeyError(f"kid not in keyset: {kid!r}")
+    previous = manifest.get("active")
+    now_iso = _to_iso(_now())
+    for e in manifest["keys"]:
+        if e["kid"] == previous and previous != kid:
+            e["status"] = "retired"
+            e["retired_at"] = now_iso
+    target["status"] = "active"
+    target["retired_at"] = None
+    manifest["active"] = kid
+    write_manifest(manifest)
+
+
+def prune(*, force_all: bool = False) -> list[str]:
+    """Drop retired kids whose grace window has elapsed; return removed kids."""
+    manifest = load_manifest()
+    if manifest is None:
+        return []
+    grace = get_settings().jwt_rotation_grace_seconds
+    now = _now()
+    kdir = keys_dir()
+    removed: list[str] = []
+    surviving: list[dict[str, Any]] = []
+    for e in manifest["keys"]:
+        if e.get("status") != "retired":
+            surviving.append(e)
+            continue
+        retired_at = _from_iso(e.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):
+            pem_path = kdir / f"{e['kid']}.pem"
+            try:
+                pem_path.unlink()
+            except FileNotFoundError:
+                pass
+            removed.append(e["kid"])
+        else:
+            surviving.append(e)
+    manifest["keys"] = surviving
+    if manifest.get("active") in removed:
+        manifest["active"] = None
+    write_manifest(manifest)
+    return removed
+
+
+def import_legacy_single_key() -> KeyEntry | None:
+    """Seed the manifest from ``JWT_PRIVATE_KEY_PATH`` / ``JWT_PRIVATE_KEY``.
+
+    Returns ``None`` if the manifest already exists or if the legacy
+    single-key environment is empty. Idempotent: re-running on a
+    non-empty manifest is a no-op.
+    """
+    if has_manifest():
+        return None
+    s = get_settings()
+    if s.jwt_private_key is None and s.jwt_private_key_path is None:
+        return None
+    if s.jwt_private_key is not None:
+        pem_bytes = s.jwt_private_key.encode()
+    elif s.jwt_private_key_path is not None and s.jwt_private_key_path.exists():
+        pem_bytes = s.jwt_private_key_path.read_bytes()
+    else:
+        return None
+
+    key = serialization.load_pem_private_key(pem_bytes, password=None)
+    signer = jwks.signing_key_from_private_key(key, s.jwt_alg, s.jwt_kid)
+
+    kdir = keys_dir()
+    kdir.mkdir(parents=True, exist_ok=True)
+    pem_path = kdir / f"{signer.kid}.pem"
+    if not pem_path.exists():
+        jwks.write_private_key_pem(pem_path, jwks.private_key_to_pem(key), force=False)
+
+    entry = KeyEntry(
+        kid=signer.kid,
+        alg=s.jwt_alg,
+        pem_path=pem_path,
+        created_at=_now(),
+        retired_at=None,
+        status="active",
+    )
+    write_manifest({
+        "active": signer.kid,
+        "keys": [_entry_to_dict(entry)],
+    })
+    return entry

supython/logging_config.py

@@ -0,0 +1,291 @@
+import contextvars
+import json
+import logging
+import sys
+import time
+import traceback
+import uuid
+from collections import deque
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from typing import Any
+
+request_id: contextvars.ContextVar[str] = contextvars.ContextVar("request_id")
+
+
+def get_request_id() -> str | None:
+    return request_id.get(None)
+
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        entry: dict[str, Any] = {
+            "timestamp": datetime.fromtimestamp(record.created, tz=UTC).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        rid = get_request_id()
+        if rid is not None:
+            entry["request_id"] = rid
+        if record.exc_info and record.exc_info[1] is not None:
+            entry["exc_info"] = "".join(traceback.format_exception(*record.exc_info))
+        if hasattr(record, "extra_fields"):
+            entry.update(record.extra_fields)
+        return json.dumps(entry, default=str)
+
+
+_PLAIN_FORMAT = "%(levelname)s %(name)s %(message)s"
+
+
+class BoundedLogRingHandler(logging.Handler):
+    """In-memory ring buffer of structured log records.
+
+    Each entry is a dict with 'timestamp', 'level', 'logger', 'message',
+    and optionally 'request_id' and 'exc_info'.  The buffer is bounded so
+    it never grows without limit.
+
+    Access the buffer via the module-level ``log_ring`` tuple:
+
+        from supython.logging_config import log_ring
+        entries = log_ring.get()  # list[dict[str, Any]]
+    """
+
+    def __init__(self, capacity: int = 5000) -> None:
+        super().__init__()
+        self._buffer: deque[dict[str, Any]] = deque(maxlen=capacity)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        entry: dict[str, Any] = {
+            "timestamp": datetime.fromtimestamp(record.created, tz=UTC).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        rid = get_request_id()
+        if rid is not None:
+            entry["request_id"] = rid
+        if record.exc_info and record.exc_info[1] is not None:
+            entry["exc_info"] = "".join(traceback.format_exception(*record.exc_info))
+        if hasattr(record, "extra_fields"):
+            entry.update(record.extra_fields)  # type: ignore[attr-defined]
+        self._buffer.append(entry)
+
+    def get(self) -> list[dict[str, Any]]:
+        return list(self._buffer)
+
+
+# Module-level ring buffer instance — populated by configure_logging() below.
+_log_ring_handler: BoundedLogRingHandler | None = None
+
+
+def get_log_ring() -> list[dict[str, Any]]:
+    """Return a snapshot of the in-memory log ring buffer.
+
+    Returns an empty list before ``configure_logging()`` has been called.
+    """
+    if _log_ring_handler is None:
+        return []
+    return _log_ring_handler.get()
+
+
+def configure_logging(level: str = "INFO", *, json_format: bool = True) -> None:
+    global _log_ring_handler
+
+    root = logging.getLogger()
+    numeric = getattr(logging, level.upper(), logging.INFO)
+    root.setLevel(numeric)
+
+    # Stdout handler
+    stdout_handler = logging.StreamHandler(sys.stdout)
+    if json_format:
+        stdout_handler.setFormatter(JsonFormatter())
+    else:
+        stdout_handler.setFormatter(logging.Formatter(_PLAIN_FORMAT))
+
+    # Ring-buffer handler (always structured, regardless of json_format)
+    ring_handler = BoundedLogRingHandler(capacity=5000)
+    ring_handler.setLevel(numeric)
+
+    root.handlers = [
+        h
+        for h in root.handlers
+        if not isinstance(h, (logging.StreamHandler, BoundedLogRingHandler))
+    ]
+    root.addHandler(stdout_handler)
+    root.addHandler(ring_handler)
+    _log_ring_handler = ring_handler
+
+
+class RequestIdMiddleware:
+    def __init__(self, app: Any) -> None:
+        self.app = app
+
+    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"] not in ("http", "websocket"):
+            await self.app(scope, receive, send)
+            return
+
+        req_id: str | None = None
+        for name, value in scope.get("headers", []):
+            if name == b"x-request-id":
+                req_id = value.decode("ascii", errors="replace")
+                break
+        if not req_id:
+            req_id = uuid.uuid4().hex
+
+        token = request_id.set(req_id)
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            request_id.reset(token)
+
+
+_REQUEST_LOG_MAX_BODY_BYTES = 10 * 1024
+_AUTH_HEADER = b"authorization"
+_REDACTED = "***REDACTED***"
+
+_access_logger = logging.getLogger("supython.access")
+
+
+class RequestLoggingMiddleware:
+    def __init__(self, app: Any) -> None:
+        self.app = app
+
+    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":
+            await self.app(scope, receive, send)
+            return
+
+        start = time.monotonic()
+        method = scope.get("method", "")
+        path = scope.get("path", "")
+
+        user_agent: str | None = None
+        for name, value in scope.get("headers", []):
+            if name == b"user-agent":
+                user_agent = value.decode("utf-8", errors="replace")
+                break
+
+        rid = get_request_id()
+
+        body_chunks: list[bytes] = []
+        body_size = 0
+        body_truncated = False
+
+        async def _drain_body() -> None:
+            nonlocal body_size, body_truncated
+            while True:
+                msg = await receive()
+                if msg["type"] != "http.request":
+                    continue
+                chunk = msg.get("body", b"")
+                more = msg.get("more_body", False)
+                if chunk and body_size < _REQUEST_LOG_MAX_BODY_BYTES:
+                    space = _REQUEST_LOG_MAX_BODY_BYTES - body_size
+                    if len(chunk) > space:
+                        body_chunks.append(chunk[:space])
+                        body_size += space
+                        body_truncated = True
+                    else:
+                        body_chunks.append(chunk)
+                        body_size += len(chunk)
+                if not more:
+                    break
+
+        await _drain_body()
+
+        full_body = b"".join(body_chunks)
+        body_consumed = False
+
+        async def _receive() -> dict[str, Any]:
+            nonlocal body_consumed
+            if not body_consumed:
+                body_consumed = True
+                return {
+                    "type": "http.request",
+                    "body": full_body,
+                    "more_body": False,
+                }
+            # Body already delivered. Forward subsequent calls to the real
+            # receive() so callers awaiting http.disconnect (e.g. Starlette's
+            # StreamingResponse.listen_for_disconnect) actually block on the
+            # event loop instead of busy-looping on synchronous returns,
+            # which would starve the streaming task and hang the request.
+            return await receive()
+
+        status_code: int = 0
+        response_size: int = 0
+
+        async def _send(message: dict[str, Any]) -> None:
+            nonlocal status_code, response_size
+            if message["type"] == "http.response.start":
+                status_code = message.get("status", 0)
+            elif message["type"] == "http.response.body":
+                response_size += len(message.get("body", b""))
+            await send(message)
+
+        exc_info: tuple[type, BaseException, Any] | None = None
+        try:
+            await self.app(scope, _receive, _send)
+        except Exception:
+            exc_info = sys.exc_info()
+            raise
+        finally:
+            duration_ms = round((time.monotonic() - start) * 1000, 2)
+
+            redacted_headers: list[list[str]] = []
+            for name, value in scope.get("headers", []):
+                if name == _AUTH_HEADER:
+                    redacted_headers.append([name.decode("ascii", errors="replace"), _REDACTED])
+                else:
+                    redacted_headers.append(
+                        [
+                            name.decode("ascii", errors="replace"),
+                            value.decode("utf-8", errors="replace"),
+                        ]
+                    )
+
+            fields: dict[str, Any] = {
+                "duration_ms": duration_ms,
+                "status": status_code,
+                "method": method,
+                "path": path,
+                "request_id": rid,
+                "user_agent": user_agent,
+                "response_size": response_size,
+                "headers": redacted_headers,
+            }
+
+            is_server_error = 500 <= status_code < 600 or exc_info is not None
+
+            if is_server_error:
+                fields["request_body"] = full_body.decode("utf-8", errors="replace")
+                if body_truncated:
+                    fields["body_truncated"] = True
+                if exc_info is not None and exc_info[1] is not None:
+                    fields["traceback"] = "".join(traceback.format_exception(*exc_info))
+
+            level = logging.ERROR if is_server_error else logging.INFO
+            record = logging.LogRecord(
+                name="supython.access",
+                level=level,
+                pathname=__file__,
+                lineno=0,
+                msg="request completed",
+                args=(),
+                exc_info=None,
+            )
+            record.extra_fields = fields  # type: ignore[attr-defined]
+
+            _access_logger.handle(record)

supython/mail.py

@@ -0,0 +1,33 @@
+"""Shared email dispatcher.
+
+Routes email through the jobs queue when jobs are enabled and a caller
+connection is available, otherwise falls back to synchronous send.
+"""
+
+import asyncpg
+
+from .mailer import EmailMessage, get_mailer
+from .settings import get_settings
+
+
+async def dispatch(
+    conn: asyncpg.Connection | None,
+    msg: EmailMessage,
+    *,
+    job_name: str = "send_email",
+) -> None:
+    """Send an email, via the jobs queue when enabled and a conn is available.
+
+    Falls back to synchronous ``mailer.send()`` otherwise.
+    """
+    s = get_settings()
+    if s.jobs_enabled and conn is not None:
+        from .jobs import service as _jobs_svc
+
+        await _jobs_svc.enqueue(
+            conn,
+            name=job_name,
+            payload=msg.model_dump(),
+        )
+        return
+    await get_mailer().send(msg)

supython/mailer.py

@@ -0,0 +1,65 @@
+import logging
+from email.message import EmailMessage as MimeMessage
+from typing import Protocol
+
+import aiosmtplib
+from pydantic import BaseModel, Field
+
+from .settings import Settings, get_settings
+
+logger = logging.getLogger(__name__)
+
+
+class EmailMessage(BaseModel):
+    to: list[str] = Field(min_length=1)
+    subject: str
+    text: str
+    html: str | None = None
+
+
+class EmailBackend(Protocol):
+    async def send(self, msg: EmailMessage) -> None: ...
+
+
+class ConsoleBackend:
+    async def send(self, msg: EmailMessage) -> None:
+        logger.info(
+            "email (console): to=%s subject=%s text=%r html=%r",
+            msg.to,
+            msg.subject,
+            msg.text,
+            msg.html,
+        )
+
+
+class SmtpBackend:
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+
+    async def send(self, msg: EmailMessage) -> None:
+        mime = MimeMessage()
+        mime["From"] = self._settings.email_from
+        mime["To"] = ", ".join(msg.to)
+        mime["Subject"] = msg.subject
+        mime.set_content(msg.text)
+        if msg.html is not None:
+            mime.add_alternative(msg.html, subtype="html")
+
+        username = self._settings.smtp_username or None
+        password = self._settings.smtp_password or None
+
+        await aiosmtplib.send(
+            mime,
+            hostname=self._settings.smtp_host,
+            port=self._settings.smtp_port,
+            username=username,
+            password=password,
+            start_tls=self._settings.smtp_starttls,
+        )
+
+
+def get_mailer() -> EmailBackend:
+    settings = get_settings()
+    if settings.email_backend == "smtp":
+        return SmtpBackend(settings)
+    return ConsoleBackend()