cpkit 0.1.0__py3-none-any.whl

cpkit/auth/bundle.py

@@ -0,0 +1,113 @@
+"""Bundled authentication wiring for cpkit FastAPI apps."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import APIRouter
+
+from cpkit.audit import create_audit_event_hook
+
+from .dependencies import AuthDependencies, create_auth_dependencies
+from .oidc import OIDCManager
+from .router import create_oidc_router
+from .secrets import decrypt_secret, encrypt_secret, validate_secret_crypto_config
+from .types import OIDCSessionRecord
+
+DEFAULT_OIDC_SESSION_COOKIE_NAME = "cp_session"
+DEFAULT_READONLY_ROLES = ("CP_READONLY",)
+DEFAULT_USER_ROLES = ("CP_USER", "CP_ADMIN")
+DEFAULT_ADMIN_ROLES = ("CP_ADMIN",)
+
+
+@dataclass(frozen=True)
+class AuthBundle:
+    """Standard auth objects for a cpkit app."""
+
+    oidc: OIDCManager
+    dependencies: AuthDependencies
+    router: APIRouter
+
+    @property
+    def require_authenticated(self):
+        return self.dependencies.require_authenticated
+
+    @property
+    def require_user(self):
+        return self.dependencies.require_user
+
+    @property
+    def require_readonly(self):
+        return self.dependencies.require_readonly
+
+    @property
+    def require_admin(self):
+        return self.dependencies.require_admin
+
+    @property
+    def get_access_scope(self):
+        return self.dependencies.get_access_scope
+
+    @property
+    def get_audit_actor(self):
+        return self.dependencies.get_audit_actor
+
+
+def create_auth_bundle(
+    *,
+    get_repo: Callable[..., Any],
+    audit_record_factory: Callable[..., Any],
+    session_cookie_name: str = DEFAULT_OIDC_SESSION_COOKIE_NAME,
+    readonly_roles: tuple[Any, ...] = DEFAULT_READONLY_ROLES,
+    user_roles: tuple[Any, ...] = DEFAULT_USER_ROLES,
+    admin_roles: tuple[Any, ...] = DEFAULT_ADMIN_ROLES,
+    login_event: str = "LOGIN",
+    logout_event: str = "LOGOUT",
+    missing_api_key_headers_detail: str = (
+        "X-CP-Access-Key, X-CP-Signature, and X-Timestamp are required."
+    ),
+) -> AuthBundle:
+    """Create standard OIDC/API-key auth for a cpkit application."""
+    oidc = OIDCManager(
+        encrypt_secret=encrypt_secret,
+        decrypt_secret=decrypt_secret,
+        session_record_factory=OIDCSessionRecord,
+        session_cookie_name=session_cookie_name,
+        validate_secret_crypto_config=validate_secret_crypto_config,
+        missing_api_key_headers_detail=missing_api_key_headers_detail,
+    )
+    dependencies = create_auth_dependencies(
+        oidc,
+        get_repo=get_repo,
+        session_cookie_name=session_cookie_name,
+        readonly_roles=readonly_roles,
+        user_roles=user_roles,
+        admin_roles=admin_roles,
+    )
+    emit_auth_event = create_audit_event_hook(
+        audit_record_factory,
+        best_effort=False,
+    )
+
+    def log_auth_event(
+        repo: Any,
+        actor_id: str,
+        action: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        event_type = login_event if action == "LOGIN" else logout_event
+        emit_auth_event(
+            repo,
+            actor_id,
+            event_type,
+            details,
+        )
+
+    router = create_oidc_router(
+        oidc,
+        get_repo=get_repo,
+        require_authenticated=dependencies.require_authenticated,
+        get_audit_actor=dependencies.get_audit_actor,
+        audit_event_hook=log_auth_event,
+    )
+    return AuthBundle(oidc=oidc, dependencies=dependencies, router=router)

cpkit/auth/claims.py

@@ -0,0 +1,37 @@
+"""Claim normalization helpers."""
+
+from typing import Any
+
+from cpkit.config import safe_csv_set
+
+
+def claim_groups(claim_value: Any) -> set[str]:
+    """Normalize a groups claim into a trimmed set of group names."""
+    if claim_value is None:
+        return set()
+    if isinstance(claim_value, str):
+        return (
+            safe_csv_set(claim_value)
+            if "," in claim_value
+            else ({claim_value.strip()} if claim_value.strip() else set())
+        )
+    if isinstance(claim_value, (list, tuple, set)):
+        return {str(v).strip() for v in claim_value if str(v).strip()}
+    return set()
+
+
+def claims_groups(
+    claims: dict[str, Any], groups_claim_name: str = "groups"
+) -> set[str]:
+    """Extract the configured groups claim from a JWT or synthetic claims payload."""
+    return claim_groups(claims.get(groups_claim_name))
+
+
+def jsonable_role_groups(role_groups: dict[Any, Any]) -> dict[str, list[str]]:
+    """Convert role-to-groups mappings into JSON-friendly sorted lists."""
+    normalized: dict[str, list[str]] = {}
+    for role_name, groups in role_groups.items():
+        normalized[str(getattr(role_name, "value", role_name))] = sorted(
+            claim_groups(groups)
+        )
+    return normalized

cpkit/auth/config.py

@@ -0,0 +1,162 @@
+"""OIDC configuration derived from framework settings."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from cpkit.config import as_bool, safe_csv_set, safe_json_string_dict
+from cpkit.settings import FrameworkSettingKey
+
+
+@dataclass(frozen=True)
+class OIDCConfig:
+    """Configuration derived from settings for OIDC login and authz."""
+
+    enabled: bool = False
+    issuer_url: str = ""
+    client_id: str = ""
+    client_secret: str = ""
+    scopes: str = "openid profile email offline_access"
+    audience: str = ""
+    extra_auth_params_raw: str = "{}"
+    redirect_uri: str = ""
+    login_path: str = "/api/auth/login"
+    session_max_age_seconds: int = 2592000
+    refresh_leeway_seconds: int = 60
+    cookie_secure: bool = False
+    cookie_samesite: str = "lax"
+    cookie_domain: str | None = None
+    verify_audience: bool = False
+    ui_username_claim: str = "preferred_username"
+    readonly_groups_raw: str = ""
+    user_groups_raw: str = ""
+    admin_groups_raw: str = ""
+    groups_claim_name: str = "groups"
+    cache_ttl_seconds: int = 300
+    api_key_signature_ttl_seconds: int = 300
+
+    @classmethod
+    def from_repo(cls, repo: Any) -> "OIDCConfig":
+        settings = {setting.key: setting for setting in repo.list_settings()}
+        return cls.from_settings(settings)
+
+    @classmethod
+    def from_settings(cls, settings: dict[Any, Any]) -> "OIDCConfig":
+        SettingKey = FrameworkSettingKey
+        enabled = as_bool(settings[SettingKey.oidc_enabled].value, default=False)
+        if not enabled:
+            return cls(
+                enabled=False,
+                cache_ttl_seconds=int(
+                    settings[SettingKey.oidc_cache_ttl_seconds].value
+                ),
+                api_key_signature_ttl_seconds=int(
+                    settings[SettingKey.auth_api_key_signature_ttl_seconds].value
+                ),
+            )
+
+        return cls(
+            enabled=enabled,
+            issuer_url=settings[SettingKey.oidc_issuer_url].value.rstrip("/"),
+            client_id=settings[SettingKey.oidc_client_id].value,
+            client_secret=settings[SettingKey.oidc_client_secret].value,
+            scopes=settings[SettingKey.oidc_scopes].value,
+            audience=settings[SettingKey.oidc_audience].value,
+            extra_auth_params_raw=settings[SettingKey.oidc_extra_auth_params].value,
+            redirect_uri=settings[SettingKey.oidc_redirect_uri].value,
+            login_path=settings[SettingKey.oidc_login_path].value,
+            session_max_age_seconds=int(
+                settings[SettingKey.oidc_session_max_age_seconds].value
+            ),
+            refresh_leeway_seconds=int(
+                settings[SettingKey.oidc_refresh_leeway_seconds].value
+            ),
+            cookie_secure=as_bool(
+                settings[SettingKey.oidc_cookie_secure].value,
+                default=False,
+            ),
+            cookie_samesite=settings[SettingKey.oidc_cookie_samesite].value.lower(),
+            cookie_domain=settings[SettingKey.oidc_cookie_domain].value or None,
+            verify_audience=as_bool(
+                settings[SettingKey.oidc_verify_audience].value,
+                default=False,
+            ),
+            ui_username_claim=settings[SettingKey.oidc_ui_username_claim].value,
+            readonly_groups_raw=settings[SettingKey.oidc_authz_readonly_groups].value,
+            user_groups_raw=settings[SettingKey.oidc_authz_user_groups].value,
+            admin_groups_raw=settings[SettingKey.oidc_authz_admin_groups].value,
+            groups_claim_name=settings[SettingKey.oidc_authz_groups_claim].value,
+            cache_ttl_seconds=int(settings[SettingKey.oidc_cache_ttl_seconds].value),
+            api_key_signature_ttl_seconds=int(
+                settings[SettingKey.auth_api_key_signature_ttl_seconds].value
+            ),
+        )
+
+    @property
+    def role_groups(self) -> dict[str, set[str]]:
+        """Map application role names to the configured OIDC groups that grant them."""
+        return {
+            "CP_READONLY": safe_csv_set(self.readonly_groups_raw),
+            "CP_USER": safe_csv_set(self.user_groups_raw),
+            "CP_ADMIN": safe_csv_set(self.admin_groups_raw),
+        }
+
+    @property
+    def authorized_groups(self) -> set[str]:
+        """Return the union of all OIDC groups allowed to access the application."""
+        role_groups = self.role_groups
+        if not role_groups:
+            return set()
+        groups: set[str] = set()
+        for values in role_groups.values():
+            groups.update(values)
+        return groups
+
+    def validate(self) -> None:
+        """Validate startup configuration before the app begins serving requests."""
+        if not self.enabled:
+            return
+
+        missing = []
+        if not self.issuer_url:
+            missing.append("oidc_issuer_url")
+        if not self.client_id:
+            missing.append("oidc_client_id")
+        if not self.client_secret:
+            missing.append("oidc_client_secret")
+
+        if missing:
+            raise RuntimeError(
+                f"OIDC is enabled but missing required settings: {', '.join(missing)}"
+            )
+
+        if self.cookie_samesite not in {"lax", "strict", "none"}:
+            raise RuntimeError("oidc_cookie_samesite must be one of: lax, strict, none")
+
+        if self.cookie_samesite == "none" and not self.cookie_secure:
+            raise RuntimeError(
+                "oidc_cookie_secure must be true when oidc_cookie_samesite=none"
+            )
+
+        if not self.ui_username_claim:
+            raise RuntimeError(
+                "oidc_ui_username_claim must be set when OIDC is enabled"
+            )
+
+        if not self.groups_claim_name:
+            raise RuntimeError(
+                "oidc_authz_groups_claim must be set when OIDC is enabled"
+            )
+
+        if not self.authorized_groups:
+            raise RuntimeError(
+                "At least one of oidc_authz_readonly_groups, oidc_authz_user_groups, oidc_authz_admin_groups must include a group when OIDC is enabled"
+            )
+
+        self.extra_auth_params()
+
+    def extra_auth_params(self) -> dict[str, str]:
+        """Return extra authorization request parameters as a string dictionary."""
+        try:
+            return safe_json_string_dict(self.extra_auth_params_raw, default={})
+        except ValueError as exc:
+            raise ValueError("oidc_extra_auth_params must be a JSON object") from exc

cpkit/auth/dependencies.py

@@ -0,0 +1,155 @@
+"""FastAPI authentication dependency helpers for cpkit apps."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import Depends, Request, Security
+from fastapi.security import APIKeyHeader
+
+from .claims import claims_groups
+from .oidc import OIDCManager
+
+ACCESS_KEY_HEADER_NAME = "X-CP-Access-Key"
+SIGNATURE_HEADER_NAME = "X-CP-Signature"
+TIMESTAMP_HEADER_NAME = "X-Timestamp"
+
+access_key_scheme = APIKeyHeader(
+    name=ACCESS_KEY_HEADER_NAME,
+    scheme_name="XAccessKey",
+    auto_error=False,
+)
+signature_scheme = APIKeyHeader(
+    name=SIGNATURE_HEADER_NAME,
+    scheme_name="XSignature",
+    auto_error=False,
+)
+timestamp_scheme = APIKeyHeader(
+    name=TIMESTAMP_HEADER_NAME,
+    scheme_name="XTimestamp",
+    auto_error=False,
+)
+
+
+@dataclass(frozen=True)
+class AuthDependencies:
+    """Container for standard cpkit auth dependency callables."""
+
+    require_authenticated: Callable[..., Any]
+    require_user: Callable[..., Any]
+    require_readonly: Callable[..., Any]
+    require_admin: Callable[..., Any]
+    get_access_scope: Callable[[dict[str, Any]], tuple[list[str], bool]]
+    get_audit_actor: Callable[..., str]
+
+
+def create_auth_dependencies(
+    oidc: OIDCManager,
+    *,
+    get_repo: Callable[..., Any],
+    readonly_roles: tuple[Any, ...],
+    user_roles: tuple[Any, ...],
+    admin_roles: tuple[Any, ...],
+    session_cookie_name: str | None = None,
+) -> AuthDependencies:
+    """Create the standard auth dependencies for a cpkit FastAPI app."""
+    effective_session_cookie_name = session_cookie_name or oidc.session_cookie_name
+
+    async def require_authenticated(
+        request: Request,
+        repo: Any = Depends(get_repo),
+        access_key: str | None = Security(access_key_scheme),
+        signature: str | None = Security(signature_scheme),
+        timestamp: str | None = Security(timestamp_scheme),
+    ) -> dict[str, Any]:
+        """Return claims for the current caller, regardless of auth transport."""
+        oidc.load_config(repo)
+        session_token = (
+            request.cookies.get(effective_session_cookie_name)
+            if effective_session_cookie_name
+            else None
+        )
+        return await oidc.current_claims(
+            request,
+            repo,
+            session_token=session_token,
+            access_key=access_key,
+            signature=signature,
+            timestamp=timestamp,
+        )
+
+    def require_user(
+        claims: dict[str, Any] = Security(require_authenticated),
+    ) -> dict[str, Any]:
+        """Require a role that permits mutating application operations."""
+        return oidc.ensure_any_role(claims, *user_roles)
+
+    def require_readonly(
+        request: Request,
+        claims: dict[str, Any] = Security(require_authenticated),
+    ) -> dict[str, Any]:
+        """Allow read-only roles on GET and require user roles on writes."""
+        if request.method.upper() == "GET":
+            return oidc.ensure_any_role(claims, *readonly_roles, *user_roles)
+        return oidc.ensure_any_role(claims, *user_roles)
+
+    def require_admin(
+        claims: dict[str, Any] = Security(require_authenticated),
+    ) -> dict[str, Any]:
+        """Require an administrator role."""
+        return oidc.ensure_any_role(claims, *admin_roles)
+
+    def get_access_scope(claims: dict[str, Any]) -> tuple[list[str], bool]:
+        """Return normalized caller groups plus whether the caller is an admin."""
+        groups_claim_name = str(
+            claims.get("_groups_claim_name", oidc.config.groups_claim_name)
+        )
+        groups = sorted(claims_groups(claims, groups_claim_name))
+
+        effective_roles = (
+            claims.get("_role_groups")
+            if isinstance(claims.get("_role_groups"), dict)
+            else oidc.config.role_groups
+        )
+        is_admin = any(
+            _role_groups_intersect(effective_roles, role, groups)
+            for role in admin_roles
+        )
+        return groups, is_admin
+
+    def get_audit_actor(
+        claims: dict[str, Any] = Security(require_authenticated),
+    ) -> str:
+        """Return the identifier that should be written into audit logs."""
+        if claims.get("auth_type") == "api_key":
+            return str(claims.get("access_key") or "anonymous")
+
+        username = claims.get(oidc.config.ui_username_claim) or claims.get("sub")
+        return str(username or "anonymous")
+
+    return AuthDependencies(
+        require_authenticated=require_authenticated,
+        require_user=require_user,
+        require_readonly=require_readonly,
+        require_admin=require_admin,
+        get_access_scope=get_access_scope,
+        get_audit_actor=get_audit_actor,
+    )
+
+
+def _role_groups_intersect(
+    role_groups_by_name: dict[Any, Any],
+    role: Any,
+    groups: list[str],
+) -> bool:
+    role_groups = role_groups_by_name.get(role, set()) or role_groups_by_name.get(
+        _role_value(role),
+        set(),
+    )
+    return bool(role_groups) and not claims_groups({"groups": role_groups}).isdisjoint(
+        groups
+    )
+
+
+def _role_value(role: Any) -> str:
+    return str(getattr(role, "value", role))