memydev-auth-sdk 0.1.0__py3-none-any.whl

memyauth/_config.py

@@ -0,0 +1,407 @@
+"""
+@fileoverview `resolve_config()` — validates and defaults every `MemyAuth` constructor field.
+@module memyauth._config
+@description Pure — no I/O. The single source of `ConfigError` in this SDK (design §F). Mirrors
+   the JS `resolveConfig()` field-for-field, default-for-default, message-for-message so the two
+   languages can be exercised by the same conformance case and produce the same failure. Two
+   points are load-bearing:
+   1. `id_token_validation` has NO DEFAULT (§C.16) — omitting it is itself a `ConfigError`, because
+      the estate genuinely runs both trust strategies in production and a default would be silently
+      wrong for someone.
+   2. An `allowed_algorithms` pin that cannot verify any token this provider issues raises
+      `UnsupportedAlgorithmPinError` HERE, at construction, before any network call — this is the
+      loud-failure mechanism that makes the twice-shipped RS256-vs-ES384 defect (roboson, memyvet)
+      structurally unrepeatable (§C.10.2, test R5).
+   Capability-specific requirements (an IAM caller credential, a session signing secret) are
+   deliberately NOT enforced here — they are enforced lazily, at first use, per §F's validation
+   timing rule, so an IAM-only consumer never needs a session secret.
+@dependencies typing, re, logging, urllib.parse (stdlib only); httpx (type-check only, optional)
+@relatedFiles _errors.py (ConfigError/UnsupportedAlgorithmPinError), _roles.py (DEFAULT_ROLE_MAP),
+   _state.py (COOKIE_NAME_RE), _client.py (calls resolve_config in __init__),
+   tests/test_config.py, tests/test_contract_parity.py (drift-checks the hand-mirrored constants
+   below against ../../contract/contract.json)
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Optional, TypedDict
+from urllib.parse import urlsplit
+
+from ._errors import ConfigError, UnsupportedAlgorithmPinError
+from ._pkce import SystemRandomSource
+from ._roles import DEFAULT_ROLE_MAP
+from ._state import COOKIE_NAME_RE
+from ._types import Clock, RandomSource, SystemClock
+
+__all__ = [
+    "PROVIDER_SIGNING_ALGORITHMS",
+    "DESCRIPTOR_SIGNING_ALGORITHMS",
+    "DEFAULT_SCOPES",
+    "RetryConfig",
+    "ResolvedConfig",
+    "resolve_config",
+]
+
+_log = logging.getLogger("memyauth")
+
+# Hand-mirrored from contract.json's security.signingAlgorithm (the provider's SOLE signing
+# algorithm) — drift-checked at test time by tests/test_contract_parity.py. There is no
+# sync-contract.mjs equivalent for Python; this constant is the one place a Python consumer of
+# this SDK reads it from.
+PROVIDER_SIGNING_ALGORITHMS: tuple[str, ...] = ("ES384",)
+
+# The descriptor schema's full `verification.allowedAlgorithms` enum (contracts/identity/
+# oidc-consumer-request-v1.schema.json) — what a consumer's PIN may legally contain, not what the
+# provider actually issues.
+DESCRIPTOR_SIGNING_ALGORITHMS: tuple[str, ...] = ("RS256", "RS384", "RS512", "ES256", "ES384", "ES512")
+
+DEFAULT_SCOPES: tuple[str, ...] = ("openid", "profile", "email")
+_DEFAULT_CALLBACK_PATH = "/api/auth/oidc/callback"
+_DEFAULT_IAM_BASE_URL = "http://memyauth-service.memydev-auth.svc.cluster.local"
+_DEFAULT_SESSION_ISSUER = "memydev-auth-sdk"
+_DEFAULT_STATE_COOKIE_NAME = "memyauth_state"
+_TOKEN_ENDPOINT_AUTH_METHODS = ("client_secret_post", "client_secret_basic")
+_ID_TOKEN_VALIDATION_MODES = ("local-jwks", "tls-token-endpoint")
+_IAM_CALLER_MODES = ("auto", "appiam", "appidp", "m2m")
+
+_ABSOLUTE_URL_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.\-]*://\S+$")
+
+
+class RetryConfig(TypedDict, total=False):
+    max_retries: int
+    base_delay_ms: int
+    retryable_statuses: list[int]
+
+
+class ResolvedConfig(TypedDict, total=False):
+    issuer_url: str
+    client_id: str
+    client_secret: str
+    internal_issuer_url: Optional[str]
+    public_base_url: Optional[str]
+    callback_path: str
+    redirect_uri: str
+    post_logout_redirect_uri: Optional[str]
+    scopes: list[str]
+    token_endpoint_auth_method: str
+    id_token_validation: str
+    allowed_algorithms: list[str]
+    acknowledge_unverifiable_algorithm_pin: bool
+    strict_unknown_fields: bool
+    iam_base_url: str
+    iam_app_id: Optional[str]
+    iam_app_secret: Optional[str]
+    iam_m2m_token: Optional[str]
+    iam_caller_mode: str
+    iam_timeout_ms: int
+    discovery_timeout_ms: int
+    retry: RetryConfig
+    session_signing_secret: Optional[str]
+    access_ttl_seconds: int
+    refresh_ttl_seconds: int
+    session_issuer: str
+    state_signing_secret: Optional[str]
+    state_ttl_seconds: int
+    state_cookie_name: str
+    role_map: dict[str, str]
+    role_overrides: dict[str, str]
+    default_role: str
+    global_admin_roles: list[str]
+    headers: dict[str, str]
+    transport: Any
+    clock: Clock
+    random: RandomSource
+
+
+def _strip_trailing_slashes(value: str) -> str:
+    return re.sub(r"/+$", "", value)
+
+
+def _is_absolute_http_url(value: str) -> bool:
+    try:
+        parts = urlsplit(value)
+    except ValueError:
+        return False
+    return parts.scheme in ("http", "https") and bool(parts.netloc)
+
+
+def _validate_absolute_http_url(value: Optional[str], field: str) -> Optional[str]:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not _is_absolute_http_url(value):
+        raise ConfigError(f"{field} must be an absolute http(s) URL")
+    return _strip_trailing_slashes(value)
+
+
+def _validate_absolute_url(value: Optional[str], field: str) -> Optional[str]:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not _ABSOLUTE_URL_RE.match(value):
+        raise ConfigError(f"{field} must be an absolute URL")
+    return value
+
+
+def _require_non_empty_str(value: Any, field: str, message: Optional[str] = None) -> str:
+    if not isinstance(value, str) or not value:
+        raise ConfigError(message or f"{field} is required")
+    return value
+
+
+def resolve_config(**kwargs: Any) -> ResolvedConfig:
+    cfg: dict[str, Any] = {}
+
+    # --- required identity fields -----------------------------------------------------------
+    cfg["issuer_url"] = _validate_absolute_http_url(kwargs.get("issuer_url"), "issuerUrl")
+    if cfg["issuer_url"] is None:
+        raise ConfigError("issuerUrl must be an absolute http(s) URL")
+
+    cfg["client_id"] = _require_non_empty_str(kwargs.get("client_id"), "clientId", "clientId is required")
+    cfg["client_secret"] = _require_non_empty_str(
+        kwargs.get("client_secret"), "clientSecret", "clientSecret is required"
+    )
+
+    # --- URLs ---------------------------------------------------------------------------------
+    cfg["internal_issuer_url"] = _validate_absolute_http_url(kwargs.get("internal_issuer_url"), "internalIssuerUrl")
+    cfg["public_base_url"] = _validate_absolute_http_url(kwargs.get("public_base_url"), "publicBaseUrl")
+
+    callback_path = kwargs.get("callback_path", _DEFAULT_CALLBACK_PATH)
+    if not isinstance(callback_path, str) or not callback_path.startswith("/"):
+        raise ConfigError("callbackPath must start with /")
+    cfg["callback_path"] = callback_path
+
+    redirect_uri = kwargs.get("redirect_uri")
+    if redirect_uri is not None:
+        cfg["redirect_uri"] = _validate_absolute_url(redirect_uri, "redirectUri")
+    elif cfg["public_base_url"]:
+        cfg["redirect_uri"] = cfg["public_base_url"] + callback_path
+    else:
+        raise ConfigError("redirectUri or publicBaseUrl must be configured")
+
+    cfg["post_logout_redirect_uri"] = _validate_absolute_url(
+        kwargs.get("post_logout_redirect_uri"), "postLogoutRedirectUri"
+    )
+
+    # --- scopes ---------------------------------------------------------------------------------
+    scopes = kwargs.get("scopes")
+    if scopes is None:
+        scopes = list(DEFAULT_SCOPES)
+    if not isinstance(scopes, (list, tuple)) or len(scopes) == 0 or "openid" not in scopes:
+        raise ConfigError('scopes must include "openid"')
+    cfg["scopes"] = list(scopes)
+
+    # --- token endpoint auth method ---------------------------------------------------------
+    token_endpoint_auth_method = kwargs.get("token_endpoint_auth_method", "client_secret_post")
+    if token_endpoint_auth_method not in _TOKEN_ENDPOINT_AUTH_METHODS:
+        raise ConfigError("tokenEndpointAuthMethod must be client_secret_post or client_secret_basic")
+    cfg["token_endpoint_auth_method"] = token_endpoint_auth_method
+
+    # --- ID-token trust strategy (§C.16 — required, no default) ----------------------------
+    id_token_validation = kwargs.get("id_token_validation")
+    if id_token_validation is None:
+        raise ConfigError(
+            "idTokenValidation is required — choose local-jwks (recommended; verifies the ID "
+            "token signature against provider JWKS) or tls-token-endpoint (no local verification; "
+            "identity comes from userinfo or /iam/me). Both are in production use in this estate, "
+            "so there is deliberately no default."
+        )
+    if id_token_validation not in _ID_TOKEN_VALIDATION_MODES:
+        raise ConfigError("idTokenValidation must be local-jwks or tls-token-endpoint")
+    cfg["id_token_validation"] = id_token_validation
+
+    allowed_algorithms = kwargs.get("allowed_algorithms")
+    if allowed_algorithms is None:
+        allowed_algorithms = ["ES384"] if id_token_validation == "local-jwks" else []
+    allowed_algorithms = list(allowed_algorithms)
+    for alg in allowed_algorithms:
+        if alg not in DESCRIPTOR_SIGNING_ALGORITHMS:
+            raise ConfigError(f"allowedAlgorithms contains an unsupported algorithm: {alg}")
+    if id_token_validation == "tls-token-endpoint" and allowed_algorithms:
+        raise ConfigError("allowedAlgorithms must be empty when idTokenValidation is tls-token-endpoint")
+    if id_token_validation == "local-jwks" and not allowed_algorithms:
+        raise ConfigError("allowedAlgorithms must not be empty when idTokenValidation is local-jwks")
+
+    acknowledge_pin = bool(kwargs.get("acknowledge_unverifiable_algorithm_pin", False))
+    if id_token_validation == "local-jwks":
+        intersects = bool(set(allowed_algorithms) & set(PROVIDER_SIGNING_ALGORITHMS))
+        if not intersects:
+            if not acknowledge_pin:
+                raise UnsupportedAlgorithmPinError(
+                    f"allowedAlgorithms {allowed_algorithms!r} cannot verify any token this "
+                    "provider issues. MemyAuth signs ID tokens with ES384 and nothing else, so "
+                    "this pin refuses every genuine token and sign-in fails closed for every "
+                    "user. Fix the pin, or set acknowledgeUnverifiableAlgorithmPin: true if you "
+                    "are deliberately targeting a different provider."
+                )
+            _log.warning(
+                "memyauth: allowedAlgorithms %r cannot verify any token this provider issues; "
+                "continuing because acknowledgeUnverifiableAlgorithmPin=True was set explicitly.",
+                allowed_algorithms,
+            )
+        elif acknowledge_pin:
+            raise ConfigError(
+                "acknowledgeUnverifiableAlgorithmPin is set but allowedAlgorithms can verify "
+                "this provider's tokens — remove it"
+            )
+    cfg["allowed_algorithms"] = allowed_algorithms
+    cfg["acknowledge_unverifiable_algorithm_pin"] = acknowledge_pin
+    cfg["strict_unknown_fields"] = bool(kwargs.get("strict_unknown_fields", False))
+
+    # --- IAM ------------------------------------------------------------------------------------
+    cfg["iam_base_url"] = _validate_absolute_http_url(
+        kwargs.get("iam_base_url", _DEFAULT_IAM_BASE_URL), "iamBaseUrl"
+    )
+
+    iam_app_id = kwargs.get("iam_app_id")
+    if iam_app_id is not None and (not isinstance(iam_app_id, str) or not iam_app_id):
+        raise ConfigError("iamAppId must be a non-empty string")
+    cfg["iam_app_id"] = iam_app_id
+
+    iam_app_secret = kwargs.get("iam_app_secret")
+    if iam_app_secret is not None:
+        if not isinstance(iam_app_secret, str) or not iam_app_secret:
+            raise ConfigError("iamAppSecret requires iamAppId")
+        if not iam_app_id:
+            raise ConfigError("iamAppSecret requires iamAppId")
+    cfg["iam_app_secret"] = iam_app_secret
+
+    iam_m2m_token = kwargs.get("iam_m2m_token")
+    if iam_m2m_token is not None and (not isinstance(iam_m2m_token, str) or not iam_m2m_token):
+        raise ConfigError("iamM2mToken must be a non-empty string")
+    cfg["iam_m2m_token"] = iam_m2m_token
+
+    iam_caller_mode = kwargs.get("iam_caller_mode", "auto")
+    if iam_caller_mode not in _IAM_CALLER_MODES:
+        raise ConfigError("iamCallerMode must be one of auto, appiam, appidp, m2m")
+    cfg["iam_caller_mode"] = iam_caller_mode
+
+    iam_timeout_ms = kwargs.get("iam_timeout_ms", 10000)
+    if not isinstance(iam_timeout_ms, int) or isinstance(iam_timeout_ms, bool) or not (1 <= iam_timeout_ms <= 120000):
+        raise ConfigError("iamTimeoutMs must be an integer between 1 and 120000")
+    cfg["iam_timeout_ms"] = iam_timeout_ms
+
+    discovery_timeout_ms = kwargs.get("discovery_timeout_ms", iam_timeout_ms)
+    if (
+        not isinstance(discovery_timeout_ms, int)
+        or isinstance(discovery_timeout_ms, bool)
+        or not (1 <= discovery_timeout_ms <= 120000)
+    ):
+        raise ConfigError("discoveryTimeoutMs must be an integer between 1 and 120000")
+    cfg["discovery_timeout_ms"] = discovery_timeout_ms
+
+    # --- retry ----------------------------------------------------------------------------------
+    retry_in = kwargs.get("retry") or {}
+    max_retries = retry_in.get("max_retries", 2)
+    if not isinstance(max_retries, int) or isinstance(max_retries, bool) or not (0 <= max_retries <= 10):
+        raise ConfigError("retry.maxRetries must be an integer between 0 and 10")
+    base_delay_ms = retry_in.get("base_delay_ms", 500)
+    if not isinstance(base_delay_ms, int) or isinstance(base_delay_ms, bool) or not (0 <= base_delay_ms <= 10000):
+        raise ConfigError("retry.baseDelayMs must be an integer between 0 and 10000")
+    retryable_statuses = list(retry_in.get("retryable_statuses", []))
+    for status in retryable_statuses:
+        if not isinstance(status, int) or isinstance(status, bool) or not (400 <= status <= 599):
+            raise ConfigError("retry.retryableStatuses must contain integers between 400 and 599")
+    cfg["retry"] = {
+        "max_retries": max_retries,
+        "base_delay_ms": base_delay_ms,
+        "retryable_statuses": retryable_statuses,
+    }
+
+    # --- session tokens ---------------------------------------------------------------------
+    session_signing_secret = kwargs.get("session_signing_secret")
+    if session_signing_secret is not None and len(session_signing_secret) < 32:
+        raise ConfigError("sessionSigningSecret must be at least 32 characters")
+    cfg["session_signing_secret"] = session_signing_secret
+
+    access_ttl_seconds = kwargs.get("access_ttl_seconds", 14400)
+    if not isinstance(access_ttl_seconds, int) or isinstance(access_ttl_seconds, bool) or access_ttl_seconds < 60:
+        raise ConfigError("accessTtlSeconds must be an integer >= 60")
+    cfg["access_ttl_seconds"] = access_ttl_seconds
+
+    refresh_ttl_seconds = kwargs.get("refresh_ttl_seconds", 7776000)
+    if (
+        not isinstance(refresh_ttl_seconds, int)
+        or isinstance(refresh_ttl_seconds, bool)
+        or refresh_ttl_seconds < access_ttl_seconds
+    ):
+        raise ConfigError("refreshTtlSeconds must be an integer >= accessTtlSeconds")
+    cfg["refresh_ttl_seconds"] = refresh_ttl_seconds
+
+    session_issuer = kwargs.get("session_issuer", _DEFAULT_SESSION_ISSUER)
+    if not isinstance(session_issuer, str) or not session_issuer:
+        raise ConfigError("sessionIssuer must be a non-empty string")
+    cfg["session_issuer"] = session_issuer
+
+    # --- state cookie -----------------------------------------------------------------------
+    state_signing_secret = kwargs.get("state_signing_secret", session_signing_secret)
+    if state_signing_secret is not None and len(state_signing_secret) < 32:
+        raise ConfigError("stateSigningSecret must be at least 32 characters")
+    cfg["state_signing_secret"] = state_signing_secret
+
+    state_ttl_seconds = kwargs.get("state_ttl_seconds", 300)
+    if (
+        not isinstance(state_ttl_seconds, int)
+        or isinstance(state_ttl_seconds, bool)
+        or not (30 <= state_ttl_seconds <= 3600)
+    ):
+        raise ConfigError("stateTtlSeconds must be an integer between 30 and 3600")
+    cfg["state_ttl_seconds"] = state_ttl_seconds
+
+    state_cookie_name = kwargs.get("state_cookie_name", _DEFAULT_STATE_COOKIE_NAME)
+    if not isinstance(state_cookie_name, str) or not COOKIE_NAME_RE.match(state_cookie_name):
+        raise ConfigError("stateCookieName is not a valid cookie name")
+    cfg["state_cookie_name"] = state_cookie_name
+
+    # --- role mapping -----------------------------------------------------------------------
+    role_map = kwargs.get("role_map", DEFAULT_ROLE_MAP)
+    for value in role_map.values():
+        if not isinstance(value, str) or not value:
+            raise ConfigError("roleMap values must be non-empty strings")
+    cfg["role_map"] = dict(role_map)
+
+    role_overrides = kwargs.get("role_overrides", {})
+    for value in role_overrides.values():
+        if not isinstance(value, str) or not value:
+            raise ConfigError("roleOverrides values must be non-empty strings")
+    cfg["role_overrides"] = dict(role_overrides)
+
+    default_role = kwargs.get("default_role", "member")
+    if not isinstance(default_role, str) or not default_role:
+        raise ConfigError("defaultRole must be a non-empty string")
+    cfg["default_role"] = default_role
+
+    global_admin_roles = kwargs.get("global_admin_roles", ["admin"])
+    if not global_admin_roles or any(not isinstance(r, str) or not r for r in global_admin_roles):
+        raise ConfigError("globalAdminRoles must be a non-empty array of role names")
+    cfg["global_admin_roles"] = list(global_admin_roles)
+
+    # --- misc / seams -----------------------------------------------------------------------
+    headers = kwargs.get("headers", {})
+    for value in headers.values():
+        if not isinstance(value, str):
+            raise ConfigError("headers values must be strings")
+    cfg["headers"] = dict(headers)
+
+    transport = kwargs.get("transport")
+    if transport is not None:
+        try:
+            import httpx
+
+            if not isinstance(transport, httpx.BaseTransport):
+                raise ConfigError("transport must be an httpx.BaseTransport")
+        except ImportError:  # pragma: no cover - httpx is a hard runtime dependency
+            pass
+    cfg["transport"] = transport
+
+    clock = kwargs.get("clock")
+    if clock is not None and not callable(getattr(clock, "now", None)):
+        raise ConfigError("clock must expose now()")
+    cfg["clock"] = clock or SystemClock()
+
+    random_source = kwargs.get("random")
+    if random_source is not None and not callable(getattr(random_source, "bytes", None)):
+        raise ConfigError("random must expose bytes(n)")
+    cfg["random"] = random_source or SystemRandomSource()
+
+    return cfg  # type: ignore[return-value]

memyauth/_discovery.py

@@ -0,0 +1,172 @@
+"""
+@fileoverview Capability 1 — OIDC discovery: dual-origin fetch, memoize-on-success, escape guard.
+@module memyauth._discovery
+@description [async -> _sync/_discovery.py twin via scripts/gen_sync.py]. Ported verbatim from
+   `memybase/src/auth/oidc.ts:89-153`. Two invariants are load-bearing:
+   1. MEMOIZE ON SUCCESS ONLY — a failed fetch must NOT be cached, or one transient provider blip
+      disables every future login until process restart. An `asyncio.Lock` serializes concurrent
+      callers so only one fetch happens even under a login stampede.
+   2. DUAL-ORIGIN SAFETY — server-side endpoints (token/userinfo/jwks) must resolve to the SAME
+      origin as the internal fetch issuer; a server-side endpoint that escapes to a different
+      origin is `DiscoveryEscapeError`, not silently followed. Browser-facing endpoints
+      (authorization, end_session) are then rewritten to the PUBLIC origin, preserving
+      pathname+search — a server calling the internal Service DNS name must still hand the
+      browser a URL it can actually reach.
+@dependencies re, asyncio, urllib.parse (stdlib); ._transport
+@relatedFiles _transport.py (Transport.send), _errors.py (DiscoveryError/IssuerMismatchError/
+   DiscoveryEscapeError/ProtocolError), _oidc.py and _idtoken.py (both consume
+   `discovery.discover()`), tests/test_discovery.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+import asyncio
+import re
+from datetime import datetime, timezone
+from typing import Optional
+from urllib.parse import urlsplit
+
+import httpx
+
+# ABSOLUTE imports for the shared/pure modules (see _transport.py's header for why); RELATIVE
+# import for ._transport, which DOES get a _sync/ twin and must bind to ITS sibling twin.
+from memyauth._errors import DiscoveryEscapeError, DiscoveryError, IssuerMismatchError, ProtocolError
+from memyauth._types import Clock, DiscoveryHealth, OidcDiscoveryDocument, SystemClock
+
+from ._transport import Transport
+
+__all__ = ["DiscoveryService"]
+
+_REQUIRED_KEYS = ("issuer", "authorization_endpoint", "token_endpoint", "userinfo_endpoint", "jwks_uri")
+_ABS_HTTP_RE = re.compile(r"^https?://")
+_DEFAULT_TIMEOUT_MS = 10000
+
+
+def _strip_trailing_slashes(value: str) -> str:
+    return re.sub(r"/+$", "", value)
+
+
+def _origin(url: str) -> str:
+    parts = urlsplit(url)
+    return f"{parts.scheme}://{parts.netloc}"
+
+
+def _rewrite_origin(url: str, new_origin: str) -> str:
+    parts = urlsplit(url)
+    tail = parts.path
+    if parts.query:
+        tail += f"?{parts.query}"
+    return new_origin + tail
+
+
+def _iso_utc_ms(epoch_ms: int) -> str:
+    dt = datetime.fromtimestamp(epoch_ms / 1000, tz=timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{epoch_ms % 1000:03d}Z"
+
+
+class DiscoveryService:
+    def __init__(
+        self,
+        *,
+        issuer_url: str,
+        internal_issuer_url: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+        clock: Optional[Clock] = None,
+    ) -> None:
+        self._public_issuer = _strip_trailing_slashes(issuer_url)
+        self._fetch_issuer = _strip_trailing_slashes(internal_issuer_url or issuer_url)
+        self._clock: Clock = clock or SystemClock()
+        self._transport = Transport(timeout_ms=timeout_ms or _DEFAULT_TIMEOUT_MS, transport=transport)
+        # A hand-rolled busy-wait mutex, NOT `asyncio.Lock` — deliberately. `scripts/gen_sync.py`
+        # renames every bare `asyncio` NAME token to `time` (so `asyncio.sleep` -> `time.sleep`,
+        # the substitution the retry backoff in _transport.py wants); `asyncio.Lock` would become
+        # the nonexistent `time.Lock` in the generated sync twin. `asyncio.sleep(0)` survives the
+        # rename as `time.sleep(0)` — a harmless no-op in the sync twin, where a single call stack
+        # can never re-enter this method concurrently in the first place. In the async original,
+        # yielding via `sleep(0)` is a standard (if humble) cooperative spin-lock: correct under
+        # asyncio's single-threaded scheduler, and adequate for a rarely-contended, boot-time-ish
+        # call like discovery.
+        self._locked = False
+        self._cached: Optional[OidcDiscoveryDocument] = None
+        self._last_success_at: Optional[str] = None
+        self._last_error: Optional[str] = None
+
+    async def discover(self) -> OidcDiscoveryDocument:
+        while self._locked:
+            await asyncio.sleep(0)
+        if self._cached is not None:
+            return self._cached
+        self._locked = True
+        try:
+            doc = await self._fetch()
+        except Exception as exc:  # noqa: BLE001 - deliberately broad: every failure clears the memo
+            self._last_error = str(exc)
+            raise
+        finally:
+            self._locked = False
+        self._cached = doc
+        self._last_success_at = _iso_utc_ms(self._clock.now())
+        self._last_error = None
+        return doc
+
+    async def _fetch(self) -> OidcDiscoveryDocument:
+        url = f"{self._fetch_issuer}/.well-known/openid-configuration"
+        resp = await self._transport.send("GET", url)
+        if not (200 <= resp.status_code < 300):
+            raise DiscoveryError(f"OIDC discovery failed: {resp.status_code}")
+        try:
+            doc = resp.json()
+        except ValueError as exc:
+            raise ProtocolError("OIDC discovery response was not JSON") from exc
+        if not isinstance(doc, dict):
+            raise ProtocolError("OIDC discovery response was not a JSON object")
+
+        for key in _REQUIRED_KEYS:
+            value = doc.get(key)
+            if not isinstance(value, str) or not _ABS_HTTP_RE.match(value):
+                raise DiscoveryError(f"OIDC discovery is missing {key}")
+
+        if _strip_trailing_slashes(doc["issuer"]) != self._public_issuer:
+            raise IssuerMismatchError(
+                f"OIDC discovery issuer mismatch: expected {self._public_issuer}, got {doc['issuer']}"
+            )
+
+        if self._fetch_issuer != self._public_issuer:
+            fetch_origin = _origin(self._fetch_issuer)
+            for key in ("token_endpoint", "userinfo_endpoint", "jwks_uri"):
+                if _origin(doc[key]) != fetch_origin:
+                    raise DiscoveryEscapeError(
+                        f"OIDC discovery {key} escaped the internal origin: {doc[key]}"
+                    )
+            public_origin = _origin(self._public_issuer)
+            doc["authorization_endpoint"] = _rewrite_origin(doc["authorization_endpoint"], public_origin)
+            end_session = doc.get("end_session_endpoint")
+            if isinstance(end_session, str):
+                doc["end_session_endpoint"] = _rewrite_origin(end_session, public_origin)
+
+        return doc
+
+    async def warm(self) -> None:
+        """Boot-time readiness warm-up. Never throws."""
+        try:
+            await self.discover()
+        except Exception:  # noqa: BLE001 - intentional: warm() is a best-effort prefetch
+            pass
+
+    def health(self) -> DiscoveryHealth:
+        """Never fetches — reports the last terminal outcome only."""
+        if self._cached is not None:
+            state = "ok"
+        elif self._last_error is not None:
+            state = "failed"
+        else:
+            state = "unknown"
+        return {"state": state, "last_success_at": self._last_success_at, "last_error": self._last_error}
+
+    def reset(self) -> None:
+        """Drops the memo so the next `discover()` call fetches again."""
+        self._cached = None
+
+    async def close(self) -> None:
+        await self._transport.close()