tr-plugin-auth 0.0.0-stage → 1.0.1

package/src/secrets-env-export.mjs

@@ -0,0 +1,322 @@
+/**
+ * Materialize .env files FROM the Total Recall secrets store.
+ *
+ * Model: TR secrets.enc is the SSOT for all user API keys.
+ * Repo / deploy .env files are projections — never the other way around.
+ *
+ * Never write secret values into vault markdown, openwiki, or surfaces.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { loadSecrets, listSecretsMeta, resolveSecretsPath } from './secrets-store.mjs';
+
+const META_KEY = '__tr_secrets_meta';
+
+const BEGIN_MARK = '# BEGIN TOTAL-RECALL-SECRETS';
+const END_MARK = '# END TOTAL-RECALL-SECRETS';
+
+function envHeader() {
+  return `${BEGIN_MARK}
+# Generated by Total Recall — do not hand-edit secret values here.
+# SSOT: secrets store (npx total-recall secret …)
+# Re-export: npx total-recall secret export-env --path <repo>
+# ${new Date().toISOString()}
+`;
+}
+
+/**
+ * Merge a managed TR secrets block into an existing .env without wiping
+ * non-secret / hand-managed keys outside the BEGIN/END markers.
+ *
+ * @param {string} existing - current file contents (or '')
+ * @param {string} managedBody - full block including BEGIN/END marks
+ * @returns {string}
+ */
+export function mergeEnvManagedBlock(existing, managedBody) {
+  const managed = String(managedBody || '').trimEnd() + '\n';
+  const text = existing == null ? '' : String(existing);
+
+  if (!text.trim()) return managed;
+
+  const beginIdx = text.indexOf(BEGIN_MARK);
+  const endIdx = text.indexOf(END_MARK);
+
+  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+    const before = text.slice(0, beginIdx).replace(/\s+$/, '');
+    const after = text.slice(endIdx + END_MARK.length).replace(/^\r?\n?/, '');
+    const parts = [];
+    if (before) parts.push(before.endsWith('\n') ? before : `${before}\n`);
+    parts.push(managed.endsWith('\n') ? managed : `${managed}\n`);
+    if (after.trim()) {
+      parts.push(after.startsWith('\n') ? after : `\n${after}`);
+    }
+    return parts.join('').replace(/\n{3,}/g, '\n\n');
+  }
+
+  // No prior TR block — append managed section after existing content
+  const base = text.endsWith('\n') ? text : `${text}\n`;
+  return `${base}\n${managed}`;
+}
+
+/**
+ * Resolve a project slug from a filesystem path (last segment).
+ * @param {string} projectPath
+ */
+export function projectSlugFromPath(projectPath) {
+  if (!projectPath) return null;
+  const abs = path.resolve(projectPath);
+  // Bindings are stored trimmed, so a directory name with stray whitespace must match.
+  return path.basename(abs).trim();
+}
+
+/**
+ * Load project-registry entries (if any).
+ */
+export function loadProjectRegistry() {
+  const registryPath = path.join(
+    os.homedir(),
+    '.agent',
+    'skills',
+    'total-recall',
+    'config',
+    'project-registry.json',
+  );
+  if (!fs.existsSync(registryPath)) return [];
+  try {
+    const data = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    return Array.isArray(data) ? data : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Decide whether a secret meta row applies to a target project.
+ *
+ * @param {object} metaRow - from listSecretsMeta
+ * @param {{ projectPath?: string, projectSlug?: string, includeGlobal?: boolean, keys?: string[] }} target
+ */
+export function secretMatchesTarget(metaRow, target = {}) {
+  if (target.keys?.length && !target.keys.includes(metaRow.key)) return false;
+
+  const slug = target.projectSlug || projectSlugFromPath(target.projectPath);
+  const repos = Array.isArray(metaRow.repos) ? metaRow.repos : [];
+  const projectPath = metaRow.project_path || '';
+
+  // Explicit key list mode
+  if (target.keys?.length) return true;
+
+  // Bound to this repo by slug or path (a key may be bound to several repos)
+  if (slug && repos.some((r) => r === slug || r === '*' || r.endsWith(`/${slug}`))) {
+    return true;
+  }
+  if (target.projectPath && projectPath) {
+    const a = path.resolve(target.projectPath);
+    const b = path.resolve(projectPath);
+    if (a === b || a.startsWith(b + path.sep) || b.startsWith(a + path.sep)) return true;
+  }
+
+  // Unbound secrets: include when includeGlobal (default true for full SSOT export)
+  if (target.includeGlobal !== false && repos.length === 0 && !projectPath) {
+    return true;
+  }
+
+  // Also include when tagged global scope with empty repos
+  if (target.includeGlobal !== false && metaRow.scope === 'global' && repos.length === 0) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Build dotenv body (KEY=value lines) for matching secrets.
+ * @returns {{ body: string, keys: string[], exampleBody: string, count: number }}
+ */
+export async function buildEnvProjection(brainDir, target = {}) {
+  const secrets = await loadSecrets(brainDir);
+  const metaRows = await listSecretsMeta(brainDir);
+  const byKey = new Map(metaRows.map((m) => [m.key, m]));
+
+  const selected = [];
+  for (const [key, value] of Object.entries(secrets)) {
+    if (key === META_KEY) continue;
+    if (value == null || value === '') continue;
+    const meta = byKey.get(key) || { key, repos: [], scope: 'global' };
+    if (!secretMatchesTarget(meta, target)) continue;
+    selected.push({ key, value: String(value), meta });
+  }
+
+  selected.sort((a, b) => a.key.localeCompare(b.key));
+
+  const lines = selected.map(({ key, value }) => {
+    // Quote if needed
+    const needsQuote = /[\s#"'$\\]/.test(value);
+    const v = needsQuote ? JSON.stringify(value) : value;
+    return `${key}=${v}`;
+  });
+
+  const exampleLines = selected.map(({ key }) => `${key}=`);
+
+  const body = `${envHeader()}${lines.join('\n')}${lines.length ? '\n' : ''}${END_MARK}\n`;
+  const exampleBody = `# Example env — names only. Values live in Total Recall secrets store.
+# Generate real .env: npx total-recall secret export-env --path .
+${exampleLines.join('\n')}${exampleLines.length ? '\n' : ''}`;
+
+  return {
+    body,
+    exampleBody,
+    keys: selected.map((s) => s.key),
+    count: selected.length,
+    store: resolveSecretsPath(brainDir),
+  };
+}
+
+/**
+ * Write .env (and optional .env.example) into a project directory.
+ *
+ * @param {string} brainDir
+ * @param {string} projectPath - repo root
+ * @param {{
+ *   filename?: string,
+ *   example?: boolean,
+ *   dryRun?: boolean,
+ *   includeGlobal?: boolean,
+ *   keys?: string[],
+ *   mode?: number,
+ * }} opts
+ */
+export async function exportEnvToProject(brainDir, projectPath, opts = {}) {
+  const abs = path.resolve(projectPath);
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
+    throw new Error(`Project path is not a directory: ${abs}`);
+  }
+
+  const filename = opts.filename || '.env';
+  const target = {
+    projectPath: abs,
+    projectSlug: projectSlugFromPath(abs),
+    includeGlobal: opts.includeGlobal !== false,
+    keys: opts.keys,
+  };
+
+  const projection = await buildEnvProjection(brainDir, target);
+  const envPath = path.join(abs, filename);
+  const examplePath = path.join(abs, `${filename}.example`);
+
+  if (opts.dryRun) {
+    return {
+      dryRun: true,
+      envPath,
+      examplePath: opts.example !== false ? examplePath : null,
+      keys: projection.keys,
+      count: projection.count,
+      store: projection.store,
+    };
+  }
+
+  const mode = opts.mode ?? 0o600;
+  // Merge by default so non-secret APP_NAME=… etc. outside the TR block survive
+  const replaceAll = opts.replaceAll === true;
+  let finalBody = projection.body;
+  let merged = false;
+  if (!replaceAll && fs.existsSync(envPath)) {
+    try {
+      const existing = fs.readFileSync(envPath, 'utf8');
+      finalBody = mergeEnvManagedBlock(existing, projection.body);
+      merged = true;
+    } catch {
+      finalBody = projection.body;
+    }
+  }
+  fs.writeFileSync(envPath, finalBody, { encoding: 'utf8', mode });
+  try {
+    fs.chmodSync(envPath, mode);
+  } catch {
+    /* windows / fs without chmod */
+  }
+
+  let wroteExample = false;
+  if (opts.example !== false) {
+    fs.writeFileSync(examplePath, projection.exampleBody, { encoding: 'utf8', mode: 0o644 });
+    wroteExample = true;
+  }
+
+  // Ensure .env is gitignored
+  ensureGitignoreHasEnv(abs);
+
+  return {
+    dryRun: false,
+    envPath,
+    examplePath: wroteExample ? examplePath : null,
+    keys: projection.keys,
+    count: projection.count,
+    store: projection.store,
+    projectSlug: target.projectSlug,
+    merged,
+  };
+}
+
+/**
+ * Export to multiple registered projects.
+ */
+export async function exportEnvToRegistry(brainDir, opts = {}) {
+  const registry = loadProjectRegistry();
+  const results = [];
+  for (const entry of registry) {
+    const projectPath = entry.path || entry.project_root;
+    if (!projectPath || !fs.existsSync(projectPath)) {
+      results.push({
+        name: entry.name,
+        path: projectPath,
+        ok: false,
+        error: 'path missing',
+      });
+      continue;
+    }
+    try {
+      const r = await exportEnvToProject(brainDir, projectPath, opts);
+      results.push({ name: entry.name, ...r, ok: true });
+    } catch (err) {
+      results.push({ name: entry.name, path: projectPath, ok: false, error: err.message });
+    }
+  }
+  return results;
+}
+
+/**
+ * Build a deploy payload: dotenv text + optional JSON map (no disk write).
+ */
+export async function buildDeploySecretsPayload(brainDir, target = {}) {
+  const projection = await buildEnvProjection(brainDir, {
+    includeGlobal: true,
+    ...target,
+  });
+  const secrets = await loadSecrets(brainDir);
+  const map = {};
+  for (const key of projection.keys) {
+    if (secrets[key] != null) map[key] = String(secrets[key]);
+  }
+  return {
+    dotenv: projection.body,
+    map,
+    keys: projection.keys,
+    count: projection.count,
+    store: projection.store,
+  };
+}
+
+function ensureGitignoreHasEnv(projectPath) {
+  const gi = path.join(projectPath, '.gitignore');
+  const linesNeeded = ['.env', '.env.local', '.env.*.local'];
+  let content = '';
+  if (fs.existsSync(gi)) {
+    content = fs.readFileSync(gi, 'utf8');
+  }
+  const missing = linesNeeded.filter((l) => !content.split(/\r?\n/).some((line) => line.trim() === l));
+  if (!missing.length) return;
+  const block = `\n# Total Recall secrets projections\n${missing.join('\n')}\n`;
+  fs.appendFileSync(gi, content.endsWith('\n') || !content ? block : `\n${block}`);
+}

package/src/secrets-gateway.mjs

@@ -0,0 +1,253 @@
+/**
+ * Secrets store — portable keys separate from the SSSS memory vault.
+ *
+ * Format: AES-256-GCM ciphertext at <brain>/config/secrets.enc with mode 0o600.
+ *
+ * Never write secret values into vault markdown, openwiki, or compiled surfaces.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import os from 'os';
+import { encryptSecrets, decryptSecrets, encryptSecretsSync, decryptSecretsSync } from './crypto.mjs';
+import { DEFAULT_KEYCHAIN_SERVICE, readKeychainPassword } from './secrets-keychain.mjs';
+import { writeFileSecure, appendFileSecure } from './secure-file.mjs';
+import { appendAuthMetadata } from './metadata-state.mjs';
+
+export const META_KEY = '__tr_secrets_meta';
+
+/**
+ * @param {string} brainDir
+ */
+export function resolveSecretsPath(brainDir) {
+  if (brainDir.endsWith('.agent')) {
+    return path.join(brainDir, 'secrets.enc');
+  }
+  return path.join(brainDir, 'config', 'secrets.enc');
+}
+
+/**
+ * @param {string} brainDir
+ */
+export function resolveAuditPath(brainDir) {
+  return path.join(brainDir, 'logs', 'secrets-audit.jsonl');
+}
+
+/**
+ * @param {string} brainDir
+ */
+export function resolveUsagePath(brainDir) {
+  return path.join(brainDir, 'logs', 'usage.jsonl');
+}
+
+/**
+ * The master password: the environment first, then — on macOS — the Keychain
+ * entry `secret rekey` already maintains (service `total-recall-secrets`,
+ * overridable with TR_SECRETS_KEYCHAIN_SERVICE), then the host env file
+ * (see readTrEnvFilePassword).
+ *
+ * Only an interactive shell profile used to read the Keychain, so a
+ * non-interactive process on the same Mac — a mesh `exec`, a release script —
+ * could not open a store its own user owns. Resolved once per process; the
+ * value is returned to the caller and never logged. TR_SECRETS_NO_KEYCHAIN=1
+ * disables the fallback.
+ */
+let keychainPassword;
+export function secretsPassword({
+  env = process.env,
+  readKeychain = readTrKeychainPassword,
+  readEnvFile = readTrEnvFilePassword,
+} = {}) {
+  const fromEnv = env.TR_SECRETS_PASSWORD || env.TR_MASTER_PASSWORD;
+  if (fromEnv) return fromEnv;
+  if (env.TR_SECRETS_NO_KEYCHAIN !== '1') {
+    let fromKeychain;
+    if (readKeychain !== readTrKeychainPassword) fromKeychain = readKeychain(env) || null;
+    else {
+      if (keychainPassword === undefined) keychainPassword = readKeychain(env) || null;
+      fromKeychain = keychainPassword;
+    }
+    if (fromKeychain) return fromKeychain;
+  }
+  return readEnvFile(env) || null;
+}
+
+/**
+ * The host's env-file carrier: `TR_ENV_FILE`, else `~/.agent/tr.env` — the file
+ * `auto-pull.sh` sources and `secret rekey --env-file` rotates. Only a shell
+ * that sources it used to see the password, so a non-interactive process on a
+ * Linux host (an agent's tool shell, cron, a systemd unit) could not open the
+ * store its own user owns. The file is honoured only when it is a regular file
+ * (not a symlink) that this user owns and no one else can read or write, in a
+ * directory this user owns that no one else can write to.
+ */
+export function readTrEnvFilePassword(env = process.env) {
+  const file = env.TR_ENV_FILE || path.join(env.HOME || os.homedir(), '.agent', 'tr.env');
+  try {
+    // lstat: a symlink could point the carrier at a file someone else controls.
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0) return null;
+    // A directory others can write to lets them replace the file.
+    const dir = fs.statSync(path.dirname(file));
+    if ((dir.mode & 0o022) !== 0) return null;
+    const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+    if (uid !== null && (stat.uid !== uid || dir.uid !== uid)) return null;
+    const line = fs
+      .readFileSync(file, 'utf8')
+      .split(/\r?\n/)
+      .find((entry) => /^\s*(?:export\s+)?TR_SECRETS_PASSWORD\s*=/.test(entry));
+    if (!line) return null;
+    let value = line.slice(line.indexOf('=') + 1).trim();
+    if (value.length >= 2 && /^(['"]).*\1$/.test(value)) value = value.slice(1, -1);
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+function readTrKeychainPassword(env) {
+  if (process.platform !== 'darwin') return null;
+  try {
+    return readKeychainPassword({
+      service: env.TR_SECRETS_KEYCHAIN_SERVICE || DEFAULT_KEYCHAIN_SERVICE,
+      account: env.USER || os.userInfo().username,
+    });
+  } catch {
+    return null;
+  }
+}
+
+/** Reject actual plaintext JSON; a ciphertext salt may also begin with a brace. */
+export function isPlainJsonStore(buf) {
+  if (!buf?.length || buf[0] !== 0x7b /* { */) return false;
+  try {
+    const parsed = JSON.parse(buf.toString('utf8'));
+    return Boolean(parsed) && typeof parsed === 'object' && !Array.isArray(parsed);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load raw secrets object synchronously
+ */
+export function loadSecretsSync(brainDir) {
+  const filePath = resolveSecretsPath(brainDir);
+  if (!fs.existsSync(filePath)) return {};
+
+  const buf = fs.readFileSync(filePath);
+  const password = secretsPassword();
+
+  if (!password) throw new Error('Unlock auth to read the encrypted credential store');
+  if (isPlainJsonStore(buf)) throw new Error('Plaintext credential store refused; encrypted native auth store required');
+  return decryptSecretsSync(buf, password);
+}
+
+/**
+ * Save raw secrets object synchronously
+ */
+export function saveSecretsSync(brainDir, obj) {
+  const filePath = resolveSecretsPath(brainDir);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  
+  const password = secretsPassword();
+  if (!password) throw new Error('TR_SECRETS_PASSWORD or TR_MASTER_PASSWORD is required to write secrets');
+  const buf = encryptSecretsSync(obj, password);
+  writeFileSecure(filePath, buf, { mode: 0o600 });
+}
+
+/**
+ * Load raw secrets object (values included). Caller must not log values.
+ * @param {string} brainDir
+ */
+export async function loadSecrets(brainDir) {
+  const filePath = resolveSecretsPath(brainDir);
+  if (!fs.existsSync(filePath)) return {};
+
+  const buf = fs.readFileSync(filePath);
+  const password = secretsPassword();
+
+  if (!password) throw new Error('Unlock auth to read the encrypted credential store');
+  if (isPlainJsonStore(buf)) throw new Error('Plaintext credential store refused; encrypted native auth store required');
+  return decryptSecrets(buf, password);
+}
+
+/**
+ * Persist secrets object.
+ * @param {string} brainDir
+ * @param {object} secrets
+ */
+export async function saveSecrets(brainDir, secrets, { onlyIfMissing = false } = {}) {
+  const filePath = resolveSecretsPath(brainDir);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const password = secretsPassword();
+
+  if (!password) throw new Error('TR_SECRETS_PASSWORD or TR_MASTER_PASSWORD is required to write secrets');
+  const buf = await encryptSecrets(secrets, password);
+  if (onlyIfMissing) installMissingSecretsBuffer(filePath, buf);
+  else writeFileSecure(filePath, buf, { mode: 0o600 });
+}
+
+export async function validateSecretsBuffer(buffer) {
+  const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer);
+  const password = secretsPassword();
+  if (!password) throw new Error('Unlock auth to validate encrypted credentials');
+  if (isPlainJsonStore(buf)) throw new Error('Plaintext credential import refused; encrypted native auth store required');
+  const parsed = await decryptSecrets(buf, password);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('Invalid encrypted credential payload');
+  return true;
+}
+
+/** Validate then atomically replace the encrypted secrets store. */
+function installMissingSecretsBuffer(filePath, buffer) {
+  const temporary = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, buffer, { mode: 0o600, flag: 'wx' });
+    // A hard-link publishes the complete encrypted file without replacing a
+    // store created by another process while encryption/validation awaited.
+    fs.linkSync(temporary, filePath);
+  } finally {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+  }
+}
+
+export async function replaceSecretsBufferAtomic(brainDir, buffer, { actor = 'mesh-sync', action = 'mesh_sync_replace', onlyIfMissing = false } = {}) {
+  await validateSecretsBuffer(buffer);
+  const filePath = resolveSecretsPath(brainDir);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  if (onlyIfMissing) {
+    installMissingSecretsBuffer(filePath, buffer);
+    appendAudit(brainDir, { action, key: '(encrypted-store)', actor });
+    return { success: true, path: filePath };
+  }
+  const tempPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(tempPath, buffer, { mode: 0o600 });
+    fs.renameSync(tempPath, filePath);
+    fs.chmodSync(filePath, 0o600);
+  } finally {
+    if (fs.existsSync(tempPath)) fs.rmSync(tempPath, { force: true });
+  }
+  appendAudit(brainDir, { action, key: '(encrypted-store)', actor });
+  return { success: true, path: filePath };
+}
+
+export function ensureMeta(secrets) {
+  if (!secrets[META_KEY] || typeof secrets[META_KEY] !== 'object') {
+    secrets[META_KEY] = { keys: {}, version: 1 };
+  }
+  if (!secrets[META_KEY].keys) secrets[META_KEY].keys = {};
+  return secrets;
+}
+
+export function appendAudit(brainDir, event) {
+  const auditPath = resolveAuditPath(brainDir);
+  fs.mkdirSync(path.dirname(auditPath), { recursive: true });
+  const row = {
+    ts: new Date().toISOString(),
+    ...event,
+    // never include values
+  };
+  appendAuthMetadata(auditPath, row);
+}

package/src/secrets-keychain.mjs

@@ -0,0 +1,83 @@
+/**
+ * macOS Keychain as a master-password carrier.
+ *
+ * `secrets-rekey` knows how to update file carriers — a LaunchAgent plist, an
+ * env file — because it can stage, back up and atomically rename them. The
+ * Keychain is not a file, so it was simply not a carrier at all. That is fine
+ * right up until a shell profile reads the password from the Keychain, which is
+ * the arrangement macOS installs steer people toward: a rekey then re-encrypts
+ * the store, updates the carriers it knows about, and leaves the Keychain
+ * holding the retired password. Every interactive shell breaks at once, with an
+ * error — "Unsupported state or unable to authenticate data" — that describes
+ * the symptom and not the cause.
+ *
+ * Portability: this module is macOS-only by nature and reports itself
+ * unavailable everywhere else, so callers can treat it as optional.
+ *
+ * The password is passed to `security` on stdin, never in argv. Anything in
+ * argv is visible to every process on the machine through `ps`.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+const SECURITY_BIN = '/usr/bin/security';
+
+/**
+ * Service name Total Recall stores its own master password under. A product
+ * constant like the `TR_SECRETS_PASSWORD` variable name — not a device or user
+ * detail — and overridable per invocation.
+ */
+export const DEFAULT_KEYCHAIN_SERVICE = 'total-recall-secrets';
+
+/** Is the Keychain usable on this host? */
+export function keychainAvailable({ platform = process.platform } = {}) {
+  if (platform !== 'darwin') return false;
+  const probe = spawnSync(SECURITY_BIN, ['help'], { encoding: 'utf8', timeout: 5_000 });
+  return probe.status === 0 || probe.status === 1; // `help` exits non-zero on some releases
+}
+
+/**
+ * Current password held for a service/account, or null when there is no entry.
+ * The value is returned, never logged — callers compare it, they do not print it.
+ */
+export function readKeychainPassword({ service, account = process.env.USER }) {
+  if (!service) throw new Error('Keychain carrier requires a service name');
+  const res = spawnSync(
+    SECURITY_BIN,
+    ['find-generic-password', '-a', String(account), '-s', String(service), '-w'],
+    { encoding: 'utf8', timeout: 10_000 },
+  );
+  if (res.status !== 0) return null;
+  // `security` terminates the value with a newline that is not part of it.
+  return (res.stdout || '').replace(/\n$/, '') || null;
+}
+
+/**
+ * Create or replace the entry. `-U` updates in place when one already exists,
+ * which keeps this idempotent and atomic for a single item.
+ *
+ * Omitting a value after `-w` makes `security` prompt for the password and read
+ * it from stdin — twice, to confirm — which is how the secret is kept out of
+ * argv.
+ */
+export function writeKeychainPassword({ service, account = process.env.USER, password }) {
+  if (!service) throw new Error('Keychain carrier requires a service name');
+  if (!password) throw new Error('Refusing to write an empty Keychain password');
+  const res = spawnSync(
+    SECURITY_BIN,
+    ['add-generic-password', '-U', '-a', String(account), '-s', String(service), '-w'],
+    { input: `${password}\n${password}\n`, encoding: 'utf8', timeout: 10_000 },
+  );
+  if (res.status !== 0) {
+    // stderr may echo the prompt text but never the value itself.
+    throw new Error(
+      `Could not update Keychain entry ${service}: ${(res.stderr || '').trim().slice(0, 200) || `exit ${res.status}`}`,
+    );
+  }
+  return true;
+}
+
+/** `{ service, account }` → a stable label for logs and results. */
+export function describeKeychainCarrier(carrier) {
+  return `keychain:${carrier.service}(${carrier.account || process.env.USER})`;
+}