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

memyauth/_sync/_iam.py

@@ -0,0 +1,300 @@
+# GENERATED by scripts/gen_sync.py from memyauth/_iam.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@fileoverview Capability 5 — IAM identity resolver: caller-credential resolution, permissive
+   response validation, role projection, tenant-key redaction.
+@module memyauth._iam
+@description [async -> _sync/_iam.py twin via scripts/gen_sync.py]. This module is the direct
+   fix for the estate's single worst confirmed defect (D2): roboson's `/iam/me` model is
+   `extra="forbid"` and omits `organizations`, a field memyauth's IAM returns UNCONDITIONALLY, so
+   a real login there can 503. `assert_iam_user_context()` is the enforcement point of the
+   "permissive about unknown fields, strict about known ones" policy (§C.5.1) — it is a
+   hand-written checker, NOT a Pydantic `BaseModel`, deliberately: `ConfigDict(extra="forbid")` is
+   one keyword away from re-creating D2, and Pydantic is not a dependency of this SDK (zero deps
+   beyond httpx + PyJWT). The caller-credential resolver mirrors
+   `memybase/src/iam/iam-client.ts:112-126` with the header names corrected to the real ones
+   (`X-App-Id`/`X-App-Secret` never existed) and enforces mutual exclusion structurally: the
+   header builder can only ever produce ONE marker header per request (R6).
+@dependencies ._transport, ._roles
+@relatedFiles _roles.py (RoleMapper — mapAll/isGlobalAdmin), _config.py (ResolvedConfig, the
+   caller-credential fields), _errors.py, _types.py (UserContext/IamSession/IamOrgEntry),
+   tests/test_iam.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+# ABSOLUTE imports for the shared/pure modules; RELATIVE for ._transport, which DOES get a
+# _sync/ twin and must bind to ITS sibling twin (see _transport.py's header for why).
+from memyauth._config import ResolvedConfig
+from memyauth._errors import ConfigError, ProtocolError, UnauthorizedError
+from memyauth._roles import RoleMapper
+from memyauth._types import IamCallerMode, IamOrgEntry, IamSession, IamTenant, IamUserContext
+
+from ._transport import Transport
+
+__all__ = ["IamService", "assert_iam_user_context"]
+
+_KNOWN_TOP_LEVEL = frozenset({"user", "tenant", "organizations", "permissions"})
+_KNOWN_USER_FIELDS = frozenset(
+    {
+        "sub", "username", "primary_email", "primary_phone", "name", "avatar", "custom_data",
+        "identities", "is_suspended", "has_password", "last_sign_in_at", "created_at",
+        "updated_at", "roles", "scopes", "organization_roles",
+    }
+)
+_KNOWN_TENANT_FIELDS = frozenset({"id", "code", "idp_users_sub", "key", "created_at", "updated_at"})
+_KNOWN_ORG_ENTRY_FIELDS = frozenset({"id", "name", "roles", "tenant"})
+
+
+def assert_iam_user_context(body: Any, *, strict_unknown_fields: bool = False) -> IamUserContext:
+    """The "permissive about unknown fields, strict about known ones" enforcement point (§C.5.1).
+
+    Unknown keys, at ANY level, are ALWAYS tolerated and preserved (the returned value IS `body`,
+    unmodified) — there is no allow-list construct that could reject a field the provider adds
+    later. `strict_unknown_fields=True` (opt-in canary, never the default) additionally checks for
+    unknown keys and raises if any are found; the default path never even computes that check.
+    """
+    if not isinstance(body, dict):
+        raise ProtocolError("Malformed IAM /iam/me response")
+
+    user = body.get("user")
+    if not isinstance(user, dict) or not isinstance(user.get("sub"), str) or not user["sub"]:
+        raise ProtocolError("Malformed IAM /iam/me response")
+    if "roles" in user and not isinstance(user["roles"], list):
+        raise ProtocolError("Malformed IAM /iam/me response")
+    if "scopes" in user and not isinstance(user["scopes"], list):
+        raise ProtocolError("Malformed IAM /iam/me response")
+
+    tenant = body.get("tenant")
+    if not isinstance(tenant, dict) or not isinstance(tenant.get("id"), str) or not tenant["id"]:
+        raise ProtocolError("Malformed IAM /iam/me response")
+
+    organizations = body.get("organizations")
+    if organizations is not None:
+        if not isinstance(organizations, dict):
+            raise ProtocolError("Malformed IAM /iam/me response")
+        for key in ("own", "as_member"):
+            if key in organizations and not isinstance(organizations[key], list):
+                raise ProtocolError("Malformed IAM /iam/me response")
+
+    permissions = body.get("permissions")
+    if permissions is not None and not isinstance(permissions, list):
+        raise ProtocolError("Malformed IAM /iam/me response")
+
+    if strict_unknown_fields:
+        _assert_no_unknown_fields(body, user, tenant, organizations)
+
+    return body  # type: ignore[return-value]
+
+
+def _assert_no_unknown_fields(
+    body: dict[str, Any], user: dict[str, Any], tenant: dict[str, Any], organizations: Any
+) -> None:
+    unknown = set(body) - _KNOWN_TOP_LEVEL
+    if unknown:
+        raise ProtocolError(f"IAM /iam/me response has unknown top-level field(s): {sorted(unknown)}")
+    unknown = set(user) - _KNOWN_USER_FIELDS
+    if unknown:
+        raise ProtocolError(f"IAM /iam/me response has unknown user field(s): {sorted(unknown)}")
+    unknown = set(tenant) - _KNOWN_TENANT_FIELDS
+    if unknown:
+        raise ProtocolError(f"IAM /iam/me response has unknown tenant field(s): {sorted(unknown)}")
+    if isinstance(organizations, dict):
+        for entries in (organizations.get("own") or [], organizations.get("as_member") or []):
+            for entry in entries:
+                if isinstance(entry, dict):
+                    unknown = set(entry) - _KNOWN_ORG_ENTRY_FIELDS
+                    if unknown:
+                        raise ProtocolError(
+                            f"IAM /iam/me response has unknown organization field(s): {sorted(unknown)}"
+                        )
+
+
+def _project_org_entry(entry: dict[str, Any], *, strip_key: bool) -> IamOrgEntry:
+    raw_tenant = entry.get("tenant")
+    projected_tenant = None
+    if isinstance(raw_tenant, dict):
+        projected_tenant = {
+            "id": raw_tenant.get("id"),
+            "code": raw_tenant.get("code"),
+            "idp_users_sub": raw_tenant.get("idp_users_sub"),
+        }
+        key = raw_tenant.get("key")
+        # strip_key=True (as_member) => the key is NEVER copied, even when the wire sent one —
+        # the C.5.1 / tenantKeyRedaction enforcement that must hold regardless of provider intent.
+        if not strip_key and isinstance(key, str) and key:
+            projected_tenant["key"] = key
+    return {
+        "id": entry.get("id"),
+        "name": entry.get("name"),
+        "roles": list(entry.get("roles") or []),
+        "tenant": projected_tenant,
+    }
+
+
+def project_session(body: IamUserContext, role_mapper: RoleMapper) -> IamSession:
+    """Ported from `iam-client.ts:75-110`."""
+    user = body["user"]  # type: ignore[index]
+    tenant = body["tenant"]  # type: ignore[index]
+    organizations = body.get("organizations") or {}  # type: ignore[union-attr]
+    own_raw = organizations.get("own") or []
+    as_member_raw = organizations.get("as_member") or []
+    idp_roles = list(user.get("roles") or [])
+    scopes = list(user.get("scopes") or [])
+    permissions = list(body.get("permissions") or [])  # type: ignore[union-attr]
+
+    email_verified = user.get("email_verified")
+    session: IamSession = {
+        "user_id": user["sub"],
+        "idp_subject": user["sub"],
+        "email": user.get("primary_email") or "",
+        "email_verified": email_verified if isinstance(email_verified, bool) else None,
+        "tenant_id": tenant["id"],
+        "tenant_code": tenant.get("code") or "",
+        "idp_roles": idp_roles,
+        "roles": role_mapper.map_all(idp_roles),
+        "scopes": scopes,
+        "permissions": permissions,
+        "is_global_admin": role_mapper.is_global_admin(idp_roles),
+        "organizations": {
+            "own": [_project_org_entry(o, strip_key=False) for o in own_raw],
+            "as_member": [_project_org_entry(o, strip_key=True) for o in as_member_raw],
+        },
+    }
+    display_name = user.get("name")
+    if display_name:
+        session["display_name"] = display_name
+    tenant_key = tenant.get("key")
+    if isinstance(tenant_key, str) and tenant_key:
+        session["tenant_key"] = tenant_key
+    return session
+
+
+def resolve_caller_headers(config: ResolvedConfig, override_mode: Optional[IamCallerMode]) -> tuple[dict[str, str], str]:
+    """Returns EXACTLY ONE marker header (or none, for m2m) + the caller kind (§C.5, R6)."""
+    mode = override_mode or config["iam_caller_mode"]
+
+    def appiam() -> tuple[dict[str, str], str]:
+        if config.get("iam_app_id") and config.get("iam_app_secret"):
+            return (
+                {"X-AppIam-Id": config["iam_app_id"], "Authorization": f"Bearer {config['iam_app_secret']}"},
+                "appiam",
+            )
+        raise ConfigError("IAM caller credentials are not configured")
+
+    def appidp() -> tuple[dict[str, str], str]:
+        if config.get("client_id") and config.get("client_secret"):
+            return (
+                {"X-AppIdp-Id": config["client_id"], "Authorization": f"Bearer {config['client_secret']}"},
+                "appidp",
+            )
+        raise ConfigError("IAM caller credentials are not configured")
+
+    def m2m() -> tuple[dict[str, str], str]:
+        if config.get("iam_m2m_token"):
+            return {"Authorization": f"Bearer {config['iam_m2m_token']}"}, "m2m"
+        raise ConfigError("IAM caller credentials are not configured")
+
+    if mode == "appiam":
+        return appiam()
+    if mode == "appidp":
+        return appidp()
+    if mode == "m2m":
+        return m2m()
+
+    # auto: precedence appiam -> appidp -> m2m (memybase's order, §C.5).
+    if config.get("iam_app_id") and config.get("iam_app_secret"):
+        return appiam()
+    if config.get("client_id") and config.get("client_secret"):
+        return appidp()
+    if config.get("iam_m2m_token"):
+        return m2m()
+    raise ConfigError("IAM caller credentials are not configured")
+
+
+class IamService:
+    def __init__(
+        self,
+        *,
+        config: ResolvedConfig,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self._config = config
+        self._transport = Transport(
+            timeout_ms=config["iam_timeout_ms"],
+            max_retries=config["retry"]["max_retries"],
+            base_delay_ms=config["retry"]["base_delay_ms"],
+            retryable_statuses=config["retry"]["retryable_statuses"],
+            transport=transport,
+        )
+        self._role_mapper = RoleMapper(
+            role_map=config["role_map"],
+            role_overrides=config["role_overrides"],
+            default_role=config["default_role"],
+            global_admin_roles=config["global_admin_roles"],
+        )
+
+    def me_raw(
+        self,
+        user_token: str,
+        *,
+        caller_mode: Optional[IamCallerMode] = None,
+        timeout_ms: Optional[int] = None,
+        headers: Optional[dict[str, str]] = None,
+    ) -> IamUserContext:
+        if not user_token:
+            raise UnauthorizedError("Missing user token")
+        auth_headers, _kind = resolve_caller_headers(self._config, caller_mode)
+        req_headers = {**auth_headers, "X-User-Token": user_token, "Accept": "application/json", **(headers or {})}
+        url = f"{self._config['iam_base_url']}/iam/me"
+        body = self._transport.request_json(
+            "GET", url, headers=req_headers, timeout_ms=timeout_ms if timeout_ms is not None else self._config["iam_timeout_ms"]
+        )
+        return assert_iam_user_context(body, strict_unknown_fields=self._config["strict_unknown_fields"])
+
+    def me(
+        self,
+        user_token: str,
+        *,
+        caller_mode: Optional[IamCallerMode] = None,
+        timeout_ms: Optional[int] = None,
+        headers: Optional[dict[str, str]] = None,
+    ) -> IamSession:
+        body = self.me_raw(user_token, caller_mode=caller_mode, timeout_ms=timeout_ms, headers=headers)
+        return project_session(body, self._role_mapper)
+
+    def tenant_by_key(
+        self,
+        tenant_key: str,
+        *,
+        caller_mode: Optional[IamCallerMode] = None,
+        timeout_ms: Optional[int] = None,
+        headers: Optional[dict[str, str]] = None,
+    ) -> IamTenant:
+        if not tenant_key:
+            raise UnauthorizedError("Missing tenant key")
+        auth_headers, _kind = resolve_caller_headers(self._config, caller_mode)
+        req_headers = {**auth_headers, "X-Tenant-Key": tenant_key, "Accept": "application/json", **(headers or {})}
+        url = f"{self._config['iam_base_url']}/iam/tenants/me"
+        body = self._transport.request_json(
+            "GET", url, headers=req_headers, timeout_ms=timeout_ms if timeout_ms is not None else self._config["iam_timeout_ms"]
+        )
+        if not isinstance(body, dict) or not isinstance(body.get("id"), str) or not body["id"]:
+            raise ProtocolError("Malformed IAM /iam/tenants/me response")
+        return body  # type: ignore[return-value]
+
+    def health(self) -> bool:
+        """Never throws."""
+        try:
+            url = f"{self._config['iam_base_url']}/iam/health"
+            resp = self._transport.send("GET", url)
+            return 200 <= resp.status_code < 300
+        except Exception:  # noqa: BLE001 - a health probe must never raise
+            return False
+
+    def close(self) -> None:
+        self._transport.close()

memyauth/_sync/_idtoken.py

@@ -0,0 +1,167 @@
+# GENERATED by scripts/gen_sync.py from memyauth/_idtoken.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@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]] = {}
+
+    def _refresh_jwks(self) -> None:
+        doc = self._discovery.discover()
+        resp = 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}
+
+    def _get_key_for_kid(self, kid: str) -> dict[str, Any]:
+        if kid not in self._jwks_cache:
+            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]
+
+    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 = 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
+
+    def close(self) -> None:
+        self._transport.close()