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

memyauth/_errors.py

@@ -0,0 +1,270 @@
+"""
+@fileoverview SDK error hierarchy — typed exceptions decoded from the MemyAuth wire format.
+@module memyauth._errors
+@description Mirrors the JS SDK's error taxonomy class-for-class, `code`-for-`code`,
+   `status`-for-`status` (design §H) so cross-language conformance can assert on `.code`/`.status`
+   rather than reimplementing per-language logic. `decode_error` is the single decoder: it maps a
+   wire `{code, message, detail?}` envelope (openapi.yaml Error schema) to the matching class, and
+   falls back to an HTTP-status-keyed default when the wire `code` is unrecognized. `ConfigError`
+   deliberately extends `MemyAuthError` (status 0) rather than a bare `ValueError` — unlike
+   memybase's `ReservedFieldError` split, a config error still carries `code`/`status` and belongs
+   in the one taxonomy (§H "Deliberate divergence from memybase").
+@dependencies typing (stdlib only)
+@relatedFiles _transport.py (raises these from non-2xx responses), _config.py (raises ConfigError
+   and UnsupportedAlgorithmPinError), _idtoken.py (raises UnsupportedAlgorithmError), tests/test_errors.py
+@created 2026-09-06
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+__all__ = [
+    "MemyAuthError",
+    "ConfigError",
+    "UnsupportedAlgorithmPinError",
+    "NetworkError",
+    "TimeoutError",
+    "ProtocolError",
+    "BadRequestError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "GoneError",
+    "ServiceUnavailableError",
+    "DiscoveryError",
+    "IssuerMismatchError",
+    "DiscoveryEscapeError",
+    "TokenExchangeError",
+    "RefreshRejectedError",
+    "UserInfoError",
+    "IdTokenError",
+    "UnsupportedAlgorithmError",
+    "SessionTokenError",
+    "StateCookieError",
+    "StateMismatchError",
+    "ERROR_CLASS_MAP",
+    "decode_error",
+]
+
+
+class MemyAuthError(Exception):
+    """Base for every MemyAuth SDK error. `status == 0` means "no wire status" (pre-wire guard,
+    network failure, or a client-side construction error) — the same signal memybase uses, so a
+    caller can branch on `status` without an extra isinstance check."""
+
+    code: str = "memyauth_error"
+    status: int = 0
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        code: Optional[str] = None,
+        status: Optional[int] = None,
+        detail: Any = None,
+        body: Any = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        if code is not None:
+            self.code = code
+        if status is not None:
+            self.status = status
+        self.detail = detail
+        self.body = body
+        self.request_id = request_id
+        self.retry_after = retry_after
+        super().__init__(message or self.code)
+
+
+class ConfigError(MemyAuthError):
+    """A supplied configuration value is missing, malformed, or self-contradictory. Raised at
+    `resolve_config()` time (or at lazy service-getter time — see §F) — never after a wire call."""
+
+    code = "config_error"
+    status = 0
+
+
+class UnsupportedAlgorithmPinError(ConfigError):
+    """`allowedAlgorithms` cannot possibly verify a token this provider issues (§C.10.2). This is
+    the loud-failure mechanism that makes the twice-shipped RS256-vs-ES384 defect (roboson,
+    memyvet) structurally unrepeatable — see `_config.py::_check_algorithm_pin`."""
+
+    code = "unverifiable_algorithm_pin"
+    status = 0
+
+
+class NetworkError(MemyAuthError):
+    code = "network_error"
+    status = 0
+
+
+class TimeoutError(MemyAuthError):  # noqa: A001 - intentional shadow, matches the JS class name
+    code = "timeout"
+    status = 0
+
+
+class ProtocolError(MemyAuthError):
+    """The provider responded, but the body did not conform to the shape this SDK requires
+    (non-JSON 2xx, a malformed `/iam/me`, a missing required discovery key, ...)."""
+
+    code = "protocol_error"
+    status = 0
+
+
+class BadRequestError(MemyAuthError):
+    code = "bad_request"
+    status = 400
+
+
+class UnauthorizedError(MemyAuthError):
+    code = "unauthorized"
+    status = 401
+
+
+class ForbiddenError(MemyAuthError):
+    code = "forbidden"
+    status = 403
+
+
+class NotFoundError(MemyAuthError):
+    code = "not_found"
+    status = 404
+
+
+class GoneError(MemyAuthError):
+    code = "gone"
+    status = 410
+
+
+class ServiceUnavailableError(MemyAuthError):
+    code = "service_unavailable"
+    status = 503
+
+
+class DiscoveryError(MemyAuthError):
+    code = "discovery_failed"
+    status = 0
+
+
+class IssuerMismatchError(DiscoveryError):
+    code = "issuer_mismatch"
+    status = 0
+
+
+class DiscoveryEscapeError(DiscoveryError):
+    """A server-side discovery endpoint (token/userinfo/jwks) resolved to an origin outside the
+    internal fetch origin — see the dual-origin rule in §C.1 step 6."""
+
+    code = "discovery_escape"
+    status = 0
+
+
+class TokenExchangeError(MemyAuthError):
+    code = "token_exchange_failed"
+    status = 0
+
+
+class RefreshRejectedError(MemyAuthError):
+    """A rejected refresh means the session is over — modeled as 401 semantics even though the
+    wire status may differ, matching memybase's `UnauthorizedError`-on-refresh-rejection behavior."""
+
+    code = "refresh_rejected"
+    status = 401
+
+
+class UserInfoError(MemyAuthError):
+    code = "userinfo_failed"
+    status = 0
+
+
+class IdTokenError(MemyAuthError):
+    code = "id_token_invalid"
+    status = 401
+
+
+class UnsupportedAlgorithmError(IdTokenError):
+    """A token's `alg` header is outside the configured `allowed_algorithms` allow-list — raised
+    BEFORE any key lookup. This is what the mandatory RS256 negative test (R1) asserts on."""
+
+    code = "unsupported_algorithm"
+    status = 401
+
+
+class SessionTokenError(MemyAuthError):
+    """Any SDK-issued (HS256) session-token verification failure. Never spans the provider
+    (ES384) token family — see the six-way separation documented in `_session.py`."""
+
+    code = "session_token_invalid"
+    status = 401
+
+
+class StateCookieError(MemyAuthError):
+    code = "state_cookie_invalid"
+    status = 401
+
+
+class StateMismatchError(StateCookieError):
+    """The callback `state` query parameter did not match the signed cookie — the actual CSRF
+    check (`verify()` alone only proves the cookie is ours, not that it matches this callback)."""
+
+    code = "state_mismatch"
+    status = 401
+
+
+# Wire code -> class, from contract.json's errorMap (§B.3, §H).
+ERROR_CLASS_MAP: dict[str, type[MemyAuthError]] = {
+    "bad_request": BadRequestError,
+    "unauthorized": UnauthorizedError,
+    "forbidden": ForbiddenError,
+    "not_found": NotFoundError,
+    "gone": GoneError,
+    "service_unavailable": ServiceUnavailableError,
+    "internal_error": MemyAuthError,  # explicit, generic — stated the same way in both languages
+}
+
+# Unknown wire code -> fall back on HTTP status (§H).
+_BY_STATUS: dict[int, type[MemyAuthError]] = {
+    400: BadRequestError,
+    401: UnauthorizedError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    410: GoneError,
+    503: ServiceUnavailableError,
+}
+
+
+def decode_error(status: int, body: Any = None, request_id: Optional[str] = None) -> MemyAuthError:
+    """Build the right `MemyAuthError` for a non-2xx response.
+
+    The envelope is `{code, message, detail?}` (openapi.yaml Error schema — `code` and `message`
+    are required). A non-conforming body still yields a typed error: the class comes from the
+    status fallback and the raw payload is preserved on `.body` for debugging, but the SDK never
+    raises a bare, untyped exception for a wire failure.
+    """
+    code: Optional[str] = None
+    message: Optional[str] = None
+    detail: Any = None
+
+    if isinstance(body, dict):
+        raw_code = body.get("code")
+        raw_message = body.get("message")
+        if isinstance(raw_code, str):
+            code = raw_code
+        if isinstance(raw_message, str):
+            message = raw_message
+        detail = body.get("detail")
+
+    cls = ERROR_CLASS_MAP.get(code) if code else None
+    if cls is None:
+        cls = _BY_STATUS.get(status, MemyAuthError)
+
+    eff_message = message or f"HTTP {status}"
+    err = cls(eff_message, status=status, detail=detail, body=body, request_id=request_id)
+    # The original wire code is always carried verbatim, even when the class came from the
+    # status fallback (an unrecognized code must never be silently rewritten to the class's own
+    # default code) — §H: "The original wire code is always carried verbatim, never reconstructed
+    # from the chosen class."
+    if code:
+        err.code = code
+    return err

memyauth/_iam.py

@@ -0,0 +1,298 @@
+"""
+@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"],
+        )
+
+    async 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 = await 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"])
+
+    async def me(
+        self,
+        user_token: str,
+        *,
+        caller_mode: Optional[IamCallerMode] = None,
+        timeout_ms: Optional[int] = None,
+        headers: Optional[dict[str, str]] = None,
+    ) -> IamSession:
+        body = await self.me_raw(user_token, caller_mode=caller_mode, timeout_ms=timeout_ms, headers=headers)
+        return project_session(body, self._role_mapper)
+
+    async 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 = await 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]
+
+    async def health(self) -> bool:
+        """Never throws."""
+        try:
+            url = f"{self._config['iam_base_url']}/iam/health"
+            resp = await self._transport.send("GET", url)
+            return 200 <= resp.status_code < 300
+        except Exception:  # noqa: BLE001 - a health probe must never raise
+            return False
+
+    async def close(self) -> None:
+        await self._transport.close()