cpkit 0.1.0__py3-none-any.whl

cpkit/audit/repository.py

@@ -0,0 +1,64 @@
+"""Repository helpers for framework-owned audit tables."""
+
+from cpkit.db import execute_stmt, fetch_all, fetch_scalar
+
+from .types import AuditLogRecord
+
+EVENT_LOG_TABLE = "cpkit.event_log"
+
+
+class AuditEventsRepositoryMixin:
+    """Repository mixin for framework audit event reads and writes."""
+
+    def list_events(
+        self,
+        limit: int,
+        offset: int,
+        groups: list[str] | None = None,
+        is_admin: bool = False,
+    ) -> list[AuditLogRecord]:
+        if is_admin:
+            return fetch_all(
+                f"""
+                SELECT ts, user_id, action, job_id, details, request_id::TEXT
+                FROM {EVENT_LOG_TABLE}
+                ORDER BY ts DESC
+                LIMIT %s
+                OFFSET %s
+                """,
+                (limit, offset),
+                AuditLogRecord,
+                operation="audit.list_events",
+            )
+
+        return []
+
+    def get_event_count(self) -> int:
+        return fetch_scalar(
+            f"""
+            SELECT count(*) AS id
+            FROM {EVENT_LOG_TABLE} AS OF SYSTEM TIME follower_read_timestamp()
+            """,
+            (),
+            operation="audit.get_event_count",
+        )
+
+    def log_event(self, log_msg: AuditLogRecord):
+        execute_stmt(
+            f"""
+            INSERT INTO {EVENT_LOG_TABLE}
+                (ts, user_id, action, job_id, details, request_id)
+            VALUES (%s, %s, %s, %s, %s, %s)
+            """,
+            (
+                log_msg.ts,
+                log_msg.user_id,
+                log_msg.action,
+                log_msg.job_id,
+                log_msg.details,
+                log_msg.request_id,
+            ),
+        )
+
+
+__all__ = ["AuditEventsRepositoryMixin", "EVENT_LOG_TABLE"]

cpkit/audit/router.py

@@ -0,0 +1,46 @@
+"""Audit event HTTP routes for cpkit FastAPI apps."""
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import APIRouter, Depends, Query
+
+from .types import AuditEventCountResponse, AuditLogRecord
+
+
+def create_events_router(
+    *,
+    get_service: Callable[..., Any],
+    get_access_scope: Callable[[dict], tuple[list[str], bool]],
+    require_readonly: Callable[..., Any],
+    handle_service_error: Callable[[Exception], None],
+    service_error_type: type[Exception] = Exception,
+) -> APIRouter:
+    """Create the framework audit event read routes."""
+    router = APIRouter(prefix="/events", tags=["cpkit"])
+
+    @router.get("/")
+    async def list_events(
+        limit: int = Query(default=20, ge=1, le=200),
+        offset: int = Query(default=0, ge=0),
+        claims: dict = Depends(require_readonly),
+        service=Depends(get_service),
+    ) -> list[AuditLogRecord]:
+        groups, is_admin = get_access_scope(claims)
+        try:
+            return service.list_visible_events(limit, offset, groups, is_admin)
+        except service_error_type as err:
+            handle_service_error(err)
+
+    @router.get("/count", response_model=AuditEventCountResponse)
+    async def get_event_count(
+        service=Depends(get_service),
+    ) -> AuditEventCountResponse:
+        try:
+            total = service.get_event_total()
+        except service_error_type as err:
+            handle_service_error(err)
+
+        return AuditEventCountResponse(total=total)
+
+    return router

cpkit/audit/service.py

@@ -0,0 +1,34 @@
+"""Generic audit emission service."""
+
+from enum import StrEnum
+from typing import Any
+
+from .types import AuditOutcome, AuditRecordCreate
+
+
+class AuditService:
+    def __init__(self, repo):
+        self.repo = repo
+
+    async def emit(
+        self,
+        event_type: str | StrEnum,
+        *,
+        actor_id: str | None = None,
+        actor_name: str | None = None,
+        resource_type: str | None = None,
+        resource_id: str | None = None,
+        outcome: AuditOutcome = AuditOutcome.REQUESTED,
+        metadata: dict[str, Any] | None = None,
+    ):
+        record = AuditRecordCreate(
+            event_type=str(event_type),
+            actor_id=actor_id,
+            actor_name=actor_name,
+            resource_type=resource_type,
+            resource_id=resource_id,
+            outcome=outcome,
+            metadata=metadata or {},
+        )
+
+        return await self.repo.insert(record)

cpkit/audit/types.py

@@ -0,0 +1,38 @@
+"""Generic audit data types."""
+
+from datetime import datetime, timezone
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class AuditOutcome(StrEnum):
+    REQUESTED = "requested"
+    STARTED = "started"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    DENIED = "denied"
+
+
+class AuditRecordCreate(BaseModel):
+    event_type: str
+    actor_id: str | None = None
+    actor_name: str | None = None
+    resource_type: str | None = None
+    resource_id: str | None = None
+    outcome: AuditOutcome = AuditOutcome.REQUESTED
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AuditLogRecord(BaseModel):
+    ts: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    user_id: str
+    action: str
+    job_id: int | None = None
+    details: dict[str, Any] | None = None
+    request_id: str | None = None
+
+
+class AuditEventCountResponse(BaseModel):
+    total: int

cpkit/auth/README.md

@@ -0,0 +1,38 @@
+# Auth
+
+The auth package owns cpkit's authentication and authorization features:
+OIDC browser login, signed API keys, role/group mapping, session storage, and
+FastAPI dependencies such as `require_admin`.
+
+Auth is bundled before most other capabilities because routes and services rely
+on it for access checks and audit actor identity.
+
+## Files
+
+- `bundle.py`: Creates the auth bundle: OIDC manager, dependencies, auth router,
+  and auth audit hooks.
+- `oidc.py`: OIDC login, callback, session validation, logout, and API key
+  request validation mechanics.
+- `dependencies.py`: FastAPI dependencies for authenticated, readonly, user, and
+  admin access.
+- `router.py`: OIDC/session routes.
+- `api_key_router.py`: Admin API key routes.
+- `api_key_service.py`: API key creation/deletion rules.
+- `api_keys.py`: API key generation and signing helpers.
+- `repositories.py`: Repository mixins for API keys, OIDC sessions, and
+  role-to-group mappings.
+- `claims.py`: Helpers for interpreting identity/provider claims.
+- `config.py`: OIDC and auth-related configuration access.
+- `redirects.py`: Login redirect helpers.
+- `secrets.py`: Secret encryption/decryption helpers.
+- `types.py`: Auth models and records.
+
+## Runtime Flow
+
+1. `create_auth_bundle()` builds the OIDC manager and dependency set.
+2. Routers use dependencies like `require_admin` to enforce access.
+3. The OIDC manager persists sessions through repository mixins.
+4. API key requests are verified using stored encrypted secrets and request
+   signatures.
+5. Login/logout and API key mutations emit audit events.
+

cpkit/auth/__init__.py

@@ -0,0 +1,123 @@
+"""Reusable authentication helpers."""
+
+from .api_key_router import create_api_keys_router
+from .api_key_service import ApiKeysService
+from .api_keys import (
+    APIKeyAuthenticationError,
+    APIKeyAuthenticator,
+    APIKeyRepository,
+    api_key_signature,
+    build_api_key_signature_payload,
+    parse_api_key_timestamp,
+    request_target_bytes,
+)
+from .bundle import (
+    DEFAULT_ADMIN_ROLES,
+    DEFAULT_OIDC_SESSION_COOKIE_NAME,
+    DEFAULT_READONLY_ROLES,
+    DEFAULT_USER_ROLES,
+    AuthBundle,
+    create_auth_bundle,
+)
+from .claims import claim_groups, claims_groups, jsonable_role_groups
+from .config import OIDCConfig
+from .dependencies import (
+    ACCESS_KEY_HEADER_NAME,
+    SIGNATURE_HEADER_NAME,
+    TIMESTAMP_HEADER_NAME,
+    AuthDependencies,
+    access_key_scheme,
+    create_auth_dependencies,
+    signature_scheme,
+    timestamp_scheme,
+)
+from .oidc import (
+    OIDCAuthenticationError,
+    OIDCManager,
+    OIDCProviderClient,
+    OIDCSessionManager,
+    OIDCSessionRepository,
+)
+from .redirects import safe_next_path
+from .repositories import (
+    ROLE_GROUP_MAPPINGS_TABLE,
+    APIKeysRepositoryMixin,
+    OIDCSessionsRepositoryMixin,
+    RoleGroupMappingsRepositoryMixin,
+)
+from .router import (
+    OIDC_NEXT_COOKIE_NAME,
+    OIDC_NONCE_COOKIE_NAME,
+    OIDC_STATE_COOKIE_NAME,
+    create_oidc_router,
+)
+from .secrets import (
+    ENCRYPTED_SECRET_VERSION,
+    decrypt_secret,
+    encrypt_secret,
+    validate_secret_crypto_config,
+)
+from .types import (
+    ApiKeyCreateRequest,
+    ApiKeyCreateRequestInDB,
+    ApiKeyCreateResponse,
+    ApiKeyRecord,
+    ApiKeySummary,
+    OIDCSessionRecord,
+    RoleGroupMap,
+)
+
+__all__ = [
+    "ENCRYPTED_SECRET_VERSION",
+    "OIDCAuthenticationError",
+    "OIDCManager",
+    "OIDC_NEXT_COOKIE_NAME",
+    "OIDC_NONCE_COOKIE_NAME",
+    "OIDCProviderClient",
+    "OIDCSessionManager",
+    "OIDCSessionRepository",
+    "OIDC_STATE_COOKIE_NAME",
+    "APIKeyAuthenticationError",
+    "APIKeyAuthenticator",
+    "APIKeyRepository",
+    "APIKeysRepositoryMixin",
+    "AuthBundle",
+    "DEFAULT_ADMIN_ROLES",
+    "DEFAULT_OIDC_SESSION_COOKIE_NAME",
+    "DEFAULT_READONLY_ROLES",
+    "DEFAULT_USER_ROLES",
+    "ROLE_GROUP_MAPPINGS_TABLE",
+    "ApiKeyCreateRequest",
+    "ApiKeyCreateRequestInDB",
+    "ApiKeyCreateResponse",
+    "ApiKeyRecord",
+    "ApiKeySummary",
+    "ApiKeysService",
+    "OIDCSessionsRepositoryMixin",
+    "OIDCSessionRecord",
+    "ACCESS_KEY_HEADER_NAME",
+    "AuthDependencies",
+    "OIDCConfig",
+    "RoleGroupMap",
+    "RoleGroupMappingsRepositoryMixin",
+    "SIGNATURE_HEADER_NAME",
+    "TIMESTAMP_HEADER_NAME",
+    "access_key_scheme",
+    "api_key_signature",
+    "build_api_key_signature_payload",
+    "claim_groups",
+    "claims_groups",
+    "create_oidc_router",
+    "create_api_keys_router",
+    "create_auth_dependencies",
+    "create_auth_bundle",
+    "decrypt_secret",
+    "encrypt_secret",
+    "jsonable_role_groups",
+    "parse_api_key_timestamp",
+    "request_target_bytes",
+    "safe_next_path",
+    "signature_scheme",
+    "timestamp_scheme",
+    "validate_secret_crypto_config",
+]

cpkit/auth/api_key_router.py

@@ -0,0 +1,52 @@
+"""FastAPI routes for framework API-key management."""
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import APIRouter, Depends
+
+from .types import ApiKeyCreateRequest, ApiKeyCreateResponse, ApiKeySummary
+
+
+def create_api_keys_router(
+    *,
+    get_service: Callable[..., Any],
+    get_audit_actor: Callable[..., Any],
+    handle_service_error: Callable[[Exception], None],
+    service_error_type: type[Exception] = Exception,
+) -> APIRouter:
+    router = APIRouter(prefix="/api_keys", tags=["cpkit"])
+
+    @router.get("/")
+    async def list_api_keys(
+        access_key: str | None = None,
+        service=Depends(get_service),
+    ) -> list[ApiKeySummary]:
+        try:
+            return service.list_api_keys(access_key)
+        except service_error_type as err:
+            handle_service_error(err)
+
+    @router.post("/", response_model=ApiKeyCreateResponse)
+    async def create_api_key(
+        request: ApiKeyCreateRequest,
+        actor_id: str = Depends(get_audit_actor),
+        service=Depends(get_service),
+    ) -> ApiKeyCreateResponse:
+        try:
+            return service.create_api_key(actor_id, request)
+        except service_error_type as err:
+            handle_service_error(err)
+
+    @router.delete("/{access_key}")
+    async def delete_api_key(
+        access_key: str,
+        actor_id: str = Depends(get_audit_actor),
+        service=Depends(get_service),
+    ) -> None:
+        try:
+            service.delete_api_key(actor_id, access_key)
+        except service_error_type as err:
+            handle_service_error(err)
+
+    return router

cpkit/auth/api_key_service.py

@@ -0,0 +1,143 @@
+"""Service helpers for framework API-key management."""
+
+import secrets
+from collections.abc import Callable
+from datetime import datetime, timezone
+from typing import Any
+
+from cpkit.errors import (
+    RepositoryError,
+    ServiceNotFoundError,
+    ServiceValidationError,
+    from_repository_error,
+)
+
+from .secrets import encrypt_secret
+from .types import (
+    ApiKeyCreateRequest,
+    ApiKeyCreateRequestInDB,
+    ApiKeyCreateResponse,
+    ApiKeySummary,
+)
+
+APIKeyAuditHook = Callable[[Any, str, str, dict[str, Any]], None]
+
+
+class ApiKeysService:
+    def __init__(
+        self,
+        repo,
+        *,
+        created_hook: APIKeyAuditHook | None = None,
+        deleted_hook: APIKeyAuditHook | None = None,
+    ) -> None:
+        self.repo = repo
+        self.created_hook = created_hook
+        self.deleted_hook = deleted_hook
+
+    def list_api_keys(self, access_key: str | None = None) -> list[ApiKeySummary]:
+        try:
+            return self.repo.list_api_keys(access_key)
+        except RepositoryError as err:
+            raise from_repository_error(
+                err,
+                unavailable_message="API keys are temporarily unavailable.",
+                fallback_message="Unable to load API keys.",
+            ) from err
+
+    def create_api_key(
+        self,
+        actor_id: str,
+        request: ApiKeyCreateRequest,
+    ) -> ApiKeyCreateResponse:
+        valid_until = self._normalize_valid_until(request.valid_until)
+
+        if valid_until <= datetime.now(timezone.utc):
+            raise ServiceValidationError("valid_until must be in the future.")
+
+        secret_access_key = secrets.token_urlsafe(32)
+        access_key = "cp-" + secrets.token_urlsafe(16)
+
+        try:
+            created = self.repo.create_api_key(
+                ApiKeyCreateRequestInDB(
+                    access_key=access_key,
+                    valid_until=valid_until,
+                    roles=request.roles,
+                ),
+                owner=actor_id,
+                encrypted_secret_access_key=encrypt_secret(secret_access_key),
+            )
+        except RepositoryError as err:
+            raise from_repository_error(
+                err,
+                unavailable_message="API keys could not be created right now.",
+                conflict_message="That API key already exists.",
+                validation_message="The API key request is invalid.",
+                fallback_message="Unable to create API key.",
+            ) from err
+
+        if self.created_hook is not None:
+            self.created_hook(
+                self.repo,
+                actor_id,
+                "API_KEY_CREATED",
+                {
+                    "access_key": created.access_key,
+                    "valid_until": created.valid_until.isoformat(),
+                    "roles": [_role_value(role) for role in created.roles or []],
+                },
+            )
+
+        return ApiKeyCreateResponse(
+            access_key=created.access_key,
+            owner=created.owner,
+            valid_until=created.valid_until,
+            roles=created.roles,
+            secret_access_key=secret_access_key,
+        )
+
+    def delete_api_key(self, actor_id: str, access_key: str) -> None:
+        try:
+            existing_key = self.repo.get_api_key(access_key)
+        except RepositoryError as err:
+            raise from_repository_error(
+                err,
+                unavailable_message="API keys could not be updated right now.",
+                fallback_message=f"Unable to load API key '{access_key}'.",
+            ) from err
+
+        if existing_key is None:
+            raise ServiceNotFoundError("API key not found.")
+
+        try:
+            self.repo.delete_api_key(access_key)
+        except RepositoryError as err:
+            raise from_repository_error(
+                err,
+                unavailable_message="API keys could not be updated right now.",
+                fallback_message=f"Unable to delete API key '{access_key}'.",
+            ) from err
+
+        if self.deleted_hook is not None:
+            self.deleted_hook(
+                self.repo,
+                actor_id,
+                "API_KEY_DELETED",
+                {
+                    "access_key": existing_key.access_key,
+                    "owner": existing_key.owner,
+                    "valid_until": existing_key.valid_until.isoformat(),
+                    "roles": [_role_value(role) for role in existing_key.roles or []],
+                },
+            )
+
+    @staticmethod
+    def _normalize_valid_until(value: datetime) -> datetime:
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+
+
+def _role_value(role: Any) -> str:
+    return str(getattr(role, "value", role))

cpkit/auth/api_keys.py

@@ -0,0 +1,143 @@
+"""Reusable API-key request signing helpers."""
+
+from datetime import datetime, timezone
+from hashlib import sha256
+from hmac import compare_digest
+from hmac import new as hmac_new
+from typing import Any, Protocol
+
+
+class APIKeyAuthenticationError(Exception):
+    """Raised when an API key request cannot be authenticated."""
+
+    def __init__(self, detail: str) -> None:
+        self.detail = detail
+        super().__init__(detail)
+
+
+class APIKeyRepository(Protocol):
+    """Repository-like object that can fetch API key records."""
+
+    def get_api_key(self, access_key: str) -> Any | None: ...
+
+
+def parse_api_key_timestamp(timestamp: str) -> datetime:
+    """Parse either epoch seconds or an ISO-8601 timestamp into UTC."""
+    raw_timestamp = timestamp.strip()
+    if not raw_timestamp:
+        raise ValueError("empty timestamp")
+
+    try:
+        parsed = datetime.fromtimestamp(float(raw_timestamp), tz=timezone.utc)
+    except OSError, OverflowError, ValueError:
+        normalized = (
+            f"{raw_timestamp[:-1]}+00:00"
+            if raw_timestamp.endswith("Z")
+            else raw_timestamp
+        )
+        parsed = datetime.fromisoformat(normalized)
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        else:
+            parsed = parsed.astimezone(timezone.utc)
+
+    return parsed
+
+
+def request_target_bytes(request: Any) -> bytes:
+    """Return the exact path and query bytes covered by the request signature."""
+    raw_path = request.scope.get("raw_path")
+    if isinstance(raw_path, bytes) and raw_path:
+        path = raw_path
+    else:
+        path = request.url.path.encode("utf-8")
+
+    query_string = request.scope.get("query_string")
+    if isinstance(query_string, bytes) and query_string:
+        return path + b"?" + query_string
+    return path
+
+
+def build_api_key_signature_payload(
+    request: Any,
+    timestamp: str,
+    body: bytes,
+) -> bytes:
+    """Build the canonical payload used for HMAC request signing."""
+    return b"\n".join(
+        [
+            request.method.upper().encode("utf-8"),
+            request_target_bytes(request),
+            timestamp.strip().encode("utf-8"),
+            body,
+        ]
+    )
+
+
+def api_key_signature(
+    secret_key: bytes,
+    request: Any,
+    timestamp: str,
+    body: bytes,
+) -> str:
+    """Return the expected HMAC signature for an API-key-authenticated request."""
+    return hmac_new(
+        secret_key,
+        build_api_key_signature_payload(request, timestamp, body),
+        sha256,
+    ).hexdigest()
+
+
+class APIKeyAuthenticator:
+    """Authenticate HMAC-signed API key requests."""
+
+    def __init__(self, *, decrypt_secret) -> None:
+        self.decrypt_secret = decrypt_secret
+
+    async def authenticate_request(
+        self,
+        request: Any,
+        repo: APIKeyRepository,
+        *,
+        access_key: str,
+        signature: str,
+        timestamp: str,
+        max_age_seconds: int,
+    ) -> dict[str, Any]:
+        api_key = repo.get_api_key(access_key)
+        if api_key is None:
+            raise APIKeyAuthenticationError("Invalid API key.")
+
+        if datetime.now(timezone.utc) >= api_key.valid_until:
+            raise APIKeyAuthenticationError("API key is expired.")
+
+        try:
+            signed_at = parse_api_key_timestamp(timestamp)
+        except ValueError as exc:
+            raise APIKeyAuthenticationError("Invalid X-Timestamp header.") from exc
+
+        age_seconds = abs((datetime.now(timezone.utc) - signed_at).total_seconds())
+        if age_seconds > max_age_seconds:
+            raise APIKeyAuthenticationError("API request timestamp is expired.")
+
+        body = await request.body()
+        secret_key = self.decrypt_secret(api_key.encrypted_secret_access_key)
+        expected_signature = api_key_signature(secret_key, request, timestamp, body)
+
+        if not compare_digest(expected_signature, signature.strip().lower()):
+            raise APIKeyAuthenticationError("Invalid API key signature.")
+
+        roles = set(api_key.roles or [])
+        role_groups = {role: {_role_value(role)} for role in roles}
+        return {
+            "sub": api_key.owner,
+            "access_key": api_key.access_key,
+            "groups": [_role_value(role) for role in roles],
+            "_groups_claim_name": "groups",
+            "_role_groups": role_groups,
+            "auth_type": "api_key",
+        }
+
+
+def _role_value(role: Any) -> str:
+    return str(getattr(role, "value", role))