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

memyauth/_session.py

@@ -0,0 +1,149 @@
+"""
+@fileoverview SDK-owned HS256 session tokens — access + refresh, structurally separate from the
+   provider's ES384 OIDC tokens.
+@module memyauth._session
+@description SYNCHRONOUS (PyJWT is sync) — a deliberate, documented asymmetry with the JS SDK's
+   `async` session methods (jose's `SignJWT.sign()`/`jwtVerify()` return promises). Because this
+   module has no `async`, it is a SHARED PURE module with no `_sync/` twin: both
+   `memyauth.SessionTokenService` and `memyauth.sync.SessionTokenService` import the exact same
+   class object (§C.7). The separation from provider tokens is enforced SIX ways — see the class
+   docstring — because a consumer that once confuses "a token I signed" with "a token MemyAuth
+   signed" has a forgeable-identity bug, not a cosmetic one.
+@dependencies pyjwt[crypto]
+@relatedFiles _types.py (SessionAccessClaims/SessionRefreshClaims/Clock), _errors.py
+   (ConfigError/SessionTokenError), _idtoken.py (the OTHER verifier — provider tokens only),
+   tests/test_session.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import jwt
+
+from ._errors import ConfigError, SessionTokenError
+from ._types import Clock, SessionAccessClaims, SessionAccessInput, SessionRefreshClaims, SessionRefreshInput, SystemClock
+
+__all__ = ["SessionTokenService"]
+
+_MIN_SECRET_LENGTH = 32
+_DEFAULT_ACCESS_TTL_SECONDS = 14400  # 4h
+_DEFAULT_REFRESH_TTL_SECONDS = 7776000  # 90d
+_DEFAULT_ISSUER = "memydev-auth-sdk"
+_ALGORITHM = "HS256"
+
+
+class SessionTokenService:
+    """Issues and verifies the SDK's own HS256 session-token family.
+
+    The separation from provider (ES384) tokens is enforced SIX ways (§C.7 — this ranking
+    outranks any naming a goal-prompt might request elsewhere):
+
+    1. Separate class — `IdTokenVerifier` (see `_idtoken.py`) is the only class that touches
+       provider tokens; neither class can do the other's job.
+    2. Separate secret field — `signing_secret` (symmetric, >= 32 chars) is never read by any
+       provider-token path; the provider's `issuer_url`/JWKS is never read here.
+    3. Mandatory `type` discriminator (`'access'` / `'refresh'`) — verification rejects the wrong
+       value.
+    4. Mandatory `iss` claim — SDK-issued tokens carry `iss = issuer` (default
+       `'memydev-auth-sdk'`); a provider token's `iss = https://auth.memy.dev/oidc` fails this
+       check before any crypto matters.
+    5. Algorithm pin — verification passes `algorithms=['HS256']` only; an ES384 token (the
+       provider's family) is rejected on `alg` alone.
+    6. Naming — every exported symbol carries `Session`; the plan's bare `AccessClaims` /
+       `RefreshClaims` names are never exported under any alias.
+    """
+
+    def __init__(
+        self,
+        *,
+        signing_secret: str,
+        access_ttl_seconds: int = _DEFAULT_ACCESS_TTL_SECONDS,
+        refresh_ttl_seconds: int = _DEFAULT_REFRESH_TTL_SECONDS,
+        issuer: str = _DEFAULT_ISSUER,
+        clock: Optional[Clock] = None,
+    ) -> None:
+        if not signing_secret or len(signing_secret) < _MIN_SECRET_LENGTH:
+            raise ConfigError(f"sessionSigningSecret must be at least {_MIN_SECRET_LENGTH} characters")
+        if refresh_ttl_seconds < access_ttl_seconds:
+            raise ConfigError("refreshTtlSeconds must be an integer >= accessTtlSeconds")
+
+        self._secret = signing_secret
+        self._access_ttl = access_ttl_seconds
+        self._refresh_ttl = refresh_ttl_seconds
+        self._issuer = issuer
+        self._clock: Clock = clock or SystemClock()
+
+    def _iat(self) -> int:
+        return self._clock.now() // 1000
+
+    def issue_access_token(self, claims: SessionAccessInput) -> str:
+        iat = self._iat()
+        payload: dict[str, Any] = {
+            **claims,
+            "type": "access",
+            "iss": self._issuer,
+            "iat": iat,
+            "exp": iat + self._access_ttl,
+        }
+        return jwt.encode(payload, self._secret, algorithm=_ALGORITHM)
+
+    def issue_refresh_token(self, claims: SessionRefreshInput) -> str:
+        iat = self._iat()
+        payload: dict[str, Any] = {
+            **claims,
+            "type": "refresh",
+            "iss": self._issuer,
+            "iat": iat,
+            "exp": iat + self._refresh_ttl,
+        }
+        return jwt.encode(payload, self._secret, algorithm=_ALGORITHM)
+
+    def _decode(self, token: str) -> dict[str, Any]:
+        try:
+            # `verify_exp`/`verify_iat` are disabled here and re-checked manually below against
+            # the INJECTED clock, not PyJWT's wall-clock read — otherwise a token minted under a
+            # fixed test clock (or any clock skewed from the real host clock) would read as
+            # already-expired to PyJWT regardless of the ttl actually configured.
+            payload = jwt.decode(
+                token,
+                self._secret,
+                algorithms=[_ALGORITHM],
+                issuer=self._issuer,
+                options={"verify_exp": False, "verify_iat": False, "require": ["exp", "iat", "iss", "type"]},
+            )
+        except jwt.PyJWTError as exc:
+            # The message NEVER echoes the token — PyJWT's own exception text does not include it.
+            raise SessionTokenError(f"session token verification failed: {exc}") from exc
+
+        now_seconds = self._clock.now() / 1000
+        exp = payload.get("exp")
+        if not isinstance(exp, (int, float)) or now_seconds > exp:
+            raise SessionTokenError("session token verification failed: token has expired")
+        return payload
+
+    def verify_access_token(self, token: str) -> SessionAccessClaims:
+        payload = self._decode(token)
+        if payload.get("type") != "access":
+            raise SessionTokenError("session token verification failed: wrong type (expected access)")
+        return payload  # type: ignore[return-value]
+
+    def verify_refresh_token(self, token: str) -> SessionRefreshClaims:
+        payload = self._decode(token)
+        if payload.get("type") != "refresh":
+            raise SessionTokenError("session token verification failed: wrong type (expected refresh)")
+        return payload  # type: ignore[return-value]
+
+    def is_session_token(self, token: str) -> bool:
+        """Recognize an SDK-signed token WITHOUT accepting it as unexpired authorization.
+        Verifies the signature only (never `exp`); returns False on any failure — never throws."""
+        try:
+            payload = jwt.decode(
+                token,
+                self._secret,
+                algorithms=[_ALGORITHM],
+                options={"verify_exp": False, "verify_iat": False},
+            )
+        except jwt.PyJWTError:
+            return False
+        return payload.get("type") in ("access", "refresh") and payload.get("iss") == self._issuer

memyauth/_state.py

@@ -0,0 +1,139 @@
+"""
+@fileoverview HS256 state cookie — PKCE/nonce/state carrier and the actual CSRF check.
+@module memyauth._state
+@description SYNCHRONOUS (same PyJWT asymmetry as `_session.py` — shared pure module, no `_sync/`
+   twin). Claim keys (`cv`/`n`/`rt`/`st`) are ported VERBATIM from
+   `memybase/src/auth/oidc.ts:227-235` so a cookie signed by memybase stays readable by this SDK
+   and vice versa. `verify()` alone only proves the cookie is ours; `verify_callback()` is the
+   actual CSRF defense — it constant-time-compares the callback's `state` query parameter against
+   the signed cookie's `st` claim (`hmac.compare_digest`), which is what the goal-prompt calls
+   "CSRF protection".
+@dependencies pyjwt[crypto], hmac (stdlib)
+@relatedFiles _session.py (the sibling HS256-but-different-purpose service), _oidc.py
+   (build_authorization_url mints the state/nonce this cookie carries), _config.py (state_*
+   field validation), tests/test_state.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+import hmac
+import re
+from typing import Any, Optional
+
+import jwt
+
+from ._errors import ConfigError, StateCookieError, StateMismatchError
+from ._types import Clock, StateCookieInput, StateCookiePayload, SystemClock
+
+__all__ = ["StateCookieService", "COOKIE_NAME_RE"]
+
+_MIN_SECRET_LENGTH = 32
+_DEFAULT_TTL_SECONDS = 300
+_DEFAULT_COOKIE_NAME = "memyauth_state"
+_ALGORITHM = "HS256"
+_MIN_TTL = 30
+_MAX_TTL = 3600
+
+# RFC 6265 §4.1.1 cookie-name token charset (also enforced at the top-level config layer, §F).
+COOKIE_NAME_RE = re.compile(r"^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$")
+
+
+class StateCookieService:
+    def __init__(
+        self,
+        *,
+        signing_secret: str,
+        ttl_seconds: int = _DEFAULT_TTL_SECONDS,
+        cookie_name: str = _DEFAULT_COOKIE_NAME,
+        clock: Optional[Clock] = None,
+    ) -> None:
+        if not signing_secret or len(signing_secret) < _MIN_SECRET_LENGTH:
+            raise ConfigError(f"stateSigningSecret must be at least {_MIN_SECRET_LENGTH} characters")
+        if not (_MIN_TTL <= ttl_seconds <= _MAX_TTL):
+            raise ConfigError(f"stateTtlSeconds must be an integer between {_MIN_TTL} and {_MAX_TTL}")
+        if not cookie_name or not COOKIE_NAME_RE.match(cookie_name):
+            raise ConfigError("stateCookieName is not a valid cookie name")
+
+        self._secret = signing_secret
+        self._ttl = ttl_seconds
+        self._cookie_name = cookie_name
+        self._clock: Clock = clock or SystemClock()
+
+    @property
+    def cookie_name(self) -> str:
+        return self._cookie_name
+
+    def sign(self, payload: StateCookieInput) -> str:
+        iat = self._clock.now() // 1000
+        claims: dict[str, Any] = {
+            "cv": payload.get("code_verifier"),
+            "n": payload.get("nonce"),
+            "st": payload.get("state"),
+            "iat": iat,
+            "exp": iat + self._ttl,
+        }
+        return_to = payload.get("return_to")
+        if return_to is not None:
+            claims["rt"] = return_to
+        return jwt.encode(claims, self._secret, algorithm=_ALGORITHM)
+
+    def verify(self, token: str) -> StateCookiePayload:
+        try:
+            # `verify_exp`/`verify_iat` disabled and re-checked manually against the INJECTED
+            # clock — see _session.py's `_decode` for why (same determinism requirement).
+            payload = jwt.decode(
+                token,
+                self._secret,
+                algorithms=[_ALGORITHM],
+                options={"verify_exp": False, "verify_iat": False, "require": ["exp", "iat"]},
+            )
+        except jwt.PyJWTError as exc:
+            raise StateCookieError(f"state cookie verification failed: {exc}") from exc
+
+        now_seconds = self._clock.now() / 1000
+        exp = payload.get("exp")
+        if not isinstance(exp, (int, float)) or now_seconds > exp:
+            raise StateCookieError("state cookie verification failed: expired")
+
+        cv = payload.get("cv")
+        nonce = payload.get("n")
+        state = payload.get("st")
+        if not isinstance(cv, str) or not isinstance(nonce, str) or not isinstance(state, str):
+            raise StateCookieError("state cookie verification failed: missing cv/n/st")
+
+        return_to = payload.get("rt")
+        if not isinstance(return_to, str):
+            return_to = "/"
+
+        return {
+            "code_verifier": cv,
+            "nonce": nonce,
+            "state": state,
+            "return_to": return_to,
+        }
+
+    def verify_callback(self, token: str, callback_state: str) -> StateCookiePayload:
+        """`verify()` + a constant-time compare of the callback's `state` query parameter. THE
+        CSRF check — see module docstring."""
+        payload = self.verify(token)
+        if not hmac.compare_digest(payload["state"], callback_state):
+            raise StateMismatchError("state cookie verification failed: state mismatch")
+        return payload
+
+    def cookie_attributes(
+        self,
+        *,
+        path: str = "/",
+        secure: bool = True,
+        same_site: str = "Lax",
+        max_age_seconds: Optional[int] = None,
+        domain: Optional[str] = None,
+    ) -> str:
+        """The `Set-Cookie` attribute fragment (no `name=value`). Pure — no crypto, no clock."""
+        effective_max_age = self._ttl if max_age_seconds is None else max_age_seconds
+        parts = [f"Path={path}", f"Max-Age={effective_max_age}", "HttpOnly", f"SameSite={same_site}"]
+        if secure:
+            parts.append("Secure")
+        if domain:
+            parts.append(f"Domain={domain}")
+        return "; ".join(parts)

memyauth/_sync/__init__.py

@@ -0,0 +1,3 @@
+# GENERATED by scripts/gen_sync.py from memyauth/__init__.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""Generated synchronous twins of the memyauth async modules — see scripts/gen_sync.py."""

memyauth/_sync/_client.py

@@ -0,0 +1,171 @@
+# GENERATED by scripts/gen_sync.py from memyauth/_client.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@fileoverview Top-level `MemyAuth` async client — composes the seven capability services.
+@module memyauth._client
+@description [async -> _sync/_client.py twin via scripts/gen_sync.py]. `SDK_VERSION` lives HERE
+   (design §G.5's six-file version-parity check reads it via
+   `/SDK_VERSION\\s*=\\s*["\\']([^"\\']+)["\\']/`). `.discovery`, `.oidc`, `.iam` and `.roles` are
+   EAGER (built in `__init__`) because their prerequisites are always present once `resolve_config`
+   succeeds; `.session`, `.state` and `.id_token` are LAZY properties — `.session`/`.state` raise
+   `ConfigError` at first access when their signing secret was never configured (an IAM-only
+   consumer should never need one), while `.id_token` never raises (`id_token_validation` is a
+   required, already-validated field, so its prerequisite is always satisfiable) but is still built
+   lazily and cached, purely to avoid touching `discovery` before it is needed.
+@dependencies ._config, ._discovery, ._oidc, ._iam, ._idtoken, ._roles, ._session, ._state
+@relatedFiles __init__.py (re-exports MemyAuth + SDK_VERSION), sync/__init__.py (the generated
+   sync facade), _config.py (resolve_config), tests/test_client.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+# ABSOLUTE imports for the shared/pure modules; RELATIVE for the sibling async modules that DO
+# get _sync/ twins, so the generated _sync/_client.py binds to ITS siblings in _sync/ (see
+# _transport.py's header for why this split is required).
+from memyauth._config import ResolvedConfig, resolve_config
+from memyauth._errors import ConfigError
+from memyauth._roles import RoleMapper
+from memyauth._session import SessionTokenService
+from memyauth._state import StateCookieService
+
+from ._discovery import DiscoveryService
+from ._iam import IamService
+from ._idtoken import IdTokenVerifier
+from ._oidc import OidcService
+
+__all__ = ["MemyAuth", "SDK_VERSION"]
+
+SDK_VERSION = "0.1.0"
+
+_SECRET_FIELDS = (
+    "client_secret",
+    "iam_app_secret",
+    "iam_m2m_token",
+    "session_signing_secret",
+    "state_signing_secret",
+)
+
+
+class MemyAuth:
+    """Async MemyAuth client — the composition root for all nine customer capabilities.
+
+    Usage::
+
+        async with MemyAuth(
+            issuer_url="https://auth.memy.dev/oidc",
+            client_id="my-app",
+            client_secret="...",
+            public_base_url="https://my-app.example.com",
+            id_token_validation="local-jwks",
+        ) as auth:
+            req = await auth.oidc.build_authorization_url()
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._config: ResolvedConfig = resolve_config(**kwargs)
+
+        self.discovery = DiscoveryService(
+            issuer_url=self._config["issuer_url"],
+            internal_issuer_url=self._config["internal_issuer_url"],
+            timeout_ms=self._config["discovery_timeout_ms"],
+            transport=self._config["transport"],
+            clock=self._config["clock"],
+        )
+        self.oidc = OidcService(
+            config=self._config,
+            discovery=self.discovery,
+            transport=self._config["transport"],
+            random=self._config["random"],
+        )
+        self.iam = IamService(config=self._config, transport=self._config["transport"])
+        self.roles = RoleMapper(
+            role_map=self._config["role_map"],
+            role_overrides=self._config["role_overrides"],
+            default_role=self._config["default_role"],
+            global_admin_roles=self._config["global_admin_roles"],
+        )
+
+        self._session: Optional[SessionTokenService] = None
+        self._state: Optional[StateCookieService] = None
+        self._id_token: Optional[IdTokenVerifier] = None
+
+    @property
+    def session(self) -> SessionTokenService:
+        if self._session is None:
+            secret = self._config.get("session_signing_secret")
+            if not secret:
+                raise ConfigError("sessionSigningSecret is required to issue or verify session tokens")
+            self._session = SessionTokenService(
+                signing_secret=secret,
+                access_ttl_seconds=self._config["access_ttl_seconds"],
+                refresh_ttl_seconds=self._config["refresh_ttl_seconds"],
+                issuer=self._config["session_issuer"],
+                clock=self._config["clock"],
+            )
+        return self._session
+
+    @property
+    def state(self) -> StateCookieService:
+        if self._state is None:
+            secret = self._config.get("state_signing_secret") or self._config.get("session_signing_secret")
+            if not secret:
+                raise ConfigError("stateSigningSecret (or sessionSigningSecret) is required to sign state cookies")
+            self._state = StateCookieService(
+                signing_secret=secret,
+                ttl_seconds=self._config["state_ttl_seconds"],
+                cookie_name=self._config["state_cookie_name"],
+                clock=self._config["clock"],
+            )
+        return self._state
+
+    @property
+    def id_token(self) -> IdTokenVerifier:
+        """Always available — `id_token_validation` is a required, already-validated field, so
+        this never raises. Still lazy + cached, purely to defer construction cost."""
+        if self._id_token is None:
+            self._id_token = IdTokenVerifier(
+                mode=self._config["id_token_validation"],
+                allowed_algorithms=self._config["allowed_algorithms"],
+                discovery=self.discovery,
+                transport=self._config["transport"],
+                clock=self._config["clock"],
+            )
+        return self._id_token
+
+    def resolved_config(self) -> dict[str, Any]:
+        """The resolved config, with every secret-bearing field replaced by `"<set>"` /
+        `"<unset>"` — safe to log or hand to a conformance driver."""
+        redacted: dict[str, Any] = dict(self._config)
+        redacted.pop("transport", None)
+        redacted.pop("clock", None)
+        redacted.pop("random", None)
+        for field in _SECRET_FIELDS:
+            redacted[field] = "<set>" if self._config.get(field) else "<unset>"
+        return redacted
+
+    def capabilities(self) -> dict[str, bool]:
+        """Which lazily-gated capabilities are currently usable, without constructing them."""
+        return {
+            "discovery": True,
+            "oidc": True,
+            "iam": True,
+            "roles": True,
+            "session": bool(self._config.get("session_signing_secret")),
+            "state": bool(self._config.get("state_signing_secret") or self._config.get("session_signing_secret")),
+            "id_token": True,
+        }
+
+    def close(self) -> None:
+        self.discovery.close()  # type: ignore[attr-defined]
+        self.oidc.close()  # type: ignore[attr-defined]
+        self.iam.close()  # type: ignore[attr-defined]
+        if self._id_token is not None:
+            self._id_token.close()  # type: ignore[attr-defined]
+
+    def __enter__(self) -> "MemyAuth":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

memyauth/_sync/_discovery.py

@@ -0,0 +1,174 @@
+# GENERATED by scripts/gen_sync.py from memyauth/_discovery.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@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 time
+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
+
+    def discover(self) -> OidcDiscoveryDocument:
+        while self._locked:
+            time.sleep(0)
+        if self._cached is not None:
+            return self._cached
+        self._locked = True
+        try:
+            doc = 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
+
+    def _fetch(self) -> OidcDiscoveryDocument:
+        url = f"{self._fetch_issuer}/.well-known/openid-configuration"
+        resp = 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
+
+    def warm(self) -> None:
+        """Boot-time readiness warm-up. Never throws."""
+        try:
+            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
+
+    def close(self) -> None:
+        self._transport.close()