aquaman-plugin 0.5.1 → 0.7.0

package/README.md

@@ -8,15 +8,16 @@ OpenClaw Gateway plugin for [aquaman](https://github.com/tech4242/aquaman) crede
 Agent / OpenClaw Gateway              Aquaman Proxy
 ┌──────────────────────┐              ┌──────────────────────┐
 │                      │              │                      │
-│  ANTHROPIC_BASE_URL  │──request────>│  Keychain / 1Pass /  │
-│  = localhost:8081    │              │  Vault / Encrypted   │
-│                      │<─response────│                      │
-│  fetch() interceptor │──channel────>│  + Auth injected:    │
-│  redirects channel   │   traffic    │    header / url-path │
+│  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     │
 │                      │              │                      │
-│  No credentials.     │              │                      │
-│  Nothing to steal.   │              │                      │
+│  No credentials.     │  ~/.aquaman/ │                      │
+│  No open ports.      │  proxy.sock  │                      │
+│  Nothing to steal.   │  (chmod 600) │                      │
 └──────────────────────┘              └───┬──────────┬───────┘
                                          │          │
                                          │          ▼
@@ -28,17 +29,24 @@ 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 so credentials never enter the Gateway process.
+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`.
 
 ## Quick Start
 
 ```bash
-npm install -g aquaman-proxy              # 1. Install the proxy CLI
-aquaman setup                             # 2. Store keys, install plugin, configure OpenClaw
-aquaman migrate openclaw --auto           # 3. Move existing channel creds to secure store
-openclaw                                  # 4. Proxy starts automatically
+npm install -g aquaman-proxy              # install the proxy CLI
+aquaman setup                             # stores keys, installs plugin, configures OpenClaw
+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`
+
+Existing plaintext credentials are migrated automatically during setup.
+Run again anytime to migrate new credentials: `aquaman migrate openclaw --auto`
+
 Troubleshooting: `aquaman doctor`
 
 ## Config Options
@@ -47,12 +55,14 @@ Troubleshooting: `aquaman doctor`
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
-| `mode` | `"embedded"` \| `"proxy"` | `"embedded"` | Isolation mode |
-| `backend` | `"keychain"` \| `"1password"` \| `"vault"` \| `"encrypted-file"` | `"keychain"` | Credential store |
+| `backend` | `"keychain"` \| `"1password"` \| `"vault"` \| `"encrypted-file"` \| `"keepassxc"` | `"keychain"` | Credential store |
 | `services` | `string[]` | `["anthropic", "openai"]` | Services to proxy |
-| `proxyPort` | `number` | `8081` | Proxy listen port |
 
-> Advanced settings (TLS, audit, vault) go in `~/.aquaman/config.yaml`.
+> Advanced settings (audit, vault) go in `~/.aquaman/config.yaml`.
+
+## Security Audit Note
+
+Running `openclaw security audit --deep` will show a `dangerous-exec` finding for this plugin. That's expected — the plugin spawns the aquaman proxy as a separate process, which is the whole point of credential isolation. `aquaman setup` adds the plugin to your `plugins.allow` trust list automatically.
 
 ## Documentation
 

package/index.ts

@@ -11,7 +11,7 @@
  *
  * The plugin will:
  *   - Start the aquaman proxy on plugin load
- *   - Set ANTHROPIC_BASE_URL, OPENAI_BASE_URL etc. to route through proxy
+ *   - 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
  */
@@ -22,7 +22,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { HttpInterceptor, createHttpInterceptor } from "./src/http-interceptor.js";
 import { createProxyManager, type ProxyManager } from "./src/proxy-manager.js";
-import { fetchHostMap, isProxyRunning } from "./src/proxy-health.js";
+import { loadHostMap, isProxyRunning, getProxyVersion } from "./src/proxy-health.js";
 
 /**
  * Find an executable in PATH using filesystem checks (no shell execution).
@@ -43,14 +43,24 @@ function findInPath(name: string): string | null {
   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: ProxyManager | null = null;
 let httpInterceptor: HttpInterceptor | null = null;
-let clientToken: string | null = null;
+let socketPath: string | null = null;
 let dynamicHostMap: Map<string, string> | null = null;
-const proxyPort = 8081;
 const services = ["anthropic", "openai"];
 
-/** Fallback host map used when proxy doesn't provide one (backward compat) */
+/** Default socket path */
+function getDefaultSocketPath(): string {
+  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<string, string>([
   ['api.anthropic.com', 'anthropic'],
   ['api.openai.com', 'openai'],
@@ -79,21 +89,6 @@ const FALLBACK_HOST_MAP = new Map<string, string>([
   ['chat.googleapis.com', 'google-chat'],
 ]);
 
-/**
- * Get external proxy URL from environment (for Docker two-container mode).
- * When set, the plugin skips spawning a local proxy and routes traffic to the external URL.
- */
-function getExternalProxyUrl(): string | null {
-  return process.env.AQUAMAN_PROXY_URL || null;
-}
-
-/**
- * Get external client token from environment (for Docker two-container mode).
- */
-function getExternalClientToken(): string | null {
-  return process.env.AQUAMAN_CLIENT_TOKEN || null;
-}
-
 /**
  * Check if aquaman CLI is installed (fs-based, no shell execution)
  */
@@ -104,12 +99,12 @@ function isAquamanInstalled(): boolean {
 /**
  * Start the aquaman proxy daemon using ProxyManager
  */
-async function startProxy(port: number, log: OpenClawPluginApi["logger"]): Promise<boolean> {
+async function startProxy(log: OpenClawPluginApi["logger"]): Promise<boolean> {
   try {
     const mgr = createProxyManager({
-      config: { proxyPort: port },
+      config: {},
       onReady: (info) => {
-        clientToken = info.token || null;
+        socketPath = info.socketPath;
         if (info.hostMap && typeof info.hostMap === "object") {
           dynamicHostMap = new Map(Object.entries(info.hostMap));
         }
@@ -122,6 +117,7 @@ async function startProxy(port: number, log: OpenClawPluginApi["logger"]): Promi
     });
     await mgr.start();
     proxyManager = mgr;
+    socketPath = mgr.getSocketPath();
     return true;
   } catch (err) {
     log.error(`Failed to start proxy: ${err}`);
@@ -141,7 +137,7 @@ function stopProxy(): void {
     proxyManager.stop();
     proxyManager = null;
   }
-  clientToken = null;
+  socketPath = null;
 }
 
 /**
@@ -149,16 +145,18 @@ function stopProxy(): void {
  * This is what provides credential isolation for channels that don't support base URL overrides.
  */
 function activateHttpInterceptor(log: OpenClawPluginApi["logger"]): void {
+  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 hostMap = dynamicHostMap || FALLBACK_HOST_MAP;
 
-  const baseUrl = getExternalProxyUrl() || `http://127.0.0.1:${proxyPort}`;
-
   httpInterceptor = createHttpInterceptor({
-    proxyBaseUrl: baseUrl,
+    socketPath,
     hostMap,
-    clientToken: clientToken || undefined,
     log: (msg) => log.info(msg),
   });
 
@@ -167,13 +165,11 @@ function activateHttpInterceptor(log: OpenClawPluginApi["logger"]): void {
 }
 
 /**
- * Set environment variables for SDK clients
+ * Set environment variables for SDK clients using sentinel hostname
  */
 function configureEnvironment(log: OpenClawPluginApi["logger"]): void {
-  const baseUrl = getExternalProxyUrl() || `http://127.0.0.1:${proxyPort}`;
-
   for (const service of services) {
-    const serviceUrl = `${baseUrl}/${service}`;
+    const serviceUrl = `http://aquaman.local/${service}`;
 
     switch (service) {
       case "anthropic":
@@ -197,10 +193,9 @@ function configureEnvironment(log: OpenClawPluginApi["logger"]): void {
 }
 
 /**
- * Register the aquaman_status tool (shared between local and external proxy modes)
+ * Register the aquaman_status tool
  */
 function registerStatusTool(api: OpenClawPluginApi): void {
-  const externalUrl = getExternalProxyUrl();
   api.registerTool(
     () => {
       return {
@@ -214,10 +209,8 @@ function registerStatusTool(api: OpenClawPluginApi): void {
         },
         async execute() {
           return {
-            externalProxy: externalUrl !== null,
-            proxyUrl: externalUrl || `http://127.0.0.1:${proxyPort}`,
-            proxyRunning: externalUrl !== null || proxyManager !== null,
-            proxyPort,
+            proxyRunning: proxyManager !== null,
+            socketPath: socketPath || getDefaultSocketPath(),
             services,
             httpInterceptorActive: httpInterceptor?.isActive() ?? false,
             environmentVariables: Object.fromEntries(
@@ -292,37 +285,6 @@ export default function register(api: OpenClawPluginApi): void {
   // Auto-generate auth-profiles.json if missing
   ensureAuthProfiles(api.logger);
 
-  const externalUrl = getExternalProxyUrl();
-
-  // External proxy mode (Docker two-container architecture)
-  if (externalUrl) {
-    api.logger.info(`External proxy mode: ${externalUrl}`);
-    clientToken = getExternalClientToken();
-    configureEnvironment(api.logger);
-
-    if (api.registerLifecycle) {
-      api.registerLifecycle({
-        async onGatewayStart() {
-          // Fetch dynamic host map from external proxy (includes custom services)
-          const map = await fetchHostMap(externalUrl, clientToken);
-          dynamicHostMap = map.size > 0 ? map : FALLBACK_HOST_MAP;
-          activateHttpInterceptor(api.logger);
-          api.logger.info("HTTP interceptor active (external proxy mode)");
-        },
-        async onGatewayStop() {
-          if (httpInterceptor) {
-            httpInterceptor.deactivate();
-            httpInterceptor = null;
-          }
-        },
-      });
-    }
-
-    registerStatusTool(api);
-    api.logger.info("Aquaman plugin registered successfully");
-    return;
-  }
-
   // Local proxy mode — requires aquaman CLI
   if (!isAquamanInstalled()) {
     api.logger.warn(
@@ -337,34 +299,47 @@ export default function register(api: OpenClawPluginApi): void {
 
   api.logger.info("aquaman CLI found, will start proxy on gateway start");
 
-  // Configure environment variables immediately
+  // Configure environment variables immediately (sentinel hostname)
   configureEnvironment(api.logger);
 
   // Register lifecycle hooks if available
   if (api.registerLifecycle) {
     api.registerLifecycle({
       async onGatewayStart() {
-        api.logger.info(`Starting aquaman proxy on port ${proxyPort}...`);
+        api.logger.info("Starting aquaman proxy...");
 
-        const started = await startProxy(proxyPort, api.logger);
-        if (started) {
+        const started = await startProxy(api.logger);
+        if (started && socketPath) {
           api.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(
+              `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);
         } else {
-          api.logger.error(
-            `Failed to start aquaman proxy on port ${proxyPort}`
-          );
-          // Check if another instance is already running on the port
-          const alreadyRunning = await isProxyRunning(proxyPort);
+          api.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(
-              `Another aquaman instance is already running on port ${proxyPort} — using it`
+              "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);
           } else {
             api.logger.error(
-              `Port ${proxyPort} may be in use. Check with: lsof -i :${proxyPort}`
+              "No running proxy found. Check: aquaman doctor"
             );
           }
         }
@@ -391,7 +366,7 @@ export default function register(api: OpenClawPluginApi): void {
           .action(() => {
             console.log("\nAquaman Status:");
             console.log(`  Proxy running: ${proxyManager !== null}`);
-            console.log(`  Proxy port: ${proxyPort}`);
+            console.log(`  Socket path: ${socketPath || getDefaultSocketPath()}`);
             console.log(`  Services: ${services.join(", ")}`);
             console.log("\nEnvironment Variables:");
             for (const service of services) {

package/openclaw.plugin.json

@@ -12,15 +12,9 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {
-      "mode": {
-        "type": "string",
-        "enum": ["embedded", "proxy"],
-        "default": "embedded",
-        "description": "embedded: credentials in gateway memory, proxy: separate process"
-      },
       "backend": {
         "type": "string",
-        "enum": ["keychain", "1password", "vault", "encrypted-file"],
+        "enum": ["keychain", "1password", "vault", "encrypted-file", "keepassxc"],
         "default": "keychain",
         "description": "Credential storage backend"
       },
@@ -29,11 +23,6 @@
         "items": { "type": "string" },
         "default": ["anthropic", "openai"],
         "description": "Services to proxy credentials for"
-      },
-      "proxyPort": {
-        "type": "number",
-        "default": 8081,
-        "description": "Port for credential proxy (proxy mode only)"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aquaman-plugin",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Credential isolation plugin for OpenClaw",
   "type": "module",
   "scripts": {
@@ -21,10 +21,12 @@
   ],
   "author": "tech4242",
   "license": "MIT",
-  "dependencies": {},
+  "dependencies": {
+    "undici": "^7.0.0"
+  },
   "peerDependencies": {
     "openclaw": ">=2026.1.0",
-    "aquaman-proxy": "0.5.1"
+    "aquaman-proxy": "0.7.0"
   },
   "peerDependenciesMeta": {
     "aquaman-proxy": {