claude-multiacc 2.0.3 → 2.0.5

package/tests/run-tests.sh

@@ -56,6 +56,16 @@ if [ "${1:-}" = "auth" ] && [ "${2:-}" = "status" ]; then
 fi
 if [ "${1:-}" = "auth" ] && [ "${2:-}" = "login" ]; then
   [ -n "${FAKE_LOGIN_FAIL:-}" ] && { echo "login aborted" >&2; exit 1; }
+  if [ -n "${FAKE_LOGIN_KEYCHAIN:-}" ] && [ -n "${CLAUDE_CONFIG_DIR:-}" ]; then
+    # simulate the macOS client in a keychain-capable session: the login lands in the
+    # keychain (via the fake `security` on PATH) and NO .credentials.json is written
+    h="$(printf '%s' "$CLAUDE_CONFIG_DIR" | { shasum -a 256 2>/dev/null || sha256sum; } | cut -c1-8)"
+    hex="$(printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-login","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999,"scopes":["user:inference"],"subscriptionType":"max"}}' \
+      | python3 -c 'import sys;print(sys.stdin.buffer.read().hex())')"
+    security add-generic-password -U -a tester -s "Claude Code-credentials-$h" -X "$hex"
+    echo "Logged in."
+    exit 0
+  fi
   # simulate a completed full-scope login: write auto-refreshing creds to the config dir
   printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-login","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999,"scopes":["user:inference"],"subscriptionType":"max"}}' > "${CLAUDE_CONFIG_DIR:-/dev/null}/.credentials.json"
   echo "Logged in."
@@ -134,6 +144,65 @@ echo "CFG=$acct TOK=${CLAUDE_CODE_OAUTH_TOKEN:-none} ARGS=$*"
 EOF
 chmod +x "$FAKEBIN/claude"
 
+# Fake macOS `security` (generic-password verbs only): items live as files under
+# $FAKE_KEYCHAIN_DIR/<service> (content = the secret) + <service>.acct (account name).
+# FAKE_KEYCHAIN_LOCKED=1 simulates a session that cannot open the keychain — secret
+# reads and every write exit 36 while ATTRIBUTE reads still answer, exactly the split
+# the real tool exhibits over ssh. Shadows any real /usr/bin/security via PATH, so a
+# macOS dev run of this suite can never touch the developer's actual keychain.
+cat > "$FAKEBIN/security" <<'EOF'
+#!/usr/bin/env bash
+KC="${FAKE_KEYCHAIN_DIR:-/nonexistent-keychain}"
+cmd="${1:-}"; shift || true
+svc=""; acct=""; want_pw=0; hexdata=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -s) svc="$2"; shift 2 ;;
+    -a) acct="$2"; shift 2 ;;
+    -w) want_pw=1; shift ;;
+    -X) hexdata="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+# The modification stamp is RECORDED AT WRITE TIME in a sidecar rather than derived
+# from the item file's mtime: `stat`/`date` flags differ between BSD and GNU (on Linux
+# `stat -f %m` even "succeeds" with garbage), and this fake must behave identically on
+# a developer's Mac and on Linux CI.
+item_mdat() { cat "$KC/$svc.mdat" 2>/dev/null || echo 00000000000000; }
+case "$cmd" in
+  show-keychain-info)
+    [ -n "${FAKE_KEYCHAIN_LOCKED:-}" ] && exit 36
+    exit 0 ;;
+  find-generic-password)
+    [ -f "$KC/$svc" ] || exit 44
+    if [ "$want_pw" = "1" ]; then
+      [ -n "${FAKE_KEYCHAIN_LOCKED:-}" ] && exit 36
+      cat "$KC/$svc"
+      exit 0
+    fi
+    a="tester"; [ -f "$KC/$svc.acct" ] && a="$(cat "$KC/$svc.acct")"
+    printf 'keychain: "login.keychain-db"\nclass: "genp"\nattributes:\n'
+    printf '    "acct"<blob>="%s"\n' "$a"
+    printf '    "mdat"<timedate>=0x00  "%sZ\\000"\n' "$(item_mdat)"
+    printf '    "svce"<blob>="%s"\n' "$svc"
+    exit 0 ;;
+  add-generic-password)
+    [ -n "${FAKE_KEYCHAIN_LOCKED:-}" ] && exit 36
+    mkdir -p "$KC"
+    printf '%s' "$hexdata" | python3 -c 'import sys;sys.stdout.buffer.write(bytes.fromhex(sys.stdin.read().strip()))' > "$KC/$svc"
+    printf '%s' "${acct:-tester}" > "$KC/$svc.acct"
+    date -u +%Y%m%d%H%M%S > "$KC/$svc.mdat"
+    exit 0 ;;
+  delete-generic-password)
+    [ -n "${FAKE_KEYCHAIN_LOCKED:-}" ] && exit 36
+    [ -f "$KC/$svc" ] || exit 44
+    rm -f "$KC/$svc" "$KC/$svc.acct" "$KC/$svc.mdat"
+    exit 0 ;;
+  *) exit 1 ;;
+esac
+EOF
+chmod +x "$FAKEBIN/security"
+
 export PATH="$REPO_DIR/bin:$FAKEBIN:$PATH"
 export FAKE_CTL="$WORK/ctl"
 # Neutralize any ambient state from the invoking environment.
@@ -155,6 +224,10 @@ export CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-endpoint-missing.json"
 # throttle keeps those background kicks from racing explicit limits runs.
 export CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-endpoint-missing.json"
 : > "$ACC/.limits-kick"
+# Keychain lookups are OFF for the legacy sections (their pools are file-based and the
+# extra `security` process per account would only slow them down); section 17 turns
+# them on explicitly against the fake `security` above.
+export CLAUDE_MULTIACC_KEYCHAIN=0
 
 now="$(date +%s)"
 
@@ -2366,6 +2439,73 @@ if command -v node >/dev/null 2>&1; then
   esac
   case "$out" in *"update manually"*|*"already latest"*|*"git pull"*) t_ok "self-update reports its path" ;;
     *) t_fail "self-update message" "unexpected: $out" ;; esac
+
+  # ---- 19a. an npm install updates itself with NO npm on PATH -----------------------
+  # launchd hands an agent PATH=/usr/bin:/bin:/usr/sbin:/sbin, so `command -v npm` finds
+  # nothing and the nightly self-update logged "npm not found; skipping" for days while
+  # every Mac's copy silently froze. npm must be resolved by path — and specifically the
+  # one inside the prefix that owns the RUNNING copy, never whatever a stray PATH offers.
+  for _cli in claude-accounts codex-accounts; do
+    PFX="$WORK/pfx-$_cli"
+    NPMROOT="$PFX/lib/node_modules/claude-multiacc"
+    mkdir -p "$NPMROOT" "$PFX/bin"
+    cp -R "$REPO_DIR/bin" "$REPO_DIR/lib" "$REPO_DIR/package.json" "$NPMROOT/"
+    # A fake npm that records how it was called and "installs" by bumping package.json.
+    # Its shebang names an interpreter that exists ONLY beside it, mirroring the real
+    # npm's `#!/usr/bin/env node`: resolving npm by absolute path is not enough if the
+    # agent's PATH cannot find npm's own interpreter, which is how the update failed
+    # with an empty version probe and no explanation.
+    cat > "$PFX/bin/multiacc-fake-node" <<'NODEEOF'
+#!/usr/bin/env bash
+exec /bin/bash "$@"
+NODEEOF
+    chmod +x "$PFX/bin/multiacc-fake-node"
+    cat > "$PFX/bin/npm" <<NPMEOF
+#!/usr/bin/env multiacc-fake-node
+echo "npm \$*" >> "$WORK/npm-calls-$_cli.log"
+case "\${1:-}" in
+  view) echo 9.9.9 ;;
+  install) python3 - "$NPMROOT/package.json" <<'PY'
+import json, sys
+p = sys.argv[1]
+doc = json.load(open(p)); doc['version'] = '9.9.9'
+json.dump(doc, open(p, 'w'))
+PY
+    ;;
+esac
+exit 0
+NPMEOF
+    chmod +x "$PFX/bin/npm"
+    # A DIFFERENT npm earlier on PATH must not win: the running copy's prefix owns it.
+    mkdir -p "$WORK/wrongbin"
+    printf '#!/usr/bin/env bash\necho "WRONG-NPM \$*" >> "%s"\nexit 0\n' "$WORK/npm-calls-$_cli.log" > "$WORK/wrongbin/npm"
+    chmod +x "$WORK/wrongbin/npm"
+    : > "$WORK/npm-calls-$_cli.log"
+    out="$(env -i HOME="$HOME" PATH="$WORK/wrongbin:/usr/bin:/bin:/usr/sbin:/sbin" \
+      CLAUDE_ACCOUNTS_DIR="$ACC" CODEX_ACCOUNTS_DIR="$WORK/codex-accounts" \
+      "$NPMROOT/bin/$_cli" self-update 2>&1)"
+    rc=$?
+    [ "$rc" = "0" ] && t_ok "$_cli: self-update exits 0 with no npm on PATH" \
+      || t_fail "$_cli self-update rc" "rc=$rc: $(printf '%s' "$out" | head -c 200)"
+    printf '%s' "$out" | grep -q "npm not found" \
+      && t_fail "$_cli self-update npm lookup" "still reports 'npm not found' with an npm in its own prefix" \
+      || t_ok "$_cli: npm resolved without PATH"
+    grep -q "^npm install " "$WORK/npm-calls-$_cli.log" \
+      && t_ok "$_cli: the prefix's own npm performed the install" \
+      || t_fail "$_cli npm install" "calls: $(cat "$WORK/npm-calls-$_cli.log" | head -3)"
+    grep -q "WRONG-NPM" "$WORK/npm-calls-$_cli.log" \
+      && t_fail "$_cli npm choice" "used the npm from PATH instead of the running prefix's" \
+      || t_ok "$_cli: a stray npm on PATH never wins over the running prefix's"
+    check "$_cli: self-update verifies the tree it wrote" "npm update ok (9.9.9)" "$out"
+    grep -q "^npm view " "$WORK/npm-calls-$_cli.log" \
+      && t_ok "$_cli: npm ran despite its interpreter being off PATH" \
+      || t_fail "$_cli npm interpreter" "npm never executed — its shebang interpreter was not found"
+  done
+  # The agents install.sh writes must carry a PATH for the same reason (a future tool
+  # that is not resolved by absolute path would hit exactly this again).
+  grep -q '<key>PATH</key>' "$REPO_DIR/install.sh" \
+    && t_ok "install.sh gives its launchd agents a PATH" \
+    || t_fail "agent PATH" "plist_env_block writes no PATH — launchd agents get /usr/bin:/bin only"
   # postinstall must SKIP for a non-global install and never fail
   out="$(node "$REPO_DIR/scripts/postinstall.mjs" 2>&1)"
   rc=$?
@@ -4072,6 +4212,156 @@ for _bin in claude-accounts codex-accounts; do
     || t_fail "$_bin unknown verb --help" "exited 0 — the probe would accept a verb that does not exist"
 done
 
+# ---- 17. macOS Keychain-held logins --------------------------------------------------
+# Claude Code on macOS moves a per-dir OAuth login into the login Keychain (service
+# "Claude Code-credentials-<sha256(dir)[:8]>") from any keychain-capable session and
+# deletes .credentials.json — the 2026-08-28 incident read five working accounts as
+# "missing". The fake `security` above serves items from $FAKE_KEYCHAIN_DIR so the real
+# lookup code runs on Linux too. Own pool root: the main pool's manifest has been
+# through a dozen mutations by this point in the suite.
+KCP="$WORK/kcpool"
+export FAKE_KEYCHAIN_DIR="$WORK/keychain"
+mkdir -p "$KCP/tmp" "$KCP/acct-01" "$KCP/acct-02" "$FAKE_KEYCHAIN_DIR"
+: > "$KCP/.limits-kick"
+cat > "$KCP/accounts.json" <<EOF
+{ "version": 1, "server": "root@203.0.113.1", "server_root": "/root/.claude-accounts",
+  "server_repo": "/root/claude-multiacc", "threshold": 90,
+  "accounts": [
+    {"id": "acct-01", "email": "kfile@test", "home": "mac", "added_at": "2026-08-28T00:00:00Z"},
+    {"id": "acct-02", "email": "kchain@test", "home": "mac", "added_at": "2026-08-28T00:00:00Z"}
+  ] }
+EOF
+printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-kfile","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}' > "$KCP/acct-01/.credentials.json"
+kc_hash() { printf '%s' "$1" | { shasum -a 256 2>/dev/null || sha256sum; } | cut -c1-8; }
+kc_svc_file() { printf '%s/Claude Code-credentials-%s' "$FAKE_KEYCHAIN_DIR" "$(kc_hash "$1")"; }
+kc_put() { # kc_put <acct dir> <credential json> — store it the way the client would
+  security add-generic-password -U -a tester -s "Claude Code-credentials-$(kc_hash "$1")" \
+    -X "$(printf '%s' "$2" | python3 -c 'import sys;print(sys.stdin.buffer.read().hex())')"
+}
+kc_put "$KCP/acct-02" '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-kchain","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}'
+export CLAUDE_MULTIACC_KEYCHAIN=1
+
+# 17a. the keychain login reads as a working machine-local OAuth login
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts list --json 2>&1)"
+python3 - "$out" <<'EOF'
+import json, sys
+doc = json.loads(sys.argv[1])
+rows = {a['id']: a for a in doc['accounts']}
+a2 = rows['acct-02']
+assert a2['status'] == 'active', a2['status']
+assert a2['credential_class'] == 'machine-local', a2['credential_class']
+assert a2['credentials']['oauth_store'] == 'keychain', a2['credentials']
+assert a2['credentials']['keychain'] == 'readable', a2['credentials']
+assert a2['selectable'] is True, a2
+assert rows['acct-01']['credentials']['oauth_store'] == 'file', rows['acct-01']['credentials']
+assert doc['summary']['selectable'] == 2, doc['summary']
+EOF
+[ $? -eq 0 ] && t_ok "keychain login is active machine-local in list --json" \
+  || t_fail "keychain list --json" "see assertions above"
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts list 2>&1)"
+check "keychain login shown in the plain list" "auth=keychain" "$out"
+
+# 17b. the shim runs under a keychain-only account (file account parked by a limit)
+printf '%s\nbucket=weekly_scoped:Fable percent=95 reason=limits\n' "$((now+3600))" > "$KCP/acct-01/.limited"
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" claude 2>&1)"
+check "shim selects the keychain-only account" "CFG=acct-02" "$out"
+
+# 17c. locked keychain (ssh session): 'locked', never 'missing'; excluded HERE only
+out="$(FAKE_KEYCHAIN_LOCKED=1 CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts list --json 2>&1)"
+python3 - "$out" <<'EOF'
+import json, sys
+doc = json.loads(sys.argv[1])
+a2 = {a['id']: a for a in doc['accounts']}['acct-02']
+assert a2['status'] == 'locked', a2['status']
+assert a2['credential_class'] == 'machine-local', a2['credential_class']
+assert a2['credentials']['keychain'] == 'locked', a2['credentials']
+assert a2['selectable'] is False, a2
+assert a2['needs_login'] is False, 'locked must not join the re-login worklist'
+EOF
+[ $? -eq 0 ] && t_ok "locked keychain reads as 'locked' machine-local, not missing" \
+  || t_fail "keychain locked state" "see assertions above"
+out="$(FAKE_KEYCHAIN_LOCKED=1 CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts expired --quiet 2>&1)"; rc=$?
+[ "$rc" = "0" ] && t_ok "a locked keychain login is not a relogin worklist item" \
+  || t_fail "locked vs expired" "rc=$rc out=$out"
+out="$(FAKE_KEYCHAIN_LOCKED=1 CLAUDE_ACCOUNTS_DIR="$KCP" claude 2>&1)"
+check "shim never selects a keychain login it cannot read" "CFG=acct-01" "$out"
+rm -f "$KCP/acct-01/.limited"
+
+# 17d. limits: the probe takes its bearer from the keychain
+rm -f "$KCP/acct-02/limits.json"
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits 2>&1)"
+check "limits fetches with a keychain bearer" "acct-02: ok" "$out"
+python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); assert d.get("source")=="oauth", d' \
+  "$KCP/acct-02/limits.json" 2>/dev/null \
+  && t_ok "keychain-backed telemetry records source=oauth" \
+  || t_fail "keychain limits source" "limits.json missing or wrong source"
+
+# 17e. refresh: an expired keychain credential refreshes via the grant and is written
+# BACK to the keychain — never copied out into a .credentials.json
+kc_put "$KCP/acct-02" '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-kold","refreshToken":"sk-ant-ort01-kc","expiresAt":1000000,"refreshTokenExpiresAt":9999999999999}}'
+rm -f "$KCP/acct-02/limits.json" "$KCP/acct-02/.oauth-refresh.json"
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-ok.json" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits --force 2>&1)"
+check "keychain credential refreshes via the grant" "acct-02: oauth access token refreshed" "$out"
+grep -q 'sk-ant-oat01-refreshednew' "$(kc_svc_file "$KCP/acct-02")" \
+  && t_ok "rotated credential written back to the keychain" \
+  || t_fail "keychain write-back" "item not updated"
+[ ! -f "$KCP/acct-02/.credentials.json" ] \
+  && t_ok "refresh never copies the keychain credential to a file" \
+  || t_fail "keychain leak to file" ".credentials.json appeared beside a keychain login"
+
+# 17f. .expired self-heals on a keychain login written after the marker
+printf '%s\nreason=auth-error marked_at=t detail=test\n' "$now" > "$KCP/acct-02/.expired"
+touch -t 202001010000 "$KCP/acct-02/.expired"
+kc_put "$KCP/acct-02" '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-knew","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}'
+CLAUDE_ACCOUNTS_DIR="$KCP" claude >/dev/null 2>&1
+[ ! -f "$KCP/acct-02/.expired" ] \
+  && t_ok ".expired self-heals on a newer keychain credential" \
+  || t_fail "keychain .expired self-heal" "marker survived a newer keychain login"
+
+# 17g. a login ceremony that lands in the keychain registers instead of dying
+out="$(CLAUDE_MULTIACC_FORCE_TTY=1 FAKE_LOGIN_KEYCHAIN=1 FAKE_EMAIL=kc3@test CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts add kc3@test 2>&1)"
+check "add registers a keychain-backed sign-in" "Registered acct-03 for kc3@test" "$out"
+[ ! -f "$KCP/acct-03/.credentials.json" ] \
+  && t_ok "keychain add leaves no plaintext credential" \
+  || t_fail "keychain add" "unexpected .credentials.json"
+[ -f "$(kc_svc_file "$KCP/acct-03")" ] && t_ok "the sign-in landed in the keychain" \
+  || t_fail "keychain add item" "no keychain item for acct-03"
+
+# 17h. export refuses a keychain-held machine-local credential, naming the store
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts export-credential acct-03 --out "$WORK/kc-export.json" 2>&1)"; rc=$?
+[ "$rc" = "3" ] && t_ok "export-credential refuses a keychain login (exit 3)" \
+  || t_fail "keychain export rc" "rc=$rc: $(printf '%s' "$out" | head -c 160)"
+check "export names the keychain as the machine-local store" "macOS Keychain" "$out"
+
+# 17i. remove deletes the keychain item with the account
+CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts remove acct-03 --yes >/dev/null 2>&1
+[ ! -f "$(kc_svc_file "$KCP/acct-03")" ] && t_ok "remove drops the keychain item" \
+  || t_fail "keychain remove" "the item survived removal"
+
+# 17j. dedupe keeps the duplicate that actually holds the (keychain) login. The
+# keychain holder gets the HIGHER id on purpose: with keychain auth invisible, the
+# lowest-id tiebreak would keep credential-less acct-04 and throw the grant away.
+python3 - "$KCP/accounts.json" <<'EOF'
+import json, sys
+doc = json.load(open(sys.argv[1]))
+doc['accounts'] += [
+    {'id': 'acct-04', 'email': 'kdup@test', 'home': 'mac', 'added_at': '2026-08-28T00:00:00Z'},
+    {'id': 'acct-05', 'email': 'kdup@test', 'home': 'mac', 'added_at': '2026-08-28T00:00:00Z'}]
+json.dump(doc, open(sys.argv[1], 'w'))
+EOF
+mkdir -p "$KCP/acct-04" "$KCP/acct-05"
+kc_put "$KCP/acct-05" '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-kdup","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}'
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts dedupe --yes 2>&1)"
+check "dedupe removes the credential-less duplicate, not the keychain one" "will remove acct-04 (kdup@test)" "$out"
+[ -f "$(kc_svc_file "$KCP/acct-05")" ] && t_ok "the keychain-authed duplicate survives dedupe" \
+  || t_fail "dedupe keychain keep" "acct-05's keychain item is gone"
+grep -q '"acct-04"' "$KCP/accounts.json" \
+  && t_fail "dedupe manifest" "acct-04 still registered" \
+  || t_ok "the credential-less duplicate left the manifest"
+
+export CLAUDE_MULTIACC_KEYCHAIN=0
+unset FAKE_KEYCHAIN_DIR
+
 # The reset-credit contract is easier to prove against a stateful local HTTP server
 # than file:// fixtures: it pins thresholding, credit ordering and idempotent POST retry.
 if CODEX_MULTIACC_AUTO_RESET=1 python3 "$REPO_DIR/tests/test_codex_reset.py"; then

package/tests/test_keychain.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Unit tests for lib/keychain.py and its audit/report integration.
+
+Runs everywhere: a fake `security` on PATH serves generic-password items from a
+temp dir, and CLAUDE_MULTIACC_KEYCHAIN=1 forces the lookup on off-macOS. Nothing
+here can ever touch a real keychain — the fake shadows /usr/bin/security.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import unittest
+
+REPO = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO / 'lib'))
+
+FAKE_SECURITY = r'''#!/usr/bin/env bash
+KC="${FAKE_KEYCHAIN_DIR:-/nonexistent-keychain}"
+cmd="${1:-}"; shift || true
+svc=""; acct=""; want_pw=0; hexdata=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -s) svc="$2"; shift 2 ;;
+    -a) acct="$2"; shift 2 ;;
+    -w) want_pw=1; shift ;;
+    -X) hexdata="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+case "$cmd" in
+  find-generic-password)
+    [ -f "$KC/$svc" ] || exit 44
+    if [ "$want_pw" = "1" ]; then
+      [ -n "${FAKE_KEYCHAIN_LOCKED:-}" ] && exit 36
+      cat "$KC/$svc"; exit 0
+    fi
+    a="tester"; [ -f "$KC/$svc.acct" ] && a="$(cat "$KC/$svc.acct")"
+    printf 'attributes:\n    "acct"<blob>="%s"\n' "$a"
+    printf '    "mdat"<timedate>=0x00  "20260828043137Z\\000"\n'
+    printf '    "svce"<blob>="%s"\n' "$svc"
+    exit 0 ;;
+  add-generic-password)
+    [ -n "${FAKE_KEYCHAIN_LOCKED:-}" ] && exit 36
+    mkdir -p "$KC"
+    printf '%s' "$hexdata" | python3 -c 'import sys;sys.stdout.buffer.write(bytes.fromhex(sys.stdin.read().strip()))' > "$KC/$svc"
+    printf '%s' "${acct:-tester}" > "$KC/$svc.acct"
+    exit 0 ;;
+  delete-generic-password)
+    [ -f "$KC/$svc" ] || exit 44
+    rm -f "$KC/$svc" "$KC/$svc.acct"; exit 0 ;;
+  *) exit 1 ;;
+esac
+'''
+
+DOC = {'claudeAiOauth': {'accessToken': 'sk-ant-oat01-x', 'refreshToken': 'r',
+                         'expiresAt': 9999999999999,
+                         'refreshTokenExpiresAt': 9999999999999}}
+
+
+class KeychainTests(unittest.TestCase):
+    def setUp(self):
+        self.work = tempfile.TemporaryDirectory()
+        work = Path(self.work.name)
+        fakebin = work / 'bin'
+        fakebin.mkdir()
+        tool = fakebin / 'security'
+        tool.write_text(FAKE_SECURITY)
+        tool.chmod(0o755)
+        self.kcdir = work / 'keychain'
+        self.saved = {k: os.environ.get(k) for k in
+                      ('PATH', 'CLAUDE_MULTIACC_KEYCHAIN', 'FAKE_KEYCHAIN_DIR',
+                       'FAKE_KEYCHAIN_LOCKED')}
+        os.environ['PATH'] = f"{fakebin}:{os.environ['PATH']}"
+        os.environ['CLAUDE_MULTIACC_KEYCHAIN'] = '1'
+        os.environ['FAKE_KEYCHAIN_DIR'] = str(self.kcdir)
+        os.environ.pop('FAKE_KEYCHAIN_LOCKED', None)
+        # (re)load with the fake in place
+        import importlib
+        import keychain
+        self.keychain = importlib.reload(keychain)
+        self.root = work / 'accounts'
+        (self.root / 'acct-01').mkdir(parents=True)
+        (self.root / 'acct-01' / 'tmp').mkdir(exist_ok=True)
+
+    def tearDown(self):
+        for key, value in self.saved.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+        self.work.cleanup()
+
+    # -- the layout facts this whole feature stands on ------------------------------
+    def test_service_name_matches_the_client(self):
+        # Observed live 2026-08-28 (Claude Code 2.1.250, my-mini): this config dir's
+        # login sat under exactly this service. The hash input is the PATH STRING as
+        # the client received it — no realpath, no trailing slash.
+        self.assertEqual(
+            self.keychain.service_name('/Users/gas/.claude-accounts/acct-16'),
+            'Claude Code-credentials-4219e2b1')
+
+    def test_absent_then_present_roundtrip(self):
+        d = str(self.root / 'acct-01')
+        self.assertEqual(self.keychain.probe(d)['state'], 'absent')
+        self.assertTrue(self.keychain.write(d, DOC, account='gas'))
+        res = self.keychain.probe(d)
+        self.assertEqual(res['state'], 'present')
+        self.assertEqual(res['doc'], DOC)
+        # -U update path keeps a single item and the account name it was made with
+        doc2 = {'claudeAiOauth': dict(DOC['claudeAiOauth'], accessToken='sk-ant-oat01-y')}
+        self.assertTrue(self.keychain.write(d, doc2))
+        again = self.keychain.probe(d)
+        self.assertEqual(again['doc']['claudeAiOauth']['accessToken'], 'sk-ant-oat01-y')
+        self.assertTrue(self.keychain.delete(d))
+        self.assertEqual(self.keychain.probe(d)['state'], 'absent')
+        self.assertTrue(self.keychain.delete(d))     # deleting a missing item is fine
+
+    def test_locked_is_distinguished_from_absent(self):
+        d = str(self.root / 'acct-01')
+        self.keychain.write(d, DOC, account='tester')
+        os.environ['FAKE_KEYCHAIN_LOCKED'] = '1'
+        res = self.keychain.probe(d)
+        self.assertEqual(res['state'], 'locked')
+        self.assertIsNone(res['doc'])
+        self.assertEqual(res['account'], 'tester')
+        self.assertGreater(self.keychain.item_mtime(d), 0)
+        # an id with NO item is still absent, not locked
+        self.assertEqual(self.keychain.probe(d + '-other')['state'], 'absent')
+
+    def test_corrupt_item(self):
+        d = str(self.root / 'acct-01')
+        svc = self.keychain.service_name(d)
+        self.kcdir.mkdir(exist_ok=True)
+        (self.kcdir / svc).write_text('not json at all')
+        self.assertEqual(self.keychain.probe(d)['state'], 'corrupt')
+
+    def test_kill_switch(self):
+        d = str(self.root / 'acct-01')
+        self.keychain.write(d, DOC)
+        os.environ['CLAUDE_MULTIACC_KEYCHAIN'] = '0'
+        self.assertFalse(self.keychain.enabled())
+        self.assertEqual(self.keychain.probe(d)['state'], 'absent')
+        os.environ['CLAUDE_MULTIACC_KEYCHAIN'] = '1'
+
+    # -- audit + report integration --------------------------------------------------
+    def _manifest(self):
+        (self.root / 'accounts.json').write_text(json.dumps({
+            'version': 1, 'server': 'root@203.0.113.1',
+            'server_root': '/root/.claude-accounts',
+            'server_repo': '/root/claude-multiacc', 'threshold': 90,
+            'accounts': [{'id': 'acct-01', 'email': 'kc@test', 'home': 'mac',
+                          'added_at': '2026-08-28T00:00:00Z'}]}))
+
+    def test_audit_sees_a_keychain_login(self):
+        import audit
+        self._manifest()
+        d = str(self.root / 'acct-01')
+        self.assertEqual(
+            audit.audit_account(str(self.root), {'id': 'acct-01', 'email': 'kc@test',
+                                                 'home': 'mac'}, machine='mac')['state'],
+            'missing')
+        self.keychain.write(d, DOC)
+        row = audit.audit_account(str(self.root), {'id': 'acct-01', 'email': 'kc@test',
+                                                   'home': 'mac'}, machine='mac')
+        self.assertEqual((row['state'], row['store']), ('ok', 'keychain'))
+        os.environ['FAKE_KEYCHAIN_LOCKED'] = '1'
+        row = audit.audit_account(str(self.root), {'id': 'acct-01', 'email': 'kc@test',
+                                                   'home': 'mac'}, machine='mac')
+        self.assertEqual(row['state'], 'locked')
+        self.assertEqual(row['label'], 'KEYCHAIN LOCKED')
+        os.environ.pop('FAKE_KEYCHAIN_LOCKED', None)
+
+    def test_report_class_and_status(self):
+        self._manifest()
+        d = str(self.root / 'acct-01')
+        self.keychain.write(d, DOC)
+        out = subprocess.run(
+            [sys.executable, str(REPO / 'lib' / 'report.py'), str(self.root),
+             'claude', 'mac', 'list'],
+            capture_output=True, text=True, check=True, env=os.environ.copy())
+        row = json.loads(out.stdout)['accounts'][0]
+        self.assertEqual(row['status'], 'active')
+        self.assertEqual(row['credential_class'], 'machine-local')
+        self.assertEqual(row['credentials']['oauth_store'], 'keychain')
+        self.assertEqual(row['credentials']['keychain'], 'readable')
+        env = dict(os.environ, FAKE_KEYCHAIN_LOCKED='1')
+        out = subprocess.run(
+            [sys.executable, str(REPO / 'lib' / 'report.py'), str(self.root),
+             'claude', 'mac', 'list'],
+            capture_output=True, text=True, check=True, env=env)
+        row = json.loads(out.stdout)['accounts'][0]
+        self.assertEqual(row['status'], 'locked')
+        self.assertEqual(row['credential_class'], 'machine-local')
+        self.assertFalse(row['selectable'])
+        self.assertFalse(row['needs_login'])
+
+
+if __name__ == '__main__':
+    unittest.main()