sonnet-auth 0.1.0__py3-none-any.whl

sonnet_auth/__init__.py

@@ -0,0 +1,92 @@
+"""sonnet-auth -- JWT/JWKS authentication and Cedar authorization for sonnet-server.
+
+Public API:
+
+  AuthN (JWT/JWKS):
+    AuthSettings            -- settings model with resolve(env_prefix, seed)
+    AuthnConfig             -- JWT/JWKS config (Pydantic, frozen)
+    AuthMode                -- jwt_verifier | oauth_proxy
+    JwtCredentialValidator   -- implements sonnet-server CredentialValidator protocol
+    build_auth_context      -- JWT claims -> AuthContext
+    resolve_attributes      -- JWT claims -> Cedar principal attributes
+    resolve_dot_path        -- nested claim extraction
+
+  AuthZ (Cedar, requires sonnet-auth[cedar]):
+    AuthzDeniedError        -- raised by check_authz on deny; transports map to 403
+    check_authz             -- raises AuthzDeniedError on deny, no-op if disabled
+    filter_authz            -- returns permitted resource IDs
+    resolve_principal_attrs -- resolves JWT claims + enrichment -> Cedar attrs
+    set_resource_attribute_resolver -- register domain-specific resolver
+    set_principal_enricher  -- register principal enricher (org hierarchy, etc.)
+    ResourceAttributeResolver -- protocol for resource attr lookup
+    PrincipalEnricher       -- protocol for principal attr enrichment
+    PolicyEngine            -- Cedar policy evaluator (check, filter, reload)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# AuthN -- always available
+from sonnet_auth.context import build_auth_context, resolve_attributes, resolve_dot_path
+from sonnet_auth.jwt_validator import JwtCredentialValidator
+from sonnet_auth.settings import AuthMode, AuthnConfig, AuthSettings
+
+if TYPE_CHECKING:
+    # Expose Cedar types for static analysis tools (mypy, pyright, IDEs).
+    # These are lazily imported at runtime to avoid cedarpy dependency
+    # when only authn is used.
+    from sonnet_auth.authz import (
+        AuthzDeniedError,
+        PrincipalEnricher,
+        ResourceAttributeResolver,
+        check_authz,
+        filter_authz,
+        resolve_principal_attrs,
+        set_principal_enricher,
+        set_resource_attribute_resolver,
+    )
+    from sonnet_auth.policy_engine import PolicyEngine
+
+__all__ = [
+    # AuthN
+    "AuthMode",
+    "AuthnConfig",
+    "AuthSettings",
+    "JwtCredentialValidator",
+    "build_auth_context",
+    "resolve_attributes",
+    "resolve_dot_path",
+    # AuthZ (lazy -- imported on use to avoid cedarpy import at module level)
+    "AuthzDeniedError",
+    "PolicyEngine",
+    "PrincipalEnricher",
+    "ResourceAttributeResolver",
+    "check_authz",
+    "filter_authz",
+    "resolve_principal_attrs",
+    "set_principal_enricher",
+    "set_resource_attribute_resolver",
+]
+
+
+def __getattr__(name: str):
+    """Lazy imports for Cedar authz -- avoids cedarpy import when only using authn."""
+    if name == "PolicyEngine":
+        from sonnet_auth.policy_engine import PolicyEngine
+
+        return PolicyEngine
+    if name in (
+        "AuthzDeniedError",
+        "PrincipalEnricher",
+        "ResourceAttributeResolver",
+        "check_authz",
+        "filter_authz",
+        "resolve_principal_attrs",
+        "set_principal_enricher",
+        "set_resource_attribute_resolver",
+    ):
+        from sonnet_auth import authz
+
+        return getattr(authz, name)
+    raise AttributeError(f"module 'sonnet_auth' has no attribute {name!r}")

sonnet_auth/authz.py

@@ -0,0 +1,221 @@
+"""AuthZ helpers — one-liner authorization for REST handlers and MCP tools.
+
+This module is the single entry point for authorization checks. It hides
+all internal plumbing (claim resolution, principal enrichment, Cedar
+evaluation) behind two stable functions:
+
+  check_authz()   — raises 403 on deny, no-op if authz disabled
+  filter_authz()  — returns permitted resource IDs, returns all if disabled
+
+Resource attribute resolution is pluggable via ``ResourceAttributeResolver``.
+Register the consumer's implementation once at startup:
+
+    from sonnet_auth.authz import set_resource_attribute_resolver
+    set_resource_attribute_resolver(PropertiesCacheResolver())
+
+The caller API (check_authz / filter_authz) never changes regardless of the
+resolver, enrichment, or Cedar evaluation happening behind the scenes.
+
+Internal flow:
+  1. get_policy_engine()                  → engine or None (no-op if disabled)
+  2. get_current_auth()                   → AuthContext (identity from JWT)
+  3. resolve_attributes(claims, claim_map) → base attrs from token
+  4. PrincipalEnricher.enrich()           → enriched attrs (if registered)
+  5. resolver.resolve(type, id)           → resource attrs
+  6. engine.check() / engine.filter()    → Cedar evaluation
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from loguru import logger
+
+from sonnet_auth.context import resolve_attributes
+from sonnet_auth.policy_engine import PolicyEngine
+from sonnet_server.guards import get_current_auth
+from sonnet_server.services.registry import get_service_registry
+
+# ---------------------------------------------------------------------------
+# ResourceAttributeResolver — pluggable resource attribute lookup
+# ---------------------------------------------------------------------------
+
+
+class ResourceAttributeResolver(Protocol):
+    """Maps a resource type + ID to Cedar entity attributes.
+
+    Implement this protocol in each consumer and register it at startup
+    via ``set_resource_attribute_resolver()``. coco-rag's implementation
+    uses ``PropertiesCache`` backed by the PostgreSQL settings table.
+
+    Returns an empty dict when no attributes are found — Cedar policies
+    that require ABAC attributes will deny by default.
+    """
+
+    def resolve(self, resource_type: str, resource_id: str) -> dict[str, Any]: ...
+
+
+_resource_attribute_resolver: ResourceAttributeResolver | None = None
+
+
+def set_resource_attribute_resolver(resolver: ResourceAttributeResolver) -> None:
+    """Register the resource attribute resolver. Call once at startup."""
+    global _resource_attribute_resolver  # noqa: PLW0603
+    _resource_attribute_resolver = resolver
+
+
+# ---------------------------------------------------------------------------
+# PrincipalEnricher — pluggable principal attribute enrichment
+# ---------------------------------------------------------------------------
+
+
+class PrincipalEnricher(Protocol):
+    """Enriches resolved JWT claim attributes before Cedar evaluation.
+
+    Implement this protocol to add org hierarchy, group expansion, or remote
+    attribute lookups. Register it via ``set_principal_enricher()``.
+
+    The default (no enricher registered) is a no-op — attrs pass through
+    unchanged.
+    """
+
+    def enrich(self, user_id: str, attrs: dict[str, Any]) -> dict[str, Any]: ...
+
+
+_principal_enricher: PrincipalEnricher | None = None
+
+
+def set_principal_enricher(enricher: PrincipalEnricher) -> None:
+    """Register the principal enricher. Call once at startup."""
+    global _principal_enricher  # noqa: PLW0603
+    _principal_enricher = enricher
+
+
+# ---------------------------------------------------------------------------
+# Engine resolution
+# ---------------------------------------------------------------------------
+
+
+def get_policy_engine() -> PolicyEngine | None:
+    """Return PolicyEngine if authz enabled, None if not configured."""
+    try:
+        return get_service_registry().get(PolicyEngine)
+    except KeyError:
+        return None
+
+
+def resolve_principal_attrs(engine: PolicyEngine, user_id: str, claims: dict) -> dict[str, Any]:
+    """Resolve claim_map attrs and run principal enrichment.
+
+    Both ``claim_map`` and ``auto_map_claims`` come from the engine (set at
+    construction from AuthnConfig). No DB access — safe in tests and CI.
+
+    Public — used by the /authz/check dry-run endpoint.
+    """
+    attrs = resolve_attributes(claims, engine.claim_map, auto_map_claims=engine.auto_map_claims)
+    if _principal_enricher is not None:
+        attrs = _principal_enricher.enrich(user_id, attrs)
+    logger.trace("Principal attrs resolved: user={} attrs={}", user_id, attrs)
+    return attrs
+
+
+# ---------------------------------------------------------------------------
+# Resource attribute resolution
+# ---------------------------------------------------------------------------
+
+
+def _resolve_resource_attrs(resource_type: str, resource_id: str, resource_attrs: dict[str, Any] | None) -> dict[str, Any]:
+    """Resolve resource attributes — explicit attrs take priority, then resolver."""
+    if resource_attrs is not None:
+        return resource_attrs
+    if _resource_attribute_resolver is not None:
+        return _resource_attribute_resolver.resolve(resource_type, resource_id)
+    return {}
+
+
+# ---------------------------------------------------------------------------
+# Public API — stable forever
+# ---------------------------------------------------------------------------
+
+
+class AuthzDeniedError(Exception):
+    """Raised when Cedar policy evaluation denies an action.
+
+    Transport layers (REST, MCP) catch this and convert it to the appropriate
+    response -- ``HTTPException(403)`` for REST, a tool error for MCP.
+
+    In practice, sonnet-server's REST handlers register an exception handler
+    that converts ``AuthzDeniedError`` to 403, so callers that use
+    ``check_authz`` in REST handlers need not catch it explicitly.
+    """
+
+    def __init__(self, action: str, resource_type: str, resource_id: str) -> None:
+        super().__init__(f"Forbidden: {action} on {resource_type}/{resource_id}")
+        self.action = action
+        self.resource_type = resource_type
+        self.resource_id = resource_id
+
+
+def check_authz(
+    action: str,
+    resource_type: str,
+    resource_id: str,
+    resource_attrs: dict[str, Any] | None = None,
+) -> None:
+    """Check Cedar policy — raises AuthzDeniedError on deny, no-op if authz disabled.
+
+    Call at the top of any REST handler or MCP tool that accesses a resource.
+    Resource properties are resolved automatically via the registered
+    ``ResourceAttributeResolver`` unless ``resource_attrs`` is explicitly provided.
+
+    Callers in REST handlers do not need to catch ``AuthzDeniedError`` —
+    the transport layer converts it to HTTP 403 via the registered exception
+    handler. MCP tool handlers should catch it and return a tool error.
+    """
+    engine = get_policy_engine()
+    if not engine:
+        return
+    auth = get_current_auth()
+    principal_attrs = resolve_principal_attrs(engine, auth.user_id, auth.claims)
+    resolved_attrs = _resolve_resource_attrs(resource_type, resource_id, resource_attrs)
+    if not engine.check(auth.user_id, principal_attrs, action, resource_type, resource_id, resolved_attrs):
+        logger.info(
+            "AuthZ denied: user={} action={} resource={}/{}{}",
+            auth.user_id,
+            action,
+            resource_type,
+            resource_id,
+            f" resource_attrs={resolved_attrs}" if resolved_attrs else "",
+        )
+        raise AuthzDeniedError(action, resource_type, resource_id)
+
+
+def filter_authz(
+    action: str,
+    resource_type: str,
+    resources: list[tuple[str, dict[str, Any]]] | list[str],
+) -> set[str]:
+    """Filter to permitted resource IDs — returns all IDs if authz disabled.
+
+    Accepts either ``[(id, attrs), ...]`` or ``[id, ...]``. When attrs are
+    not provided, they are resolved automatically via the registered
+    ``ResourceAttributeResolver``. Enrichment is applied once per call.
+    """
+    if not resources:
+        return set()
+
+    engine = get_policy_engine()
+    if not engine:
+        if isinstance(resources[0], str):
+            return set(resources)
+        return {rid for rid, _ in resources}
+
+    # Normalise input to [(id, attrs)] pairs
+    if isinstance(resources[0], str):
+        pairs = [(rid, _resolve_resource_attrs(resource_type, rid, None)) for rid in resources]
+    else:
+        pairs = [(rid, _resolve_resource_attrs(resource_type, rid, attrs)) for rid, attrs in resources]
+
+    auth = get_current_auth()
+    principal_attrs = resolve_principal_attrs(engine, auth.user_id, auth.claims)
+    return set(engine.filter(auth.user_id, principal_attrs, action, resource_type, pairs))

sonnet_auth/context.py

@@ -0,0 +1,133 @@
+"""Shared claim-to-AuthContext mapping used by both REST and MCP transports.
+
+Both ``JwtCredentialValidator`` (REST) and ``AuthBridgeMiddleware`` (MCP)
+produce an ``AuthContext`` from a validated JWT's claim dict. This module
+centralises that mapping so any future field change requires a single edit.
+
+The OIDC-standard ``sub`` claim is always mapped to ``user_id``/``username``.
+Additional claims are extracted via ``claim_map`` (dot-path → attribute name)
+from ``AuthConfig``. Mapped attributes named ``email`` or ``tenant_id``
+populate the corresponding ``AuthContext`` fields; all others are available
+to the Cedar policy engine via ``resolve_attributes()``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any
+
+from sonnet_server.guards import AuthContext
+
+# JWT standard/registered claims excluded from auto-mapping — these are
+# protocol plumbing, not domain attributes meaningful to Cedar policies.
+_JWT_PLUMBING: frozenset[str] = frozenset({"sub", "iat", "exp", "nbf", "iss", "aud", "jti"})
+
+
+def resolve_dot_path(data: Mapping, path: str) -> Any | None:
+    """Walk a dot-delimited path into a nested mapping, returning None on miss.
+
+    Accepts any ``Mapping`` (dict, MappingProxyType, etc.) so callers can
+    pass raw JWT dicts or the frozen ``AuthContext.claims`` proxy directly.
+
+    **Limitation:** returns ``None`` both when a path is absent *and* when a
+    leaf value is explicitly ``None``. Callers cannot distinguish the two cases.
+    A claim value that is legitimately ``None`` in the JWT will be treated as
+    absent. This is an accepted constraint — JWT claims used as Cedar attributes
+    should carry a meaningful value; ``None`` is not a valid Cedar attribute value.
+
+    >>> resolve_dot_path({"a": {"b": [1, 2]}}, "a.b")
+    [1, 2]
+    >>> resolve_dot_path({"a": 1}, "a.b.c") is None
+    True
+    """
+    current: Any = data
+    for segment in path.split("."):
+        if not isinstance(current, Mapping):
+            return None
+        current = current.get(segment)
+        if current is None:
+            return None
+    return current
+
+
+_SENTINEL = object()
+
+
+def resolve_attributes(
+    claims: Mapping,
+    claim_map: dict[str, str],
+    auto_map_claims: bool = False,
+) -> dict[str, Any]:
+    """Resolve JWT claims to Cedar principal attributes.
+
+    When ``auto_map_claims`` is True, all top-level claims are included
+    as attributes using their original name (except ``sub``, ``iat``,
+    ``exp``, ``nbf``, ``iss``, ``aud``, ``jti`` which are JWT plumbing).
+    Falsy but present values (``False``, ``0``, ``[]``, ``""``) are included.
+    Explicit ``claim_map`` entries take priority over auto-mapped names,
+    allowing renames and dot-path extraction of nested claims.
+
+    When ``auto_map_claims`` is False (default), only claims listed in
+    ``claim_map`` are visible.
+    """
+    attrs: dict[str, Any] = {}
+
+    # Auto-map: pass through all top-level claims (except JWT plumbing).
+    # Include falsy-but-present values (e.g. active=False, count=0).
+    # Skip only None and absent keys.
+    if auto_map_claims:
+        for key, value in claims.items():
+            if key not in _JWT_PLUMBING and value is not None:
+                attrs[key] = value
+
+    # Explicit claim_map: overrides auto-mapped names, supports dot-paths.
+    # resolve_dot_path returns None for both absent keys and None values;
+    # we use a sentinel to distinguish "key present but falsy" from "key absent".
+    for attr_name, dot_path in claim_map.items():
+        # Walk the path manually to detect absent vs None leaf
+        current: Any = claims
+        found = True
+        for segment in dot_path.split("."):
+            if not isinstance(current, Mapping):
+                found = False
+                break
+            current = current.get(segment, _SENTINEL)
+            if current is _SENTINEL:
+                found = False
+                break
+        if found and current is not None:
+            attrs[attr_name] = current
+
+    return attrs
+
+
+def build_auth_context(
+    claims: dict,
+    claim_map: dict[str, str] | None = None,
+    auto_map_claims: bool = False,
+) -> AuthContext:
+    """Build an ``AuthContext`` from a validated JWT claim dict.
+
+    The OIDC-standard ``sub`` claim is always mapped to ``user_id`` and
+    ``username``. Additional claims are extracted via ``claim_map`` and
+    ``auto_map_claims``:
+
+    - ``email`` → ``AuthContext.email`` (when mapped)
+    - ``tenant_id`` → ``AuthContext.tenant_id`` (when mapped)
+    - All others remain available to Cedar via ``resolve_attributes()``
+      at evaluation time (re-derived from ``claims`` + ``claim_map``).
+
+    Precondition: ``claims`` must come from a token that has already been
+    validated (signature, expiry, issuer, audience).
+    """
+    sub = claims["sub"]
+    attrs = resolve_attributes(claims, claim_map or {}, auto_map_claims=auto_map_claims)
+
+    return AuthContext(
+        user_id=sub,
+        username=sub,
+        email=attrs.get("email"),
+        tenant_id=attrs.get("tenant_id"),
+        claims=MappingProxyType(claims),
+    )

sonnet_auth/jwt_validator.py

@@ -0,0 +1,136 @@
+"""JwtCredentialValidator — validates JWT bearer tokens against a JWKS endpoint.
+
+Uses joserfc (the successor to authlib.jose) — the same crypto library as
+FastMCP's JWTVerifier, ensuring consistent token validation across both
+REST and MCP transports.
+
+JWKS keys are fetched synchronously at construction time. If the JWKS
+endpoint is unreachable at startup, the validator starts with no keys
+and returns None (→ 401) for every request until the TTL-based refresh
+succeeds. This avoids a hard startup failure when the IdP is temporarily
+unavailable during rolling deploys.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+import httpx
+from joserfc import jwt as joserfc_jwt
+from joserfc.errors import JoseError
+from joserfc.jwk import KeySet
+from loguru import logger
+
+from sonnet_auth.context import build_auth_context
+from sonnet_server.guards import AuthContext, CredentialValidator
+
+if TYPE_CHECKING:
+    from sonnet_auth.settings import AuthConfig
+
+# JWKS cache TTL in seconds — keys are re-fetched after this interval
+_JWKS_CACHE_TTL = 3600
+
+
+class JwtCredentialValidator(CredentialValidator):
+    """Validates JWT bearer tokens (RS256/ES256) against a JWKS endpoint.
+
+    Uses joserfc for consistent crypto with FastMCP's JWTVerifier.
+    The ``jwks_client`` parameter is injectable for testing.
+
+    Precondition: ``auth_config.jwks_uri`` must be non-None and HTTPS.
+    This is enforced by ``AuthSettings`` validation before construction.
+    """
+
+    def __init__(
+        self,
+        auth_config: AuthConfig,
+        *,
+        key_set: KeySet | None = None,
+    ) -> None:
+        if not auth_config.jwks_uri:
+            raise ValueError("JwtCredentialValidator requires auth_config.jwks_uri to be set")
+        self._jwks_uri = auth_config.jwks_uri
+        self._issuer = auth_config.issuer
+        self._audience = auth_config.audience
+        self._claim_map: dict[str, str] = auth_config.claim_map
+        self._auto_map_claims: bool = auth_config.auto_map_claims
+
+        if key_set is not None:
+            # Injected key set (tests) — skip network fetch
+            self._key_set: KeySet | None = key_set
+        else:
+            try:
+                self._key_set = self._fetch_key_set()
+            except RuntimeError as exc:
+                # JWKS endpoint unreachable at startup — start with no keys.
+                # All requests return 401 until the TTL refresh succeeds.
+                logger.warning("JWKS fetch failed at startup — all requests will return 401 until resolved: {}", exc)
+                self._key_set = None
+
+        self._key_set_fetched_at = time.monotonic()
+
+    def _fetch_key_set(self) -> KeySet:
+        """Fetch JWKS from the configured endpoint synchronously."""
+        try:
+            response = httpx.get(self._jwks_uri, timeout=10.0)
+            response.raise_for_status()
+            key_set = KeySet.import_key_set(response.json())
+            logger.trace("JWKS fetched successfully — {} key(s)", len(key_set.keys))
+            return key_set
+        except httpx.HTTPError as exc:
+            raise RuntimeError(f"Failed to fetch JWKS from {self._jwks_uri}: {exc}") from exc
+
+    def _get_key_set(self) -> KeySet | None:
+        """Return cached key set, refreshing if TTL has expired or no keys yet."""
+        if self._key_set is None or time.monotonic() - self._key_set_fetched_at > _JWKS_CACHE_TTL:
+            logger.debug("Fetching JWKS from {} ({})", self._jwks_uri, "retry" if self._key_set is None else "TTL expired")
+            try:
+                self._key_set = self._fetch_key_set()
+                self._key_set_fetched_at = time.monotonic()
+            except RuntimeError as exc:
+                if self._key_set is not None:
+                    logger.warning("JWKS refresh failed, using cached keys: {}", exc)
+                else:
+                    logger.warning("JWKS fetch failed — all requests will return 401: {}", exc)
+        return self._key_set
+
+    def validate(self, bearer_token: str) -> AuthContext | None:
+        """Validate a bearer token. Returns AuthContext on success, None on failure.
+
+        Returns None (→ 401) if no JWKS keys are available yet.
+        """
+        try:
+            key_set = self._get_key_set()
+            if key_set is None:
+                logger.debug("JWT validation skipped — no JWKS keys available")
+                return None
+            token = joserfc_jwt.decode(bearer_token, key_set, algorithms=["RS256", "ES256"])
+
+            claims_registry = joserfc_jwt.JWTClaimsRegistry(
+                sub={"essential": True},
+                exp={"essential": True},
+                **({} if self._issuer is None else {"iss": {"essential": True, "value": self._issuer}}),
+                **({} if self._audience is None else {"aud": {"essential": True, "value": self._audience}}),
+            )
+            claims_registry.validate(token.claims)
+
+            ctx = build_auth_context(token.claims, self._claim_map, auto_map_claims=self._auto_map_claims)
+            logger.trace(
+                "JWT validated: user={} iss={} aud={}",
+                ctx.user_id,
+                token.claims.get("iss"),
+                token.claims.get("aud"),
+            )
+            return ctx
+        except JoseError as exc:
+            logger.debug("JWT validation failed: {}", exc)
+            return None
+        except RuntimeError as exc:
+            logger.warning("JWKS error during token validation: {}", exc)
+            return None
+        except (KeyError, AttributeError) as exc:
+            # Configuration error (e.g. malformed claim_map, unexpected claims shape).
+            # Re-raise so misconfigurations surface clearly rather than silently
+            # producing 401 responses that look like invalid tokens.
+            raise RuntimeError(f"Auth configuration error during token validation: {exc}") from exc

sonnet_auth/policy_engine.py

@@ -0,0 +1,230 @@
+"""PolicyEngine — Cedar-based authorization evaluation.
+
+Pure evaluator: receives validated policies + schema at construction,
+performs no I/O. Loading from the settings table is the caller's
+responsibility (see services/di.py).
+
+The engine exposes two operations:
+
+  check()   — permit/deny a single (principal, action, resource) triple
+  filter()  — from a list of (resource_id, resource_attrs) pairs, return
+               only the IDs the principal is permitted to act on.
+               Uses is_authorized_batch() internally — one Cedar call for
+               the entire list, not N individual calls.
+
+Principal attributes and resource attributes are always provided by the
+caller (authz helpers). The engine never resolves claims, never runs
+enrichers, never fetches anything — it is a pure function of its inputs.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cedarpy import is_authorized, is_authorized_batch, validate_policies
+from loguru import logger
+
+# Cedar entity type name for principals — must match the schema
+_TYPE_USER = "User"
+
+
+class PolicyEngine:
+    """Cedar policy evaluator.
+
+    Construction validates policies against the schema and raises
+    ``ValueError`` immediately if validation fails — fail fast at startup,
+    not at first request.
+
+    Stores ``claim_map`` as a read-only property for the authz helpers to
+    read — the engine itself never uses it.
+    """
+
+    def __init__(
+        self,
+        policies: str,
+        schema: str,
+        claim_map: dict[str, str] | None = None,
+        auto_map_claims: bool = False,
+    ) -> None:
+        result = validate_policies(policies, schema)
+        if not result.validation_passed:
+            raise ValueError(f"Cedar policy validation failed: {result.errors}")
+
+        self._policies = policies
+        self._claim_map: dict[str, str] = claim_map or {}
+        self._auto_map_claims: bool = auto_map_claims
+        logger.info("PolicyEngine initialised — Cedar policies validated successfully")
+
+    @property
+    def claim_map(self) -> dict[str, str]:
+        """JWT claim dot-paths → Cedar attribute names. Read by authz helpers."""
+        return self._claim_map
+
+    @property
+    def auto_map_claims(self) -> bool:
+        """Whether to pass all top-level JWT claims as Cedar attributes. Read by authz helpers."""
+        return self._auto_map_claims
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def reload(self, policies: str, schema: str) -> None:
+        """Replace policies and schema. Validates before swapping — old policies
+        stay active if validation fails.
+
+        Raises:
+            ValueError: If the new policies fail validation against the schema.
+        """
+        result = validate_policies(policies, schema)
+        if not result.validation_passed:
+            raise ValueError(f"Cedar policy validation failed: {result.errors}")
+        self._policies = policies
+        logger.info("PolicyEngine reloaded — new Cedar policies validated and active")
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def check(
+        self,
+        user_id: str,
+        principal_attrs: dict[str, Any],
+        action: str,
+        resource_type: str,
+        resource_id: str,
+        resource_attrs: dict[str, Any] | None = None,
+    ) -> bool:
+        """Return True if the principal is permitted to perform action on resource.
+
+        Args:
+            user_id:         Principal entity ID (from AuthContext.user_id).
+            principal_attrs: Pre-built principal attributes (from authz helpers).
+            action:          Cedar action name (e.g. "search", "configure").
+            resource_type:   Cedar entity type (e.g. "Topic", "Source").
+            resource_id:     Resource identifier (e.g. "backend", "my-repo").
+            resource_attrs:  Resource attributes for ABAC. Empty dict or None for RBAC.
+        """
+        entities = [
+            _build_principal_entity(user_id, principal_attrs),
+            _build_resource_entity(resource_type, resource_id, resource_attrs or {}),
+        ]
+        request = _build_request(user_id, action, resource_type, resource_id)
+        logger.trace(
+            "Cedar check: principal={} principal_attrs={} action={} resource={}/{} resource_attrs={}",
+            user_id,
+            principal_attrs,
+            action,
+            resource_type,
+            resource_id,
+            resource_attrs or {},
+        )
+        result = is_authorized(request, self._policies, entities)
+
+        decision = "ALLOW" if result.allowed else "DENY"
+        logger.debug(
+            "PolicyEngine.check: user={} action={} resource={}/{} → {}",
+            user_id,
+            action,
+            resource_type,
+            resource_id,
+            decision,
+        )
+        if not result.allowed:
+            logger.trace("PolicyEngine deny diagnostics: {}", result.diagnostics)
+        return result.allowed
+
+    def filter(
+        self,
+        user_id: str,
+        principal_attrs: dict[str, Any],
+        action: str,
+        resource_type: str,
+        resources: list[tuple[str, dict[str, Any]]],
+    ) -> list[str]:
+        """Return the subset of resource IDs the principal is permitted to act on.
+
+        Uses is_authorized_batch() for efficiency — one Cedar evaluation
+        call regardless of list length.
+
+        Args:
+            user_id:         Principal entity ID.
+            principal_attrs: Pre-built principal attributes.
+            action:          Cedar action name.
+            resource_type:   Cedar entity type ("Topic" or "Source").
+            resources:       List of (resource_id, resource_attrs) pairs.
+
+        Returns:
+            List of permitted resource IDs (preserves input order).
+        """
+        if not resources:
+            return []
+
+        entities = [_build_principal_entity(user_id, principal_attrs)] + [
+            _build_resource_entity(resource_type, rid, attrs) for rid, attrs in resources
+        ]
+        requests = [_build_request(user_id, action, resource_type, rid) for rid, _ in resources]
+        logger.trace(
+            "Cedar filter: principal={} principal_attrs={} action={} type={} resources={}",
+            user_id,
+            principal_attrs,
+            action,
+            resource_type,
+            [(rid, attrs) for rid, attrs in resources],
+        )
+        results = is_authorized_batch(requests=requests, policies=self._policies, entities=entities)
+        permitted = [rid for (rid, _), result in zip(resources, results, strict=True) if result.allowed]
+
+        logger.debug(
+            "PolicyEngine.filter: user={} action={} type={} total={} permitted={}",
+            user_id,
+            action,
+            resource_type,
+            len(resources),
+            len(permitted),
+        )
+        if len(permitted) < len(resources):
+            denied = [rid for rid in (r[0] for r in resources) if rid not in set(permitted)]
+            logger.trace("PolicyEngine filter denied resources: {}", denied)
+        return permitted
+
+
+# ------------------------------------------------------------------
+# Entity / request builders (module-level — no state, easy to test)
+# ------------------------------------------------------------------
+
+
+def _build_principal_entity(user_id: str, attrs: dict[str, Any]) -> dict:
+    """Build a Cedar User entity from pre-built attributes."""
+    return {
+        "uid": {"__entity": {"type": _TYPE_USER, "id": user_id}},
+        "attrs": attrs,
+        "parents": [],
+    }
+
+
+def _build_resource_entity(resource_type: str, resource_id: str, attrs: dict[str, Any]) -> dict:
+    """Build a Cedar resource entity (Topic, Source, etc.)."""
+    return {
+        "uid": {"__entity": {"type": resource_type, "id": resource_id}},
+        "attrs": attrs,
+        "parents": [],
+    }
+
+
+def _build_request(user_id: str, action: str, resource_type: str, resource_id: str) -> dict:
+    """Build a Cedar authorization request dict.
+
+    Cedar entity references use ``Type::"id"`` syntax — embedded double
+    quotes would break parsing.  User-controlled values (user_id from JWT
+    ``sub``, resource_id from tool args) are checked defensively here.
+    """
+    for name, value in (("user_id", user_id), ("resource_id", resource_id)):
+        if '"' in value:
+            raise ValueError(f"Cedar entity ID must not contain double quotes: {name}={value!r}")
+    return {
+        "principal": f'{_TYPE_USER}::"{user_id}"',
+        "action": f'Action::"{action}"',
+        "resource": f'{resource_type}::"{resource_id}"',
+        "context": {},
+    }

sonnet_auth/settings.py

@@ -0,0 +1,254 @@
+"""AuthSettings — typed auth configuration with env var + optional seed resolution.
+
+Resolution per field (example with prefix ``COCO_RAG_``):
+  env var COCO_RAG_AUTHN_ENABLED > seed value (e.g. from DB) > default.
+
+The env prefix is passed explicitly to ``AuthSettings.resolve()`` so the
+same model works for any consumer (COCO_RAG_, COCO_GRAPH_, ATLAS_, …).
+No module-level mutable state — safe to call from any context.
+
+Seed key contract (what callers pass to resolve()):
+  ``authn_enabled`` (bool) — AuthN toggle
+  ``authn_config``  (dict) — AuthN config blob (validated by AuthnConfig)
+  ``authz_enabled`` (bool) — AuthZ toggle
+
+DB storage keys (coco-rag settings table):
+  authn_enabled         — flat boolean (AuthN toggle / emergency kill switch)
+  authn_config          — JSON object: AuthN config (jwks_uri, issuer, audience,
+                          mode, claim_map, auto_map_claims, mcp_base_url,
+                          upstream_* fields)
+  authz_enabled         — flat boolean (AuthZ / Cedar toggle)
+  authz_cedar_policies  — text: Cedar policy source
+  authz_cedar_schema    — text: Cedar schema source
+
+CLI usage:
+  coco-rag settings set authn_enabled true
+  coco-rag settings set authn_config '{"jwks_uri": "...", "issuer": "...", "audience": "..."}'
+  coco-rag settings set authz_enabled true
+  coco-rag settings set-text authz_cedar_policies --file policies.cedar
+  coco-rag settings set-text authz_cedar_schema   --file schema.cedarschema
+
+Future (Phase 4 — atlas bundle pull):
+  ``authz_config``  (dict) — AuthZ config blob (AuthzConfig, when added)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from enum import StrEnum
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator, model_validator
+
+
+def _validate_https_url(v: str | None, *, env_prefix: str = "") -> str | None:
+    """Validate URL uses HTTPS with a non-empty host. Preserves value as-is (no normalisation).
+
+    ``{env_prefix}AUTHN_ALLOW_HTTP=true`` relaxes to HTTP for test environments
+    (localhost only). For example: ``COCO_RAG_AUTHN_ALLOW_HTTP=true``.
+    """
+    if v is None:
+        return None
+    from urllib.parse import urlparse
+
+    parsed = urlparse(v)
+    allow_http = os.environ.get(f"{env_prefix}AUTHN_ALLOW_HTTP", "").lower() in ("true", "1")
+
+    if allow_http:
+        if parsed.scheme not in ("http", "https") or not parsed.hostname:
+            raise ValueError(f"URL must use HTTP(S) with a valid host: {v!r}")
+        if parsed.scheme == "http" and parsed.hostname not in ("localhost", "127.0.0.1"):
+            raise ValueError(f"HTTP is only allowed for localhost in test mode: {v!r}")
+        return v
+
+    if parsed.scheme != "https" or not parsed.hostname:
+        raise ValueError(f"URL must use HTTPS with a valid host: {v!r}")
+    return v
+
+
+class AuthMode(StrEnum):
+    JWT_VERIFIER = "jwt_verifier"
+    OAUTH_PROXY = "oauth_proxy"
+
+
+class AuthnConfig(BaseModel):
+    """JWT/JWKS authentication configuration.
+
+    Stored as the ``auth_config`` settings key. All fields that must be
+    consistent live here. The enable/disable toggle is a separate flat key
+    (``auth_enabled``) so it can be flipped independently.
+
+    MCP-specific fields (``mcp_base_url``, ``upstream_*``, ``mode``) are
+    included here because the MCP auth provider is constructed from this
+    config. Services without MCP leave these fields at their defaults.
+
+    Instances are frozen — post-construction mutation raises ValidationError.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    jwks_uri: str | None = None
+    issuer: str | None = None
+    audience: str | None = None
+    mode: AuthMode = AuthMode.JWT_VERIFIER
+
+    # Claim mapping — controls how JWT claims become AuthContext fields and
+    # Cedar principal attributes. Shared by both authn and authz layers.
+    auto_map_claims: bool = False
+    claim_map: dict[str, str] = Field(default_factory=dict)
+
+    # MCP auth provider — public base URL for RFC 9728 metadata endpoint.
+    # Required when mode=jwt_verifier and an MCP server is active.
+    # Required when mode=oauth_proxy.
+    mcp_base_url: str | None = None
+
+    # OAuthProxy-only (when mode="oauth_proxy")
+    upstream_authorization_endpoint: str | None = None
+    upstream_token_endpoint: str | None = None
+    upstream_client_id: str | None = None
+    upstream_client_secret: SecretStr | None = None
+
+    # Env var suffixes (without prefix) mapped to field names.
+    # Used by AuthSettings.resolve() to apply per-field env var overrides.
+    # Full env var: {prefix}AUTHN_{SUFFIX} e.g. COCO_RAG_AUTHN_JWKS_URI
+    _ENV_SUFFIXES: ClassVar[dict[str, str]] = {
+        "AUTHN_JWKS_URI": "jwks_uri",
+        "AUTHN_ISSUER": "issuer",
+        "AUTHN_AUDIENCE": "audience",
+        "AUTHN_MODE": "mode",
+        "AUTHN_AUTO_MAP_CLAIMS": "auto_map_claims",
+        "AUTHN_CLAIM_MAP": "claim_map",
+        "AUTHN_MCP_BASE_URL": "mcp_base_url",
+        "AUTHN_UPSTREAM_AUTHORIZATION_ENDPOINT": "upstream_authorization_endpoint",
+        "AUTHN_UPSTREAM_TOKEN_ENDPOINT": "upstream_token_endpoint",
+        "AUTHN_UPSTREAM_CLIENT_ID": "upstream_client_id",
+        "AUTHN_UPSTREAM_CLIENT_SECRET": "upstream_client_secret",
+    }
+
+    @field_validator(
+        "jwks_uri", "issuer", "mcp_base_url", "upstream_authorization_endpoint", "upstream_token_endpoint", mode="before"
+    )
+    @classmethod
+    def _require_https(cls, v: str | None) -> str | None:
+        # The field validator has no access to the env prefix. It enforces
+        # HTTPS strictly and respects the bare AUTHN_ALLOW_HTTP env var (no
+        # prefix). Callers that need prefix-aware allow-HTTP (e.g. test
+        # environments using COCO_RAG_AUTHN_ALLOW_HTTP) must use
+        # AuthSettings.resolve(), which applies the prefix before building
+        # the model. Direct construction (e.g. in tests) should either use
+        # HTTPS URLs or set the unprefixed AUTHN_ALLOW_HTTP env var.
+        return _validate_https_url(v)
+
+    @model_validator(mode="after")
+    def _validate_oauth_proxy_fields(self) -> AuthnConfig:
+        if self.mode == AuthMode.OAUTH_PROXY:
+            missing = [
+                f
+                for f in ("mcp_base_url", "upstream_authorization_endpoint", "upstream_token_endpoint", "upstream_client_id")
+                if not getattr(self, f)
+            ]
+            if missing:
+                raise ValueError(f"oauth_proxy mode requires: {', '.join(missing)}")
+        return self
+
+
+class AuthSettings(BaseModel):
+    """Complete auth settings: authn toggle + config, authz toggle.
+
+    Instances are frozen — post-construction mutation raises ValidationError.
+
+    Note: AuthzConfig will be added in Phase 4 when atlas bundle pull
+    fields (atlas_url, bundle_ttl) exist. Adding an empty model now would
+    be structural noise with no current value.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    enabled: bool = False
+    config: AuthnConfig = Field(default_factory=AuthnConfig)
+    authz_enabled: bool = False
+
+    @model_validator(mode="after")
+    def _validate_enabled_requires_config(self) -> AuthSettings:
+        """When auth is enabled, jwks_uri, issuer, and audience are all required."""
+        if self.enabled:
+            missing = [f for f in ("jwks_uri", "issuer", "audience") if not getattr(self.config, f)]
+            if missing:
+                raise ValueError(f"auth_enabled=true requires auth_config fields: {', '.join(missing)}")
+        return self
+
+    @classmethod
+    def resolve(cls, *, env_prefix: str = "", seed: dict[str, Any] | None = None) -> AuthSettings:
+        """Build AuthSettings from env vars with optional seed values.
+
+        Args:
+            env_prefix: Env var prefix for this consumer, e.g. ``"COCO_RAG_"``.
+            seed: Optional pre-loaded values (e.g. from a DB settings table).
+                  Expected keys:
+                    ``authn_enabled`` (bool)  — AuthN toggle
+                    ``authn_config``  (dict)  — AuthN config blob (AuthnConfig)
+                    ``authz_enabled`` (bool)  — AuthZ toggle
+                  Per-field resolution: env var > seed value > default.
+                  Unexpected keys are ignored with a warning logged.
+        """
+        from loguru import logger
+
+        seed = seed or {}
+
+        unexpected = set(seed) - {"authn_enabled", "authn_config", "authz_enabled"}
+        if unexpected:
+            logger.warning("AuthSettings.resolve: unexpected seed keys ignored: {}", sorted(unexpected))
+
+        enabled = _resolve(env_prefix, "AUTHN_ENABLED", seed.get("authn_enabled"), default=False)
+        authz_enabled = _resolve(env_prefix, "AUTHZ_ENABLED", seed.get("authz_enabled"), default=False)
+
+        seed_config = seed.get("authn_config")
+        if seed_config is None:
+            seed_config = {}
+        elif not isinstance(seed_config, dict):
+            logger.warning("AuthSettings.resolve: authn_config is not a dict ({}), ignoring", type(seed_config).__name__)
+            seed_config = {}
+
+        config_data = dict(seed_config)
+        for suffix, field in AuthnConfig._ENV_SUFFIXES.items():
+            _override_from_env(config_data, field, env_prefix, suffix)
+
+        return cls(
+            enabled=enabled,
+            config=AuthnConfig.model_validate(config_data),
+            authz_enabled=authz_enabled,
+        )
+
+
+def _resolve(env_prefix: str, env_suffix: str, seed_value: Any, *, default: Any = None) -> Any:
+    """Return env var value if set, else seed value, else default."""
+    env_val = os.environ.get(f"{env_prefix}{env_suffix}")
+    if env_val is not None:
+        return _parse_env_value(env_val)
+    if seed_value is not None:
+        return seed_value
+    return default
+
+
+def _override_from_env(config_data: dict, field: str, env_prefix: str, env_suffix: str) -> None:
+    """Override a single field in config_data if the env var is set."""
+    env_val = os.environ.get(f"{env_prefix}{env_suffix}")
+    if env_val is not None:
+        config_data[field] = _parse_env_value(env_val)
+
+
+def _parse_env_value(val: str) -> Any:
+    """Parse an env var string into a Python value."""
+    lower = val.lower()
+    if lower in ("true", "1", "yes"):
+        return True
+    if lower in ("false", "0", "no"):
+        return False
+    try:
+        result = json.loads(val)
+        if result is None:
+            raise ValueError("Env var value 'null' is not supported — unset the variable to use the default")
+        return result
+    except json.JSONDecodeError:
+        return val

sonnet_auth-0.1.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: sonnet-auth
+Version: 0.1.0
+Summary: JWT/JWKS authentication and Cedar authorization for sonnet-server applications
+Author-email: Wolfgang Miller <wolfgang.miller@petrarca-labs.com>
+License-Expression: Apache-2.0
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <4.0,>=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: sonnet-server>=0.1.9
+Requires-Dist: joserfc>=1.0.0
+Requires-Dist: httpx>=0.28.0
+Provides-Extra: cedar
+Requires-Dist: cedarpy>=4.0.0; extra == "cedar"
+Provides-Extra: dev
+Requires-Dist: sonnet-auth[cedar]; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: testcontainers[keycloak]>=4.0; extra == "dev"
+
+# Sonnet Auth
+
+JWT/JWKS authentication and Cedar authorization for sonnet-server
+applications. No FastMCP dependency -- MCP auth wiring lives in each
+domain service.
+
+## What it provides
+
+- **JWT/JWKS validation** -- `JwtCredentialValidator` implements
+  sonnet-server's `CredentialValidator` protocol. RS256/ES256 with
+  TTL-based JWKS key refresh and graceful degradation on IdP outages.
+- **Claim mapping** -- configurable dot-path extraction from JWT claims
+  to `AuthContext` fields and Cedar principal attributes.
+  `auto_map_claims` mode passes all non-plumbing claims automatically.
+- **Cedar policy evaluation** (optional `[cedar]` extra) -- `PolicyEngine`
+  wraps cedarpy for in-process RBAC/ABAC. `check_authz()` and
+  `filter_authz()` are one-liner authorization for REST and MCP handlers.
+- **Pluggable resource resolution** -- `ResourceAttributeResolver` protocol
+  for domain-specific Cedar resource attributes.
+- **Settings model** -- `AuthSettings.resolve(env_prefix, seed)` with
+  per-field env var overrides and optional DB seeding. No global state.
+
+## Install
+
+```bash
+# JWT authentication only
+pip install sonnet-auth
+
+# JWT + Cedar authorization
+pip install sonnet-auth[cedar]
+```
+
+## Prerequisites
+
+- Python 3.14+
+- sonnet-server >= 0.1.9
+
+## Usage
+
+### AuthN only (JWT/JWKS)
+
+```python
+from sonnet_auth import AuthSettings, JwtCredentialValidator
+from sonnet_server.guards import set_credential_validator
+
+auth = AuthSettings.resolve(env_prefix="MY_APP_")
+if auth.enabled:
+    set_credential_validator(JwtCredentialValidator(auth.config))
+```
+
+Configuration via env vars:
+
+```
+MY_APP_AUTHN_ENABLED=true
+MY_APP_AUTHN_JWKS_URI=https://idp.example.com/.well-known/jwks.json
+MY_APP_AUTHN_ISSUER=https://idp.example.com
+MY_APP_AUTHN_AUDIENCE=my-app
+```
+
+Or with DB seeding (coco-rag pattern):
+
+```python
+seed = {
+    "authn_enabled": svc.get("authn_enabled"),
+    "authn_config": svc.get("authn_config"),
+    "authz_enabled": svc.get("authz_enabled"),
+}
+auth = AuthSettings.resolve(env_prefix="COCO_RAG_", seed=seed)
+```
+
+### AuthZ (Cedar policies)
+
+```python
+from sonnet_auth import check_authz, filter_authz, set_resource_attribute_resolver
+
+# Register domain-specific resource resolver
+set_resource_attribute_resolver(MyResolver())
+
+# In any REST handler or MCP tool
+check_authz("search", "Source", source_name)  # raises AuthzDeniedError on deny
+
+# For list operations
+permitted = filter_authz("list", "Source", source_names)
+```
+
+## Package structure
+
+```
+src/sonnet_auth/
+    __init__.py          # public API with lazy Cedar imports
+    settings.py          # AuthSettings, AuthnConfig
+    context.py           # JWT claim -> AuthContext mapping
+    jwt_validator.py     # JwtCredentialValidator (JWKS)
+    policy_engine.py     # Cedar PolicyEngine [cedar extra]
+    authz.py             # check_authz, filter_authz [cedar extra]
+```
+
+## License
+
+Apache License 2.0

sonnet_auth-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sonnet_auth/__init__.py,sha256=q-E3Zf6i7PAxUIQ_6-56jqwcm66qe5qpOYWEVqIqsHs,3335
+sonnet_auth/authz.py,sha256=TVoNBGZjQ4NtDgT2CapL_8BRaWTN4QtUkxCxvGwMuXg,8797
+sonnet_auth/context.py,sha256=RTtOfMDsVIForXipFKnCCvfVZXLy81eZzMqhPoqNO-4,5156
+sonnet_auth/jwt_validator.py,sha256=zU0Xfr9dAHVHe7fQEljQjxnJv5Pqkxm94mtgpAXV_dg,5920
+sonnet_auth/policy_engine.py,sha256=EuLFbQnWuiLkpQRM7SAUod_npJjLlL5cJNc4JsH0Qcs,8829
+sonnet_auth/settings.py,sha256=vVHHEUPmcEOXZEBPkZo4iftO8RgslcQjkVLQaThQqEI,10595
+sonnet_auth-0.1.0.dist-info/METADATA,sha256=oSf9SjnukRBuH0QuId8hg1CsWrLQoEhgdBGDpunO3Z0,3827
+sonnet_auth-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sonnet_auth-0.1.0.dist-info/top_level.txt,sha256=7FcXKvjjxrmHdmUjoKgHEN6l8Of_LVsT1jieOYMtgWM,12
+sonnet_auth-0.1.0.dist-info/RECORD,,

sonnet_auth-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sonnet_auth-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sonnet_auth