aquaman-proxy 0.15.0 → 0.17.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,17 @@ 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.
+
+## OpenShell credential driver (v0.17.0+)
+
+`aquaman daemon` can serve NVIDIA OpenShell's external credential driver protocol (`credential_driver.proto`, extension protocol 1.0) on `<configDir>/openshell.sock` (0600). Enable it with `aquaman openshell setup`, which prints the gateway TOML.
+
+- **Reference mode:** `openshell provider create --credential KEY=aquaman://svc/key`. The ref must be declared (`aquaman broker allow`) and exist in the vault; nothing is stored, the ref is the handle, and deleting the provider never deletes the vault item.
+- **Copy mode:** a plain value is written to the vault under the `openshell` service.
+- Every resolve is audited as a `read` (agent `openshell`), without the value. Handles are interpreted by namespace, never by gateway-supplied metadata, so a reference can't bypass the allow-list.
+- `@grpc/grpc-js` and `@grpc/proto-loader` are optional peer dependencies, loaded only when the driver is on. The vendored protocol files live in `proto/openshell/`.
+
 ## 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) {
@@ -366,6 +419,14 @@ program
             }
             lines.push('');
         }
+        const os_ = byName.get('openshell');
+        if (os_) {
+            lines.push(aqua('NVIDIA OpenShell integration'));
+            for (const sub of helper.visibleCommands(os_).filter((s) => s.name() !== 'help')) {
+                lines.push(renderRow(`openshell ${sub.name()}`, sub.description() || ''));
+            }
+            lines.push('');
+        }
         // --- Other ---
         const helpCmd = byName.get('help');
         if (helpCmd) {
@@ -389,7 +450,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 +675,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 +691,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 +849,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,17 +996,35 @@ 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
             });
         }
     });
     await credentialProxy.start();
+    // OpenShell external credential driver (v0.17.0+). Opt-in; a failure here
+    // is reported but never takes the proxy down.
+    let openshellDriver;
+    let openshellDriverError;
+    if (config.openshell?.driver?.enabled) {
+        try {
+            const { startOpenShellDriver } = await import('../openshell/integration.js');
+            openshellDriver = await startOpenShellDriver({ config, store: credentialStore, scope: brokerScope, audit: auditLogger, version: VERSION });
+        }
+        catch (err) {
+            openshellDriverError = err instanceof Error ? err.message : String(err);
+        }
+    }
     // Write PID file
     writePidFile();
     console.log(`Credential proxy: ${socketPath}`);
     console.log(`Credential broker: ${describeBroker(brokerScope)}`);
+    if (openshellDriver)
+        console.log(`OpenShell credential driver: ${openshellDriver.socketPath}`);
+    if (openshellDriverError)
+        console.error(`  ⚠ OpenShell credential driver not started: ${openshellDriverError}`);
     if (brokerScope?.declarationError()) {
         console.error(`  ⚠ ${brokerScope.declarationError()} — refs declared there are refused until it parses`);
     }
@@ -953,6 +1036,7 @@ program
     // Handle shutdown
     const shutdown = async () => {
         console.log('\nShutting down daemon...');
+        await openshellDriver?.stop();
         await credentialProxy.stop();
         removePidFile();
         try {
@@ -1004,7 +1088,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 +1467,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 +1514,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 +1632,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 +2112,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 +2138,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 +2695,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 +2780,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 +2819,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 +2839,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();
@@ -2881,6 +3000,151 @@ policy
         console.log(`  \u2717 DENIED by rule: ${rule.method} ${rule.path} \u2192 ${rule.action}`);
     }
 });
+// ── aquaman openshell …: NVIDIA OpenShell external credential driver (v0.17.0+) ──
+const openshell = program
+    .command('openshell')
+    .description('NVIDIA OpenShell integration: aquaman as the gateway credential driver');
+/** Edit config.yaml `openshell.driver` in the raw file so env overrides are never persisted. */
+function updateOpenShellDriverConfig(enabled, socketPath) {
+    ensureConfigDir();
+    const configPath = getConfigPath();
+    let raw = {};
+    if (fs.existsSync(configPath)) {
+        const parsed = yamlParse(fs.readFileSync(configPath, 'utf-8'));
+        if (parsed && typeof parsed === 'object')
+            raw = parsed;
+    }
+    const current = raw.openshell?.driver && typeof raw.openshell.driver === 'object' ? raw.openshell.driver : {};
+    raw.openshell = { ...(raw.openshell && typeof raw.openshell === 'object' ? raw.openshell : {}), driver: { ...current, enabled } };
+    if (socketPath)
+        raw.openshell.driver.socketPath = socketPath;
+    fs.writeFileSync(configPath, yamlStringify(raw), { encoding: 'utf-8', mode: 0o600 });
+}
+openshell
+    .command('setup')
+    .description('Serve the OpenShell credential driver from `aquaman daemon` and print the gateway config')
+    .option('--socket <path>', 'Absolute Unix socket path for the driver (default: <configDir>/openshell.sock)')
+    .option('--disable', 'Turn the driver off again')
+    .action(async (opts) => {
+    const { grpcAvailable, gatewayConfigSnippet, openshellDriverSocketPath, MAX_SOCKET_PATH } = await import('../openshell/integration.js');
+    const { GRPC_INSTALL_HINT } = await import('../openshell/grpc-server.js');
+    if (opts.disable) {
+        updateOpenShellDriverConfig(false);
+        console.log('OpenShell credential driver disabled. Restart the daemon: aquaman stop && aquaman daemon');
+        console.log('Remove the [openshell.credential_drivers.aquaman] table from your gateway config too.');
+        return;
+    }
+    if (opts.socket && !path.isAbsolute(opts.socket)) {
+        console.error('--socket must be an absolute path (the gateway config needs one).');
+        process.exit(1);
+    }
+    updateOpenShellDriverConfig(true, opts.socket);
+    const socketPath = openshellDriverSocketPath(loadConfig());
+    console.log(`OpenShell credential driver enabled in ${getConfigPath()}`);
+    if (Buffer.byteLength(socketPath) > MAX_SOCKET_PATH) {
+        console.error(`  ⚠ ${socketPath} is longer than the ${MAX_SOCKET_PATH}-byte Unix socket limit. Rerun with --socket <shorter path>.`);
+    }
+    if (!(await grpcAvailable())) {
+        console.log(`\n  The driver needs two optional packages: ${aqua(GRPC_INSTALL_HINT)}`);
+    }
+    console.log('\n1. Add this to your OpenShell gateway config (TOML):\n');
+    console.log(gatewayConfigSnippet(socketPath).split('\n').map((l) => `   ${l}`).join('\n'));
+    console.log('\n2. Restart aquaman, then the gateway:');
+    console.log('   aquaman stop; aquaman daemon');
+    console.log('\n3. Create providers by reference. The secret stays in your vault; nothing is copied:');
+    console.log(`   ${aqua('aquaman broker allow aquaman://anthropic/api_key')}`);
+    console.log(`   openshell provider create --name claude --type anthropic --credential ANTHROPIC_API_KEY=aquaman://anthropic/api_key`);
+    console.log('\n   A plain value (--credential KEY=sk-...) is stored in your vault under the "openshell" service instead.');
+    console.log(`\nCheck everything with: ${aqua('aquaman openshell doctor')}`);
+});
+openshell
+    .command('doctor')
+    .description('Check the OpenShell credential driver: packages, config, socket, declared refs')
+    .option('--gateway-config <path>', 'Also check an OpenShell gateway TOML file points at this driver')
+    .action(async (opts) => {
+    const net = await import('node:net');
+    const { grpcAvailable, openshellDriverSocketPath, MAX_SOCKET_PATH } = await import('../openshell/integration.js');
+    const { GRPC_INSTALL_HINT } = await import('../openshell/grpc-server.js');
+    const config = loadConfig();
+    const socketPath = openshellDriverSocketPath(config);
+    let failed = 0;
+    const pass = (m) => console.log(`  ✓ ${m}`);
+    const fail = (m, fix) => { failed++; console.log(`  ✗ ${m}`); if (fix)
+        console.log(`    → ${fix}`); };
+    console.log(`\n  ${aqua('OpenShell credential driver')}\n`);
+    if (await grpcAvailable())
+        pass('gRPC packages installed (@grpc/grpc-js, @grpc/proto-loader)');
+    else
+        fail('gRPC packages missing', GRPC_INSTALL_HINT);
+    if (config.openshell?.driver?.enabled)
+        pass('Driver enabled in config.yaml');
+    else
+        fail('Driver not enabled', 'aquaman openshell setup');
+    if (Buffer.byteLength(socketPath) <= MAX_SOCKET_PATH)
+        pass(`Socket path ${socketPath}`);
+    else
+        fail(`Socket path over ${MAX_SOCKET_PATH} bytes: ${socketPath}`, 'aquaman openshell setup --socket <shorter absolute path>');
+    let isSocket = false;
+    try {
+        isSocket = fs.statSync(socketPath).isSocket();
+    }
+    catch { /* absent */ }
+    if (!isSocket) {
+        fail('Driver socket not present (daemon not running, or started before setup)', 'aquaman stop; aquaman daemon');
+    }
+    else {
+        const mode = fs.statSync(socketPath).mode & 0o777;
+        if (mode === 0o600)
+            pass('Socket is owner-only (0600)');
+        else
+            fail(`Socket mode is ${mode.toString(8)}, expected 600`, 'aquaman stop; aquaman daemon');
+        const reachable = await new Promise((resolve) => {
+            const c = net.connect(socketPath, () => { c.end(); resolve(true); });
+            c.on('error', () => resolve(false));
+            setTimeout(() => { c.destroy(); resolve(false); }, 2000);
+        });
+        if (reachable)
+            pass('Driver socket accepts connections');
+        else
+            fail('Driver socket does not accept connections', 'aquaman stop; aquaman daemon');
+    }
+    const scope = daemonBrokerScope(config);
+    if (!scope) {
+        fail('Broker disabled (broker.enabled: false): references cannot resolve', 'set broker.enabled: true in config.yaml');
+    }
+    else {
+        const n = scope.declared().length;
+        if (n > 0)
+            pass(`${n} declared ref${n === 1 ? '' : 's'} usable by reference (aquaman broker list)`);
+        else
+            console.log('  • No declared refs yet: reference-mode providers will be refused until you run aquaman broker allow <ref>');
+    }
+    if (opts.gatewayConfig) {
+        let toml = '';
+        try {
+            toml = fs.readFileSync(opts.gatewayConfig, 'utf-8');
+        }
+        catch {
+            fail(`Cannot read ${opts.gatewayConfig}`);
+        }
+        if (toml) {
+            const listsDriver = /credential_drivers\s*=\s*\[[^\]]*"aquaman"[^\]]*\]/.test(toml);
+            const table = /\[openshell\.credential_drivers\.aquaman\]([\s\S]*?)(?=\n\[|$)/.exec(toml)?.[1] ?? '';
+            const uds = /transport\s*=\s*"uds"/.test(table);
+            const sock = /socket_path\s*=\s*"([^"]*)"/.exec(table)?.[1];
+            if (listsDriver && uds && sock === socketPath)
+                pass(`Gateway config ${opts.gatewayConfig} points at this driver`);
+            else
+                fail(`Gateway config ${opts.gatewayConfig} does not point at this driver`, 'paste the snippet from: aquaman openshell setup');
+        }
+    }
+    console.log('');
+    if (failed > 0) {
+        console.log(`  ${failed} check${failed === 1 ? '' : 's'} failed.\n`);
+        process.exit(1);
+    }
+    console.log('  All checks passed.\n');
+});
 // Credential broker scope (v0.15.0+)
 const broker = program
     .command('broker')
@@ -2923,6 +3187,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 +3677,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}`);