total-recall-brain 3.22.0 → 3.23.0

package/src/cli/secret.mjs

@@ -5,7 +5,7 @@
  *   npx total-recall secret set <key> <value> [--provider name] [--scope global|project]
  *   npx total-recall secret get <key>          # prints value (use carefully)
  *   npx total-recall secret list
- *   npx total-recall secret rotate <key> <new-value>
+ *   npx total-recall secret rotate <key>       # prompts for the value
  *   npx total-recall secret delete <key>
  *   npx total-recall secret audit [--limit N]
  *   npx total-recall secret usage [--days N]
@@ -60,6 +60,19 @@ import { listProviders, getProvider } from '../core/provider-catalog.mjs';
 import { resolveBrainDir, parseLayerFlag } from './agent-dir.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+import {
+  generateSecretsMasterPassword,
+  readMasterPasswordFromCarrier,
+  rekeySecretsTransaction,
+} from '../core/secrets-rekey.mjs';
+import {
+  DEFAULT_KEYCHAIN_SERVICE,
+  keychainAvailable,
+  readKeychainPassword,
+} from '../core/secrets-keychain.mjs';
+import { agentDir as configuredAgentDir, getActiveBrains } from '../core/config.mjs';
 
 // Reads a secret value from stdin (fd 0) so it never has to appear as a CLI
 // argument — CLI args land in shell history, `ps aux`, and any transcript
@@ -71,6 +84,75 @@ function readStdinValue() {
   return raw.endsWith('\n') ? raw.slice(0, -1) : raw;
 }
 
+/**
+ * Read the OS clipboard. Keeps a pasted credential inside this process rather
+ * than routing it through argv, shell history, or an agent transcript.
+ *
+ * @returns {string}
+ */
+function readSystemClipboard() {
+  const cmds =
+    process.platform === 'darwin'
+      ? [['pbpaste', []]]
+      : process.platform === 'win32'
+        ? [['powershell', ['-NoProfile', '-Command', 'Get-Clipboard']]]
+        : [
+            ['wl-paste', ['--no-newline']],
+            ['xclip', ['-selection', 'clipboard', '-o']],
+            ['xsel', ['--clipboard', '--output']],
+          ];
+  for (const [cmd, args] of cmds) {
+    try {
+      return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    } catch {
+      // try the next clipboard tool
+    }
+  }
+  return '';
+}
+
+/**
+ * Read a credential without echoing it and without it ever becoming an argv
+ * element. `argv` is world-readable via `ps`, lands in shell history, and is
+ * captured verbatim by any agent driving this CLI. Falls back to reading one
+ * line from stdin when the input is piped rather than a terminal.
+ *
+ * @param {string} label
+ * @returns {Promise<string>}
+ */
+function readSecretValue(label) {
+  return new Promise((resolve, reject) => {
+    const input = process.stdin;
+    if (!input.isTTY) {
+      resolve(readStdinValue());
+      return;
+    }
+    process.stdout.write(label);
+    input.setRawMode(true);
+    input.resume();
+    input.setEncoding('utf8');
+    let buf = '';
+    const onData = (ch) => {
+      if (ch === '\n' || ch === '\r' || ch === '\u0004') {
+        input.setRawMode(false);
+        input.pause();
+        input.removeListener('data', onData);
+        process.stdout.write('\n');
+        resolve(buf.trim());
+      } else if (ch === '\u0003') {
+        input.setRawMode(false);
+        process.stdout.write('\n');
+        process.exit(130);
+      } else if (ch === '\u007f' || ch === '\b') {
+        buf = buf.slice(0, -1);
+      } else {
+        buf += ch;
+      }
+    };
+    input.on('data', onData);
+  });
+}
+
 function printHelp() {
   console.log(`
   total-recall secret — Secrets store (separate from memory vault)
@@ -84,7 +166,18 @@ function printHelp() {
     generate <key>        Generate a random secret for outside integrations
     get <key>             Print secret value (audited)
     list                  List keys + metadata only (no values)
-    rotate <key> [value]  Replace value and mark rotated (also supports --stdin)
+    rotate <key>          Replace value and mark rotated. Prompts for the value;
+                           --stdin reads fd0, --from-clipboard reads the OS
+                           clipboard (use the browser you are already signed
+                           into). The value never appears in argv or output.
+    rekey                 Rotate the secrets-store master password transactionally.
+                           The replacement is generated in memory by default;
+                           --stdin accepts a coordinated replacement without argv.
+                           --launch-agent/--env-file/--keychain select persistent
+                           carriers. The macOS Keychain entry is included
+                           automatically when present, because a shell profile
+                           that reads it would otherwise be left on the retired
+                           password; --no-keychain opts out.
     delete <key>          Remove a secret
     audit [--limit N]     Recent set/get/rotate events (no values)
     usage [--days N]      Sum usage.jsonl for last N days (default 1)
@@ -232,6 +325,11 @@ function parseArgs(args) {
     remotePort: 22,
     restartCmd: null,
     stdin: false,
+    launchAgents: [],
+    envFiles: [],
+    keychainServices: [],
+    keychain: true,
+    storePaths: [],
   };
   if (!args.length || args[0] === '--help' || args[0] === '-h') {
     out.help = true;
@@ -382,6 +480,9 @@ function parseArgs(args) {
       case '--replace-all':
         out.replaceAll = true;
         break;
+      case '--from-clipboard':
+        out.fromClipboard = true;
+        break;
       case '--export-env':
         out.exportEnv = true;
         break;
@@ -434,6 +535,21 @@ function parseArgs(args) {
       case '--stdin':
         out.stdin = true;
         break;
+      case '--launch-agent':
+        out.launchAgents.push(args[++i]);
+        break;
+      case '--env-file':
+        out.envFiles.push(args[++i]);
+        break;
+      case '--keychain':
+        out.keychainServices.push(args[++i]);
+        break;
+      case '--no-keychain':
+        out.keychain = false;
+        break;
+      case '--store':
+        out.storePaths.push(args[++i]);
+        break;
       case '--help':
       case '-h':
         out.help = true;
@@ -466,11 +582,11 @@ export default async function secretCli(argv) {
   }
 
   if (opts.stdin) {
-    if (!['set', 'rotate'].includes(opts.command)) {
-      console.error('❌ --stdin is only valid with `set` or `rotate`');
+    if (!['set', 'rotate', 'rekey'].includes(opts.command)) {
+      console.error('❌ --stdin is only valid with `set`, `rotate`, or `rekey`');
       process.exit(1);
     }
-    if (!opts.key) {
+    if (opts.command !== 'rekey' && !opts.key) {
       console.error(`Usage: total-recall secret ${opts.command} <key> --stdin`);
       process.exit(1);
     }
@@ -482,6 +598,102 @@ export default async function secretCli(argv) {
   }
 
   try {
+    if (opts.command === 'rekey') {
+      const carriers = [
+        ...opts.launchAgents.filter(Boolean).map((carrierPath) => ({
+          path: path.resolve(carrierPath),
+          type: 'launchd-plist',
+          allowInsert: true,
+        })),
+        ...opts.envFiles.filter(Boolean).map((carrierPath) => ({
+          path: path.resolve(carrierPath),
+          type: 'env',
+          allowInsert: true,
+        })),
+      ];
+
+      if (!carriers.length && process.platform === 'darwin') {
+        const launchAgentsDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+        if (fs.existsSync(launchAgentsDir)) {
+          for (const entry of fs.readdirSync(launchAgentsDir)) {
+            if (!entry.endsWith('.plist')) continue;
+            const carrierPath = path.join(launchAgentsDir, entry);
+            const source = fs.readFileSync(carrierPath, 'utf8');
+            if (source.includes('<key>TR_SECRETS_PASSWORD</key>')) {
+              carriers.push({ path: carrierPath, type: 'launchd-plist' });
+            }
+          }
+        }
+      }
+
+      // A shell profile that reads the password from the Keychain is the most
+      // common macOS arrangement, and it is invisible to a file-carrier scan.
+      // Left out, a rotation succeeds and every interactive shell breaks at
+      // once — so the entry is picked up by default when it exists.
+      const keychainCarriers = opts.keychainServices.filter(Boolean).map((service) => ({ service }));
+      if (!keychainCarriers.length && opts.keychain !== false && keychainAvailable()) {
+        if (readKeychainPassword({ service: DEFAULT_KEYCHAIN_SERVICE })) {
+          keychainCarriers.push({ service: DEFAULT_KEYCHAIN_SERVICE });
+        }
+      }
+
+      if (!carriers.length && !keychainCarriers.length) {
+        console.error(
+          '❌ No persistent master-password carrier found. Use --launch-agent <path>, --env-file <path> or --keychain <service>.',
+        );
+        process.exit(1);
+      }
+
+      const currentPasswords = [
+        ...carriers.map((carrier) => readMasterPasswordFromCarrier(carrier)),
+        ...keychainCarriers.map((carrier) => readKeychainPassword(carrier)),
+      ].filter(Boolean);
+      const oldPassword = currentPasswords[0] || process.env.TR_SECRETS_PASSWORD;
+      if (!oldPassword) {
+        console.error('❌ The current master password is unavailable from the selected carriers.');
+        process.exit(1);
+      }
+      if (currentPasswords.some((value) => value !== oldPassword)) {
+        console.error('❌ Selected credential carriers do not contain the same current master password.');
+        console.error('   Every carrier must hold the same password before one can replace it.');
+        process.exit(1);
+      }
+
+      const defaultBrainDirs = [
+        configuredAgentDir,
+        brainDir,
+        ...Object.values(getActiveBrains()).map((brain) => brain?.brainDir),
+      ].filter(Boolean);
+      const legacyAgentDirs = defaultBrainDirs
+        .filter(
+          (dir) =>
+            path.basename(dir) === 'total-recall' && path.basename(path.dirname(dir)) === 'skills',
+        )
+        .map((dir) => path.dirname(path.dirname(dir)));
+      const storePaths = opts.storePaths.length
+        ? opts.storePaths.map((storePath) => path.resolve(storePath))
+        : [...new Set([...defaultBrainDirs, ...legacyAgentDirs].map((dir) => resolveSecretsPath(dir)))].filter(
+            (storePath) => fs.existsSync(storePath),
+          );
+      const newPassword = opts.value || generateSecretsMasterPassword();
+      const result = await rekeySecretsTransaction({
+        storePaths,
+        carriers,
+        keychainCarriers,
+        oldPassword,
+        newPassword,
+      });
+
+      console.log(`\n  ✅ Secrets master password rotated transactionally`);
+      console.log(`     stores re-encrypted and verified: ${result.stores.length}`);
+      console.log(`     persistent carriers updated: ${result.carriers.length}`);
+      console.log(`     keychain entries updated: ${result.keychain.length}`);
+      console.log(`     retired password rejected: yes`);
+      console.log(`     replacement value was not printed`);
+      console.log(`     restart affected services so they load the new credential\n`);
+      return;
+    }
+
     if (opts.command === 'set') {
       if (!opts.key || opts.value == null) {
         console.error('Usage: total-recall secret set <key> <value>');
@@ -918,8 +1130,39 @@ export default async function secretCli(argv) {
     }
 
     if (opts.command === 'rotate') {
-      if (!opts.key || !opts.value) {
-        console.error('Usage: total-recall secret rotate <key> <new-value> [--export-env|--export-all|--remote <name>]');
+      if (!opts.key) {
+        console.error('Usage: total-recall secret rotate <key> [--export-env|--export-all|--remote <name>]');
+        console.error('       The new value is read from a prompt or stdin — never from argv.');
+        process.exit(1);
+      }
+      // A credential passed as an argument is disclosed the moment it is typed:
+      // argv is readable by any user via `ps`, is saved to shell history, and is
+      // captured verbatim by any agent driving this CLI. Read it from a hidden
+      // prompt (or stdin when piped) so it stays in this process's memory.
+      if (!opts.value && opts.fromClipboard) {
+        // Read the OS clipboard inside this process. This lets the operator use
+        // the browser they are already signed into — copy the new credential
+        // there, and the value travels clipboard -> Node -> secrets.enc without
+        // ever passing through argv, a terminal echo, or an agent transcript.
+        opts.value = readSystemClipboard();
+        if (!opts.value) {
+          console.error('Error: clipboard is empty — copy the new credential first.');
+          process.exit(1);
+        }
+        console.log(`  📋 Read ${opts.value.length} chars from the clipboard (value not shown).`);
+      }
+      if (!opts.value) {
+        opts.value = await readSecretValue(`New value for ${opts.key}: `);
+      } else if (!opts.fromClipboard) {
+        console.error(
+          `\n  ⚠️  WARNING: the value was passed as a command-line argument.\n` +
+            `     It is now in your shell history and was visible to any user\n` +
+            `     running \`ps\` on this machine. Treat it as already disclosed\n` +
+            `     and rotate again using the prompt: total-recall secret rotate ${opts.key}\n`,
+        );
+      }
+      if (!opts.value) {
+        console.error('Error: empty value — aborting rotation.');
         process.exit(1);
       }
       if (opts.remote) {

package/src/core/browser-session.mjs

@@ -90,17 +90,42 @@ export async function launchRotationContext(brainDir, opts = {}) {
   // headless first-run would simply hang on an invisible challenge.
   const headless = opts.headless === true;
 
-  try {
-    const context = await chromium.launchPersistentContext(profileDir, {
-      headless,
-      viewport: { width: 1440, height: 900 },
-      args: ['--disable-blink-features=AutomationControlled', '--no-first-run'],
-    });
-    context.setDefaultTimeout(opts.timeoutMs ?? 30_000);
-    return { ok: true, context, profileDir };
-  } catch (err) {
-    return { ok: false, error: `failed to launch browser profile: ${err.message}`, profileDir };
+  const base = {
+    headless,
+    viewport: { width: 1440, height: 900 },
+    args: ['--disable-blink-features=AutomationControlled', '--no-first-run'],
+  };
+
+  // Playwright's bundled Chromium is not available on every host — it has
+  // dropped support for older macOS versions, and the pinned build is often
+  // simply not downloaded. A rotation that dies here strands the operator with
+  // live, burned credentials, so fall back to any locally installed Chrome or
+  // Edge before giving up.
+  const attempts = [
+    { label: 'bundled chromium', options: base },
+    { label: 'system chrome', options: { ...base, channel: 'chrome' } },
+    { label: 'system edge', options: { ...base, channel: 'msedge' } },
+  ];
+
+  const failures = [];
+  for (const attempt of attempts) {
+    try {
+      const context = await chromium.launchPersistentContext(profileDir, attempt.options);
+      context.setDefaultTimeout(opts.timeoutMs ?? 30_000);
+      return { ok: true, context, profileDir, browser: attempt.label };
+    } catch (err) {
+      failures.push(`${attempt.label}: ${err.message.split('\n')[0]}`);
+    }
   }
+
+  return {
+    ok: false,
+    error:
+      `failed to launch a browser profile. Tried ${attempts.length} browsers —\n  ` +
+      failures.join('\n  ') +
+      '\nInstall one with: npx playwright install chromium (or install Google Chrome).',
+    profileDir,
+  };
 }
 
 /**
@@ -128,16 +153,46 @@ export async function openConsole(context, recipe) {
  * @param {{ signed_in?: string, signed_out?: string }} recipe
  * @returns {Promise<boolean>}
  */
-export async function isAuthenticated(page, recipe) {
+export async function isAuthenticated(page, recipe, opts = {}) {
   // A visible signed-out marker (login form, "Sign in" CTA) is decisive.
   if (recipe.signed_out) {
     const out = await page.locator(recipe.signed_out).first().isVisible().catch(() => false);
     if (out) return false;
   }
+
   if (recipe.signed_in) {
-    return page.locator(recipe.signed_in).first().isVisible().catch(() => false);
+    // Consoles are SPA-heavy: the positive marker frequently renders a second
+    // or two after DOMContentLoaded. Give it a real wait instead of a single
+    // instantaneous probe.
+    const appeared = await page
+      .locator(recipe.signed_in)
+      .first()
+      .waitFor({ state: 'visible', timeout: opts.markerTimeoutMs ?? 8000 })
+      .then(() => true)
+      .catch(() => false);
+    if (appeared) return true;
+
+    // The positive marker never showed and no login form matched. Selectors go
+    // stale constantly, so fall back to the one signal every console agrees on:
+    // an unauthenticated request gets redirected to a login URL.
+    return !looksLikeLoginUrl(page.url());
   }
-  return true;
+
+  return !looksLikeLoginUrl(page.url());
+}
+
+/**
+ * Provider-agnostic sign-in detection. Consoles redirect anonymous visitors to
+ * a login route rather than returning an error status, so the landed URL is a
+ * far more durable signal than any per-provider CSS selector.
+ *
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function looksLikeLoginUrl(url) {
+  return /\/(login|log-in|sign[_-]?in|signin|auth\/login|sessions\/new|u\/login)(\/|\?|#|$)/i.test(
+    String(url || ''),
+  );
 }
 
 /**

package/src/core/headscale-client.mjs

@@ -225,3 +225,90 @@ export async function createHeadscalePreAuthKey(options = {}, brainDir) {
   }
   throw lastError || new Error('Headscale did not return a pre-auth key');
 }
+
+/**
+ * Read the control server's ACL policy.
+ *
+ * Requires the server to run with `policy.mode: database` — in `file` mode the
+ * policy lives on the control server's disk and the API cannot manage it.
+ *
+ * Headscale returns a 500 (not a 404) when database mode is on but the policy
+ * table is still empty, so an unset policy is normalised to `policy: null`
+ * rather than thrown. That distinction matters: "no policy yet" is the expected
+ * first-run state, whereas a real transport or auth failure must still surface.
+ */
+export async function getHeadscalePolicy(brainDir) {
+  try {
+    const data = await headscaleFetch('/api/v1/policy', {}, brainDir);
+    return {
+      policy: data?.policy ?? null,
+      updatedAt: data?.updatedAt ?? null,
+      configured: Boolean(data?.policy),
+      raw: data,
+    };
+  } catch (err) {
+    const detail = String(err.detail || '');
+    const emptyPolicyTable =
+      err.status === 404 ||
+      (err.status === 500 && /policy|not found|no such/i.test(detail));
+    if (emptyPolicyTable) {
+      return { policy: null, updatedAt: null, configured: false, unset: true, raw: null };
+    }
+    if (err.status === 400 && /database/i.test(detail)) {
+      const modeError = new Error(
+        'Headscale is running in file policy mode; set `policy.mode: database` to manage the policy over the API',
+      );
+      modeError.status = err.status;
+      modeError.detail = err.detail;
+      modeError.code = 'POLICY_MODE_FILE';
+      throw modeError;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Replace the control server's ACL policy.
+ *
+ * `policy` may be an object (serialised here) or an already-formatted
+ * HuJSON/JSON string. Headscale validates server-side and rejects the write if
+ * the policy's own `tests` block fails, so a bad policy never lands.
+ */
+export async function setHeadscalePolicy(policy, brainDir) {
+  if (!policy) throw new Error('A policy is required');
+  const serialised = typeof policy === 'string' ? policy : JSON.stringify(policy, null, 2);
+
+  const data = await headscaleFetch(
+    '/api/v1/policy',
+    { method: 'PUT', body: JSON.stringify({ policy: serialised }) },
+    brainDir,
+  );
+  return { policy: data?.policy ?? serialised, updatedAt: data?.updatedAt ?? null, raw: data };
+}
+
+/**
+ * Build a policy that lets every mesh member reach every other member, and use
+ * Tailscale SSH between them as any non-root user.
+ *
+ * This is deliberately the simple single-operator shape: one person's own
+ * machines, all equally trusted. It is NOT appropriate for a multi-tenant
+ * tailnet — headscale membership is the trust boundary, so anything admitted to
+ * the mesh inherits this access. Narrow `src`/`dst` before adding a node you do
+ * not control.
+ *
+ * root is excluded via `autogroup:nonroot`: SSH-ing straight to root over the
+ * mesh removes the audit trail that makes per-user access worth having.
+ */
+export function buildMeshSshPolicy({ allowRoot = false } = {}) {
+  return {
+    acls: [{ action: 'accept', src: ['*'], dst: ['*:*'] }],
+    ssh: [
+      {
+        action: 'accept',
+        src: ['autogroup:member'],
+        dst: ['autogroup:self'],
+        users: allowRoot ? ['autogroup:nonroot', 'root'] : ['autogroup:nonroot'],
+      },
+    ],
+  };
+}