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

memyauth/_idtoken.py

@@ -0,0 +1,165 @@
+"""
+@fileoverview Capability C0 — ID-token trust strategies: local JWKS verification, or an explicit
+   no-verification mode for TLS-token-endpoint trust.
+@module memyauth._idtoken
+@description [async -> _sync/_idtoken.py twin via scripts/gen_sync.py]. BOTH trust strategies are
+   first-class and BOTH are in live production use (§C.10.1): `local-jwks` (memyui, roboson,
+   memyvet) and `tls-token-endpoint` (memybase). `mode` has no default at this layer — the caller
+   MUST pick one, mirroring `_config.py`'s `id_token_validation` (§C.16). This is the module the
+   mandatory RS256 negative test (R1) exercises: a pin that cannot verify ANY token this provider
+   issues must fail LOUDLY, and `UnsupportedAlgorithmError` must be raised on the `alg` header
+   BEFORE any key lookup — a verifier that skipped the algorithm check and just tried every key
+   would accept a genuinely-signed RS256 token, which is exactly the twice-shipped defect (D4)
+   this class exists to make impossible. Exp/nbf are checked against the INJECTED `Clock`, not
+   PyJWT's internal wall-clock read, so the conformance harness's `fixedClock` can pin determinism.
+@dependencies pyjwt[crypto]
+@relatedFiles _discovery.py (source of `jwks_uri` — always the internal/fetch origin, never
+   rewritten, since JWKS is a server-side endpoint per §C.1 step 6), _config.py
+   (`allowed_algorithms`/`id_token_validation`), _errors.py, tests/test_idtoken.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+import jwt
+
+# 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._errors import ConfigError, IdTokenError, UnsupportedAlgorithmError
+from memyauth._types import Clock, IdpTokenClaims, IdTokenValidationMode, SystemClock
+
+from ._discovery import DiscoveryService
+from ._transport import Transport, read_json_or_none
+
+__all__ = ["IdTokenVerifier"]
+
+_DEFAULT_LOCAL_JWKS_ALGORITHMS = ("ES384",)
+_DEFAULT_CLOCK_TOLERANCE_SECONDS = 60
+
+
+class IdTokenVerifier:
+    def __init__(
+        self,
+        *,
+        mode: IdTokenValidationMode,
+        allowed_algorithms: Optional[list[str]] = None,
+        discovery: DiscoveryService,
+        clock_tolerance_seconds: int = _DEFAULT_CLOCK_TOLERANCE_SECONDS,
+        transport: Optional[httpx.BaseTransport] = None,
+        clock: Optional[Clock] = None,
+    ) -> None:
+        if mode not in ("local-jwks", "tls-token-endpoint"):
+            raise ConfigError("idTokenValidation must be local-jwks or tls-token-endpoint")
+
+        resolved_algorithms = allowed_algorithms
+        if resolved_algorithms is None:
+            resolved_algorithms = list(_DEFAULT_LOCAL_JWKS_ALGORITHMS) if mode == "local-jwks" else []
+
+        if mode == "tls-token-endpoint" and resolved_algorithms:
+            raise ConfigError("allowedAlgorithms must be empty when idTokenValidation is tls-token-endpoint")
+        if mode == "local-jwks" and not resolved_algorithms:
+            raise ConfigError("allowedAlgorithms must not be empty when idTokenValidation is local-jwks")
+
+        self.mode: IdTokenValidationMode = mode
+        self._allowed_algorithms = set(resolved_algorithms)
+        self._discovery = discovery
+        self._clock_tolerance_seconds = clock_tolerance_seconds
+        self._clock: Clock = clock or SystemClock()
+        self._transport = Transport(transport=transport)
+        self._jwks_cache: dict[str, dict[str, Any]] = {}
+
+    async def _refresh_jwks(self) -> None:
+        doc = await self._discovery.discover()
+        resp = await self._transport.send("GET", doc["jwks_uri"])
+        if not (200 <= resp.status_code < 300):
+            raise IdTokenError(f"failed to fetch JWKS: {resp.status_code}")
+        body = read_json_or_none(resp)
+        keys = (body or {}).get("keys", []) if isinstance(body, dict) else []
+        self._jwks_cache = {k["kid"]: k for k in keys if isinstance(k, dict) and "kid" in k}
+
+    async def _get_key_for_kid(self, kid: str) -> dict[str, Any]:
+        if kid not in self._jwks_cache:
+            await self._refresh_jwks()  # the single forced refresh on an unknown kid
+        if kid not in self._jwks_cache:
+            raise IdTokenError(f"no matching JWKS key for kid={kid!r}")
+        return self._jwks_cache[kid]
+
+    async def verify(
+        self,
+        id_token: str,
+        *,
+        issuer: str,
+        audience: str,
+        nonce: Optional[str] = None,
+        max_age_seconds: Optional[int] = None,
+    ) -> IdpTokenClaims:
+        if self.mode == "tls-token-endpoint":
+            raise ConfigError(
+                "tls-token-endpoint mode does not verify ID tokens; identity is derived from the "
+                "token-endpoint TLS channel per OIDC Core 3.1.3.7 item 6 — use decode_unverified() "
+                "plus /oidc/me or /iam/me"
+            )
+
+        try:
+            header = jwt.get_unverified_header(id_token)
+        except jwt.PyJWTError as exc:
+            raise IdTokenError(f"malformed ID token: {exc}") from exc
+
+        alg = header.get("alg")
+        # THE R1 check: reject on `alg` BEFORE any key lookup — a verifier that tried every key
+        # regardless of alg would accept a genuinely-signed RS256 token under an ES384-only pin.
+        if alg not in self._allowed_algorithms:
+            raise UnsupportedAlgorithmError(
+                f"ID token alg {alg!r} is not in the allowed algorithms {sorted(self._allowed_algorithms)!r}"
+            )
+
+        kid = header.get("kid")
+        if not kid:
+            raise IdTokenError("ID token is missing a kid header")
+        jwk = await self._get_key_for_kid(kid)
+        key = jwt.PyJWK(jwk).key
+
+        try:
+            claims = jwt.decode(
+                id_token,
+                key,
+                algorithms=[alg],
+                audience=audience,
+                issuer=issuer,
+                options={"verify_exp": False, "verify_nbf": False, "require": ["exp", "iat"]},
+            )
+        except jwt.PyJWTError as exc:
+            raise IdTokenError(f"ID token verification failed: {exc}") from exc
+
+        # exp/nbf checked against the INJECTED clock, not PyJWT's wall-clock read (determinism).
+        now_seconds = self._clock.now() / 1000
+        tolerance = self._clock_tolerance_seconds
+        exp = claims.get("exp")
+        if not isinstance(exp, (int, float)) or now_seconds > exp + tolerance:
+            raise IdTokenError("ID token has expired")
+        nbf = claims.get("nbf")
+        if isinstance(nbf, (int, float)) and now_seconds < nbf - tolerance:
+            raise IdTokenError("ID token is not yet valid")
+
+        if nonce is not None and claims.get("nonce") != nonce:
+            raise IdTokenError("ID token nonce mismatch")
+
+        if max_age_seconds is not None:
+            auth_time = claims.get("auth_time")
+            if not isinstance(auth_time, (int, float)) or (now_seconds - auth_time) > max_age_seconds:
+                raise IdTokenError("ID token auth_time exceeds max_age_seconds")
+
+        return claims  # type: ignore[return-value]
+
+    def decode_unverified(self, id_token: str) -> IdpTokenClaims:
+        """Decode without verifying. Available in BOTH modes; the ONLY path in
+        `tls-token-endpoint` mode."""
+        try:
+            return jwt.decode(id_token, options={"verify_signature": False})  # type: ignore[return-value]
+        except jwt.PyJWTError as exc:
+            raise IdTokenError(f"malformed ID token: {exc}") from exc
+
+    async def close(self) -> None:
+        await self._transport.close()

memyauth/_oidc.py

@@ -0,0 +1,237 @@
+"""
+@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,
+        )
+
+    async 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 = await 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 {}
+
+    async def _post_token(self, body: dict[str, str]) -> httpx.Response:
+        doc = await self._discovery.discover()
+        form = {**body, **self._credential_form_fields()}
+        headers = self._credential_headers()
+        return await 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]
+
+    async 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 = await 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)
+
+    async def refresh_tokens(self, refresh_token: str) -> OidcTokenResponse:
+        body = {"grant_type": "refresh_token", "refresh_token": refresh_token}
+        resp = await 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)
+
+    async def fetch_user_info(self, access_token: str) -> UserInfo:
+        doc = await self._discovery.discover()
+        resp = await 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]
+
+    async 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 = await 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)}"
+
+    async def close(self) -> None:
+        await 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/_pkce.py

@@ -0,0 +1,61 @@
+"""
+@fileoverview PKCE (RFC 7636) code-verifier/challenge generation and random state/nonce helpers.
+@module memyauth._pkce
+@description Pure, synchronous, zero I/O — ported verbatim from
+   `memybase/src/auth/oidc.ts:14-20`. PKCE is mandatory and S256-only in this estate (the
+   descriptor schema makes anything else structurally invalid — §C.2). Every random value is drawn
+   through the injected `RandomSource` seam so the conformance harness can seed determinism
+   (`fixedRandom` replaying `case.seed.randomHex`); the default seam uses `secrets.token_bytes`,
+   Python's CSPRNG.
+@dependencies hashlib, base64, secrets (stdlib only)
+@relatedFiles _oidc.py (build_authorization_url), _types.py (RandomSource protocol)
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+
+from ._types import RandomSource
+
+__all__ = [
+    "SystemRandomSource",
+    "base64url_encode",
+    "generate_code_verifier",
+    "generate_code_challenge",
+    "random_state",
+    "random_nonce",
+]
+
+
+class SystemRandomSource:
+    """Default `RandomSource`: Python's CSPRNG (`secrets.token_bytes`, itself `os.urandom`)."""
+
+    def bytes(self, n: int) -> bytes:
+        return secrets.token_bytes(n)
+
+
+def base64url_encode(data: bytes) -> str:
+    """Base64url, NO padding — RFC 7636 §4.1 / RFC 4648 §5, matching the JS SDK's encoder."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def generate_code_verifier(random: RandomSource) -> str:
+    """43-128 char verifier. 32 random bytes -> 43-char base64url string (RFC 7636 §4.1)."""
+    return base64url_encode(random.bytes(32))
+
+
+def generate_code_challenge(code_verifier: str) -> str:
+    """S256 challenge: base64url(sha256(ascii(code_verifier))). The only method this estate's
+    descriptor schema permits (`pkce.methods ⊆ ['S256']`)."""
+    digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
+    return base64url_encode(digest)
+
+
+def random_state(random: RandomSource) -> str:
+    return base64url_encode(random.bytes(32))
+
+
+def random_nonce(random: RandomSource) -> str:
+    return base64url_encode(random.bytes(32))

memyauth/_roles.py

@@ -0,0 +1,109 @@
+"""
+@fileoverview IdP role -> consumer role mapping, and the sole global-admin vocabulary check.
+@module memyauth._roles
+@description Pure — no I/O, no async, no sync twin (§C.6, shared module in both surfaces). Ported
+   verbatim from `memybase/src/iam/iam-client.ts:61-72,82-89`. This is a CONSUMER concept: memyauth
+   itself has no role-mapping table. `GLOBAL_ADMIN_IDP_ROLES = ['admin']` is the single most
+   contested fact in the whole design (§C.6.1) — roboson independently invented `'global-admin'`,
+   a string that appears NOWHERE in the provider (verified by a zero-hit grep across the whole
+   memyauth tree), and its admin gate has matched nobody since. `is_global_admin` MUST test the
+   RAW idp roles, never the mapped output, and `'global-admin'` MUST NOT be a default alias — a
+   test that accepted both would be a weaker test than the one this module ships with.
+@dependencies typing (stdlib only)
+@relatedFiles _iam.py (constructs a RoleMapper and calls map_all/is_global_admin during
+   projection), _errors.py (ConfigError), tests/test_roles.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+from typing import Mapping, Optional, Sequence
+
+from ._errors import ConfigError
+
+__all__ = [
+    "DEFAULT_ROLE_MAP",
+    "CONSUMER_ROLES",
+    "DEFAULT_CONSUMER_ROLE",
+    "GLOBAL_ADMIN_IDP_ROLES",
+    "RoleMapper",
+]
+
+# Ported verbatim from memybase/src/iam/iam-client.ts:61-72 (includes the `datamanager` alias).
+DEFAULT_ROLE_MAP: dict[str, str] = {
+    "admin": "owner",
+    "owner": "owner",
+    "member": "member",
+    "developer": "developer",
+    "data-manager": "data-manager",
+    "datamanager": "data-manager",
+    "viewer": "viewer",
+}
+
+CONSUMER_ROLES: tuple[str, ...] = ("owner", "member", "developer", "data-manager", "viewer")
+DEFAULT_CONSUMER_ROLE = "member"
+
+# §C.6.1 RESOLVED: 'admin' is the canonical global-admin IdP role. 'global-admin' (roboson's
+# invented string) is deliberately ABSENT and must never be added as a default alias.
+GLOBAL_ADMIN_IDP_ROLES: tuple[str, ...] = ("admin",)
+
+
+def _normalize(raw: str) -> str:
+    return raw.strip().lower()
+
+
+class RoleMapper:
+    def __init__(
+        self,
+        *,
+        role_map: Optional[Mapping[str, str]] = None,
+        role_overrides: Optional[Mapping[str, str]] = None,
+        default_role: str = DEFAULT_CONSUMER_ROLE,
+        global_admin_roles: Sequence[str] = GLOBAL_ADMIN_IDP_ROLES,
+        passthrough_unknown: bool = False,
+    ) -> None:
+        base = role_map if role_map is not None else DEFAULT_ROLE_MAP
+        self._validate_map_values("roleMap", base)
+        merged: dict[str, str] = {_normalize(k): v for k, v in base.items()}
+        if role_overrides:
+            self._validate_map_values("roleOverrides", role_overrides)
+            merged.update({_normalize(k): v for k, v in role_overrides.items()})
+        self._map = merged
+
+        if not default_role or not default_role.strip():
+            raise ConfigError("defaultRole must be a non-empty string")
+        self._default_role = default_role
+
+        admins = list(global_admin_roles)
+        if not admins or any(not a or not a.strip() for a in admins):
+            raise ConfigError("globalAdminRoles must be a non-empty array of role names")
+        self._global_admin_roles = {_normalize(a) for a in admins}
+
+        self._passthrough_unknown = passthrough_unknown
+
+    @staticmethod
+    def _validate_map_values(label: str, mapping: Mapping[str, str]) -> None:
+        for value in mapping.values():
+            if not isinstance(value, str) or not value.strip():
+                raise ConfigError(f"{label} values must be non-empty strings")
+
+    def map(self, idp_role: str) -> Optional[str]:
+        normalized = _normalize(idp_role)
+        if normalized in self._map:
+            return self._map[normalized]
+        return normalized if self._passthrough_unknown else None
+
+    def map_all(self, idp_roles: Sequence[str]) -> list[str]:
+        result: list[str] = []
+        seen: set[str] = set()
+        for raw in idp_roles:
+            mapped = self.map(raw)
+            if mapped is None:
+                continue
+            if mapped not in seen:
+                seen.add(mapped)
+                result.append(mapped)
+        return result if result else [self._default_role]
+
+    def is_global_admin(self, idp_roles: Sequence[str]) -> bool:
+        """Tests the RAW idp roles (never the mapped output) against `global_admin_roles`."""
+        return any(_normalize(raw) in self._global_admin_roles for raw in idp_roles)