sonnet-auth 0.1.0__tar.gz

sonnet_auth-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,100 @@
+# 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/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sonnet-auth"
+version = "0.1.0"
+authors = [
+    { name = "Wolfgang Miller", email = "wolfgang.miller@petrarca-labs.com" },
+]
+description = "JWT/JWKS authentication and Cedar authorization for sonnet-server applications"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.14,<4.0"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "sonnet-server>=0.1.9",
+    "joserfc>=1.0.0",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+cedar = [
+    "cedarpy>=4.0.0",
+]
+dev = [
+    "sonnet-auth[cedar]",
+    "ruff>=0.3.0",
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.23.0",
+    "testcontainers[keycloak]>=4.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+markers = [
+    "unit: marks tests as unit tests (default)",
+    "integration: marks tests as integration tests",
+]
+testpaths = ["tests"]
+addopts = [
+    "-m unit",
+    "--strict-markers",
+]
+asyncio_mode = "auto"
+filterwarnings = [
+    "ignore:.*wait_container_is_ready.*:DeprecationWarning",
+    "ignore:.*wait_for_logs.*:DeprecationWarning",
+]

sonnet_auth-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sonnet_auth-0.1.0/src/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-0.1.0/src/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))