lorebase-keeper 0.2.3__py3-none-any.whl

lorebase_keeper/auth/provider.py

@@ -0,0 +1,250 @@
+"""The OpenID Connect provider as seen by Keeper's sign-in flow (design 13.2).
+
+Provider metadata (discovery), the authorization request with PKCE (RFC 7636, S256 only), the
+token endpoint for the code exchange and refreshes (RFC 6749), and the RP-initiated logout URL
+(OpenID Connect RP-Initiated Logout 1.0). Plain HTTP with httpx, as for the signing keys in
+`oidc.py`: no provider SDK and no new dependency.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import logging
+import secrets
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import parse_qsl, quote, urlencode, urlsplit, urlunsplit
+
+import httpx
+
+from lorebase_keeper.auth.config import OidcSettings, SessionSettings, insecure_url_problem
+from lorebase_keeper.auth.oidc import DISCOVERY_PATH, ProviderUnavailableError
+
+logger = logging.getLogger("lorebase.keeper.auth.provider")
+
+PKCE_METHOD = "S256"
+_VERIFIER_BYTES = 48  # 64 characters of base64url, within RFC 7636's 43 to 128
+
+
+class TokenRefusedError(Exception):
+    """The token endpoint refused the grant (expired or revoked code or refresh token, or a
+    client misconfiguration). The message is for logs only."""
+
+
+def random_token(nbytes: int = 32) -> str:
+    """A URL-safe random string of `nbytes` bytes of entropy."""
+    return secrets.token_urlsafe(nbytes)
+
+
+def pkce_pair() -> tuple[str, str]:
+    """A PKCE code verifier and its S256 challenge."""
+    verifier = secrets.token_urlsafe(_VERIFIER_BYTES)
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return verifier, base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+@dataclass(frozen=True)
+class ProviderMetadata:
+    """The endpoints the sign-in flow uses."""
+
+    authorization_endpoint: str
+    token_endpoint: str
+    end_session_endpoint: str | None
+
+
+@dataclass(frozen=True)
+class TokenResponse:
+    """What the token endpoint returned that Keeper keeps or checks."""
+
+    id_token: str | None
+    refresh_token: str | None
+    expires_in: int | None
+
+
+class ProviderClient:
+    """Metadata, authorization URL, token requests and logout URL of the configured provider."""
+
+    def __init__(
+        self,
+        settings: SessionSettings,
+        oidc: OidcSettings,
+        http: httpx.AsyncClient,
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._settings = settings
+        self._oidc = oidc
+        self._http = http
+        self._monotonic = monotonic
+        self._metadata: ProviderMetadata | None = None
+        self._fetched_at = 0.0
+
+    @property
+    def client_id(self) -> str:
+        """The client id registered at the provider."""
+        return self._settings.client_id or ""
+
+    async def metadata(self) -> ProviderMetadata:
+        """The provider's endpoints, cached for `metadata_cache_ttl_s`.
+
+        `ProviderUnavailableError` when the document cannot be fetched or is not acceptable:
+        another issuer, endpoints over plain http off loopback, or no S256 PKCE support.
+        """
+        now = self._monotonic()
+        if self._metadata and now - self._fetched_at < self._settings.metadata_cache_ttl_s:
+            return self._metadata
+        url = self._settings.discovery_url or (self._oidc.issuer or "").rstrip("/") + DISCOVERY_PATH
+        try:
+            response = await self._http.get(url, headers={"Accept": "application/json"})
+            response.raise_for_status()
+            document = response.json()
+        except (httpx.HTTPError, ValueError) as exc:
+            logger.warning("cannot fetch provider metadata: %s", type(exc).__name__)
+            raise ProviderUnavailableError("provider metadata unavailable") from None
+        self._metadata = self._parse(document)
+        self._fetched_at = now
+        return self._metadata
+
+    def _parse(self, document: object) -> ProviderMetadata:
+        if not isinstance(document, dict) or document.get("issuer") != self._oidc.issuer:
+            logger.warning("provider metadata refused: issuer differs from oidc.issuer")
+            raise ProviderUnavailableError("provider metadata does not match the issuer")
+        methods = document.get("code_challenge_methods_supported")
+        if isinstance(methods, list) and PKCE_METHOD not in methods:
+            logger.warning("provider metadata refused: no S256 PKCE support")
+            raise ProviderUnavailableError("provider does not support S256 PKCE")
+        endpoints: dict[str, str | None] = {}
+        for name in ("authorization_endpoint", "token_endpoint", "end_session_endpoint"):
+            value = document.get(name)
+            if value is None and name == "end_session_endpoint":
+                endpoints[name] = None
+                continue
+            problem = (
+                insecure_url_problem(value, self._oidc.allow_insecure)
+                if isinstance(value, str)
+                else "is missing"
+            )
+            if problem:
+                logger.warning("provider metadata refused: %s %s", name, problem)
+                raise ProviderUnavailableError(f"provider {name} is not acceptable")
+            endpoints[name] = value
+        return ProviderMetadata(
+            authorization_endpoint=endpoints["authorization_endpoint"] or "",
+            token_endpoint=endpoints["token_endpoint"] or "",
+            end_session_endpoint=endpoints["end_session_endpoint"],
+        )
+
+    def authorization_url(
+        self, metadata: ProviderMetadata, *, state: str, nonce: str, challenge: str
+    ) -> str:
+        """The authorization request: code flow, PKCE S256, the configured redirect URI."""
+        settings = self._settings
+        return _with_query(
+            metadata.authorization_endpoint,
+            {
+                "response_type": "code",
+                "client_id": self.client_id,
+                "redirect_uri": settings.redirect_uri or "",
+                "scope": " ".join(settings.scopes),
+                "state": state,
+                "nonce": nonce,
+                "code_challenge": challenge,
+                "code_challenge_method": PKCE_METHOD,
+            },
+        )
+
+    async def exchange_code(self, code: str, verifier: str) -> TokenResponse:
+        """Redeem an authorization code with its PKCE verifier."""
+        return await self._token_request(
+            {
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": self._settings.redirect_uri or "",
+                "code_verifier": verifier,
+            }
+        )
+
+    async def refresh(self, refresh_token: str) -> TokenResponse:
+        """Use a refresh token; `TokenRefusedError` when the provider refuses it."""
+        return await self._token_request(
+            {"grant_type": "refresh_token", "refresh_token": refresh_token}
+        )
+
+    def end_session_url(self, metadata: ProviderMetadata, id_token: str | None) -> str | None:
+        """Where to send the browser to sign out at the provider; None without an endpoint."""
+        if metadata.end_session_endpoint is None:
+            return None
+        settings = self._settings
+        params = {
+            "client_id": self.client_id,
+            "post_logout_redirect_uri": settings.post_logout_redirect_uri or settings.app_url or "",
+        }
+        if id_token:
+            params["id_token_hint"] = id_token
+        return _with_query(metadata.end_session_endpoint, params)
+
+    async def _token_request(self, form: dict[str, str]) -> TokenResponse:
+        metadata = await self.metadata()
+        settings = self._settings
+        headers = {"Accept": "application/json"}
+        secret = settings.client_secret.get_secret_value() if settings.client_secret else ""
+        if settings.token_endpoint_auth_method == "client_secret_basic":
+            # RFC 6749 2.3.1: both parts form-encoded before base64.
+            pair = f"{quote(self.client_id, safe='')}:{quote(secret, safe='')}"
+            headers["Authorization"] = "Basic " + base64.b64encode(pair.encode()).decode()
+        else:
+            form["client_id"] = self.client_id
+            if settings.token_endpoint_auth_method == "client_secret_post":
+                form["client_secret"] = secret
+        try:
+            response = await self._http.post(metadata.token_endpoint, data=form, headers=headers)
+        except httpx.HTTPError as exc:
+            logger.warning("token endpoint unreachable: %s", type(exc).__name__)
+            raise ProviderUnavailableError("token endpoint unreachable") from None
+        if 400 <= response.status_code < 500:
+            raise TokenRefusedError(
+                f"{form['grant_type']} refused with {response.status_code} "
+                f"({_error_code(response)})"
+            )
+        if response.status_code != 200:
+            logger.warning("token endpoint answered %s", response.status_code)
+            raise ProviderUnavailableError("token endpoint failed")
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+        if not isinstance(body, dict):
+            raise ProviderUnavailableError("token endpoint answered no JSON object")
+        return _token_response(body)
+
+
+def _token_response(body: Mapping[str, Any]) -> TokenResponse:
+    id_token = body.get("id_token")
+    refresh_token = body.get("refresh_token")
+    expires_in = body.get("expires_in")
+    if isinstance(expires_in, str) and expires_in.isdecimal():
+        expires_in = int(expires_in)
+    return TokenResponse(
+        id_token=id_token if isinstance(id_token, str) and id_token else None,
+        refresh_token=refresh_token if isinstance(refresh_token, str) and refresh_token else None,
+        expires_in=expires_in if isinstance(expires_in, int) and expires_in > 0 else None,
+    )
+
+
+def _error_code(response: httpx.Response) -> str:
+    """The OAuth error code of a refusal, for logs; never the description."""
+    try:
+        body = response.json()
+    except ValueError:
+        return "no JSON body"
+    code = body.get("error") if isinstance(body, dict) else None
+    return code if isinstance(code, str) and code.isascii() and len(code) <= 64 else "unknown"
+
+
+def _with_query(url: str, params: Mapping[str, str]) -> str:
+    """`url` with `params` added to the query it already has."""
+    parts = urlsplit(url)
+    query = [*parse_qsl(parts.query, keep_blank_values=True), *params.items()]
+    return urlunsplit(parts._replace(query=urlencode(query)))

lorebase_keeper/auth/rbac.py

@@ -0,0 +1,247 @@
+"""Authorization: Domain roles, scoped grants and the permission check (design 10.2).
+
+A grant gives a subject (a principal or a group) a role in a Domain. By default it applies to
+the whole Domain; a grant may be narrowed to a Kind, an Operation or a branch name pattern
+(`agent/*`), and then counts only for requests that name that Kind, Operation or branch.
+Deny by default: a permission is allowed when some grant of the caller's subjects has a role
+containing it and its scope covers the request.
+
+Grants are cached per (Domain, subjects) for `authz.grants_cache_ttl_s`; changes made through
+this process call `invalidate`, other processes converge within the time to live.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from lorebase_keeper.auth.cache import TtlCache
+from lorebase_keeper.auth.config import AuthzSettings
+from lorebase_keeper.auth.permissions import (
+    INSTALLATION_ADMIN_PERMISSIONS,
+    INSTALLATION_PERMISSIONS,
+    Permission,
+    role_catalog,
+)
+from lorebase_keeper.auth.ports import AuthStore
+from lorebase_keeper.auth.principals import Principal
+from lorebase_store.auth import GrantRecord
+from lorebase_store.models.enums import GrantScope
+
+DOMAIN_SCOPE_PREFIX = "domain:"
+
+
+@dataclass(frozen=True)
+class AccessContext:
+    """What a request is about, for grants narrowed to a Kind, Operation or branch."""
+
+    kind: str | None = None
+    operation: str | None = None
+    branch: str | None = None
+
+
+NO_CONTEXT = AccessContext()
+
+
+def domain_scope(domain_id: str) -> str:
+    """The API key scope naming a Domain."""
+    return f"{DOMAIN_SCOPE_PREFIX}{domain_id}"
+
+
+class Authorizer:
+    """Decides whether a principal holds a permission."""
+
+    def __init__(
+        self,
+        settings: AuthzSettings,
+        *,
+        store: AuthStore | None,
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._roles = role_catalog(settings.custom_roles)
+        self.invisible_kinds = settings.invisible_kinds
+        """Whether Kinds left out by Kind-narrowed grants are invisible (design 13.3)."""
+        self._store = store
+        self._cache: TtlCache[tuple[str | None, tuple[str, ...]], tuple[GrantRecord, ...]] = (
+            TtlCache(settings.grants_cache_ttl_s, settings.grants_cache_max_entries, monotonic)
+        )
+
+    @property
+    def role_names(self) -> frozenset[str]:
+        """Roles that can be granted: built in and custom."""
+        return frozenset(self._roles)
+
+    def invalidate(self) -> None:
+        """Drop cached grants after a grant changed through this process."""
+        self._cache.clear()
+
+    async def allows(
+        self,
+        principal: Principal,
+        permission: Permission,
+        domain_id: str,
+        context: AccessContext = NO_CONTEXT,
+    ) -> bool:
+        """Whether `principal` holds `permission` in the Domain for this request context."""
+        if principal.method == "none":
+            return True
+        if principal.key_scopes and domain_scope(domain_id) not in principal.key_scopes:
+            return False
+        grants = await self._grants(principal, domain_id)
+        return any(self._grant_allows(grant, permission, context) for grant in grants)
+
+    async def allows_anywhere(
+        self, principal: Principal, permission: Permission, domain_id: str
+    ) -> bool:
+        """Whether some grant of the principal in the Domain has a role containing
+        `permission`, whatever its scope. Lets a route refuse callers without any such grant
+        before it looks anything up."""
+        if principal.method == "none":
+            return True
+        if principal.key_scopes and domain_scope(domain_id) not in principal.key_scopes:
+            return False
+        grants = await self._grants(principal, domain_id)
+        return any(permission in self._roles.get(grant.role, frozenset()) for grant in grants)
+
+    async def roles_of(
+        self, principal: Principal, domain_id: str, context: AccessContext = NO_CONTEXT
+    ) -> frozenset[str]:
+        """Roles the principal holds in the Domain through grants covering `context`. With
+        authentication off the caller holds every role."""
+        if principal.method == "none":
+            return self.role_names
+        if principal.key_scopes and domain_scope(domain_id) not in principal.key_scopes:
+            return frozenset()
+        grants = await self._grants(principal, domain_id)
+        return frozenset(g.role for g in grants if _covers(g, context))
+
+    async def reveals_missing_domain(self, principal: Principal, domain_id: str) -> bool:
+        """Whether `domain_id` names no Domain and `principal` may be told so (404, not 403).
+
+        Installation administrators and holders of a Domain-wide grant on that id may. Callers
+        without grants there, or with grants narrowed to a Kind, Operation or branch, may not:
+        for them a missing Domain and one they cannot read answer alike, so the answer does not
+        tell whether the Domain exists. A key limited to other Domains never may.
+        """
+        if principal.key_scopes and domain_scope(domain_id) not in principal.key_scopes:
+            return False
+        if not principal.installation_admin:
+            grants = await self._grants(principal, domain_id)
+            if not any(grant.scope_type is GrantScope.DOMAIN for grant in grants):
+                return False
+        return not await self._domain_exists(domain_id)
+
+    async def _domain_exists(self, domain_id: str) -> bool:
+        assert self._store is not None, "authorization needs a store"
+        async with self._store.unit() as unit:
+            return await unit.grants.domain_exists(domain_id)
+
+    async def granted_kinds(
+        self, principal: Principal, permission: Permission, domain_id: str
+    ) -> frozenset[str]:
+        """Kinds that grants narrowed to a Kind give `permission` on, on every branch and
+        Revision of the Domain. Grants not narrowed to a Kind are not listed."""
+        if principal.method == "none":
+            return frozenset()
+        if principal.key_scopes and domain_scope(domain_id) not in principal.key_scopes:
+            return frozenset()
+        grants = await self._grants(principal, domain_id)
+        return frozenset(
+            grant.scope_ref
+            for grant in grants
+            if grant.scope_type is GrantScope.KIND
+            and grant.scope_ref is not None
+            and permission in self._roles.get(grant.role, frozenset())
+        )
+
+    async def domains_granting(
+        self, principal: Principal, permission: Permission
+    ) -> frozenset[str] | None:
+        """Domains where a Domain-wide grant of the principal has a role containing
+        `permission`; None means every Domain (authentication off, or an installation
+        administrator whose key is not limited to Domains)."""
+        if principal.method == "none":
+            return None
+        if principal.installation_admin and not principal.key_scopes:
+            return None
+        grants = await self._grants(principal, None)
+        found = {
+            grant.domain_id
+            for grant in grants
+            if grant.scope_type is GrantScope.DOMAIN
+            and permission in self._roles.get(grant.role, frozenset())
+        }
+        if principal.key_scopes:
+            found = {d for d in found if domain_scope(d) in principal.key_scopes}
+        return frozenset(found)
+
+    async def allows_installation(self, principal: Principal, permission: Permission) -> bool:
+        """Whether `principal` holds an installation-level permission.
+
+        API keys limited to Domains never do, whoever holds them: no Domain scope covers the
+        installation, and the scope check comes before the administrator one. Otherwise
+        installation administrators do, and others do when a Domain-wide grant of theirs has a
+        role containing it.
+        """
+        if permission not in INSTALLATION_PERMISSIONS:
+            raise ValueError(f"{permission.value} is not an installation-level permission")
+        if principal.method == "none":
+            return True
+        if principal.key_scopes:
+            return False
+        if principal.installation_admin:
+            return True
+        if permission in INSTALLATION_ADMIN_PERMISSIONS:
+            return False
+        grants = await self._grants(principal, None)
+        return any(
+            grant.scope_type is GrantScope.DOMAIN
+            and self._grant_allows(grant, permission, AccessContext())
+            for grant in grants
+        )
+
+    async def _grants(self, principal: Principal, domain_id: str | None) -> tuple[GrantRecord, ...]:
+        """Grants of the principal in a Domain, or in every Domain when `domain_id` is None.
+
+        Only None selects every Domain: a Domain id comes from the request and is compared as
+        it is, so no value of it (such as "*") can widen the lookup.
+        """
+        key = (domain_id, principal.subjects)
+        cached = self._cache.get(key)
+        if cached is not None:
+            return cached
+        assert self._store is not None, "authorization needs a store"
+        async with self._store.unit() as unit:
+            found = (
+                await unit.grants.for_subjects_anywhere(principal.subjects)
+                if domain_id is None
+                else await unit.grants.for_subjects(domain_id, principal.subjects)
+            )
+        grants = tuple(found)
+        self._cache.set(key, grants)
+        return grants
+
+    def _grant_allows(
+        self, grant: GrantRecord, permission: Permission, context: AccessContext
+    ) -> bool:
+        return permission in self._roles.get(grant.role, frozenset()) and _covers(grant, context)
+
+
+def _covers(grant: GrantRecord, context: AccessContext) -> bool:
+    ref = grant.scope_ref
+    match grant.scope_type:
+        case GrantScope.DOMAIN:
+            return True
+        case GrantScope.KIND:
+            return ref is not None and context.kind == ref
+        case GrantScope.OPERATION:
+            return ref is not None and context.operation == ref
+        case GrantScope.BRANCH:
+            return (
+                ref is not None
+                and context.branch is not None
+                and fnmatch.fnmatchcase(context.branch, ref)
+            )
+    return False  # pragma: no cover - exhaustive over GrantScope