aquaman-proxy 0.15.0 → 0.16.0

package/README.md

@@ -78,7 +78,7 @@ The Telegram Bot API has no auth header, so there the token travels in the `/bot
 
 Trade-off: any local process can reach a loopback port, including other users, where the socket's `0600` shuts them out. The token is the gate there, so the listener stays off until `aquaman hermes setup` or `aquaman openclaw setup` turns it on.
 
-**Bring your own vault.** Aquaman has no house vault. It injects credentials from the secret store you already run: Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, or encrypted-file. No new store to adopt, no migration.
+**Bring your own vault.** Aquaman has no house vault. It injects credentials from the secret store you already run: Keychain, 1Password, HashiCorp Vault, Bitwarden, Keeper, KeePassXC, systemd-creds, or encrypted-file. No new store to adopt, no migration.
 
 ## Broker endpoint (v0.12.0+)
 
@@ -97,6 +97,8 @@ Scoped since v0.15.0, because it hands out values rather than injecting them:
 - Over the loopback listener the LLM provider keys are never materialized, declared or not (`404 broker_ref_isolated`). They stay on the proxy path.
 - Declaring a ref is an explicit opt-in to handing that value to processes running as you. Refusals and resolves are both audited.
 
+`aquaman get <aquaman://service/key>` (v0.16.0+) is the command-line form, for tools that take a command printing a secret: Docker Sandboxes (`sbx secret set <svc> --command`), Codex (`model_providers.<id>.auth.command`), Claude Code (`apiKeyHelper`), OpenClaw exec secret providers and Hermes command secret sources. It only talks to the running daemon, so the same scope applies and every read is audited. It refuses to print to an interactive terminal without `--show`, and prints no trailing newline when another program reads it. The value goes to the program that runs the command.
+
 ## Documentation
 
 - **[Root README](https://github.com/tech4242/aquaman#readme)**: value prop, three-path Quick Start, security model

package/dist/cli/index.js

@@ -82,7 +82,9 @@ function storeOptionsFromConfig(config) {
         keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
         bitwardenFolder: config.credentials.bitwardenFolder,
         bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-        bitwardenCollectionId: config.credentials.bitwardenCollectionId
+        bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+        keeperFolderUid: config.credentials.keeperFolderUid,
+        keeperConfigPath: config.credentials.keeperConfigPath
     };
 }
 /**
@@ -151,6 +153,58 @@ function updateBrokerAllowedRefs(refs, mode) {
         console.log('Note: broker.enabled is false in config.yaml, so the broker is off regardless.');
     }
 }
+/**
+ * `POST /broker/resolve` against the running daemon over UDS. Always goes
+ * through the daemon (never the vault directly), so `aquaman get` is
+ * scope-checked and audited exactly like a coding-agent or Hermes resolve.
+ */
+function brokerResolve(socketPath, service, key, timeoutMs) {
+    const body = JSON.stringify({ service, key });
+    return new Promise((resolve) => {
+        const req = http.request({
+            socketPath,
+            path: '/broker/resolve',
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+            timeout: timeoutMs,
+        }, (res) => {
+            let payload = '';
+            res.on('data', (chunk) => { payload += chunk; });
+            res.on('end', () => {
+                let json;
+                try {
+                    json = JSON.parse(payload);
+                }
+                catch {
+                    resolve({ error: `Proxy returned a non-JSON response (HTTP ${res.statusCode})` });
+                    return;
+                }
+                if (res.statusCode === 200 && typeof json.value === 'string') {
+                    resolve({ value: json.value });
+                }
+                else {
+                    resolve({ error: json.error || `Broker error (HTTP ${res.statusCode})`, fix: json.fix, code: json.code });
+                }
+            });
+        });
+        req.on('error', (err) => {
+            if (err.code === 'ENOENT' || err.code === 'ECONNREFUSED') {
+                resolve({ error: `Cannot reach the aquaman proxy at ${socketPath}`, fix: 'Start it with: aquaman daemon', code: 'proxy_unreachable' });
+            }
+            else if (err.code === 'EPERM' || err.code === 'EACCES') {
+                resolve({ error: `Connecting to ${socketPath} was denied (${err.code})`, fix: 'If this runs inside a sandbox, allowlist the socket; otherwise check its owner and 0600 mode', code: 'socket_blocked' });
+            }
+            else {
+                resolve({ error: err.message });
+            }
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            resolve({ error: `Broker request timed out after ${timeoutMs}ms`, fix: 'A vault that prompts (e.g. 1Password biometrics) may need longer: pass --timeout <ms>' });
+        });
+        req.end(body);
+    });
+}
 function describeBroker(scope) {
     if (!scope)
         return 'disabled (broker.enabled: false)';
@@ -312,7 +366,7 @@ program
         }
         lines.push('');
         lines.push(aqua('Vault management'));
-        for (const name of ['credentials', 'audit', 'services', 'policy']) {
+        for (const name of ['credentials', 'get', 'broker', 'audit', 'services', 'policy']) {
             const c = byName.get(name);
             if (c)
                 lines.push(renderCmd(c));
@@ -336,13 +390,12 @@ program
         }
         // --- Coder namespace (shim \u2014 list documented subcommands) ---
         if (byName.has('coder')) {
-            lines.push(aqua('AI coding-agent integration (Claude Code today)'));
+            lines.push(aqua('AI coding-agent integration (Claude Code, Codex)'));
             const coderSubs = [
-                ['coder setup <agent>', 'Install hooks for an agent (claude-code today)'],
+                ['coder setup <agent>', 'Install hooks for an agent (claude-code, codex)'],
                 ['coder doctor', 'Deep diagnostic \u2014 projects, broker, per-project vault'],
                 ['coder status', 'Configured projects + hook wiring + broker activity'],
                 ['coder project list/add/remove', 'Manage ~/.aquaman/projects.yaml'],
-                ['coder get <ref>', 'Resolve an aquaman://service/key reference'],
                 ['coder exec <cmd>', 'Run command with project env injected + output redacted'],
             ];
             for (const [term, desc] of coderSubs) {
@@ -389,7 +442,7 @@ program
 program
     .command('setup')
     .description('Vault-only setup wizard \u2014 backend + credentials (use `aquaman openclaw setup` or `aquaman coder setup` for full bundles)')
-    .option('--backend <backend>', 'Credential backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden)')
+    .option('--backend <backend>', 'Credential backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden, keeper)')
     .option('--no-policy', 'Skip request policy preset configuration')
     .option('--non-interactive', 'Use environment variables instead of prompts (for CI)')
     .action(async (options) => {
@@ -614,7 +667,7 @@ async function runVaultSetup(opts) {
             }
         }
     }
-    const validBackends = ['keychain', 'encrypted-file', 'keepassxc', '1password', 'vault', 'systemd-creds', 'bitwarden'];
+    const validBackends = ['keychain', 'encrypted-file', 'keepassxc', '1password', 'vault', 'systemd-creds', 'bitwarden', 'keeper'];
     if (!validBackends.includes(backend)) {
         console.error(`  Invalid backend: ${backend}. Valid: ${validBackends.join(', ')}`);
         process.exit(1);
@@ -630,6 +683,9 @@ async function runVaultSetup(opts) {
         config = loadConfig();
     }
     config.credentials.backend = backend;
+    if (backend === 'keeper' && process.env['AQUAMAN_KEEPER_FOLDER_UID']) {
+        config.credentials.keeperFolderUid = process.env['AQUAMAN_KEEPER_FOLDER_UID'];
+    }
     fs.writeFileSync(configPath, yamlStringify(config), { encoding: 'utf-8', mode: 0o600 });
     const auditDir = path.join(configDir, 'audit');
     fs.mkdirSync(auditDir, { recursive: true, mode: 0o700 });
@@ -785,7 +841,8 @@ openclaw
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
-                operation: 'use',
+                // A broker resolve hands the value out; everything else injects it.
+                operation: info.method === 'BROKER' ? 'read' : 'use',
                 success: !info.error,
                 error: info.error
             });
@@ -931,7 +988,8 @@ program
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
-                operation: 'use',
+                // A broker resolve hands the value out; everything else injects it.
+                operation: info.method === 'BROKER' ? 'read' : 'use',
                 success: !info.error,
                 error: info.error
             });
@@ -1004,7 +1062,8 @@ openclaw
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
-                operation: 'use',
+                // A broker resolve hands the value out; everything else injects it.
+                operation: info.method === 'BROKER' ? 'read' : 'use',
                 success: !info.error,
                 error: info.error
             });
@@ -1382,7 +1441,7 @@ program
 openclaw
     .command('setup')
     .description('Full setup for OpenClaw — vault + plugin + auth profiles + (optional) auto-migrate')
-    .option('--backend <backend>', 'Credential backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden)')
+    .option('--backend <backend>', 'Credential backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden, keeper)')
     .option('--no-openclaw', 'Skip OpenClaw plugin installation step (run vault setup only)')
     .option('--no-policy', 'Skip request policy preset configuration')
     .option('--non-interactive', 'Use environment variables instead of prompts (for CI)')
@@ -1429,7 +1488,7 @@ openclaw
         }
     }
     // Validate backend
-    const validBackends = ['keychain', 'encrypted-file', 'keepassxc', '1password', 'vault', 'systemd-creds', 'bitwarden'];
+    const validBackends = ['keychain', 'encrypted-file', 'keepassxc', '1password', 'vault', 'systemd-creds', 'bitwarden', 'keeper'];
     if (!validBackends.includes(backend)) {
         console.error(`  Invalid backend: ${backend}`);
         console.error(`  Valid options: ${validBackends.join(', ')}`);
@@ -1547,10 +1606,30 @@ openclaw
             process.exit(1);
         }
     }
+    else if (backend === 'keeper') {
+        const { KeeperStore } = await import('../core/credentials/backends/keeper.js');
+        if (!KeeperStore.isAvailable()) {
+            console.error('  Keeper Commander (keeper) not found.');
+            console.error('  Install: pip install keepercommander');
+            console.error('  Then, once: keeper shell -> login -> this-device register -> this-device persistent-login on');
+            process.exit(1);
+        }
+        if (!process.env['AQUAMAN_KEEPER_FOLDER_UID']) {
+            console.error('  Keeper backend needs the folder that will hold aquaman records.');
+            console.error('  Create one in Keeper, then: export AQUAMAN_KEEPER_FOLDER_UID=<folder UID>');
+            console.error('  (find the UID with: keeper get "<folder name>" --format json)');
+            process.exit(1);
+        }
+    }
     // 2. Run init internally (create dirs, config)
     ensureConfigDir();
     const config = getDefaultConfig();
     config.credentials.backend = backend;
+    if (backend === 'keeper') {
+        config.credentials.keeperFolderUid = process.env['AQUAMAN_KEEPER_FOLDER_UID'];
+        if (process.env['AQUAMAN_KEEPER_CONFIG'])
+            config.credentials.keeperConfigPath = process.env['AQUAMAN_KEEPER_CONFIG'];
+    }
     fs.writeFileSync(configPath, yamlStringify(config), { encoding: 'utf-8', mode: 0o600 });
     // Create audit directory
     const auditDir = path.join(configDir, 'audit');
@@ -2007,6 +2086,12 @@ openclaw
                 throw new Error('systemd-creds backend requires systemd >= 256 with --user support');
             }
         }
+        if (config.credentials.backend === 'keeper') {
+            const { KeeperStore } = await import('../core/credentials/backends/keeper.js');
+            if (!KeeperStore.isAvailable()) {
+                throw new Error('Keeper Commander (keeper) not found. Install: pip install keepercommander');
+            }
+        }
         if (config.credentials.backend === 'bitwarden') {
             const { BitwardenStore } = await import('../core/credentials/backends/bitwarden.js');
             if (!BitwardenStore.isAvailable()) {
@@ -2027,7 +2112,9 @@ openclaw
             keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
             bitwardenFolder: config.credentials.bitwardenFolder,
             bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-            bitwardenCollectionId: config.credentials.bitwardenCollectionId
+            bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+            keeperFolderUid: config.credentials.keeperFolderUid,
+            keeperConfigPath: config.credentials.keeperConfigPath
         });
         // 3. Count credentials
         const creds = await store.list();
@@ -2582,7 +2669,9 @@ credentials
             keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
             bitwardenFolder: config.credentials.bitwardenFolder,
             bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-            bitwardenCollectionId: config.credentials.bitwardenCollectionId
+            bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+            keeperFolderUid: config.credentials.keeperFolderUid,
+            keeperConfigPath: config.credentials.keeperConfigPath
         });
     }
     catch (error) {
@@ -2665,7 +2754,9 @@ credentials
             keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
             bitwardenFolder: config.credentials.bitwardenFolder,
             bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-            bitwardenCollectionId: config.credentials.bitwardenCollectionId
+            bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+            keeperFolderUid: config.credentials.keeperFolderUid,
+            keeperConfigPath: config.credentials.keeperConfigPath
         });
     }
     catch {
@@ -2702,7 +2793,9 @@ credentials
             keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
             bitwardenFolder: config.credentials.bitwardenFolder,
             bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-            bitwardenCollectionId: config.credentials.bitwardenCollectionId
+            bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+            keeperFolderUid: config.credentials.keeperFolderUid,
+            keeperConfigPath: config.credentials.keeperConfigPath
         });
     }
     catch {
@@ -2720,7 +2813,7 @@ credentials
 credentials
     .command('guide')
     .description('Show setup commands for seeding credentials based on your backend')
-    .option('--backend <backend>', 'Override backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden)')
+    .option('--backend <backend>', 'Override backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden, keeper)')
     .option('--service <name>', 'Show commands for a single service only')
     .action(async (options) => {
     const config = loadConfig();
@@ -2923,6 +3016,63 @@ broker
     .action((refs) => {
     updateBrokerAllowedRefs(refs, 'revoke');
 });
+// v0.16.0: fills the "run a command, read the secret from stdout" slot every
+// host now has (sbx secret set --command, Codex model_providers.*.auth.command,
+// Claude Code apiKeyHelper, OpenClaw exec providers, Hermes command sources).
+// This materializes the value into the CALLING process, so it is not process
+// isolation; it is scope-checked and audited because it goes through the daemon.
+program
+    .command('get')
+    .description('Print a declared credential to stdout, via the running daemon (for host credential-helper commands)')
+    .argument('<ref>', 'aquaman://service/key, declared with `aquaman broker allow` or in projects.yaml')
+    .option('--show', 'Allow printing to an interactive terminal')
+    .option('--timeout <ms>', 'How long to wait for the daemon (vaults that prompt may need longer)', '15000')
+    .addHelpText('after', `
+Examples:
+  sbx secret set github --command "$(command -v node) $(command -v aquaman) get aquaman://github/token"
+  Codex config.toml:  [model_providers.openai.auth]  command = "aquaman"  args = ["get", "aquaman://openai/api_key"]
+  Claude Code:        "apiKeyHelper": "aquaman get aquaman://anthropic/api_key"
+
+The value lands in whichever process runs this command. Every read is checked
+against the broker scope and written to the audit log.`)
+    .action(async (ref, opts) => {
+    const parsed = parseAquamanRef(ref);
+    if (!parsed) {
+        console.error(`Invalid ref: ${ref}`);
+        console.error('Refs look like aquaman://<service>/<key>, e.g. aquaman://github/token');
+        process.exit(1);
+    }
+    const timeoutMs = Number(opts.timeout);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1) {
+        console.error(`Invalid --timeout: ${opts.timeout} (milliseconds, a positive integer)`);
+        process.exit(1);
+    }
+    // Refuse before resolving, so an accidental run at a prompt neither
+    // prints the secret into scrollback nor spends an audited read.
+    if (process.stdout.isTTY && !opts.show) {
+        console.error('Refusing to print a credential to a terminal.');
+        console.error('This command is meant to be run by another program. To print it anyway, pass --show.');
+        process.exit(1);
+    }
+    const result = await brokerResolve(path.join(getConfigDir(), 'proxy.sock'), parsed.service, parsed.key, timeoutMs);
+    if ('value' in result) {
+        // No trailing newline when piped: credential-helper consumers differ on
+        // whether they trim, and a stray "\n" in an auth header breaks requests.
+        process.stdout.write(process.stdout.isTTY ? `${result.value}\n` : result.value);
+        return;
+    }
+    console.error(`Error: ${result.error}`);
+    if (result.code === 'broker_ref_not_declared') {
+        console.error(`Fix: aquaman broker allow ${ref}`);
+    }
+    else if (result.code === 'broker_disabled') {
+        console.error('Fix: the proxy on this socket does not serve the broker. If the OpenClaw plugin started it, run `aquaman daemon` instead (the last proxy started owns the socket).');
+    }
+    else if (result.fix) {
+        console.error(`Fix: ${result.fix}`);
+    }
+    process.exit(1);
+});
 // Migration commands
 openclaw
     .command('migrate')
@@ -3356,7 +3506,9 @@ openclaw
             keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
             bitwardenFolder: config.credentials.bitwardenFolder,
             bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-            bitwardenCollectionId: config.credentials.bitwardenCollectionId
+            bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+            keeperFolderUid: config.credentials.keeperFolderUid,
+            keeperConfigPath: config.credentials.keeperConfigPath
         });
         const creds = await store.list();
         console.log(`\nStored credentials: ${creds.length}`);