aquaman-plugin 0.6.0 → 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,7 +29,7 @@ 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
 
@@ -54,12 +55,10 @@ Troubleshooting: `aquaman doctor`
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
-| `mode` | `"embedded"` \| `"proxy"` | `"embedded"` | Isolation mode |
 | `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
 

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
  */
@@ -50,12 +50,17 @@ try { PLUGIN_VERSION = JSON.parse(fs.readFileSync(pluginPkgPath, 'utf-8')).versi
 
 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'],
@@ -84,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)
  */
@@ -109,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));
         }
@@ -127,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}`);
@@ -146,7 +137,7 @@ function stopProxy(): void {
     proxyManager.stop();
     proxyManager = null;
   }
-  clientToken = null;
+  socketPath = null;
 }
 
 /**
@@ -154,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),
   });
 
@@ -172,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":
@@ -202,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 {
@@ -219,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(
@@ -297,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() {
-          // 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)");
-        },
-        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(
@@ -342,22 +299,21 @@ 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 proxyBaseUrl = `http://127.0.0.1:${proxyPort}`;
-          const proxyVersion = await getProxyVersion(proxyBaseUrl);
+          const proxyVersion = await getProxyVersion(socketPath);
           if (proxyVersion && proxyVersion !== PLUGIN_VERSION) {
             api.logger.warn(
               `Warning: plugin version ${PLUGIN_VERSION} \u2260 proxy version ${proxyVersion}. ` +
@@ -368,19 +324,22 @@ export default function register(api: OpenClawPluginApi): void {
           // 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"
             );
           }
         }
@@ -407,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,12 +12,6 @@
     "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", "keepassxc"],
@@ -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.6.0",
+  "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.6.0"
+    "aquaman-proxy": "0.7.0"
   },
   "peerDependenciesMeta": {
     "aquaman-proxy": {

package/src/commands.ts

@@ -4,13 +4,11 @@
  * Provides /aquaman commands for users to interact with the plugin.
  */
 
-import type { EmbeddedMode } from './embedded.js';
 import type { ProxyManager } from './proxy-manager.js';
 import type { PluginConfig } from './config-schema.js';
 
 export interface CommandContext {
   config: PluginConfig;
-  embeddedMode?: EmbeddedMode;
   proxyManager?: ProxyManager;
 }
 
@@ -37,43 +35,17 @@ export async function statusCommand(ctx: CommandContext): Promise<CommandResult>
 
   lines.push('aquaman plugin status');
   lines.push('');
-  lines.push(`Mode: ${ctx.config.mode || 'embedded'}`);
   lines.push(`Backend: ${ctx.config.backend || 'keychain'}`);
   lines.push(`Services: ${(ctx.config.services || []).join(', ')}`);
 
-  if (ctx.config.mode === 'proxy') {
-    if (ctx.proxyManager?.isRunning()) {
-      const info = ctx.proxyManager.getConnectionInfo();
-      lines.push('');
-      lines.push('Proxy Status: Running');
-      lines.push(`  URL: ${info?.baseUrl}`);
-      lines.push(`  Port: ${info?.port}`);
-      lines.push(`  Protocol: ${info?.protocol}`);
-    } else {
-      lines.push('');
-      lines.push('Proxy Status: Not running');
-    }
-  } else if (ctx.embeddedMode) {
-    const status = ctx.embeddedMode.getStatus();
+  if (ctx.proxyManager?.isRunning()) {
+    const info = ctx.proxyManager.getConnectionInfo();
     lines.push('');
-    lines.push('Embedded Mode Status:');
-    lines.push(`  Initialized: ${status.initialized}`);
-    lines.push(`  Audit Enabled: ${status.auditEnabled}`);
-  }
-
-  // List credentials (without values)
-  if (ctx.embeddedMode) {
-    try {
-      const creds = await ctx.embeddedMode.listCredentials();
-      lines.push('');
-      lines.push(`Stored Credentials: ${creds.length}`);
-      for (const cred of creds) {
-        lines.push(`  - ${cred.service}/${cred.key}`);
-      }
-    } catch (error) {
-      lines.push('');
-      lines.push('Credentials: (unavailable)');
-    }
+    lines.push('Proxy Status: Running');
+    lines.push(`  Socket: ${info?.socketPath}`);
+  } else {
+    lines.push('');
+    lines.push('Proxy Status: Not running');
   }
 
   return {
@@ -86,19 +58,10 @@ export async function statusCommand(ctx: CommandContext): Promise<CommandResult>
  * /aquaman add <service> - Add a credential (prompts for value)
  */
 export async function addCommand(
-  ctx: CommandContext,
+  _ctx: CommandContext,
   service: string,
   key: string = 'api_key'
 ): Promise<CommandResult> {
-  if (!ctx.embeddedMode) {
-    return {
-      success: false,
-      message: 'Embedded mode not available. Use proxy mode for credential management.'
-    };
-  }
-
-  // Note: In a real OpenClaw plugin, this would trigger a secure input prompt
-  // For now, we return instructions
   return {
     success: true,
     message: `To add a credential for ${service}/${key}:\n\n` +
@@ -111,143 +74,30 @@ export async function addCommand(
 /**
  * /aquaman list - List stored credentials
  */
-export async function listCommand(ctx: CommandContext): Promise<CommandResult> {
-  if (!ctx.embeddedMode) {
-    return {
-      success: false,
-      message: 'Embedded mode not available.'
-    };
-  }
-
-  try {
-    const creds = await ctx.embeddedMode.listCredentials();
-
-    if (creds.length === 0) {
-      return {
-        success: true,
-        message: 'No credentials stored.\n\nUse `aquaman credentials add <service> <key>` to add one.'
-      };
-    }
-
-    const lines = ['Stored credentials:', ''];
-    for (const cred of creds) {
-      lines.push(`  ${cred.service}/${cred.key}`);
-    }
-
-    return {
-      success: true,
-      message: lines.join('\n'),
-      data: creds
-    };
-  } catch (error) {
-    return {
-      success: false,
-      message: `Failed to list credentials: ${error}`
-    };
-  }
+export async function listCommand(_ctx: CommandContext): Promise<CommandResult> {
+  return {
+    success: true,
+    message: 'Run in your terminal:\n  aquaman credentials list'
+  };
 }
 
 /**
  * /aquaman logs - Show recent audit entries
  */
-export async function logsCommand(ctx: CommandContext, count: number = 10): Promise<CommandResult> {
-  if (!ctx.embeddedMode) {
-    return {
-      success: false,
-      message: 'Embedded mode not available.'
-    };
-  }
-
-  try {
-    const entries = await ctx.embeddedMode.getRecentAuditEntries(count);
-
-    if (entries.length === 0) {
-      return {
-        success: true,
-        message: 'No audit entries found.'
-      };
-    }
-
-    const lines = [`Last ${entries.length} audit entries:`, ''];
-    for (const entry of entries) {
-      const time = new Date(entry.timestamp).toISOString();
-      const type = entry.type.toUpperCase().padEnd(16);
-      let details = '';
-
-      if (entry.type === 'credential_access') {
-        details = `${entry.data.service} ${entry.data.operation} ${entry.data.success ? 'OK' : 'FAIL'}`;
-      } else {
-        details = JSON.stringify(entry.data).slice(0, 60);
-      }
-
-      lines.push(`${time} [${type}] ${details}`);
-    }
-
-    return {
-      success: true,
-      message: lines.join('\n'),
-      data: entries
-    };
-  } catch (error) {
-    return {
-      success: false,
-      message: `Failed to get audit logs: ${error}`
-    };
-  }
+export async function logsCommand(_ctx: CommandContext, _count: number = 10): Promise<CommandResult> {
+  return {
+    success: true,
+    message: 'Run in your terminal:\n  aquaman audit tail'
+  };
 }
 
 /**
  * /aquaman verify - Verify audit log integrity
  */
-export async function verifyCommand(ctx: CommandContext): Promise<CommandResult> {
-  if (!ctx.embeddedMode) {
-    return {
-      success: false,
-      message: 'Embedded mode not available.'
-    };
-  }
-
-  try {
-    const result = await ctx.embeddedMode.verifyAuditIntegrity();
-
-    if (result.valid) {
-      return {
-        success: true,
-        message: 'Audit log integrity verified. No tampering detected.'
-      };
-    } else {
-      return {
-        success: false,
-        message: 'Audit log integrity FAILED!\n\n' +
-          'Errors:\n' +
-          result.errors.map(e => `  - ${e}`).join('\n')
-      };
-    }
-  } catch (error) {
-    return {
-      success: false,
-      message: `Failed to verify audit log: ${error}`
-    };
-  }
-}
-
-/**
- * /aquaman mode <embedded|proxy> - Switch mode
- */
-export async function modeCommand(ctx: CommandContext, mode: 'embedded' | 'proxy'): Promise<CommandResult> {
-  if (mode !== 'embedded' && mode !== 'proxy') {
-    return {
-      success: false,
-      message: 'Invalid mode. Use "embedded" or "proxy".'
-    };
-  }
-
-  // Mode switching requires configuration change
+export async function verifyCommand(_ctx: CommandContext): Promise<CommandResult> {
   return {
     success: true,
-    message: `To switch to ${mode} mode, update your openclaw.json:\n\n` +
-      `{\n  "plugins": {\n    "aquaman": {\n      "mode": "${mode}"\n    }\n  }\n}\n\n` +
-      `Then restart OpenClaw.`
+    message: 'Run in your terminal:\n  aquaman audit verify'
   };
 }
 
@@ -272,36 +122,26 @@ export async function executeCommand(
     case 'list':
       return listCommand(ctx);
 
-    case 'logs':
+    case 'logs': {
       const count = args[0] ? parseInt(args[0], 10) : 10;
       return logsCommand(ctx, count);
+    }
 
     case 'verify':
       return verifyCommand(ctx);
 
-    case 'mode':
-      if (args.length < 1) {
-        return { success: false, message: 'Usage: /aquaman mode <embedded|proxy>' };
-      }
-      return modeCommand(ctx, args[0] as 'embedded' | 'proxy');
-
     case 'help':
     default:
       return {
         success: true,
         message: `aquaman plugin commands:
 
-  /aquaman status    - Show plugin status and stored credentials
+  /aquaman status    - Show plugin status
   /aquaman add       - Add a credential (shows instructions)
   /aquaman list      - List stored credentials
-  /aquaman logs [n]  - Show recent audit entries (default: 10)
+  /aquaman logs [n]  - Show recent audit entries
   /aquaman verify    - Verify audit log integrity
-  /aquaman mode      - Switch between embedded and proxy mode
-  /aquaman help      - Show this help message
-
-Mode comparison:
-  embedded: Simpler setup, credentials in Gateway memory
-  proxy:    Stronger isolation, credentials in separate process`
+  /aquaman help      - Show this help message`
       };
   }
 }
@@ -313,7 +153,7 @@ export function getAvailableCommands(ctx: CommandContext): PluginCommand[] {
   return [
     {
       name: 'status',
-      description: 'Show aquaman plugin status and stored credentials',
+      description: 'Show aquaman plugin status',
       execute: async () => {
         const result = await statusCommand(ctx);
         return result.message;
@@ -357,18 +197,6 @@ export function getAvailableCommands(ctx: CommandContext): PluginCommand[] {
         return result.message;
       }
     },
-    {
-      name: 'mode',
-      description: 'Switch between embedded and proxy mode',
-      execute: async (args) => {
-        const mode = args.mode || args._?.[0];
-        if (!mode) {
-          return 'Usage: /aquaman mode <embedded|proxy>';
-        }
-        const result = await modeCommand(ctx, mode as 'embedded' | 'proxy');
-        return result.message;
-      }
-    },
     {
       name: 'help',
       description: 'Show help for aquaman commands',