lorebase-keeper 0.2.3__py3-none-any.whl

lorebase_keeper/auth/deps.py

@@ -0,0 +1,183 @@
+"""FastAPI dependencies for authentication and authorization.
+
+Routes depend on `require(permission)` (a Domain permission, the Domain taken from the path) or
+`require_installation(permission)`; both authenticate first and return what they decided on:
+
+    @router.get("/domains/{domain_id}/grants")
+    async def list_grants(access: Annotated[Access, Depends(require(Permission.GRANT_MANAGE))]): ...
+
+Kind, Operation and branch scoped grants are evaluated when the route names the path parameter
+that carries them (`kind_param`, `operation_param`, `branch_param`).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Annotated, cast
+
+from fastapi import Depends, Request
+from fastapi.security import HTTPBearer
+
+from lorebase_keeper.auth.audit import annotate
+from lorebase_keeper.auth.permissions import Permission
+from lorebase_keeper.auth.principals import Principal
+from lorebase_keeper.auth.rbac import NO_CONTEXT, AccessContext, Authorizer
+from lorebase_keeper.auth.runtime import AuthRuntime
+from lorebase_keeper.client_address import client_address
+from lorebase_keeper.errors import FORBIDDEN, NOT_FOUND, UNAVAILABLE, ProblemError
+
+_PRINCIPAL_KEY = "principal"
+_bearer_scheme = HTTPBearer(auto_error=False, description="API key (lbk_...) or OIDC access token.")
+
+
+def get_auth(request: Request) -> AuthRuntime:
+    """The application's auth components."""
+    return cast(AuthRuntime, request.app.state.auth)
+
+
+AuthDep = Annotated[AuthRuntime, Depends(get_auth)]
+
+
+def require_store(auth: AuthRuntime) -> None:
+    """Raise 503 when no database is configured (administration needs one)."""
+    if auth.store is None:
+        raise ProblemError(UNAVAILABLE, "This operation needs a configured database.")
+
+
+async def current_principal(
+    request: Request,
+    auth: AuthDep,
+    _credentials: Annotated[object, Depends(_bearer_scheme)] = None,
+) -> Principal:
+    """Authenticate the request (once) or answer 401."""
+    state = request.scope.setdefault("state", {})
+    principal = state.get(_PRINCIPAL_KEY)
+    if principal is None:
+        principal = await auth.authenticator.authenticate(
+            request.headers, client_address(request), request.method
+        )
+        state[_PRINCIPAL_KEY] = principal
+    annotate(request, actor=principal.id, principal_type=principal.type.value)
+    return cast(Principal, principal)
+
+
+PrincipalDep = Annotated[Principal, Depends(current_principal)]
+
+
+@dataclass(frozen=True)
+class Access:
+    """An authorized request: who, in which Domain (none for installation-level), what for."""
+
+    principal: Principal
+    domain_id: str | None
+    permission: Permission
+    kinds: frozenset[str] | None = None
+    """Set when only grants narrowed to these Kinds allowed the request (`require` with
+    `kind_limited`): the response must not tell about other Kinds."""
+
+
+def require(
+    permission: Permission,
+    *,
+    domain_param: str = "domain_id",
+    kind_param: str | None = None,
+    operation_param: str | None = None,
+    branch_param: str | None = None,
+    kind_limited: bool = False,
+) -> Callable[..., Awaitable[Access]]:
+    """Dependency: the caller holds `permission` in the Domain named by the path.
+
+    With `kind_limited`, grants narrowed to Kinds count too when Kinds are invisible to such
+    callers (`keeper.auth.authz.invisible_kinds`, design 13.3): for reads that tell nothing
+    about Kinds (the Domain, its branches and tags), which a caller limited to Kinds needs to
+    find its way. `Access.kinds` then names them.
+
+    Answers 401 without a valid credential and 403, naming the missing permission, otherwise.
+    """
+
+    async def dependency(request: Request, principal: PrincipalDep, auth: AuthDep) -> Access:
+        params = request.path_params
+        domain_id = str(params[domain_param])
+        context = AccessContext(
+            kind=_param(params, kind_param),
+            operation=_param(params, operation_param),
+            branch=_param(params, branch_param),
+        )
+        try:
+            return await authorize(request, auth, principal, permission, domain_id, context)
+        except ProblemError as error:
+            if not kind_limited or error.status_code != 403:
+                raise
+            kinds = await limited_kinds(auth.authorizer, principal, permission, domain_id)
+            if not kinds:
+                raise
+            return Access(principal, domain_id, permission, kinds)
+
+    return dependency
+
+
+async def authorize(
+    request: Request,
+    auth: AuthRuntime,
+    principal: Principal,
+    permission: Permission,
+    domain_id: str,
+    context: AccessContext = NO_CONTEXT,
+) -> Access:
+    """Check `permission` in a Domain for a context known only inside the route (a branch or
+    Operation named in the body). Answers 403 naming the missing permission."""
+    annotate(request, domain_id=domain_id, permission=permission.value)
+    if not await auth.authorizer.allows(principal, permission, domain_id, context):
+        raise await refusal(auth.authorizer, principal, permission, domain_id)
+    return Access(principal=principal, domain_id=domain_id, permission=permission)
+
+
+async def limited_kinds(
+    authorizer: Authorizer, principal: Principal, permission: Permission, domain_id: str
+) -> frozenset[str]:
+    """Kinds that grants narrowed to Kinds give `permission` on, when such Kinds are invisible
+    to the caller (design 13.3); empty otherwise."""
+    if not authorizer.invisible_kinds:
+        return frozenset()
+    return await authorizer.granted_kinds(principal, permission, domain_id)
+
+
+async def refusal(
+    authorizer: Authorizer, principal: Principal, permission: Permission, domain_id: str
+) -> ProblemError:
+    """The problem for a caller who lacks `permission` in a Domain: 404 when the Domain does not
+    exist and the caller may be told so (see `Authorizer.reveals_missing_domain`), else 403."""
+    if await authorizer.reveals_missing_domain(principal, domain_id):
+        return ProblemError(NOT_FOUND, f"Domain {domain_id!r} not found.")
+    return missing_permission(permission, domain_id)
+
+
+def missing_permission(permission: Permission, domain_id: str) -> ProblemError:
+    """The 403 problem naming the permission a caller lacks in a Domain."""
+    return ProblemError(
+        FORBIDDEN,
+        f"Missing permission {permission.value} in Domain {domain_id}.",
+        extensions={"permission": permission.value, "domain": domain_id},
+    )
+
+
+def require_installation(permission: Permission) -> Callable[..., Awaitable[Access]]:
+    """Dependency: the caller holds an installation-level `permission`."""
+
+    async def dependency(request: Request, principal: PrincipalDep, auth: AuthDep) -> Access:
+        annotate(request, permission=permission.value)
+        if not await auth.authorizer.allows_installation(principal, permission):
+            raise ProblemError(
+                FORBIDDEN,
+                f"Missing permission {permission.value}.",
+                extensions={"permission": permission.value},
+            )
+        return Access(principal=principal, domain_id=None, permission=permission)
+
+    return dependency
+
+
+def _param(params: dict[str, object], name: str | None) -> str | None:
+    value = params.get(name) if name else None
+    return None if value is None else str(value)

lorebase_keeper/auth/keyring.py

@@ -0,0 +1,14 @@
+"""Keys derived from `keeper.auth.sessions.encryption_key` (`lorebase_store.keyring`)."""
+
+from __future__ import annotations
+
+from lorebase_store.keyring import Keyring as _Keyring
+
+NAMESPACE = "keeper"
+
+
+class Keyring(_Keyring):
+    """The session keyring: keys derived under the `keeper` namespace."""
+
+    def __init__(self, secret: str) -> None:
+        super().__init__(secret, namespace=NAMESPACE)

lorebase_keeper/auth/oidc.py

@@ -0,0 +1,242 @@
+"""Bearer token validation against any OpenID Connect provider (design 13.2).
+
+Tokens are JWTs checked against the provider's published signing keys (JWKS): signature,
+issuer, audience, expiry and not-before, with the configured clock skew. Keys are fetched with
+httpx and cached; an unknown key id triggers at most one refresh per `jwks_min_refresh_s`.
+
+PyJWT (with `cryptography`) does the token work. python-jose was not chosen: it is barely
+maintained and has had several security advisories; PyJWT is maintained, small and parses JWKS
+natively. No provider SDK is involved: discovery and key download are plain HTTP.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hmac
+import logging
+import time
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+import jwt
+from jwt import PyJWK
+
+from lorebase_keeper.auth.config import OidcSettings, insecure_url_problem
+
+logger = logging.getLogger("lorebase.keeper.auth.oidc")
+
+DISCOVERY_PATH = "/.well-known/openid-configuration"
+
+
+class InvalidTokenError(Exception):
+    """The token is not acceptable. The message is for logs, never for the client."""
+
+
+class ProviderUnavailableError(Exception):
+    """The provider's keys cannot be obtained, so no token can be judged."""
+
+
+@dataclass(frozen=True)
+class OidcClaims:
+    """What Keeper needs from a validated token."""
+
+    subject: str
+    display_name: str
+    groups: tuple[str, ...]
+
+
+class JwksCache:
+    """Signing keys of the provider, refreshed after a time to live or for an unknown key id."""
+
+    def __init__(
+        self,
+        settings: OidcSettings,
+        http: httpx.AsyncClient,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._settings = settings
+        self._http = http
+        self._clock = clock
+        self._keys: dict[str, PyJWK] = {}
+        self._fetched_at: float | None = None
+        self._attempted_at: float | None = None
+        self._jwks_uri = settings.jwks_uri
+        self._lock = asyncio.Lock()
+
+    async def key_for(self, kid: str | None) -> PyJWK:
+        """The signing key with this id (the only key when the token names none)."""
+        if self._is_stale():
+            await self._refresh()
+        key = self._find(kid)
+        if key is None:
+            await self._refresh()  # the provider may have rotated its keys
+            key = self._find(kid)
+        if key is None:
+            if not self._keys:
+                raise ProviderUnavailableError("signing keys unavailable")
+            raise InvalidTokenError(f"no signing key {kid!r}")
+        return key
+
+    def _find(self, kid: str | None) -> PyJWK | None:
+        if kid is not None:
+            return self._keys.get(kid)
+        return next(iter(self._keys.values())) if len(self._keys) == 1 else None
+
+    def _is_stale(self) -> bool:
+        return (
+            self._fetched_at is None
+            or self._clock() - self._fetched_at >= self._settings.jwks_cache_ttl_s
+        )
+
+    async def _refresh(self) -> None:
+        """Fetch the keys, unless an attempt was made less than `jwks_min_refresh_s` ago.
+
+        On failure the previous keys stay in use and the next attempt waits for the same delay,
+        so an unreachable provider is not hammered.
+        """
+        async with self._lock:
+            now = self._clock()
+            if (
+                self._attempted_at is not None
+                and now - self._attempted_at < self._settings.jwks_min_refresh_s
+            ):
+                return
+            self._attempted_at = now
+            try:
+                document = await self._fetch_jwks()
+            except (httpx.HTTPError, ValueError) as exc:
+                logger.warning("cannot fetch signing keys: %s", type(exc).__name__)
+                return
+            self._keys = _parse_keys(document)
+            self._fetched_at = now
+
+    async def _fetch_jwks(self) -> Mapping[str, Any]:
+        if self._jwks_uri is None:
+            self._jwks_uri = await self._discover()
+        response = await self._http.get(self._jwks_uri)
+        response.raise_for_status()
+        document = response.json()
+        if not isinstance(document, dict) or not isinstance(document.get("keys"), list):
+            raise ValueError("malformed JWKS document")
+        return document
+
+    async def _discover(self) -> str:
+        issuer = self._settings.issuer or ""
+        response = await self._http.get(issuer.rstrip("/") + DISCOVERY_PATH)
+        response.raise_for_status()
+        document = response.json()
+        if not isinstance(document, dict) or document.get("issuer") != issuer:
+            raise ValueError("discovery document does not match the configured issuer")
+        uri = document.get("jwks_uri")
+        if not isinstance(uri, str) or not uri:
+            raise ValueError("discovery document has no jwks_uri")
+        problem = insecure_url_problem(uri, self._settings.allow_insecure)
+        if problem:
+            logger.warning("discovered jwks_uri %r refused: %s", uri, problem)
+            raise ValueError("discovered jwks_uri is not acceptable")
+        return uri
+
+
+def _parse_keys(document: Mapping[str, Any]) -> dict[str, PyJWK]:
+    keys: dict[str, PyJWK] = {}
+    for index, entry in enumerate(document["keys"]):
+        if not isinstance(entry, dict) or entry.get("use", "sig") != "sig":
+            continue
+        try:
+            key = PyJWK(entry)
+        except jwt.PyJWTError:
+            logger.info("skipping unsupported signing key %s", entry.get("kid", index))
+            continue
+        keys[str(entry.get("kid", f"#{index}"))] = key
+    return keys
+
+
+class OidcVerifier:
+    """Validates bearer tokens and extracts the claims Keeper uses."""
+
+    def __init__(self, settings: OidcSettings, jwks: JwksCache) -> None:
+        self._settings = settings
+        self._jwks = jwks
+
+    async def verify(self, token: str) -> OidcClaims:
+        """Claims of a valid token; `InvalidTokenError` or `ProviderUnavailableError` otherwise."""
+        claims = await self._decode(token, self._settings.audience, ("exp", "iss", "aud"))
+        return self._claims(claims)
+
+    async def verify_id_token(
+        self,
+        token: str,
+        *,
+        client_id: str,
+        nonce: str | None = None,
+        nonce_required: bool = True,
+    ) -> OidcClaims:
+        """Claims of a valid ID token issued to `client_id` (OpenID Connect Core 3.1.3.7).
+
+        The audience must contain the client id and, with several audiences, `azp` must name it.
+        `nonce`, when given, must equal the token's. At sign-in the token must carry it; a
+        refreshed ID token (`nonce_required=False`) may omit it but, if present, must carry the
+        sign-in's nonce (Core 12.2).
+        """
+        claims = await self._decode(token, (client_id,), ("exp", "iat", "iss", "aud"))
+        audience = claims.get("aud")
+        if isinstance(audience, list) and len(audience) > 1 and claims.get("azp") != client_id:
+            raise InvalidTokenError("azp does not name this client")
+        if nonce is not None:
+            received = claims.get("nonce")
+            if received is None and not nonce_required:
+                return self._claims(claims)
+            if not isinstance(received, str) or not hmac.compare_digest(received, nonce):
+                raise InvalidTokenError("nonce mismatch")
+        return self._claims(claims)
+
+    async def _decode(
+        self, token: str, audience: Sequence[str], required: Sequence[str]
+    ) -> dict[str, Any]:
+        settings = self._settings
+        try:
+            header = jwt.get_unverified_header(token)
+            algorithm = header.get("alg")
+            if algorithm not in settings.algorithms:
+                raise InvalidTokenError(f"algorithm {algorithm!r} is not accepted")
+            key = await self._jwks.key_for(header.get("kid"))
+            claims: dict[str, Any] = jwt.decode(
+                token,
+                key.key,
+                algorithms=[algorithm],
+                audience=list(audience),
+                issuer=settings.issuer,
+                leeway=settings.clock_skew_s,
+                options={"require": [*required, settings.subject_claim]},
+            )
+        except jwt.PyJWTError as exc:
+            raise InvalidTokenError(f"{type(exc).__name__}: {exc}") from None
+        return claims
+
+    def _claims(self, claims: Mapping[str, Any]) -> OidcClaims:
+        settings = self._settings
+        subject = claims.get(settings.subject_claim)
+        if not isinstance(subject, str) or not subject:
+            raise InvalidTokenError("subject claim is not a non-empty string")
+        return OidcClaims(
+            subject=subject,
+            display_name=self._display_name(claims, subject),
+            groups=_groups(claims.get(settings.groups_claim)),
+        )
+
+    def _display_name(self, claims: Mapping[str, Any], subject: str) -> str:
+        for name in self._settings.name_claims:
+            value = claims.get(name)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+        return subject
+
+
+def _groups(value: object) -> tuple[str, ...]:
+    if isinstance(value, str):
+        return (value,)
+    if isinstance(value, list):
+        return tuple(str(item) for item in value if isinstance(item, str))
+    return ()

lorebase_keeper/auth/permissions.py

@@ -0,0 +1,142 @@
+"""Permissions and the built-in Domain roles (design 10.2).
+
+A role is a named set of permissions. Roles are granted per Domain (see `rbac`); installations
+may add roles built from these permissions in `keeper.auth.authz.custom_roles`. The built-in
+roles cannot be redefined.
+
+Role semantics where the design table leaves room:
+
+- every role except `admin` is additive on top of read access, so a principal holding only
+  `editor` can still read what it edits;
+- `maintainer` includes `editor` and `reviewer`, not `modeler`;
+- `editor` and `modeler` open Proposals (`proposal.create`) from the branches they change;
+  `editor` (and so `maintainer`) also triggers Source synchronizations (`source.sync`), whose
+  outcome goes through the Source's merge policy;
+  `editor` uploads documents for extraction (`document.write`) and reads them
+  (`document.read`); `reviewer` reads documents too, since extraction items quote them;
+  documents are raw, unmasked input, so `viewer`, `explorer` and `agent-reader` do not read
+  them;
+  `reviewer` reviews them and resolves Conflicts; merging needs `proposal.merge`
+  (`maintainer`), into protected and unprotected branches alike;
+- `admin` holds every permission of the Domain (it is the Domain owner role); only it may
+  delete the Domain (`domain.delete`), read values of sensitive Attributes (`pii.read`,
+  `confidential.read`, `restricted.read`; other callers see them masked), erase vault
+  values (`pii.erase`) and feed values of vault Attributes through the built-in imports and
+  Source synchronizations (`pii.import`, see `services.pii_import`); custom roles grant the
+  clearances to others. `admin` also reads the agent traces of other principals in its Domain
+  (`trace.read`) and the query plans of traced requests (`trace.explain`); every principal
+  reads its own traces. `domain.create` is installation-level: installation administrators
+  hold it, and so do admins of any Domain;
+- `vault.manage` (vault key rotation and its status) is held by installation administrators
+  only: no role, built in or custom, contains it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from enum import StrEnum
+from types import MappingProxyType
+
+
+class Permission(StrEnum):
+    """What a route may require. Names are stable: they appear in 403 responses."""
+
+    SCHEMA_READ = "schema.read"
+    DATA_READ = "data.read"
+    VIEWS_WRITE = "views.write"
+    BRANCH_CREATE = "branch.create"
+    OPERATION_EXECUTE = "operation.execute"
+    OPERATION_EXECUTE_CUSTOM = "operation.execute_custom"
+    SCHEMA_WRITE = "schema.write"
+    SOURCE_MAP = "source.map"
+    PROPOSAL_CREATE = "proposal.create"
+    PROPOSAL_REVIEW = "proposal.review"
+    CONFLICT_RESOLVE = "conflict.resolve"
+    PROPOSAL_MERGE = "proposal.merge"
+    SOURCE_MANAGE = "source.manage"
+    SOURCE_SYNC = "source.sync"
+    DOCUMENT_READ = "document.read"
+    DOCUMENT_WRITE = "document.write"
+    JOB_MANAGE = "job.manage"
+    GRANT_MANAGE = "grant.manage"
+    APIKEY_MANAGE = "apikey.manage"
+    DOMAIN_SETTINGS = "domain.settings"
+    DOMAIN_DELETE = "domain.delete"
+    DOMAIN_CREATE = "domain.create"
+    AUDIT_READ = "audit.read"
+    PRINCIPAL_READ = "principal.read"
+    PII_READ = "pii.read"
+    CONFIDENTIAL_READ = "confidential.read"
+    RESTRICTED_READ = "restricted.read"
+    PII_ERASE = "pii.erase"
+    PII_IMPORT = "pii.import"
+    TRACE_READ = "trace.read"
+    TRACE_EXPLAIN = "trace.explain"
+    VAULT_MANAGE = "vault.manage"
+
+
+INSTALLATION_ADMIN_PERMISSIONS = frozenset({Permission.VAULT_MANAGE})
+"""Installation-level permissions only installation administrators hold: no role contains
+them."""
+
+INSTALLATION_PERMISSIONS = (
+    frozenset({Permission.PRINCIPAL_READ, Permission.DOMAIN_CREATE})
+    | INSTALLATION_ADMIN_PERMISSIONS
+)
+"""Permissions that are not about one Domain: installation administrators hold them, and so do
+principals who hold them through a role in at least one Domain (except
+`INSTALLATION_ADMIN_PERMISSIONS`)."""
+
+_VIEWER = frozenset({Permission.SCHEMA_READ, Permission.DATA_READ})
+_EDITOR = _VIEWER | {
+    Permission.BRANCH_CREATE,
+    Permission.OPERATION_EXECUTE,
+    Permission.PROPOSAL_CREATE,
+    Permission.SOURCE_SYNC,
+    Permission.DOCUMENT_READ,
+    Permission.DOCUMENT_WRITE,
+}
+_REVIEWER = _VIEWER | {
+    Permission.PROPOSAL_REVIEW,
+    Permission.CONFLICT_RESOLVE,
+    Permission.DOCUMENT_READ,
+}
+
+BUILTIN_ROLES: Mapping[str, frozenset[Permission]] = MappingProxyType(
+    {
+        "viewer": _VIEWER,
+        "explorer": _VIEWER | {Permission.VIEWS_WRITE},
+        "editor": _EDITOR,
+        "operator": _VIEWER | {Permission.OPERATION_EXECUTE_CUSTOM},
+        "modeler": _VIEWER
+        | {Permission.SCHEMA_WRITE, Permission.SOURCE_MAP, Permission.PROPOSAL_CREATE},
+        "reviewer": _REVIEWER,
+        "maintainer": _EDITOR
+        | _REVIEWER
+        | {Permission.PROPOSAL_MERGE, Permission.SOURCE_MANAGE, Permission.JOB_MANAGE},
+        "admin": frozenset(Permission) - INSTALLATION_ADMIN_PERMISSIONS,
+        "agent-reader": _VIEWER,
+    }
+)
+
+
+def permission_names() -> frozenset[str]:
+    """Every permission name."""
+    return frozenset(p.value for p in Permission)
+
+
+def role_catalog(
+    custom: Mapping[str, Iterable[str]] | None = None,
+) -> dict[str, frozenset[Permission]]:
+    """Built-in roles plus `custom` ones. Unknown permissions raise `ValueError`."""
+    catalog = dict(BUILTIN_ROLES)
+    for name, permissions in (custom or {}).items():
+        if name in BUILTIN_ROLES:
+            raise ValueError(f"role {name!r} is built in and cannot be redefined")
+        granted = frozenset(Permission(p) for p in permissions)
+        reserved = granted & INSTALLATION_ADMIN_PERMISSIONS
+        if reserved:
+            names = ", ".join(sorted(p.value for p in reserved))
+            raise ValueError(f"role {name!r}: {names} is held by installation administrators only")
+        catalog[name] = granted
+    return catalog