@josfox/jos 4.0.8 → 5.0.0

package/src/commands/secrets.js

@@ -1,137 +1,717 @@
 /**
- * JOS SECRETS Command - Secure credential storage with AES-256-CBC
+ * JOS SECRETS - local credential storage in ~/.jos/secrets/ (threat model and format: SECURITY-SECRETS.md).
+ *
+ * Format v2: AES-256-GCM per entry, 12-byte random nonce per write, the entry name as AAD, 16-byte tag; the
+ * GCM key is derived from the master key with HKDF-SHA256, so the legacy CBC key and the GCM key are never the
+ * same bytes. Entries written by 4.x and 5.0.0-rc.1/rc.2 (AES-256-CBC, "<iv>:<ct>") are still read, and are
+ * rewritten only by `jos secrets migrate` (backup 0600 first, every value verified after the write).
+ *
+ * Values never reach argv, stdout, files other than the vault, or error messages:
+ *   set NAME --stdin          value from stdin (hidden prompt on a terminal); a value argument is refused
+ *   get NAME                  existence + keyed fingerprint (file backend: hmac:, 8 hex); --reveal only to a terminal, confirmed
+ *   exec --only A,B -- cmd    the values go only into the child's environment
+ * The directory must be 0700 and everything in it 0600 (0700 for directories), owned by the user, no symlinks;
+ * otherwise nothing is read until `jos secrets fix-perms`. JOS_SECRETS_BACKEND=keychain uses the macOS keychain.
+ *
+ * Every process-dependent input (streams, environment, platform, uid, clock, the security(1) path, the stdio of
+ * an exec child, read-back after a write) goes through `io`, so the tests reach every branch in-process.
+ *
+ * Exit codes: 0 ok, 1 error, not found or refused, 64 usage; exec returns the child's code (126/127 if it
+ * cannot be started, 128+n if it dies by signal n).
  */
-
+'use strict';
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
+const { spawn } = require('child_process');
+const { StringDecoder } = require('string_decoder');
+const ui = require('../ui');
+const { RULE } = ui;
 
-// AURORA colors
-const C = {
-    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
-    purple: '\x1b[38;5;135m', magenta: '\x1b[38;5;198m', cyan: '\x1b[38;5;51m',
-    green: '\x1b[38;5;78m', red: '\x1b[38;5;196m', gray: '\x1b[38;5;245m',
-    white: '\x1b[38;5;255m', yellow: '\x1b[38;5;220m'
-};
+const HEX = /^[0-9a-f]*$/i;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+const FS_CODE = /^E[A-Z]+$/;
+const ALG = 'aes-256-gcm';
+const HKDF_INFO = 'jos-secrets/v2 aes-256-gcm';
+const HKDF_FP_INFO = 'jos-secrets/v2 fingerprint hmac-sha256'; // its own label: the fingerprint key is never the GCM key
+const MAX_VALUE = 1024 * 1024; // bytes (stdin) or characters (terminal) at most
+const MAX_NAME = 256;
+const KEYCHAIN_SERVICE = 'jos';
+const KEYCHAIN_MAX = 128; // security(1) reads a prompted password with getpass(3): 128 characters at most
+const ACTIONS = ['set', 'get', 'list', 'delete', 'exec', 'migrate', 'fix-perms'];
 
-function ensureMasterKey(secretsDir) {
-    const masterPath = path.join(secretsDir, '.master');
-    if (!fs.existsSync(secretsDir)) {
-        fs.mkdirSync(secretsDir, { recursive: true, mode: 0o700 });
+class VaultError extends Error {}
+class UsageError extends Error {}
+
+function defaultIO() {
+    return {
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        env: process.env,
+        platform: process.platform,
+        /* node:coverage ignore next */
+        uid: typeof process.getuid === 'function' ? process.getuid() : -1, // Windows has no uid (and no mode check)
+        now: () => new Date(),
+        security: '/usr/bin/security',
+        childStdio: 'inherit',
+        readBack: (file) => fs.readFileSync(file, 'utf8'),
+    };
+}
+
+// ------------------------------------------------------------------------------------------------ files
+
+function writeAtomic(file, data) {
+    // Unique temp name created exclusively (never follows a planted file), mode 0600, then renamed over.
+    const tmp = file + '.' + process.pid + '.' + crypto.randomBytes(4).toString('hex') + '.tmp';
+    const buf = Buffer.from(data, 'utf8');
+    const fd = fs.openSync(tmp, 'wx', 0o600);
+    try {
+        for (let off = 0; off < buf.length;) off += fs.writeSync(fd, buf, off, buf.length - off);
+        fs.fchmodSync(fd, 0o600);
+        fs.fsyncSync(fd);
+    } finally { fs.closeSync(fd); }
+    fs.renameSync(tmp, file);
+}
+
+function modeText(m) { return '0' + (m & 0o777).toString(8).padStart(3, '0'); }
+
+// What is wrong with the permissions of the secrets directory and of every entry in it. A missing directory
+// is not a problem (nothing is stored yet); a non-directory is an fs error (ENOTDIR).
+function permissionProblems(dir, io) {
+    const problems = [];
+    let st;
+    try { st = fs.lstatSync(dir); } catch (e) { if (e.code === 'ENOENT') return problems; throw e; }
+    if (st.isSymbolicLink()) return [{ path: dir, why: 'is a symbolic link', fixable: false }];
+    if (!st.isDirectory()) throw Object.assign(new Error('not a directory'), { code: 'ENOTDIR' });
+    if (io.platform === 'win32') return problems; // no POSIX modes: the directory ACL is the user's
+    const look = (p, s, want) => {
+        if (s.uid !== io.uid) problems.push({ path: p, why: 'is owned by uid ' + s.uid + ', not by you (' + io.uid + ')', fixable: false });
+        if (s.mode & 0o077) problems.push({ path: p, why: 'has mode ' + modeText(s.mode) + ', expected ' + modeText(want), fixable: true, want });
+    };
+    look(dir, st, 0o700);
+    for (const name of fs.readdirSync(dir)) {
+        const p = path.join(dir, name);
+        const s = fs.lstatSync(p);
+        if (s.isSymbolicLink()) problems.push({ path: p, why: 'is a symbolic link', fixable: false });
+        else look(p, s, s.isDirectory() ? 0o700 : 0o600);
     }
+    return problems;
+}
+
+function readMasterKey(dir, create, io) {
+    const masterPath = path.join(dir, '.master');
     if (!fs.existsSync(masterPath)) {
-        // Generate secure master key
-        const key = crypto.randomBytes(32).toString('hex');
-        fs.writeFileSync(masterPath, key, { mode: 0o600 });
-        console.log(`${C.green}✓ Master key generated${C.reset}`);
-    }
-    return Buffer.from(fs.readFileSync(masterPath, 'utf8').trim(), 'hex');
-}
-
-exports.execute = async (args, home) => {
-    const action = args[0];
-    const key = args[1];
-    const val = args[2];
-    const showHelp = args.includes('--help') || args.includes('-h');
-
-    if (showHelp || !action) {
-        console.log(`
-${C.cyan}${C.bold}JOS SECRETS${C.reset} - Secure credential storage (AES-256-CBC)
-
-${C.white}Usage:${C.reset} jos secrets <action> [key] [value]
-
-${C.white}Actions:${C.reset}
-  set <key> <value>    Encrypt and store a secret
-  get <key>            Decrypt and retrieve a secret
-  list                 List all secret keys (not values)
-  delete <key>         Remove a secret
-
-${C.white}Examples:${C.reset}
-  jos secrets set API_KEY sk-abc123
-  jos secrets get API_KEY
-  jos secrets list
-  jos secrets delete API_KEY
-
-${C.white}Security:${C.reset}
-  • Master key: ~/.jos/secrets/.master (0600)
-  • Vault: ~/.jos/secrets/vault.json
-  • Encryption: AES-256-CBC with random IV per secret
-`);
+        if (!create) return null;
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeAtomic(masterPath, crypto.randomBytes(32).toString('hex'));
+        const e = ui.printer(io.stderr);
+        e.ok('New master key generated at ' + masterPath);
+        e.hint('0600; keep it: without it the entries of the vault cannot be decrypted');
+    }
+    const text = fs.readFileSync(masterPath, 'utf8').trim();
+    if (text.length !== 64 || !HEX.test(text)) {
+        throw new VaultError('master key is corrupt: ' + masterPath + ' must hold 64 hex characters');
+    }
+    return Buffer.from(text, 'hex');
+}
+
+// ------------------------------------------------------------------------------------------------ vault
+
+function entryFormat(v) { return typeof v === 'string' ? 1 : 2; }
+
+function isObject(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
+
+function checkEntry(k, v, vaultPath) {
+    if (typeof v === 'string') {
+        const parts = v.split(':');
+        if (parts.length !== 2 || parts[0].length !== 32 || !HEX.test(parts[0]) || parts[1].length === 0 || parts[1].length % 32 !== 0 || !HEX.test(parts[1])) {
+            throw new VaultError('vault is corrupt: entry ' + JSON.stringify(k) + ' in ' + vaultPath + ' is not "<iv hex>:<ciphertext hex>"');
+        }
         return;
     }
+    if (isObject(v) && typeof v.v === 'number' && v.v > 2) {
+        throw new VaultError('vault entry ' + JSON.stringify(k) + ' uses format v' + v.v + ', which this version of jos does not read');
+    }
+    const ok = isObject(v) && v.v === 2 && v.alg === ALG &&
+        typeof v.iv === 'string' && v.iv.length === 24 && HEX.test(v.iv) &&
+        typeof v.tag === 'string' && v.tag.length === 32 && HEX.test(v.tag) &&
+        typeof v.ct === 'string' && v.ct.length % 2 === 0 && HEX.test(v.ct) &&
+        Object.keys(v).every((f) => ['v', 'alg', 'iv', 'tag', 'ct'].includes(f));
+    if (!ok) {
+        throw new VaultError('vault is corrupt: entry ' + JSON.stringify(k) + ' in ' + vaultPath + ' is neither "<iv hex>:<ciphertext hex>" (v1) nor {"v":2,"alg":"aes-256-gcm","iv","tag","ct"}');
+    }
+}
+
+function parseVault(text, vaultPath) {
+    let parsed;
+    try { parsed = JSON.parse(text); } catch (e) {
+        throw new VaultError('vault is corrupt: ' + vaultPath + ' is not valid JSON');
+    }
+    if (!isObject(parsed)) throw new VaultError('vault is corrupt: ' + vaultPath + ' must hold a JSON object');
+    const vault = Object.create(null); // "__proto__" is an ordinary name
+    for (const k of Object.keys(parsed)) { checkEntry(k, parsed[k], vaultPath); vault[k] = parsed[k]; }
+    return vault;
+}
+
+function serializeVault(vault) {
+    const out = Object.create(null); // a plain {} would treat "__proto__" as the prototype and drop the entry
+    for (const k of Object.keys(vault)) out[k] = vault[k];
+    return JSON.stringify(out, null, 2) + '\n';
+}
+
+function gcmKey(master) { return Buffer.from(crypto.hkdfSync('sha256', master, Buffer.alloc(0), HKDF_INFO, 32)); }
 
-    const secretsDir = path.join(home, 'secrets');
-    const vaultPath = path.join(secretsDir, 'vault.json');
+function encryptV2(master, name, value) {
+    const key = gcmKey(master);
+    const iv = crypto.randomBytes(12);
+    const c = crypto.createCipheriv(ALG, key, iv, { authTagLength: 16 });
+    c.setAAD(Buffer.from(name, 'utf8'));
+    const ct = Buffer.concat([c.update(value), c.final()]);
+    key.fill(0);
+    return { v: 2, alg: ALG, iv: iv.toString('hex'), tag: c.getAuthTag().toString('hex'), ct: ct.toString('hex') };
+}
 
+function decryptEntry(master, name, entry) {
+    const v1 = typeof entry === 'string';
+    const key = v1 ? Buffer.from(master) : gcmKey(master);
+    let value;
     try {
-        const masterKey = ensureMasterKey(secretsDir);
-        let vault = {};
-        if (fs.existsSync(vaultPath)) {
-            vault = JSON.parse(fs.readFileSync(vaultPath, 'utf8'));
+        let d;
+        if (v1) {
+            d = crypto.createDecipheriv('aes-256-cbc', key, Buffer.from(entry.slice(0, 32), 'hex'));
+            value = Buffer.concat([d.update(Buffer.from(entry.slice(33), 'hex')), d.final()]);
+        } else {
+            d = crypto.createDecipheriv(ALG, key, Buffer.from(entry.iv, 'hex'), { authTagLength: 16 });
+            d.setAAD(Buffer.from(name, 'utf8'));
+            d.setAuthTag(Buffer.from(entry.tag, 'hex'));
+            value = Buffer.concat([d.update(Buffer.from(entry.ct, 'hex')), d.final()]);
         }
+    } catch (e) {
+        throw new VaultError(v1
+            ? 'secret ' + JSON.stringify(name) + ' cannot be decrypted with the current master key'
+            : 'secret ' + JSON.stringify(name) + ' failed authentication: the vault entry was altered, renamed, or the master key is not the one that wrote it');
+    } finally { key.fill(0); }
+    return value;
+}
 
-        switch (action) {
-            case 'set':
-                if (!key || !val) {
-                    console.log(`${C.red}✖ Usage: jos secrets set <key> <value>${C.reset}`);
-                    process.exit(1);
-                }
-                const iv = crypto.randomBytes(16);
-                const cipher = crypto.createCipheriv('aes-256-cbc', masterKey, iv);
-                let encrypted = cipher.update(val, 'utf8', 'hex');
-                encrypted += cipher.final('hex');
-                vault[key] = iv.toString('hex') + ':' + encrypted;
-                fs.writeFileSync(vaultPath, JSON.stringify(vault, null, 2), { mode: 0o600 });
-                console.log(`${C.green}🔒 Secret '${key}' saved securely.${C.reset}`);
-                break;
-
-            case 'get':
-                if (!key) {
-                    console.log(`${C.red}✖ Usage: jos secrets get <key>${C.reset}`);
-                    process.exit(1);
-                }
-                if (!vault[key]) {
-                    console.log(`${C.yellow}⚠ Secret '${key}' not found${C.reset}`);
-                    process.exit(1);
-                }
-                const [ivHex, encData] = vault[key].split(':');
-                const decipher = crypto.createDecipheriv('aes-256-cbc', masterKey, Buffer.from(ivHex, 'hex'));
-                let decrypted = decipher.update(encData, 'hex', 'utf8');
-                decrypted += decipher.final('utf8');
-                console.log(decrypted);
-                break;
-
-            case 'list':
-                const keys = Object.keys(vault);
-                if (keys.length === 0) {
-                    console.log(`${C.dim}No secrets stored${C.reset}`);
-                } else {
-                    console.log(`${C.cyan}🔐 Stored secrets (${keys.length}):${C.reset}`);
-                    keys.forEach(k => console.log(`  ${C.white}•${C.reset} ${k}`));
-                }
-                break;
+// Keyed fingerprint: HMAC-SHA256 under a key derived (HKDF) from the master key with its own label, first 8 hex.
+// Stable for one value in one vault, different between vaults, and not computable (so a guess not testable)
+// without the master key. A bare sha256 of the value would let anyone who saw the output test guesses.
+function fingerprint(master, value) {
+    const key = Buffer.from(crypto.hkdfSync('sha256', master, Buffer.alloc(0), HKDF_FP_INFO, 32));
+    const mac = crypto.createHmac('sha256', key).update(value).digest('hex').slice(0, 8);
+    key.fill(0);
+    return 'hmac:' + mac;
+}
 
-            case 'delete':
-                if (!key) {
-                    console.log(`${C.red}✖ Usage: jos secrets delete <key>${C.reset}`);
-                    process.exit(1);
-                }
-                if (vault[key]) {
-                    delete vault[key];
-                    fs.writeFileSync(vaultPath, JSON.stringify(vault, null, 2), { mode: 0o600 });
-                    console.log(`${C.green}✓ Secret '${key}' deleted${C.reset}`);
-                } else {
-                    console.log(`${C.yellow}⚠ Secret '${key}' not found${C.reset}`);
-                }
-                break;
+function sameBytes(a, b) { return a.length === b.length && crypto.timingSafeEqual(a, b); }
+
+// ------------------------------------------------------------------------------------------------ keychain (macOS)
+
+function run(io, argv, input, detached) {
+    return new Promise((resolve) => {
+        // detached: a new session without a controlling terminal, so security(1) reads the prompted password
+        // from this stdin pipe instead of /dev/tty.
+        const ch = spawn(io.security, argv, { stdio: ['pipe', 'pipe', 'ignore'], detached, env: io.env });
+        const out = [];
+        ch.stdout.on('data', (d) => out.push(d));
+        ch.on('error', () => resolve({ code: -1, out: Buffer.alloc(0) }));
+        ch.on('close', (code) => resolve({ code, out: Buffer.concat(out) }));
+        // EPIPE if the child exits before reading (its exit code tells); not reproducible in a test: the input is
+        // at most 2 x 129 bytes and fits the pipe buffer before the child can exit.
+        /* node:coverage ignore next */
+        ch.stdin.on('error', () => {});
+        ch.stdin.end(input);
+    });
+}
+
+function keychain(io) {
+    const kc = {
+        async get(name) {
+            const r = await run(io, ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', name, '-w'], '', false);
+            if (r.code === 44) return null;
+            if (r.code !== 0) throw new VaultError('keychain read of ' + JSON.stringify(name) + ' failed (security exit ' + r.code + ')');
+            const b = r.out;
+            return b.length && b[b.length - 1] === 0x0a ? b.subarray(0, b.length - 1) : b;
+        },
+        async set(name, value) {
+            const line = Buffer.concat([value, Buffer.from('\n')]);
+            const input = Buffer.concat([line, line]); // the password, then its confirmation
+            line.fill(0);
+            const r = await run(io, ['add-generic-password', '-U', '-s', KEYCHAIN_SERVICE, '-a', name, '-w'], input, true);
+            input.fill(0);
+            if (r.code !== 0) throw new VaultError('keychain write of ' + JSON.stringify(name) + ' failed (security exit ' + r.code + ')');
+            const back = await kc.get(name);
+            const same = back !== null && sameBytes(back, value);
+            if (back) back.fill(0);
+            if (!same) {
+                await kc.del(name);
+                throw new VaultError('keychain write of ' + JSON.stringify(name) + ' could not be verified; the item was removed');
+            }
+        },
+        async del(name) {
+            const r = await run(io, ['delete-generic-password', '-s', KEYCHAIN_SERVICE, '-a', name], '', false);
+            if (r.code === 44) return false;
+            if (r.code !== 0) throw new VaultError('keychain delete of ' + JSON.stringify(name) + ' failed (security exit ' + r.code + ')');
+            return true;
+        },
+    };
+    return kc;
+}
+
+// The keychain cannot be listed without dumping it, so the names (never the values) are kept in keychain.json.
+function readIndex(indexPath) {
+    if (!fs.existsSync(indexPath)) return [];
+    let p = null;
+    try { p = JSON.parse(fs.readFileSync(indexPath, 'utf8')); } catch (e) { /* reported below */ }
+    if (!isObject(p) || p.v !== 1 || !Array.isArray(p.names) || !p.names.every((n) => typeof n === 'string')) {
+        throw new VaultError('keychain index is corrupt: ' + indexPath + ' must hold {"v":1,"names":[...]}');
+    }
+    return p.names;
+}
+
+function writeIndex(dir, indexPath, names) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeAtomic(indexPath, JSON.stringify({ v: 1, names: Array.from(new Set(names)).sort() }, null, 2) + '\n');
+}
+
+// ------------------------------------------------------------------------------------------------ input
+
+function readPiped(stdin, max) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let n = 0;
+        const finish = (e) => {
+            stdin.removeListener('data', onData);
+            stdin.removeListener('end', onEnd);
+            stdin.removeListener('error', finish);
+            stdin.pause();
+            const buf = Buffer.concat(chunks);
+            for (const c of chunks) c.fill(0);
+            if (e) { buf.fill(0); reject(e); } else resolve(buf);
+        };
+        const onData = (d) => { chunks.push(d); n += d.length; if (n > max) finish(new UsageError('the value is longer than ' + max + ' bytes')); };
+        const onEnd = () => finish();
+        stdin.on('data', onData);
+        stdin.on('end', onEnd);
+        stdin.on('error', finish);
+        stdin.resume();
+    });
+}
+
+// One line from a terminal. hidden: raw mode (no echo), backspace edits, Enter or Ctrl-D ends, Ctrl-C cancels.
+function readTerminalLine(io, prompt, hidden) {
+    return new Promise((resolve, reject) => {
+        const stdin = io.stdin;
+        const dec = new StringDecoder('utf8');
+        let chars = [];
+        const finish = (e) => {
+            stdin.removeListener('data', onData);
+            if (hidden) { stdin.setRawMode(false); ui.printer(io.stderr).line(); }
+            stdin.pause();
+            const text = chars.join('');
+            chars = [];
+            if (e) reject(e); else resolve(text);
+        };
+        const onData = (d) => {
+            for (const ch of dec.write(d)) {
+                if (ch === '\r' || ch === '\n' || ch === '\u0004') return finish();
+                if (ch === '\u0003') return finish(Object.assign(new UsageError('cancelled'), { exitCode: 130 }));
+                if (hidden && (ch === '\u007f' || ch === '\b')) { chars.pop(); continue; }
+                chars.push(ch);
+                if (chars.length > MAX_VALUE) return finish(new UsageError('the value is longer than ' + MAX_VALUE + ' characters'));
+            }
+        };
+        ui.printer(io.stderr).text(prompt);
+        if (hidden) stdin.setRawMode(true);
+        stdin.on('data', onData);
+        stdin.resume();
+    });
+}
+
+async function readSecretValue(io, name) {
+    let buf;
+    if (io.stdin.isTTY) {
+        buf = Buffer.from(await readTerminalLine(io, 'Value for ' + JSON.stringify(name) + ' (input hidden, Enter to finish): ', true), 'utf8');
+    } else {
+        const raw = await readPiped(io.stdin, MAX_VALUE);
+        let end = raw.length; // one final line break comes from `echo` or a heredoc; it is not part of the value
+        if (end && raw[end - 1] === 0x0a) { end--; if (end && raw[end - 1] === 0x0d) end--; }
+        buf = Buffer.from(raw.subarray(0, end));
+        raw.fill(0);
+    }
+    if (buf.length === 0) throw new UsageError('empty value: nothing was read from stdin');
+    return buf;
+}
+
+// ------------------------------------------------------------------------------------------------ command line
+
+const HELP = (C) => `
+${C.purple}${RULE}${C.reset}
+${C.bold}JOS SECRETS${C.reset} // local credential storage (AES-256-GCM, values never on the command line)
+${C.purple}${RULE}${C.reset}
 
-            default:
-                console.log(`${C.red}✖ Unknown action: ${action}${C.reset}`);
-                console.log(`${C.dim}Run 'jos secrets --help' for usage${C.reset}`);
-                process.exit(1);
+${C.bold}Usage:${C.reset} jos secrets <action> [name] [options]
+
+${C.bold}Actions:${C.reset}
+  set <name> --stdin           Store a secret read from stdin (hidden prompt on a terminal); the name is
+                               an environment variable name: letters, digits, "_", not starting with a digit
+  get <name>                   Say whether it exists and print its keyed fingerprint (hmac, 8 hex; file backend)
+  get <name> --reveal          Print the value, only to a terminal and after typing the name
+  exec --only A,B -- <cmd> ... Run <cmd> with the secrets A and B added to its environment only
+  list                         List the names (not the values); marks entries in the old format
+  delete <name>                Remove a secret
+  migrate                      Rewrite old-format entries (AES-256-CBC) as v2, with a 0600 backup
+  fix-perms                    Set the secrets directory to 0700 and its files to 0600
+
+${C.bold}Examples:${C.reset}
+  printf %s "$TOKEN" | jos secrets set OPENAI_API_KEY --stdin
+  jos secrets exec --only OPENAI_API_KEY -- node agent.js
+
+${C.bold}Files:${C.reset}
+  ~/.jos/secrets/.master      master key, 64 hex characters (0600)
+  ~/.jos/secrets/vault.json   {"<name>": {"v":2,"alg":"aes-256-gcm","iv","tag","ct"}} (0600)
+
+${C.bold}Environment:${C.reset} JOS_SECRETS_BACKEND=keychain stores values in the macOS login keychain (service "jos")
+
+${C.bold}Exit codes:${C.reset} 0 ok, 1 error, not found or refused, 64 usage; exec returns the code of <cmd>
+`;
+
+function parseArgs(args) {
+    const dd = args.indexOf('--');
+    const head = dd === -1 ? args : args.slice(0, dd);
+    const o = { action: head[0], positional: [], stdin: false, reveal: false, only: null, unknown: [], command: dd === -1 ? null : args.slice(dd + 1) };
+    o.help = head.includes('--help') || head.includes('-h');
+    for (let i = 1; i < head.length; i++) {
+        const a = head[i];
+        if (a === '--stdin') o.stdin = true;
+        else if (a === '--reveal') o.reveal = true;
+        else if (a === '--only') o.only = i + 1 < head.length ? head[++i] : '';
+        else if (a.startsWith('--only=')) o.only = a.slice(7);
+        else if (a.startsWith('-') && a !== '--help' && a !== '-h') o.unknown.push(a);
+        else if (!a.startsWith('-')) o.positional.push(a);
+    }
+    return o;
+}
+
+function checkName(name) {
+    if (name === undefined || name.length === 0) throw new UsageError('missing secret name');
+    if (name.length > MAX_NAME) throw new UsageError('secret names are at most ' + MAX_NAME + ' characters');
+    if (CONTROL.test(name)) throw new UsageError('secret names cannot contain control characters');
+}
+
+// One rule for the names `set` accepts and `exec --only` accepts: they are environment variable names.
+// `get`, `delete` and `list` keep the looser checkName, so a vault written by an older version (names such as
+// "my-key") can still be listed, read and cleaned up.
+const NAME_RULE = 'letters, digits and "_", not starting with a digit ([A-Za-z_][A-Za-z0-9_]*), because exec hands the name to the command as an environment variable';
+function checkEnvName(name, where) {
+    if (!ENV_NAME.test(name)) throw new UsageError(where + ': ' + JSON.stringify(name) + ' is not a valid secret name: use ' + NAME_RULE);
+}
+
+const SET_ARG_REFUSED =
+    'a value on the command line is visible in the process list and in your shell history, so it is not accepted.\n' +
+    '  Pipe it:  printf %s "$VALUE" | jos secrets set NAME --stdin\n' +
+    '  or type it at the hidden prompt:  jos secrets set NAME --stdin';
+
+// Usage errors, found before anything is read.
+function checkUsage(o, io) {
+    const action = o.action;
+    if (!ACTIONS.includes(action)) throw new UsageError('unknown action ' + JSON.stringify(action) + ' (' + ACTIONS.join(', ') + ')');
+    if (o.unknown.length) throw new UsageError('unknown option ' + JSON.stringify(o.unknown[0]) + ' for ' + action);
+    const backend = io.env.JOS_SECRETS_BACKEND || 'file';
+    if (backend !== 'file' && backend !== 'keychain') throw new UsageError('JOS_SECRETS_BACKEND must be "file" or "keychain"');
+    if (backend === 'keychain' && io.platform !== 'darwin') throw new UsageError('JOS_SECRETS_BACKEND=keychain is available on macOS only');
+    if (o.command !== null && action !== 'exec') throw new UsageError('"--" is only used by exec');
+    if (o.stdin && action !== 'set') throw new UsageError('--stdin is only used by set');
+    if (o.reveal && action !== 'get') throw new UsageError('--reveal is only used by get');
+    if (o.only !== null && action !== 'exec') throw new UsageError('--only is only used by exec');
+    if (action === 'set') {
+        if (o.positional.length > 1) throw new UsageError(SET_ARG_REFUSED);
+        checkName(o.positional[0]);
+        checkEnvName(o.positional[0], 'set');
+        if (!o.stdin) throw new UsageError('set needs --stdin; ' + SET_ARG_REFUSED);
+    } else if (action === 'get' || action === 'delete') {
+        if (o.positional.length !== 1) throw new UsageError('usage: jos secrets ' + action + ' <name>');
+        checkName(o.positional[0]);
+    } else if (action === 'exec') {
+        if (o.positional.length) throw new UsageError('usage: jos secrets exec --only A,B -- <command> [args]');
+        if (!o.only) throw new UsageError('exec needs --only A,B: the secrets the command receives are always named');
+        if (!o.command || o.command.length === 0) throw new UsageError('exec needs "-- <command> [args]"');
+        for (const n of o.only.split(',')) checkEnvName(n, 'exec --only');
+    } else if (o.positional.length) {
+        throw new UsageError('usage: jos secrets ' + action);
+    }
+    return backend;
+}
+
+exports.execute = async (args, home, ioOverride) => {
+    const io = Object.assign(defaultIO(), ioOverride);
+    const out = ui.printer(io.stdout);
+    const err = ui.printer(io.stderr);
+    const ctx = {
+        io, C: out.C, out, err,
+        secretsDir: path.join(home, 'secrets'),
+    };
+    ctx.vaultPath = path.join(ctx.secretsDir, 'vault.json');
+    ctx.indexPath = path.join(ctx.secretsDir, 'keychain.json');
+    const o = parseArgs(args);
+    if (!o.action || o.help) { out.text(HELP(out.C)); return 0; }
+
+    try {
+        const backend = checkUsage(o, io);
+        if (o.action === 'fix-perms') return fixPerms(ctx);
+        const problems = permissionProblems(ctx.secretsDir, io);
+        if (problems.length) {
+            for (const p of problems) err.warn(`${p.path} ${p.why}`);
+            err.fail('jos secrets: refusing to read the secrets while their permissions are open: run `jos secrets fix-perms`');
+            return 1;
         }
+        return backend === 'keychain' ? await withKeychain(o, ctx) : await withFile(o, ctx);
     } catch (e) {
-        console.log(`${C.red}✖ Error: ${e.message}${C.reset}`);
-        process.exit(1);
+        if (e instanceof UsageError || e instanceof VaultError) {
+            err.fail('jos secrets: ' + e.message);
+            return e instanceof VaultError ? 1 : (e.exitCode || 64);
+        }
+        if (typeof e.code === 'string' && FS_CODE.test(e.code)) {
+            // file system errors (ENOTDIR, EACCES, ...): report the path, not a stack
+            err.fail(`jos secrets: cannot use ${ctx.secretsDir}: ${e.code}`);
+            return 1;
+        }
+        // A host bug. No message of a crypto or fs error carries a value, but the message is replaced anyway
+        // (unless JOS_DEBUG is set) so that no future error path can leak one through bin/jos.
+        if (io.env.JOS_DEBUG) throw e;
+        throw new Error('secrets: unexpected error (set JOS_DEBUG=1 for details)');
     }
 };
+
+async function withFile(o, ctx) {
+    const { io, C, out, err, secretsDir, vaultPath } = ctx;
+    const text = fs.existsSync(vaultPath) ? fs.readFileSync(vaultPath, 'utf8') : null;
+    const vault = text === null ? Object.create(null) : parseVault(text, vaultPath);
+    const names = Object.keys(vault);
+    const masterPath = path.join(secretsDir, '.master');
+    // A master key is created only by the first `set` of an empty vault: never next to existing entries.
+    const master = readMasterKey(secretsDir, o.action === 'set' && names.length === 0, io);
+    const needMaster = () => {
+        if (!master) throw new VaultError('master key is missing: ' + masterPath + ' (the entries of ' + vaultPath + ' cannot be decrypted without it)');
+        return master;
+    };
+    const name = o.positional[0];
+    const notFound = () => { err.warn(`Secret '${name}' not found`); return 1; };
+
+    switch (o.action) {
+        case 'set': {
+            const m = needMaster();
+            const value = await readSecretValue(io, name);
+            vault[name] = encryptV2(m, name, value);
+            const fp = fingerprint(m, value);
+            value.fill(0);
+            writeAtomic(vaultPath, serializeVault(vault));
+            err.ok(`Secret '${name}' saved`, `(aes-256-gcm, ${fp})`);
+            return 0;
+        }
+        case 'get': {
+            if (!(name in vault)) return notFound();
+            if (o.reveal) return await reveal(ctx, name, () => decryptEntry(needMaster(), name, vault[name]));
+            const m = needMaster();
+            const value = decryptEntry(m, name, vault[name]);
+            const fp = fingerprint(m, value);
+            value.fill(0);
+            out.line(`${name} exists · ${fp} · ` + (entryFormat(vault[name]) === 1 ? 'v1 aes-256-cbc (old format: run jos secrets migrate)' : 'v2 aes-256-gcm'));
+            return 0;
+        }
+        case 'list': {
+            if (names.length === 0) { out.line(`${C.dim}No secrets stored${C.reset}`); return 0; }
+            const old = names.filter((k) => entryFormat(vault[k]) === 1);
+            out.line(`${C.cyan}Stored secrets (${names.length}):${C.reset}`);
+            for (const k of names) out.item(k + (entryFormat(vault[k]) === 1 ? `  ${C.yellow}[v1 aes-256-cbc, old format]${C.reset}` : ''));
+            if (old.length) out.warn(`${old.length} of ${names.length} in the old format (unauthenticated AES-256-CBC): run \`jos secrets migrate\``);
+            return 0;
+        }
+        case 'delete': {
+            if (!(name in vault)) return notFound();
+            delete vault[name];
+            writeAtomic(vaultPath, serializeVault(vault));
+            err.ok(`Secret '${name}' deleted`);
+            return 0;
+        }
+        case 'exec': {
+            const want = Array.from(new Set(o.only.split(',')));
+            const missing = want.find((n) => !(n in vault));
+            if (missing !== undefined) { err.warn(`Secret '${missing}' not found; the command was not started`); return 1; }
+            const add = Object.create(null);
+            for (const n of want) add[n] = envValue(n, decryptEntry(needMaster(), n, vault[n]));
+            return await execChild(ctx, o.command, add);
+        }
+        default: // migrate (checkUsage admits nothing else here)
+            return migrate(ctx, vault, text, names.length ? needMaster() : null);
+    }
+}
+
+function envValue(name, buf) {
+    const nul = buf.includes(0);
+    const s = buf.toString('utf8');
+    buf.fill(0);
+    if (nul) throw new VaultError('secret ' + JSON.stringify(name) + ' contains a NUL byte and cannot be passed in an environment variable');
+    return s;
+}
+
+function execChild(ctx, command, add) {
+    const { io, err } = ctx;
+    return new Promise((resolve) => {
+        const env = Object.assign(Object.create(null), io.env, add); // null prototype: "__proto__" is a name too
+        const cannot = (code) => err.fail(`jos secrets exec: cannot start ${JSON.stringify(command[0])}: ${code}`);
+        let child;
+        try {
+            child = spawn(command[0], command.slice(1), { stdio: io.childStdio, env, shell: false });
+        } catch (e) { // invalid arguments (a NUL byte in the command, ...)
+            cannot(e.code);
+            resolve(126);
+            return;
+        }
+        const forward = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+        const relay = (s) => { child.kill(s); };
+        for (const s of forward) process.on(s, relay);
+        const done = (code) => { for (const s of forward) process.removeListener(s, relay); resolve(code); };
+        child.on('error', (e) => { cannot(e.code); done(e.code === 'ENOENT' ? 127 : 126); });
+        child.on('exit', (code, signal) => done(signal ? 128 + os.constants.signals[signal] : code));
+    });
+}
+
+async function reveal(ctx, name, decrypt) {
+    const { io, err } = ctx;
+    if (!io.stdout.isTTY || !io.stdin.isTTY) {
+        err.fail('jos secrets: --reveal prints only to a terminal (stdin and stdout must both be one).');
+        err.hint('To hand the value to a program: jos secrets exec --only ' + (ENV_NAME.test(name) ? name : 'NAME') + ' -- <command>');
+        return 1;
+    }
+    const typed = await readTerminalLine(io, 'Type the name ' + JSON.stringify(name) + ' to print its value on this terminal: ', false);
+    if (typed !== name) { err.warn('Not confirmed; nothing printed'); return 1; }
+    const value = await decrypt();
+    ui.data(io.stdout, Buffer.concat([value, Buffer.from('\n')])); // the value itself: data, not a message
+    value.fill(0);
+    return 0;
+}
+
+function fixPerms(ctx) {
+    const { io, out, err, secretsDir } = ctx;
+    const problems = permissionProblems(secretsDir, io);
+    if (problems.length === 0) { out.ok('jos secrets: permissions are already 0700/0600; nothing to fix'); return 0; }
+    let bad = 0;
+    for (const p of problems) {
+        if (!p.fixable) { bad++; err.fail(`${p.path} ${p.why}; fix it by hand`); continue; }
+        fs.chmodSync(p.path, p.want);
+        out.ok(`${p.path}: ${modeText(p.want)}`);
+    }
+    return bad ? 1 : 0;
+}
+
+function migrate(ctx, vault, text, master) {
+    const { io, out, vaultPath } = ctx;
+    const old = Object.keys(vault).filter((k) => entryFormat(vault[k]) === 1);
+    if (old.length === 0) { out.ok('jos secrets: nothing to migrate (every entry is already v2)'); return 0; }
+
+    const plain = Object.create(null);
+    try {
+        // 1. decrypt every old entry first: if one fails, nothing is written
+        for (const k of old) plain[k] = decryptEntry(master, k, vault[k]);
+
+        // 2. a copy of the exact bytes, created exclusively with mode 0600, read back and compared
+        const stamp = io.now().toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+        let backup = vaultPath + '.bak-' + stamp + '-v1';
+        for (let i = 1; fs.existsSync(backup); i++) backup = vaultPath + '.bak-' + stamp + '-v1-' + i;
+        const fd = fs.openSync(backup, 'wx', 0o600);
+        try { fs.writeSync(fd, Buffer.from(text, 'utf8')); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+        if (io.readBack(backup) !== text) throw new VaultError('backup ' + backup + ' could not be verified; the vault was not changed');
+
+        // 3. write the v2 vault, read it back from disk, decrypt every migrated value and compare; any
+        //    difference restores the original bytes
+        const next = Object.create(null);
+        for (const k of Object.keys(vault)) next[k] = entryFormat(vault[k]) === 1 ? encryptV2(master, k, plain[k]) : vault[k];
+        writeAtomic(vaultPath, serializeVault(next));
+        let ok;
+        try {
+            const disk = parseVault(io.readBack(vaultPath), vaultPath);
+            ok = Object.keys(disk).length === Object.keys(vault).length && old.every((k) => {
+                if (entryFormat(disk[k]) !== 2) return false;
+                const got = decryptEntry(master, k, disk[k]);
+                const same = sameBytes(got, plain[k]);
+                got.fill(0);
+                return same;
+            });
+        } catch (e) { ok = false; }
+        if (!ok) {
+            writeAtomic(vaultPath, text);
+            throw new VaultError('migration could not be verified on disk; the original vault was restored (backup: ' + backup + ')');
+        }
+        out.ok(`migrated ${old.length} entr${old.length === 1 ? 'y' : 'ies'} to v2 (aes-256-gcm); every value verified`);
+        out.hint('backup of the old vault: ' + backup + ' (0600)');
+        out.hint('it holds the old unauthenticated ciphertexts under the same master key: delete it once you have checked the vault');
+        return 0;
+    } finally {
+        for (const k of Object.keys(plain)) plain[k].fill(0);
+    }
+}
+
+async function withKeychain(o, ctx) {
+    const { io, C, out, err, secretsDir, indexPath } = ctx;
+    const kc = keychain(io);
+    const names = readIndex(indexPath);
+    const name = o.positional[0];
+    const notFound = (n, tail) => { err.warn(`Secret '${n}' not found${tail}`); return 1; };
+    const fetch = async (n) => {
+        const v = await kc.get(n);
+        if (v === null) throw new VaultError('secret ' + JSON.stringify(n) + ' is in ' + indexPath + ' but not in the keychain');
+        return v;
+    };
+    switch (o.action) {
+        case 'set': {
+            const value = await readSecretValue(io, name);
+            try {
+                if (value.length > KEYCHAIN_MAX || !value.every((b) => b >= 0x20 && b <= 0x7e)) {
+                    throw new UsageError('the keychain backend stores printable ASCII values of at most ' + KEYCHAIN_MAX + ' characters; use the file backend for this one');
+                }
+                await kc.set(name, value);
+                writeIndex(secretsDir, indexPath, names.concat([name]));
+                err.ok(`Secret '${name}' saved`, `(macOS keychain, service "${KEYCHAIN_SERVICE}")`);
+                return 0;
+            } finally { value.fill(0); }
+        }
+        case 'get': {
+            if (!names.includes(name)) return notFound(name, '');
+            const v = await fetch(name);
+            if (o.reveal) {
+                try { return await reveal(ctx, name, () => Buffer.from(v)); } finally { v.fill(0); }
+            }
+            v.fill(0); // read to prove the item exists; no fingerprint here (no master key to key it: SECURITY-SECRETS.md)
+            out.line(`${name} exists · macOS keychain`);
+            return 0;
+        }
+        case 'list': {
+            if (names.length === 0) { out.line(`${C.dim}No secrets stored${C.reset}`); return 0; }
+            out.line(`${C.cyan}Stored secrets (${names.length}, macOS keychain):${C.reset}`);
+            for (const k of names) out.item(k);
+            return 0;
+        }
+        case 'delete': {
+            const was = await kc.del(name);
+            if (!was && !names.includes(name)) return notFound(name, '');
+            writeIndex(secretsDir, indexPath, names.filter((n) => n !== name));
+            err.ok(`Secret '${name}' deleted`);
+            return 0;
+        }
+        case 'exec': {
+            const want = Array.from(new Set(o.only.split(',')));
+            const missing = want.find((n) => !names.includes(n));
+            if (missing !== undefined) return notFound(missing, '; the command was not started');
+            const add = Object.create(null);
+            for (const n of want) add[n] = envValue(n, await fetch(n));
+            return await execChild(ctx, o.command, add);
+        }
+        default: // migrate
+            throw new UsageError('migrate rewrites the file vault; run it without JOS_SECRETS_BACKEND=keychain');
+    }
+}