total-recall-brain 3.41.2 → 3.41.4

package/scaffold/.agent/skills/total-recall/plugins/auth/cli.mjs

@@ -9,6 +9,7 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { hostSecretsBrainDir } from './src/host-secrets-store.mjs';
 
 function resolveTrPath() {
   const localTr = path.join(process.cwd(), 'bin', 'total-recall.mjs');
@@ -19,13 +20,13 @@ function resolveTrPath() {
 }
 
 async function resolveSecret(key) {
-  const { getSecret, defaultBrainDir } = await import('./src/secrets-store.mjs');
-  const result = await getSecret(process.env.TR_SECRETS_BRAIN || defaultBrainDir(), key, { actor: 'auth-cli', action: 'use' });
+  const { getSecret } = await import('./src/secrets-store.mjs');
+  const result = await getSecret(hostSecretsBrainDir(), key, { actor: 'auth-cli', action: 'use' });
   return result.found ? result.value : null;
 }
 
 function resolveBrainDir() {
-  return process.env.TR_SECRETS_BRAIN || process.env.TR_BRAIN || path.join(process.env.HOME || '', '.agent', 'skills', 'total-recall');
+  return hostSecretsBrainDir();
 }
 
 async function listStoredPasskeys() {
@@ -33,7 +34,11 @@ async function listStoredPasskeys() {
   return listPasskeys(resolveBrainDir());
 }
 
-async function handleStatus(json) {
+async function handleStatus(subArgs, json) {
+  if (Array.isArray(subArgs) && (subArgs.includes('--help') || subArgs.includes('-h') || subArgs[0] === 'help')) {
+    console.log('Usage: total-recall auth status [--json]');
+    return;
+  }
   const passkeys = await listStoredPasskeys();
   const googleClientId = await resolveSecret('GOOGLE_CLIENT_ID');
   const googleClientSecret = await resolveSecret('GOOGLE_CLIENT_SECRET');
@@ -87,9 +92,15 @@ async function handleStatus(json) {
 }
 
 async function handlePasskey(subArgs, json) {
-  const passkeys = await listStoredPasskeys();
   const action = subArgs[0] || 'list';
 
+  if (action === 'help' || action === '--help' || action === '-h') {
+    console.log('Usage: total-recall auth passkey [list|status|delete <id>] [--json]');
+    return;
+  }
+
+  const passkeys = await listStoredPasskeys();
+
   if (action === 'list') {
     if (json) {
       console.log(JSON.stringify({ count: passkeys.length, passkeys }, null, 2));
@@ -112,25 +123,80 @@ async function handlePasskey(subArgs, json) {
     return;
   }
 
+  if (action === 'delete' || action === 'remove' || action === 'rm') {
+    const id = subArgs[1];
+    if (!id) {
+      console.error('Credential ID required: total-recall auth passkey delete <id>');
+      process.exitCode = 1;
+      return;
+    }
+    const { deletePasskey } = await import('./src/webauthn-store.mjs');
+    const result = deletePasskey(resolveBrainDir(), id);
+    if (!result.found) {
+      console.error(`Passkey not found: ${id}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (json) {
+      console.log(JSON.stringify({ success: true, deleted: id }));
+    } else {
+      console.log(`Passkey removed: ${id}`);
+    }
+    return;
+  }
+
   console.error(`Unknown passkey action: ${action}`);
   process.exitCode = 1;
 }
 
 async function handleGoogle(subArgs, json) {
+  const action = subArgs[0] || 'status';
+  if (action === 'help' || action === '--help' || action === '-h') {
+    console.log('Usage: total-recall auth google [status|connect|accounts|refresh <id>|disconnect <id>] [--json]');
+    return;
+  }
   const { createGoogleOAuth } = await import('./src/google-oauth.mjs');
   const google = createGoogleOAuth({ brainDir: resolveBrainDir() });
-  const action = subArgs[0] || 'status';
-  if (action === 'accounts') { console.log(JSON.stringify({ accounts: google.status() })); return; }
+  if (action === 'accounts') {
+    const accounts = google.status();
+    if (json) {
+      console.log(JSON.stringify({ accounts }));
+    } else {
+      console.log(`Google Connected Accounts: ${accounts.length}`);
+      for (const a of accounts) {
+        console.log(`  • [${a.status}] ${a.email || a.account_id} (Expires: ${a.expiry || 'never'})`);
+      }
+    }
+    return;
+  }
   if (action === 'refresh' || action === 'disconnect') {
-    if (!subArgs[1]) throw new Error('Google account identifier required');
-    if (action === 'refresh') { await google.access(subArgs[1]); console.log(JSON.stringify({ accounts: google.status() })); }
-    else console.log(JSON.stringify(await google.disconnect(subArgs[1])));
+    if (!subArgs[1]) {
+      console.error(`Google account identifier required: total-recall auth google ${action} <id>`);
+      process.exitCode = 1;
+      return;
+    }
+    if (action === 'refresh') {
+      await google.access(subArgs[1]);
+      const accounts = google.status();
+      if (json) console.log(JSON.stringify({ accounts }));
+      else console.log(`Account ${subArgs[1]} refreshed.`);
+    } else {
+      const res = await google.disconnect(subArgs[1]);
+      if (json) console.log(JSON.stringify(res));
+      else console.log(`Account ${subArgs[1]} disconnected.`);
+    }
+    return;
+  }
+  if (!['status', 'connect'].includes(action)) {
+    console.error(`Unknown action: ${action}. Use: total-recall auth google [status|connect|accounts|refresh|disconnect]`);
+    process.exitCode = 1;
     return;
   }
-  if (!['status', 'connect'].includes(action)) throw new Error('Use google status|connect|accounts|refresh|disconnect');
   let cfg;
   try { cfg = google.config(); } catch {
-    console.log(JSON.stringify({ configured: false, error: 'Configure GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and GOOGLE_REDIRECT_URI in auth' })); process.exitCode = 2; return;
+    console.log(JSON.stringify({ configured: false, error: 'Configure GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and GOOGLE_REDIRECT_URI in auth' }));
+    process.exitCode = 2;
+    return;
   }
   // Browser initiation sets its own HttpOnly state cookie; never manufacture a state-less consent URL in the CLI.
   const authUrl = new URL('/auth/google', cfg.redirectUri).href;
@@ -138,7 +204,11 @@ async function handleGoogle(subArgs, json) {
   console.log(json ? JSON.stringify(out) : `Open sign-in: ${authUrl}`);
 }
 
-async function handleProbe(json) {
+async function handleProbe(subArgs, json) {
+  if (Array.isArray(subArgs) && (subArgs.includes('--help') || subArgs.includes('-h') || subArgs[0] === 'help')) {
+    console.log('Usage: total-recall auth probe [--json]');
+    return;
+  }
   const host = process.env.TR_HOST || 'http://localhost:3000';
   const endpoints = ['/auth/status', '/auth/providers', '/health'];
   const results = [];
@@ -182,7 +252,11 @@ async function handleProbe(json) {
   if (!allOk) process.exitCode = 1;
 }
 
-async function handleSession(json) {
+async function handleSession(subArgs, json) {
+  if (Array.isArray(subArgs) && (subArgs.includes('--help') || subArgs.includes('-h') || subArgs[0] === 'help')) {
+    console.log('Usage: total-recall auth session [--json]');
+    return;
+  }
   const brain = resolveBrainDir();
   const secretExists = Boolean(await resolveSecret('SESSION_SECRET'));
 
@@ -208,7 +282,11 @@ async function handleSecret(subArgs, json) {
   await secretCli(forwarded);
 }
 
-async function handleAudit(json) {
+async function handleAudit(subArgs, json) {
+  if (Array.isArray(subArgs) && (subArgs.includes('--help') || subArgs.includes('-h') || subArgs[0] === 'help')) {
+    console.log('Usage: total-recall auth audit [--json]');
+    return;
+  }
   const brain = resolveBrainDir();
   const webauthnPath = path.join(brain, 'config', 'webauthn.json');
   const findings = [];
@@ -284,16 +362,41 @@ async function handleAudit(json) {
 }
 
 async function handleRotate(subArgs, json) {
+  if (Array.isArray(subArgs) && (subArgs.includes('--help') || subArgs.includes('-h') || subArgs[0] === 'help')) {
+    console.log('Usage: total-recall auth rotate [--collaboration] [--json]');
+    return;
+  }
   const { createSessionCredentials } = await import('./src/session-credentials.mjs');
   const { defaultBrainDir } = await import('./src/secrets-store.mjs');
   const purpose = subArgs.includes('--collaboration') ? 'collaboration' : 'dashboard';
   const result = createSessionCredentials({ brainDir: process.env.TR_SECRETS_BRAIN || defaultBrainDir() }).rotateSession(purpose);
   console.log(json ? JSON.stringify(result) : 'Auth signing credential rotated; existing sessions are invalidated.');
 }
+
 async function handlePassword(args, json) {
-  if (args[0] !== 'set' || !args.includes('--stdin') || args.slice(1).some(value => !['--stdin', '--force-reset'].includes(value))) throw new Error('Use auth password set --stdin');
+  if (!Array.isArray(args) || args.includes('--help') || args.includes('-h') || args[0] === 'help') {
+    console.log('Usage: total-recall auth password set --stdin [--force-reset]');
+    console.log('       total-recall auth password status [--json]');
+    return;
+  }
+  if (args[0] === 'status') {
+    const { createSessionCredentials } = await import('./src/session-credentials.mjs');
+    const state = createSessionCredentials({ brainDir: resolveBrainDir() }).dashboardState();
+    if (json) {
+      console.log(JSON.stringify(state));
+    } else {
+      console.log(`Dashboard Password: ${state.configured ? 'Configured' : 'Not configured'}`);
+      if (state.forcePasswordReset) console.log('  • Password reset is currently enforced');
+    }
+    return;
+  }
+  if (args[0] !== 'set' || !args.includes('--stdin') || args.slice(1).some(value => !['--stdin', '--force-reset'].includes(value))) {
+    console.error('Use: total-recall auth password set --stdin [--force-reset]');
+    process.exitCode = 1;
+    return;
+  }
   const chunks = []; let size = 0;
-  for await (const chunk of process.stdin) { size += chunk.length; if (size > 8192) throw new Error('Password input exceeds limit'); chunks.push(chunk); }
+  for await (const chunk of process.stdin) { size += chunk.length; if (size > 8192) { console.error('Password input exceeds limit'); process.exitCode = 1; return; } chunks.push(chunk); }
   const password = Buffer.concat(chunks).toString('utf8').replace(/\r?\n$/, '');
   const { createSessionCredentials } = await import('./src/session-credentials.mjs');
   const result = await createSessionCredentials({ brainDir: resolveBrainDir() }).setDashboardPassword(password, { forcePasswordReset: args.includes('--force-reset') });
@@ -313,10 +416,10 @@ export async function run(argv = []) {
 
   switch (command) {
     case 'status':
-      await handleStatus(isJson);
+      await handleStatus(rest, isJson);
       break;
     case 'audit':
-      await handleAudit(isJson);
+      await handleAudit(rest, isJson);
       break;
     case 'rotate':
       await handleRotate(rest, isJson);
@@ -328,32 +431,95 @@ export async function run(argv = []) {
       await handlePasskey(rest, isJson);
       break;
     case 'key': {
+      if (rest.includes('--help') || rest.includes('-h') || rest[0] === 'help') {
+        console.log('Usage: total-recall auth key list [--json]');
+        console.log('       total-recall auth key issue <name> --scopes <csv> [--role <role>] [--kind <kind>] [--expires <date>] [--json]');
+        console.log('       total-recall auth key revoke <id> [--json]');
+        console.log('       total-recall auth key usage [id] [--json]');
+        console.log('       total-recall auth key roles [--json]');
+        console.log('       total-recall auth key role-set <name> --scopes <csv> [--json]');
+        break;
+      }
       const { createKeyStore } = await import('./src/access-keys.mjs');
       const store = createKeyStore({ brainDir: resolveBrainDir() });
       const [action = 'list', id] = rest;
       const flag = name => { const at = rest.indexOf(name); return at < 0 ? undefined : rest[at + 1]; };
       let result;
-      if (action === 'list') result = store.loadKeys().map(({ token_hash, ...key }) => key);
-      else if (action === 'issue') result = store.issueKey(id, { scopes: flag('--scopes')?.split(','), role: flag('--role'), kind: flag('--kind'), expires_at: flag('--expires') });
-      else if (action === 'revoke') result = store.revokeKey(id);
-      else if (action === 'usage') result = store.listKeyUsage(id);
-      else if (action === 'roles') result = store.loadRoles();
-      else if (action === 'role-set') result = store.setRole(id, flag('--scopes')?.split(','));
-      else throw new Error('Use auth key list|issue <name> --scopes <csv> [--role role] [--expires date]|revoke <id>|usage [id]|roles|role-set <name> --scopes <csv>');
-      console.log(JSON.stringify(result)); break;
+      if (action === 'list') {
+        const keys = store.loadKeys().map(({ token_hash, ...key }) => key);
+        if (isJson) {
+          console.log(JSON.stringify(keys));
+        } else {
+          console.log(`Access Keys: ${keys.length}`);
+          for (const k of keys) {
+            const status = k.revoked ? '[REVOKED]' : '[ACTIVE]';
+            console.log(`  • ${status} ${k.name} (${k.token_prefix}…)`);
+            console.log(`    ID: ${k.id}`);
+            console.log(`    Scopes: ${(k.scopes || []).join(', ') || 'none'}`);
+            if (k.expires_at) console.log(`    Expires: ${k.expires_at}`);
+            if (k.last_used_at) console.log(`    Last used: ${k.last_used_at} (${k.hit_count} hits)`);
+          }
+        }
+        break;
+      } else if (action === 'issue') {
+        result = store.issueKey(id, { scopes: flag('--scopes')?.split(','), role: flag('--role'), kind: flag('--kind'), expires_at: flag('--expires') });
+      } else if (action === 'revoke') {
+        result = store.revokeKey(id);
+      } else if (action === 'usage') {
+        result = store.listKeyUsage(id);
+      } else if (action === 'roles') {
+        result = store.loadRoles();
+      } else if (action === 'role-set') {
+        result = store.setRole(id, flag('--scopes')?.split(','));
+      } else {
+        console.error('Use: total-recall auth key list|issue|revoke|usage|roles|role-set');
+        process.exitCode = 1;
+        break;
+      }
+      if (isJson) {
+        console.log(JSON.stringify(result));
+      } else {
+        if (action === 'issue') {
+          console.log(`Key issued: ${result.name} (${result.id})`);
+          console.log(`Token: ${result.token}`);
+          console.log('Store this token now; it will not be displayed again.');
+        } else if (action === 'revoke') {
+          console.log(`Key revoked: ${id}`);
+        } else {
+          console.log(JSON.stringify(result, null, 2));
+        }
+      }
+      break;
     }
     case 'agent': {
       // Sign in an agent CLI that authenticates on its own terminal. The pty lives in
       // scripts/agent-login-pty.py because Node has none and this plugin carries no pty library;
       // this routes the plugin's own surface to it.
+      if (rest.includes('--help') || rest.includes('-h') || rest[0] === 'help') {
+        console.log('Usage: total-recall auth agent list [--json]');
+        console.log('       total-recall auth agent login <agent> [--code <code>] [--code-file <path>] [--url-file <path>] [--json]');
+        break;
+      }
       const { loginAgent, AGENT_LOGIN_PROFILES } = await import('./src/agent-login.mjs');
       const [action = 'list', name] = rest;
       const flag = (n) => { const at = rest.indexOf(n); return at < 0 ? undefined : rest[at + 1]; };
       if (action === 'list') {
-        console.log(JSON.stringify(Object.keys(AGENT_LOGIN_PROFILES).map((id) => ({ id, ...AGENT_LOGIN_PROFILES[id] }))));
+        const list = Object.keys(AGENT_LOGIN_PROFILES).map((id) => ({ id, ...AGENT_LOGIN_PROFILES[id] }));
+        if (isJson) {
+          console.log(JSON.stringify(list));
+        } else {
+          console.log('Supported Agent Profiles:');
+          for (const item of list) {
+            console.log(`  • ${item.id}: ${item.name || item.id}`);
+          }
+        }
+        break;
+      }
+      if (action !== 'login') {
+        console.error('Use: total-recall auth agent list | total-recall auth agent login <agent>');
+        process.exitCode = 1;
         break;
       }
-      if (action !== 'login') throw new Error('Use auth agent list | auth agent login <agent> [--code <code>] [--code-file <path>] [--url-file <path>]');
       const result = await loginAgent({
         agent: name,
         code: flag('--code'),
@@ -371,10 +537,10 @@ export async function run(argv = []) {
       await handleGoogle(rest, isJson);
       break;
     case 'probe':
-      await handleProbe(isJson);
+      await handleProbe(rest, isJson);
       break;
     case 'session':
-      await handleSession(isJson);
+      await handleSession(rest, isJson);
       break;
     case 'secret':
     case 'secrets':

package/scaffold/.agent/skills/total-recall/plugins/auth/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "tr-plugin-auth",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-auth",
-      "version": "1.2.3",
+      "version": "1.2.5",
       "license": "MIT",
       "dependencies": {
         "@simplewebauthn/server": "^13.3.2",
@@ -18,7 +18,7 @@
       },
       "devDependencies": {
         "supertest": "^7.3.1",
-        "total-recall-brain": "3.41.1",
+        "total-recall-brain": "3.41.2",
         "vitest": "^4.1.12"
       }
     },
@@ -3733,9 +3733,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.41.1",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.1.tgz",
-      "integrity": "sha512-QraXzcZpCTMssx1gaz8xjvSKf5KqirAaxzzER/ICBrWvawdNTLUDDMsVEYQUA/7thgwtL1QVIxU4dpfCGZwp+g==",
+      "version": "3.41.2",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.41.2.tgz",
+      "integrity": "sha512-bwJFAFAyvk9ysf+5zhBzMxrKus1Hj1AygUWdBNt+vQbM2sfSEf6701sa30KwfGyU8+cMuN6YNT5Mn63mFZIi/w==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-auth",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "White-label Total Recall auth plugin: Passkey biometric FIDO2 and Google OAuth2 authentication.",
   "type": "module",
   "main": "cli.mjs",

package/scaffold/.agent/skills/total-recall/plugins/auth/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
   "id": "auth",
   "name": "Auth & Secrets",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Hardware WebAuthn biometric FIDO2 passkeys, OAuth session security, and access control.",
   "author": "Total Recall contributors",
   "license": "MIT",
@@ -154,6 +154,13 @@
         "tag": "tr-auth-card",
         "module": "ui/card.js",
         "description": "Gatepass Card Face"
+      },
+      {
+        "id": "panel",
+        "kind": "panel",
+        "tag": "tr-auth-panel",
+        "module": "ui/panel.js",
+        "description": "Gatepass Auth & Credentials Management Panel"
       }
     ]
   },

package/scaffold/.agent/skills/total-recall/plugins/auth/src/cli-secret.mjs

@@ -51,6 +51,7 @@ import {
   enqueueRotationDueTasks,
   getBrowserRotateAssist,
 } from './secrets-rotate.mjs';
+import { findAmbientPasswordExports, removeAmbientPasswordExports, carrierPassword } from './secrets-carriers.mjs';
 import {
   loadRemoteTargets,
   addRemoteTarget,
@@ -200,6 +201,7 @@ function printHelp() {
     generate <key>        Generate a random secret for outside integrations
     get <key> [--json]    Read selected-store value (audited); JSON reports found/value
     list                  List keys + metadata only (no values)
+    prune                 Read-only report: unbound, errored and duplicate keys
     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
@@ -286,6 +288,9 @@ function printHelp() {
     --headscale-url <https-url>
     rotation-due          List keys overdue for rotation
       --enqueue           Create daemon tasks + browser-use prompts for each due key
+    carriers              Find shell profiles and /etc files that export the master
+                           password to every process; --remove-ambient deletes them
+                           once an owner-only carrier holds the same password.
     fingerprint           Identify a credential without printing it: length, type
                            prefix, fingerprint and the store keys holding the same
                            value. --from-clipboard | --stdin; --expect-prefix <p>
@@ -643,6 +648,9 @@ function parseArgs(args) {
       case '--stdin':
         out.stdin = true;
         break;
+      case '--remove-ambient':
+        out.removeAmbient = true;
+        break;
       case '--app':
         out.app = args[++i];
         break;
@@ -1045,6 +1053,18 @@ export default async function secretCli(argv) {
       return;
     }
 
+    if (opts.command === 'prune') {
+      const { pruneCandidates, pruneSummary } = await import('./secrets-prune.mjs');
+      const rows = (await listSecretsMeta(brainDir)).filter((r) => r.set);
+      const candidates = pruneCandidates(rows);
+      const sum = pruneSummary(rows, candidates);
+      console.log(`\n  prune report (read-only): ${sum.candidates} of ${sum.total} keys worth a look`);
+      console.log(`     unbound=${sum.unbound}  error=${sum.errored}  duplicated=${sum.duplicated}\n`);
+      for (const c of candidates) console.log(`  • ${c.key.padEnd(38)} ${c.provider || '-'}  [${c.reasons.join('; ')}]`);
+      console.log('\n  Nothing was deleted. Remove a key with: auth secret delete <key>\n');
+      return;
+    }
+
     if (opts.command === 'shared' || opts.command === 'shared-values' || opts.command === 'duplicates') {
       const shared = await getSharedValueHealth(brainDir);
       console.log(`\n  ${shared.healthy ? '✅' : '❌'} ${shared.message}`);
@@ -1209,6 +1229,34 @@ export default async function secretCli(argv) {
       return;
     }
 
+    if (opts.command === 'carriers') {
+      // Files that make the master password ambient (shell profiles, /etc/environment).
+      // Reports files and line numbers only; --remove-ambient deletes those exports once an
+      // owner-only carrier is verified to hold the same password.
+      if (opts.removeAmbient) {
+        const r = removeAmbientPasswordExports();
+        if (opts.json) console.log(JSON.stringify(r, null, 2));
+        else {
+          console.log(`\n  ${r.removed.length ? '✅ Removed ambient master-password exports' : 'No ambient master-password exports found'}`);
+          for (const row of r.removed) console.log(`     ${row.file}: line ${row.lines.join(', ')}`);
+          console.log('');
+        }
+        return;
+      }
+      const found = findAmbientPasswordExports();
+      const carried = Boolean(carrierPassword());
+      if (opts.json) console.log(JSON.stringify({ ambient: found, owner_only_carrier: carried }, null, 2));
+      else {
+        console.log(`\n  Owner-only carrier holds the master password: ${carried ? 'yes' : 'NO'}`);
+        if (!found.length) console.log('  No ambient exports in shell profiles or /etc');
+        for (const row of found) console.log(`  ❌ ${row.file}: line ${row.lines.join(', ')} exports it to every process started there`);
+        if (found.length) console.log('     Remove with: total-recall auth secret carriers --remove-ambient');
+        console.log('');
+      }
+      if (found.length) process.exitCode = 1;
+      return;
+    }
+
     if (opts.command === 'fingerprint') {
       // Identify a credential without seeing it: which store keys hold the same
       // value, its length and its non-secret type prefix. Lets an operator check

package/scaffold/.agent/skills/total-recall/plugins/auth/src/login-projections.mjs

@@ -0,0 +1,42 @@
+/**
+ * Tool logins derived from stored secrets.
+ *
+ * A secret that reaches a node (see secrets-sync.mjs) is only useful to people and
+ * agents there once the tool that uses it is signed in. This signs `gh` in from
+ * `github_token`, and wires git to it, so a token rotated once lands on every machine
+ * without anyone logging in by hand. Nothing here prints or logs the token.
+ */
+import { execFile } from 'node:child_process';
+
+const TIMEOUT_MS = 20_000;
+
+/** Run a command, optionally feeding stdin; never rejects. */
+export function defaultRun(cmd, args, input) {
+  return new Promise((resolve) => {
+    const child = execFile(cmd, args, { timeout: TIMEOUT_MS, env: { ...process.env, GH_PROMPT_DISABLED: '1', GH_NO_UPDATE_NOTIFIER: '1' } }, (error, stdout, stderr) => {
+      resolve({ ok: !error, code: error?.code ?? 0, stdout: String(stdout || ''), stderr: String(stderr || '') });
+    });
+    child.stdin?.end(input === undefined ? undefined : String(input));
+  });
+}
+
+const firstLine = (text) => String(text || '').split('\n').map((l) => l.trim()).find(Boolean) || 'unknown error';
+
+/**
+ * Sign `gh` in with `token` when it is not already, then point git at it.
+ * @returns {{ status: 'no-token'|'gh-missing'|'current'|'logged-in'|'failed', error?: string }}
+ */
+export async function projectGithubLogin({ token, run = defaultRun } = {}) {
+  const wanted = String(token || '').trim();
+  if (!wanted) return { status: 'no-token' };
+
+  const current = await run('gh', ['auth', 'token']);
+  if (current.code === 'ENOENT') return { status: 'gh-missing' };
+  if (current.ok && current.stdout.trim() === wanted) return { status: 'current' };
+
+  const login = await run('gh', ['auth', 'login', '--hostname', 'github.com', '--git-protocol', 'https', '--with-token'], wanted);
+  if (!login.ok) return { status: 'failed', error: firstLine(login.stderr).replaceAll(wanted, '***') };
+
+  await run('gh', ['auth', 'setup-git', '--hostname', 'github.com']);
+  return { status: 'logged-in' };
+}

package/scaffold/.agent/skills/total-recall/plugins/auth/src/mesh-secrets.mjs

@@ -26,6 +26,24 @@ const FETCH_TIMEOUT_MS = 8_000;
 
 /* ---------- leader side ---------- */
 
+/**
+ * A grant key `repo:<name>` stands for every secret whose `repos` metadata names that
+ * repository, so a machine is given the keys its repositories use rather than a list of
+ * names or `*`. Resolved on each request, so rebinding a key takes effect on the next sync.
+ */
+export function expandRepoGrants(policy, rows) {
+  const byRepo = new Map();
+  for (const row of rows || []) for (const repo of row.repos || []) {
+    if (!byRepo.has(repo)) byRepo.set(repo, []);
+    byRepo.get(repo).push(row.key);
+  }
+  const grants = (policy?.grants || []).map((grant) => ({
+    ...grant,
+    keys: (grant.keys || []).flatMap((key) => (String(key).startsWith('repo:') ? (byRepo.get(String(key).slice(5)) || []) : [key])),
+  }));
+  return { ...policy, grants };
+}
+
 function audit(brainDir, event) {
   try {
     appendAudit(brainDir, event);

package/scaffold/.agent/skills/total-recall/plugins/auth/src/routes/secrets.mjs

@@ -26,7 +26,8 @@ import {
 } from '../secrets-store.mjs';
 import { logger } from '../logger.mjs';
 import { getMeshSyncAuthorization, requireMeshSyncAuth } from '../mesh-auth.mjs';
-import { createMeshIdentityMiddleware, createMeshListHandler, createMeshSecretHandler } from '../mesh-secrets.mjs';
+import { createMeshIdentityMiddleware, createMeshListHandler, createMeshSecretHandler, expandRepoGrants } from '../mesh-secrets.mjs';
+import { loadPolicy } from '../mesh-identity.mjs';
 import { throttledFetch } from '../throttled-fetch.mjs';
 import { listProviders, getProvider } from '../provider-catalog.mjs';
 import {
@@ -90,15 +91,17 @@ router.get('/api/secrets/checksum', requireMeshSyncAuth, async (req, res) => {
 // Mesh-identity secrets: the caller is the enrolled machine, not a shared
 // token. Each node gets only the keys its grant allows; see mesh-secrets.mjs.
 const requireMeshIdentity = createMeshIdentityMiddleware();
+const meshPolicyFor = async (brainDir) => expandRepoGrants(await loadPolicy(brainDir), await listSecretsMeta(brainDir));
 router.get(
   '/api/secrets/mesh',
   requireMeshIdentity,
   createMeshListHandler({
     brainDir: BRAIN_DIR,
+    policyFor: meshPolicyFor,
     keysFor: async () => (await listSecretsMeta(BRAIN_DIR)).map((entry) => entry.key),
   }),
 );
-router.get('/api/secrets/mesh/:key', requireMeshIdentity, createMeshSecretHandler({ brainDir: BRAIN_DIR }));
+router.get('/api/secrets/mesh/:key', requireMeshIdentity, createMeshSecretHandler({ brainDir: BRAIN_DIR, policyFor: meshPolicyFor }));
 
 router.get('/api/secrets/list', requireAuth, requireScope('keys:read', 'config:read'), async (req, res) => {
   try {