aquaman-plugin 0.9.1 → 0.10.0

package/README.md

@@ -1,19 +1,18 @@
 # aquaman-plugin
 
-OpenClaw Gateway plugin for [aquaman](https://github.com/tech4242/aquaman) credential isolation.
-
-## How It Works
+OpenClaw Gateway plugin for [aquaman](https://github.com/tech4242/aquaman) — credential isolation for OpenClaw.
 
 ```
 Agent / OpenClaw Gateway              Aquaman Proxy
 ┌──────────────────────┐              ┌──────────────────────┐
 │                      │              │                      │
-│  ANTHROPIC_BASE_URL  │══ Unix ════>│  Keychain / 1Pass /  │
-│  = aquaman.local     │   Domain    │  Vault / Encrypted   │
-│                      │<═ Socket ═══│                      │
-│  fetch() interceptor │══ (UDS) ══=>│  + Auth injected:    │
-│  redirects channel   │              │    header / url-path │
-│  API traffic         │              │    basic / oauth     │
+│  ANTHROPIC_BASE_URL  │══ Unix ═════>│  Keychain / 1Pass /  │
+│  = aquaman.local     │   Domain     │  Vault / Encrypted   │
+│                      │<═ Socket ════│                      │
+│  fetch() interceptor │══ (UDS) ════>│  + Policy enforced   │
+│  redirects channel   │              │  + Auth injected:    │
+│  API traffic         │              │    header / url-path │
+│                      │              │    basic / oauth     │
 │                      │              │                      │
 │  No credentials.     │  ~/.aquaman/ │                      │
 │  No open ports.      │  proxy.sock  │                      │
@@ -30,24 +29,22 @@ Agent / OpenClaw Gateway              Aquaman Proxy
                                slack.com/api  ...
 ```
 
-This plugin makes the left side work. It routes all LLM and channel API traffic through the aquaman proxy via Unix domain socket so credentials never enter the Gateway process. No TCP port is opened — traffic flows through `~/.aquaman/proxy.sock`.
+This plugin is the left side — it runs inside the Gateway process and routes all LLM and channel API traffic through the aquaman proxy via Unix domain socket. Credentials never enter the agent's address space.
+
+**What it does on load:**
+1. Sets `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` to `http://aquaman.local/<service>` (routed to UDS)
+2. Spawns the proxy daemon via `ProxyManager`
+3. Activates a `globalThis.fetch` interceptor to redirect channel API traffic through the proxy
+4. Registers `/aquaman-status` command and `aquaman_status` tool
 
 ## Quick Start
 
 ```bash
-npm install -g aquaman-proxy              # install the proxy CLI
-aquaman setup                             # stores keys, installs plugin, configures OpenClaw
-openclaw                                  # proxy starts automatically
+npm install -g aquaman-proxy
+aquaman setup                   # stores keys, installs this plugin, applies policy defaults
+openclaw                        # proxy starts automatically
 ```
 
-> `aquaman setup` auto-detects your credential backend. macOS defaults to Keychain,
-> Linux defaults to encrypted file. Override with `--backend`:
-> `aquaman setup --backend keepassxc`
-> Options: `keychain`, `encrypted-file`, `keepassxc`, `1password`, `vault`, `systemd-creds`, `bitwarden`
-
-Existing plaintext credentials are migrated automatically during setup.
-Run again anytime to migrate new credentials: `aquaman migrate openclaw --auto`
-
 Troubleshooting: `aquaman doctor`
 
 ## Config Options
@@ -59,20 +56,20 @@ Troubleshooting: `aquaman doctor`
 | `backend` | `"keychain"` \| `"1password"` \| `"vault"` \| `"encrypted-file"` \| `"keepassxc"` \| `"systemd-creds"` \| `"bitwarden"` | `"keychain"` | Credential store |
 | `services` | `string[]` | `["anthropic", "openai"]` | Services to proxy |
 
-> Advanced settings (audit, vault) go in `~/.aquaman/config.yaml`.
+> Advanced settings (audit, vault, request policies) go in `~/.aquaman/config.yaml`. See [request policy docs](https://github.com/tech4242/aquaman#request-policies).
 
-## Security Audit Note
+## Security Audit
 
-Running `openclaw security audit --deep` will show two expected findings:
+`openclaw security audit --deep` reports two expected findings:
 
-- **`dangerous-exec`** on `proxy-manager.ts` — the plugin spawns the aquaman proxy as a separate process, which is the whole point of credential isolation.
-- **`tools_reachable_permissive_policy`** — advisory that plugin tools are reachable under the default tool policy. This is about your OpenClaw tool profile setting, not about aquaman. Set `"tools": { "profile": "coding" }` in `openclaw.json` if your agents handle untrusted input.
+- **`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 your `plugins.allow` trust list automatically.
+`aquaman setup` adds the plugin to `plugins.allow` automatically.
 
 ## Documentation
 
-See the [main README](https://github.com/tech4242/aquaman#readme) for architecture, Docker deployment, and manual testing.
+See the [main README](https://github.com/tech4242/aquaman#readme) for the full security model, architecture diagrams, and manual testing guides.
 
 ## License
 

package/index.ts

@@ -17,6 +17,16 @@
  */
 
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+// OpenClawPluginDefinition exists in the SDK internals but isn't re-exported from "openclaw/plugin-sdk".
+// Mirror the type here until OpenClaw exposes it from the barrel.
+type OpenClawPluginDefinition = {
+  id?: string;
+  name?: string;
+  description?: string;
+  version?: string;
+  register?: (api: OpenClawPluginApi) => void | Promise<void>;
+};
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
@@ -52,7 +62,7 @@ let proxyManager: ProxyManager | null = null;
 let httpInterceptor: HttpInterceptor | null = null;
 let socketPath: string | null = null;
 let dynamicHostMap: Map<string, string> | null = null;
-const services = ["anthropic", "openai"];
+let configuredServices: string[] = ["anthropic", "openai"];
 
 /** Default socket path */
 function getDefaultSocketPath(): string {
@@ -169,7 +179,7 @@ function activateHttpInterceptor(log: OpenClawPluginApi["logger"]): void {
 /**
  * Set environment variables for SDK clients using sentinel hostname
  */
-function configureEnvironment(log: OpenClawPluginApi["logger"]): void {
+function configureEnvironment(log: OpenClawPluginApi["logger"], services: string[]): void {
   for (const service of services) {
     const serviceUrl = `http://aquaman.local/${service}`;
 
@@ -197,11 +207,12 @@ function configureEnvironment(log: OpenClawPluginApi["logger"]): void {
 /**
  * Register the aquaman_status tool
  */
-function registerStatusTool(api: OpenClawPluginApi): void {
+function registerStatusTool(api: OpenClawPluginApi, services: string[]): void {
   api.registerTool(
     () => {
       return {
         name: "aquaman_status",
+        label: "Aquaman Status",
         description:
           "Check aquaman credential proxy status and configured services",
         parameters: {
@@ -209,8 +220,8 @@ function registerStatusTool(api: OpenClawPluginApi): void {
           properties: {},
           required: [] as string[],
         },
-        async execute() {
-          return {
+        async execute(_toolCallId: string, _params: unknown) {
+          const status = {
             proxyRunning: proxyManager !== null,
             socketPath: socketPath || getDefaultSocketPath(),
             services,
@@ -227,6 +238,10 @@ function registerStatusTool(api: OpenClawPluginApi): void {
               })
             ),
           };
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(status, null, 2) }],
+            details: status,
+          };
         },
       };
     },
@@ -239,7 +254,7 @@ function registerStatusTool(api: OpenClawPluginApi): void {
  * 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: OpenClawPluginApi["logger"]): void {
+function ensureAuthProfiles(log: OpenClawPluginApi["logger"], services: string[]): void {
   const stateDir =
     process.env.OPENCLAW_STATE_DIR ||
     path.join(os.homedir(), ".openclaw");
@@ -280,127 +295,155 @@ function ensureAuthProfiles(log: OpenClawPluginApi["logger"]): void {
 }
 
 /**
- * OpenClaw plugin register function
+ * Aquaman OpenClaw Plugin Definition
  */
-export default function register(api: OpenClawPluginApi): void {
-  api.logger.info("Aquaman plugin loaded");
-
-  // Auto-generate auth-profiles.json if missing
-  ensureAuthProfiles(api.logger);
-
-  // Local proxy mode — requires aquaman CLI
-  if (!isAquamanInstalled()) {
-    api.logger.warn(
-      "aquaman CLI not found. Install with: npm install -g aquaman-proxy"
-    );
-    api.logger.warn(
-      "Then run: aquaman setup"
-    );
-    configureEnvironment(api.logger);
-    return;
-  }
+const plugin: OpenClawPluginDefinition = {
+  id: 'aquaman-plugin',
+  name: 'Aquaman Vault',
+  version: PLUGIN_VERSION,
+  description: 'Credential isolation for OpenClaw — API keys never enter the agent process',
+
+  register(api) {
+    api.logger.info("Aquaman plugin loaded");
+
+    // Read services from plugin config
+    const pluginCfg = api.pluginConfig as { backend?: string; services?: string[] } | undefined;
+    configuredServices = pluginCfg?.services ?? ["anthropic", "openai"];
+
+    // Auto-generate auth-profiles.json if missing
+    ensureAuthProfiles(api.logger, configuredServices);
+
+    // Local proxy mode — requires aquaman CLI
+    if (!isAquamanInstalled()) {
+      api.logger.warn(
+        "aquaman CLI not found. Install with: npm install -g aquaman-proxy"
+      );
+      api.logger.warn(
+        "Then run: aquaman setup"
+      );
+      configureEnvironment(api.logger, configuredServices);
+      return;
+    }
 
-  api.logger.info("aquaman CLI found, will start proxy on gateway start");
+    api.logger.info("aquaman CLI found, will start proxy on gateway start");
 
-  // Configure environment variables immediately (sentinel hostname)
-  configureEnvironment(api.logger);
+    // Configure environment variables immediately (sentinel hostname)
+    configureEnvironment(api.logger, configuredServices);
 
-  // Register lifecycle hooks if available
-  if (api.registerLifecycle) {
-    api.registerLifecycle({
-      async onGatewayStart() {
-        api.logger.info("Starting aquaman proxy...");
+    // Register service for proxy lifecycle management
+    api.registerService({
+      id: 'aquaman-proxy',
+      async start(ctx) {
+        ctx.logger.info("Starting aquaman proxy...");
 
-        const started = await startProxy(api.logger);
+        const started = await startProxy(ctx.logger);
         if (started && socketPath) {
-          api.logger.info("Aquaman proxy started successfully");
+          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) {
-            api.logger.warn(
+            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(api.logger);
+          activateHttpInterceptor(ctx.logger);
         } else {
-          api.logger.error("Failed to start aquaman proxy");
+          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;
-            api.logger.info(
+            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(api.logger);
+            activateHttpInterceptor(ctx.logger);
           } else {
-            api.logger.error(
+            ctx.logger.error(
               "No running proxy found. Check: aquaman doctor"
             );
           }
         }
       },
-
-      async onGatewayStop() {
-        api.logger.info("Stopping aquaman proxy...");
+      async stop(ctx) {
+        ctx.logger.info("Stopping aquaman proxy...");
         stopProxy();
-      },
+      }
     });
-  }
 
-  // Register CLI commands if available
-  if (api.registerCli) {
-    api.registerCli(
-      ({ program }) => {
-        const aquamanCmd = program
-          .command("aquaman")
-          .description("Aquaman credential management");
-
-        aquamanCmd
-          .command("status")
-          .description("Show aquaman proxy status")
-          .action(() => {
-            console.log("\nAquaman Status:");
-            console.log(`  Proxy running: ${proxyManager !== null}`);
-            console.log(`  Socket path: ${socketPath || getDefaultSocketPath()}`);
-            console.log(`  Services: ${services.join(", ")}`);
-            console.log("\nEnvironment Variables:");
-            for (const service of services) {
-              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("add <service> [key]")
-          .description("Add a credential (opens secure prompt)")
-          .action((service: string, key: string = "api_key") => {
-            console.log(`\n  Run in your terminal:\n    aquaman credentials add ${service} ${key}\n`);
-          });
-
-        aquamanCmd
-          .command("list")
-          .description("List stored credentials")
-          .action(() => {
-            console.log(`\n  Run in your terminal:\n    aquaman credentials list\n`);
-          });
-      },
-      { commands: ["aquaman"] }
-    );
+    // 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 = {
+          proxyRunning: proxyManager !== null,
+          socketPath: socketPath || getDefaultSocketPath(),
+          services: configuredServices,
+          httpInterceptorActive: httpInterceptor?.isActive() ?? false,
+        };
+        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 credential management");
+
+          aquamanCmd
+            .command("status")
+            .description("Show aquaman proxy status")
+            .action(() => {
+              console.log("\nAquaman Status:");
+              console.log(`  Proxy running: ${proxyManager !== null}`);
+              console.log(`  Socket path: ${socketPath || getDefaultSocketPath()}`);
+              console.log(`  Services: ${configuredServices.join(", ")}`);
+              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("add <service> [key]")
+            .description("Add a credential (opens secure prompt)")
+            .action((service: string, key: string = "api_key") => {
+              console.log(`\n  Run in your terminal:\n    aquaman credentials add ${service} ${key}\n`);
+            });
+
+          aquamanCmd
+            .command("list")
+            .description("List stored credentials")
+            .action(() => {
+              console.log(`\n  Run in your terminal:\n    aquaman credentials list\n`);
+            });
+        },
+        { commands: ["aquaman"] }
+      );
+    }
+
+    registerStatusTool(api, configuredServices);
+    api.logger.info("Aquaman plugin registered successfully");
   }
+};
 
-  registerStatusTool(api);
-  api.logger.info("Aquaman plugin registered successfully");
-}
+export default plugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aquaman-plugin",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Credential isolation plugin for OpenClaw",
   "type": "module",
   "scripts": {
@@ -26,8 +26,8 @@
     "undici": "^7.0.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.1.0",
-    "aquaman-proxy": "0.9.1"
+    "openclaw": ">=2026.1.11",
+    "aquaman-proxy": "0.10.0"
   },
   "peerDependenciesMeta": {
     "aquaman-proxy": {