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

memyauth/_sync/_oidc.py

@@ -0,0 +1,239 @@
+# GENERATED by scripts/gen_sync.py from memyauth/_oidc.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@fileoverview Capabilities 2, 3, 4, 9 — authorization URL, token exchange/refresh, userinfo, logout.
+@module memyauth._oidc
+@description [async -> _sync/_oidc.py twin via scripts/gen_sync.py]. Ported from
+   `memybase/src/auth/oidc.ts:14-20,155-159,178-225`. Every URL this service builds comes from the
+   DISCOVERY DOCUMENT, never from a guessed path convention (§C.2, D7 — memyui's guessed
+   `{issuer}/auth`). Token exchange and refresh are POSTs and are therefore NEVER retried by
+   `Transport` (§0 C13 — an authorization code is single-use); their errors are bespoke
+   (`TokenExchangeError` / `RefreshRejectedError`) rather than the generic `decode_error` mapping,
+   because the token endpoint's failure body is an OAuth `{error, error_description}` shape, not
+   the IAM surface's `{code,message,detail}` envelope.
+@dependencies base64, urllib.parse (stdlib); ._transport, ._pkce, ._discovery
+@relatedFiles _discovery.py (this service's sole source of every OIDC URL), _pkce.py (PKCE +
+   random helpers), _config.py (ResolvedConfig), _errors.py, tests/test_oidc.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+import base64
+from typing import Optional
+from urllib.parse import urlencode
+
+import httpx
+
+# ABSOLUTE imports for the shared/pure modules; RELATIVE for ._discovery/._transport, which DO get
+# _sync/ twins and must bind to THEIR sibling twins (see _transport.py's header for why).
+from memyauth._config import ResolvedConfig
+from memyauth._errors import ConfigError, ProtocolError, RefreshRejectedError, TokenExchangeError, UserInfoError
+from memyauth._pkce import generate_code_challenge, generate_code_verifier, random_nonce, random_state
+from memyauth._types import AuthorizationRequest, OidcTokenResponse, RandomSource, UserInfo
+
+from ._discovery import DiscoveryService
+from ._transport import Transport, read_json_or_none, truncated_text
+
+__all__ = ["OidcService"]
+
+_AUTH_STANDARD_KEYS = frozenset(
+    {"response_type", "client_id", "redirect_uri", "code_challenge", "code_challenge_method", "scope", "state", "nonce", "prompt"}
+)
+_LOGOUT_STANDARD_KEYS = frozenset({"post_logout_redirect_uri", "id_token_hint", "client_id", "state"})
+
+
+class OidcService:
+    def __init__(
+        self,
+        *,
+        config: ResolvedConfig,
+        discovery: DiscoveryService,
+        transport: Optional[httpx.BaseTransport] = None,
+        random: Optional[RandomSource] = None,
+    ) -> None:
+        self._config = config
+        self._discovery = discovery
+        self._random: RandomSource = random or config["random"]
+        self._transport = Transport(
+            timeout_ms=config.get("discovery_timeout_ms", 10000),
+            max_retries=config["retry"]["max_retries"],
+            base_delay_ms=config["retry"]["base_delay_ms"],
+            retryable_statuses=config["retry"]["retryable_statuses"],
+            transport=transport,
+        )
+
+    def build_authorization_url(
+        self,
+        *,
+        redirect_uri: Optional[str] = None,
+        scopes: Optional[list[str]] = None,
+        state: Optional[str] = None,
+        nonce: Optional[str] = None,
+        code_verifier: Optional[str] = None,
+        prompt: Optional[str] = None,
+        return_to: Optional[str] = None,
+        extra_params: Optional[dict[str, str]] = None,
+    ) -> AuthorizationRequest:
+        # Validated BEFORE any network call (sdk-design.md §C.2) — mirrors js/src/oidc.ts:143,
+        # where `assertNoReservedCollision` runs ahead of `discovery.discover()`. A misconfigured
+        # caller must fail deterministically without spending a discovery round trip or generating
+        # provider traffic.
+        _assert_no_extra_param_collision(extra_params, _AUTH_STANDARD_KEYS)
+        doc = self._discovery.discover()
+
+        effective_redirect_uri = redirect_uri or self._config["redirect_uri"]
+        if not effective_redirect_uri:
+            raise ConfigError("redirectUri or publicBaseUrl must be configured")
+
+        cv = code_verifier or generate_code_verifier(self._random)
+        challenge = generate_code_challenge(cv)
+        effective_state = state or random_state(self._random)
+        effective_nonce = nonce or random_nonce(self._random)
+
+        base_scopes = scopes if scopes is not None else self._config["scopes"]
+        scopes_supported = doc.get("scopes_supported")
+        if isinstance(scopes_supported, list) and scopes_supported:
+            negotiated = [s for s in base_scopes if s == "openid" or s in scopes_supported]
+        else:
+            negotiated = list(base_scopes)
+        scope = " ".join(negotiated)
+
+        params: dict[str, str] = {
+            "response_type": "code",
+            "client_id": self._config["client_id"],
+            "redirect_uri": effective_redirect_uri,
+            "code_challenge": challenge,
+            "code_challenge_method": "S256",
+            "scope": scope,
+            "state": effective_state,
+            "nonce": effective_nonce,
+            "prompt": prompt if prompt is not None else "consent",
+        }
+        if extra_params:
+            params.update(extra_params)
+
+        url = f"{doc['authorization_endpoint']}?{urlencode(params)}"
+        return {
+            "url": url,
+            "code_verifier": cv,
+            "code_challenge": challenge,
+            "state": effective_state,
+            "nonce": effective_nonce,
+            "redirect_uri": effective_redirect_uri,
+            "scope": scope,
+        }
+
+    def _credential_form_fields(self) -> dict[str, str]:
+        if self._config["token_endpoint_auth_method"] == "client_secret_post":
+            return {"client_id": self._config["client_id"], "client_secret": self._config["client_secret"]}
+        return {}
+
+    def _credential_headers(self) -> dict[str, str]:
+        if self._config["token_endpoint_auth_method"] == "client_secret_basic":
+            raw = f"{self._config['client_id']}:{self._config['client_secret']}".encode("utf-8")
+            return {"Authorization": f"Basic {base64.b64encode(raw).decode('ascii')}"}
+        return {}
+
+    def _post_token(self, body: dict[str, str]) -> httpx.Response:
+        doc = self._discovery.discover()
+        form = {**body, **self._credential_form_fields()}
+        headers = self._credential_headers()
+        return self._transport.send("POST", doc["token_endpoint"], form=form, headers=headers)
+
+    @staticmethod
+    def _parse_token_response(resp: httpx.Response) -> OidcTokenResponse:
+        body = read_json_or_none(resp)
+        if not isinstance(body, dict) or "token_type" not in body or "expires_in" not in body:
+            raise ProtocolError("OIDC token response is missing token_type or expires_in")
+        return body  # type: ignore[return-value]
+
+    def exchange_code(
+        self, *, code: str, code_verifier: str, redirect_uri: Optional[str] = None
+    ) -> OidcTokenResponse:
+        body = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri or self._config["redirect_uri"],
+            "code_verifier": code_verifier,
+        }
+        resp = self._post_token(body)
+        if not (200 <= resp.status_code < 300):
+            raise TokenExchangeError(
+                f"OIDC token exchange failed: {resp.status_code}", detail=truncated_text(resp)
+            )
+        return self._parse_token_response(resp)
+
+    def refresh_tokens(self, refresh_token: str) -> OidcTokenResponse:
+        body = {"grant_type": "refresh_token", "refresh_token": refresh_token}
+        resp = self._post_token(body)
+        if not (200 <= resp.status_code < 300):
+            raise RefreshRejectedError(
+                f"OIDC token refresh rejected: {resp.status_code}", detail=truncated_text(resp)
+            )
+        return self._parse_token_response(resp)
+
+    def fetch_user_info(self, access_token: str) -> UserInfo:
+        doc = self._discovery.discover()
+        resp = self._transport.send(
+            "GET",
+            doc["userinfo_endpoint"],
+            headers={"Authorization": f"Bearer {access_token}", "Accept": "application/json"},
+        )
+        if not (200 <= resp.status_code < 300):
+            raise UserInfoError(f"OIDC userinfo failed: {resp.status_code}", detail=truncated_text(resp))
+        body = read_json_or_none(resp)
+        if not isinstance(body, dict) or not isinstance(body.get("sub"), str) or not body["sub"]:
+            raise ProtocolError("OIDC userinfo response is missing sub")
+        return body  # type: ignore[return-value]
+
+    def build_logout_url(
+        self,
+        *,
+        post_logout_redirect_uri: Optional[str] = None,
+        id_token_hint: Optional[str] = None,
+        client_id: Optional[str] = None,
+        state: Optional[str] = None,
+        extra_params: Optional[dict[str, str]] = None,
+    ) -> str:
+        doc = self._discovery.discover()
+        endpoint = doc.get("end_session_endpoint") or f"{doc['issuer'].rstrip('/')}/session/end"
+
+        # NOTE: unlike build_authorization_url, client_id is NEVER silently defaulted from config
+        # here — only an EXPLICITLY passed value is emitted. Memybase's own `buildLogoutUrl()`
+        # (the estate's shipped behavior, oidc.ts:222-225) takes no arguments and returns the bare
+        # endpoint with no query string at all; the frozen invariant "no arguments and no
+        # configured postLogoutRedirectUri -> bare endpoint, no ?" (conformance case
+        # `logout-url-bare-endpoint`) is only satisfiable if every param, client_id included, is
+        # caller-opt-in.
+        params: dict[str, str] = {}
+        effective_plr = post_logout_redirect_uri or self._config.get("post_logout_redirect_uri")
+        if effective_plr:
+            params["post_logout_redirect_uri"] = effective_plr
+        if id_token_hint:
+            params["id_token_hint"] = id_token_hint
+        if client_id:
+            params["client_id"] = client_id
+        if state:
+            params["state"] = state
+        _merge_extra_params(params, extra_params, _LOGOUT_STANDARD_KEYS)
+
+        if not params:
+            return endpoint
+        return f"{endpoint}?{urlencode(params)}"
+
+    def close(self) -> None:
+        self._transport.close()
+
+
+def _assert_no_extra_param_collision(extra: Optional[dict[str, str]], standard_keys: frozenset) -> None:
+    if not extra:
+        return
+    for key in extra:
+        if key in standard_keys:
+            raise ConfigError(f"extraParams cannot override a standard parameter: {key}")
+
+
+def _merge_extra_params(params: dict[str, str], extra: Optional[dict[str, str]], standard_keys: frozenset) -> None:
+    _assert_no_extra_param_collision(extra, standard_keys)
+    if extra:
+        params.update(extra)

memyauth/_sync/_transport.py

@@ -0,0 +1,223 @@
+# GENERATED by scripts/gen_sync.py from memyauth/_transport.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@fileoverview Shared async HTTP transport — timeout, GET/HEAD-only retry, JSON/form encoding.
+@module memyauth._transport
+@description [async -> _sync/_transport.py twin via scripts/gen_sync.py]. Used by discovery, oidc,
+   iam and idtoken (§C.11). NOT bound to a single base_url — discovery/oidc/idtoken/iam each call
+   different absolute origins (issuer, internal issuer, iam_base_url), so every call site passes a
+   full URL. The retry policy is narrowed from the memybase pattern by §0 C13: an OAuth
+   authorization code is single-use, so `POST` (and any other non-GET/HEAD method) is NEVER
+   retried — not on status, not on timeout, not on a network error. A `Retry-After` response
+   header REPLACES (never stacks on) the computed exponential backoff for that iteration, clamped
+   to 60s. With `base_delay_ms=0` the backoff is exactly 0 regardless of jitter, which is how the
+   conformance harness pins determinism.
+
+   `send()` is deliberately low-level: it applies the retry policy and returns the raw
+   `httpx.Response` for ANY status (only a genuine transport failure raises NetworkError /
+   TimeoutError here). Each capability decides how to turn a non-2xx response into its OWN typed
+   error, because the estate's endpoints do NOT share one error envelope: `/iam/me` follows
+   openapi.yaml's `{code,message,detail}` shape (decoded via `decode_error`, §H), while OIDC-native
+   endpoints (discovery, token, userinfo) do not — they get bespoke wrapping
+   (DiscoveryError/TokenExchangeError/RefreshRejectedError/UserInfoError) carrying a truncated raw
+   body as `detail`, exactly as memybase's `oidc.ts` does. `request_json()` is the IAM-only
+   convenience that DOES raise via `decode_error` for a non-2xx response.
+@dependencies httpx
+@relatedFiles _errors.py (decode_error/NetworkError/TimeoutError/ProtocolError), _config.py
+   (RetryConfig), _discovery.py, _oidc.py, _iam.py, _idtoken.py, tests/test_transport.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+import time
+import random as _random_module
+from typing import Any, Optional
+
+import httpx
+
+# ABSOLUTE import of the shared/pure module: unasync generates memyauth/_sync/_transport.py,
+# whose relative `from ._errors` would resolve to the nonexistent memyauth._sync._errors — the
+# absolute path makes both the async module and its sync twin bind the SAME single _errors module
+# (the exact hazard memybase's own _transport.py documents at the same import line).
+from memyauth._errors import NetworkError, ProtocolError, TimeoutError, decode_error
+
+__all__ = ["Transport"]
+
+_SAFE_METHODS = frozenset({"GET", "HEAD"})
+_BASE_READ_RETRY = frozenset({429, 503})
+_MAX_BACKOFF_MS = 30000
+_MAX_RETRY_AFTER_MS = 60000
+
+
+class Transport:
+    """Internal HTTP transport: header merge, timeout, GET/HEAD-only retry. One instance per
+    capability service (each may have its own timeout), all optionally sharing the same injected
+    `httpx.BaseTransport` test seam."""
+
+    def __init__(
+        self,
+        *,
+        timeout_ms: int = 10000,
+        max_retries: int = 2,
+        base_delay_ms: int = 500,
+        retryable_statuses: Optional[list[int]] = None,
+        headers: Optional[dict[str, str]] = None,
+        user_agent: Optional[str] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self._timeout_ms = timeout_ms
+        self._max_retries = max_retries
+        self._base_delay_ms = base_delay_ms
+        self._extra_retryable_statuses = frozenset(retryable_statuses or [])
+        self._extra_headers = dict(headers or {})
+        self._user_agent = user_agent
+        self._transport = transport
+        self._client: Optional[httpx.Client] = None
+
+    def _get_client(self) -> httpx.Client:
+        if self._client is None or self._client.is_closed:
+            headers = {"Accept": "application/json", **self._extra_headers}
+            if self._user_agent:
+                headers["User-Agent"] = self._user_agent
+            kwargs: dict[str, Any] = {"headers": headers}
+            if self._transport is not None:
+                kwargs["transport"] = self._transport
+            self._client = httpx.Client(**kwargs)
+        return self._client
+
+    def send(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Optional[dict[str, str]] = None,
+        json_body: Any = None,
+        form: Optional[dict[str, str]] = None,
+        params: Optional[dict[str, str]] = None,
+        timeout_ms: Optional[int] = None,
+    ) -> httpx.Response:
+        """Apply the retry policy and return the raw response for ANY terminal status. Raises
+        only `NetworkError` / `TimeoutError` for a genuine transport-level failure."""
+        method_upper = method.upper()
+        is_safe = method_upper in _SAFE_METHODS
+        max_retries = self._max_retries if is_safe else 0
+        retryable_statuses = (_BASE_READ_RETRY | self._extra_retryable_statuses) if is_safe else frozenset()
+        effective_timeout = (timeout_ms if timeout_ms is not None else self._timeout_ms) / 1000.0
+
+        client = self._get_client()
+        attempt = 0
+
+        while True:
+            try:
+                resp = client.request(
+                    method_upper,
+                    url,
+                    headers=headers,
+                    json=json_body,
+                    data=form,
+                    params=params,
+                    timeout=effective_timeout,
+                )
+            except httpx.TimeoutException as exc:
+                if is_safe and attempt < max_retries:
+                    time.sleep(_backoff_seconds(attempt, self._base_delay_ms))
+                    attempt += 1
+                    continue
+                raise TimeoutError(str(exc)) from exc
+            except httpx.HTTPError as exc:
+                raise NetworkError(str(exc)) from exc
+
+            if resp.status_code in retryable_statuses and attempt < max_retries:
+                retry_after_ms = _parse_retry_after_ms(resp.headers.get("retry-after"))
+                delay_seconds = (
+                    min(retry_after_ms, _MAX_RETRY_AFTER_MS) / 1000.0
+                    if retry_after_ms is not None
+                    else _backoff_seconds(attempt, self._base_delay_ms)
+                )
+                time.sleep(delay_seconds)
+                attempt += 1
+                continue
+
+            return resp
+
+    def request_json(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Optional[dict[str, str]] = None,
+        json_body: Any = None,
+        form: Optional[dict[str, str]] = None,
+        params: Optional[dict[str, str]] = None,
+        timeout_ms: Optional[int] = None,
+    ) -> Any:
+        """IAM-only convenience: `send()` + auto-raise via `decode_error` on non-2xx (the openapi
+        `{code,message,detail}` envelope). 204 / empty 2xx body -> `None`."""
+        resp = self.send(
+            method,
+            url,
+            headers=headers,
+            json_body=json_body,
+            form=form,
+            params=params,
+            timeout_ms=timeout_ms,
+        )
+        if resp.status_code == 204:
+            return None
+        if 200 <= resp.status_code < 300:
+            return read_json_or_none(resp)
+        raise decode_error(
+            resp.status_code,
+            body=read_json_or_none(resp),
+            request_id=resp.headers.get("x-request-id"),
+        )
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+
+def read_json_or_none(resp: httpx.Response) -> Any:
+    """2xx body -> parsed JSON, or `None` when empty. Raises `ProtocolError` on non-JSON content
+    (a 2xx body that fails to parse is a protocol violation, not an absent body)."""
+    if not resp.content:
+        return None
+    try:
+        return resp.json()
+    except ValueError as exc:
+        raise ProtocolError("expected a JSON response body") from exc
+
+
+def read_json_or_none_lenient(resp: httpx.Response) -> Any:
+    """Like `read_json_or_none`, but never raises — used when building an error `detail` where a
+    non-JSON body is expected and should not itself trigger a different failure."""
+    try:
+        return resp.json() if resp.content else None
+    except ValueError:
+        return None
+
+
+def truncated_text(resp: httpx.Response, limit: int = 200) -> str:
+    """First `limit` chars of the raw body, for an error `detail` — memybase truncates identically
+    before logging (§C.3)."""
+    try:
+        text = resp.text
+    except Exception:
+        return ""
+    return text[:limit]
+
+
+def _backoff_seconds(attempt: int, base_delay_ms: int) -> float:
+    computed = min(_MAX_BACKOFF_MS, base_delay_ms * (2**attempt))
+    jitter = _random_module.uniform(0, base_delay_ms) if base_delay_ms else 0
+    return (computed + jitter) / 1000.0
+
+
+def _parse_retry_after_ms(value: Optional[str]) -> Optional[int]:
+    if not value:
+        return None
+    try:
+        return max(0, int(float(value) * 1000))
+    except ValueError:
+        return None

memyauth/_transport.py

@@ -0,0 +1,221 @@
+"""
+@fileoverview Shared async HTTP transport — timeout, GET/HEAD-only retry, JSON/form encoding.
+@module memyauth._transport
+@description [async -> _sync/_transport.py twin via scripts/gen_sync.py]. Used by discovery, oidc,
+   iam and idtoken (§C.11). NOT bound to a single base_url — discovery/oidc/idtoken/iam each call
+   different absolute origins (issuer, internal issuer, iam_base_url), so every call site passes a
+   full URL. The retry policy is narrowed from the memybase pattern by §0 C13: an OAuth
+   authorization code is single-use, so `POST` (and any other non-GET/HEAD method) is NEVER
+   retried — not on status, not on timeout, not on a network error. A `Retry-After` response
+   header REPLACES (never stacks on) the computed exponential backoff for that iteration, clamped
+   to 60s. With `base_delay_ms=0` the backoff is exactly 0 regardless of jitter, which is how the
+   conformance harness pins determinism.
+
+   `send()` is deliberately low-level: it applies the retry policy and returns the raw
+   `httpx.Response` for ANY status (only a genuine transport failure raises NetworkError /
+   TimeoutError here). Each capability decides how to turn a non-2xx response into its OWN typed
+   error, because the estate's endpoints do NOT share one error envelope: `/iam/me` follows
+   openapi.yaml's `{code,message,detail}` shape (decoded via `decode_error`, §H), while OIDC-native
+   endpoints (discovery, token, userinfo) do not — they get bespoke wrapping
+   (DiscoveryError/TokenExchangeError/RefreshRejectedError/UserInfoError) carrying a truncated raw
+   body as `detail`, exactly as memybase's `oidc.ts` does. `request_json()` is the IAM-only
+   convenience that DOES raise via `decode_error` for a non-2xx response.
+@dependencies httpx
+@relatedFiles _errors.py (decode_error/NetworkError/TimeoutError/ProtocolError), _config.py
+   (RetryConfig), _discovery.py, _oidc.py, _iam.py, _idtoken.py, tests/test_transport.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+import asyncio
+import random as _random_module
+from typing import Any, Optional
+
+import httpx
+
+# ABSOLUTE import of the shared/pure module: unasync generates memyauth/_sync/_transport.py,
+# whose relative `from ._errors` would resolve to the nonexistent memyauth._sync._errors — the
+# absolute path makes both the async module and its sync twin bind the SAME single _errors module
+# (the exact hazard memybase's own _transport.py documents at the same import line).
+from memyauth._errors import NetworkError, ProtocolError, TimeoutError, decode_error
+
+__all__ = ["Transport"]
+
+_SAFE_METHODS = frozenset({"GET", "HEAD"})
+_BASE_READ_RETRY = frozenset({429, 503})
+_MAX_BACKOFF_MS = 30000
+_MAX_RETRY_AFTER_MS = 60000
+
+
+class Transport:
+    """Internal HTTP transport: header merge, timeout, GET/HEAD-only retry. One instance per
+    capability service (each may have its own timeout), all optionally sharing the same injected
+    `httpx.BaseTransport` test seam."""
+
+    def __init__(
+        self,
+        *,
+        timeout_ms: int = 10000,
+        max_retries: int = 2,
+        base_delay_ms: int = 500,
+        retryable_statuses: Optional[list[int]] = None,
+        headers: Optional[dict[str, str]] = None,
+        user_agent: Optional[str] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self._timeout_ms = timeout_ms
+        self._max_retries = max_retries
+        self._base_delay_ms = base_delay_ms
+        self._extra_retryable_statuses = frozenset(retryable_statuses or [])
+        self._extra_headers = dict(headers or {})
+        self._user_agent = user_agent
+        self._transport = transport
+        self._client: Optional[httpx.AsyncClient] = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            headers = {"Accept": "application/json", **self._extra_headers}
+            if self._user_agent:
+                headers["User-Agent"] = self._user_agent
+            kwargs: dict[str, Any] = {"headers": headers}
+            if self._transport is not None:
+                kwargs["transport"] = self._transport
+            self._client = httpx.AsyncClient(**kwargs)
+        return self._client
+
+    async def send(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Optional[dict[str, str]] = None,
+        json_body: Any = None,
+        form: Optional[dict[str, str]] = None,
+        params: Optional[dict[str, str]] = None,
+        timeout_ms: Optional[int] = None,
+    ) -> httpx.Response:
+        """Apply the retry policy and return the raw response for ANY terminal status. Raises
+        only `NetworkError` / `TimeoutError` for a genuine transport-level failure."""
+        method_upper = method.upper()
+        is_safe = method_upper in _SAFE_METHODS
+        max_retries = self._max_retries if is_safe else 0
+        retryable_statuses = (_BASE_READ_RETRY | self._extra_retryable_statuses) if is_safe else frozenset()
+        effective_timeout = (timeout_ms if timeout_ms is not None else self._timeout_ms) / 1000.0
+
+        client = self._get_client()
+        attempt = 0
+
+        while True:
+            try:
+                resp = await client.request(
+                    method_upper,
+                    url,
+                    headers=headers,
+                    json=json_body,
+                    data=form,
+                    params=params,
+                    timeout=effective_timeout,
+                )
+            except httpx.TimeoutException as exc:
+                if is_safe and attempt < max_retries:
+                    await asyncio.sleep(_backoff_seconds(attempt, self._base_delay_ms))
+                    attempt += 1
+                    continue
+                raise TimeoutError(str(exc)) from exc
+            except httpx.HTTPError as exc:
+                raise NetworkError(str(exc)) from exc
+
+            if resp.status_code in retryable_statuses and attempt < max_retries:
+                retry_after_ms = _parse_retry_after_ms(resp.headers.get("retry-after"))
+                delay_seconds = (
+                    min(retry_after_ms, _MAX_RETRY_AFTER_MS) / 1000.0
+                    if retry_after_ms is not None
+                    else _backoff_seconds(attempt, self._base_delay_ms)
+                )
+                await asyncio.sleep(delay_seconds)
+                attempt += 1
+                continue
+
+            return resp
+
+    async def request_json(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Optional[dict[str, str]] = None,
+        json_body: Any = None,
+        form: Optional[dict[str, str]] = None,
+        params: Optional[dict[str, str]] = None,
+        timeout_ms: Optional[int] = None,
+    ) -> Any:
+        """IAM-only convenience: `send()` + auto-raise via `decode_error` on non-2xx (the openapi
+        `{code,message,detail}` envelope). 204 / empty 2xx body -> `None`."""
+        resp = await self.send(
+            method,
+            url,
+            headers=headers,
+            json_body=json_body,
+            form=form,
+            params=params,
+            timeout_ms=timeout_ms,
+        )
+        if resp.status_code == 204:
+            return None
+        if 200 <= resp.status_code < 300:
+            return read_json_or_none(resp)
+        raise decode_error(
+            resp.status_code,
+            body=read_json_or_none(resp),
+            request_id=resp.headers.get("x-request-id"),
+        )
+
+    async def close(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+
+def read_json_or_none(resp: httpx.Response) -> Any:
+    """2xx body -> parsed JSON, or `None` when empty. Raises `ProtocolError` on non-JSON content
+    (a 2xx body that fails to parse is a protocol violation, not an absent body)."""
+    if not resp.content:
+        return None
+    try:
+        return resp.json()
+    except ValueError as exc:
+        raise ProtocolError("expected a JSON response body") from exc
+
+
+def read_json_or_none_lenient(resp: httpx.Response) -> Any:
+    """Like `read_json_or_none`, but never raises — used when building an error `detail` where a
+    non-JSON body is expected and should not itself trigger a different failure."""
+    try:
+        return resp.json() if resp.content else None
+    except ValueError:
+        return None
+
+
+def truncated_text(resp: httpx.Response, limit: int = 200) -> str:
+    """First `limit` chars of the raw body, for an error `detail` — memybase truncates identically
+    before logging (§C.3)."""
+    try:
+        text = resp.text
+    except Exception:
+        return ""
+    return text[:limit]
+
+
+def _backoff_seconds(attempt: int, base_delay_ms: int) -> float:
+    computed = min(_MAX_BACKOFF_MS, base_delay_ms * (2**attempt))
+    jitter = _random_module.uniform(0, base_delay_ms) if base_delay_ms else 0
+    return (computed + jitter) / 1000.0
+
+
+def _parse_retry_after_ms(value: Optional[str]) -> Optional[int]:
+    if not value:
+        return None
+    try:
+        return max(0, int(float(value) * 1000))
+    except ValueError:
+        return None