claude-autorouter 0.3.7 → 0.5.0

package/src/telemetry-event.mjs

@@ -0,0 +1,200 @@
+// @ts-check
+import { redactSensitive } from './redaction.mjs';
+// Shared, bounded telemetry contract. Never copy request bodies, headers, raw
+// errors or arbitrary provider fields into status snapshots or saved history.
+export const TELEMETRY_SCHEMA_VERSION = 2;
+export const UNPRICED_REASONS = Object.freeze(['request_failed', 'request_cancelled', 'request_evicted',
+  'unknown_baseline', 'unknown_model', 'missing_model', 'missing_usage', 'invalid_usage',
+  'conflicting_usage', 'mixed_models', 'unsupported_pricing', 'invalid_telemetry',
+  'unknown_pricing_version', 'unconfirmed_completion', 'incomplete_usage', 'missing_outcome']);
+const EVENTS = new Set(['request_start', 'route', 'upstream_response', 'upstream_model', 'upstream_usage',
+  'upstream_error', 'request_complete', 'request_error', 'request_cancelled']);
+const SOURCES = new Set(['jev', 'ollama', 'cache', 'fallback', 'passthrough']);
+const ERRORS = new Set(['invalid_request_error', 'authentication_error', 'billing_error', 'permission_error',
+  'not_found_error', 'request_too_large', 'rate_limit_error', 'api_error', 'overloaded_error', 'timeout_error',
+  'unknown_error', 'http_error', 'request_error']);
+const CLASSIFIER_ERRORS = new Set(['timeout', 'http_error', 'invalid_response', 'network_error', 'capacity_exhausted']);
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+export const sanitizeIdentifier = value => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,200}$/.test(value) ? value : undefined;
+export const sanitizeModel = value => typeof value === 'string' && /^[A-Za-z0-9_.:/-]{1,120}$/.test(value) ? value : undefined;
+const code = value => typeof value === 'string' && /^[a-z][a-z0-9_]{0,79}$/.test(value) ? value : undefined;
+const count = value => Number.isSafeInteger(value) && value >= 0;
+const latency = value => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+const httpStatus = value => Number.isInteger(value) && value >= 100 && value <= 599;
+const absent = value => value === undefined || value === null || value === '';
+const assign = (row, field, value) => { if (value !== undefined) row[field] = value; };
+
+export function normalizePricingContext(value) {
+  if (value === undefined) return;
+  if (!object(value)) return { pricing_unsupported: true };
+  const row = {};
+  for (const [key, allowed] of Object.entries({ speed: ['standard', 'fast'],
+    inference_geo: ['global', 'us', 'not_available'], service_tier: ['auto', 'standard_only', 'standard', 'priority', 'batch'] })) {
+    if (!Object.hasOwn(value, key)) continue;
+    if (allowed.includes(value[key])) row[key] = value[key];
+    else row.pricing_unsupported = true;
+  }
+  for (const key of ['pricing_unsupported', 'unsupported']) {
+    if (Object.hasOwn(value, key) && value[key] !== false) row.pricing_unsupported = true;
+  }
+  return row;
+}
+
+export function normalizeUsageTelemetry(value) {
+  if (value === undefined) return;
+  if (!object(value)) return { pricing_unsupported: true };
+  /** @type {Record<string,any>} */
+  const row = { ...normalizePricingContext(value) };
+  for (const key of ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens']) {
+    if (!Object.hasOwn(value, key)) continue;
+    if (count(value[key])) row[key] = value[key];
+    else row.pricing_unsupported = true;
+  }
+  if (Object.hasOwn(value, 'cache_creation')) {
+    if (value.cache_creation === null && value.cache_creation_input_tokens === 0) { /* no cache writes */ }
+    else if (!object(value.cache_creation)) row.pricing_unsupported = true;
+    else {
+      row.cache_creation = {};
+      for (const key of ['ephemeral_5m_input_tokens', 'ephemeral_1h_input_tokens']) {
+        if (!Object.hasOwn(value.cache_creation, key)) continue;
+        if (count(value.cache_creation[key])) row.cache_creation[key] = value.cache_creation[key];
+        else row.pricing_unsupported = true;
+      }
+    }
+  }
+  return row;
+}
+
+function reasons(value) {
+  if (!object(value)) return;
+  return Object.fromEntries(UNPRICED_REASONS.filter(key => count(value[key])).map(key => [key, value[key]]));
+}
+
+function normalizeSavings(value) {
+  if (!object(value)) return;
+  const row = {};
+  assign(row, 'baseline_model', sanitizeModel(value.baseline_model));
+  for (const key of ['actual_usd', 'baseline_usd', 'saved_usd', 'percent']) {
+    if (typeof value[key] === 'number' && Number.isFinite(value[key]) && Math.abs(value[key]) <= 1e18
+      && (!['actual_usd', 'baseline_usd'].includes(key) || value[key] >= 0)) row[key] = value[key];
+  }
+  for (const key of ['requests', 'priced_requests', 'unpriced_requests']) if (count(value[key])) row[key] = value[key];
+  if (value.partial === true) row.partial = true;
+  if (typeof value.pricing_version === 'string' && /^[A-Za-z0-9_.-]{1,40}$/.test(value.pricing_version)) row.pricing_version = value.pricing_version;
+  if (typeof value.pricing_date === 'string' && /^\d{4}-\d\d-\d\d$/.test(value.pricing_date)) row.pricing_date = value.pricing_date;
+  // Provenance is a maintained public URL, never an arbitrary URL that might
+  // contain credentials or a private endpoint.
+  if (value.pricing_source === 'https://platform.claude.com/docs/en/about-claude/pricing') row.pricing_source = value.pricing_source;
+  assign(row, 'unpriced_reasons', reasons(value.unpriced_reasons));
+  return row;
+}
+
+function timestamp(value) {
+  return typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value)
+    && Number.isFinite(Date.parse(value)) ? value : new Date().toISOString();
+}
+
+/**
+ * @template {import('./contracts.mjs').LifecycleName|'decision'|'outcome'} T
+ * @param {any} entry
+ * @param {T} event
+ * @returns {(import('./contracts.mjs').TelemetryFields & {event:T,request_id:string})|undefined}
+ */
+function base(entry, event) {
+  const requestId = sanitizeIdentifier(entry.request_id);
+  if (!requestId) return;
+  /** @type {import('./contracts.mjs').TelemetryFields & {event:T,request_id:string}} */
+  const row = { schema_version: TELEMETRY_SCHEMA_VERSION, event, timestamp: timestamp(entry.timestamp), request_id: requestId };
+  for (const key of ['session_id', 'agent_id', 'prompt_id']) {
+    if (absent(entry[key])) continue;
+    const value = sanitizeIdentifier(entry[key]);
+    // Reject invalid explicit identities instead of merging them into the
+    // anonymous session or treating an unknown agent as the foreground UI.
+    if (!value) return;
+    row[key] = value;
+  }
+  if (!absent(entry.request_class)) {
+    const requestClass = code(entry.request_class);
+    if (!requestClass) return;
+    row.request_class = requestClass;
+  }
+  for (const key of ['requested_model', 'selected_model', 'confirmed_model', 'model', 'baseline_model']) assign(row, key, sanitizeModel(entry[key]));
+  if (typeof entry.pricing_version === 'string' && /^[A-Za-z0-9_.-]{1,40}$/.test(entry.pricing_version)) row.pricing_version = entry.pricing_version;
+  for (const key of ['reason', 'compatibility_reason', 'continuity_state']) assign(row, key, code(entry[key]));
+  if (SOURCES.has(entry.source)) row.source = entry.source;
+  if (['jev', 'ollama'].includes(entry.evaluator)) row.evaluator = entry.evaluator;
+  for (const key of ['tier', 'classified_tier']) if (['haiku', 'sonnet', 'opus'].includes(entry[key])) row[key] = entry[key];
+  for (const key of ['latency_ms', 'evaluation_latency_ms', 'routing_latency_ms', 'decision_latency_ms',
+    'first_response_ms', 'upstream_latency_ms', 'total_latency_ms']) if (latency(entry[key])) row[key] = entry[key];
+  if (CLASSIFIER_ERRORS.has(entry.classifier_error)) row.classifier_error = entry.classifier_error;
+  if (httpStatus(entry.classifier_status)) row.classifier_status = entry.classifier_status;
+  if (ERRORS.has(entry.error_type)) row.error_type = entry.error_type;
+  if (httpStatus(entry.http_status)) row.http_status = entry.http_status;
+  if (['within_budget', 'over_budget', 'count_unavailable'].includes(entry.context_check)) row.context_check = entry.context_check;
+  if (count(entry.counted_input_tokens)) row.counted_input_tokens = entry.counted_input_tokens;
+  if (Array.isArray(entry.model_transitions)) {
+    const transitions = entry.model_transitions.slice(0, 16).map(sanitizeModel).filter(Boolean);
+    row.model_transitions = transitions;
+    if (entry.model_transitions.length > 16 || transitions.length !== entry.model_transitions.length) row.model_transitions_truncated = true;
+  } else if (entry.model_transitions !== undefined) row.model_transitions_truncated = true;
+  if (entry.model_transitions_truncated === true) row.model_transitions_truncated = true;
+  assign(row, 'usage', normalizeUsageTelemetry(entry.usage));
+  assign(row, 'pricing_context', normalizePricingContext(entry.pricing_context));
+  for (const key of ['usage_complete', 'pricing_eligible', 'completion_confirmed']) if (typeof entry[key] === 'boolean') row[key] = entry[key];
+  if (UNPRICED_REASONS.includes(entry.unpriced_reason)) row.unpriced_reason = entry.unpriced_reason;
+  assign(row, 'savings', normalizeSavings(entry.savings));
+  assign(row, 'savings_coverage', normalizeSavings(entry.savings_coverage));
+  return row;
+}
+
+/** @param {any} entry @returns {import('./contracts.mjs').LifecycleEvent|undefined} */
+export function normalizeTelemetryEvent(entry) {
+  try {
+    if (!object(entry)) return;
+    const event = entry.event === 'error' ? 'request_error' : entry.event === 'cancelled' ? 'request_cancelled' : entry.event;
+    if (!EVENTS.has(event)) return;
+    const row = base(entry, event);
+    if (row && httpStatus(entry.status)) row.status = entry.status;
+    return row;
+  } catch { return; }
+}
+
+function excerpt(value) {
+  let text = '', length = 0;
+  if (typeof value !== 'string') return { text, truncated: false };
+  // Defense in depth, and it also covers records written before redaction
+  // existed when they are read back. Already-redacted text is unchanged.
+  value = redactSensitive(value);
+  for (const character of value) {
+    if (length++ === 500) return { text: text.toWellFormed(), truncated: true };
+    text += character;
+  }
+  return { text: text.toWellFormed(), truncated: false };
+}
+
+/**
+ * @param {any} entry
+ * @param {{includePrompts?:boolean}} [options]
+ * @returns {import('./contracts.mjs').SessionRecord|undefined}
+ */
+export function normalizeSessionRecord(entry, { includePrompts = true } = {}) {
+  try {
+    if (!object(entry) || !['decision', 'outcome'].includes(entry.event)) return;
+    if (entry.schema_version !== undefined && ![1, 2].includes(entry.schema_version)) return;
+    const row = base(entry, entry.event);
+    if (!row) return;
+    if (entry.event === 'decision') {
+      if (!row.requested_model || !row.selected_model) return;
+      if (includePrompts) {
+        const foreground = !row.request_class || row.request_class === 'main';
+        const prompt = foreground ? excerpt(entry.prompt_excerpt) : { text: '', truncated: false };
+        row.prompt_excerpt = prompt.text;
+        row.prompt_truncated = prompt.truncated || (foreground && entry.prompt_truncated === true);
+      }
+    } else {
+      if (!['completed', 'error', 'cancelled'].includes(entry.status)) return;
+      row.status = entry.status;
+    }
+    return row;
+  } catch { return; }
+}

package/src/token-counter.mjs

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { prepareRequest } from './model-request.mjs';
+import { targetCompatibility } from './auto-routing.mjs';
 
 // Count-token API fields, including the beta fields used by Claude Code.
 // Keep unknown extensions out of the count path: dropping new input context
@@ -76,7 +77,8 @@ export function createTokenCounter(config, { fetchImpl = fetch } = {}) {
   const cacheTtlMs = config.tokenCountCacheTtlMs ?? 5 * 60 * 1000;
   const cache = new Map();
   return async function countTokens(body, model, { headers = {}, signal, search = '' } = {}) {
-    if (signal?.aborted || !canCount(body) || typeof model !== 'string' || !model) return undefined;
+    if (signal?.aborted || !canCount(body) || typeof model !== 'string' || !model
+      || !targetCompatibility(body, model, { autoMode: config.clientProfile === 'auto' }).compatible) return undefined;
     let timer;
     let onAbort;
     const controller = new AbortController();

package/src/turn-state.mjs

@@ -0,0 +1,132 @@
+// Active execution state is not an evaluator cache. Pending tools and the
+// current human task survive cache expiry; only retired tasks use the idle TTL.
+export class TurnState {
+  constructor({ limit = 1000, idleTtlMs = 30 * 60 * 1000, now = Date.now } = {}) {
+    this.limit = limit;
+    this.idleTtlMs = idleTtlMs;
+    this.now = now;
+    this.records = new Set();
+    this.aliases = new Map();
+    this.attempts = new Map();
+  }
+
+  remove(record) {
+    for (const key of record.keys) if (this.aliases.get(key) === record) this.aliases.delete(key);
+    this.records.delete(record);
+  }
+
+  get(key) {
+    const record = this.aliases.get(key);
+    if (!record) return undefined;
+    if (!record.active && !record.pending && record.expires <= this.now()) {
+      this.remove(record);
+      return undefined;
+    }
+    if (this.ambiguous(key)) return undefined;
+    return record.pin;
+  }
+
+  ambiguous(key) {
+    const record = this.aliases.get(key);
+    return Boolean(record && record.keys[0] !== key && [...this.records].filter(other =>
+      other.active && other.pin && other.scope === record.scope && other.keys.includes(key)).length > 1);
+  }
+
+  toolOwner(scope, ids) {
+    if (!ids.length) return undefined;
+    const matches = [...this.records].filter(record => record.scope === scope && record.pin?.confirmed
+      && ids.every(id => record.pin.toolModels?.some(tool => tool.id === id)));
+    return matches.length === 1 ? { key: matches[0].keys[0], pin: matches[0].pin }
+      : matches.length > 1 ? { ambiguous: true } : undefined;
+  }
+
+  /**
+   * @param {string[]} keys
+   * @param {any} pin
+   * @param {{scope?:string,requestId?:string,sequence?:number}} [options]
+   */
+  select(keys, pin, { scope = '', requestId, sequence = 0 } = {}) {
+    // Rejected admission must not supersede an already accepted attempt.
+    if (requestId && (this.attempts.size >= this.limit || this.attempts.has(requestId))) return false;
+    // An explicit new prompt identity starts a new task even when its text is
+    // identical to an older task. Content aliases are lookup fallbacks, never
+    // authority to merge two different primary identities.
+    let record = this.aliases.get(keys[0]);
+    if (!record) {
+      for (const old of this.records) {
+        if (!old.active && !old.pending && (old.expires <= this.now() || this.records.size >= this.limit)) this.remove(old);
+      }
+      // Never evict an active task just because other agents fill the cache.
+      // The caller reports the capacity limit instead of inventing continuity.
+      if (this.records.size >= this.limit) return false;
+      record = { keys: [], scope, active: true, pending: 0, sequence, createdSequence: sequence, pin: undefined };
+      this.records.add(record);
+    }
+    record.sequence = Math.max(record.sequence, sequence);
+    for (const key of keys) {
+      if (record.keys.includes(key)) continue;
+      record.keys.push(key);
+      // Stage secondary aliases privately until execution succeeds. Otherwise
+      // a failed same-content task could destroy an older confirmed lookup.
+      if (record.keys.length === 1) this.aliases.set(key, record);
+      // Keep the primary identity and bounded recent discovery aliases.
+      if (record.keys.length > 8) {
+        const [expired] = record.keys.splice(1, 1);
+        if (this.aliases.get(expired) === record) this.aliases.delete(expired);
+      }
+    }
+    if (requestId) {
+      record.pending++;
+      this.attempts.set(requestId, { record, pin, sequence });
+    } else {
+      // Embedders that only call route() have selection evidence, not a
+      // provider confirmation. The HTTP gateway always uses request IDs.
+      this.commit(record, { ...pin, confirmed: false }, sequence);
+    }
+    return true;
+  }
+
+  commit(record, pin, sequence) {
+    if (sequence !== record.sequence) return;
+    record.pin = pin;
+    for (const key of record.keys) {
+      const current = this.aliases.get(key);
+      if (!current || !current.pin || current === record || record.createdSequence >= current.createdSequence) this.aliases.set(key, record);
+    }
+    // Task age, not the order of later tool requests, determines retirement.
+    record.active = Boolean(pin.toolModels?.length) || ![...this.records].some(other =>
+      other !== record && other.scope === record.scope && other.pin && other.createdSequence > record.createdSequence);
+    if (!record.active) record.expires = this.now() + this.idleTtlMs;
+    for (const old of this.records) {
+      if (old !== record && old.scope === record.scope && old.createdSequence < record.createdSequence && !old.pending && !old.pin?.toolModels?.length) {
+        old.active = false;
+        old.expires = this.now() + this.idleTtlMs;
+      }
+    }
+  }
+
+  complete(requestId, evidence) {
+    const attempt = this.attempts.get(requestId);
+    if (!attempt) return false;
+    this.attempts.delete(requestId);
+    const { record, pin, sequence } = attempt;
+    record.pending--;
+    const model = evidence?.continuation_model;
+    if (typeof model === 'string' && model && sequence === record.sequence) {
+      const toolModels = evidence.tool_uses ?? [];
+      // Ambiguous or unbounded tool ownership must not be committed as fact.
+      if (Array.isArray(toolModels) && toolModels.length <= 1000
+        && toolModels.every(tool => typeof tool?.id === 'string' && tool.id.length > 0 && tool.id.length <= 256 && tool.model === model)) {
+        this.commit(record, { ...pin, model, confirmed: true, toolModels }, sequence);
+        return true;
+      }
+    }
+    if (!record.pin && !record.pending) this.remove(record);
+    else if (!record.pending && !record.pin?.toolModels?.length && [...this.records].some(other =>
+      other !== record && other.scope === record.scope && other.pin && other.createdSequence > record.createdSequence)) {
+      record.active = false;
+      record.expires = this.now() + this.idleTtlMs;
+    }
+    return false;
+  }
+}

package/src/user-config.mjs

@@ -2,22 +2,32 @@ import {
   closeSync, constants, fchmodSync, fsyncSync, linkSync, lstatSync,
   mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync,
 } from 'node:fs';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { createKeychain } from './keychain.mjs';
 
-const CONFIG_KEYS = new Set([
-  'AUTOROUTER_AUTH_MODE', 'AUTOROUTER_CLIENT_PROFILE',
+export const CONFIG_KEYS = Object.freeze([
+  'AUTOROUTER_AUTH_MODE', 'AUTOROUTER_CLIENT_PROFILE', 'AUTOROUTER_SECRET_STORE',
   'ANTHROPIC_API_KEY', 'TYPESAFE_API_KEY', 'AUTOROUTER_TOKEN',
   'AUTOROUTER_UPSTREAM_URL', 'AUTOROUTER_JEV_URL', 'AUTOROUTER_JEV_MODEL',
   'AUTOROUTER_HAIKU_MODEL', 'AUTOROUTER_SONNET_MODEL', 'AUTOROUTER_OPUS_MODEL',
   'AUTOROUTER_PORT', 'AUTOROUTER_JEV_TIMEOUT_MS', 'AUTOROUTER_TOKEN_COUNT_TIMEOUT_MS',
   'AUTOROUTER_MIN_CONFIDENCE', 'AUTOROUTER_STATUSLINE', 'AUTOROUTER_DEBUG',
-  'AUTOROUTER_SESSION_LOG_DIR',
+  'AUTOROUTER_SESSION_LOG_DIR', 'AUTOROUTER_SESSION_LOG_MODE',
   'ENABLE_TOOL_SEARCH', 'CLAUDE_CODE_STOP_HOOK_BLOCK_CAP',
   'AUTOROUTER_EVALUATOR', 'AUTOROUTER_OLLAMA_URL', 'AUTOROUTER_OLLAMA_MODEL',
   'AUTOROUTER_OLLAMA_TIMEOUT_MS', 'AUTOROUTER_OLLAMA_KEEP_ALIVE',
 ]);
+export const SECRET_CONFIG_KEYS = Object.freeze(['ANTHROPIC_API_KEY', 'TYPESAFE_API_KEY', 'AUTOROUTER_TOKEN']);
+export const SECRET_STORES = Object.freeze(['file', 'keychain']);
+const allowedKeys = new Set(CONFIG_KEYS);
+const defaultKeychain = createKeychain();
+// Items are scoped to one configuration file, so separate configurations
+// (including test fixtures) never share or overwrite each other's secrets.
+const keychainAccount = (path, key) => `${key}:${createHash('sha256').update(path).digest('hex').slice(0, 16)}`;
+const keychainLabel = (path, key) => `AutoRouter ${key} (${path})`;
+const revision = content => createHash('sha256').update(content).digest('hex');
 const SAFE_FS_CODES = new Set([
   'EACCES', 'EPERM', 'ENOENT', 'ENOTDIR', 'EISDIR', 'ENOSPC', 'EROFS',
   'EMFILE', 'ENFILE', 'ELOOP', 'EIO', 'EEXIST',
@@ -44,7 +54,7 @@ function validate(values) {
   }
   const validated = {};
   for (const key of Reflect.ownKeys(values)) {
-    if (!CONFIG_KEYS.has(key)) {
+    if (!allowedKeys.has(key)) {
       // An unknown key can itself contain a pasted credential.
       throw configError('AutoRouter configuration contains an unsupported key.');
     }
@@ -54,6 +64,9 @@ function validate(values) {
     }
     validated[key] = descriptor.value;
   }
+  if (validated.AUTOROUTER_SECRET_STORE !== undefined && !SECRET_STORES.includes(validated.AUTOROUTER_SECRET_STORE)) {
+    throw configError('AUTOROUTER_SECRET_STORE must be file or keychain.');
+  }
   return validated;
 }
 
@@ -71,14 +84,20 @@ export function getConfigPath(env = process.env) {
   return join(xdg || join(homedir(), '.config'), 'claude-autorouter', 'config.json');
 }
 
-export function loadUserConfig(env = process.env) {
+// The saved store setting decides where saved secrets live; the environment
+// only overrides values. With the keychain store, `values` includes secrets
+// read from the keychain so callers can update settings without losing them.
+export function loadUserConfig(env = process.env, { allowMissing = false, readSecrets = true, keychain = defaultKeychain } = {}) {
   const path = getConfigPath(env);
   let content;
   try {
     content = readFileSync(path, 'utf8');
   } catch (error) {
     if (error.code === 'ENOENT') {
-      if (env.AUTOROUTER_CONFIG === undefined) return { env: { ...env }, path, exists: false };
+      if (env.AUTOROUTER_CONFIG === undefined || allowMissing) {
+        return { env: { ...env }, values: {}, path, exists: false, revision: null,
+          secretStore: 'file', keychainSecrets: [], unavailableSecrets: [] };
+      }
       throw configError('AUTOROUTER_CONFIG points to a missing configuration file.');
     }
     throw filesystemError(error, 'read');
@@ -87,7 +106,36 @@ export function loadUserConfig(env = process.env) {
   try { parsed = JSON.parse(content); }
   catch { throw configError('AutoRouter configuration must contain valid JSON.'); }
   const values = validate(parsed);
-  return { env: { ...values, ...env }, path, exists: true };
+  const secretStore = values.AUTOROUTER_SECRET_STORE ?? 'file';
+  const keychainSecrets = [], unavailableSecrets = [];
+  if (secretStore === 'keychain' && readSecrets) {
+    for (const key of SECRET_CONFIG_KEYS) {
+      if (Object.hasOwn(values, key)) continue;
+      let value;
+      try { value = keychain.read(keychainAccount(path, key)); }
+      catch (error) {
+        // An environment value can stand in for a locked keychain, such as
+        // over SSH. Only a missing required value stops the caller.
+        if (env[key] !== undefined) { unavailableSecrets.push(key); continue; }
+        throw error;
+      }
+      if (value !== undefined) { values[key] = value; keychainSecrets.push(key); }
+    }
+  }
+  return { env: { ...values, ...env }, values, path, exists: true, revision: revision(content),
+    secretStore, keychainSecrets, unavailableSecrets };
+}
+
+// Keychain items to delete when saving `nextStore`, given what was loaded.
+// Moving between stores needs every saved secret, so refuse while one could
+// not be read; deleting it unseen would lose it.
+export function keychainRemovals(loaded, nextStore, { replace = false, values = {} } = {}) {
+  if (loaded.secretStore !== 'keychain') return [];
+  if (nextStore !== 'keychain' && loaded.unavailableSecrets?.length) {
+    throw configError('Could not read every saved secret from the macOS Keychain. Unlock the login keychain and retry.');
+  }
+  if (nextStore !== 'keychain') return [...loaded.keychainSecrets];
+  return replace ? loaded.keychainSecrets.filter(key => !Object.hasOwn(values, key)) : [];
 }
 
 function existingFile(path) {
@@ -99,23 +147,42 @@ function existingFile(path) {
   return stat;
 }
 
-export function saveUserConfig(values, { env = process.env, overwrite = false } = {}) {
+// With the keychain store, secrets are written to the keychain before the file
+// (an interrupted move leaves both copies, never neither) and stale items are
+// removed only after the file is saved.
+export function saveUserConfig(values, {
+  env = process.env, overwrite = false, expectedRevision, removeSecrets = [], keychain = defaultKeychain,
+} = {}) {
   const validated = validate(values);
+  const store = validated.AUTOROUTER_SECRET_STORE ?? 'file';
+  const keychainKeys = store === 'keychain' ? SECRET_CONFIG_KEYS.filter(key => Object.hasOwn(validated, key)) : [];
+  const fileValues = { ...validated };
+  for (const key of keychainKeys) delete fileValues[key];
   const path = getConfigPath(env);
   const parent = dirname(path);
   let temporary;
   let descriptor;
+  const checkRevision = () => {
+    if (expectedRevision === undefined) return;
+    const current = existingFile(path) ? revision(readFileSync(path, 'utf8')) : null;
+    if (current !== expectedRevision) throw configError('AutoRouter configuration changed while this operation was running. Retry with the current settings.');
+  };
   try {
     if (existingFile(path) && !overwrite) {
       throw configError('AutoRouter configuration already exists; use overwrite to replace it.');
     }
+    checkRevision();
+    if (store === 'keychain' && !keychain.available) {
+      throw configError('The macOS Keychain secret store is available only on macOS.');
+    }
+    for (const key of keychainKeys) keychain.write(keychainAccount(path, key), validated[key], keychainLabel(path, key));
     // mkdir leaves existing directory permissions unchanged. Only directories
     // created for this configuration receive the private creation mode.
     mkdirSync(parent, { recursive: true, mode: 0o700 });
     temporary = join(parent, `.${basename(path)}.${process.pid}.${randomBytes(12).toString('hex')}.tmp`);
     descriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
     fchmodSync(descriptor, 0o600);
-    writeFileSync(descriptor, `${JSON.stringify(validated, null, 2)}\n`, 'utf8');
+    writeFileSync(descriptor, `${JSON.stringify(fileValues, null, 2)}\n`, 'utf8');
     fsyncSync(descriptor);
     closeSync(descriptor);
     descriptor = undefined;
@@ -125,6 +192,7 @@ export function saveUserConfig(values, { env = process.env, overwrite = false }
     if (existingFile(path) && !overwrite) {
       throw configError('AutoRouter configuration already exists; use overwrite to replace it.');
     }
+    checkRevision();
     if (overwrite) {
       renameSync(temporary, path);
       temporary = undefined;
@@ -133,6 +201,9 @@ export function saveUserConfig(values, { env = process.env, overwrite = false }
       // symlink can never be replaced by the default save operation.
       linkSync(temporary, path);
     }
+    for (const key of removeSecrets) {
+      if (SECRET_CONFIG_KEYS.includes(key) && !keychainKeys.includes(key)) keychain.remove(keychainAccount(path, key));
+    }
     return path;
   } catch (error) {
     if (error?.code === 'EEXIST') {