claude-multiacc 2.0.3 → 2.0.4

package/CLAUDE_ACCS_TASK.md

@@ -40,6 +40,11 @@ See README.md (tested reality). Deltas from plan, decided during implementation:
 Original plan below. Verified facts from planning:
 - This Mac stores Claude Code credentials per-config-dir in files (`.credentials.json`),
   NOT in macOS Keychain (tested 2026-07-13, Claude Code 2.1.207) → per-dir logins coexist.
+  **Superseded 2026-08-28:** that observation was an artefact of testing over ssh. Claude
+  Code (verified on 2.1.250) writes each config dir's login to the login Keychain
+  (`Claude Code-credentials-<sha256(dir)[:8]>`) from any session that can open it and
+  deletes the file; ssh/background sessions fall back to the file. The pool now reads
+  both (`lib/keychain.py`); per-dir logins still coexist (one Keychain item per dir).
 - `CLAUDE_CONFIG_DIR` isolation confirmed working on this Mac (isolated dir = "Not logged in").
 - Real binary: `~/.local/bin/claude`. Interactive `claude` is a zsh alias adding
   `--dangerously-skip-permissions` (kept; it composes with the shim via PATH).
@@ -231,6 +236,8 @@ Per account, in ONE incognito browser window signed into that claude.ai account:
 - `setup-token` tokens are inference-only (no Remote Control) — acceptable for `-p` usage.
 - macOS installs that store creds in Keychain (not this Mac) would break per-dir `/login`
   isolation; the addon must detect this at install time and warn (token-based fallback).
+  (2026-08-28: wrong on both counts — the Keychain item is per config dir, so isolation
+  holds, and every Mac does this from a GUI session; the addon reads the Keychain now.)
 - The usage/limits endpoint is internal (what `/usage` consumes) and may change without
   notice; limit tracking must fail OPEN (account treated available, retry logic as backstop)
   so limits telemetry can never break the 100% `-p` guarantee.

package/README.md

@@ -56,6 +56,7 @@ MAC (source of truth)                      SERVER (mirror)
   acct-01 -> ~/.claude   ("adopted")         acct-01/server.token   (synced, 600, once minted)
   acct-02/               (registered)        acct-02 -> /root/.claude ("adopted")
     server.token / .credentials.json
+    (or the login lives in the macOS Keychain — see below)
   selection.log  sync.log  health.log      /usr/local/bin/claude -> repo shim
 repo bin/ first on PATH (rc-file block)    /root/claude-multiacc/  (addon repo)
 ```
@@ -68,7 +69,8 @@ repo bin/ first on PATH (rc-file block)    /root/claude-multiacc/  (addon repo)
    token, revoked grant, a run that failed to authenticate) or an **org-blocked** one
    (Claude Code disabled for that account). Those can only fail, so they never enter
    selection.
-4. Among the accounts that remain valid **on this machine** (`.credentials.json` or
+4. Among the accounts that remain valid **on this machine** (an OAuth login —
+   `.credentials.json`, or a macOS Keychain item this session can open — or
    `server.token` present) and not limit-excluded, pick the one with the **most remaining
    headroom** (see below). On equal headroom the pool **rotates away from the account it
    just handed out** and samples the rest at random — so quitting a session and starting
@@ -177,8 +179,20 @@ Only when even that is unavailable does selection rank the account last, logged
 If an account's OAuth access token has been expired for a while (idle account,
 nothing ran claude under it for hours), the refresher renews it directly via the OAuth
 **refresh-token grant** — the same endpoint and public client id Claude Code itself uses —
-and atomically persists the rotated credential (0600) back to that account's
-`.credentials.json`. This is what keeps idle accounts' telemetry fresh so they win
+and atomically persists the rotated credential back to wherever it came from: that
+account's `.credentials.json` (0600), or its macOS Keychain item.
+
+> **Where a claude OAuth login actually lives (macOS).** Claude Code writes each config
+> dir's login to the **login Keychain** (service `Claude Code-credentials-<sha256(dir)[:8]>`)
+> from any session that can open it — a Terminal window, a launchd agent — and then
+> deletes `.credentials.json`. Sessions that cannot open the keychain (**ssh, tmux from
+> ssh, background jobs**) fall back to the plaintext file, and they also cannot READ a
+> Keychain-held login: those accounts show `KEYCHAIN LOCKED` there and are excluded from
+> that session's selection, while working normally from the Mac's own session. So a
+> login made over ssh migrates into the Keychain the first time a GUI-session process
+> refreshes its token — the pool reads both places (`lib/keychain.py`), and an account
+> that must work from everywhere should carry a portable token (`claude-accounts mint`).
+> Override: `CLAUDE_MULTIACC_KEYCHAIN=0` disables the lookup. This is what keeps idle accounts' telemetry fresh so they win
 selection over busy accounts; without it, stale telemetry ranks neutral and a truly-idle
 account would lose to a busy-but-fresh one. Refresh failures fail open and back off via
 `<acct>/.oauth-refresh.json` (10 min transient, 6 h when the grant looks revoked — the log
@@ -260,7 +274,7 @@ above about the claude pool holds for the codex pool with these translations:
 | `bin/claude` shim, `claude-accounts` CLI | `bin/codex` shim, `codex-accounts` CLI |
 | pool `~/.claude-accounts` | pool `~/.codex-accounts` |
 | `CLAUDE_CONFIG_DIR` per-account dirs | `CODEX_HOME` per-account dirs |
-| `.credentials.json` (OAuth, machine-local) | `auth.json` (ChatGPT OAuth, machine-local) |
+| `.credentials.json` / macOS Keychain item (OAuth, machine-local) | `auth.json` (ChatGPT OAuth, machine-local) |
 | `claude -p` auto-retry | `codex exec` auto-retry |
 | Anthropic OAuth usage and Fable buckets | Codex usage endpoint and per-model buckets |
 | `CLAUDE_*` pool controls | equivalent `CODEX_*` controls |
@@ -372,8 +386,9 @@ What install does (all reversible, nothing else):
   (+ bash rc files if present) — end-of-file placement matters because those files
   re-prepend `~/.local/bin`; launchd agents `com.claude-multiacc.limits` +
   `.codex-limits` (5m), `.health` + `.codex-health` (weekly Mon morning), and
-  `.update` (daily 04:07). Warns if this Mac stores credentials in the Keychain
-  (file-based credentials are required for per-dir logins).
+  `.update` (daily 04:07). Notes when this Mac keeps Claude Code logins in the
+  Keychain (the pool reads them; ssh sessions cannot — mint portable tokens for
+  accounts that must work from everywhere).
 - **Linux (root):** PATH block in `~/.bashrc` + `/etc/profile.d/claude-multiacc.sh`,
   shim symlinks at `/usr/local/bin/claude` and `/usr/local/bin/codex` (shadow via
   PATH order — on the systemd default PATH too; the original binaries are untouched),

package/bin/claude

@@ -96,6 +96,58 @@ else
   file_mtime() { stat -c %Y "$1" 2>/dev/null || echo 0; }
 fi
 
+# ---- macOS Keychain-held logins ----------------------------------------------------
+# Claude Code on macOS moves a config dir's OAuth login into the login Keychain
+# (service "Claude Code-credentials-<sha256(dir)[:8]>") the first time a GUI-session
+# process can write there, deleting .credentials.json as it does. A session that
+# cannot open the keychain (ssh/tmux/background: `security` exits 36) neither sees
+# such a login nor can the real client it launches use it — so here "readable" is
+# the only state that counts as auth, and a locked item counts as none FOR THIS
+# SESSION (the audit reports it as 'locked' rather than missing). lib/keychain.py is
+# the reference; this is the same lookup without a python start-up on the hot path.
+case "${CLAUDE_MULTIACC_KEYCHAIN:-}" in
+  0|false|no|off) KC_ON=0 ;;
+  1|true|yes|on) KC_ON=1 ;;
+  *) if [ "$(uname -s)" = "Darwin" ]; then KC_ON=1; else KC_ON=0; fi ;;
+esac
+if [ "$KC_ON" = "1" ] && ! command -v security >/dev/null 2>&1; then KC_ON=0; fi
+kc_service() { # $1 = acct dir -> the keychain service name the client uses for it
+  local h=""
+  if command -v shasum >/dev/null 2>&1; then h="$(printf '%s' "$1" | shasum -a 256 2>/dev/null)"
+  elif command -v sha256sum >/dev/null 2>&1; then h="$(printf '%s' "$1" | sha256sum 2>/dev/null)"; fi
+  printf 'Claude Code-credentials-%s' "$(printf '%s' "$h" | cut -c1-8)"
+}
+# One lookup per dir per run: has_auth, auth_dead and acct_token all ask about the
+# same dir in a row, and every `security` call is a process. Memoised in variables
+# (not a $(...) result) so the memo survives — callers read KC_JSON after kc_lookup.
+KC_MEMO_DIR=""; KC_MEMO_RC=1; KC_JSON=""
+kc_lookup() { # $1 = acct dir; sets KC_JSON; rc 0 readable, 1 none, 2 exists but locked here
+  [ "$KC_ON" = "1" ] || { KC_JSON=""; return 1; }
+  if [ "$KC_MEMO_DIR" = "$1" ]; then return "$KC_MEMO_RC"; fi
+  local out rc
+  out="$(security find-generic-password -s "$(kc_service "$1")" -w 2>/dev/null)"; rc=$?
+  KC_MEMO_DIR="$1"; KC_JSON=""; KC_MEMO_RC=1
+  case "$rc" in
+    0) case "$out" in *claudeAiOauth*) KC_JSON="$out"; KC_MEMO_RC=0 ;; esac ;;
+    36) KC_MEMO_RC=2 ;;
+  esac
+  return "$KC_MEMO_RC"
+}
+kc_mtime() { # $1 = acct dir -> epoch of the item's last write (0 when none); attributes
+             # are readable even when the secret is locked, so a marker still self-heals
+  [ "$KC_ON" = "1" ] || { echo 0; return 0; }
+  local stamp
+  stamp="$(security find-generic-password -s "$(kc_service "$1")" 2>/dev/null \
+    | LC_ALL=C sed -n 's/.*"mdat"<timedate>=0x[0-9A-Fa-f]*  *"\([0-9]\{14\}\)Z.*/\1/p' | head -1)"
+  case "$stamp" in
+    [0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9])
+      date -j -u -f '%Y%m%d%H%M%S' "$stamp" +%s 2>/dev/null \
+        || date -u -d "${stamp:0:8} ${stamp:8:2}:${stamp:10:2}:${stamp:12:2}" +%s 2>/dev/null \
+        || echo 0 ;;
+    *) echo 0 ;;
+  esac
+}
+
 
 # A number this shim will do ARITHMETIC on: digits only, and short enough that bash
 # cannot go out of range. An over-range value makes `[ x -lt y ]` print
@@ -563,28 +615,43 @@ sel_capture_session() { # $1 acct dir
 
 # An empty credentials file is NOT auth (an interrupted write must not make a
 # dead account selectable and turn a working stock run into an auth failure).
-has_auth() { [ -s "$1/.credentials.json" ] || [ -s "$1/server.token" ]; }
+# A Keychain-held login counts only when THIS session can read it (kc_lookup rc 0).
+has_auth() { [ -s "$1/.credentials.json" ] || [ -s "$1/server.token" ] || kc_lookup "$1"; }
+# The OAuth login itself, wherever the client keeps it (file or readable Keychain item).
+has_oauth() { [ -f "$1/.credentials.json" ] || kc_lookup "$1"; }
 
-cred_num() { # cred_num <file> <json key> -> integer (epoch ms) or empty
+cred_num() { # cred_num <json text> <json key> -> integer (epoch ms) or empty
   # The leading quote makes "expiresAt" unambiguous: "refreshTokenExpiresAt" cannot match it.
-  LC_ALL=C sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p" "$1" 2>/dev/null | head -1
+  printf '%s' "$1" | LC_ALL=C sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p" 2>/dev/null | head -1
 }
 
-# TRUE when <dir>/.credentials.json exists but can no longer authenticate: the access
+# The credential document for <dir>: .credentials.json when present (even unreadable
+# or truncated — the scrape below is deliberately lenient), else the Keychain item
+# this session can read. Empty when there is neither.
+cred_text() { # $1 = acct dir
+  if [ -s "$1/.credentials.json" ]; then
+    cat "$1/.credentials.json" 2>/dev/null
+  elif kc_lookup "$1"; then
+    printf '%s' "$KC_JSON"
+  fi
+}
+
+# TRUE when the dir's OAuth login exists but can no longer authenticate: the access
 # token is expired AND nothing can renew it (no refresh token, or the refresh token is
 # itself expired). Such an account fails EVERY run with "OAuth session expired and
 # could not be refreshed", so selecting it is strictly worse than not having it.
 # Anything unparseable fails OPEN (treated as alive) — telemetry-free guesswork must
 # never take a working account out of the pool.
 creds_dead() { # $1 = acct dir
-  local f="$1/.credentials.json" exp rexp
-  [ -s "$f" ] || return 1
-  exp="$(cred_num "$f" expiresAt)"
+  local src exp rexp
+  has_oauth "$1" || return 1
+  src="$(cred_text "$1")"
+  exp="$(cred_num "$src" expiresAt)"
   case "$exp" in ''|*[!0-9]*) exp=0 ;; esac
   [ $((exp / 1000)) -gt "$now" ] && return 1        # access token still valid
   # Access token expired: only a live refresh token can save it.
-  grep -q '"refreshToken"[[:space:]]*:[[:space:]]*"[^"]' "$f" 2>/dev/null || return 0
-  rexp="$(cred_num "$f" refreshTokenExpiresAt)"
+  printf '%s' "$src" | grep -q '"refreshToken"[[:space:]]*:[[:space:]]*"[^"]' 2>/dev/null || return 0
+  rexp="$(cred_num "$src" refreshTokenExpiresAt)"
   case "$rexp" in ''|*[!0-9]*) return 1 ;; esac     # unknown expiry => fail open
   [ $((rexp / 1000)) -le "$now" ]
 }
@@ -617,6 +684,12 @@ expired_marked() { # $1 = acct dir
         return 1
       fi
     done
+    # A login the client keeps in the Keychain is "written after the marker" in the
+    # same sense; its stamp is readable even from a session that cannot open it.
+    if [ ! -f "$1/.credentials.json" ] && [ "$(kc_mtime "$1")" -gt "$mt" ]; then
+      rm -f "$m" 2>/dev/null
+      return 1
+    fi
   fi
   soft="$(LC_ALL=C sed -n 's/.*soft_until=\([0-9][0-9]*\).*/\1/p' "$m" 2>/dev/null | head -1)"
   case "$soft" in
@@ -639,7 +712,7 @@ auth_dead() { # $1 = acct dir
 acct_token() { # $1 = acct dir; prints token if the dir must authenticate by token
   # Token-auth dirs (no local creds), and dirs whose OAuth credential is dead but which
   # still carry a portable setup-token — the token is the only thing that can work there.
-  if [ -s "$1/server.token" ] && { [ ! -f "$1/.credentials.json" ] || creds_dead "$1"; }; then
+  if [ -s "$1/server.token" ] && { ! has_oauth "$1" || creds_dead "$1"; }; then
     tr -d '[:space:]' < "$1/server.token"
   fi
 }