crbro-memory 1.7.0 → 1.8.1

package/dist/engine/keychain.js

@@ -0,0 +1,329 @@
+"use strict";
+// ─── CRBRO Keychain Broker ───────────────────────────────────────
+//
+// The secret filter says no. It refuses to write a credential into the brain,
+// which is right — but it leaves the user holding a password and nowhere to
+// put it, so it goes back into a config file in plain text and nothing was
+// gained. This module is the other half of that sentence: "no, not in memory —
+// I put it in your keychain and remembered the name."
+//
+// CRBRO stores nothing itself and invents no crypto. Every platform already
+// ships a credential store that is better reviewed than anything written here
+// could be, so the job is to broker access to it and stay out of the way:
+//
+//   macOS    security(1), the login keychain
+//   Linux    secret-tool(1), the Secret Service the desktop already runs
+//   Windows  DPAPI through PowerShell, sealed to the user account
+//
+// Windows is the odd one. Its Credential Manager has no supported way to read
+// a secret back from the command line — cmdkey writes but will not return the
+// value, and reading needs P/Invoke into CredRead. So there the secret is
+// sealed with DPAPI, which is the same crypto the Credential Manager uses,
+// into a file only that Windows account can open. Copied to another machine,
+// lifted from a backup or pushed to a repository, it is unreadable.
+//
+// The store lives OUTSIDE the brain on purpose. Nothing under ~/.crbro is ever
+// consulted here, so no sync, no team space and no `crbro_share` can reach a
+// secret even if some future bug tried to.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeychainUnavailable = void 0;
+exports.detectBackend = detectBackend;
+exports.setSecret = setSecret;
+exports.getSecret = getSecret;
+exports.listSecrets = listSecrets;
+exports.removeSecret = removeSecret;
+exports._resetWindowsStoreForTests = _resetWindowsStoreForTests;
+const node_child_process_1 = require("node:child_process");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+/** Namespace under which every CRBRO secret is filed in the OS store. */
+const SERVICE = 'crbro';
+/**
+ * Windows only: the sealed file, deliberately a sibling of the brain, never
+ * inside it. CRBRO_KEYS_DIR redirects it, which is how the tests avoid writing
+ * into the real store — a test suite that can only run by touching the user's
+ * own credentials is a test suite nobody runs twice.
+ */
+function winPaths() {
+    const dir = process.env['CRBRO_KEYS_DIR'] || (0, node_path_1.join)((0, node_os_1.homedir)(), '.crbro-keys');
+    return { dir, file: (0, node_path_1.join)(dir, 'keys.dpapi') };
+}
+class KeychainUnavailable extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = 'KeychainUnavailable';
+    }
+}
+exports.KeychainUnavailable = KeychainUnavailable;
+/** Runs a command without a shell, so a value with spaces or quotes cannot be reinterpreted. */
+function run(cmd, args, input) {
+    return (0, node_child_process_1.spawnSync)(cmd, args, {
+        encoding: 'utf8',
+        input,
+        timeout: 30_000,
+        windowsHide: true,
+    });
+}
+/**
+ * Which store this machine can actually use — not which one it should have.
+ * Returns null with a reason the caller can show the user, because "no
+ * keychain here" is a normal answer on a headless box, not a failure.
+ */
+function detectBackend() {
+    const os = (0, node_os_1.platform)();
+    if (os === 'darwin') {
+        const probe = run('security', ['-h']);
+        if (probe.error)
+            return { backend: null, reason: 'security(1) not found — unexpected on macOS.' };
+        return { backend: 'macos-keychain' };
+    }
+    if (os === 'win32') {
+        const probe = run('powershell.exe', ['-NoProfile', '-Command', '$PSVersionTable.PSVersion.Major']);
+        if (probe.error || probe.status !== 0) {
+            return { backend: null, reason: 'PowerShell not available, so DPAPI cannot be reached.' };
+        }
+        return { backend: 'windows-dpapi' };
+    }
+    // Linux and the BSDs. secret-tool needs a running Secret Service over D-Bus;
+    // over SSH with no desktop session there is usually none, and that is worth
+    // saying plainly rather than failing with a D-Bus error.
+    const probe = run('secret-tool', ['--help']);
+    if (probe.error) {
+        return { backend: null, reason: 'secret-tool not installed. On Debian/Ubuntu: apt install libsecret-tools.' };
+    }
+    if (!process.env['DBUS_SESSION_BUS_ADDRESS']) {
+        return {
+            backend: null,
+            reason: 'secret-tool is installed but no D-Bus session is running, which is normal over SSH. ' +
+                'Start a session bus or use the CRBRO_SECRET_* environment variables instead.',
+        };
+    }
+    return { backend: 'linux-secret-service' };
+}
+function requireBackend() {
+    const { backend, reason } = detectBackend();
+    if (!backend)
+        throw new KeychainUnavailable(reason ?? 'No credential store available on this machine.');
+    return backend;
+}
+// Every DPAPI call costs a PowerShell start, about a second. A script that
+// needs four credentials would pay four seconds for no reason, so a read is
+// held briefly in memory.
+//
+// Briefly is the whole point. The MCP server is long-lived, and a cache with
+// no expiry would keep every secret in the heap for as long as the editor is
+// open. Thirty seconds covers the burst of reads at the start of a task and
+// nothing beyond it.
+const CACHE_TTL_MS = 30_000;
+let cached = null;
+function invalidateCache() {
+    cached = null;
+}
+function psDpapi(script, input) {
+    const r = run('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script], input);
+    if (r.error || r.status !== 0) {
+        throw new KeychainUnavailable(`DPAPI call failed: ${(r.stderr || '').trim() || 'unknown error'}`);
+    }
+    return r.stdout;
+}
+function winRead() {
+    const { file } = winPaths();
+    if (cached && cached.file === file && Date.now() - cached.at < CACHE_TTL_MS) {
+        return cached.store;
+    }
+    if (!(0, node_fs_1.existsSync)(file))
+        return {};
+    const sealed = (0, node_fs_1.readFileSync)(file, 'utf8').trim();
+    if (!sealed)
+        return {};
+    // ConvertTo-SecureString without -Key is DPAPI at CurrentUser scope: only
+    // this Windows account, on this machine, can turn it back into text.
+    const json = psDpapi('$e = [Console]::In.ReadToEnd().Trim();' +
+        '$s = ConvertTo-SecureString $e;' +
+        '$b = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($s);' +
+        'try { [Runtime.InteropServices.Marshal]::PtrToStringAuto($b) }' +
+        'finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($b) }', sealed);
+    try {
+        const store = JSON.parse(json);
+        cached = { store, at: Date.now(), file };
+        return store;
+    }
+    catch {
+        throw new KeychainUnavailable('The key store exists but could not be read. It was sealed by a different Windows account.');
+    }
+}
+function winWrite(store) {
+    const { dir, file } = winPaths();
+    if (!(0, node_fs_1.existsSync)(dir))
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    const sealed = psDpapi('$j = [Console]::In.ReadToEnd();' +
+        'ConvertTo-SecureString $j -AsPlainText -Force | ConvertFrom-SecureString', JSON.stringify(store)).trim();
+    // Atomic: a crash mid-write leaves the previous store intact rather than a
+    // truncated file that would take every secret with it.
+    const tmp = `${file}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, sealed, { encoding: 'ascii', mode: 0o600 });
+    (0, node_fs_1.renameSync)(tmp, file);
+    cached = { store, at: Date.now(), file };
+}
+// ─── macOS: an index of its own ──────────────────────────────────
+//
+// There is no clean way to list the items of one service. dump-keychain asks
+// for authorisation once per item, and find-generic-password -g returns a
+// single match and prints the password to stderr behind a "password: " prefix
+// — reading that back just to enumerate names would mean handling secrets
+// for no reason. So the names live in an item of their own: one extra write
+// per change, and a listing that tells the truth.
+// security(1) prints the whole value as hex pairs if a single byte of it is
+// not printable, and a UTF-8 accent is two bytes above 0x7F — so "contraseña"
+// comes back as "636f6e747261736ec3b161". Worse, it is ambiguous: the literal
+// secret "deadbeef" is returned exactly like the hex of the bytes DE AD BE EF,
+// and nothing in the output says which one it was.
+//
+// Base64 is printable ASCII from end to end, so the hex path is never taken
+// and any byte sequence survives the round trip unchanged.
+function macEncode(value) {
+    return Buffer.from(value, 'utf8').toString('base64');
+}
+function macDecode(raw) {
+    // -w always ends with a newline of its own (putchar), and only that one is
+    // removed: .trim() would eat spaces that belong to the secret.
+    return Buffer.from(raw.replace(/\n$/, ''), 'base64').toString('utf8');
+}
+const MAC_INDEX = '__crbro_index__';
+function macReadIndex() {
+    const r = run('security', ['find-generic-password', '-s', SERVICE, '-a', MAC_INDEX, '-w']);
+    if (r.status !== 0)
+        return {};
+    try {
+        return JSON.parse(macDecode(r.stdout));
+    }
+    catch {
+        return {};
+    }
+}
+function macWriteIndex(index) {
+    run('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', MAC_INDEX, '-w', macEncode(JSON.stringify(index)), '-T', '/usr/bin/security']);
+}
+// ─── Public surface ──────────────────────────────────────────────
+function setSecret(name, value, description = '') {
+    const backend = requireBackend();
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name)) {
+        throw new Error(`Invalid secret name "${name}". Use SCREAMING_SNAKE_CASE, e.g. WORDPRESS_APP_PASSWORD.`);
+    }
+    if (!value)
+        throw new Error('Refusing to store an empty value.');
+    if (backend === 'windows-dpapi') {
+        const store = winRead();
+        store[name] = { value, description, updated: new Date().toISOString().slice(0, 10) };
+        winWrite(store);
+        return;
+    }
+    if (backend === 'macos-keychain') {
+        // -U updates in place instead of erroring when the item already exists.
+        // -w with the value on argv is visible to `ps` for the life of the call;
+        // security(1) offers no stdin form, so the exposure is unavoidable and
+        // measured in milliseconds on the user's own machine.
+        const r = run('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', name, '-w', macEncode(value), '-j', description, '-T', '/usr/bin/security']);
+        if (r.status !== 0)
+            throw new KeychainUnavailable(`Keychain refused the write: ${(r.stderr || '').trim()}`);
+        const index = macReadIndex();
+        index[name] = { description, updated: new Date().toISOString().slice(0, 10) };
+        macWriteIndex(index);
+        return;
+    }
+    // secret-tool reads the secret from stdin, so it never reaches the process
+    // table. It stays open waiting for EOF, which spawnSync gives it.
+    const r = run('secret-tool', ['store', '--label', `CRBRO ${name}`, 'service', SERVICE, 'account', name, 'description', description], value);
+    if (r.status !== 0)
+        throw new KeychainUnavailable(`secret-tool refused the write: ${(r.stderr || '').trim()}`);
+}
+/**
+ * The value, or null when there is no such secret. An environment variable of
+ * the same name wins, which is what makes CI and one-off overrides work
+ * without touching the store.
+ */
+function getSecret(name) {
+    const fromEnv = process.env[name];
+    if (fromEnv)
+        return fromEnv;
+    const backend = requireBackend();
+    if (backend === 'windows-dpapi') {
+        return winRead()[name]?.value ?? null;
+    }
+    if (backend === 'macos-keychain') {
+        const r = run('security', ['find-generic-password', '-s', SERVICE, '-a', name, '-w']);
+        // security(1) returns the OSStatus itself, truncated to eight bits: 44 is
+        // errSecItemNotFound, 36 is errSecInteractionNotAllowed — a locked
+        // keychain, which is the normal state over SSH and in CI. Reporting that
+        // one as "no such secret" would send someone hunting for a typo.
+        if (r.status === 36) {
+            throw new KeychainUnavailable('The macOS keychain is locked, which is usual over SSH or in CI. Unlock it in a desktop session, ' +
+                'or pass the credential as an environment variable instead.');
+        }
+        if (r.status !== 0)
+            return null;
+        return macDecode(r.stdout);
+    }
+    // Unlike security(1), secret-tool adds no trailing newline when stdout
+    // is a pipe: write_password_stdout only appends one for a tty. Trimming
+    // here would silently eat a newline that was genuinely part of the secret.
+    // Exit 1 with nothing on stderr is how it reports "no such item"; anything
+    // on stderr is a real failure and must not be mistaken for absence.
+    const r = run('secret-tool', ['lookup', 'service', SERVICE, 'account', name]);
+    if (r.status === 0)
+        return r.stdout;
+    if (r.status === 1 && !(r.stderr || '').trim())
+        return null;
+    throw new KeychainUnavailable(`secret-tool failed: ${(r.stderr || '').trim() || `exit ${r.status}`}`);
+}
+/** Names and descriptions only. Values are never returned by design. */
+function listSecrets() {
+    const backend = requireBackend();
+    if (backend === 'windows-dpapi') {
+        return Object.entries(winRead())
+            .map(([name, e]) => ({ name, description: e.description, updated: e.updated }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    if (backend === 'macos-keychain') {
+        return Object.entries(macReadIndex())
+            .map(([name, e]) => ({ name, description: e.description, updated: e.updated }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    const r = run('secret-tool', ['search', '--all', 'service', SERVICE]);
+    if (r.status !== 0)
+        return [];
+    const names = [...r.stdout.matchAll(/^attribute\.account = (.+)$/gm)].map(m => m[1].trim());
+    return [...new Set(names)].sort().map(name => ({ name, description: '', updated: '' }));
+}
+function removeSecret(name) {
+    const backend = requireBackend();
+    if (backend === 'windows-dpapi') {
+        const store = winRead();
+        if (!(name in store))
+            return false;
+        delete store[name];
+        winWrite(store);
+        return true;
+    }
+    if (backend === 'macos-keychain') {
+        const gone = run('security', ['delete-generic-password', '-s', SERVICE, '-a', name]).status === 0;
+        if (gone) {
+            const index = macReadIndex();
+            delete index[name];
+            macWriteIndex(index);
+        }
+        return gone;
+    }
+    return run('secret-tool', ['clear', 'service', SERVICE, 'account', name]).status === 0;
+}
+/** Windows only, and only for tests: forget the sealed file entirely. */
+function _resetWindowsStoreForTests() {
+    invalidateCache();
+    const { file } = winPaths();
+    if ((0, node_fs_1.existsSync)(file))
+        (0, node_fs_1.unlinkSync)(file);
+}
+//# sourceMappingURL=keychain.js.map

package/dist/engine/keychain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keychain.js","sourceRoot":"","sources":["../../src/engine/keychain.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAgBpE,wBAAgB,YAAY,IAAI,SAAS,CAqgCxC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoCpE,wBAAgB,YAAY,IAAI,SAAS,CAkmCxC"}

package/dist/server.js

@@ -1,10 +1,12 @@
 "use strict";
 // ─── CRBRO MCP Server ────────────────────────────────────────────
-// Main server with all 15 tools registered
+// Main server with all 22 tools registered
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createServer = createServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const zod_1 = require("zod");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const brain_js_1 = require("./engine/brain.js");
 const cortex_js_1 = require("./engine/cortex.js");
 const synapses_js_1 = require("./engine/synapses.js");
@@ -14,10 +16,26 @@ const prefrontal_js_1 = require("./engine/prefrontal.js");
 const index_js_1 = require("./search/index.js");
 const maintenance_js_1 = require("./engine/maintenance.js");
 const space_js_1 = require("./sync/space.js");
+const keychain_js_1 = require("./engine/keychain.js");
+/**
+ * The version of CRBRO that is actually running. The manifest carries its own
+ * version, but that one stamps the brain FORMAT and has not moved since 1.0.0
+ * — reporting it as "the version" told every user the same thing regardless of
+ * what they had installed, which is no use to anyone deciding whether to
+ * update.
+ */
+function runningVersion() {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '..', 'package.json'), 'utf8')).version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
 function createServer() {
     const server = new mcp_js_1.McpServer({
         name: 'crbro-memory',
-        version: '1.7.0',
+        version: '1.8.1',
     });
     // ─── Initialize engines ──────────────────────────────────────
     const brain = new brain_js_1.Brain();
@@ -37,9 +55,9 @@ function createServer() {
     // to this machine's own log. Nobody ever writes to anyone else's file, so
     // two people working at once have nothing to collide over.
     (0, space_js_1.attachSync)(brain, cortex);
-    // v1.4.0: CRBRO is fully free — all 15 tools, no license, no network calls.
-    // The former license engine (Firestore-backed freemium) lives in git history
-    // before this version if it is ever needed again.
+    // v1.4.0: CRBRO is fully free — no license, no network calls. The former
+    // license engine (Firestore-backed freemium) lives in git history before
+    // that version if it is ever needed again.
     // ═══════════════════════════════════════════════════════════════
     // TOOL 1: crbro_boot — Boot sequence
     // ═══════════════════════════════════════════════════════════════
@@ -111,7 +129,8 @@ function createServer() {
                 content: [{
                         type: 'text',
                         text: JSON.stringify({
-                            version: manifest.version,
+                            crbro_version: runningVersion(),
+                            brain_format: manifest.version,
                             total_neurons: manifest.total_neurons,
                             total_synapses: manifest.total_synapses,
                             total_sessions: manifest.total_sessions,
@@ -175,7 +194,8 @@ function createServer() {
                             redaction_note: result.redacted.length > 0
                                 ? `Stored, but ${result.redacted.length} credential(s) were replaced with a marker: ` +
                                     `${result.redacted.join(', ')}. The sentence around them was kept. ` +
-                                    'Tell the user, and do not try to store the value again.'
+                                    'Do not try to store the value again. Offer the user crbro_secret instead: ' +
+                                    'it puts the credential in the OS keychain, and then you record only its name here.'
                                 : undefined,
                             total_facts: result.neuron.facts.length,
                             total_decisions: result.neuron.decisions.length,
@@ -701,6 +721,90 @@ function createServer() {
         }
     });
     // ═══════════════════════════════════════════════════════════════
+    // TOOL 22: crbro_secret — Credentials, brokered to the OS keychain
+    // ═══════════════════════════════════════════════════════════════
+    server.tool('crbro_secret', 'Store and read credentials in the operating system own keychain — macOS Keychain, the Linux Secret Service, or DPAPI on Windows. CRBRO keeps no copy and invents no crypto: it brokers access to the store the machine already has, outside the brain, where no sync and no team space can reach it. Use it the moment the user hands you a credential: store it here, then record only the NAME with crbro_learn, never the value. Use get when a task needs one, and do not print the value back to the user unless they asked for that specific secret. Names are SCREAMING_SNAKE_CASE, e.g. WORDPRESS_APP_PASSWORD.', {
+        action: zod_1.z.enum(['get', 'set', 'list', 'remove', 'status'])
+            .describe('get = read one, set = store or update one, list = names only, remove = delete one, status = which keychain this machine offers'),
+        name: zod_1.z.string().optional().describe('Secret name in SCREAMING_SNAKE_CASE'),
+        value: zod_1.z.string().optional().describe('The credential itself. Only for set.'),
+        description: zod_1.z.string().optional().describe('What it is for, e.g. "WordPress example.com - REST API"'),
+    }, async (args) => {
+        try {
+            let payload;
+            if (args.action === 'status') {
+                const { backend, reason } = (0, keychain_js_1.detectBackend)();
+                payload = {
+                    backend,
+                    available: backend !== null,
+                    message: backend
+                        ? `Credentials on this machine are stored in: ${backend}.`
+                        : `No credential store available here. ${reason ?? ''} Credentials can still be passed as environment variables.`,
+                };
+            }
+            else if (args.action === 'list') {
+                const entries = (0, keychain_js_1.listSecrets)();
+                payload = {
+                    count: entries.length,
+                    secrets: entries,
+                    note: 'Names only. Values are never listed, by design.',
+                };
+            }
+            else if (!args.name) {
+                throw new Error(`"name" is required for action "${args.action}".`);
+            }
+            else if (args.action === 'set') {
+                if (!args.value)
+                    throw new Error('"value" is required for action "set".');
+                (0, keychain_js_1.setSecret)(args.name, args.value, args.description ?? '');
+                payload = {
+                    stored: args.name,
+                    message: `Stored in the OS keychain as ${args.name}. Now record the NAME in the brain with crbro_learn — never the value — so a later session knows where to look.`,
+                };
+            }
+            else if (args.action === 'remove') {
+                const gone = (0, keychain_js_1.removeSecret)(args.name);
+                payload = {
+                    removed: gone,
+                    message: gone
+                        ? `${args.name} deleted from the keychain.`
+                        : `No secret named ${args.name} was found.`,
+                };
+            }
+            else {
+                const value = (0, keychain_js_1.getSecret)(args.name);
+                payload = value === null
+                    ? {
+                        found: false,
+                        message: `No secret named ${args.name}. Run action "list" to see what is stored, or ask the user for it and store it with action "set".`,
+                    }
+                    : {
+                        found: true,
+                        name: args.name,
+                        value,
+                        note: 'Use it for the task at hand. Do not repeat it back to the user and do not write it into any file.',
+                    };
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(payload, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: err instanceof keychain_js_1.KeychainUnavailable
+                            ? `No credential store available: ${err.message}`
+                            : `CRBRO secret error: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════
     // TOOL 18: crbro_forget — Remove knowledge for good
     // ═══════════════════════════════════════════════════════════════
     server.tool('crbro_forget', 'Permanently remove facts from a neuron. This is for things that must not exist at all — a credential, personal data, something stored by mistake. For knowledge that merely stopped being true, use crbro_revise instead, which keeps the history. The whole neuron is copied to .quarantine/ before anything is removed, so a mistake can be undone by hand. Always tell the user what you are about to remove and get their agreement first.', {