tr-plugin-auth 0.0.0-stage → 1.0.1

package/src/secrets-rekey.mjs

@@ -0,0 +1,366 @@
+/**
+ * Transactional master-password rotation for encrypted Total Recall stores.
+ *
+ * Secret material stays in process memory. Callers must source the old/new
+ * passwords without argv, stdout, logs, or transcripts.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { clearDerivedKeyCache, decryptSecrets, encryptSecrets } from './crypto.mjs';
+import { isPlainJsonStore } from './secrets-store.mjs';
+import {
+  describeKeychainCarrier,
+  readKeychainPassword,
+  writeKeychainPassword,
+} from './secrets-keychain.mjs';
+
+const MASTER_KEY = 'TR_SECRETS_PASSWORD';
+
+function assertObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Secrets payload must be an object');
+  }
+  return value;
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function xmlUnescape(value) {
+  return String(value)
+    .replaceAll('&apos;', "'")
+    .replaceAll('&quot;', '"')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&amp;', '&');
+}
+
+function parseEnvValue(raw) {
+  const value = String(raw).trim();
+  if (
+    value.length >= 2 &&
+    ((value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'")))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+export function readMasterPasswordFromCarrierText(text, type) {
+  if (type === 'launchd-plist') {
+    const match = String(text).match(
+      /<key>\s*TR_SECRETS_PASSWORD\s*<\/key>\s*<string>([\s\S]*?)<\/string>/,
+    );
+    return match ? xmlUnescape(match[1]) : null;
+  }
+  if (type === 'env') {
+    const line = String(text)
+      .split(/\r?\n/)
+      .find((entry) => /^\s*(?:export\s+)?TR_SECRETS_PASSWORD\s*=/.test(entry));
+    if (!line) return null;
+    return parseEnvValue(line.slice(line.indexOf('=') + 1));
+  }
+  throw new Error(`Unsupported credential carrier type: ${type}`);
+}
+
+export function updateMasterPasswordCarrierText(text, type, newPassword, options = {}) {
+  if (type === 'launchd-plist') {
+    const source = String(text);
+    const expression =
+      /(<key>\s*TR_SECRETS_PASSWORD\s*<\/key>\s*<string>)[\s\S]*?(<\/string>)/;
+    if (expression.test(source)) {
+      return source.replace(expression, `$1${xmlEscape(newPassword)}$2`);
+    }
+    if (!options.allowInsert) {
+      throw new Error('LaunchAgent does not define TR_SECRETS_PASSWORD');
+    }
+    const environment = /(<key>\s*EnvironmentVariables\s*<\/key>\s*<dict>)/;
+    if (!environment.test(source)) {
+      throw new Error('LaunchAgent does not define an EnvironmentVariables dictionary');
+    }
+    return source.replace(
+      environment,
+      `$1\n\t\t<key>${MASTER_KEY}</key>\n\t\t<string>${xmlEscape(newPassword)}</string>`,
+    );
+  }
+
+  if (type === 'env') {
+    const source = String(text);
+    const expression = /^\s*(?:export\s+)?TR_SECRETS_PASSWORD\s*=.*$/m;
+    const replacement = `${MASTER_KEY}=${newPassword}`;
+    if (expression.test(source)) return source.replace(expression, replacement);
+    if (!options.allowInsert) throw new Error('Environment file does not define TR_SECRETS_PASSWORD');
+    return `${source.replace(/\s*$/, '')}\n${replacement}\n`;
+  }
+
+  throw new Error(`Unsupported credential carrier type: ${type}`);
+}
+
+export function readMasterPasswordFromCarrier(carrier) {
+  const text = fs.readFileSync(carrier.path, 'utf8');
+  return readMasterPasswordFromCarrierText(text, carrier.type);
+}
+
+export function generateSecretsMasterPassword(bytes = 48) {
+  if (!Number.isInteger(bytes) || bytes < 32) {
+    throw new Error('Master password generation requires at least 32 random bytes');
+  }
+  return crypto.randomBytes(bytes).toString('base64url');
+}
+
+async function decodeStore(buffer, oldPassword) {
+  // Was a fifth copy of "first byte is `{` therefore plain JSON". An encrypted
+  // store opens with a random salt, so that byte is `{` about once in 256
+  // stores; the shared check parses instead of guessing.
+  if (isPlainJsonStore(buffer)) {
+    return { payload: assertObject(JSON.parse(buffer.toString('utf8') || '{}')), encrypted: false };
+  }
+  if (!oldPassword) throw new Error('Encrypted secrets store has no current master password');
+  return { payload: assertObject(await decryptSecrets(buffer, oldPassword)), encrypted: true };
+}
+
+function payloadFingerprint(payload) {
+  return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+
+function writeStagedFile(targetPath, data, mode, transactionId) {
+  const stagedPath = `${targetPath}.rekey-${transactionId}.tmp`;
+  const fd = fs.openSync(stagedPath, 'wx', mode);
+  try {
+    fs.writeFileSync(fd, data);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.chmodSync(stagedPath, mode);
+  return stagedPath;
+}
+
+function fsyncDirectory(targetPath) {
+  let fd;
+  try {
+    fd = fs.openSync(path.dirname(targetPath), 'r');
+    fs.fsyncSync(fd);
+  } catch {
+    // Some filesystems do not allow directory fsync. File fsync + atomic rename
+    // still provides the strongest portable behavior available here.
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+/**
+ * Re-encrypt stores and update persistent credential carriers as one rollback-
+ * protected transaction. Backups encrypted with the old password are deleted
+ * immediately after verification succeeds.
+ */
+export async function rekeySecretsTransaction({
+  storePaths,
+  carriers,
+  keychainCarriers,
+  oldPassword,
+  newPassword,
+  allowStoreOnly = false,
+}) {
+  const uniqueStores = [...new Set((storePaths || []).filter(Boolean))];
+  const uniqueCarriers = [...new Map((carriers || []).map((item) => [item.path, item])).values()];
+  const uniqueKeychain = [
+    ...new Map(
+      (keychainCarriers || []).map((item) => [`${item.service}\u0000${item.account || ''}`, item]),
+    ).values(),
+  ];
+  if (!uniqueStores.length) throw new Error('No secrets stores were provided');
+  if (!uniqueCarriers.length && !uniqueKeychain.length && !allowStoreOnly) {
+    throw new Error('No persistent credential carriers were provided');
+  }
+  if (!oldPassword) throw new Error('Current master password is required');
+  if (!newPassword || newPassword.length < 32 || newPassword === oldPassword) {
+    throw new Error('New master password must be distinct and at least 32 characters');
+  }
+
+  const targets = new Set();
+  for (const targetPath of [...uniqueStores, ...uniqueCarriers.map((item) => item.path)]) {
+    if (targets.has(targetPath)) throw new Error(`Duplicate rekey target: ${targetPath}`);
+    targets.add(targetPath);
+  }
+
+  // Checked before anything is staged: a Keychain entry holding a password that
+  // is neither the current nor the new one means someone else has already moved
+  // it, and continuing would leave the fleet split across two passwords.
+  for (const carrier of uniqueKeychain) {
+    const current = readKeychainPassword(carrier);
+    if (current && current !== oldPassword && current !== newPassword) {
+      throw new Error(
+        `Keychain entry does not match the current master password: ${describeKeychainCarrier(carrier)}`,
+      );
+    }
+  }
+
+  const transactionId = crypto.randomUUID();
+  const writes = [];
+  const storeChecks = [];
+  /** Prior Keychain values, kept so a late failure can put them back. */
+  const keychainRestores = [];
+
+  try {
+    for (const storePath of uniqueStores) {
+      if (!fs.existsSync(storePath)) continue;
+      const original = fs.readFileSync(storePath);
+      const decoded = await decodeStore(original, oldPassword);
+      const encrypted = await encryptSecrets(decoded.payload, newPassword);
+      const verified = assertObject(await decryptSecrets(encrypted, newPassword));
+      const expectedFingerprint = payloadFingerprint(decoded.payload);
+      if (payloadFingerprint(verified) !== expectedFingerprint) {
+        throw new Error(`Rekey verification failed for ${storePath}`);
+      }
+      writes.push({
+        path: storePath,
+        original,
+        mode: 0o600,
+        staged: writeStagedFile(storePath, encrypted, 0o600, transactionId),
+      });
+      storeChecks.push({
+        path: storePath,
+        expectedFingerprint,
+        keys: Object.keys(decoded.payload).length,
+      });
+    }
+    if (!storeChecks.length) throw new Error('None of the provided secrets stores exist');
+
+    for (const carrier of uniqueCarriers) {
+      const original = fs.readFileSync(carrier.path);
+      const source = original.toString('utf8');
+      const current = readMasterPasswordFromCarrierText(source, carrier.type);
+      if (current && current !== oldPassword) {
+        throw new Error(`Credential carrier does not match the current master password: ${carrier.path}`);
+      }
+      if (!current && !carrier.allowInsert) {
+        throw new Error(`Credential carrier is missing TR_SECRETS_PASSWORD: ${carrier.path}`);
+      }
+      const updated = updateMasterPasswordCarrierText(source, carrier.type, newPassword, {
+        allowInsert: carrier.allowInsert,
+      });
+      if (readMasterPasswordFromCarrierText(updated, carrier.type) !== newPassword) {
+        throw new Error(`Credential carrier verification failed: ${carrier.path}`);
+      }
+      const mode = fs.statSync(carrier.path).mode & 0o777;
+      writes.push({
+        path: carrier.path,
+        original,
+        mode,
+        staged: writeStagedFile(carrier.path, updated, mode, transactionId),
+      });
+    }
+
+    for (const write of writes) {
+      write.backup = `${write.path}.rekey-${transactionId}.backup`;
+      fs.copyFileSync(write.path, write.backup, fs.constants.COPYFILE_EXCL);
+      fs.chmodSync(write.backup, write.mode);
+    }
+
+    const applied = [];
+    try {
+      for (const write of writes) {
+        fs.renameSync(write.staged, write.path);
+        fs.chmodSync(write.path, write.mode);
+        fsyncDirectory(write.path);
+        applied.push(write);
+      }
+
+      for (const check of storeChecks) {
+        const current = fs.readFileSync(check.path);
+        const verified = assertObject(await decryptSecrets(current, newPassword));
+        if (payloadFingerprint(verified) !== check.expectedFingerprint) {
+          throw new Error(`Post-commit verification failed for ${check.path}`);
+        }
+        let oldPasswordAccepted = false;
+        try {
+          await decryptSecrets(current, oldPassword);
+          oldPasswordAccepted = true;
+        } catch {
+          // Expected: AES-GCM authentication rejects the retired key.
+        }
+        if (oldPasswordAccepted) throw new Error(`Retired master password still decrypts ${check.path}`);
+      }
+
+      for (const carrier of uniqueCarriers) {
+        if (readMasterPasswordFromCarrier(carrier) !== newPassword) {
+          throw new Error(`Post-commit credential carrier verification failed: ${carrier.path}`);
+        }
+      }
+
+      // Last, because it is the only participant that cannot be staged: the
+      // Keychain is written in place. Its previous value is captured first so
+      // the rollback below can restore it alongside the files.
+      for (const carrier of uniqueKeychain) {
+        keychainRestores.push({ carrier, previous: readKeychainPassword(carrier) });
+        writeKeychainPassword({ ...carrier, password: newPassword });
+        if (readKeychainPassword(carrier) !== newPassword) {
+          throw new Error(
+            `Post-commit Keychain verification failed: ${describeKeychainCarrier(carrier)}`,
+          );
+        }
+      }
+    } catch (error) {
+      // A Keychain entry that cannot be put back leaves this machine holding a
+      // password the store no longer accepts — the exact failure this carrier
+      // exists to prevent, and invisible unless it is said out loud. It must not
+      // replace the original error, so it is appended to it.
+      const unrestored = [];
+      for (const { carrier, previous } of keychainRestores.reverse()) {
+        try {
+          if (previous) writeKeychainPassword({ ...carrier, password: previous });
+        } catch {
+          unrestored.push(describeKeychainCarrier(carrier));
+        }
+      }
+      if (unrestored.length) {
+        error.message +=
+          `\nAND the previous password could not be restored to: ${unrestored.join(', ')}.` +
+          ' Shells reading those entries will fail to decrypt until they are set by hand.';
+      }
+      for (const write of applied.reverse()) {
+        if (write.backup && fs.existsSync(write.backup)) {
+          fs.renameSync(write.backup, write.path);
+          fs.chmodSync(write.path, write.mode);
+          fsyncDirectory(write.path);
+        }
+      }
+      throw error;
+    }
+
+    for (const write of writes) {
+      if (write.backup && fs.existsSync(write.backup)) fs.rmSync(write.backup, { force: true });
+    }
+
+    return {
+      stores: storeChecks.map(({ path: storePath, keys }) => ({ path: storePath, keys })),
+      carriers: uniqueCarriers.map((carrier) => ({ path: carrier.path, type: carrier.type })),
+      keychain: uniqueKeychain.map((carrier) => ({
+        service: carrier.service,
+        account: carrier.account || process.env.USER,
+      })),
+      old_password_rejected: true,
+    };
+  } finally {
+    // Both passwords were derived against during this transaction. The cache
+    // keys on the password digest so a stale entry can never be SERVED, but
+    // there is no reason to keep the retired key sitting in memory once the
+    // rotation is over — and on the failure path the staged-but-abandoned new
+    // key should go too.
+    clearDerivedKeyCache();
+    for (const write of writes) {
+      if (write.staged && fs.existsSync(write.staged)) fs.rmSync(write.staged, { force: true });
+      if (write.backup && fs.existsSync(write.backup)) fs.rmSync(write.backup, { force: true });
+    }
+  }
+}

package/src/secrets-remote-deploy.mjs

@@ -0,0 +1,250 @@
+/**
+ * Push the Total Recall secrets-store SSOT to a remote deploy target over SSH.
+ *
+ * Generic by design — Total Recall core never hardcodes a hostname, path, or
+ * product name. Every target (host, remote path, restart command) is
+ * declared by the user in this repo's own remote-targets.json, the same way
+ * repos/scopes are declared for export-env. This module only knows how to:
+ *   1. build the same dotenv projection export-env already builds,
+ *   2. fetch + merge it into a REMOTE file over SSH (never local disk),
+ *   3. optionally run a user-declared restart command over SSH.
+ *
+ * Secret values never touch argv, shell history, or process listings on
+ * either end — they're piped over stdin to a remote `cat > file` and never
+ * echoed back. Callers must not log the returned `dotenv`/`map` fields.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { buildEnvProjection, mergeEnvManagedBlock, projectSlugFromPath } from './secrets-env-export.mjs';
+import { resolveSecretsPath } from './secrets-store.mjs';
+import { authState } from './metadata-state.mjs';
+
+/**
+ * @param {string} brainDir
+ */
+export function resolveRemoteTargetsPath(brainDir) {
+  return path.join(path.dirname(resolveSecretsPath(brainDir)), 'remote-targets.json');
+}
+
+/**
+ * @typedef {{
+ *   name: string,
+ *   host: string,
+ *   user?: string,
+ *   port?: number,
+ *   remotePath: string,
+ *   filename?: string,
+ *   restartCommand?: string,
+ *   sshOpts?: string[],
+ *   keys?: string[],
+ *   includeGlobal?: boolean,
+ * }} RemoteTarget
+ */
+
+/** @param {string} brainDir @returns {RemoteTarget[]} */
+export function loadRemoteTargets(brainDir) {
+  const p = resolveRemoteTargetsPath(brainDir);
+  const data = authState(p).read([]);
+  if (!Array.isArray(data)) throw new Error('Invalid auth deployment target registry');
+  return data;
+}
+
+/** @param {string} brainDir @param {RemoteTarget[]} targets */
+export function saveRemoteTargets(brainDir, targets) {
+  const p = resolveRemoteTargetsPath(brainDir);
+  if (!Array.isArray(targets)) throw new Error('Invalid auth deployment target registry');
+  const store = authState(p); store.read([]); store.write(targets);
+  return store.documentPath;
+}
+
+/** @param {string} brainDir @param {RemoteTarget} target */
+export function addRemoteTarget(brainDir, target) {
+  if (!target?.name) throw new Error('Remote target requires a name');
+  if (!target?.host) throw new Error('Remote target requires a host');
+  if (!target?.remotePath) throw new Error('Remote target requires remotePath (remote directory)');
+  const targets = loadRemoteTargets(brainDir).filter((t) => t.name !== target.name);
+  targets.push({
+    name: target.name,
+    host: target.host,
+    user: target.user || 'root',
+    port: target.port || 22,
+    remotePath: target.remotePath,
+    filename: target.filename || '.env',
+    restartCommand: target.restartCommand || null,
+    sshOpts: target.sshOpts || [],
+    keys: target.keys || undefined,
+    includeGlobal: target.includeGlobal !== false,
+  });
+  const p = saveRemoteTargets(brainDir, targets);
+  return { path: p, targets };
+}
+
+/** @param {string} brainDir @param {string} name */
+export function removeRemoteTarget(brainDir, name) {
+  const targets = loadRemoteTargets(brainDir);
+  const next = targets.filter((t) => t.name !== name);
+  const removed = next.length !== targets.length;
+  if (removed) saveRemoteTargets(brainDir, next);
+  return { removed, targets: next };
+}
+
+function sshBaseArgs(target) {
+  return [
+    '-o', 'BatchMode=yes',
+    '-o', 'ConnectTimeout=8',
+    '-p', String(target.port || 22),
+    ...(target.sshOpts || []),
+  ];
+}
+
+function sshDestination(target) {
+  return `${target.user || 'root'}@${target.host}`;
+}
+
+/**
+ * Run a remote command over SSH, optionally piping stdin. Never uses a
+ * shell-interpolated string built from secret values — the remote command
+ * itself is a fixed, non-secret string; the secret body travels over stdin.
+ */
+function runSsh(target, remoteCommand, { input } = {}) {
+  const args = [...sshBaseArgs(target), sshDestination(target), remoteCommand];
+  const result = spawnSync('ssh', args, {
+    input: input != null ? input : undefined,
+    encoding: 'utf8',
+    timeout: 20000,
+  });
+  return result;
+}
+
+function quoteRemotePath(p) {
+  // POSIX single-quote escaping — safe for arbitrary remote paths.
+  return `'${String(p).replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Fetch the current remote file body (empty string if absent/unreachable-file).
+ */
+function fetchRemoteFile(target, remoteFile) {
+  const r = runSsh(target, `cat ${quoteRemotePath(remoteFile)} 2>/dev/null || true`);
+  if (r.error) throw new Error(`SSH connect failed for target "${target.name}": ${r.error.message}`);
+  return r.stdout || '';
+}
+
+/**
+ * Write body to the remote file via stdin (never as an argv/shell string),
+ * then chmod 600. Uses a temp file + atomic rename on the remote side so a
+ * dropped connection mid-write can't leave a truncated secrets file live.
+ */
+function writeRemoteFile(target, remoteFile, body) {
+  const tmp = `${remoteFile}.tr-tmp.$$`;
+  const cmd =
+    `set -e; TMP="${remoteFile}.tr-tmp.$$"; ` +
+    `cat > "$TMP" && chmod 600 "$TMP" && mv "$TMP" ${quoteRemotePath(remoteFile)}`;
+  const r = runSsh(target, cmd, { input: body });
+  if (r.error) throw new Error(`SSH write failed for target "${target.name}": ${r.error.message}`);
+  if (r.status !== 0) {
+    throw new Error(
+      `Remote write failed for target "${target.name}" (exit ${r.status}): ${(r.stderr || '').slice(0, 500)}`,
+    );
+  }
+  return true;
+}
+
+/**
+ * Deploy the SSOT projection to one configured remote target.
+ *
+ * @param {string} brainDir
+ * @param {string} targetName
+ * @param {{ dryRun?: boolean, keys?: string[], skipRestart?: boolean }} opts
+ */
+export async function deployEnvToRemote(brainDir, targetName, opts = {}) {
+  const targets = loadRemoteTargets(brainDir);
+  const target = targets.find((t) => t.name === targetName);
+  if (!target) {
+    throw new Error(
+      `Unknown remote target "${targetName}". Configure one first: npx total-recall secret remote add ${targetName} --host <host> --path </remote/dir>`,
+    );
+  }
+
+  // Match the same projection local `export-env --path .` builds: repo-bound
+  // secrets (set with --repo <name>) only resolve when the caller's project
+  // slug is passed through. Without this, deployEnvToRemote silently dropped
+  // every repo-scoped key and pushed only unbound/global ones — the opposite
+  // of what --repo scoping is for. cwd is the right default since this CLI
+  // is always invoked from the repo root (same assumption --path . makes).
+  const projectPath = opts.projectPath || process.cwd();
+  const projection = await buildEnvProjection(brainDir, {
+    includeGlobal: target.includeGlobal !== false,
+    keys: opts.keys?.length ? opts.keys : target.keys,
+    projectPath,
+    projectSlug: opts.projectSlug || projectSlugFromPath(projectPath),
+  });
+
+  const remoteFile = path.posix.join(target.remotePath, target.filename || '.env');
+
+  if (opts.dryRun) {
+    return {
+      dryRun: true,
+      target: target.name,
+      host: target.host,
+      remoteFile,
+      keys: projection.keys,
+      count: projection.count,
+    };
+  }
+
+  if (!projection.count) {
+    return {
+      dryRun: false,
+      target: target.name,
+      host: target.host,
+      remoteFile,
+      keys: [],
+      count: 0,
+      skipped: 'no matching keys',
+    };
+  }
+
+  const existing = fetchRemoteFile(target, remoteFile);
+  const merged = mergeEnvManagedBlock(existing, projection.body);
+  writeRemoteFile(target, remoteFile, merged);
+
+  let restarted = false;
+  let restartOutput = null;
+  if (target.restartCommand && !opts.skipRestart) {
+    const r = runSsh(target, target.restartCommand);
+    restarted = r.status === 0;
+    restartOutput = (r.stdout || '') + (r.stderr || '');
+  }
+
+  return {
+    dryRun: false,
+    target: target.name,
+    host: target.host,
+    remoteFile,
+    keys: projection.keys,
+    count: projection.count,
+    restarted,
+    restartOutput: restartOutput ? restartOutput.slice(0, 2000) : null,
+  };
+}
+
+/**
+ * Deploy to every remote target that has this key bound via `keys`, or to
+ * every target when the key list is unset (target opts into "all keys").
+ */
+export async function deployKeyToRemotes(brainDir, key, opts = {}) {
+  const targets = loadRemoteTargets(brainDir);
+  const matching = targets.filter((t) => !t.keys?.length || t.keys.includes(key));
+  const results = [];
+  for (const t of matching) {
+    try {
+      results.push(await deployEnvToRemote(brainDir, t.name, opts));
+    } catch (err) {
+      results.push({ target: t.name, host: t.host, ok: false, error: err.message });
+    }
+  }
+  return results;
+}