claude-multiacc 1.0.13 → 1.0.15

package/lib/common.sh

@@ -18,20 +18,33 @@ DEFAULT_SERVER_REPO="/root/claude-multiacc"
 
 LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd -P)"
 
+# INSTANCE-SCOPED POOLS: <PROVIDER>_ACCOUNTS_ROOT relocates the whole pool, so
+# several app-robot instances on one machine/user keep completely isolated account
+# sets. The older <PROVIDER>_ACCOUNTS_DIR spelling still works (it is what the test
+# suite and existing runner envs set) — _ROOT wins when both are present.
 if [ "$MULTIACC_PROVIDER" = "codex" ]; then
-  ACC_ROOT="${CODEX_ACCOUNTS_DIR:-$HOME/.codex-accounts}"
+  ACC_ROOT="${CODEX_ACCOUNTS_ROOT:-${CODEX_ACCOUNTS_DIR:-$HOME/.codex-accounts}}"
+  DEFAULT_ACC_ROOT="$HOME/.codex-accounts"
   DEFAULT_SERVER_ROOT="/root/.codex-accounts"
   USAGE_URL="${CODEX_MULTIACC_USAGE_URL:-https://chatgpt.com/backend-api/codex/usage}"
   AUDIT_PY="$LIB_DIR/codex_audit.py"
   PROVIDER_CLI="codex-accounts"
+  SYNC_TARGET_ENV="${CODEX_MULTIACC_SYNC_TARGET:-${MULTIACC_SYNC_TARGET:-}}"
+  SYNC_ROOT_ENV="${CODEX_MULTIACC_SYNC_ROOT:-${MULTIACC_SYNC_ROOT:-}}"
+  SYNC_REPO_ENV="${CODEX_MULTIACC_SYNC_REPO:-${MULTIACC_SYNC_REPO:-}}"
 else
-  ACC_ROOT="${CLAUDE_ACCOUNTS_DIR:-$HOME/.claude-accounts}"
+  ACC_ROOT="${CLAUDE_ACCOUNTS_ROOT:-${CLAUDE_ACCOUNTS_DIR:-$HOME/.claude-accounts}}"
+  DEFAULT_ACC_ROOT="$HOME/.claude-accounts"
   DEFAULT_SERVER_ROOT="/root/.claude-accounts"
   USAGE_URL="${CLAUDE_MULTIACC_USAGE_URL:-https://api.anthropic.com/api/oauth/usage}"
   AUDIT_PY="$LIB_DIR/audit.py"
   PROVIDER_CLI="claude-accounts"
+  SYNC_TARGET_ENV="${CLAUDE_MULTIACC_SYNC_TARGET:-${MULTIACC_SYNC_TARGET:-}}"
+  SYNC_ROOT_ENV="${CLAUDE_MULTIACC_SYNC_ROOT:-${MULTIACC_SYNC_ROOT:-}}"
+  SYNC_REPO_ENV="${CLAUDE_MULTIACC_SYNC_REPO:-${MULTIACC_SYNC_REPO:-}}"
 fi
 MANIFEST="$ACC_ROOT/accounts.json"
+REPORT_PY="$LIB_DIR/report.py"
 
 ts_utc() { date -u +%Y-%m-%dT%H:%M:%SZ; }
 epoch_now() { date +%s; }
@@ -159,6 +172,253 @@ valid_ssh_target() {
 
 acct_dir() { printf '%s/%s\n' "$ACC_ROOT" "$1"; }
 
+# ---- sync target resolution ----------------------------------------------------
+# Where this pool pushes, in precedence order:
+#   1. <PROVIDER>_MULTIACC_SYNC_TARGET / MULTIACC_SYNC_TARGET (env — the runner daemon
+#      sets these per instance, without rewriting a manifest it does not own)
+#   2. the manifest's server/server_root/server_repo (what install.sh --server wrote)
+#   3. DEFAULT_SERVER — the historical default, unchanged for existing installs.
+# The value 'none' (also 'local'/'off'/'disabled'/empty) selects LOCAL-ONLY mode: the
+# pool has no ssh target because something else (the panel/runner daemon) distributes
+# it. That is a supported mode, not a misconfiguration.
+sync_target_is_local() {
+  case "$(printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]')" in
+    ''|none|local|off|disabled) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+sync_target() {
+  if [ -n "${SYNC_TARGET_ENV:-}" ]; then printf '%s\n' "$SYNC_TARGET_ENV"
+  else manifest_get server "$DEFAULT_SERVER"; fi
+}
+sync_target_root() {
+  if [ -n "${SYNC_ROOT_ENV:-}" ]; then printf '%s\n' "$SYNC_ROOT_ENV"
+  else manifest_get server_root "$DEFAULT_SERVER_ROOT"; fi
+}
+sync_target_repo() {
+  if [ -n "${SYNC_REPO_ENV:-}" ]; then printf '%s\n' "$SYNC_REPO_ENV"
+  else manifest_get server_repo "$DEFAULT_SERVER_REPO"; fi
+}
+
+# The machine-readable pool document shared by `list|status|limits --json`
+# (lib/report.py). Stdout is JSON and nothing else — every human line a --json run
+# would otherwise print goes to stderr or a log.
+emit_report_json() { # emit_report_json <list|status|limits>
+  local target mode
+  target="$(sync_target)"
+  if sync_target_is_local "$target"; then mode=local; target=""; else mode=server; fi
+  MULTIACC_REPORT_SYNC_TARGET="$target" \
+  MULTIACC_REPORT_SYNC_ROOT="$(sync_target_root)" \
+  MULTIACC_REPORT_SYNC_REPO="$(sync_target_repo)" \
+  MULTIACC_REPORT_SYNC_MODE="$mode" \
+  "$PYBIN" "$REPORT_PY" "$ACC_ROOT" "$MULTIACC_PROVIDER" "$(machine_kind)" "${1:-list}" \
+    || die "could not build the JSON report from $ACC_ROOT"
+}
+
+# True when every manifest account has a well-formed id and an email. A corrupt
+# manifest must never be pushed (it would blank the target pools) and must never be
+# reported as a clean local sync either.
+manifest_well_formed() {
+  "$PYBIN" - "$MANIFEST" <<'PYEOF' 2>/dev/null
+import json, re, sys
+doc = json.load(open(sys.argv[1]))
+accounts = doc.get('accounts')
+if not isinstance(accounts, list):
+    sys.exit(1)
+for a in accounts:
+    if not isinstance(a, dict) or not re.fullmatch(r'acct-\d{2}', str(a.get('id', ''))) \
+       or not str(a.get('email', '')).strip():
+        sys.exit(1)
+PYEOF
+}
+
+# The housekeeping a pool does on ITSELF: seed any missing account dirs and put the
+# credential files back to 0600. It is what a sync target runs after a push, and all
+# a local-only pool has to do (nothing is pushed anywhere there).
+local_pool_fixup() {
+  local id d
+  for id in $(account_ids); do
+    d="$ACC_ROOT/$id"
+    seed_account_dir "$d"
+    if [ "$MULTIACC_PROVIDER" = "codex" ]; then
+      [ -f "$d/auth.json" ] && chmod 600 "$d/auth.json" 2>/dev/null
+    else
+      [ -f "$d/server.token" ] && chmod 600 "$d/server.token" 2>/dev/null
+      [ -f "$d/.credentials.json" ] && chmod 600 "$d/.credentials.json" 2>/dev/null
+    fi
+  done
+  return 0
+}
+
+CREDENTIAL_PY="$LIB_DIR/credential.py"
+
+# EXIT-trap body for the limits refresh lock — a function for the same reason as
+# import_cred_cleanup: the lock path contains the pool root.
+LIMITS_LOCK=""
+limits_lock_release() {
+  [ -n "${LIMITS_LOCK:-}" ] && rm -rf "$LIMITS_LOCK" 2>/dev/null
+  LIMITS_LOCK=""
+  return 0
+}
+
+# EXIT-trap body for cmd_import_credential. A function, not an interpolated string:
+# the staged blob lives under the pool root, and a root containing a quote would
+# otherwise inject shell code into the trap program.
+IMPORT_STAGE=""
+import_cred_cleanup() {
+  [ -n "${IMPORT_STAGE:-}" ] && rm -f "$IMPORT_STAGE" 2>/dev/null
+  IMPORT_STAGE=""
+  mutate_unlock 2>/dev/null || true
+  return 0
+}
+
+cmd_export_credential() {
+  # Emit a self-contained transfer blob for ONE account. Read-only on this pool:
+  # nothing is written, refreshed or re-minted, so exporting a live production
+  # account cannot disturb it. lib/credential.py owns the format AND the
+  # portability rule (it exits 3 on a machine-local credential); this wrapper only
+  # decides where the blob lands and propagates that exit code verbatim, because a
+  # daemon branches on it.
+  require_manifest
+  local id="" out="" identity=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --out) out="${2:?--out requires a path}"; shift 2 ;;
+      --identity-only) identity=1; shift ;;
+      --*) die "unknown option: $1" ;;
+      *) if [ -z "$id" ]; then id="$1"; shift; else die "unexpected argument: $1"; fi ;;
+    esac
+  done
+  [ -n "$id" ] || die "usage: $PROVIDER_CLI export-credential <acct-NN> [--out PATH] [--identity-only]"
+  valid_acct_id "$id" || die "not a valid account id: $id"
+  set -- export "$ACC_ROOT" "$MULTIACC_PROVIDER" "$id"
+  [ "$identity" = "1" ] && set -- "$@" --identity-only
+  # --out is handled INSIDE credential.py: it creates a unique 0600 file next to the
+  # target and renames it into place, so the blob is never briefly world-readable and
+  # a planted symlink at the target is replaced rather than written through — neither
+  # of which a shell redirect can promise.
+  [ -n "$out" ] && set -- "$@" --out "$out"
+  local rc=0
+  "$PYBIN" "$CREDENTIAL_PY" "$@" || rc=$?
+  [ "$rc" = "0" ] || return "$rc"
+  log_to ops.log "export-credential $id -> ${out:-stdout} identity_only=$identity"
+  if [ -n "$out" ]; then
+    if [ "$identity" = "1" ]; then
+      echo "Wrote $out (identity only — no credential material)."
+    else
+      echo "Wrote $out (carries a live credential: keep it secret, delete it once imported)."
+    fi
+  fi
+  return 0
+}
+
+cmd_import_credential() {
+  # Install a transfer blob into this pool, non-interactively. Idempotent by EMAIL:
+  # re-importing an account that is already here refreshes its credential in place
+  # instead of creating a second entry, so a daemon can push the same pool to a
+  # machine repeatedly. The secret never passes through a shell variable or argv —
+  # it is staged 0600 and installed by lib/credential.py.
+  require_manifest
+  local id="" in_file="-" home="" no_sync=0 force=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --in|--file) in_file="${2:?--in requires a path}"; shift 2 ;;
+      --id) id="${2:?--id requires acct-NN}"; shift 2 ;;
+      --home) home="${2:?--home requires mac|server}"; shift 2 ;;
+      --no-sync) no_sync=1; shift ;;
+      --force) force=1; shift ;;
+      --*) die "unknown option: $1" ;;
+      *) if [ -z "$id" ]; then id="$1"; shift; else die "unexpected argument: $1"; fi ;;
+    esac
+  done
+  if [ -n "$id" ]; then valid_acct_id "$id" || die "not a valid account id: $id"; fi
+  if [ "$in_file" = "-" ] && [ -t 0 ]; then
+    die "import-credential reads the blob on stdin — pipe it in, or pass --in PATH"
+  fi
+  mkdir -p "$ACC_ROOT/tmp" 2>/dev/null || true
+  # mktemp (0600, O_EXCL, unpredictable name), not "$$": the staged file holds live
+  # credential material, and a predictable path could be pre-planted as a symlink and
+  # written through. The cleanup trap is armed BEFORE anything is written, so an
+  # interrupt during staging cannot leave the blob behind either.
+  local stage rc=0
+  stage="$(mktemp "$ACC_ROOT/tmp/import-cred.XXXXXX")" \
+    || die "could not create a staging file under $ACC_ROOT/tmp"
+  IMPORT_STAGE="$stage"
+  trap import_cred_cleanup EXIT
+  if [ "$in_file" = "-" ]; then
+    cat > "$stage" || rc=$?
+  else
+    [ -f "$in_file" ] || { import_cred_cleanup; trap - EXIT; die "credential blob not found: $in_file"; }
+    cat "$in_file" > "$stage" || rc=$?
+  fi
+  [ "$rc" = "0" ] || { import_cred_cleanup; trap - EXIT; die "could not read the credential blob"; }
+  chmod 600 "$stage" 2>/dev/null || true
+
+  local meta cclass bid bemail bhome badded btype us
+  # 0x1F, not a tab: bash collapses runs of IFS *whitespace*, so a blob with an empty
+  # `home` would shift added_at into it and corrupt the manifest entry. credential.py
+  # refuses any control character in the metadata, so the separator is unambiguous.
+  us="$(printf '\037')"
+  meta="$("$PYBIN" "$CREDENTIAL_PY" inspect "$MULTIACC_PROVIDER" "$stage")" || rc=$?
+  if [ "$rc" != "0" ]; then
+    import_cred_cleanup
+    trap - EXIT
+    return "$rc"
+  fi
+  IFS="$us" read -r cclass bid bemail bhome badded btype <<EOF
+$meta
+EOF
+  [ -n "$home" ] || home="$bhome"
+  [ -n "$home" ] || home="$(machine_kind)"
+
+  mutate_lock || { import_cred_cleanup; trap - EXIT; die "could not acquire the account lock (another op is stuck?) — try again"; }
+  fail_locked() { import_cred_cleanup; trap - EXIT; die "$@"; }
+  local owner target_id existing
+  owner="$(email_owner "$bemail")"
+  target_id="$id"
+  if [ -z "$target_id" ]; then
+    if [ -n "$owner" ]; then
+      target_id="$owner"          # this email already lives here: refresh it in place
+    elif [ -n "$bid" ] && [ ! -e "$ACC_ROOT/$bid" ] && ! account_ids | grep -qx "$bid"; then
+      target_id="$bid"            # the source's id is free here: keep ids aligned
+    else
+      target_id="$(next_id)"
+    fi
+  fi
+  if [ -n "$owner" ] && [ "$owner" != "$target_id" ] && [ "$force" != "1" ]; then
+    fail_locked "$bemail is already registered as $owner — import into it ('$PROVIDER_CLI import-credential $owner') or pass --force"
+  fi
+  existing="$(manifest_email_of "$target_id")"
+  if [ -n "$existing" ] && [ "$existing" != "$bemail" ] && [ "$force" != "1" ]; then
+    fail_locked "$target_id is $existing on this machine, not $bemail — pick another id or pass --force"
+  fi
+  # An adopted account dir is a symlink (usually to ~/.claude). Writing a credential
+  # through it would land outside the pool — the very boundary account ids are
+  # validated to protect — so this is refused outright, --force included: --force
+  # settles identity conflicts, it does not authorize writing outside the pool.
+  if [ -L "$ACC_ROOT/$target_id" ]; then
+    fail_locked "$target_id is adopted (a symlink to $(readlink "$ACC_ROOT/$target_id")) — a credential must never be written through it; remove the account first ('$PROVIDER_CLI remove $target_id'), or import under a different id"
+  fi
+  local d="$ACC_ROOT/$target_id"
+  seed_account_dir "$d"
+  "$PYBIN" "$CREDENTIAL_PY" install "$MULTIACC_PROVIDER" "$stage" "$d" >/dev/null \
+    || fail_locked "could not install the credential into $d — nothing registered"
+  manifest_add_account "$target_id" "$bemail" "$home" "$badded" \
+    || fail_locked "manifest update failed — $target_id was seeded but NOT registered (re-run import-credential)"
+  # Fresh material landed: whatever parked this account before no longer applies.
+  [ "$cclass" = "portable" ] && clear_auth_markers "$d"
+  import_cred_cleanup
+  trap - EXIT
+  log_to ops.log "import-credential $target_id $bemail class=$cclass type=$btype home=$home"
+  if [ "$cclass" = "portable" ]; then
+    echo "Imported $target_id ($bemail, home=$home) with a portable $btype credential."
+  else
+    echo "Registered $target_id ($bemail, home=$home) — identity only, no credential."
+    echo "It needs one interactive sign-in on a machine that will run it: $PROVIDER_CLI login $target_id"
+  fi
+  [ "$no_sync" = "1" ] || auto_sync
+}
+
 has_local_auth() { # $1 = acct dir
   if [ "$MULTIACC_PROVIDER" = "codex" ]; then
     [ -s "$1/auth.json" ]

package/lib/credential.py

@@ -0,0 +1,336 @@
+"""Portable-credential transfer — the blob format `export-credential` writes and
+`import-credential` installs, for both providers, in ONE place so the two ends can
+never drift apart.
+
+Run (all paths absolute; the blob never passes through argv):
+  python3 lib/credential.py export  <acc-root> <provider> <acct-NN> [--identity-only]
+                                    [--out PATH]
+      writes the blob to stdout, or to PATH (created 0600 and renamed into place, so
+      a refusal leaves nothing behind and no other process ever sees it wider)
+  python3 lib/credential.py inspect <provider> <blob-file>
+      validates a blob and prints one 0x1F-separated record:
+      class, id, email, home, added_at, cred_type. The separator is deliberately NOT
+      whitespace: bash collapses runs of IFS whitespace, which would silently shift
+      an empty field (a blob with no `home`) into the next one.
+  python3 lib/credential.py install <provider> <blob-file> <dest-dir>
+      writes the credential material into <dest-dir> (0600, atomic); no-op for an
+      identity-only blob. Prints the file it wrote (or nothing).
+
+Exit codes are the contract a daemon branches on:
+  0  done
+  2  usage / unknown account / malformed blob
+  3  the credential is MACHINE-LOCAL — copying it would break both machines
+  4  the account has no credential material here
+  5  credential material is present but unusable (corrupt / wrong shape)
+
+WHAT IS PORTABLE
+  claude: `server.token` — a subscription setup-token (`sk-ant-oat…`, ~1y life,
+          inference-only). It authenticates from any machine and is exactly what the
+          existing sync already mirrors to the server, so distributing it is safe.
+  claude: `.credentials.json` — NOT portable. Its refresh token rotates on every
+          refresh; a second machine refreshing the same grant strands the first.
+  codex:  `auth.json` — NOT portable, same rotating-refresh-token reason. Codex has
+          no portable credential type at all: each machine signs in once with the
+          device-code flow (`codex-accounts login <id>`, works over SSH).
+"""
+
+import json
+import os
+import re
+import socket
+import sys
+import tempfile
+import time
+
+FORMAT = 'claude-multiacc/credential'
+VERSION = 1
+VALID_ID = re.compile(r'acct-\d{2}')
+# Metadata crosses into a shell (the CLIs read it as a record) and into the manifest.
+# A control character there could truncate or shift a record, so it is refused at the
+# boundary rather than escaped downstream.
+CONTROL_CHARS = re.compile(r'[\x00-\x1f\x7f]')
+FIELD_SEP = '\x1f'
+# A subscription setup-token, and nothing else — API keys are refused pool-wide
+# (bin/claude-accounts: valid_subscription_token). Kept in sync with that check.
+SETUP_TOKEN = re.compile(r'sk-ant-oat\d{2}-[A-Za-z0-9_-]{40,}\Z')
+
+
+def die(msg, code=2):
+    sys.stderr.write(msg.rstrip('\n') + '\n')
+    sys.exit(code)
+
+
+def _load(path):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except Exception as e:
+        die(f'not readable JSON: {path} ({str(e)[:120]})')
+
+
+def _clean(value, what):
+    """Metadata that is safe to hand to a shell and to write into the manifest."""
+    text = '' if value is None else str(value)
+    if CONTROL_CHARS.search(text):
+        die(f'{what} contains a control character — refusing to transfer it')
+    return text
+
+
+def _write_secure(path, data, nofollow_dir=False):
+    """Create <path> with the content, never following a symlink and never widening
+    permissions: a unique 0600 temp file in the same directory (mkstemp is O_EXCL),
+    then an atomic rename. os.replace does not follow a symlink at the destination,
+    so a planted link is replaced rather than written through.
+
+    nofollow_dir additionally pins the DIRECTORY: it is opened O_NOFOLLOW|O_DIRECTORY
+    once and every later step runs relative to that descriptor, so swapping the
+    directory for a symlink after the check cannot redirect the write. Used for
+    credential material landing in a pool; a caller-named --out path does not need it
+    (the caller chose the path) and may live on a filesystem without dir_fd support."""
+    d = os.path.dirname(os.path.abspath(path)) or '.'
+    base = os.path.basename(path)
+    if not os.path.isdir(d):
+        die(f'destination directory does not exist: {d}')
+    dir_fd = None
+    if nofollow_dir:
+        # Fail CLOSED: if the platform cannot pin the directory, refuse rather than
+        # quietly downgrading to the path-based write this argument exists to avoid.
+        # NB: the rename primitive is os.rename, not os.replace — on POSIX both are
+        # renameat(2) (rename already replaces atomically), but CPython registers only
+        # os.rename in supports_dir_fd on macOS, and demanding os.replace would make
+        # this fail closed on the very platform the pool runs on.
+        missing = [n for n in ('O_DIRECTORY', 'O_NOFOLLOW') if not hasattr(os, n)]
+        if missing or os.open not in os.supports_dir_fd \
+                or os.rename not in os.supports_dir_fd \
+                or os.unlink not in os.supports_dir_fd:
+            die(f'this platform cannot write a credential safely (no directory-fd '
+                f'support{": missing " + ", ".join(missing) if missing else ""}) — '
+                f'refusing to install it', 5)
+        try:
+            dir_fd = os.open(d, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+        except OSError as e:
+            die(f'could not open {d} safely ({str(e)[:120]})')
+    tmp = None
+    try:
+        if dir_fd is not None:
+            tmp = f'.cred.{os.getpid()}.{os.urandom(6).hex()}'
+            fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                         0o600, dir_fd=dir_fd)
+            os.fchmod(fd, 0o600)
+            with os.fdopen(fd, 'w') as f:
+                f.write(data)
+            os.rename(tmp, base, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
+            tmp = None
+        else:
+            fd, tmp = tempfile.mkstemp(prefix='.cred.', dir=d)
+            os.fchmod(fd, 0o600)
+            with os.fdopen(fd, 'w') as f:
+                f.write(data)
+            os.replace(tmp, path)
+            tmp = None
+    except Exception as e:
+        # Any exception, not just OSError: an interrupt or an unexpected TypeError
+        # must not leave a file holding live credential material behind.
+        die(f'could not write {path} ({str(e)[:120]})')
+    finally:
+        if tmp:
+            try:
+                if dir_fd is not None:
+                    os.unlink(tmp, dir_fd=dir_fd)
+                else:
+                    os.unlink(tmp)
+            except OSError:
+                pass
+        if dir_fd is not None:
+            os.close(dir_fd)
+
+
+def _manifest_account(root, aid):
+    doc = _load(os.path.join(root, 'accounts.json'))
+    if not isinstance(doc, dict):
+        die(f'manifest is not a JSON object: {os.path.join(root, "accounts.json")}')
+    for a in doc.get('accounts', []):
+        if isinstance(a, dict) and str(a.get('id', '')) == aid:
+            return a
+    return None
+
+
+def cmd_export(argv):
+    if len(argv) < 3:
+        die('usage: credential.py export <acc-root> <provider> <acct-NN> '
+            '[--identity-only] [--out PATH]')
+    root, provider, aid = argv[0], argv[1], argv[2]
+    rest = list(argv[3:])
+    identity_only = '--identity-only' in rest
+    out_path = None
+    if '--out' in rest:
+        i = rest.index('--out')
+        if i + 1 >= len(rest):
+            die('--out requires a path')
+        out_path = rest[i + 1]
+
+    def emit(blob):
+        text = json.dumps(blob, indent=2) + '\n'
+        if out_path:
+            _write_secure(out_path, text)
+        else:
+            sys.stdout.write(text)
+
+    if not VALID_ID.fullmatch(aid):
+        die(f'not a valid account id: {aid}')
+    acct = _manifest_account(root, aid)
+    if acct is None:
+        die(f'{aid} is not registered in {os.path.join(root, "accounts.json")}')
+    d = os.path.join(root, aid)
+    blob = {
+        'format': FORMAT,
+        'version': VERSION,
+        'provider': provider,
+        'class': 'identity',
+        'account': {
+            'id': aid,
+            'email': _clean(acct.get('email', ''), 'the account email'),
+            'home': _clean(acct.get('home', ''), 'the account home'),
+            'added_at': _clean(acct.get('added_at', ''), 'added_at') or None,
+        },
+        'exported_at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()),
+        'exported_from': {'host': socket.gethostname(),
+                          'machine': 'mac' if sys.platform == 'darwin' else 'linux',
+                          'pool_root': root},
+    }
+    if identity_only:
+        emit(blob)
+        return
+
+    if provider == 'codex':
+        has_auth = os.path.isfile(os.path.join(d, 'auth.json')) \
+            and os.path.getsize(os.path.join(d, 'auth.json')) > 0
+        if not has_auth:
+            die(f'{aid} has no codex credential in {d}\n'
+                f'  fix: sign in on the machine that should run it — '
+                f'codex-accounts login {aid}', 4)
+        die(f'{aid} is a MACHINE-LOCAL codex credential (auth.json) and cannot be exported.\n'
+            f'  Why: auth.json carries a refresh token that ROTATES on every refresh; a\n'
+            f'  second machine using the same grant invalidates the first one.\n'
+            f'  Codex has no portable credential type — sign in once per machine:\n'
+            f'    codex-accounts login {aid}     (device-code flow; works over SSH)\n'
+            f'  To move only the registry entry (id/email/home), add --identity-only.', 3)
+
+    tpath = os.path.join(d, 'server.token')
+    cpath = os.path.join(d, '.credentials.json')
+    has_token = os.path.isfile(tpath) and os.path.getsize(tpath) > 0
+    if not has_token:
+        if os.path.isfile(cpath) and os.path.getsize(cpath) > 0:
+            die(f'{aid} only has a MACHINE-LOCAL credential (.credentials.json) and cannot '
+                f'be exported.\n'
+                f'  Why: the OAuth grant\'s refresh token ROTATES on every refresh; a second\n'
+                f'  machine refreshing the same grant strands the first one.\n'
+                f'  Make it portable (one interactive sign-in on THIS machine):\n'
+                f'    claude-accounts mint {aid}      # mints a portable setup-token\n'
+                f'  then re-run export-credential. Or sign in on the other machine:\n'
+                f'    claude-accounts login {aid}\n'
+                f'  To move only the registry entry (id/email/home), add --identity-only.', 3)
+        die(f'{aid} has no credential material in {d}\n'
+            f'  fix: claude-accounts login {aid}  (or --token for a portable one)', 4)
+    try:
+        with open(tpath) as f:
+            token = f.read().strip()
+    except OSError as e:
+        die(f'{aid}: server.token unreadable ({str(e)[:120]})', 5)
+    if not SETUP_TOKEN.fullmatch(token):
+        die(f'{aid}: server.token is not a subscription setup-token (sk-ant-oat…) — '
+            f'refusing to export unusable material.\n'
+            f'  fix: claude-accounts mint {aid}', 5)
+    blob['class'] = 'portable'
+    blob['credential'] = {'type': 'setup-token', 'value': token}
+    emit(blob)
+
+
+def _validate(provider, path):
+    blob = _load(path)
+    if not isinstance(blob, dict):
+        die('blob is not a JSON object')
+    if blob.get('format') != FORMAT:
+        die(f'not a claude-multiacc credential blob (format={blob.get("format")!r})')
+    try:
+        version = int(blob.get('version'))
+    except (TypeError, ValueError):
+        die(f'blob version is not a number: {blob.get("version")!r}')
+    if version > VERSION:
+        die(f'blob is version {version}; this claude-multiacc understands up to '
+            f'{VERSION} — update the addon (claude-accounts self-update)')
+    if blob.get('provider') != provider:
+        die(f'blob is for provider {blob.get("provider")!r}, not {provider!r} — '
+            f'use {blob.get("provider")}-accounts import-credential')
+    cclass = blob.get('class')
+    if cclass not in ('portable', 'identity'):
+        die(f'unknown credential class {cclass!r} (expected portable or identity)')
+    acct = blob.get('account')
+    if not isinstance(acct, dict):
+        die("blob has no 'account' object")
+    aid = _clean(acct.get('id', ''), 'blob account id')
+    if aid and not VALID_ID.fullmatch(aid):
+        die(f'blob account id is malformed: {aid!r}')
+    email = _clean(acct.get('email', ''), 'blob account email').strip()
+    if not email:
+        die('blob account has no email')
+    cred_type = ''
+    if cclass == 'portable':
+        cred = blob.get('credential')
+        if not isinstance(cred, dict):
+            die("blob is class 'portable' but has no 'credential' object")
+        cred_type = _clean(cred.get('type', ''), 'credential type')
+        value = cred.get('value')
+        if provider == 'codex':
+            die('codex credentials are machine-local — a portable codex blob cannot be '
+                'installed. Sign in on this machine instead: codex-accounts login <id>', 3)
+        if cred_type != 'setup-token':
+            die(f'unsupported credential type {cred_type!r} for provider {provider} '
+                f'(expected setup-token)', 3)
+        if not isinstance(value, str) or not SETUP_TOKEN.fullmatch(value.strip()):
+            die('credential value is not a subscription setup-token (sk-ant-oat…) — '
+                'API keys and truncated tokens are refused', 5)
+    return (blob, cclass, aid, email,
+            _clean(acct.get('home', ''), 'blob account home'),
+            _clean(acct.get('added_at', ''), 'blob added_at'), cred_type)
+
+
+def cmd_inspect(argv):
+    if len(argv) < 2:
+        die('usage: credential.py inspect <provider> <blob-file>')
+    _, cclass, aid, email, home, added_at, cred_type = _validate(argv[0], argv[1])
+    # 0x1F-separated: a NON-whitespace separator, so an empty field (a blob with no
+    # `home`) stays an empty field when bash splits the record instead of collapsing
+    # into the next one. _clean has already refused any control character in the data.
+    print(FIELD_SEP.join((cclass, aid, email, home, added_at, cred_type)))
+
+
+def cmd_install(argv):
+    if len(argv) < 3:
+        die('usage: credential.py install <provider> <blob-file> <dest-dir>')
+    provider, path, dest = argv[0], argv[1], argv[2]
+    blob, cclass, _aid, _email, _home, _added, _type = _validate(provider, path)
+    if cclass == 'identity':
+        return  # registry-only: nothing to write
+    if os.path.islink(dest):
+        die(f'destination is a symlink ({dest} -> {os.readlink(dest)}) — refusing to '
+            f'write a credential through it', 2)
+    if not os.path.isdir(dest):
+        die(f'destination is not a directory: {dest}')
+    out = os.path.join(dest, 'server.token')
+    _write_secure(out, blob['credential']['value'].strip(), nofollow_dir=True)
+    print(out)
+
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        die(__doc__.strip())
+    verb, rest = sys.argv[1], sys.argv[2:]
+    if verb == 'export':
+        cmd_export(rest)
+    elif verb == 'inspect':
+        cmd_inspect(rest)
+    elif verb == 'install':
+        cmd_install(rest)
+    else:
+        die(f'unknown verb: {verb}')