Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* macOS Keychain secret store — the engine.
*
* A dependency-light wrapper over `/usr/bin/security` that stores one generic-
* password item per API-key env var:
*
* service = "claudish"
* account = the env var name e.g. GEMINI_API_KEY
* label = "claudish: GEMINI_API_KEY" (findable in Keychain Access.app)
* value = the secret (UTF-8, no control characters — see below)
*
* One item per variable rather than a single JSON blob: individually visible,
* individually deletable, individually ACL'd by macOS. The blob layout would
* collapse N spawns into one, but `dump-keychain` already collapses the only
* operation that needed N — enumeration — so the blob buys nothing and costs
* discoverability.
*
* WHY THE `security` CLI AND NOT A NATIVE BINDING
*
* A keychain item's ACL is bound to the code signature of the binary that
* accesses it. `/usr/bin/security` is Apple-signed and its path is stable, so a
* value written through it reads back through it without a new authorization
* dialog. A native binding inside a `bun`-compiled executable presents a
* DIFFERENT identity that changes with every rebuild and every `bun` upgrade —
* which macOS surfaces as a fresh "claudish wants to access your keychain"
* prompt each time. The subprocess is the less elegant option and the only one
* that stays quiet.
*
* MEASURED COSTS (darwin 25.6.0; transcripts in
* ai-docs/reports/keychain-security-cli-measurements.md)
*
* find-generic-password -w 17.4 ms per call, per variable
* dump-keychain (no -d) 28 ms ONCE, for the entire item list
*
* That gap is the whole architecture. A per-variable read cannot sit on a
* synchronous path — 25 providers would cost ~435 ms against a provider-
* registration pass that runs in ~1.5-2 ms. Enumeration can: it answers
* "which variables are stored?" for every provider in a single spawn.
* `dump-keychain` reads item ATTRIBUTES only and never item DATA, which is why
* it is prompt-free while a value read is not.
*
* WHY SECRETS GO ON STDIN
*
* `security add-generic-password -w <secret>` puts the secret in the process's
* argv, where any other user on the machine can read it out of `ps` for the
* duration of the call. Writes therefore go through `security -i`, which reads
* the command itself from stdin, with the value carried as `-X <hex>` so no
* shell-style quoting of quotes/backslashes/spaces is ever required.
*
* The documented alternative — `-w` passed LAST so `security` prompts for the
* value — was measured and REJECTED: it demands the password twice, a single
* piped line fails the confirmation, and it then exits 0 having created an item
* with an EMPTY value. A write path that reports success while storing nothing
* is worse than no write path at all.
*
* WHY CONTROL CHARACTERS ARE REJECTED
*
* `find-generic-password -w` prints the value as RAW text for printable data
* but as a HEX STRING when the data contains control characters, with nothing
* in the output to distinguish the two — a printable key that happens to be all
* hex digits is genuinely ambiguous. Rather than guess at read time, values
* containing control characters are refused at WRITE time, which makes every
* stored value unambiguous by construction. API keys are single-line printable
* tokens, so this rejects nothing a user actually has.
*
* Every side effect is behind an injectable `KeychainDeps` seam, so the module
* is fully testable with no real keychain. Same rationale as
* `auth/antigravity-token.ts`, which reads the SHARED agy/claudish token item
* and is the existing precedent for talking to `security` from this codebase.
*/
/** Keychain service name for every item claudish owns. */
export const KEYCHAIN_SERVICE = "claudish";
/** Absolute path — `security` must not be resolved through a mutable PATH. */
const SECURITY_BIN = "/usr/bin/security";
/**
* `security` exit code for "the specified item could not be found".
*
* Distinguishing it from a real failure is what lets a miss stay silent while a
* genuine error (locked keychain, denied ACL, missing binary) still surfaces.
* Measured, not assumed: both a `find` miss and a `delete` of an absent item
* exit 44.
*/
const EXIT_ITEM_NOT_FOUND = 44;
/**
* Burst memo TTL.
*
* A process-lifetime cache would be WRONG: the user can edit the keychain in
* Keychain Access.app, and another claudish process can write it, while this
* one runs. The goal is collapsing repeated asks inside ONE operation (a TUI
* render pass, a routing chain walking several candidate providers), not
* caching across a session. Mirrors `antigravity-token.ts`'s READ_STORE_TTL_MS
* for the same reason.
*/
const MEMO_TTL_MS = 3000;
/**
* Hard ceiling on any single `security` invocation.
*
* A keychain call that hangs must not hang claudish. The measured cost of every
* operation here is 17-30 ms, so ten seconds means something is genuinely wrong
* — most plausibly a LOCKED keychain, where `security` blocks on an unlock
* dialog that a proxy server or an MCP child has no way to answer. `syncRun`
* blocks the event loop outright, so without this a locked keychain would
* freeze the process indefinitely.
*
* Verified that `Bun.spawnSync` honours it: a 1s timeout on `sleep 5` returned
* in 1002ms with `exitCode: null, signal: "SIGTERM"` — which `normalizeResult`
* reports as a signal kill rather than inventing an exit code.
*
* This guard was briefly LOST in the move from `execFileSync` (which carried its
* own `timeout` option) to `Bun.spawnSync`, which is the kind of thing a
* mechanical port drops silently.
*/
const SPAWN_TIMEOUT_MS = 10_000;
// ---------------------------------------------------------------------------
// Errors
// ---------------------------------------------------------------------------
/** A keychain operation failed for a reason the caller should show the user. */
export class KeychainError extends Error {
constructor(
message: string,
/** `security`'s exit code, when the failure came from the binary. */
readonly exitCode?: number
) {
super(message);
this.name = "KeychainError";
}
}
// ---------------------------------------------------------------------------
// Injectable side-effect seam
// ---------------------------------------------------------------------------
export interface KeychainRunResult {
code: number;
stdout: string;
stderr: string;
}
export interface KeychainDeps {
/** `process.platform`, injectable so tests can exercise the non-darwin path. */
platform: () => string;
/** Run `security` with the given argv; `stdin` is written to its stdin when set. */
run: (args: string[], stdin?: string) => KeychainRunResult;
/** Async form, used by the parallel hydration pass. */
runAsync: (args: string[], stdin?: string) => Promise<KeychainRunResult>;
/**
* Start `security` and hand back its completion as a JOINABLE handle, with NO
* deadline and NO kill path. `done` resolves only when `security` itself
* exits — never rejects — and `pid` is the child's pid (undefined when the
* spawn failed). See {@link KeychainSpawn}.
*/
spawnAsync: (args: string[], stdin?: string) => KeychainSpawn;
}
/**
* One `security` run that may outlive whoever started it.
*
* WHY NO DEADLINE AND NO KILL. A value read of an item another application owns
* (`find-generic-password -w`) can open the macOS access dialog, and the user
* may take minutes to answer it. `runAsync`'s `SPAWN_TIMEOUT_MS` would KILL
* `security` at ten seconds, and a `security` killed mid-transaction is how
* this codebase once made macOS restart `securityd`, which dropped every
* running application's keychain session (keychain.md, "NEVER verify against
* the real login keychain"). Killing it also throws away the user's answer:
* the dialog stays up, and a click on "Always Allow" lands on a process that is
* gone.
*
* So the handle is the contract. A caller races `done` against ITS OWN
* deadline and, when the deadline wins, simply stops waiting: `done` stays
* alive, a late approval still resolves it, and the next caller can JOIN the
* same `done` instead of spawning a second dialog. `pid` lets a caller record
* which `security` holds the dialog (a per-machine lock names the child, not
* the claudish process that may exit first).
*/
export interface KeychainSpawn {
done: Promise<KeychainRunResult>;
pid: number | undefined;
}
/**
* WHY `Bun.spawnSync` AND NOT `execFileSync` — this one is measured, and it is
* the difference between the write working and the config TUI freezing.
*
* Node's `execFileSync(..., { input })` HANGS when the parent's stdin is in raw
* mode or has an active `data` listener — which is exactly what any TUI does.
* Measured inside the config TUI: the call blocked for the full timeout and came
* back `status: null, signal: "SIGTERM", code: "ETIMEDOUT"`, with EMPTY stderr.
* Because it is synchronous, it froze the whole interface for ten seconds first.
* The identical code path succeeds from a plain CLI process, so this cannot be
* caught anywhere except by driving the real TUI.
*
* `Bun.spawnSync` with a `Uint8Array` stdin has no such interaction — verified
* under raw mode WITH a data listener attached: exit 0 in ~30ms, value round-
* tripped. Bun's native spawn is also what the rest of claudish relies on, and
* the launcher (`bin/claudish.cjs`) refuses to run under Node at all, so the
* `Bun` global is guaranteed here.
*
* stderr is ALWAYS piped, never inherited. The most common keychain operation —
* a lookup that misses — writes "SecKeychainSearchCopyNext: The specified item
* could not be found" to it. Inheriting that would spray one line per provider
* per resolution pass into a terminal claudish SHARES with the Claude Code TUI,
* which is how this codebase corrupted its own display once already (see
* terminal-isolation.ts).
*/
function syncRun(args: string[], stdin?: string): KeychainRunResult {
try {
const proc = Bun.spawnSync([SECURITY_BIN, ...args], {
stdin: stdin === undefined ? "ignore" : new TextEncoder().encode(stdin),
stdout: "pipe",
stderr: "pipe",
timeout: SPAWN_TIMEOUT_MS,
});
return normalizeResult(
proc.exitCode,
proc.signalCode,
decode(proc.stdout),
decode(proc.stderr)
);
} catch (err) {
// A throw here means the spawn itself failed (binary missing, EPERM) — the
// message is the only diagnostic there is, so it must not be discarded.
return { code: 1, stdout: "", stderr: err instanceof Error ? err.message : String(err) };
}
}
async function asyncRun(args: string[], stdin?: string): Promise<KeychainRunResult> {
try {
const proc = Bun.spawn([SECURITY_BIN, ...args], {
stdin: stdin === undefined ? "ignore" : new TextEncoder().encode(stdin),
stdout: "pipe",
stderr: "pipe",
timeout: SPAWN_TIMEOUT_MS,
});
const [stdout, stderr, exitCode] = await Promise.all([
new Response(proc.stdout).text(),
new Response(proc.stderr).text(),
proc.exited,
]);
return normalizeResult(exitCode, proc.signalCode, stdout, stderr);
} catch (err) {
return { code: 1, stdout: "", stderr: err instanceof Error ? err.message : String(err) };
}
}
/**
* {@link KeychainDeps.spawnAsync}: no `timeout` option, no `kill()`, anywhere.
* stderr piped for the same reason as `syncRun`. A spawn that cannot start
* resolves `done` with the error, as `asyncRun` reports it.
*/
function spawnAsyncRun(args: string[], stdin?: string): KeychainSpawn {
try {
const proc = Bun.spawn([SECURITY_BIN, ...args], {
stdin: stdin === undefined ? "ignore" : new TextEncoder().encode(stdin),
stdout: "pipe",
stderr: "pipe",
});
const done = Promise.all([
new Response(proc.stdout).text(),
new Response(proc.stderr).text(),
proc.exited,
]).then(
([stdout, stderr, exitCode]) => normalizeResult(exitCode, proc.signalCode, stdout, stderr),
(err: unknown) => ({
code: 1,
stdout: "",
stderr: err instanceof Error ? err.message : String(err),
})
);
return { done, pid: proc.pid };
} catch (err) {
return {
done: Promise.resolve({
code: 1,
stdout: "",
stderr: err instanceof Error ? err.message : String(err),
}),
pid: undefined,
};
}
}
function decode(buf: Uint8Array | null | undefined): string {
return buf ? new TextDecoder().decode(buf) : "";
}
/**
* Turn a spawn outcome into a result, WITHOUT inventing an exit code.
*
* A process killed by a signal reports `exitCode: null`. An earlier version
* collapsed that to `1` and produced the message "security exited 1" for what
* was actually a ten-second timeout — a fabricated exit code that sent the
* investigation in the wrong direction. When there is no real exit code, say so
* and name the signal instead.
*/
function normalizeResult(
exitCode: number | null,
signalCode: string | null | undefined,
stdout: string,
stderr: string
): KeychainRunResult {
if (typeof exitCode === "number") return { code: exitCode, stdout, stderr };
const detail = signalCode ? `killed by ${signalCode}` : "terminated without an exit code";
return { code: -1, stdout, stderr: stderr.trim() || `security ${detail}` };
}
const defaultDeps: KeychainDeps = {
platform: () => process.platform,
run: syncRun,
runAsync: asyncRun,
spawnAsync: spawnAsyncRun,
};
let deps: KeychainDeps = defaultDeps;
/**
* Replace the side-effect seam. Pass `null` to restore the real one.
* MANDATORY in tests — otherwise the suite mutates the developer's own keychain.
*/
export function setKeychainTestDeps(next: Partial<KeychainDeps> | null): void {
deps = next ? { ...defaultDeps, ...next } : defaultDeps;
invalidateKeychainCache();
}
// ---------------------------------------------------------------------------
// Memo
// ---------------------------------------------------------------------------
let listMemo: { at: number; value: KeychainEnumeration } | null = null;
const valueMemo = new Map<string, { at: number; value: string | null }>();
/** Drop every memo. Call after ANY mutation, and after swapping the deps seam. */
export function invalidateKeychainCache(): void {
listMemo = null;
valueMemo.clear();
}
function now(): number {
return Date.now();
}
// ---------------------------------------------------------------------------
// Validation
// ---------------------------------------------------------------------------
/**
* C0 controls plus DEL. Deliberately includes tab, newline and carriage return:
* see the module header — their presence is what flips `-w` from raw output to
* hex output, and no API key contains them.
*
* The `noControlCharactersInRegex` suppression below is intentional and narrow:
* matching control characters IS this expression's entire purpose, so the rule's
* usual "you probably meant something else" assumption is inverted here. It must
* stay a SINGLE line — Biome only attaches a suppression to the statement
* immediately following it, and continuation lines silently detach it.
*/
// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the purpose — this guard is what keeps `security -w` reads unambiguous
const CONTROL_CHARS = /[\u0000-\u001F\u007F]/;
/** Conventional env-var spelling. Anything else cannot be an API-key variable. */
const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
export function isValidKeychainVarName(name: string): boolean {
return ENV_VAR_NAME.test(name);
}
/**
* Why a value cannot be stored, or null when it can.
* Exported so callers can pre-validate a batch (e.g. `keychain import`'s plan)
* without attempting a write per entry.
*/
export function describeUnstorableValue(value: string): string | null {
if (value.length === 0) return "value is empty";
if (CONTROL_CHARS.test(value)) {
return "value contains control characters (tab/newline/etc), which the keychain read path cannot represent unambiguously";
}
return null;
}
// ---------------------------------------------------------------------------
// Platform
// ---------------------------------------------------------------------------
/** True when this platform has a macOS keychain claudish can drive. */
export function isKeychainSupported(): boolean {
return deps.platform() === "darwin";
}
/** The reason keychain is unavailable, or null when it is available. */
export function keychainUnavailableReason(): string | null {
if (!isKeychainSupported()) {
return `the macOS Keychain is only available on macOS (this is ${deps.platform()})`;
}
return null;
}
// ---------------------------------------------------------------------------
// Read
// ---------------------------------------------------------------------------
/**
* `security -w` appends exactly one newline to the value.
*
* Stripping ONE trailing "\n" rather than calling `.trim()` is deliberate: trim
* would also eat whitespace that is genuinely part of a stored secret, turning
* a working key into a subtly broken one that fails with a 401 nobody can
* explain.
*/
function stripOneTrailingNewline(out: string): string {
return out.endsWith("\n") ? out.slice(0, -1) : out;
}
/**
* Target keychain FILE, when `CLAUDISH_KEYCHAIN_FILE` names one.
*
* `security` takes an optional trailing keychain path on every subcommand;
* without one it uses the user's default (login) keychain. Setting this env var
* redirects every operation in this module to a throwaway keychain instead.
*
* WHY THIS EXISTS. End-to-end verification against the REAL login keychain is
* not safe: during development of this module, hung `security` processes were
* killed mid-transaction and macOS restarted `securityd`, which drops every
* running application's authenticated keychain session and produces a storm of
* re-authorization prompts across the whole machine. Nothing was lost and no
* ACL was altered, but it disrupted the user's entire desktop.
*
* Unit tests use the `KeychainDeps` seam and never spawn anything. But live
* verification is still worth doing — it is what caught the `execFileSync`
* raw-mode hang, which no seam-based test could have surfaced — so it needs a
* safe target rather than care and good intentions. Point this at a keychain
* created with `security create-keychain` and the blast radius is that file.
*
* Read at CALL time, not captured at module load, so a test can set it after
* import.
*/
function keychainFileArgs(): string[] {
const file = process.env.CLAUDISH_KEYCHAIN_FILE;
return file ? [file] : [];
}
function findArgs(envVar: string): string[] {
return [
"find-generic-password",
"-s",
KEYCHAIN_SERVICE,
"-a",
envVar,
"-w",
...keychainFileArgs(),
];
}
/** Interpret a `find-generic-password -w` result. Throws on a real failure. */
function interpretRead(envVar: string, res: KeychainRunResult): string | null {
if (res.code === 0) {
const value = stripOneTrailingNewline(res.stdout);
return value.length > 0 ? value : null;
}
if (res.code === EXIT_ITEM_NOT_FOUND) return null;
throw new KeychainError(
`Keychain lookup for ${envVar} failed: ${res.stderr.trim() || `security exited ${res.code}`}`,
res.code
);
}
/**
* The stored secret for `envVar`, or null when absent.
*
* SYNCHRONOUS and ~17 ms. Never call this once per provider on a render or
* registration path — use {@link listKeychainVars} for presence, which answers
* for every provider in one spawn.
*/
export function readKeychainSecret(envVar: string): string | null {
if (!isKeychainSupported()) return null;
const cached = valueMemo.get(envVar);
const at = now();
if (cached && at - cached.at < MEMO_TTL_MS) return cached.value;
const value = interpretRead(envVar, deps.run(findArgs(envVar)));
// Memoize the MISS too: "not stored" is the answer that repeats hardest,
// and it costs a full failed spawn every time.
valueMemo.set(envVar, { at, value });
return value;
}
/** Async twin of {@link readKeychainSecret}, for parallel batch hydration. */
export async function readKeychainSecretAsync(envVar: string): Promise<string | null> {
if (!isKeychainSupported()) return null;
const cached = valueMemo.get(envVar);
const at = now();
if (cached && at - cached.at < MEMO_TTL_MS) return cached.value;
const value = interpretRead(envVar, await deps.runAsync(findArgs(envVar)));
valueMemo.set(envVar, { at, value });
return value;
}
// ---------------------------------------------------------------------------
// Another application's generic-password item (joinable, no kill path)
// ---------------------------------------------------------------------------
/** Which generic-password item, in which keychain file. */
export interface GenericPasswordQuery {
service: string;
account?: string;
/**
* A keychain FILE to search instead of the default search list. Absent:
* `CLAUDISH_KEYCHAIN_FILE` when set, else the user's default keychains.
*/
keychainFile?: string;
}
/** The outcome of one item lookup. `failed` is never collapsed into `absent`. */
export type GenericPasswordResult =
| { kind: "found"; value?: string }
| { kind: "absent" }
| { kind: "failed"; code: number; error: string };
function genericPasswordArgs(query: GenericPasswordQuery, withValue: boolean): string[] {
return [
"find-generic-password",
"-s",
query.service,
...(query.account !== undefined ? ["-a", query.account] : []),
...(withValue ? ["-w"] : []),
...(query.keychainFile !== undefined ? [query.keychainFile] : keychainFileArgs()),
];
}
function interpretGenericPassword(
res: KeychainRunResult,
withValue: boolean
): GenericPasswordResult {
if (res.code === 0) {
if (!withValue) return { kind: "found" };
const value = stripOneTrailingNewline(res.stdout);
return value.length > 0 ? { kind: "found", value } : { kind: "absent" };
}
if (res.code === EXIT_ITEM_NOT_FOUND) return { kind: "absent" };
return {
kind: "failed",
code: res.code,
error: res.stderr.trim() || `security exited ${res.code}`,
};
}
/**
* Whether an item exists, from its ATTRIBUTES only: `find-generic-password`
* without `-w` reads no item data, so it opens no access dialog. Async, and
* through {@link KeychainDeps.spawnAsync}, so nothing ever kills it; it is
* never on a render path. stdout (the attribute dump) is discarded here.
*/
export async function findGenericPasswordPresence(
query: GenericPasswordQuery
): Promise<GenericPasswordResult> {
if (!isKeychainSupported()) return { kind: "absent" };
const res = await deps.spawnAsync(genericPasswordArgs(query, false)).done;
return interpretGenericPassword(res, false);
}
/**
* Start a VALUE read of an item (`find-generic-password -w`). This may open the
* macOS access dialog for an item another application owns, so it returns the
* joinable handle rather than a promise with a deadline: the caller races
* `done` against its own deadline, never kills `security`, and a later caller
* may join the same `done` (see {@link KeychainSpawn}). The value is never
* memoized here; the caller decides what to keep.
*/
export function startGenericPasswordRead(query: GenericPasswordQuery): {
done: Promise<GenericPasswordResult>;
pid: number | undefined;
} {
if (!isKeychainSupported()) {
return { done: Promise.resolve({ kind: "absent" }), pid: undefined };
}
const spawn = deps.spawnAsync(genericPasswordArgs(query, true));
return { done: spawn.done.then((res) => interpretGenericPassword(res, true)), pid: spawn.pid };
}
// ---------------------------------------------------------------------------
// Enumerate
// ---------------------------------------------------------------------------
/**
* `dump-keychain` renders a blob attribute either as `="text"` or, when the
* bytes are not printable ASCII, as `=0x48656C6C6F "Hello"`. Both forms end in
* the quoted rendering, so one pattern covers them.
*/
const ACCT_ATTR = /"acct"<blob>=(?:0x[0-9A-Fa-f]*\s+)?"([^"]*)"/;
/** Exact service match — `="claudish"` must not also match `="claudish-foo"`. */
const SVCE_MATCH = `"svce"<blob>="${KEYCHAIN_SERVICE}"`;
/**
* The result of an enumeration attempt.
*
* `failed` is the whole point of this type. An earlier version collapsed a
* failed `dump-keychain` into an empty array, which is a LIE with consequences
* that compound: a locked store reads as "nothing stored", so the credential
* source reports a clean absence rather than a transient failure, so the
* authority caches the miss for the process lifetime, so predefined endpoints
* silently vanish — and, worst of all, `keychain import` builds its
* overwrite plan from that false-empty set and reports every existing key as
* `new`, then overwrites it with `-U` without ever showing the warning that
* exists precisely to prevent an unrecoverable replacement.
*
* "I could not ask" and "there is nothing there" must never be the same value.
*/
export interface KeychainEnumeration {
/** Stored env var names, sorted. Empty when `failed` is true. */
names: string[];
/** True when the keychain could not be enumerated (locked, denied, no binary). */
failed: boolean;
/** Diagnostic for the failure. Never contains key material. */
error?: string;
}
/**
* Every env var name claudish has stored in the keychain, plus whether the
* question could be answered at all.
*
* ONE spawn (~28 ms) for the whole list, memoized for the burst. This is the
* function that makes a synchronous presence check affordable, and it is the
* reason no mirror of these names is kept in `config.json`: a second copy of a
* list is a second thing that can be wrong, and this list is cheap enough to
* read from the store that owns it.
*
* Attributes only — `dump-keychain` is invoked WITHOUT `-d`, so it never reads
* item DATA and never triggers a per-item access dialog.
*
* Does not throw: a failure is DATA here, because the callers are render paths
* and a provider-registration pass that must not die over a diagnostic. The
* memo caches the failure too — deliberately, since a locked keychain stays
* locked and re-spawning per provider would achieve nothing — but only for the
* 3-second burst window, so it re-tries as soon as the burst ends.
*/
export function enumerateKeychainVars(): KeychainEnumeration {
if (!isKeychainSupported()) return { names: [], failed: false };
const at = now();
if (listMemo && at - listMemo.at < MEMO_TTL_MS) return listMemo.value;
const res = deps.run(["dump-keychain", ...keychainFileArgs()]);
const value: KeychainEnumeration =
res.code === 0
? { names: parseDumpAccounts(res.stdout), failed: false }
: {
names: [],
failed: true,
error: res.stderr.trim() || `security exited ${res.code}`,
};
listMemo = { at, value };
return value;
}
/**
* Stored env var names, sorted — the names ONLY.
*
* Callers that can act differently on "could not enumerate" must use
* {@link enumerateKeychainVars} instead; this convenience wrapper cannot
* distinguish an empty store from an unreachable one.
*/
export function listKeychainVars(): string[] {
return enumerateKeychainVars().names;
}
/** Exported for tests: parse `dump-keychain` output into claudish's accounts. */
export function parseDumpAccounts(dump: string): string[] {
const found = new Set<string>();
for (const block of dump.split(/\nkeychain: /)) {
if (!block.includes(SVCE_MATCH)) continue;
const m = block.match(ACCT_ATTR);
if (m?.[1] && isValidKeychainVarName(m[1])) found.add(m[1]);
}
return Array.from(found).sort();
}
/** True when `envVar` has a stored keychain value. One spawn for ALL providers. */
export function keychainHasVar(envVar: string): boolean {
return lookupKeychainVar(envVar).present;
}
/**
* Presence for `envVar`, carrying whether the store could be consulted at all.
*
* `{present: false, failed: true}` means "unknown", NOT "absent" — the caller
* decides what to do with that. Collapsing the two is what turned a locked
* keychain into a silent, cached "no credential here" for the whole process.
*/
export function lookupKeychainVar(envVar: string): { present: boolean; failed: boolean } {
if (!isKeychainSupported()) return { present: false, failed: false };
// Prefer a memoized VALUE when one is already present: after a write or a
// resolve, the value memo is the fresher of the two, and consulting it avoids
// a dump for a question that has already been answered exactly. It also
// answers correctly while enumeration is failing.
const cached = valueMemo.get(envVar);
if (cached && now() - cached.at < MEMO_TTL_MS && cached.value !== null) {
return { present: true, failed: false };
}
const listed = enumerateKeychainVars();
return { present: listed.names.includes(envVar), failed: listed.failed };
}
// ---------------------------------------------------------------------------
// Write / delete
// ---------------------------------------------------------------------------
function toHex(value: string): string {
return Buffer.from(value, "utf8").toString("hex");
}
/**
* Quote one argument for `security -i`, which parses its stdin line with
* shell-like tokenization.
*
* Unquoted values SPLIT ON WHITESPACE — which silently turned the item label
* ("claudish: GEMINI_API_KEY") and the comment ("Stored by claudish") into
* stray positional tokens and made every write fail with a usage dump. Values
* are quoted uniformly rather than only where a space is expected today,
* because "this particular string can't contain a space" is the kind of
* assumption that stops being true one refactor later.
*
* The secret itself travels as hex and needs none of this; it is quoted anyway
* so no argument is a special case.
*/
function quoteForStdin(value: string): string {
return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
}
/**
* Store (or replace) `envVar`'s secret.
*
* The command goes over stdin so the secret never reaches argv; `-X` carries it
* as hex so no quoting is needed; `-U` upserts (without it, a second write to
* the same account fails with -25299); `-T /usr/bin/security` pins the ACL to
* the same Apple-signed binary every read uses, which is what keeps subsequent
* reads dialog-free.
*
* The write is VERIFIED by reading the value back. macOS imposes its own limits
* on item data, and rather than hard-code a size ceiling this cannot verify,
* the round-trip proves the store actually holds what the user was told it
* holds. ~17 ms extra on an operation that happens once per key.
*/
export function writeKeychainSecret(envVar: string, value: string): void {
const unsupported = keychainUnavailableReason();
if (unsupported) throw new KeychainError(`Cannot write ${envVar}: ${unsupported}`);
if (!isValidKeychainVarName(envVar)) {
throw new KeychainError(`Cannot write "${envVar}": not a valid environment variable name`);
}
const unstorable = describeUnstorableValue(value);
if (unstorable) throw new KeychainError(`Cannot store ${envVar}: ${unstorable}`);
// Invalidate BEFORE the write, so a throwing `security` still leaves the memo
// dropped rather than serving a value the store may or may not still hold.
invalidateKeychainCache();
const cmd = [
"add-generic-password",
"-s",
quoteForStdin(KEYCHAIN_SERVICE),
"-a",
quoteForStdin(envVar),
"-l",
quoteForStdin(`${KEYCHAIN_SERVICE}: ${envVar}`),
"-D",
quoteForStdin("application password"),
"-j",
quoteForStdin("Stored by claudish"),
"-X",
quoteForStdin(toHex(value)),
"-U",
"-T",
quoteForStdin(SECURITY_BIN),
// Trailing keychain path, when one is targeted. Must come LAST — `security`
// treats the final positional argument as the keychain to operate on.
...keychainFileArgs().map(quoteForStdin),
].join(" ");
const res = deps.run(["-i"], `${cmd}\n`);
if (res.code !== 0) {
throw new KeychainError(
`Failed to store ${envVar} in the keychain: ${res.stderr.trim() || `security exited ${res.code}`}`,
res.code
);
}
invalidateKeychainCache();
const readBack = readKeychainSecret(envVar);
if (readBack !== value) {
throw new KeychainError(
`Keychain write for ${envVar} did not round-trip — the stored value differs from what was written. ` +
"The item may exceed the keychain's size limit; nothing should be assumed saved."
);
}
}
/**
* Remove `envVar` from the keychain. Returns true when an item was deleted,
* false when there was nothing there. Idempotent by design — "remove this key"
* succeeding on an already-absent key is the behaviour every caller wants.
*/
export function deleteKeychainSecret(envVar: string): boolean {
if (!isKeychainSupported()) return false;
invalidateKeychainCache();
const res = deps.run([
"delete-generic-password",
"-s",
KEYCHAIN_SERVICE,
"-a",
envVar,
...keychainFileArgs(),
]);
invalidateKeychainCache();
if (res.code === 0) return true;
if (res.code === EXIT_ITEM_NOT_FOUND) return false;
throw new KeychainError(
`Failed to delete ${envVar} from the keychain: ${res.stderr.trim() || `security exited ${res.code}`}`,
res.code
);
}
// ---------------------------------------------------------------------------
// Display helpers
// ---------------------------------------------------------------------------
/**
* Last-4 identification tail, the "••••1234" pattern the 1Password tab already
* uses so a user can confirm WHICH credential is wired up. Never returns more
* than four characters of the secret, and returns none at all for a value short
* enough that four characters would be most of it.
*/
export function valueTail(value: string): string {
if (value.length <= 6) return "••••";
return `••••${value.slice(-4)}`;
}