opencode-swap 0.4.0__py3-none-any.whl

opencode_swap/opencode_auth.py

@@ -0,0 +1,54 @@
+"""Whole-file read/validate/atomic-write of OpenCode's auth.json.
+
+Generic across providers — a Provider only interprets the one key it owns
+(see providers/base.py). This module never inspects provider-specific
+fields; it just guarantees a safe, atomic round-trip of the file OpenCode
+itself writes non-atomically and without a lock (verified:
+opencode/packages/core/src/fs-util.ts:110-114 truncate+write then a separate
+chmod, no temp file, no rename; opencode/packages/opencode/src/auth/index.ts
+:75-79 does an unlocked read-merge-write). opencode-swap holds itself to a
+higher bar: 0600 temp file in the same directory, then os.replace — the only
+publish point, so a crash mid-write never leaves auth.json truncated.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from opencode_swap.atomic import atomic_write_json
+from opencode_swap.exceptions import AuthFileError
+from opencode_swap.models import JsonObject
+
+
+def read_auth(path: Path) -> JsonObject:
+    """Read and parse auth.json. Raises AuthFileError if missing/malformed.
+
+    An absent file is a distinct, expected state (OpenCode with no accounts
+    configured yet) — callers that want to treat "no file" as "empty auth"
+    should catch AuthFileError and check path.exists() themselves; this
+    function never silently invents an empty dict, since a genuinely
+    unreadable file (permissions, corruption) must not look identical to
+    "nothing here yet."
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise AuthFileError(f"auth.json not found at {path}") from exc
+    except OSError as exc:
+        raise AuthFileError(f"could not read {path}: {exc}") from exc
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise AuthFileError(f"{path} is not valid JSON: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise AuthFileError(f"{path} does not contain a JSON object at the top level")
+
+    return data
+
+
+def atomic_write_auth(path: Path, data: JsonObject) -> None:
+    """Write auth.json atomically: 0600 temp file in the same dir, then rename."""
+    atomic_write_json(path, data)

opencode_swap/paths.py

@@ -0,0 +1,83 @@
+"""Path resolution for OpenCode's auth state and opencode-swap's own data.
+
+Mirrors OpenCode's own path resolution so opencode-swap reads and writes
+exactly the file OpenCode does. Verified from OpenCode source
+(``packages/core/src/global.ts``, via xdg-basedir) and cross-checked against
+opencode-balancer's independent reimplementation (``src/core/path.ts``):
+
+- Data dir: ``$XDG_DATA_HOME/opencode`` if ``XDG_DATA_HOME`` is set (and
+  absolute), else ``~/.local/share/opencode``. Identical on Linux and macOS —
+  OpenCode uses xdg-basedir defaults everywhere it runs on POSIX; there is no
+  macOS-specific data location.
+- Auth file: ``<data dir>/auth.json``.
+- ``OPENCODE_AUTH_CONTENT``, if set in the *OpenCode process's* environment,
+  makes ``Auth.all()`` return that JSON in-memory and ignore the file
+  entirely (``auth/index.ts:59-63``). We can only detect whether it is set in
+  *our own* process env — useful for ``doctor`` diagnostics, not for writing.
+- ``OPENCODE_CONFIG_DIR`` overrides OpenCode's *config* dir only, not the
+  data dir — it does not move auth.json (``global.ts:64``).
+- ``OPENCODE_TEST_HOME`` overrides OpenCode's notion of home (``global.ts:19``)
+  and is honored here too, so integration tests can point both OpenCode and
+  opencode-swap at the same fake home without touching the real one.
+
+opencode-swap's own data (registry, backups, fallback secrets) lives under
+``$XDG_DATA_HOME/opencode-swap`` using the same resolution — uniform across
+Linux and macOS since this is a new tool with no legacy layout to preserve.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+OPENCODE_DIRNAME = "opencode"
+OPENCODE_SWAP_DIRNAME = "opencode-swap"
+AUTH_FILENAME = "auth.json"
+
+
+def effective_home() -> Path:
+    """Return the home directory, honoring OPENCODE_TEST_HOME for test parity."""
+    test_home = os.environ.get("OPENCODE_TEST_HOME")
+    if test_home:
+        return Path(test_home)
+    return Path.home()
+
+
+def xdg_data_home() -> Path:
+    """Return XDG_DATA_HOME, falling back to ``<home>/.local/share``.
+
+    Per the XDG spec (and OpenCode's own xdg-basedir usage), an unset, empty,
+    or non-absolute XDG_DATA_HOME is ignored in favor of the default.
+    """
+    env = os.environ.get("XDG_DATA_HOME", "")
+    if env:
+        candidate = Path(os.path.expanduser(env))
+        if candidate.is_absolute():
+            return candidate
+    return effective_home() / ".local" / "share"
+
+
+def get_opencode_data_dir() -> Path:
+    """Return OpenCode's data directory (``$XDG_DATA_HOME/opencode``)."""
+    return xdg_data_home() / OPENCODE_DIRNAME
+
+
+def get_opencode_auth_path() -> Path:
+    """Return the path to OpenCode's auth.json."""
+    return get_opencode_data_dir() / AUTH_FILENAME
+
+
+def opencode_auth_content_override_active() -> bool:
+    """Return True if OPENCODE_AUTH_CONTENT is set in our own process env.
+
+    When set in the *OpenCode* process's environment, OpenCode ignores
+    auth.json entirely and reads this instead — a swap would have no effect.
+    We can only observe our own env, so this is a best-effort diagnostic
+    signal for ``doctor``, not a guarantee about OpenCode's runtime.
+    """
+    return bool(os.environ.get("OPENCODE_AUTH_CONTENT"))
+
+
+def get_data_root() -> Path:
+    """Return opencode-swap's own data root (``$XDG_DATA_HOME/opencode-swap``)."""
+    return xdg_data_home() / OPENCODE_SWAP_DIRNAME

opencode_swap/process_detection.py

@@ -0,0 +1,29 @@
+"""Best-effort detection of a running OpenCode process.
+
+OpenCode has no cooperative lock protocol opencode-swap can join (verified:
+Auth.set does an unlocked read-merge-write, auth/index.ts:75-79). The
+closest thing to a safety net is warning the caller that a swap is racing a
+live OpenCode process, which might be mid-refresh and write auth.json again
+right after opencode-swap does. Detection failure (no `pgrep`, permission
+denied, etc.) degrades to "not detected" rather than raising — this is
+advisory, not a security boundary.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+_TIMEOUT = 2.0
+
+
+def is_opencode_running() -> bool:
+    try:
+        result = subprocess.run(
+            ["pgrep", "-x", "opencode"],
+            capture_output=True,
+            timeout=_TIMEOUT,
+            check=False,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return False
+    return result.returncode == 0

opencode_swap/providers/__init__.py

@@ -0,0 +1,26 @@
+"""Provider registry: maps an OpenCode provider id to its Provider implementation."""
+
+from __future__ import annotations
+
+from opencode_swap.models import normalize_provider_id
+from opencode_swap.providers.api import ApiProvider
+from opencode_swap.providers.base import Provider
+from opencode_swap.providers.github_copilot import GitHubCopilotProvider
+from opencode_swap.providers.openai import OpenAiProvider
+from opencode_swap.providers.poe import PoeProvider
+from opencode_swap.providers.xai import XaiProvider
+from opencode_swap.providers.zai import ZaiProvider
+
+PROVIDERS: dict[str, Provider] = {
+    "openai": OpenAiProvider(),
+    "github-copilot": GitHubCopilotProvider(),
+    "poe": PoeProvider(),
+    "xai": XaiProvider(),
+    "zai-coding-plan": ZaiProvider(),
+}
+
+
+def get_provider(provider_id: str) -> Provider:
+    """Return specialized handling or canonical API-only fallback."""
+    provider_id = normalize_provider_id(provider_id)
+    return PROVIDERS.get(provider_id) or ApiProvider(provider_id)

opencode_swap/providers/api.py

@@ -0,0 +1,50 @@
+"""Generic static API-key provider supported by OpenCode's common path."""
+
+from __future__ import annotations
+
+from opencode_swap import usage
+from opencode_swap.exceptions import SchemaError
+from opencode_swap.models import AccountDesc, AuthRecord, JsonObject, Validity
+from opencode_swap.providers.common import credential_values, extract_raw, key_account_hint, published_raw, validate_api
+
+
+class ApiProvider:
+    usage_record_types: frozenset[str] = frozenset()  # no known usage endpoint for an arbitrary API provider
+
+    def __init__(self, provider_id: str):
+        self.id = provider_id
+
+    def extract(self, auth: JsonObject) -> AuthRecord | None:
+        raw = extract_raw(auth, self.id)
+        if raw is None:
+            return None
+        if raw.get("type") != "api":
+            raise SchemaError(f"{self.id} auth type is not supported by opencode-swap")
+        return validate_api(raw, self.id)
+
+    def splice(self, auth: JsonObject, record: AuthRecord) -> JsonObject:
+        if record.type != "api":
+            raise SchemaError(f"{self.id} auth type is not supported by opencode-swap")
+        return {**auth, self.id: published_raw(record.raw)}
+
+    def identity(self, record: AuthRecord) -> str:
+        key = record.raw.get("key")
+        return f"api-key\0{key if isinstance(key, str) else ''}"
+
+    def identity_is_stable(self, record: AuthRecord) -> bool:
+        return True
+
+    def credential_values(self, record: AuthRecord) -> set[str]:
+        return credential_values(record)
+
+    def describe(self, record: AuthRecord) -> AccountDesc:
+        return AccountDesc(type="api", email=None, account_id=key_account_hint(record), expires=None)
+
+    def validate(self, record: AuthRecord) -> Validity:
+        return Validity.OK if record.type == "api" else Validity.INVALID
+
+    def refresh(self, record: AuthRecord) -> AuthRecord | None:
+        return None  # API keys don't expire/rotate; nothing to refresh
+
+    def fetch_usage(self, record: AuthRecord) -> usage.UsageSnapshot | None:
+        return None  # no usage endpoint for an arbitrary API provider (usage_record_types is empty)

opencode_swap/providers/base.py

@@ -0,0 +1,91 @@
+"""The Provider seam: the only part of opencode-swap that varies per OpenCode
+provider/account type.
+
+auth.json's whole-file handling (read/validate/atomic-write) is generic and
+lives in opencode_auth.py. A Provider owns only what's provider-specific:
+which key(s) it occupies in auth.json, and how to read identity/validity out
+of its record. Adding a second provider means adding a second Provider
+implementation — no changes to the switch/store/lock machinery.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from opencode_swap import usage
+from opencode_swap.models import AccountDesc, AuthRecord, JsonObject, Validity
+
+
+class Provider(Protocol):
+    id: str
+
+    usage_record_types: frozenset[str]
+    """Record types (``"api"``, ``"oauth"``, ...) this provider can look up
+    live usage for via ``fetch_usage``. Empty (the default for every provider
+    without a known usage endpoint) tells ``Switcher.fetch_usage`` to skip all
+    lock/refresh work and report "not applicable" rather than "unavailable"."""
+
+    def extract(self, auth: JsonObject) -> AuthRecord | None:
+        """Pull this provider's entry out of a parsed auth.json.
+
+        Returns None if the provider has no entry. Raises SchemaError if an
+        entry exists but doesn't match a known shape (fail-safe: never guess).
+        """
+        ...
+
+    def splice(self, auth: JsonObject, record: AuthRecord) -> JsonObject:
+        """Return a new auth.json dict with this provider's entry replaced.
+
+        Does not mutate ``auth``; all other providers' keys are preserved.
+
+        Implementations must route the record through
+        ``providers.common.published_raw`` -- this is the only path by which
+        opencode-swap content reaches OpenCode, so it is where read-side
+        tolerance has to stop. ``test_every_provider_splice_publishes_an
+        _integer_expiry`` enforces this for every registered provider.
+        """
+        ...
+
+    def identity(self, record: AuthRecord) -> str:
+        """A stable string identifying which real-world account this record
+        belongs to, independent of token rotation (e.g. account id, or the
+        refresh token itself as a fallback)."""
+        ...
+
+    def identity_is_stable(self, record: AuthRecord) -> bool:
+        """Whether identity remains unchanged when OpenCode refreshes it."""
+        ...
+
+    def credential_values(self, record: AuthRecord) -> set[str]:
+        """Secret strings which must never enter metadata or output."""
+        ...
+
+    def describe(self, record: AuthRecord) -> AccountDesc:
+        """Human-facing, secret-free description of the account."""
+        ...
+
+    def validate(self, record: AuthRecord) -> Validity:
+        """Whether the record looks usable, expired, or malformed."""
+        ...
+
+    def refresh(self, record: AuthRecord) -> AuthRecord | None:
+        """Rotated-token copy of `record` from a standalone OAuth refresh.
+
+        Returns None if this provider/record type has no standalone refresh
+        (the default for every provider but OpenAI oauth records). Raises
+        RefreshError if a refresh was attempted and the grant was rejected
+        or the request otherwise failed -- callers must not treat that the
+        same as "no refresh available".
+        """
+        ...
+
+    def fetch_usage(self, record: AuthRecord) -> usage.UsageSnapshot | None:
+        """Live usage/quota for `record`, fetched over the network.
+
+        Only called for record types in ``usage_record_types``. Returns None
+        when this particular record can't be looked up (missing field, secret
+        store out of sync) -- distinct from ``UsageSnapshot(available=False)``
+        ("looked it up, the request failed"). Never raises: network and shape
+        failures come back as ``available=False``.
+        """
+        ...

opencode_swap/providers/common.py

@@ -0,0 +1,144 @@
+"""Shared validation for OpenCode's canonical auth record shapes."""
+
+from __future__ import annotations
+
+import math
+from typing import TypeGuard
+
+from opencode_swap.exceptions import SchemaError
+from opencode_swap.models import AuthRecord, JsonObject
+
+
+def require_str(raw: JsonObject, field: str, provider_id: str, entry_type: str) -> str:
+    value = raw.get(field)
+    if not isinstance(value, str) or not value:
+        raise SchemaError(f"{provider_id} {entry_type} entry missing/invalid field {field!r}")
+    return value
+
+
+def optional_str(raw: JsonObject, field: str, provider_id: str, entry_type: str) -> str | None:
+    if field not in raw:
+        return None
+    value = raw[field]
+    if not isinstance(value, str):
+        raise SchemaError(f"{provider_id} {entry_type} entry has invalid field {field!r}")
+    return value
+
+
+def is_json_number(value: object) -> TypeGuard[int | float]:
+    """Whether value survives OpenCode's JavaScript JSON-number boundary."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return False
+    try:
+        return math.isfinite(float(value))
+    except OverflowError:
+        return False
+
+
+def require_expiry(raw: JsonObject, provider_id: str) -> int | float:
+    expires = raw.get("expires")
+    if not is_json_number(expires) or expires < 0:
+        raise SchemaError(f"{provider_id} oauth entry has invalid 'expires'")
+    return expires
+
+
+def published_raw(raw: JsonObject) -> JsonObject:
+    """Copy of `raw` safe to publish into OpenCode's auth.json.
+
+    Every `Provider.splice` routes its record through this -- splice is the
+    only path by which opencode-swap content reaches auth.json, and the one
+    place where our tolerance for what we *read* must stop.
+
+    OpenCode types `expires` as `NonNegativeInt` (auth/index.ts's Oauth
+    class, via packages/schema/src/schema.ts's `Schema.Int`), and `Auth.all()`
+    decodes with `Record.filterMap`, which drops entries that fail to decode
+    instead of reporting them. Publishing a fractional `expires` therefore
+    makes the provider vanish from OpenCode entirely, with the first symptom
+    appearing far away as an `auth.type` access on an undefined record
+    (codex.ts:331).
+
+    Deliberately not done in `extract`: that is a validator on records we
+    did not write, and normalizing there would also rewrite the live record
+    captured by `backup.write_unclaimed`, whose entire purpose is to
+    preserve a foreign login exactly as found. Reads stay verbatim; only
+    what we hand back to OpenCode is constrained. Records written by older
+    versions (see oauth_refresh.py) are healed on the next switch as a
+    consequence.
+
+    Scoped to `type == "oauth"`: that is the only OpenCode auth variant
+    whose schema types `expires` as `NonNegativeInt` at all (Api and
+    WellKnown carry no `expires` field in OpenCode's schema). Truncating an
+    `expires`-named key on any other type -- or any other unknown field --
+    would silently mutate data that isn't ours to touch and OpenCode was
+    never going to reject in the first place.
+    """
+    if raw.get("type") != "oauth":
+        return dict(raw)
+    expires = raw.get("expires")
+    if not is_json_number(expires) or isinstance(expires, int):
+        return dict(raw)  # absent, non-numeric (rejected elsewhere), or already integral
+    return {**raw, "expires": int(expires)}
+
+
+def extract_raw(auth: JsonObject, provider_id: str) -> JsonObject | None:
+    raw = auth.get(provider_id)
+    if raw is None:
+        return None
+    if not isinstance(raw, dict) or "type" not in raw:
+        raise SchemaError(f"{provider_id} entry is not a recognizable auth record")
+    return raw
+
+
+def validate_api(raw: JsonObject, provider_id: str) -> AuthRecord:
+    require_str(raw, "key", provider_id, "api")
+    metadata = raw.get("metadata")
+    if "metadata" in raw and (
+        not isinstance(metadata, dict) or any(not isinstance(key, str) or not isinstance(value, str) for key, value in metadata.items())
+    ):
+        raise SchemaError(f"{provider_id} api entry has invalid field 'metadata'")
+    return AuthRecord(type="api", raw=dict(raw))
+
+
+def validate_oauth(raw: JsonObject, provider_id: str) -> AuthRecord:
+    require_str(raw, "refresh", provider_id, "oauth")
+    require_str(raw, "access", provider_id, "oauth")
+    require_expiry(raw, provider_id)
+    optional_str(raw, "accountId", provider_id, "oauth")
+    optional_str(raw, "enterpriseUrl", provider_id, "oauth")
+    return AuthRecord(type="oauth", raw=dict(raw))
+
+
+_MIN_KEY_LENGTH_FOR_HINT = 20  # leaves >=16 characters hidden; see key_account_hint
+
+
+def credential_values(record: AuthRecord) -> set[str]:
+    return {value for field in ("refresh", "access", "key", "token") if isinstance((value := record.raw.get(field)), str) and value}
+
+
+def key_account_hint(record: AuthRecord) -> str | None:
+    """`"...{last 4 chars}"` of a static API key -- a stable identifier for
+    *which* key a saved account holds, shown in the account-id column in
+    place of an account id for static-key providers (which have none). This
+    is the same head/tail form providers show on their own API-key
+    dashboards, so a row can be matched against one; the literal `...`
+    carries no information about the key itself, it only marks the value as
+    a deliberate partial (matching how `cli._redact_account_id` marks a
+    truncated account id the same way).
+
+    Only ``record.type == "api"`` is considered: an oauth record's raw dict
+    can carry an unrelated/unverified `key` field (schema validation doesn't
+    forbid extra fields), and that is not the credential this hint is about.
+
+    Returns None below `_MIN_KEY_LENGTH_FOR_HINT`: revealing 4 characters of
+    a short, possibly low-entropy value (a hand-picked token, not a real API
+    key) can materially narrow it -- e.g. an 8-character key exposes half of
+    it. The threshold instead guarantees at least 16 characters stay hidden,
+    which no realistic API key format (all comfortably 20+ chars) is close
+    to tripping.
+    """
+    if record.type != "api":
+        return None
+    key = record.raw.get("key")
+    if not isinstance(key, str) or len(key) < _MIN_KEY_LENGTH_FOR_HINT:
+        return None
+    return f"...{key[-4:]}"

opencode_swap/providers/github_copilot.py

@@ -0,0 +1,46 @@
+"""GitHub Copilot auth as implemented by OpenCode's built-in plugin."""
+
+from __future__ import annotations
+
+from opencode_swap.exceptions import SchemaError
+from opencode_swap.models import AccountDesc, AuthRecord, JsonObject, Validity
+from opencode_swap.providers.common import credential_values, extract_raw, published_raw, validate_oauth
+
+
+class GitHubCopilotProvider:
+    id = "github-copilot"
+    usage_record_types: frozenset[str] = frozenset()  # no known usage endpoint
+
+    def extract(self, auth: JsonObject) -> AuthRecord | None:
+        raw = extract_raw(auth, self.id)
+        if raw is None:
+            return None
+        if raw.get("type") != "oauth":
+            raise SchemaError("github-copilot auth type is not supported by opencode-swap")
+        return validate_oauth(raw, self.id)
+
+    def splice(self, auth: JsonObject, record: AuthRecord) -> JsonObject:
+        return {**auth, self.id: published_raw(record.raw)}
+
+    def identity(self, record: AuthRecord) -> str:
+        refresh = record.raw.get("refresh")
+        enterprise = record.raw.get("enterpriseUrl")
+        return f"copilot\0{enterprise if isinstance(enterprise, str) else ''}\0{refresh if isinstance(refresh, str) else ''}"
+
+    def identity_is_stable(self, record: AuthRecord) -> bool:
+        return True
+
+    def credential_values(self, record: AuthRecord) -> set[str]:
+        return credential_values(record)
+
+    def describe(self, record: AuthRecord) -> AccountDesc:
+        return AccountDesc(type="oauth", email=None, account_id=None, expires=None)
+
+    def validate(self, record: AuthRecord) -> Validity:
+        return Validity.OK if record.type == "oauth" else Validity.INVALID
+
+    def refresh(self, record: AuthRecord) -> AuthRecord | None:
+        return None  # no verified standalone refresh flow for this provider yet
+
+    def fetch_usage(self, record: AuthRecord) -> None:
+        return None  # unreachable: usage_record_types is empty