terp-cap-oidc 0.1.0__tar.gz

terp_cap_oidc-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright (conformance e2e) artifacts
+test-results/
+playwright-report/
+blob-report/
+playwright/.cache/
+.last-run.json
+
+# Local frontend template render checks
+apps/example/_frontend_tpl_check/
+
+# Editor / OS
+.DS_Store
+.idea/
+*.local
+
+# Local environment overrides — never commit (a real .env may hold SECRET_KEY).
+# The tracked template is `.env.example`.
+.env
+.env.*
+!.env.example
+!.env.example.jinja
+# Rendered app-declared variables (environment.schema.json) — may hold secrets.
+.app.env

terp_cap_oidc-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: terp-cap-oidc
+Version: 0.1.0
+Summary: Terp OIDC capability — pluggable SSO via the OpenID Connect code flow with PKCE.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyjwt[crypto]>=2.8
+Requires-Dist: terp-cap-auth==0.1.0
+Requires-Dist: terp-core==0.1.0

terp_cap_oidc-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "terp-cap-oidc"
+version = "0.1.0"
+description = "Terp OIDC capability — pluggable SSO via the OpenID Connect code flow with PKCE."
+requires-python = ">=3.13"
+license = "Apache-2.0"
+dependencies = [
+    "terp-core==0.1.0",
+    "terp-cap-auth==0.1.0",
+    # The token-endpoint exchange + discovery/JWKS fetches (like the webhooks delivery
+    # client, the outbound HTTP client lives only inside the capability).
+    "httpx>=0.27",
+    # ID-token signature validation against the provider JWKS (asymmetric algorithms
+    # need the crypto extra).
+    "pyjwt[crypto]>=2.8",
+]
+
+# A library capability: the app builds its module explicitly (build_oidc_module) with
+# its provider registry + identity seam, so there is no self-registering entry point.
+
+# PEP 420 namespace package: this distribution owns only `terp.capabilities.oidc`.
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = ["src/terp/capabilities/oidc"]

terp_cap_oidc-0.1.0/src/terp/capabilities/oidc/__init__.py

@@ -0,0 +1,56 @@
+"""terp.capabilities.oidc — pluggable SSO via the OpenID Connect code flow (ADR 0058).
+
+An opt-in capability implementing the Authorization Code flow with PKCE against any
+spec-compliant OIDC provider — no vendor tenant baked in (design §5.5). It owns the
+*protocol* only: the app wires the one identity seam
+(``resolve_or_provision(session, claims) -> Principal | None``, backed by the identity
+capability's federated store) and the auth capability's token seams, so an SSO login
+mints a normal Terp session and every existing session control (revocation, refresh,
+``/me``, ``/logout``) covers it unchanged.
+"""
+
+from __future__ import annotations
+
+from terp.capabilities.oidc.client import (
+    ALLOWED_ALGORITHMS,
+    CLOCK_SKEW_LEEWAY_SECONDS,
+    OIDCClient,
+    ProviderUnavailableError,
+)
+from terp.capabilities.oidc.config import OIDCClaims, OIDCProviderConfig
+from terp.capabilities.oidc.router import (
+    IdentityResolver,
+    SecretResolver,
+    build_oidc_module,
+    build_oidc_router,
+)
+from terp.capabilities.oidc.schemas import AuthorizationRequest, OIDCCallbackRequest
+from terp.capabilities.oidc.state import (
+    DEFAULT_STATE_TTL,
+    InMemoryStateStore,
+    OIDCStateStore,
+    PendingAuthorization,
+    code_challenge_s256,
+    generate_code_verifier,
+)
+
+__all__ = [
+    "ALLOWED_ALGORITHMS",
+    "AuthorizationRequest",
+    "CLOCK_SKEW_LEEWAY_SECONDS",
+    "DEFAULT_STATE_TTL",
+    "IdentityResolver",
+    "InMemoryStateStore",
+    "OIDCCallbackRequest",
+    "OIDCClaims",
+    "OIDCClient",
+    "OIDCProviderConfig",
+    "OIDCStateStore",
+    "PendingAuthorization",
+    "ProviderUnavailableError",
+    "SecretResolver",
+    "build_oidc_module",
+    "build_oidc_router",
+    "code_challenge_s256",
+    "generate_code_verifier",
+]

terp_cap_oidc-0.1.0/src/terp/capabilities/oidc/client.py

@@ -0,0 +1,227 @@
+"""The OIDC protocol client: discovery, JWKS, code exchange, ID-token validation.
+
+One ``OIDCClient`` per configured provider. Endpoints and signing keys come from the
+issuer's ``/.well-known/openid-configuration`` (fetched lazily, cached for the client's
+lifetime); the JWKS is cached too and re-fetched **once** when a token names an unknown
+``kid`` (key rotation). Validation is fail-closed (ADR 0058): asymmetric signature
+algorithms only (``alg=none`` / HS* are never accepted), exact ``iss`` / ``aud`` /
+``nonce`` matches, ``exp`` / ``iat`` required with bounded clock skew, and the discovery
+document's ``issuer`` must equal the configured issuer (IdP mix-up defense). Every
+validation failure is the uniform 401; an unreachable provider is a distinct 502 so
+operators can tell an outage from an attack.
+
+The outbound HTTP client lives only inside this capability (like the webhooks delivery
+client); tests inject an ``http_factory`` returning an ``httpx.Client`` over a mock
+transport.
+"""
+
+from __future__ import annotations
+
+from threading import Lock
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+import jwt
+
+from terp.core import AppError, AuthenticationError
+
+from terp.capabilities.oidc.config import OIDCClaims, OIDCProviderConfig
+
+#: Asymmetric signature algorithms accepted on an ID token. ``alg=none`` and the
+#: HS* (symmetric) family are excluded by construction: with HS* the "key" would be
+#: the client secret, and a leaked secret could then forge identities.
+ALLOWED_ALGORITHMS: tuple[str, ...] = ("RS256", "RS384", "RS512", "PS256", "ES256", "ES384")
+
+#: Bounded clock skew for ``exp`` / ``iat`` validation, in seconds.
+CLOCK_SKEW_LEEWAY_SECONDS = 60
+
+_DISCOVERY_PATH = "/.well-known/openid-configuration"
+_HTTP_TIMEOUT_SECONDS = 10.0
+
+
+class ProviderUnavailableError(AppError):
+    """502 — the identity provider could not be reached or answered malformed data."""
+
+    status_code = 502
+    code = "oidc_provider_unavailable"
+    default_message = "The identity provider is unavailable; please try again."
+
+
+def _default_http_factory() -> httpx.Client:
+    return httpx.Client(timeout=_HTTP_TIMEOUT_SECONDS)
+
+
+class OIDCClient:
+    """The protocol client for one configured provider."""
+
+    def __init__(
+        self,
+        config: OIDCProviderConfig,
+        *,
+        http_factory: Callable[[], httpx.Client] | None = None,
+    ) -> None:
+        self._config = config
+        self._http_factory = http_factory or _default_http_factory
+        self._lock = Lock()
+        self._discovery: dict[str, Any] | None = None
+        self._jwks: jwt.PyJWKSet | None = None
+
+    @property
+    def config(self) -> OIDCProviderConfig:
+        return self._config
+
+    # ------------------------------------------------------------------ #
+    # discovery + JWKS
+    # ------------------------------------------------------------------ #
+    def _get_json(self, url: str) -> dict[str, Any]:
+        """GET *url* and parse JSON; any transport / status / parse failure is a 502."""
+        try:
+            with self._http_factory() as client:
+                response = client.get(url)
+                response.raise_for_status()
+                payload = response.json()
+        except (httpx.HTTPError, ValueError) as exc:
+            raise ProviderUnavailableError() from exc
+        if not isinstance(payload, dict):
+            raise ProviderUnavailableError()
+        return payload
+
+    def discovery(self) -> dict[str, Any]:
+        """The provider's discovery document (fetched once, then cached)."""
+        with self._lock:
+            if self._discovery is None:
+                document = self._get_json(
+                    self._config.issuer.rstrip("/") + _DISCOVERY_PATH
+                )
+                # IdP mix-up defense: the document must claim exactly the configured
+                # issuer, and must name the three endpoints the code flow needs.
+                if document.get("issuer") != self._config.issuer:
+                    raise ProviderUnavailableError(
+                        "The provider's discovery document does not match the "
+                        "configured issuer."
+                    )
+                for key in ("authorization_endpoint", "token_endpoint", "jwks_uri"):
+                    if not document.get(key):
+                        raise ProviderUnavailableError(
+                            "The provider's discovery document is missing a "
+                            "required endpoint."
+                        )
+                self._discovery = document
+            return self._discovery
+
+    def _signing_key(self, token: str) -> jwt.PyJWK:
+        """The JWKS key for *token*'s ``kid`` — re-fetching once on rotation."""
+        try:
+            kid = jwt.get_unverified_header(token).get("kid")
+        except jwt.PyJWTError as exc:
+            raise AuthenticationError() from exc
+        if not kid:
+            raise AuthenticationError()
+        jwks_uri = str(self.discovery()["jwks_uri"])
+        with self._lock:
+            for refreshed in (False, True):
+                if self._jwks is None or refreshed:
+                    try:
+                        self._jwks = jwt.PyJWKSet.from_dict(self._get_json(jwks_uri))
+                    except jwt.PyJWTError as exc:
+                        raise ProviderUnavailableError() from exc
+                for key in self._jwks.keys:
+                    if key.key_id == kid:
+                        return key
+            raise AuthenticationError()
+
+    # ------------------------------------------------------------------ #
+    # the code flow
+    # ------------------------------------------------------------------ #
+    def authorization_url(self, *, state: str, nonce: str, code_challenge: str) -> str:
+        """The IdP authorize URL for one flow — code + PKCE (S256) parameters only."""
+        params = httpx.QueryParams(
+            response_type="code",
+            client_id=self._config.client_id,
+            redirect_uri=self._config.redirect_uri,
+            scope=" ".join(self._config.scopes),
+            state=state,
+            nonce=nonce,
+            code_challenge=code_challenge,
+            code_challenge_method="S256",
+        )
+        endpoint = str(self.discovery()["authorization_endpoint"])
+        separator = "&" if "?" in endpoint else "?"
+        return f"{endpoint}{separator}{params}"
+
+    def exchange_code(self, *, code: str, code_verifier: str, client_secret: str) -> str:
+        """Redeem *code* at the token endpoint; return the raw ID token.
+
+        The IdP's access / refresh tokens in the response are deliberately ignored
+        (ADR 0058): Terp mints its own session, so they are used zero times and never
+        stored or returned.
+        """
+        endpoint = str(self.discovery()["token_endpoint"])
+        try:
+            with self._http_factory() as client:
+                response = client.post(
+                    endpoint,
+                    data={
+                        "grant_type": "authorization_code",
+                        "code": code,
+                        "redirect_uri": self._config.redirect_uri,
+                        "client_id": self._config.client_id,
+                        "client_secret": client_secret,
+                        "code_verifier": code_verifier,
+                    },
+                )
+        except httpx.HTTPError as exc:
+            raise ProviderUnavailableError() from exc
+        if response.status_code != 200:
+            # A refused exchange (bad / replayed / expired code) is an auth failure,
+            # not an outage — the uniform 401.
+            raise AuthenticationError()
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise ProviderUnavailableError() from exc
+        id_token = payload.get("id_token") if isinstance(payload, dict) else None
+        if not isinstance(id_token, str) or not id_token:
+            raise AuthenticationError()
+        return id_token
+
+    def validate_id_token(self, raw_token: str, *, nonce: str) -> OIDCClaims:
+        """Fully validate *raw_token*; return the typed claims or raise the uniform 401."""
+        key = self._signing_key(raw_token)
+        try:
+            payload = jwt.decode(
+                raw_token,
+                key=key,
+                algorithms=list(ALLOWED_ALGORITHMS),
+                audience=self._config.client_id,
+                issuer=self._config.issuer,
+                leeway=CLOCK_SKEW_LEEWAY_SECONDS,
+                options={"require": ["exp", "iat", "iss", "aud", "sub"]},
+            )
+        except jwt.PyJWTError as exc:
+            raise AuthenticationError() from exc
+        if payload.get("nonce") != nonce:
+            # The nonce binds the token to the flow this server started; a mismatch
+            # is an injected / replayed token.
+            raise AuthenticationError()
+        subject = payload.get("sub")
+        if not isinstance(subject, str) or not subject:
+            raise AuthenticationError()
+        email = payload.get("email")
+        return OIDCClaims(
+            issuer=self._config.issuer,
+            subject=subject,
+            email=email if isinstance(email, str) and email else None,
+            email_verified=payload.get("email_verified") is True,
+            name=payload.get("name") if isinstance(payload.get("name"), str) else None,
+            raw=payload,
+        )
+
+
+__all__ = [
+    "ALLOWED_ALGORITHMS",
+    "CLOCK_SKEW_LEEWAY_SECONDS",
+    "OIDCClient",
+    "ProviderUnavailableError",
+]

terp_cap_oidc-0.1.0/src/terp/capabilities/oidc/config.py

@@ -0,0 +1,79 @@
+"""Provider registry — one validated ``OIDCProviderConfig`` per named provider.
+
+Fail-fast (ADR 0058): a config is validated at construction, so a misconfigured
+provider refuses to boot instead of failing on the first login. The redirect URI is
+the app's own explicit allowlisted value — it is signed into every authorize request
+and echoed at the token exchange, so an attacker-supplied redirect can never enter
+the flow (deny-by-default, mirroring the CORS stance). In production the issuer and
+redirect URI must be ``https``; the scopes must include ``openid`` (without it the
+IdP would run plain OAuth2 and return no ID token).
+
+The ``client_secret`` may be a sealed ``enc:v1:`` value (ADR 0055); the capability
+never decrypts it — see ``build_oidc_module``'s ``secret_resolver`` seam.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from terp.core import settings
+
+_NAME_RE = re.compile(r"^[a-z][a-z0-9_-]*$")
+
+
+@dataclass(frozen=True)
+class OIDCProviderConfig:
+    """One OIDC provider: issuer + client credentials + the allowlisted redirect URI."""
+
+    name: str
+    issuer: str
+    client_id: str
+    client_secret: str
+    redirect_uri: str
+    scopes: tuple[str, ...] = ("openid", "email", "profile")
+
+    def __post_init__(self) -> None:
+        if not _NAME_RE.match(self.name):
+            raise ValueError(
+                f"OIDC provider name {self.name!r} must be a lowercase slug "
+                "(it becomes a path segment)"
+            )
+        if "openid" not in self.scopes:
+            raise ValueError(
+                f"OIDC provider {self.name!r} must request the 'openid' scope; "
+                "without it the IdP returns no ID token"
+            )
+        for label, url in (("issuer", self.issuer), ("redirect_uri", self.redirect_uri)):
+            if not url.startswith(("https://", "http://")):
+                raise ValueError(
+                    f"OIDC provider {self.name!r} {label} must be an http(s) URL"
+                )
+            if settings.is_production and not url.startswith("https://"):
+                raise ValueError(
+                    f"OIDC provider {self.name!r} {label} must be https in production "
+                    "(a plaintext redirect leaks the authorization code)"
+                )
+        if not self.client_id:
+            raise ValueError(f"OIDC provider {self.name!r} requires a client_id")
+
+
+@dataclass(frozen=True)
+class OIDCClaims:
+    """The validated identity claims an SSO login hands to the identity seam.
+
+    Only what the ``resolve_or_provision`` seam needs: the stable ``(issuer, subject)``
+    pair links to a local user; the email pair gates JIT provisioning (a provisioner
+    must refuse an unverified email — ADR 0058). The IdP's raw tokens never leave the
+    capability.
+    """
+
+    issuer: str
+    subject: str
+    email: str | None = None
+    email_verified: bool = False
+    name: str | None = None
+    raw: dict[str, object] = field(default_factory=dict)
+
+
+__all__ = ["OIDCClaims", "OIDCProviderConfig"]

terp_cap_oidc-0.1.0/src/terp/capabilities/oidc/router.py

@@ -0,0 +1,234 @@
+"""The SSO login router + ``ModuleSpec`` builder for the OIDC capability (ADR 0058).
+
+Two public routes per configured provider, shaped for a SPA client:
+
+* ``GET /{provider}/authorize`` opens a flow — generates ``state`` / ``nonce`` / PKCE
+  verifier into the single-use state store and returns the IdP authorize URL; and
+* ``POST /{provider}/callback`` finishes it — consumes the state (single-use,
+  expiring), exchanges the code (PKCE verifier + client secret), fully validates the
+  ID token, resolves a principal through the app-wired identity seam, and mints a
+  normal **Terp** session (the IdP's tokens are used once and discarded).
+
+The capability owns protocol, never users: ``resolve_or_provision(session, claims)``
+is the one identity seam (the ``authenticate`` analog), app-wired to the identity
+capability's federated store. Token minting reuses the auth capability's machinery
+unchanged — the ``tenant_resolver`` / ``token_version_resolver`` (ADR 0031) /
+``refresh_issuer`` (ADR 0054) seams — so revocation, ``/refresh``, ``/me``, and
+``/logout`` cover an SSO session exactly as a password one.
+
+A sealed (``enc:v1:``) client secret requires the app-wired ``secret_resolver`` (the
+app's single allowlisted decrypt site, ADR 0055); a sealed secret with no resolver is
+refused at construction, and the capability itself never calls ``decrypt_config``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+import httpx
+from fastapi import APIRouter, Request, Response
+from sqlmodel import Session
+
+from terp.core import (
+    AuthenticationError,
+    ModuleSpec,
+    NotFoundError,
+    Policy,
+    Principal,
+    SessionDep,
+    client_ip,
+    is_sealed_config,
+)
+
+from terp.capabilities.auth import (
+    AccessToken,
+    LoginTenantResolver,
+    LoginThrottle,
+    RefreshIssuer,
+    TokenVersionResolver,
+    create_access_token,
+    set_refresh_cookie,
+)
+
+from terp.capabilities.oidc.client import OIDCClient
+from terp.capabilities.oidc.config import OIDCClaims, OIDCProviderConfig
+from terp.capabilities.oidc.schemas import AuthorizationRequest, OIDCCallbackRequest
+from terp.capabilities.oidc.state import (
+    InMemoryStateStore,
+    OIDCStateStore,
+    code_challenge_s256,
+)
+
+# The one identity seam (the ``authenticate`` analog): validated claims in, a
+# principal (or a refusal) out. App-wired so OIDC never imports where users live.
+IdentityResolver = Callable[[Session, OIDCClaims], Principal | None]
+# Unseal a sealed client secret — app-wired to its single allowlisted decrypt site
+# (ADR 0055); the capability never decrypts.
+SecretResolver = Callable[[str], str]
+
+
+def _throttle_key(provider: str, request: Request) -> str:
+    """Per-source lockout key for the callback (the login-throttle analog).
+
+    Keys on the centrally resolved client address (``terp.core.client_ip``), so a
+    deployment that declared ``SecurityConfig.trusted_proxy_hops`` throttles the
+    real caller rather than collapsing everyone onto the proxy's IP.
+    """
+    return f"oidc:{provider}:{client_ip(request)}"
+
+
+def build_oidc_router(
+    providers: Sequence[OIDCProviderConfig],
+    resolve_or_provision: IdentityResolver,
+    *,
+    tenant_resolver: LoginTenantResolver | None = None,
+    token_version_resolver: TokenVersionResolver | None = None,
+    refresh_issuer: RefreshIssuer | None = None,
+    throttle: LoginThrottle | None = None,
+    state_store: OIDCStateStore | None = None,
+    secret_resolver: SecretResolver | None = None,
+    http_factory: Callable[[], httpx.Client] | None = None,
+) -> APIRouter:
+    """Build the per-provider ``/authorize`` + ``/callback`` router (fail-fast).
+
+    Construction refuses an empty or name-colliding registry, and a sealed client
+    secret with no *secret_resolver* — a misconfigured provider fails the boot, not
+    the first login.
+    """
+    if not providers:
+        raise ValueError("build_oidc_router requires at least one OIDCProviderConfig")
+    registry: dict[str, OIDCProviderConfig] = {}
+    for config in providers:
+        if config.name in registry:
+            raise ValueError(f"duplicate OIDC provider name {config.name!r}")
+        if is_sealed_config(config.client_secret) and secret_resolver is None:
+            raise ValueError(
+                f"OIDC provider {config.name!r} has a sealed client_secret but no "
+                "secret_resolver is wired; the capability never decrypts (ADR 0055)"
+            )
+        registry[config.name] = config
+
+    clients = {
+        name: OIDCClient(config, http_factory=http_factory)
+        for name, config in registry.items()
+    }
+    store = state_store if state_store is not None else InMemoryStateStore()
+    active_throttle = throttle if throttle is not None else LoginThrottle()
+
+    def _client(provider: str) -> OIDCClient:
+        client = clients.get(provider)
+        if client is None:
+            raise NotFoundError(f"Unknown SSO provider {provider!r}.")
+        return client
+
+    def _client_secret(config: OIDCProviderConfig) -> str:
+        if is_sealed_config(config.client_secret):
+            assert secret_resolver is not None  # noqa: S101 - enforced at construction
+            return secret_resolver(config.client_secret)
+        return config.client_secret
+
+    def _mint_access_token(session: Session, principal: Principal) -> str:
+        tenant = tenant_resolver(session, principal) if tenant_resolver is not None else None
+        token_version = (
+            token_version_resolver(session, principal)
+            if token_version_resolver is not None
+            else 0
+        )
+        return create_access_token(
+            subject=principal.id,
+            role=principal.role,
+            tenant=tenant,
+            token_version=token_version,
+        )
+
+    router = APIRouter(tags=["auth"])
+
+    @router.get("/{provider}/authorize", response_model=AuthorizationRequest)
+    def authorize(provider: str) -> AuthorizationRequest:
+        client = _client(provider)
+        state, pending = store.issue(provider)
+        return AuthorizationRequest(
+            provider=provider,
+            authorization_url=client.authorization_url(
+                state=state,
+                nonce=pending.nonce,
+                code_challenge=code_challenge_s256(pending.code_verifier),
+            ),
+        )
+
+    @router.post("/{provider}/callback", response_model=AccessToken)
+    def callback(
+        provider: str,
+        payload: OIDCCallbackRequest,
+        session: SessionDep,
+        request: Request,
+        response: Response,
+    ) -> AccessToken:
+        client = _client(provider)
+        identifier = _throttle_key(provider, request)
+        active_throttle.check(identifier)
+        pending = store.consume(payload.state, provider)
+        if pending is None:
+            # Unknown, expired, replayed, or cross-provider state — the uniform 401.
+            active_throttle.record_failure(identifier)
+            raise AuthenticationError()
+        id_token = client.exchange_code(
+            code=payload.code,
+            code_verifier=pending.code_verifier,
+            client_secret=_client_secret(client.config),
+        )
+        claims = client.validate_id_token(id_token, nonce=pending.nonce)
+        principal = resolve_or_provision(session, claims)
+        if principal is None:
+            active_throttle.record_failure(identifier)
+            raise AuthenticationError()
+        active_throttle.record_success(identifier)
+        token = _mint_access_token(session, principal)
+        if refresh_issuer is not None:
+            # The SSO session gets the same rotating refresh cookie a password login
+            # does (ADR 0054), so reloads and /refresh work identically.
+            set_refresh_cookie(response, refresh_issuer(session, principal.id))
+        return AccessToken(access_token=token)
+
+    return router
+
+
+def build_oidc_module(
+    providers: Sequence[OIDCProviderConfig],
+    resolve_or_provision: IdentityResolver,
+    *,
+    name: str = "oidc",
+    tenant_resolver: LoginTenantResolver | None = None,
+    token_version_resolver: TokenVersionResolver | None = None,
+    refresh_issuer: RefreshIssuer | None = None,
+    throttle: LoginThrottle | None = None,
+    state_store: OIDCStateStore | None = None,
+    secret_resolver: SecretResolver | None = None,
+    http_factory: Callable[[], httpx.Client] | None = None,
+) -> ModuleSpec:
+    """Build the SSO ``ModuleSpec`` (public authorize + callback endpoints)."""
+    return ModuleSpec(
+        name=name,
+        router=build_oidc_router(
+            providers,
+            resolve_or_provision,
+            tenant_resolver=tenant_resolver,
+            token_version_resolver=token_version_resolver,
+            refresh_issuer=refresh_issuer,
+            throttle=throttle,
+            state_store=state_store,
+            secret_resolver=secret_resolver,
+            http_factory=http_factory,
+        ),
+        policy=Policy.public_write(
+            reason="SSO login endpoints must be reachable without a token"
+        ),
+    )
+
+
+__all__ = [
+    "IdentityResolver",
+    "SecretResolver",
+    "build_oidc_module",
+    "build_oidc_router",
+]

terp_cap_oidc-0.1.0/src/terp/capabilities/oidc/schemas.py

@@ -0,0 +1,28 @@
+"""SSO request/response DTOs."""
+
+from __future__ import annotations
+
+from sqlmodel import Field
+
+from terp.core import BaseSchema
+
+
+class AuthorizationRequest(BaseSchema):
+    """The IdP authorize URL for one freshly-opened flow — the client navigates to it.
+
+    The binding secrets (``state`` server-side lookup key aside, the ``nonce`` and the
+    PKCE verifier) stay server-side in the state store; only the URL leaves.
+    """
+
+    provider: str
+    authorization_url: str
+
+
+class OIDCCallbackRequest(BaseSchema):
+    """What the IdP appended to the redirect URI, relayed by the client."""
+
+    code: str = Field(max_length=4096)
+    state: str = Field(max_length=512)
+
+
+__all__ = ["AuthorizationRequest", "OIDCCallbackRequest"]

terp_cap_oidc-0.1.0/src/terp/capabilities/oidc/state.py

@@ -0,0 +1,125 @@
+"""Single-use, TTL-bounded authorization state (ADR 0058).
+
+Every ``/authorize`` issues a fresh ``state`` (the CSRF binder), ``nonce`` (bound
+into the ID token), and PKCE ``code_verifier`` — all from ``secrets`` — and parks
+them here until the callback presents the ``state`` back. ``consume`` is strictly
+single-use (a replayed state finds nothing) and expiring (an abandoned flow ages
+out), so a captured callback URL cannot be replayed and the store cannot grow
+without bound. In-memory and per-process by default — an authorization flow is
+short-lived, so per-instance state suffices behind a sticky or single-API setup; a
+multi-instance deployment swaps in a shared :class:`OIDCStateStore` implementation
+(e.g. ``terp.capabilities.redis.oidc.RedisOIDCStateStore``) so any replica can
+finish a flow another replica opened.
+"""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import secrets
+from threading import Lock
+from base64 import urlsafe_b64encode
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+DEFAULT_STATE_TTL = datetime.timedelta(minutes=10)
+
+
+def _utc_now() -> datetime.datetime:
+    """UTC ``now`` provider — private so tests can monkeypatch the clock."""
+    return datetime.datetime.now(datetime.UTC)
+
+
+@dataclass(frozen=True)
+class PendingAuthorization:
+    """One in-flight authorization: what the callback must match against."""
+
+    provider: str
+    nonce: str
+    code_verifier: str
+    expires_at: datetime.datetime
+
+
+def generate_code_verifier() -> str:
+    """A high-entropy PKCE code verifier (RFC 7636 §4.1)."""
+    return secrets.token_urlsafe(64)
+
+
+def code_challenge_s256(verifier: str) -> str:
+    """The S256 code challenge for *verifier* (RFC 7636 §4.2): base64url(sha256), unpadded."""
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+@runtime_checkable
+class OIDCStateStore(Protocol):
+    """The single-use authorization-state port every state store implements.
+
+    The router only ever calls these two methods, so a deployment picks its scope by
+    implementation: the default :class:`InMemoryStateStore` is per-process (one API
+    replica or sticky routing); a shared implementation (e.g. the Redis-backed store in
+    ``terp-cap-redis[oidc]``) lets any replica finish a flow another replica opened.
+    Every implementation must keep ``consume`` strictly single-use, expiring, and
+    provider-matched.
+    """
+
+    def issue(self, provider: str) -> tuple[str, PendingAuthorization]:
+        """Open a new flow for *provider*: returns ``(state, pending)``."""
+        ...
+
+    def consume(self, state: str, provider: str) -> PendingAuthorization | None:
+        """Redeem *state* exactly once, or ``None`` (unknown / expired / wrong provider)."""
+        ...
+
+
+class InMemoryStateStore:
+    """The default per-process single-use state store."""
+
+    def __init__(self, *, ttl: datetime.timedelta = DEFAULT_STATE_TTL) -> None:
+        self._ttl = ttl
+        self._pending: dict[str, PendingAuthorization] = {}
+        self._lock = Lock()
+
+    def issue(self, provider: str) -> tuple[str, PendingAuthorization]:
+        """Open a new flow for *provider*: returns ``(state, pending)``."""
+        state = secrets.token_urlsafe(32)
+        pending = PendingAuthorization(
+            provider=provider,
+            nonce=secrets.token_urlsafe(32),
+            code_verifier=generate_code_verifier(),
+            expires_at=_utc_now() + self._ttl,
+        )
+        with self._lock:
+            self._prune()
+            self._pending[state] = pending
+        return state, pending
+
+    def consume(self, state: str, provider: str) -> PendingAuthorization | None:
+        """Redeem *state* exactly once, or ``None`` (unknown / expired / wrong provider).
+
+        The provider match refuses a cross-provider splice: a state issued for one
+        provider cannot finish another provider's callback.
+        """
+        with self._lock:
+            pending = self._pending.pop(state, None)
+        if pending is None or pending.provider != provider:
+            return None
+        if pending.expires_at <= _utc_now():
+            return None
+        return pending
+
+    def _prune(self) -> None:
+        """Drop expired flows (called under the lock) so abandoned logins age out."""
+        now = _utc_now()
+        for key in [k for k, v in self._pending.items() if v.expires_at <= now]:
+            del self._pending[key]
+
+
+__all__ = [
+    "DEFAULT_STATE_TTL",
+    "InMemoryStateStore",
+    "OIDCStateStore",
+    "PendingAuthorization",
+    "code_challenge_s256",
+    "generate_code_verifier",
+]