aquaman-proxy 0.16.0 → 0.17.1

package/README.md

@@ -99,6 +99,15 @@ Scoped since v0.15.0, because it hands out values rather than injecting them:
 
 `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

@@ -16,7 +16,7 @@ import { loadConfig, getConfigDir, getConfigPath, ensureConfigDir, getDefaultCon
 import { fileURLToPath } from 'node:url';
 import { createCredentialProxy } from '../daemon.js';
 import { createServiceRegistry, ServiceRegistry } from '../service-registry.js';
-import { createOpenClawIntegration, authProfilesAreSqliteOnly, legacyAuthProfilesBlockProviders, pluginInstallNeedsCapabilityConsent } from '../openclaw/integration.js';
+import { createOpenClawIntegration, authProfilesAreSqliteOnly, legacyAuthProfilesBlockProviders, pluginInstallNeedsCapabilityConsent, pluginProvenanceIsReported } from '../openclaw/integration.js';
 import { supportsSecretRefIntegrations, wireSecretRefProviders, secretRefWiringStatus } from '../openclaw/secretref.js';
 import { CHANNEL_ROUTING_SUPPORTED, wireChannelRouting, channelRoutingStatus } from '../openclaw/channel-routing.js';
 import { createHermesIntegration, detectHermes } from '../hermes/integration.js';
@@ -307,7 +307,7 @@ function describeChannelSkip(reason, channel) {
         case 'not-wired':
             return 'routable but not wired yet (re-run: aquaman openclaw setup)';
         case 'unroutable':
-            return 'this OpenClaw exposes no endpoint override for it, so its traffic cannot be routed';
+            return 'this OpenClaw has no per-channel endpoint override in its config for it, so aquaman does not route its traffic';
     }
 }
 const program = new Command();
@@ -419,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) {
@@ -996,10 +1004,27 @@ program
         }
     });
     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`);
     }
@@ -1011,6 +1036,7 @@ program
     // Handle shutdown
     const shutdown = async () => {
         console.log('\nShutting down daemon...');
+        await openshellDriver?.stop();
         await credentialProxy.stop();
         removePidFile();
         try {
@@ -2294,6 +2320,9 @@ openclaw
             catch { /* ok */ }
             const verLabel = pluginVer ? ` v${pluginVer}` : '';
             console.log(`  \u2713 ${aqua('Plugin')} installed${verLabel} (${pluginPath})`);
+            if (pluginProvenanceIsReported(openclawVersion)) {
+                console.log(`  \u2192 ${aqua('Plugin source')} OpenClaw 2026.11+ reports "can't verify where this plugin came from" for it and \`openclaw plugins doctor\` exits 1. The plugin still loads; this is how that OpenClaw classes a plugin installed from ClawHub or copied by setup.`);
+            }
             if (pluginVer && pluginVer !== VERSION) {
                 console.log(`  \u2717 ${aqua('Version mismatch:')} CLI v${VERSION} \u2260 plugin v${pluginVer}`);
                 console.log('    \u2192 Update: openclaw plugins install aquaman-plugin');
@@ -2384,6 +2413,18 @@ openclaw
                     }
                     else if (status.baseUrlProviders.length > 0) {
                         console.log(`  ✓ ${aqua('Model routing')} through the proxy for ${status.baseUrlProviders.join(', ')}`);
+                        // A provider key exported in the gateway's environment wins over
+                        // the configured SecretRef: verified live on OpenClaw 2026.11.3,
+                        // the gateway sent $OPENAI_API_KEY itself to the loopback
+                        // listener, which rejected it (401, no loopback token). The
+                        // real key is then in the agent process, and model calls fail.
+                        // Doctor can only see its own environment, so this is a note.
+                        const exported = status.baseUrlProviders
+                            .map((svc) => `${svc.toUpperCase()}_API_KEY`)
+                            .filter((name) => !!process.env[name]);
+                        if (exported.length > 0) {
+                            console.log(`  \u2192 ${aqua('Environment')} ${exported.join(', ')} ${exported.length > 1 ? 'are' : 'is'} set in this shell. If OpenClaw starts with ${exported.length > 1 ? 'them' : 'it'}, it sends that key instead of the proxy token: the key is in the agent process and the proxy answers 401. Unset ${exported.length > 1 ? 'them' : 'it'} where OpenClaw runs.`);
+                        }
                     }
                 }
                 else if (status.providerConfigured) {
@@ -2433,7 +2474,7 @@ openclaw
                 if (routing.unroutable.length > 0) {
                     // Not a failure: nothing the user can do, and the credentials can
                     // still live in the vault. Stated so nobody assumes coverage.
-                    console.log(`  \u2192 ${aqua('Channel routing')} not available for ${routing.unroutable.join(', ')} on this OpenClaw (no endpoint override)`);
+                    console.log(`  \u2192 ${aqua('Channel routing')} not available for ${routing.unroutable.join(', ')} on this OpenClaw (no config-level endpoint override)`);
                     console.log('    (their tokens can live in the vault, but the proxy is not in their egress path)');
                 }
             }
@@ -2974,6 +3015,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')