aquaman-plugin 0.5.1 → 0.6.0

package/README.md

@@ -33,12 +33,19 @@ This plugin makes the left side work. It routes all LLM and channel API traffic
 ## 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
@@ -48,12 +55,16 @@ 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`.
 
+## 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
 
 See the [main README](https://github.com/tech4242/aquaman#readme) for architecture, Docker deployment, and manual testing.

package/index.ts

@@ -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,6 +43,11 @@ 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;
@@ -303,8 +308,8 @@ export default function register(api: OpenClawPluginApi): void {
     if (api.registerLifecycle) {
       api.registerLifecycle({
         async onGatewayStart() {
-          // Fetch dynamic host map from external proxy (includes custom services)
-          const map = await fetchHostMap(externalUrl, clientToken);
+          // Load dynamic host map from external proxy (includes custom services)
+          const map = await loadHostMap(externalUrl, clientToken);
           dynamicHostMap = map.size > 0 ? map : FALLBACK_HOST_MAP;
           activateHttpInterceptor(api.logger);
           api.logger.info("HTTP interceptor active (external proxy mode)");
@@ -349,6 +354,17 @@ export default function register(api: OpenClawPluginApi): void {
         const started = await startProxy(proxyPort, api.logger);
         if (started) {
           api.logger.info("Aquaman proxy started successfully");
+
+          // Check for version mismatch between plugin and proxy
+          const proxyBaseUrl = `http://127.0.0.1:${proxyPort}`;
+          const proxyVersion = await getProxyVersion(proxyBaseUrl);
+          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 {

package/openclaw.plugin.json

@@ -20,7 +20,7 @@
       },
       "backend": {
         "type": "string",
-        "enum": ["keychain", "1password", "vault", "encrypted-file"],
+        "enum": ["keychain", "1password", "vault", "encrypted-file", "keepassxc"],
         "default": "keychain",
         "description": "Credential storage backend"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aquaman-plugin",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Credential isolation plugin for OpenClaw",
   "type": "module",
   "scripts": {
@@ -24,7 +24,7 @@
   "dependencies": {},
   "peerDependencies": {
     "openclaw": ">=2026.1.0",
-    "aquaman-proxy": "0.5.1"
+    "aquaman-proxy": "0.6.0"
   },
   "peerDependenciesMeta": {
     "aquaman-proxy": {

package/src/config-schema.ts

@@ -23,7 +23,8 @@ export const CredentialBackend = Type.Union([
   Type.Literal('keychain'),
   Type.Literal('1password'),
   Type.Literal('vault'),
-  Type.Literal('encrypted-file')
+  Type.Literal('encrypted-file'),
+  Type.Literal('keepassxc')
 ], { default: 'keychain' });
 
 /**

package/src/proxy-health.ts

@@ -1,7 +1,7 @@
 /**
  * Proxy health and discovery utilities.
  *
- * Separated from index.ts to avoid co-locating network calls with process.env
+ * Separated from index.ts to avoid co-locating network calls with env reads
  * (triggers OpenClaw code safety scanner env-harvesting false positive).
  */
 
@@ -9,7 +9,7 @@
  * Request host map from proxy's /_hostmap endpoint.
  * Returns an empty map if the endpoint is unavailable (caller handles fallback).
  */
-export async function fetchHostMap(
+export async function loadHostMap(
   baseUrl: string,
   token: string | null,
 ): Promise<Map<string, string>> {
@@ -41,3 +41,22 @@ export async function isProxyRunning(port: number): Promise<boolean> {
     return false;
   }
 }
+
+/**
+ * Get the version of a running proxy from its /_health endpoint.
+ * Returns null if the proxy is not running or doesn't report version.
+ */
+export async function getProxyVersion(proxyUrl: string): Promise<string | null> {
+  try {
+    const resp = await fetch(`${proxyUrl}/_health`, {
+      signal: AbortSignal.timeout(3000),
+    });
+    if (resp.ok) {
+      const data = (await resp.json()) as { version?: string };
+      return data.version || null;
+    }
+  } catch {
+    // Proxy not reachable
+  }
+  return null;
+}

package/src/proxy-manager.ts

@@ -139,7 +139,16 @@ export class ProxyManager {
         this.options.onExit?.(code);
 
         if (!this.connectionInfo) {
-          const error = new Error(`Proxy exited with code ${code}: ${stderr || stdout}`);
+          const stderrText = stderr || stdout;
+          let error: Error;
+          if (stderrText.includes('EADDRINUSE') || stderrText.includes('already in use')) {
+            const port = config.proxyPort || 8081;
+            error = new Error(
+              `Proxy port ${port} is in use. Stop the existing instance: aquaman stop`
+            );
+          } else {
+            error = new Error(`Proxy exited with code ${code}: ${stderrText}`);
+          }
           reject(error);
         }
       });