simulo 0.26.0__py3-none-any.whl

simulo/_client/http.py

@@ -0,0 +1,414 @@
+"""Shared HTTP request/auth logic for the cloud submit surface (stdlib ``urllib`` only).
+
+Factored out of ``jobs_api.py`` so ``jobs_api.py``, ``submit_api.py``, and
+``login.py`` share exactly one request path, one structured-error parser, and
+one bearer-attachment policy — a security-sensitive decision that must not be
+reimplemented three times.
+
+**https-when-token guard.** A bearer token must never be sent to a plain-http
+URL unless that URL's host is the local loopback (developing against
+``simulo-backend serve`` on ``127.0.0.1`` is the one legitimate plaintext
+case). Sending a token to a non-loopback ``http://`` URL is refused with a
+clear error — it almost always means ``SIMULO_API_URL`` is misconfigured
+(missing ``https://``), and silently sending the token anyway would leak it to
+anyone on the network path.
+
+**Foreign-host rule.** A caller resolving a presigned (or control-plane-served)
+``download_url``/``upload_url`` from a JSON response body must attach the API
+bearer only when that URL's host equals the API host — see
+``simulo.interfaces.platform.submit`` module docstring ("Worker URL rule").
+Presigned S3 URLs carry their own auth in their query string; sending the API
+bearer to a third-party host is both unnecessary and a credential-leakage risk.
+:func:`may_attach_bearer` implements this rule for any URL against a resolved
+API base URL.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Optional
+
+#: Every outbound call has an explicit timeout (NFR — no open-ended waits).
+DEFAULT_TIMEOUT_S = 10.0
+
+#: Loopback hostnames exempt from the https-when-token guard. ``localhost``
+#: is not an IP literal so it needs an explicit exact-match entry;
+#: ``127.0.0.1``/``::1`` are listed too for defense-in-depth clarity even
+#: though :func:`is_loopback_host` also recognizes them (and the rest of
+#: ``127.0.0.0/8``) via ``ipaddress.ip_address(...).is_loopback``.
+_LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1"})
+
+
+class HttpError(RuntimeError):
+    """Base error for HTTP communication problems against the Simulo platform."""
+
+
+class HttpUnavailable(HttpError):
+    """The endpoint cannot be reached at all (nothing listening / DNS failure)."""
+
+
+class HttpHTTPError(HttpError):
+    """A structured non-2xx response, parsed from the standard error envelope.
+
+    ``candidates`` (optional): some 409 responses carry a machine-readable
+    ``candidates`` list as a SIBLING of the ``error`` envelope — the ids an
+    ambiguous resource-id prefix matched (``job_ref_ambiguous``,
+    explicit-run-intent wave; the server's human ``message`` lists them too,
+    so callers that only print ``message`` still show them). ``None`` when
+    the response carried no such field — the normal case.
+
+    ``retry_after`` (optional): the parsed ``Retry-After`` header (seconds) that
+    the control plane sends on a 429 ``rate_limit_exceeded`` response (NFR:
+    "Never return 429 without ``Retry-After``"). ``None`` when the header was
+    absent or not an integer number of seconds. The CLI's observe loops sleep
+    this value (falling back to their own poll interval) and continue rather
+    than dying on a rate limit — see ``cli.py``'s 429 branches.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        *,
+        candidates: Optional[list[str]] = None,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        super().__init__(f"{code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.candidates = candidates
+        self.retry_after = retry_after
+
+
+class InsecureBearerError(HttpError):
+    """Refused to attach a bearer token to a plain-http, non-loopback URL."""
+
+
+def is_loopback_host(hostname: Optional[str]) -> bool:
+    """``True`` for ``localhost`` / ``::1`` / any genuine loopback IP literal — the
+    local dev loopback.
+
+    Public (not ``_``-prefixed): shared by the bearer-attachment guard below
+    AND by any caller that needs the same "is this the local dev stand-in"
+    judgment for a DIFFERENT scheme pair (e.g. ``simulo view``'s https-or-
+    loopback-http / wss-or-loopback-ws checks on a server-supplied URL before
+    handing it to ``webbrowser.open`` — see ``cli._validate_mint_response_urls``).
+    This is also the function the console's ``isLoopbackHost`` port
+    (``simulo-ui/apps/simulo-console/src/api/jobs.ts``) names as its
+    "authority" — any behavioral drift there is a bug in the console, not a
+    reinterpretation, so the rule stated here is the canonical one.
+
+    **The rule.** ``hostname`` is loopback when it is EXACTLY ``localhost``
+    or ``::1`` (a case-SENSITIVE exact-string match against this function's
+    own input — ``localhost.evil.com`` and the trailing-dot ``localhost.``
+    are NOT loopback regardless of case. This does NOT mean an uppercase
+    URL is rejected end to end: BOTH real call sites pass this function
+    ``urlsplit(url).hostname``, which ``urlsplit`` already lowercases, so
+    ``http://LOCALHOST/`` — and ``http://LOCALHOST/`` piped through either
+    ``require_https_or_loopback_for_bearer`` or
+    ``cli._validate_mint_response_urls`` — is accepted; only a DIRECT call
+    to this function with a raw, still-uppercase string like
+    ``is_loopback_host("LOCALHOST")`` sees the case sensitivity), OR when
+    it parses as a
+    genuine IPv4/IPv6 literal whose address is loopback — i.e. the full
+    ``127.0.0.0/8`` range (``127.0.0.1``, ``127.5.5.5``,
+    ``127.255.255.255``, ...), not just ``127.0.0.1`` itself, plus the
+    IPv4-mapped IPv6 alias ``::ffff:127.0.0.1`` (a genuine loopback address
+    per RFC 4291, not an attacker-controllable string) — but ONLY the
+    IPv4-MAPPED form (``::ffff:a.b.c.d``, ``IPv6Address.ipv4_mapped`` set).
+    The deprecated IPv4-COMPATIBLE form (``::127.0.0.1``), a 6to4 address
+    embedding a loopback octet (``2002:7f00:1::``), and a NAT64
+    well-known-prefix address embedding one (``64:ff9b::127.0.0.1``) are
+    all REJECTED — each parses to a distinct IPv6 literal with
+    ``ipv4_mapped is None`` (verified directly), so they fall to
+    ``addr.is_loopback`` on the address AS WRITTEN, which is ``False`` for
+    all three; they are not silently folded into the mapped case. A
+    hostname is deliberately NOT loopback merely for STARTING WITH the
+    string
+    ``"127."`` — ``127.evil.com``, ``127.0.0.1.evil.com``, and
+    ``127.0.0.1.attacker.tld`` are ordinary attacker-registrable public
+    domains and are rejected — a naive ``hostname.startswith("127.")``
+    check would have wrongly accepted all three, which is exactly the
+    trap this function exists to avoid. The trailing-dot form
+    ``127.0.0.1.`` is ALSO now rejected (``ipaddress.ip_address`` refuses
+    it) — a narrowing versus the old prefix check, which used to accept
+    it; fail-closed, so not a security regression, but worth stating since
+    it is a behavior change. An IPv6 zone id (``::1%eth0``,
+    ``::1%25eth0``) is still accepted — ``ipaddress`` parses the zone and
+    the address portion is still exactly ``::1``; security-neutral (a zone
+    id narrows which local interface a scope-local address binds to, it
+    cannot be used to reach a remote host), documented here so it reads as
+    a deliberate decision rather than an oversight.
+
+    **Why this does not just call ``ipaddress.IPv6Address.is_loopback``
+    directly.** That property only special-cases an IPv4-mapped address
+    (delegating to the mapped ``IPv4Address``'s own ``is_loopback``) on
+    Python >= 3.11.9 / >= 3.12.4 (the CVE-2024-4032 backport) — on any
+    OLDER patch release within this package's own ``>=3.11`` floor (e.g.
+    3.11.0-3.11.8, 3.12.0-3.12.3 — verified directly against a 3.12.3
+    interpreter), it falls back to a bare ``self._ip == 1`` check and
+    returns ``False`` for ``::ffff:127.0.0.1``. Relying on that delegation
+    would make this function's behavior depend on which patch release
+    happens to be installed — the exact same ``127.0.0.1`` URL would be
+    accepted on one machine and refused on another. This function reads
+    ``IPv6Address.ipv4_mapped`` (a plain attribute, unaffected by that CVE
+    fix, correct on every supported release) itself and checks
+    ``is_loopback`` on the UNWRAPPED address, so the result is identical
+    on every Python version this package supports.
+
+    **Deliberately REJECTED, not accidentally:** alternate/shorthand IPv4
+    encodings — ``127.1`` (BSD ``inet_aton`` shorthand), ``2130706433``
+    (decimal 32-bit form), ``0x7f000001`` (hex form), and ``0177.0.0.1``
+    (leading-octal first octet) — all raise ``ValueError`` out of
+    ``ipaddress.ip_address`` and so are treated as NOT loopback here,
+    fail-closed. (The console's JS port's OWN ``isLoopbackHost`` function
+    rejects these same four strings too — ``isLoopbackHost('127.1')`` is
+    ``False`` there as well. What differs is the console's URL-LEVEL
+    check: the browser's ``URL()`` parser canonicalizes a ``viewerUrl``/
+    ``gatewayUrl`` string like ``http://127.1/session`` to
+    ``http://127.0.0.1/session`` *before* ``isLoopbackHost`` ever sees the
+    hostname, so the console's end-to-end URL validation accepts those
+    URLs even though its own ``isLoopbackHost`` would reject the bare
+    string ``"127.1"``. Python's ``urllib.parse.urlsplit()`` performs no
+    such canonicalization — the hostname reaching THIS function is still
+    the literal, unresolved string — so accepting these here would mean
+    reimplementing that canonicalization ourselves for a dev-only
+    affordance that real dev servers never report their bind address as.)
+    Out-of-range octets (``127.256.0.1``) and ambiguous leading-zero
+    octets (``127.001.0.1`` — the same octal-vs-decimal ambiguity
+    CVE-2021-29921 hardened ``ipaddress`` against) are rejected the same
+    way.
+
+    A THIRD, independent copy of this "is this the local dev loopback"
+    judgment lives in ``simulo-backend``'s parked CLI —
+    ``sdk/src/simulo/cli/api/client.py``'s module-level ``_LOOPBACK_HOSTS``
+    frozenset, tested inline inside ``SimuloClient._assert_token_transport_safe``
+    (no separate function). Not vulnerable to the bug this function's
+    docstring describes above (it was always exact-set membership, no
+    prefix test), but it does not recognize the full ``127.0.0.0/8``
+    range or IPv4-mapped IPv6 the way this function now does, so it is
+    STRICTER, not just independently correct. Not unified with this
+    module here (`simulo-backend` is a separate, GPU-only package that
+    does not depend on the ``simulo`` thin client) — flagged so a future
+    reader of either copy knows the other exists.
+    """
+    if hostname is None or not isinstance(hostname, str):
+        return False
+    if hostname in _LOOPBACK_HOSTS:
+        return True
+    try:
+        addr = ipaddress.ip_address(hostname)
+    except ValueError:
+        return False
+    # Read `ipv4_mapped` ourselves rather than trusting `addr.is_loopback`
+    # to do it — see the docstring's CVE-2024-4032 note above.
+    mapped = getattr(addr, "ipv4_mapped", None)
+    return (mapped or addr).is_loopback
+
+
+def require_https_or_loopback_for_bearer(url: str) -> None:
+    """Raise :class:`InsecureBearerError` if *url* would carry a bearer over plaintext.
+
+    Call this immediately before attaching an ``Authorization: Bearer`` header to
+    any request. ``https://`` is always fine; ``http://`` is fine only to the
+    local loopback (127.0.0.1 / localhost / ::1) — the local dev stand-in.
+    """
+    parsed = urllib.parse.urlsplit(url)
+    if parsed.scheme == "https":
+        return
+    if parsed.scheme == "http" and is_loopback_host(parsed.hostname):
+        return
+    raise InsecureBearerError(
+        f"Refusing to send an Authorization bearer token to {url!r}: only https:// URLs "
+        "(or plain http:// to the local loopback) may carry a bearer token. Check "
+        "SIMULO_API_URL / SIMULO_ENV for a missing 'https://'."
+    )
+
+
+def may_attach_bearer(url: str, *, api_base_url: str) -> bool:
+    """``True`` when *url*'s host matches *api_base_url*'s host.
+
+    Implements the "worker URL rule" from ``simulo.interfaces.platform.submit``
+    for client-side downloads too: a presigned/foreign-host URL returned inside
+    a JSON response (e.g. a recording's ``download_url``) must never receive the
+    API bearer — only requests to the API host itself may carry it.
+    """
+    return urllib.parse.urlsplit(url).netloc == urllib.parse.urlsplit(api_base_url).netloc
+
+
+#: Ceiling on a parsed ``Retry-After`` (seconds) — mirrors the control plane's
+#: own rate-limit windows (all well under an hour). Security clamp (LOW,
+#: PR #398 review): without this, an untrusted/misbehaving server value flows
+#: straight into ``time.sleep`` in the CLI's observe loops, which has TWO
+#: failure modes — an indefinite-looking wedge on a huge-but-sleepable value,
+#: and an *uncaught* ``OverflowError`` (``time.sleep`` rejects a duration that
+#: doesn't fit its underlying timer) on a value beyond roughly 1e9 seconds,
+#: crashing the CLI with a traceback instead of backing off. Clamping here —
+#: the single parse site — closes both: every caller only ever sees a value
+#: in ``[0, _RETRY_AFTER_MAX_S]``.
+_RETRY_AFTER_MAX_S = 3600
+
+
+def _parse_retry_after(headers: Any) -> Optional[int]:
+    """Parse a ``Retry-After`` response header (seconds) tolerantly, clamped.
+
+    ``headers`` is the error response's ``http.client.HTTPMessage`` (a
+    case-insensitive ``email.message.Message``); ``.get`` returns ``None`` when
+    the header is absent. The control plane always sends ``Retry-After`` as an
+    integer number of seconds on a 429. Per RFC 7231 the header MAY instead be
+    an HTTP-date — the platform never emits that form, so a non-integer (or
+    negative) value simply yields ``None`` and the caller falls back to its own
+    poll interval rather than failing the whole error parse. A value larger
+    than ``_RETRY_AFTER_MAX_S`` is clamped down to it, never rejected to
+    ``None`` — a large-but-honest backoff request should still be honored
+    (bounded), not silently downgraded to the caller's (likely much shorter)
+    default poll interval.
+    """
+    if headers is None:
+        return None
+    raw = headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        seconds = int(str(raw).strip())
+    except (TypeError, ValueError):
+        return None
+    if seconds < 0:
+        return None
+    return min(seconds, _RETRY_AFTER_MAX_S)
+
+
+def _structured_http_error(exc: urllib.error.HTTPError) -> HttpHTTPError:
+    """Parse the standard ``{"error": {code, message, ...}}`` envelope, tolerantly."""
+    code, message = "http_error", f"HTTP {exc.code}"
+    candidates: Optional[list[str]] = None
+    # Read the `Retry-After` header (429 rate-limit backoff) BEFORE consuming
+    # the body — headers are always present even when the body is empty/non-JSON.
+    retry_after = _parse_retry_after(getattr(exc, "headers", None))
+    try:
+        body = json.loads(exc.read().decode("utf-8"))
+        if isinstance(body, dict) and isinstance(body.get("error"), dict):
+            error = body["error"]
+            code = str(error.get("code", code))
+            message = str(error.get("message", message))
+            # `candidates` rides as a SIBLING of the error envelope (see
+            # HttpHTTPError docstring) — parsed just as tolerantly: anything
+            # that isn't a list stays None rather than failing the parse.
+            raw_candidates = body.get("candidates")
+            if isinstance(raw_candidates, list):
+                candidates = [str(candidate) for candidate in raw_candidates]
+    except (ValueError, OSError):
+        pass  # non-JSON error body — keep the generic code/message
+    return HttpHTTPError(exc.code, code, message, candidates=candidates, retry_after=retry_after)
+
+
+def _redact_query(url: str) -> str:
+    """Strip *url*'s query string (security LOW, PR-7 trio review).
+
+    A presigned S3 PUT/GET URL's query string carries the SigV4 signature
+    and credential scope — printing it whole into an error message (which
+    can land in a terminal, a CI log, or a bug report) would leak a live,
+    unexpired credential for the duration of the presign's TTL. The host and
+    path stay (useful for diagnosis: which endpoint failed); only the query
+    is dropped. Applied narrowly at the one error-text call site
+    (:func:`_unavailable_message`) — additive, no behavior change for a
+    caller that never sees an unreachable-host error.
+    """
+    parsed = urllib.parse.urlsplit(url)
+    return urllib.parse.urlunsplit((parsed.scheme, parsed.netloc, parsed.path, "", parsed.fragment))
+
+
+def _unavailable_message(url: str, unavailable_hint: str, reason: object) -> str:
+    hint = f"\n{unavailable_hint}" if unavailable_hint else ""
+    return f"Cannot reach the Simulo platform at {_redact_query(url)} ({reason}).{hint}"
+
+
+def request_bytes(
+    method: str,
+    url: str,
+    *,
+    token: Optional[str] = None,
+    api_base_url: Optional[str] = None,
+    body: Optional[bytes] = None,
+    content_type: Optional[str] = None,
+    extra_headers: Optional[dict[str, str]] = None,
+    timeout: float = DEFAULT_TIMEOUT_S,
+    unavailable_hint: str = "",
+    on_response_headers: Optional[Callable[[Any], None]] = None,
+) -> bytes:
+    """Issue one HTTP request; return the raw response body bytes.
+
+    When *token* is given, it is attached as ``Authorization: Bearer`` UNLESS
+    *api_base_url* is given and *url* resolves to a different host (the
+    foreign-host rule) — in which case the header is silently omitted (the
+    normal, expected case for a presigned download URL). When the header WOULD
+    be attached, :func:`require_https_or_loopback_for_bearer` is enforced first.
+
+    ``on_response_headers`` (optional) is called with the SUCCESS response's
+    header mapping (``http.client.HTTPMessage``) before the body is read —
+    the additive seam the asset multipart-upload client uses to capture a
+    presigned part PUT's ``ETag`` header (S3's convention) without a second
+    request path. Never called on an error response.
+    """
+    headers: dict[str, str] = dict(extra_headers or {})
+    if token is not None and (api_base_url is None or may_attach_bearer(url, api_base_url=api_base_url)):
+        require_https_or_loopback_for_bearer(url)
+        headers["Authorization"] = f"Bearer {token}"
+    if content_type is not None:
+        headers["Content-Type"] = content_type
+    request = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            if on_response_headers is not None:
+                on_response_headers(response.headers)
+            result: bytes = response.read()
+            return result
+    except urllib.error.HTTPError as exc:
+        raise _structured_http_error(exc) from exc
+    except urllib.error.URLError as exc:
+        raise HttpUnavailable(_unavailable_message(url, unavailable_hint, exc.reason)) from exc
+
+
+def request_json(
+    method: str,
+    url: str,
+    *,
+    token: Optional[str] = None,
+    api_base_url: Optional[str] = None,
+    json_body: Optional[Any] = None,
+    extra_headers: Optional[dict[str, str]] = None,
+    timeout: float = DEFAULT_TIMEOUT_S,
+    unavailable_hint: str = "",
+) -> Any:
+    """Issue one JSON-in/JSON-out request; return the parsed response body."""
+    headers = {"Accept": "application/json", **(extra_headers or {})}
+    body: Optional[bytes] = None
+    content_type: Optional[str] = None
+    if json_body is not None:
+        body = json.dumps(json_body).encode("utf-8")
+        content_type = "application/json"
+    raw = request_bytes(
+        method,
+        url,
+        token=token,
+        api_base_url=api_base_url,
+        body=body,
+        content_type=content_type,
+        extra_headers=headers,
+        timeout=timeout,
+        unavailable_hint=unavailable_hint,
+    )
+    if not raw:
+        return None
+    return json.loads(raw.decode("utf-8"))
+
+
+def quote_path_segment(segment: str) -> str:
+    """Percent-encode one URL path segment (rejects ``/`` so traversal cannot survive)."""
+    return urllib.parse.quote(segment, safe="")

simulo/_client/identity_api.py

@@ -0,0 +1,117 @@
+"""Authenticated identity lookup for the thin CLI.
+
+Organization names and slugs are live server-owned profile data.  They do not
+belong in the credential file, whose UUID fields remain the authorization
+contract.  This client therefore reads ``GET /users/me`` through the shared
+stdlib HTTP boundary without persisting any response field.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+from uuid import UUID
+
+from simulo._client import http
+
+_REQUEST_TIMEOUT_S = 10.0
+_UNAVAILABLE_HINT = "Cannot load your current identity — check your network connection and try again."
+
+
+class IdentityApiError(http.HttpError):
+    """A malformed or unavailable current-user response."""
+
+
+def _require_canonical_uuid(value: Any, *, context: str) -> str:
+    if not isinstance(value, str):
+        raise IdentityApiError(f"Malformed {context} (organization ID is not a string).")
+    try:
+        canonical = str(UUID(value))
+    except ValueError as exc:
+        raise IdentityApiError(f"Malformed {context} (organization ID is not a UUID).") from exc
+    if canonical != value:
+        raise IdentityApiError(f"Malformed {context} (organization ID is not canonical).")
+    return canonical
+
+
+class IdentityApiClient:
+    """Client for ``GET /users/me``."""
+
+    def __init__(self, base_url: str, *, token: Optional[str] = None) -> None:
+        if not base_url.startswith(("http://", "https://")):
+            raise IdentityApiError(f"API base URL must be an http(s) URL, got {base_url!r}.")
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+
+    def get_me(self) -> dict[str, Any]:
+        try:
+            payload = http.request_json(
+                "GET",
+                self._base_url + "/users/me",
+                token=self._token,
+                api_base_url=self._base_url,
+                timeout=_REQUEST_TIMEOUT_S,
+                unavailable_hint=_UNAVAILABLE_HINT,
+            )
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            raise IdentityApiError("Malformed current-user response (expected UTF-8 JSON).") from exc
+        if not isinstance(payload, dict) or not isinstance(payload.get("email"), str):
+            raise IdentityApiError("Malformed current-user response (missing email).")
+        active = payload.get("active_organization")
+        if active is not None:
+            if not isinstance(active, dict):
+                raise IdentityApiError("Malformed current-user response (active organization is not an object).")
+            missing = [
+                field
+                for field in ("organization_id", "name", "slug")
+                if not isinstance(active.get(field), str) or not active[field]
+            ]
+            if missing:
+                raise IdentityApiError(
+                    f"Malformed current-user response (active organization missing field(s) {missing})."
+                )
+            _require_canonical_uuid(active["organization_id"], context="current-user response")
+        memberships = payload.get("memberships")
+        if not isinstance(memberships, list):
+            raise IdentityApiError("Malformed current-user response (memberships is not an array).")
+        for membership in memberships:
+            if not isinstance(membership, dict):
+                raise IdentityApiError("Malformed current-user response (membership is not an object).")
+            missing = [
+                field
+                for field in ("organization_id", "name", "slug", "role", "status")
+                if not isinstance(membership.get(field), str) or not membership[field]
+            ]
+            if missing:
+                raise IdentityApiError(f"Malformed current-user response (membership missing field(s) {missing}).")
+            _require_canonical_uuid(membership["organization_id"], context="current-user response")
+        return payload
+
+    def switch_organization(self, organization_id: str) -> dict[str, Any]:
+        """Switch to an already-resolved active membership UUID."""
+        organization_id = _require_canonical_uuid(organization_id, context="organization switch request")
+        try:
+            payload = http.request_json(
+                "POST",
+                self._base_url + f"/orgs/{http.quote_path_segment(organization_id)}/switch",
+                token=self._token,
+                api_base_url=self._base_url,
+                timeout=_REQUEST_TIMEOUT_S,
+                unavailable_hint=_UNAVAILABLE_HINT,
+            )
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            raise IdentityApiError("Malformed organization-switch response (expected UTF-8 JSON).") from exc
+        if not isinstance(payload, dict) or not isinstance(payload.get("active_organization"), dict):
+            raise IdentityApiError("Malformed organization-switch response (missing active organization).")
+        active = payload["active_organization"]
+        missing = [
+            field
+            for field in ("organization_id", "name", "slug", "role")
+            if not isinstance(active.get(field), str) or not active[field]
+        ]
+        if missing:
+            raise IdentityApiError(f"Malformed organization-switch response (missing field(s) {missing}).")
+        _require_canonical_uuid(active["organization_id"], context="organization-switch response")
+        if str(active["organization_id"]) != organization_id:
+            raise IdentityApiError("Malformed organization-switch response (organization does not match request).")
+        return dict(active)