aquaman-plugin 0.11.3 → 0.11.5

package/README.md

@@ -51,6 +51,42 @@ The `aquaman` proxy binary is bundled as an npm dependency — no separate downl
 > **Using npm?** `npm install -g aquaman-proxy && aquaman setup` does
 > the same thing. Use this if you prefer managing packages with npm.
 
+## Security model
+
+Aquaman keeps API credentials out of the agent process by running them in a separate proxy process. The agent never sees the secret — only a sentinel base URL that the proxy intercepts, authenticates, and forwards. See the [architecture diagram in the main README](https://github.com/tech4242/aquaman#architecture-decision-isolation-vs-detection).
+
+**Proxy process**
+
+- The plugin spawns the `aquaman` binary from the `aquaman-proxy` npm package, which is declared as an exact-pinned dependency (no semver range) in the plugin's `package.json` and published by the same author. After spawn the plugin checks the running proxy's reported version against the plugin's own and warns if they disagree.
+- The spawn is what triggers the `dangerous-exec` finding in OpenClaw's static scanner — it's intentional and is the whole point of the plugin.
+
+**HTTP interceptor**
+
+- Only services listed in the plugin's `services` config get their traffic redirected to the local proxy. As of v0.11.4, the interceptor filters its known-host map by your `services` list — channels you didn't opt into keep talking to the upstream directly.
+- The interceptor uses a Unix Domain Socket (no TCP, no network exposure).
+
+**Auth profiles**
+
+- On load the plugin writes `~/.openclaw/agents/<id>/agent/auth-profiles.json` with placeholder API-key entries for `anthropic` and `openai` so OpenClaw doesn't reject requests before they reach the proxy. The proxy strips the placeholder and injects the real credential.
+- The plugin never overwrites an existing `auth-profiles.json`. To suppress the generation entirely, set `autoGenerateAuthProfiles: false` in the plugin config (v0.11.4+).
+
+**Audit log**
+
+- Every credential use is recorded in `~/.aquaman/audit/current.jsonl` with a SHA-256 hash chain so tampering is detectable. The log stays local — no telemetry.
+- `aquaman doctor` surfaces audit log issues; `aquaman audit tail` shows recent entries.
+- Operators can constrain which upstream endpoints get proxied (and therefore credentialed) via the `policy` config in `~/.aquaman/config.yaml`. Denied requests return 403 before any credential is injected.
+
+### Scanner findings
+
+`openclaw security audit --deep` reports two expected findings:
+
+- **`dangerous-exec`** on the proxy-manager module — the plugin spawns the proxy as a separate process. This is how credential isolation works.
+- **`tools_reachable_permissive_policy`** — advisory about your tool policy, not an aquaman vulnerability. Set `"tools": { "profile": "coding" }` in `openclaw.json` if your agents handle untrusted input.
+
+ClawHub's ClawScan additionally produces a higher-level review of plugin behavior. The current scan acknowledges credential isolation, proxy spawn, the host map, the auth-profiles generation, and the audit log — see the publisher note on the package page for context on each item.
+
+`aquaman setup` adds the plugin to `plugins.allow` automatically.
+
 ## Available Commands
 
 All commands work via OpenClaw CLI or your terminal:
@@ -77,19 +113,11 @@ Troubleshooting: `openclaw aquaman doctor` or `aquaman doctor`
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | `backend` | `"keychain"` \| `"1password"` \| `"vault"` \| `"encrypted-file"` \| `"keepassxc"` \| `"systemd-creds"` \| `"bitwarden"` | `"keychain"` | Credential store |
-| `services` | `string[]` | `["anthropic", "openai"]` | Services to proxy |
+| `services` | `string[]` | `["anthropic", "openai"]` | Services to proxy (also gates which hostnames the interceptor redirects, v0.11.4+) |
+| `autoGenerateAuthProfiles` | `boolean` | `true` | Auto-generate `auth-profiles.json` with placeholder anthropic/openai entries when the file is absent. Set `false` to manage your own (v0.11.4+) |
 
 > Advanced settings (audit, vault, request policies) go in `~/.aquaman/config.yaml`. See [request policy docs](https://github.com/tech4242/aquaman#request-policies).
 
-## Security Audit
-
-`openclaw security audit --deep` reports two expected findings:
-
-- **`dangerous-exec`** on `proxy-manager.ts` — the plugin spawns the proxy as a separate process. This is how credential isolation works.
-- **`tools_reachable_permissive_policy`** — advisory about your tool policy, not an aquaman vulnerability. Set `"tools": { "profile": "coding" }` in `openclaw.json` if your agents handle untrusted input.
-
-`aquaman setup` adds the plugin to `plugins.allow` automatically.
-
 ## Documentation
 
 See the [main README](https://github.com/tech4242/aquaman#readme) for the full security model, architecture diagrams, request policy config, and manual testing guides.

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Aquaman OpenClaw Plugin
+ *
+ * Credential isolation for OpenClaw.
+ * Credentials never enter the agent process - they're managed by a separate proxy.
+ *
+ * Usage:
+ *   1. Install aquaman: npm install -g aquaman-proxy
+ *   2. Store credentials: aquaman credentials add anthropic api_key
+ *   3. Enable this plugin in openclaw.json
+ *
+ * The plugin will:
+ *   - Start the aquaman proxy on plugin load
+ *   - Set ANTHROPIC_BASE_URL, OPENAI_BASE_URL etc. to route through proxy via UDS
+ *   - The proxy injects credentials into requests
+ *   - Agent never sees the actual API keys
+ */
+interface OpenClawPluginLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+interface OpenClawPluginApi {
+    logger: OpenClawPluginLogger;
+    pluginConfig: unknown;
+    registerService(def: {
+        id: string;
+        start(ctx: {
+            logger: OpenClawPluginLogger;
+        }): void | Promise<void>;
+        stop(ctx: {
+            logger: OpenClawPluginLogger;
+        }): void | Promise<void>;
+    }): void;
+    registerCommand(def: {
+        name: string;
+        description: string;
+        acceptsArgs: boolean;
+        requireAuth: boolean;
+        handler(): Promise<{
+            text: string;
+        }>;
+    }): void;
+    registerCli?(fn: (opts: {
+        program: any;
+    }) => void, opts: {
+        commands: string[];
+    }): void;
+    registerTool(factory: () => {
+        name: string;
+        label: string;
+        description: string;
+        parameters: {
+            type: "object";
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+        execute(toolCallId: string, params: unknown): Promise<{
+            content: {
+                type: "text";
+                text: string;
+            }[];
+            details: unknown;
+        }>;
+    }, opts: {
+        names: string[];
+    }): void;
+}
+type OpenClawPluginDefinition = {
+    id?: string;
+    name?: string;
+    description?: string;
+    version?: string;
+    register?: (api: OpenClawPluginApi) => void | Promise<void>;
+};
+/**
+ * Aquaman OpenClaw Plugin Definition
+ */
+declare const plugin: OpenClawPluginDefinition;
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,UAAU,oBAAoB;IAC5B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,UAAU,iBAAiB;IACzB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,GAAG,EAAE;QACnB,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,CAAC,GAAG,EAAE;YAAE,MAAM,EAAE,oBAAoB,CAAA;SAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACnE,IAAI,CAAC,GAAG,EAAE;YAAE,MAAM,EAAE,oBAAoB,CAAA;SAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACnE,GAAG,IAAI,CAAC;IACT,eAAe,CAAC,GAAG,EAAE;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,OAAO,CAAC;QACrB,WAAW,EAAE,OAAO,CAAC;QACrB,OAAO,IAAI,OAAO,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACtC,GAAG,IAAI,CAAC;IACT,WAAW,CAAC,CACV,EAAE,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,GAAG,CAAA;KAAE,KAAK,IAAI,EACpC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,GAC3B,IAAI,CAAC;IACR,YAAY,CACV,OAAO,EAAE,MAAM;QACb,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE;YAAE,IAAI,EAAE,QAAQ,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC;QACxF,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;YACpD,OAAO,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,IAAI,EAAE,MAAM,CAAA;aAAE,EAAE,CAAC;YAC1C,OAAO,EAAE,OAAO,CAAC;SAClB,CAAC,CAAC;KACJ,EACD,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,GACxB,IAAI,CAAC;CACT;AAED,KAAK,wBAAwB,GAAG;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D,CAAC;AAqSF;;GAEG;AACH,QAAA,MAAM,MAAM,EAAE,wBAqPb,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -0,0 +1,502 @@
+/**
+ * Aquaman OpenClaw Plugin
+ *
+ * Credential isolation for OpenClaw.
+ * Credentials never enter the agent process - they're managed by a separate proxy.
+ *
+ * Usage:
+ *   1. Install aquaman: npm install -g aquaman-proxy
+ *   2. Store credentials: aquaman credentials add anthropic api_key
+ *   3. Enable this plugin in openclaw.json
+ *
+ * The plugin will:
+ *   - Start the aquaman proxy on plugin load
+ *   - Set ANTHROPIC_BASE_URL, OPENAI_BASE_URL etc. to route through proxy via UDS
+ *   - The proxy injects credentials into requests
+ *   - Agent never sees the actual API keys
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { createHttpInterceptor } from "./src/http-interceptor.js";
+import { createProxyManager, findAquamanProxyBinary, execAquamanProxyCli, execAquamanProxyInteractive } from "./src/proxy-manager.js";
+import { loadHostMap, isProxyRunning, getProxyVersion } from "./src/proxy-health.js";
+/**
+ * Find an executable in PATH using filesystem checks (no shell execution).
+ * Avoids execSync("which ...") which triggers dangerous-exec security audit flags.
+ */
+function findInPath(name) {
+    const pathEnv = process.env.PATH || "";
+    const dirs = pathEnv.split(path.delimiter);
+    for (const dir of dirs) {
+        const candidate = path.join(dir, name);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Not found or not executable in this dir
+        }
+    }
+    return null;
+}
+// Read plugin version from package.json
+const pluginPkgPath = path.join(path.dirname(new URL(import.meta.url).pathname), 'package.json');
+let PLUGIN_VERSION = 'unknown';
+try {
+    PLUGIN_VERSION = JSON.parse(fs.readFileSync(pluginPkgPath, 'utf-8')).version;
+}
+catch { /* ok */ }
+let proxyManager = null;
+let httpInterceptor = null;
+let socketPath = null;
+let dynamicHostMap = null;
+let configuredServices = ["anthropic", "openai"];
+/** Default socket path */
+function getDefaultSocketPath() {
+    const configDir = path.join(os.homedir(), '.aquaman');
+    return path.join(configDir, 'proxy.sock');
+}
+/** Fallback host map used when proxy doesn't provide one */
+const FALLBACK_HOST_MAP = new Map([
+    ['api.anthropic.com', 'anthropic'],
+    ['api.openai.com', 'openai'],
+    ['api.github.com', 'github'],
+    ['api.x.ai', 'xai'],
+    ['gateway.ai.cloudflare.com', 'cloudflare-ai'],
+    ['api.mistral.ai', 'mistral'],
+    ['api-inference.huggingface.co', 'huggingface'],
+    ['slack.com', 'slack'],
+    ['*.slack.com', 'slack'],
+    ['discord.com', 'discord'],
+    ['*.discord.com', 'discord'],
+    ['api.telegram.org', 'telegram'],
+    ['matrix.org', 'matrix'],
+    ['*.matrix.org', 'matrix'],
+    ['api.line.me', 'line'],
+    ['api-data.line.me', 'line'],
+    ['api.twitch.tv', 'twitch'],
+    ['id.twitch.tv', 'twitch'],
+    ['api.twilio.com', 'twilio'],
+    ['*.twilio.com', 'twilio'],
+    ['api.telnyx.com', 'telnyx'],
+    ['api.elevenlabs.io', 'elevenlabs'],
+    ['openapi.zalo.me', 'zalo'],
+    ['graph.microsoft.com', 'ms-teams'],
+    ['open.feishu.cn', 'feishu'],
+    ['open.larksuite.com', 'feishu'],
+    ['chat.googleapis.com', 'google-chat'],
+]);
+/**
+ * Check if aquaman proxy binary is available (local node_modules or PATH)
+ */
+function isAquamanProxyInstalled() {
+    return findAquamanProxyBinary() !== null;
+}
+/**
+ * Start the aquaman proxy daemon using ProxyManager
+ */
+async function startProxy(log) {
+    try {
+        const mgr = createProxyManager({
+            config: {},
+            onReady: (info) => {
+                socketPath = info.socketPath;
+                if (info.hostMap && typeof info.hostMap === "object") {
+                    dynamicHostMap = new Map(Object.entries(info.hostMap));
+                }
+            },
+            onError: (err) => log.error(`Proxy error: ${err.message}`),
+            onExit: (code) => {
+                proxyManager = null;
+                log.warn(`Proxy exited with code ${code}`);
+            },
+        });
+        await mgr.start();
+        proxyManager = mgr;
+        socketPath = mgr.getSocketPath();
+        return true;
+    }
+    catch (err) {
+        log.error(`Failed to start proxy: ${err}`);
+        return false;
+    }
+}
+/**
+ * Stop the proxy daemon and deactivate the HTTP interceptor
+ */
+function stopProxy() {
+    if (httpInterceptor) {
+        httpInterceptor.deactivate();
+        httpInterceptor = null;
+    }
+    if (proxyManager) {
+        proxyManager.stop();
+        proxyManager = null;
+    }
+    socketPath = null;
+}
+/**
+ * Activate the HTTP interceptor to redirect channel API traffic through the proxy.
+ * This is what provides credential isolation for channels that don't support base URL overrides.
+ */
+function activateHttpInterceptor(log) {
+    if (!socketPath) {
+        log.error("Cannot activate HTTP interceptor: no socket path");
+        return;
+    }
+    // Use dynamic host map from proxy (includes custom services from services.yaml)
+    // Falls back to builtin map for backward compatibility.
+    const sourceMap = dynamicHostMap || FALLBACK_HOST_MAP;
+    // Restrict interception to services the operator opted into. The interceptor
+    // only redirects traffic to hosts whose service value appears in the plugin's
+    // `services` config. Channels not in `services` keep their normal direct-to-
+    // upstream behavior. (Closes ClawScan ASI02.)
+    const allowed = new Set(configuredServices);
+    const effectiveHostMap = new Map();
+    for (const [host, service] of sourceMap) {
+        if (allowed.has(service))
+            effectiveHostMap.set(host, service);
+    }
+    httpInterceptor = createHttpInterceptor({
+        socketPath,
+        hostMap: effectiveHostMap,
+        log: (msg) => log.info(msg),
+    });
+    httpInterceptor.activate();
+    const skipped = sourceMap.size - effectiveHostMap.size;
+    log.info(`HTTP interceptor active: ${effectiveHostMap.size} host patterns redirected through proxy` +
+        (skipped > 0 ? ` (${skipped} known patterns skipped — not in plugin services config)` : ""));
+}
+/**
+ * Set environment variables for SDK clients using sentinel hostname
+ */
+function configureEnvironment(log, services) {
+    for (const service of services) {
+        const serviceUrl = `http://aquaman.local/${service}`;
+        switch (service) {
+            case "anthropic":
+                process.env["ANTHROPIC_BASE_URL"] = serviceUrl;
+                log.info(`Set ANTHROPIC_BASE_URL=${serviceUrl}`);
+                break;
+            case "openai":
+                process.env["OPENAI_BASE_URL"] = serviceUrl;
+                log.info(`Set OPENAI_BASE_URL=${serviceUrl}`);
+                break;
+            case "github":
+                process.env["GITHUB_API_URL"] = serviceUrl;
+                log.info(`Set GITHUB_API_URL=${serviceUrl}`);
+                break;
+            default:
+                const envKey = `${service.toUpperCase().replace(/-/g, "_")}_BASE_URL`;
+                process.env[envKey] = serviceUrl;
+                log.info(`Set ${envKey}=${serviceUrl}`);
+        }
+    }
+}
+/**
+ * Build status object for both the tool and slash command
+ */
+function getStatus(services) {
+    const cliInstalled = isAquamanProxyInstalled();
+    return {
+        cliInstalled,
+        proxyRunning: proxyManager !== null,
+        socketPath: socketPath || getDefaultSocketPath(),
+        services,
+        httpInterceptorActive: httpInterceptor?.isActive() ?? false,
+        ...(cliInstalled ? {} : { fix: "Run: npm install -g aquaman-proxy && aquaman setup" }),
+        ...(!cliInstalled ? {} : proxyManager === null ? { fix: "Run: aquaman setup (or: openclaw aquaman setup)" } : {}),
+        environmentVariables: Object.fromEntries(services.map((s) => {
+            const key = s === "anthropic"
+                ? "ANTHROPIC_BASE_URL"
+                : s === "openai"
+                    ? "OPENAI_BASE_URL"
+                    : `${s.toUpperCase()}_BASE_URL`;
+            return [key, process.env[key] ?? null];
+        })),
+    };
+}
+/**
+ * Register the aquaman_status tool — always registered (works in degraded mode)
+ */
+function registerStatusTool(api, services) {
+    api.registerTool(() => {
+        return {
+            name: "aquaman_status",
+            label: "Aquaman Status",
+            description: "Check aquaman credential proxy status and configured services",
+            parameters: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+            async execute(_toolCallId, _params) {
+                const status = getStatus(services);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(status, null, 2) }],
+                    details: status,
+                };
+            },
+        };
+    }, { names: ["aquaman_status"] });
+}
+/**
+ * Auto-generate auth-profiles.json with placeholder keys for proxied services.
+ * OpenClaw checks its auth store before making API calls — without a placeholder
+ * key, requests are rejected before they ever reach the proxy.
+ */
+function ensureAuthProfiles(log, services) {
+    const stateDir = process.env.OPENCLAW_STATE_DIR ||
+        path.join(os.homedir(), ".openclaw");
+    const profilesPath = path.join(stateDir, "agents", "main", "agent", "auth-profiles.json");
+    if (fs.existsSync(profilesPath))
+        return;
+    const profiles = {};
+    const order = {};
+    for (const service of services) {
+        if (service === "anthropic" || service === "openai") {
+            profiles[`${service}:default`] = {
+                type: "api_key",
+                provider: service,
+                key: "aquaman-proxy-managed",
+            };
+            order[service] = [`${service}:default`];
+        }
+    }
+    const dir = path.dirname(profilesPath);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(profilesPath, JSON.stringify({ version: 1, profiles, order }, null, 2), { mode: 0o600 });
+    log.info(`Generated auth-profiles.json with placeholder keys at ${profilesPath}`);
+}
+/**
+ * Aquaman OpenClaw Plugin Definition
+ */
+const plugin = {
+    id: 'aquaman-plugin',
+    name: 'Aquaman — API Key Protection',
+    version: PLUGIN_VERSION,
+    description: 'API key protection for OpenClaw — credentials stay in your vault, never in the agent\'s memory',
+    register(api) {
+        api.logger.info("Aquaman plugin loaded");
+        // Read services from plugin config
+        const pluginCfg = api.pluginConfig;
+        configuredServices = pluginCfg?.services ?? ["anthropic", "openai"];
+        // Auto-generate auth-profiles.json if missing. Opt-out via plugin config
+        // `autoGenerateAuthProfiles: false` for operators managing their own auth
+        // profiles. (Closes ClawScan ASI03.)
+        const autoGenerateAuthProfiles = pluginCfg?.autoGenerateAuthProfiles ?? true;
+        if (autoGenerateAuthProfiles) {
+            ensureAuthProfiles(api.logger, configuredServices);
+        }
+        else {
+            api.logger.info("auto-generation of auth-profiles.json disabled by plugin config");
+        }
+        // Check if aquaman proxy binary is available
+        const proxyAvailable = isAquamanProxyInstalled();
+        if (!proxyAvailable) {
+            api.logger.warn("aquaman proxy not found. Install with: npm install -g aquaman-proxy");
+            api.logger.warn("Then run: aquaman setup");
+            // DO NOT call configureEnvironment() — sentinel URLs without a proxy
+            // would break all API calls (connection refused to non-existent socket)
+        }
+        else {
+            api.logger.info("aquaman proxy found, will start proxy on gateway start");
+            // Configure environment variables immediately (sentinel hostname)
+            configureEnvironment(api.logger, configuredServices);
+            // Register service for proxy lifecycle management
+            api.registerService({
+                id: 'aquaman-proxy',
+                async start(ctx) {
+                    ctx.logger.info("Starting aquaman proxy...");
+                    const started = await startProxy(ctx.logger);
+                    if (started && socketPath) {
+                        ctx.logger.info("Aquaman proxy started successfully");
+                        // Check for version mismatch between plugin and proxy
+                        const proxyVersion = await getProxyVersion(socketPath);
+                        if (proxyVersion && proxyVersion !== PLUGIN_VERSION) {
+                            ctx.logger.warn(`Warning: plugin version ${PLUGIN_VERSION} \u2260 proxy version ${proxyVersion}. ` +
+                                `Update both: npm install -g aquaman-proxy && openclaw plugins install aquaman-plugin`);
+                        }
+                        // Activate HTTP interceptor to redirect channel traffic through proxy
+                        activateHttpInterceptor(ctx.logger);
+                    }
+                    else {
+                        ctx.logger.error("Failed to start aquaman proxy");
+                        // Check if another instance is already running
+                        const defaultSock = getDefaultSocketPath();
+                        const alreadyRunning = await isProxyRunning(defaultSock);
+                        if (alreadyRunning) {
+                            socketPath = defaultSock;
+                            ctx.logger.info("Another aquaman instance is already running — using it");
+                            // Load host map from existing proxy
+                            const map = await loadHostMap(defaultSock);
+                            dynamicHostMap = map.size > 0 ? map : FALLBACK_HOST_MAP;
+                            activateHttpInterceptor(ctx.logger);
+                        }
+                        else {
+                            ctx.logger.error("No running proxy found. Check: openclaw aquaman doctor");
+                        }
+                    }
+                },
+                async stop(ctx) {
+                    ctx.logger.info("Stopping aquaman proxy...");
+                    stopProxy();
+                }
+            });
+        }
+        // --- Commands, tools, and CLI are ALWAYS registered (even without proxy) ---
+        // This ensures ClawHub users who installed the plugin but haven't run setup
+        // still get actionable commands and status information.
+        // Register /aquaman-status slash command for humans
+        api.registerCommand({
+            name: 'aquaman-status',
+            description: 'Show aquaman credential proxy status and configured services',
+            acceptsArgs: false,
+            requireAuth: true,
+            async handler() {
+                const status = getStatus(configuredServices);
+                return { text: JSON.stringify(status, null, 2) };
+            }
+        });
+        // Register CLI commands if available
+        if (api.registerCli) {
+            api.registerCli(({ program }) => {
+                const aquamanCmd = program
+                    .command("aquaman")
+                    .description("Aquaman — API key protection");
+                aquamanCmd
+                    .command("status")
+                    .description("Show aquaman proxy status")
+                    .action(() => {
+                    const status = getStatus(configuredServices);
+                    console.log("\nAquaman Status:");
+                    console.log(`  Proxy binary: ${status.cliInstalled ? "found" : "NOT FOUND"}`);
+                    console.log(`  Proxy running: ${status.proxyRunning}`);
+                    console.log(`  Socket path: ${status.socketPath}`);
+                    console.log(`  Services: ${configuredServices.join(", ")}`);
+                    if (status.fix) {
+                        console.log(`\n  Action needed: ${status.fix}`);
+                    }
+                    if (status.proxyRunning) {
+                        console.log("\nEnvironment Variables:");
+                        for (const service of configuredServices) {
+                            const envKey = service === "anthropic"
+                                ? "ANTHROPIC_BASE_URL"
+                                : service === "openai"
+                                    ? "OPENAI_BASE_URL"
+                                    : `${service.toUpperCase()}_BASE_URL`;
+                            console.log(`  ${envKey}=${process.env[envKey] ?? "(not set)"}`);
+                        }
+                    }
+                });
+                aquamanCmd
+                    .command("setup")
+                    .description("Run the setup wizard (stores keys, configures backend)")
+                    .action(async () => {
+                    try {
+                        const exitCode = await execAquamanProxyInteractive(['setup']);
+                        if (exitCode !== 0)
+                            process.exitCode = exitCode;
+                    }
+                    catch {
+                        console.log("\n  Run in your terminal:\n    aquaman setup\n");
+                    }
+                });
+                aquamanCmd
+                    .command("doctor")
+                    .description("Diagnose issues with actionable fixes")
+                    .action(async () => {
+                    try {
+                        const result = await execAquamanProxyCli(['doctor']);
+                        process.stdout.write(result.stdout);
+                        if (result.stderr)
+                            process.stderr.write(result.stderr);
+                        if (result.exitCode !== 0)
+                            process.exitCode = result.exitCode;
+                    }
+                    catch (err) {
+                        console.error(`Failed to run aquaman doctor: ${err.message}`);
+                        process.exitCode = 1;
+                    }
+                });
+                const credsCmd = aquamanCmd
+                    .command("credentials")
+                    .description("Credential management");
+                credsCmd
+                    .command("list")
+                    .description("List stored credentials")
+                    .action(async () => {
+                    try {
+                        const result = await execAquamanProxyCli(['credentials', 'list']);
+                        process.stdout.write(result.stdout);
+                        if (result.stderr)
+                            process.stderr.write(result.stderr);
+                    }
+                    catch (err) {
+                        console.error(`Failed: ${err.message}`);
+                    }
+                });
+                credsCmd
+                    .command("add <service> [key]")
+                    .description("Add a credential (secure prompt)")
+                    .action(async (service, key = "api_key") => {
+                    try {
+                        const exitCode = await execAquamanProxyInteractive(['credentials', 'add', service, key]);
+                        if (exitCode !== 0)
+                            process.exitCode = exitCode;
+                    }
+                    catch {
+                        console.log(`\n  Run in your terminal:\n    aquaman credentials add ${service} ${key}\n`);
+                    }
+                });
+                aquamanCmd
+                    .command("policy-list")
+                    .description("List configured request policy rules")
+                    .action(async () => {
+                    try {
+                        const result = await execAquamanProxyCli(['policy', 'list']);
+                        process.stdout.write(result.stdout);
+                        if (result.stderr)
+                            process.stderr.write(result.stderr);
+                    }
+                    catch (err) {
+                        console.error(`Failed: ${err.message}`);
+                    }
+                });
+                aquamanCmd
+                    .command("audit-tail")
+                    .description("Show recent audit log entries")
+                    .action(async () => {
+                    try {
+                        const result = await execAquamanProxyCli(['audit', 'tail']);
+                        process.stdout.write(result.stdout);
+                        if (result.stderr)
+                            process.stderr.write(result.stderr);
+                    }
+                    catch (err) {
+                        console.error(`Failed: ${err.message}`);
+                    }
+                });
+                aquamanCmd
+                    .command("services-list")
+                    .description("List all configured services")
+                    .action(async () => {
+                    try {
+                        const result = await execAquamanProxyCli(['services', 'list']);
+                        process.stdout.write(result.stdout);
+                        if (result.stderr)
+                            process.stderr.write(result.stderr);
+                    }
+                    catch (err) {
+                        console.error(`Failed: ${err.message}`);
+                    }
+                });
+            }, { commands: ["aquaman"] });
+        }
+        registerStatusTool(api, configuredServices);
+        api.logger.info("Aquaman plugin registered successfully");
+    }
+};
+export default plugin;
+//# sourceMappingURL=index.js.map