cpkit 0.1.0__py3-none-any.whl

cpkit/auth/redirects.py

@@ -0,0 +1,12 @@
+"""Redirect target validation helpers."""
+
+
+def safe_next_path(next_path: str | None) -> str:
+    """Normalize redirect targets so only in-app absolute paths are allowed."""
+    if not next_path:
+        return "/"
+    if not next_path.startswith("/"):
+        return "/"
+    if next_path.startswith("//"):
+        return "/"
+    return next_path

cpkit/auth/repositories.py

@@ -0,0 +1,181 @@
+"""Repository mixins for framework-owned auth tables."""
+
+from cpkit.db import execute_stmt, fetch_all, fetch_one
+
+from .types import ApiKeyRecord, ApiKeySummary, OIDCSessionRecord, RoleGroupMap
+
+API_KEYS_TABLE = "cpkit.api_keys"
+OIDC_SESSIONS_TABLE = "cpkit.oidc_sessions"
+ROLE_GROUP_MAPPINGS_TABLE = "cpkit.role_to_groups_mappings"
+
+
+class APIKeysRepositoryMixin:
+    api_key_record_type = ApiKeyRecord
+    api_key_summary_type = ApiKeySummary
+
+    def get_api_key(self, access_key: str):
+        return fetch_one(
+            f"""
+                    SELECT access_key, encrypted_secret_access_key, owner, valid_until, roles
+                    FROM {API_KEYS_TABLE}
+                    WHERE access_key = %s
+                    """,
+            (access_key,),
+            self.api_key_record_type,
+            operation="api_keys.get",
+        )
+
+    def list_api_keys(self, access_key: str | None = None):
+        params: list[str] = []
+        sql = f"""
+            SELECT access_key, owner, valid_until, roles
+            FROM {API_KEYS_TABLE}
+        """
+
+        if access_key is not None:
+            sql += " WHERE access_key = %s"
+            params.append(access_key)
+
+        sql += " ORDER BY access_key"
+
+        return fetch_all(
+            sql,
+            tuple(params),
+            self.api_key_summary_type,
+            operation="api_keys.list",
+        )
+
+    def create_api_key(
+        self,
+        api_key,
+        *,
+        owner: str,
+        encrypted_secret_access_key: bytes,
+    ):
+        return fetch_one(
+            f"""
+                    INSERT INTO {API_KEYS_TABLE} (
+                        access_key,
+                        encrypted_secret_access_key,
+                        owner,
+                        valid_until,
+                        roles
+                    )
+                    VALUES (%s, %s, %s, %s, %s)
+                    RETURNING access_key, owner, valid_until, roles
+                    """,
+            (
+                api_key.access_key,
+                encrypted_secret_access_key,
+                owner,
+                api_key.valid_until,
+                api_key.roles,
+            ),
+            self.api_key_summary_type,
+            operation="api_keys.create",
+        )
+
+    def delete_api_key(self, access_key: str) -> None:
+        execute_stmt(
+            f"""
+                DELETE
+                FROM {API_KEYS_TABLE}
+                WHERE access_key = %s
+                """,
+            (access_key,),
+            operation="api_keys.delete",
+        )
+
+
+class OIDCSessionsRepositoryMixin:
+    oidc_session_record_type = OIDCSessionRecord
+
+    def get_oidc_session(self, session_id: str):
+        return fetch_one(
+            f"""
+            SELECT
+                session_id,
+                encrypted_id_token,
+                encrypted_refresh_token,
+                token_expires_at,
+                session_expires_at,
+                created_at,
+                updated_at
+            FROM {OIDC_SESSIONS_TABLE}
+            WHERE session_id = %s
+                AND session_expires_at > now()
+            """,
+            (session_id,),
+            self.oidc_session_record_type,
+            operation="auth.get_oidc_session",
+        )
+
+    def create_oidc_session(self, session) -> None:
+        execute_stmt(
+            f"""
+            INSERT INTO {OIDC_SESSIONS_TABLE}
+                (session_id, encrypted_id_token, encrypted_refresh_token,
+                 token_expires_at, session_expires_at)
+            VALUES
+                (%s, %s, %s, %s, %s)
+            """,
+            (
+                session.session_id,
+                session.encrypted_id_token,
+                session.encrypted_refresh_token,
+                session.token_expires_at,
+                session.session_expires_at,
+            ),
+            operation="auth.create_oidc_session",
+        )
+
+    def update_oidc_session(
+        self,
+        session_id: str,
+        *,
+        encrypted_id_token: bytes,
+        encrypted_refresh_token: bytes | None,
+        token_expires_at,
+    ) -> None:
+        execute_stmt(
+            f"""
+            UPDATE {OIDC_SESSIONS_TABLE}
+            SET
+                encrypted_id_token = %s,
+                encrypted_refresh_token = %s,
+                token_expires_at = %s
+            WHERE session_id = %s
+            """,
+            (
+                encrypted_id_token,
+                encrypted_refresh_token,
+                token_expires_at,
+                session_id,
+            ),
+            operation="auth.update_oidc_session",
+        )
+
+    def delete_oidc_session(self, session_id: str) -> None:
+        execute_stmt(
+            f"""
+            DELETE FROM {OIDC_SESSIONS_TABLE}
+            WHERE session_id = %s
+            """,
+            (session_id,),
+            operation="auth.delete_oidc_session",
+        )
+
+
+class RoleGroupMappingsRepositoryMixin:
+    role_group_map_type = RoleGroupMap
+
+    def list_role_group_mappings(self) -> list[RoleGroupMap]:
+        return fetch_all(
+            f"""
+            SELECT role, groups
+            FROM {ROLE_GROUP_MAPPINGS_TABLE}
+            """,
+            (),
+            self.role_group_map_type,
+            operation="auth.list_role_group_mappings",
+        )

cpkit/auth/router.py

@@ -0,0 +1,214 @@
+"""OIDC HTTP routes for cpkit FastAPI apps."""
+
+import secrets
+from collections.abc import Callable
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, Security
+from fastapi.responses import RedirectResponse
+
+from .oidc import OIDCManager
+from .redirects import safe_next_path
+
+OIDC_STATE_COOKIE_NAME = "cp_oidc_state"
+OIDC_NONCE_COOKIE_NAME = "cp_oidc_nonce"
+OIDC_NEXT_COOKIE_NAME = "cp_oidc_next"
+
+AuthEventHook = Callable[[Any, str, str, dict[str, Any] | None], None]
+
+
+def create_oidc_router(
+    oidc: OIDCManager,
+    *,
+    get_repo: Callable[..., Any],
+    require_authenticated: Callable[..., Any],
+    get_audit_actor: Callable[..., str],
+    audit_event_hook: AuthEventHook | None = None,
+    prefix: str = "/auth",
+    tags: list[str] | None = None,
+    state_cookie_name: str = OIDC_STATE_COOKIE_NAME,
+    nonce_cookie_name: str = OIDC_NONCE_COOKIE_NAME,
+    next_cookie_name: str = OIDC_NEXT_COOKIE_NAME,
+) -> APIRouter:
+    """Create the standard OIDC auth router for a cpkit app."""
+    router = APIRouter(prefix=prefix, tags=tags or ["cpkit"])
+
+    def oidc_cookie_kwargs() -> dict[str, Any]:
+        return {
+            "httponly": True,
+            "secure": oidc.config.cookie_secure,
+            "samesite": oidc.config.cookie_samesite,
+            "domain": oidc.config.cookie_domain,
+            "path": "/",
+        }
+
+    def log_auth_event(
+        repo: Any,
+        actor_id: str,
+        action: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        if audit_event_hook is not None:
+            audit_event_hook(repo, actor_id, action, details)
+
+    @router.get("/login")
+    def oidc_login(
+        request: Request,
+        next: str = "/",  # noqa: A002
+        repo: Any = Depends(get_repo),
+    ):
+        """Start the browser OIDC login flow and store anti-CSRF cookies."""
+        oidc.load_config(repo)
+        if not oidc.enabled:
+            raise HTTPException(
+                status_code=404,
+                detail="OIDC is disabled.",
+            )
+
+        state = secrets.token_urlsafe(24)
+        nonce = secrets.token_urlsafe(24)
+        next_path = safe_next_path(next)
+        redirect_uri = oidc.config.redirect_uri or str(request.url_for("oidc_callback"))
+        auth_url = oidc.build_authorization_url(redirect_uri, state, nonce)
+
+        resp = RedirectResponse(auth_url, status_code=302)
+        cookie_kwargs = oidc_cookie_kwargs()
+        resp.set_cookie(state_cookie_name, state, max_age=300, **cookie_kwargs)
+        resp.set_cookie(nonce_cookie_name, nonce, max_age=300, **cookie_kwargs)
+        resp.set_cookie(next_cookie_name, next_path, max_age=300, **cookie_kwargs)
+        return resp
+
+    @router.get("/callback", name="oidc_callback")
+    def oidc_callback(
+        request: Request,
+        repo: Any = Depends(get_repo),
+        code: str | None = None,
+        state: str | None = None,
+        error: str | None = None,
+        error_description: str | None = None,
+    ):
+        """Finish OIDC login, persist a session, and set the session cookie."""
+        oidc.load_config(repo)
+        if not oidc.enabled:
+            raise HTTPException(
+                status_code=404,
+                detail="OIDC is disabled.",
+            )
+
+        if error:
+            desc = error_description or "OIDC authorization failed."
+            raise HTTPException(status_code=401, detail=f"{error}: {desc}")
+
+        expected_state = request.cookies.get(state_cookie_name)
+        expected_nonce = request.cookies.get(nonce_cookie_name)
+        next_path = safe_next_path(request.cookies.get(next_cookie_name))
+
+        if not code:
+            raise HTTPException(status_code=400, detail="Missing authorization code.")
+        if not state or not expected_state or state != expected_state:
+            raise HTTPException(status_code=401, detail="Invalid OIDC state.")
+        if not expected_nonce:
+            raise HTTPException(status_code=401, detail="Missing OIDC nonce.")
+
+        redirect_uri = oidc.config.redirect_uri or str(request.url_for("oidc_callback"))
+        token_payload = oidc.exchange_code(code, redirect_uri)
+
+        id_token = token_payload.get("id_token")
+        if not id_token or not isinstance(id_token, str):
+            raise HTTPException(
+                status_code=401,
+                detail="Token endpoint response missing id_token.",
+            )
+        refresh_token = token_payload.get("refresh_token")
+        refresh_token_value = (
+            refresh_token if isinstance(refresh_token, str) and refresh_token else None
+        )
+
+        claims = oidc.validate_jwt(
+            id_token,
+            expected_nonce=expected_nonce,
+            strict_client_audience=True,
+        )
+        oidc.ensure_authorized(claims)
+        session_id = secrets.token_urlsafe(32)
+        repo.create_oidc_session(
+            oidc.build_session_record(
+                session_id,
+                id_token=id_token,
+                refresh_token=refresh_token_value,
+                claims=claims,
+            )
+        )
+        actor_id = str(claims.get(oidc.config.ui_username_claim) or claims.get("sub"))
+        log_auth_event(
+            repo,
+            actor_id,
+            "LOGIN",
+            {
+                "auth_type": "oidc",
+                "refresh_token_present": bool(refresh_token_value),
+            },
+        )
+
+        resp = RedirectResponse(next_path, status_code=302)
+        cookie_kwargs = oidc_cookie_kwargs()
+        if oidc.session_cookie_name:
+            resp.set_cookie(
+                oidc.session_cookie_name,
+                session_id,
+                max_age=oidc.config.session_max_age_seconds,
+                **cookie_kwargs,
+            )
+        resp.delete_cookie(
+            state_cookie_name,
+            path="/",
+            domain=oidc.config.cookie_domain,
+        )
+        resp.delete_cookie(
+            nonce_cookie_name,
+            path="/",
+            domain=oidc.config.cookie_domain,
+        )
+        resp.delete_cookie(
+            next_cookie_name,
+            path="/",
+            domain=oidc.config.cookie_domain,
+        )
+        return resp
+
+    @router.post("/logout")
+    def oidc_logout(
+        repo: Any = Depends(get_repo),
+        actor_id: str = Depends(get_audit_actor),
+        claims: dict[str, Any] = Security(require_authenticated),
+    ):
+        """Clear the OIDC session cookie and write a logout audit event."""
+        session_id = str(claims.get("_session_id") or "").strip()
+        if session_id:
+            repo.delete_oidc_session(session_id)
+        log_auth_event(
+            repo,
+            actor_id,
+            "LOGOUT",
+            {"auth_type": str(claims.get("auth_type") or "oidc")},
+        )
+        resp = Response(status_code=204)
+        if oidc.session_cookie_name:
+            resp.delete_cookie(
+                oidc.session_cookie_name,
+                path="/",
+                domain=oidc.config.cookie_domain,
+            )
+        return resp
+
+    @router.get("/me")
+    def oidc_me(
+        request: Request,
+        claims: dict[str, Any] = Security(require_authenticated),
+    ) -> dict[str, Any]:
+        """Return the current caller's claims plus auth metadata."""
+        payload = oidc.enrich_claims(claims)
+        payload["cookies"] = request.cookies
+        return payload
+
+    return router

cpkit/auth/secrets.py

@@ -0,0 +1,78 @@
+"""Versioned symmetric secret encryption helpers."""
+
+import base64
+import os
+import secrets
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+ENCRYPTED_SECRET_VERSION = b"\x01"
+DEFAULT_MASTER_KEY_ENV_VAR = "CPKIT_MASTER_KEY"
+
+
+def validate_secret_crypto_config(
+    *,
+    master_key_env_var: str = DEFAULT_MASTER_KEY_ENV_VAR,
+) -> None:
+    _secret_master_key(master_key_env_var=master_key_env_var)
+
+
+def encrypt_secret(
+    secret: bytes | str,
+    *,
+    master_key_env_var: str = DEFAULT_MASTER_KEY_ENV_VAR,
+) -> bytes:
+    nonce = secrets.token_bytes(12)
+    key = _secret_master_key(master_key_env_var=master_key_env_var)
+    ciphertext = AESGCM(key).encrypt(nonce, _secret_bytes(secret), None)
+    return ENCRYPTED_SECRET_VERSION + nonce + ciphertext
+
+
+def decrypt_secret(
+    secret: bytes | str,
+    *,
+    master_key_env_var: str = DEFAULT_MASTER_KEY_ENV_VAR,
+) -> bytes:
+    encrypted_secret = _secret_bytes(secret)
+    if not encrypted_secret:
+        raise RuntimeError("Encrypted secret is empty.")
+    if encrypted_secret[:1] != ENCRYPTED_SECRET_VERSION:
+        raise RuntimeError(
+            "Encrypted secret has an unsupported format. Migrate stored secrets to the versioned encrypted format."
+        )
+
+    nonce = encrypted_secret[1:13]
+    ciphertext = encrypted_secret[13:]
+    if len(nonce) != 12 or not ciphertext:
+        raise RuntimeError("Encrypted secret is malformed.")
+
+    try:
+        return AESGCM(
+            _secret_master_key(master_key_env_var=master_key_env_var)
+        ).decrypt(nonce, ciphertext, None)
+    except Exception as exc:
+        raise RuntimeError(
+            f"Encrypted secret could not be decrypted. Check {master_key_env_var} and stored key material."
+        ) from exc
+
+
+def _secret_master_key(*, master_key_env_var: str) -> bytes:
+    encoded_key = os.getenv(master_key_env_var, "").strip()
+    if not encoded_key:
+        raise RuntimeError(f"{master_key_env_var} must be set for secret encryption.")
+
+    try:
+        key = base64.b64decode(encoded_key, validate=True)
+    except ValueError as exc:
+        raise RuntimeError(f"{master_key_env_var} must be valid base64.") from exc
+
+    if len(key) != 32:
+        raise RuntimeError(f"{master_key_env_var} must decode to exactly 32 bytes.")
+
+    return key
+
+
+def _secret_bytes(secret: bytes | str) -> bytes:
+    if isinstance(secret, bytes):
+        return secret
+    return secret.encode("utf-8")

cpkit/auth/types.py

@@ -0,0 +1,49 @@
+"""Generic auth capability data types."""
+
+import datetime as dt
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class ApiKeyRecord(BaseModel):
+    access_key: str
+    encrypted_secret_access_key: bytes
+    owner: str
+    valid_until: dt.datetime
+    roles: list[Any] | None = None
+
+
+class ApiKeySummary(BaseModel):
+    access_key: str
+    owner: str
+    valid_until: dt.datetime
+    roles: list[Any] | None = None
+
+
+class ApiKeyCreateRequest(BaseModel):
+    valid_until: dt.datetime
+    roles: list[Any] | None = None
+
+
+class ApiKeyCreateRequestInDB(ApiKeyCreateRequest):
+    access_key: str
+
+
+class ApiKeyCreateResponse(ApiKeySummary):
+    secret_access_key: str
+
+
+class OIDCSessionRecord(BaseModel):
+    session_id: str
+    encrypted_id_token: bytes
+    encrypted_refresh_token: bytes | None = None
+    token_expires_at: dt.datetime
+    session_expires_at: dt.datetime
+    created_at: dt.datetime | None = None
+    updated_at: dt.datetime | None = None
+
+
+class RoleGroupMap(BaseModel):
+    role: str
+    groups: list[str]