opencode-swap 0.4.0__py3-none-any.whl

opencode_swap/exceptions.py

@@ -0,0 +1,60 @@
+"""Exception hierarchy for opencode-swap."""
+
+from __future__ import annotations
+
+
+class OpenCodeSwapError(Exception):
+    """Base class for all opencode-swap errors."""
+
+
+class AuthFileError(OpenCodeSwapError):
+    """auth.json is missing, unreadable, or not valid JSON."""
+
+
+class BackupError(OpenCodeSwapError):
+    """A recovery snapshot is unreadable or has an invalid top-level shape."""
+
+
+class SchemaError(OpenCodeSwapError):
+    """A provider's entry in auth.json doesn't match a known shape.
+
+    Raised instead of silently dropping or guessing at the data (fail-safe:
+    refuse to operate on state we don't understand rather than risk
+    corrupting it). OpenCode itself is lenient here — its own Auth.all()
+    silently drops entries that fail schema decode (auth/index.ts:66) — but
+    opencode-swap is about to overwrite that state, so it holds itself to a
+    stricter standard.
+    """
+
+
+class LockError(OpenCodeSwapError):
+    """Could not acquire opencode-swap's own cross-process file lock."""
+
+
+class RegistryError(OpenCodeSwapError):
+    """opencode-swap's own account registry is missing, corrupt, or the
+    requested operation doesn't make sense against its current state."""
+
+
+class SecretStoreError(OpenCodeSwapError):
+    """A secret-store operation failed on every backend available to it."""
+
+
+class AccountExistsError(OpenCodeSwapError):
+    """`add`/`rename` would create a name or identity collision."""
+
+
+class TransferError(OpenCodeSwapError):
+    """An account transfer archive is unsafe, corrupt, or incompatible."""
+
+
+class RefreshError(OpenCodeSwapError):
+    """A standalone OAuth token refresh was attempted and rejected/failed.
+
+    Distinct from usage.py's UsageSnapshot(available=False): that case is a
+    read that degrades gracefully. A rejected refresh grant means the
+    account's refresh token is spent -- OpenAI issues a new one on every use
+    (docs/architecture.md#why-sync-back-is-mandatory) -- so the account is
+    genuinely unusable until the owner re-authenticates with OpenCode
+    (`opencode auth login`) and re-adds it (`opencode-swap add`).
+    """

opencode_swap/locking.py

@@ -0,0 +1,70 @@
+"""Cross-process file lock serializing opencode-swap's own invocations.
+
+Ported from claude-swap's locking.py (fcntl.flock on an exclusive,
+non-blocking lock file, polled with a timeout); the Windows msvcrt branch is
+dropped since opencode-swap v1 targets Linux and macOS only.
+
+This lock has no relationship to OpenCode's own process — it only prevents
+two concurrent `opencode-swap` invocations from interleaving writes to the
+same account data. See switcher.py for how a *running OpenCode* is handled
+(detected and warned about separately, since OpenCode has no cooperative
+lock protocol to join).
+"""
+
+from __future__ import annotations
+
+import fcntl
+import time
+from pathlib import Path
+from types import TracebackType
+from typing import IO, Self
+
+from opencode_swap.exceptions import LockError
+
+
+class FileLock:
+    def __init__(self, lock_path: Path, timeout: float = 10.0):
+        self.lock_path = lock_path
+        self.timeout = timeout
+        self._lock_file: IO[str] | None = None
+        self._locked = False
+
+    def acquire(self, timeout: float | None = None) -> bool:
+        if timeout is None:
+            timeout = self.timeout
+        self.lock_path.parent.mkdir(parents=True, exist_ok=True)
+        lock_file = open(self.lock_path, "w")  # noqa: SIM115
+        self._lock_file = lock_file
+
+        start = time.monotonic()
+        while True:
+            try:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                self._locked = True
+                return True
+            except (BlockingIOError, OSError):
+                if time.monotonic() - start > timeout:
+                    lock_file.close()
+                    self._lock_file = None
+                    return False
+                time.sleep(0.1)
+
+    def release(self) -> None:
+        if self._lock_file and self._locked:
+            fcntl.flock(self._lock_file.fileno(), fcntl.LOCK_UN)
+            self._lock_file.close()
+            self._lock_file = None
+            self._locked = False
+
+    def __enter__(self) -> Self:
+        if not self.acquire():
+            raise LockError(f"failed to acquire lock at {self.lock_path} within {self.timeout}s — another opencode-swap instance may be running")
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.release()

opencode_swap/macos_keychain.py

@@ -0,0 +1,136 @@
+"""macOS Keychain access via the ``security`` CLI.
+
+Ported from claude-swap's macos_keychain.py. A small wrapper around the
+system ``security`` tool for storing generic passwords, used instead of the
+third-party ``keyring`` library:
+
+- Keychain items are created and read by the same stable ``security``
+  binary, so reads stay silent across upgrades. ``keyring`` (and any
+  in-process Security.framework call) anchors the item's access to the
+  *Python interpreter*, which ``uv tool upgrade`` rebuilds — at which point
+  macOS can show the "wants to use your keychain" prompt. ``security``
+  never changes, so creator == reader and there is no prompt.
+
+ - ``set_password`` hex-encodes the value (``-X``) and pipes the command
+   through ``security -i`` (stdin) so the secret never appears in process
+   argv (a process-monitor concern). Measured on-device: ``security -i``
+   truncates a stdin line at 4095 characters regardless of how much more
+   follows (probed with 5K/10K/20K-byte inputs — all truncate identically;
+   no line continuation exists for quoted args or a trailing backslash). A
+   command over this limit fails closed rather than silently truncating a
+   credential. Because this makes any raw credential over ~2000 bytes
+   unroutable through ``security -i`` (hex-encoding doubles it), callers
+   must not depend on this backend alone for values that size or larger —
+   see sealed.py's envelope format, which keeps every Keychain value to a
+   fixed 64 hex chars regardless of credential size.
+- ``get_password`` uses ``find-generic-password ... -w`` and treats exit
+  code 44 as "not found" (returns ``None``); any *other* non-zero exit
+  raises so callers can tell a genuine miss apart from a locked/denied/
+  unavailable Keychain.
+
+Caveat: values must be printable text. ``find-generic-password -w`` prints
+stored data raw only when it is printable; opencode-swap only ever stores
+JSON (ASCII), so this holds — don't reuse this wrapper for binary data.
+
+This module is import-safe on every platform (it only shells out at call
+time); its functions are only meaningful on macOS.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+# ``security -i`` reads stdin with a 4096-byte fgets() buffer and truncates
+# any longer line, with no continuation across lines. Measured directly
+# (5K/10K/20K-byte probe inputs all truncate at the same 4095-char point;
+# BUFSIZ itself is 1024 on darwin, so this is the tool's own internal
+# buffer, not libc's). 64 bytes of headroom guards against line-terminator
+# accounting differences.
+SECURITY_STDIN_LINE_LIMIT = 4096 - 64
+
+_NOT_FOUND_RC = 44  # errSecItemNotFound surfaced by find/delete-generic-password
+
+# Bound every ``security`` spawn so a wedged Keychain (a locked login
+# keychain prompting for an unlock that never comes on a headless/SSH host)
+# can't hang the CLI. A healthy Keychain answers in well under 100ms.
+_TIMEOUT = 5.0
+
+# Pin the absolute path to Apple's system binary rather than resolving via
+# PATH: this is a credential tool, so an attacker-controlled ``security``
+# earlier on PATH must not be able to intercept secrets.
+_SECURITY = "/usr/bin/security"
+
+
+class KeychainError(Exception):
+    """A ``security`` invocation failed for a reason other than "not found"."""
+
+
+# The exceptions a Keychain operation may raise that callers should treat as
+# "Keychain unusable" (→ fall back to file storage) rather than a
+# programming bug. Catching this tuple — never bare Exception — keeps a real
+# bug loud instead of silently routing to the file backend mid-invocation.
+KEYCHAIN_ERRORS = (KeychainError, subprocess.TimeoutExpired, OSError)
+
+
+def _quote(value: str) -> str:
+    """Quote a value for a ``security -i`` stdin command line."""
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def get_password(service: str, account: str) -> str | None:
+    """Return the stored password, or None if no such item exists (rc 44)."""
+    try:
+        result = subprocess.run(
+            [_SECURITY, "find-generic-password", "-a", account, "-w", "-s", service],
+            capture_output=True,
+            text=True,
+            timeout=_TIMEOUT,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as e:
+        raise KeychainError(f"security find-generic-password timed out after {_TIMEOUT}s") from e
+    if result.returncode == 0:
+        return result.stdout.removesuffix("\n")
+    if result.returncode == _NOT_FOUND_RC:
+        return None
+    raise KeychainError(f"security find-generic-password failed (rc={result.returncode}): {result.stderr.strip()}")
+
+
+def set_password(service: str, account: str, password: str) -> None:
+    """Create or update a generic-password item (``-U``)."""
+    hex_value = password.encode("utf-8").hex()
+    command = f"add-generic-password -U -a {_quote(account)} -s {_quote(service)} -X {hex_value}\n"
+    try:
+        if len(command.encode("utf-8")) <= SECURITY_STDIN_LINE_LIMIT:
+            result = subprocess.run(
+                [_SECURITY, "-i"],
+                input=command,
+                capture_output=True,
+                text=True,
+                timeout=_TIMEOUT,
+                check=False,
+            )
+        else:
+            raise KeychainError("security add-generic-password input exceeds safe stdin limit")
+    except subprocess.TimeoutExpired as e:
+        raise KeychainError(f"security add-generic-password timed out after {_TIMEOUT}s") from e
+    if result.returncode != 0:
+        raise KeychainError(f"security add-generic-password failed (rc={result.returncode}): {result.stderr.strip()}")
+
+
+def delete_password(service: str, account: str) -> None:
+    """Delete a generic-password item. rc 44 (already absent) counts as success."""
+    try:
+        result = subprocess.run(
+            [_SECURITY, "delete-generic-password", "-a", account, "-s", service],
+            capture_output=True,
+            text=True,
+            timeout=_TIMEOUT,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as e:
+        raise KeychainError(f"security delete-generic-password timed out after {_TIMEOUT}s") from e
+    if result.returncode in (0, _NOT_FOUND_RC):
+        return
+    raise KeychainError(f"security delete-generic-password failed (rc={result.returncode}): {result.stderr.strip()}")

opencode_swap/models.py

@@ -0,0 +1,190 @@
+"""Data models for opencode-swap."""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass, field
+from enum import Enum, auto
+
+from opencode_swap.exceptions import RegistryError
+
+#: Account name validation: lowercase letters/digits/-/_/./@/+, non-empty,
+#: not leading '-' (argparse would read it as a flag) or '.' (keeps the file-
+#: fallback secret-store filename derived from this name free of anything
+#: that could resemble a relative path component). ``@`` and ``+`` support
+#: common email-address labels.
+_NAME_RE = re.compile(r"^[a-z0-9_.@+-]+$")
+
+type JsonObject = dict[str, object]
+type AccountKey = tuple[str, str]
+
+
+def normalize_account_name(name: str) -> str:
+    """Lowercase and validate a proposed account name; raise ValueError if invalid."""
+    normalized = name.strip().lower()
+    if not normalized:
+        raise ValueError("account name cannot be empty")
+    if normalized.startswith("-"):
+        raise ValueError(f"account name '{name}' cannot start with '-' (would be read as a command flag)")
+    if normalized.startswith("."):
+        raise ValueError(f"account name '{name}' cannot start with '.'")
+    if not _NAME_RE.match(normalized):
+        raise ValueError(f"account name '{name}' may only contain letters, digits, '-', '_', '.', '@', and '+'")
+    return normalized
+
+
+def normalize_provider_id(provider_id: str) -> str:
+    """Validate an exact OpenCode auth.json provider key."""
+    if not provider_id or provider_id != provider_id.strip():
+        raise ValueError("provider id cannot be empty or have surrounding whitespace")
+    if any(ord(char) < 32 or ord(char) == 127 for char in provider_id):
+        raise ValueError("provider id contains control characters")
+    return provider_id
+
+
+class Validity(Enum):
+    """Result of validating an auth record."""
+
+    OK = auto()
+    EXPIRED = auto()
+    INVALID = auto()
+
+
+class ImportConflictAction(Enum):
+    """Action selected when an imported account name already exists."""
+
+    SKIP = auto()
+    OVERWRITE = auto()
+    ABORT = auto()
+
+
+@dataclass(frozen=True)
+class AuthRecord:
+    """A single provider's entry from OpenCode's auth.json.
+
+    ``raw`` is the full original dict, preserved verbatim so a round-trip
+    (read -> store -> splice back in) never drops a field opencode-swap
+    doesn't know about — important since the schema is undocumented and can
+    gain fields across OpenCode versions (see SchemaError).
+    """
+
+    type: str
+    raw: JsonObject
+
+
+@dataclass(frozen=True)
+class AccountDesc:
+    """Human-facing description of an account, safe to print (no secrets)."""
+
+    type: str
+    email: str | None
+    account_id: str | None
+    expires: float | None
+
+
+@dataclass(frozen=True)
+class AccountMeta:
+    """Non-secret registry metadata for one saved account.
+
+    Deliberately excludes the identity string used for switch-time matching
+    (see providers/base.py Provider.identity): when no accountId claim is
+    available, identity falls back to the raw refresh token, which must
+    never land in the non-secret registry. Identity is recomputed on demand
+    from the secret-store-held record instead.
+    """
+
+    name: str
+    provider: str
+    type: str
+    account_id: str | None
+    email: str | None
+    added: str
+
+    def to_dict(self) -> JsonObject:
+        return {
+            "provider": self.provider,
+            "type": self.type,
+            "accountId": self.account_id,
+            "email": self.email,
+            "added": self.added,
+        }
+
+    @classmethod
+    def from_dict(cls, name: str, data: object) -> AccountMeta:
+        try:
+            if normalize_account_name(name) != name:
+                raise ValueError("invalid account name")
+        except ValueError as exc:
+            raise RegistryError(f"registry account has invalid name {name!r}") from exc
+        if not isinstance(data, dict):
+            raise RegistryError(f"registry account {name!r} is not an object")
+
+        unexpected_fields = set(data) - {"provider", "type", "accountId", "email", "added"}
+        if unexpected_fields:
+            raise RegistryError(f"registry account {name!r} has unsupported fields")
+
+        provider = data.get("provider")
+        record_type = data.get("type", "oauth")
+        account_id = data.get("accountId")
+        email = data.get("email")
+        added = data.get("added", "")
+        if not isinstance(provider, str) or not provider:
+            raise RegistryError(f"registry account {name!r} has invalid provider")
+        if not isinstance(record_type, str) or not record_type:
+            raise RegistryError(f"registry account {name!r} has invalid type")
+        if account_id is not None and not isinstance(account_id, str):
+            raise RegistryError(f"registry account {name!r} has invalid accountId")
+        if email is not None and not isinstance(email, str):
+            raise RegistryError(f"registry account {name!r} has invalid email")
+        if not isinstance(added, str):
+            raise RegistryError(f"registry account {name!r} has invalid added timestamp")
+        return cls(
+            name=name,
+            provider=provider,
+            type=record_type,
+            account_id=account_id,
+            email=email,
+            added=added,
+        )
+
+
+@dataclass
+class SwitchTransaction:
+    """Tracks completed steps of an `use_account` switch so switcher.py can
+    roll back the one step that actually mutates OpenCode's live state
+    (auth.json) if a later step fails. See switcher.py's use_account/
+    _rollback for why only "auth_written" needs an active rollback action:
+    every step before it either hasn't touched live state yet, or (for the
+    atomic auth.json write itself) is guaranteed by atomic_write_auth to
+    leave the original file untouched on failure.
+    """
+
+    original_auth: JsonObject
+    completed_steps: list[str] = field(default_factory=list)
+
+    def record_step(self, step: str) -> None:
+        self.completed_steps.append(step)
+
+
+class Platform(Enum):
+    """Supported platforms."""
+
+    MACOS = auto()
+    LINUX = auto()
+    UNKNOWN = auto()
+
+    @classmethod
+    def detect(cls) -> Platform:
+        """Detect current platform.
+
+        Uses sys.platform rather than platform.system(), which can shell out
+        to external tools depending on OS (see claude-swap's Platform.detect
+        docstring for the Windows WMI-hang precedent this avoids).
+        """
+        platform_name = sys.platform.lower()
+        if platform_name == "darwin":
+            return cls.MACOS
+        if platform_name.startswith("linux"):
+            return cls.LINUX
+        return cls.UNKNOWN

opencode_swap/oauth_jwt.py

@@ -0,0 +1,66 @@
+"""Decode claims from an OpenAI OAuth access-token JWT. No network calls.
+
+Mirrors OpenCode's own claim extraction (opencode's
+packages/opencode/src/plugin/openai/codex.ts:47-76, parseJwtClaims /
+extractAccountIdFromClaims) so opencode-swap derives the same accountId
+OpenCode would from the same token. Not signature-verified: we never trust
+these claims for authorization, only use them to label/identify an account
+that OpenCode itself already trusts.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+
+from opencode_swap.models import JsonObject
+
+
+def decode_claims(token: str) -> JsonObject:
+    """Decode a JWT's payload claims. Returns {} if token isn't a valid JWT.
+
+    Empirically (see M0 spike), a real OpenAI access token does not always
+    carry an ``email`` claim — callers must treat email as optional.
+    """
+    parts = token.split(".")
+    if len(parts) != 3:
+        return {}
+    payload = parts[1]
+    padded = payload + "=" * (-len(payload) % 4)
+    try:
+        decoded = base64.urlsafe_b64decode(padded)
+        claims = json.loads(decoded)
+    except (ValueError, UnicodeDecodeError, json.JSONDecodeError):
+        return {}
+    return claims if isinstance(claims, dict) else {}
+
+
+def extract_account_id(claims: JsonObject) -> str | None:
+    """Extract chatgpt_account_id from JWT claims, same fallback order as codex.ts."""
+    direct = claims.get("chatgpt_account_id")
+    if isinstance(direct, str) and direct:
+        return direct
+    nested = claims.get("https://api.openai.com/auth")
+    if isinstance(nested, dict):
+        account_id = nested.get("chatgpt_account_id")
+        if isinstance(account_id, str) and account_id:
+            return account_id
+    orgs = claims.get("organizations")
+    if isinstance(orgs, list) and orgs and isinstance(orgs[0], dict):
+        account_id = orgs[0].get("id")
+        if isinstance(account_id, str):
+            return account_id
+    return None
+
+
+def extract_email(claims: JsonObject) -> str | None:
+    """Extract an email claim if present (not guaranteed on OpenAI access tokens)."""
+    email = claims.get("email")
+    if isinstance(email, str) and email:
+        return email
+    nested = claims.get("https://api.openai.com/auth")
+    if isinstance(nested, dict):
+        email = nested.get("email")
+        if isinstance(email, str) and email:
+            return email
+    return None

opencode_swap/oauth_refresh.py

@@ -0,0 +1,156 @@
+"""Standalone OpenAI OAuth refresh, for accounts opencode-swap manages but
+OpenCode isn't currently pointed at.
+
+Verified against OpenCode's own implementation
+(packages/opencode/src/plugin/openai/codex.ts:125-139,
+refreshAccessToken), not guessed: POST {issuer}/oauth/token,
+grant_type=refresh_token, against the same public PKCE client id OpenCode
+itself uses (docs/opencode-auth.md#loading-and-refresh). There is no client
+secret to protect; this is the same request OpenCode makes on every expired
+request, just triggered by opencode-swap instead.
+
+Refresh tokens are single-use: OpenAI issues a new one on every grant and
+invalidates the old one (docs/architecture.md#why-sync-back-is-mandatory).
+A caller that fails to persist a successful result here has permanently
+lost access to the account -- the old token is already dead. See
+switcher.py's use of this module for the locking/persistence discipline
+that keeps that window as short as possible.
+
+Unlike usage.py, this module raises on failure rather than returning an
+"unavailable" sentinel: a caller deciding whether an account's refresh
+token is dead (needs re-login) versus merely offline needs to be able to
+tell those apart.
+
+`expires` is an *integer* epoch-ms timestamp, not a float. OpenCode's auth
+schema types it as `NonNegativeInt` (auth/index.ts's Oauth class, via
+packages/schema/src/schema.ts's `Schema.Int`), and `Auth.all()` decodes
+with `Record.filterMap` -- an entry that fails to decode is silently
+dropped rather than reported. A fractional `expires` therefore makes
+OpenCode behave as if the provider were never logged in at all, which
+surfaces far from the cause (`auth.type` on an undefined record). OpenCode's
+own refresh builds this from `Date.now()`, which is always integral;
+`time.time() * 1000` is not, so the conversion happens here.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+
+from opencode_swap.exceptions import RefreshError
+from opencode_swap.oauth_jwt import decode_claims, extract_account_id
+
+CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"  # codex.ts:10, public PKCE client, no secret
+ISSUER = "https://auth.openai.com"  # codex.ts:11
+_TOKEN_PATH = "/oauth/token"
+_TIMEOUT = 10.0
+_USER_AGENT = "opencode-swap"
+_DEFAULT_EXPIRES_IN = 3600  # codex.ts:372, `tokens.expires_in ?? 3600`
+
+
+@dataclass(frozen=True)
+class RefreshedTokens:
+    access: str
+    refresh: str
+    expires: int  # epoch ms, integral -- see module docstring
+    account_id: str | None
+
+
+def _valid_expires_in(value: object) -> float | None:
+    """A JSON `expires_in` is otherwise-untrusted server input: it can carry
+    a huge literal (`1e400`) that overflows to `inf`, or `NaN`/`Infinity`
+    directly (Python's json module accepts both by default). Either would
+    silently produce a non-finite `expires` timestamp, which then fails
+    `require_expiry`'s finite check the next time this record is loaded
+    (providers/common.py) -- by then the old refresh token this grant
+    consumed is already dead, permanently bricking the account. Reject here
+    instead, before any of that is persisted.
+    """
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        return None
+    try:
+        if not math.isfinite(value) or value <= 0:
+            return None
+    except OverflowError:
+        return None
+    return float(value)
+
+
+def _account_id_from_tokens(id_token: object, access_token: str) -> str | None:
+    """Same fallback order as codex.ts's extractAccountId: id_token claims
+    first, then access_token claims."""
+    if isinstance(id_token, str) and id_token:
+        account_id = extract_account_id(decode_claims(id_token))
+        if account_id:
+            return account_id
+    return extract_account_id(decode_claims(access_token))
+
+
+def refresh_openai_oauth(refresh_token: str, *, now_ms: float, issuer: str = ISSUER) -> RefreshedTokens:
+    """Exchange a refresh token for a rotated access/refresh pair.
+
+    Raises RefreshError on any failure: rejected grant, network error,
+    timeout, or a response that doesn't match the expected shape. Never
+    includes the response body or the refresh token in the error message
+    (docs/security.md: CLI output must never include a secret).
+    """
+    body = urllib.parse.urlencode(
+        {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": CLIENT_ID,
+        }
+    ).encode()
+    request = urllib.request.Request(
+        f"{issuer}{_TOKEN_PATH}",
+        data=body,
+        headers={"Content-Type": "application/x-www-form-urlencoded", "User-Agent": _USER_AGENT},
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(request, timeout=_TIMEOUT) as response:
+            payload = json.loads(response.read())
+    except urllib.error.HTTPError as exc:
+        if exc.code in (400, 401):
+            raise RefreshError(
+                "refresh token was rejected (it may already have been used elsewhere, or expired); "
+                "run `opencode auth login` for this account, then `opencode-swap add <provider> <name>` again"
+            ) from exc
+        raise RefreshError(f"token refresh failed (HTTP {exc.code})") from exc
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        raise RefreshError(f"token refresh failed: {exc.reason if isinstance(exc, urllib.error.URLError) else exc}") from exc
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise RefreshError(f"token refresh returned an unreadable response: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise RefreshError("token refresh returned an unexpected response shape")
+
+    access_token = payload.get("access_token")
+    new_refresh_token = payload.get("refresh_token")
+    if not isinstance(access_token, str) or not access_token:
+        raise RefreshError("token refresh response is missing 'access_token'")
+    if not isinstance(new_refresh_token, str) or not new_refresh_token:
+        raise RefreshError("token refresh response is missing 'refresh_token'")
+
+    expires_in = _valid_expires_in(payload.get("expires_in"))
+    if expires_in is None:
+        expires_in = float(_DEFAULT_EXPIRES_IN)
+
+    expires = now_ms + expires_in * 1000
+    if not math.isfinite(expires):
+        raise RefreshError("token refresh returned an unusable expiry")
+
+    return RefreshedTokens(
+        access=access_token,
+        refresh=new_refresh_token,
+        # Truncate rather than round: an expiry that lands marginally early
+        # costs at most one extra refresh, while one that lands late would
+        # send a request with an already-dead access token.
+        expires=int(expires),
+        account_id=_account_id_from_tokens(payload.get("id_token"), access_token),
+    )