audit-core/audit_core/senders.py

"""Sender identities and what they are permitted to claim.

AUDIT-WP-0004-T03. WP-0003 recorded tenant isolation as delivered, but the
receiver accepted whatever ``tenant`` and ``source`` a caller sent as long as
it held the one shared token. This module binds a credential to the sources and
tenants it may write for, and drives that binding from configuration rather
than literals.

Each identity carries a *list* of tokens so a credential can be rotated without
a delivery gap: publish the replacement alongside the incumbent, move the
sender, then drop the old one.
"""

from __future__ import annotations

import hmac
import json
import os
from dataclasses import dataclass, field
from typing import Any, Iterable

WILDCARD = "*"


@dataclass(frozen=True)
class SenderIdentity:
    """A credential holder and the claims it is allowed to make."""

    name: str
    tokens: tuple[str, ...]
    sources: frozenset[str]
    tenants: frozenset[str] = field(default_factory=lambda: frozenset({WILDCARD}))
    may_write: bool = True
    may_read: bool = False

    def __post_init__(self) -> None:
        if not self.name:
            raise ValueError("sender identity needs a name")
        if not self.tokens or any(not t for t in self.tokens):
            raise ValueError(f"sender {self.name!r} needs at least one non-empty token")
        if not self.sources:
            raise ValueError(f"sender {self.name!r} needs at least one permitted source")

    def permits_source(self, source: str) -> bool:
        return WILDCARD in self.sources or source in self.sources

    def permits_tenant(self, tenant: str) -> bool:
        """Whether this identity may write for ``tenant``.

        Tenant identifiers are opaque here. Their shape
        (``tenant:<grouping>:<name>``) is owned by the IAM Profile and
        tenant-engine; matching is exact, never parsed or pattern-derived.
        """
        return WILDCARD in self.tenants or tenant in self.tenants


class SenderRegistry:
    """Resolves a credential to the identity that holds it."""

    def __init__(self, identities: Iterable[SenderIdentity]) -> None:
        self.identities = tuple(identities)
        if not self.identities:
            raise ValueError("at least one sender identity is required")

    def authenticate(self, authorization_header: str | None) -> SenderIdentity | None:
        """Return the matching identity, or None.

        Every candidate token is compared even after a match is found, so the
        work done does not depend on which credential was supplied or how many
        identities precede it.
        """
        supplied = str(authorization_header or "")
        matched: SenderIdentity | None = None
        for identity in self.identities:
            for token in identity.tokens:
                try:
                    hit = hmac.compare_digest(supplied, f"Bearer {token}")
                except TypeError:
                    # compare_digest rejects non-ASCII str; such a header is
                    # simply not a valid credential.
                    hit = False
                if hit and matched is None:
                    matched = identity
        return matched

    @classmethod
    def from_env(cls, env: dict[str, str] | None = None) -> "SenderRegistry":
        """Build a registry from ``AUDIT_CORE_SENDERS`` (JSON).

        Shape::

            [{"name": "user-engine",
              "tokens": ["current", "next"],
              "sources": ["user-engine"],
              "tenants": ["tenant:friendly:binky"],
              "may_read": false}]

        ``tenants`` defaults to ``["*"]``. Omitting it is a deliberate choice to
        accept any tenant from that sender and should be justified per sender,
        not adopted by default.
        """
        env = env if env is not None else dict(os.environ)
        raw = env.get("AUDIT_CORE_SENDERS")
        if raw:
            return cls(_parse_identities(raw))

        legacy = (env.get("AUDIT_CORE_INGEST_TOKEN") or "").strip()
        if not legacy:
            raise ValueError(
                "no sender configuration: set AUDIT_CORE_SENDERS (preferred) "
                "or AUDIT_CORE_INGEST_TOKEN"
            )
        # Legacy single-token form. Kept so an existing deployment keeps
        # working, but it grants every tenant — which is what T03 exists to
        # stop, so it is deliberately noisy about what it is.
        return cls([
            SenderIdentity(
                name="legacy-ingest-token",
                tokens=(legacy,),
                sources=frozenset({"user-engine"}),
                tenants=frozenset({WILDCARD}),
            )
        ])


def _parse_identities(raw: str) -> list[SenderIdentity]:
    try:
        entries = json.loads(raw)
    except json.JSONDecodeError as exc:
        raise ValueError(f"AUDIT_CORE_SENDERS is not valid JSON: {exc}") from exc
    if not isinstance(entries, list) or not entries:
        raise ValueError("AUDIT_CORE_SENDERS must be a non-empty JSON list")
    return [_identity_from(entry) for entry in entries]


def _identity_from(entry: Any) -> SenderIdentity:
    if not isinstance(entry, dict):
        raise ValueError("each sender entry must be an object")
    tokens = entry.get("tokens") or ([entry["token"]] if entry.get("token") else [])
    return SenderIdentity(
        name=str(entry.get("name") or ""),
        tokens=tuple(str(t) for t in tokens),
        sources=frozenset(str(s) for s in (entry.get("sources") or [])),
        tenants=frozenset(str(t) for t in (entry.get("tenants") or [WILDCARD])),
        may_write=bool(entry.get("may_write", True)),
        may_read=bool(entry.get("may_read", False)),
    )


def development_registry(token: str) -> SenderRegistry:
    """A single permissive sender, for tests and local development.

    Accepts any tenant. Not a production configuration — production binds each
    sender to the tenants it may write for via ``AUDIT_CORE_SENDERS``.
    """
    return SenderRegistry([
        SenderIdentity(
            name="development",
            tokens=(token,),
            sources=frozenset({"user-engine"}),
            tenants=frozenset({WILDCARD}),
            may_read=True,
        )
    ])