aquaman-proxy 0.9.2 → 0.10.0

package/README.md

@@ -1,19 +1,18 @@
 # aquaman-proxy
 
-Credential isolation proxy and CLI for [aquaman](https://github.com/tech4242/aquaman).
-
-## How It Works
+The proxy daemon and CLI 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,33 +29,22 @@ Agent / OpenClaw Gateway              Aquaman Proxy
                                slack.com/api  ...
 ```
 
-This package is the right side. A reverse proxy that listens on a Unix domain socket (`~/.aquaman/proxy.sock`) and injects credentials from secure backends. No TCP port, no network exposure. 25 builtin services, six auth modes.
+This package is the right side — a reverse proxy on a Unix domain socket that stores credentials in secure backends, enforces request policies, injects auth headers, and logs every access. The agent never sees a key.
 
 ## Quick Start
 
-With OpenClaw:
-
 ```bash
-npm install -g aquaman-proxy              # install the proxy CLI
-aquaman setup                             # stores keys, installs plugin, configures OpenClaw
-openclaw                                  # proxy starts automatically via plugin
+npm install -g aquaman-proxy
+aquaman setup                   # stores keys, installs OpenClaw plugin, applies policy defaults
+openclaw                        # proxy starts automatically via plugin
 ```
 
-> `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`
-
-Standalone:
+Standalone (without OpenClaw):
 
 ```bash
-npm install -g aquaman-proxy
 aquaman init
 aquaman credentials add anthropic api_key
-aquaman daemon                               # listens on ~/.aquaman/proxy.sock
+aquaman daemon                  # listens on ~/.aquaman/proxy.sock
 ```
 
 Troubleshooting: `aquaman doctor`
@@ -65,7 +53,7 @@ Troubleshooting: `aquaman doctor`
 
 | Command | Description |
 |---------|-------------|
-| `aquaman setup` | Guided onboarding (stores keys, installs plugin) |
+| `aquaman setup` | Guided onboarding (stores keys, installs plugin, applies policy defaults) |
 | `aquaman doctor` | Diagnose issues with actionable fixes |
 | `aquaman credentials add <svc> <key>` | Store a credential |
 | `aquaman credentials list` | List stored credentials |
@@ -74,6 +62,8 @@ Troubleshooting: `aquaman doctor`
 | `aquaman start` | Start proxy + launch OpenClaw |
 | `aquaman stop` | Stop running proxy |
 | `aquaman status` | Show config and proxy status |
+| `aquaman policy list` | List configured policy rules |
+| `aquaman policy test <svc> <method> <path>` | Dry-run a request against policy rules |
 | `aquaman audit tail` | Recent audit entries |
 | `aquaman audit verify` | Verify hash chain integrity |
 
@@ -88,9 +78,20 @@ Troubleshooting: `aquaman doctor`
 | **Channels (OAuth)** | MS Teams, Feishu, Google Chat |
 | **At-rest only** | Nostr, Tlon |
 
+## Security
+
+The proxy enforces four layers of protection:
+
+- **Process isolation** — credentials in a separate address space, connected via UDS (`chmod 600`)
+- **Service allowlisting** — `proxiedServices` controls which APIs the agent can reach
+- **Request policies** — method + path rules per service, checked *before* credential injection ([details](https://github.com/tech4242/aquaman#request-policies))
+- **Audit trail** — SHA-256 hash-chained logs of every credential use
+
+7 credential backends: Keychain, 1Password, Vault, Bitwarden, KeePassXC, systemd-creds, encrypted-file.
+
 ## Documentation
 
-See the [main README](https://github.com/tech4242/aquaman#readme) for architecture, credential backends, Docker deployment, and configuration.
+See the [main README](https://github.com/tech4242/aquaman#readme) for the full security model, request policy config, Docker deployment, and architecture diagrams.
 
 ## License
 

package/dist/cli/index.js

@@ -17,6 +17,7 @@ import { fileURLToPath } from 'node:url';
 import { createCredentialProxy } from '../daemon.js';
 import { createServiceRegistry, ServiceRegistry } from '../service-registry.js';
 import { createOpenClawIntegration } from '../openclaw/integration.js';
+import { loadPolicyFromConfig, validatePolicyConfig, getDefaultPolicyPresets, matchPolicy } from '../request-policy.js';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 // Read version from package.json (single source of truth)
 const __cliFilename = fileURLToPath(import.meta.url);
@@ -28,6 +29,14 @@ const VERSION = pkgJson.version;
 const noColor = process.env['NO_COLOR'] !== undefined ||
     (!process.stdout.isTTY && process.env['FORCE_COLOR'] === undefined);
 const aqua = (s) => noColor ? s : `\x1b[38;2;127;255;212m${s}\x1b[0m`;
+// Credential name validation — shared pattern from daemon.ts and systemd-creds backend
+const SAFE_CRED_NAME = /^[a-z0-9][a-z0-9._-]*$/;
+function validateCredName(label, value) {
+    if (!SAFE_CRED_NAME.test(value)) {
+        console.error(`Invalid ${label}: "${value}". Allowed: lowercase alphanumeric, dots, hyphens, underscores.`);
+        process.exit(1);
+    }
+}
 // PID file management
 const getPidFile = () => path.join(getConfigDir(), 'daemon.pid');
 const writePidFile = () => {
@@ -172,11 +181,13 @@ program
     const serviceRegistry = createServiceRegistry({ configPath: config.services.configPath });
     // Start credential proxy
     const socketPath = path.join(getConfigDir(), 'proxy.sock');
+    const policyConfig = loadPolicyFromConfig(config);
     const credentialProxy = createCredentialProxy({
         socketPath,
         store: credentialStore,
         allowedServices: config.credentials.proxiedServices,
         serviceRegistry,
+        policyConfig,
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
@@ -324,11 +335,13 @@ program
     // Initialize service registry
     const serviceRegistry = createServiceRegistry({ configPath: config.services.configPath });
     // Start credential proxy
+    const policyConfig2 = loadPolicyFromConfig(config);
     const credentialProxy = createCredentialProxy({
         socketPath,
         store: credentialStore,
         allowedServices: config.credentials.proxiedServices,
         serviceRegistry,
+        policyConfig: policyConfig2,
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
@@ -401,11 +414,13 @@ program
     // Initialize service registry
     const serviceRegistry = createServiceRegistry({ configPath: config.services.configPath });
     // Start credential proxy
+    const policyConfig3 = loadPolicyFromConfig(config);
     const credentialProxy = createCredentialProxy({
         socketPath,
         store: credentialStore,
         allowedServices: config.credentials.proxiedServices,
         serviceRegistry,
+        policyConfig: policyConfig3,
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
@@ -498,6 +513,7 @@ program
     .description('All-in-one setup wizard — creates config, stores credentials, installs plugin')
     .option('--backend <backend>', 'Credential backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden)')
     .option('--no-openclaw', 'Skip OpenClaw plugin installation')
+    .option('--no-policy', 'Skip request policy preset configuration')
     .option('--non-interactive', 'Use environment variables instead of prompts (for CI)')
     .action(async (options) => {
     const os = await import('node:os');
@@ -769,6 +785,43 @@ program
             console.log('    Skipped\n');
         }
     }
+    // 3.5. Apply request policy presets
+    if (options.policy !== false && storedServices.length > 0) {
+        let shouldApplyPolicy = true;
+        if (!isNonInteractive) {
+            const rl = (await import('node:readline')).createInterface({
+                input: process.stdin,
+                output: process.stdout
+            });
+            const answer = await new Promise((resolve) => {
+                rl.question('  ? Enable API request policies? (Y/n): ', resolve);
+            });
+            rl.close();
+            shouldApplyPolicy = answer.toLowerCase() !== 'n';
+            if (shouldApplyPolicy) {
+                console.log('    Policies restrict which API endpoints agents can call.\n');
+            }
+        }
+        if (shouldApplyPolicy) {
+            const presets = getDefaultPolicyPresets();
+            const policyToApply = {};
+            for (const svc of storedServices) {
+                if (presets[svc]) {
+                    policyToApply[svc] = presets[svc];
+                }
+            }
+            if (Object.keys(policyToApply).length > 0) {
+                config.policy = policyToApply;
+                saveConfig(config);
+                console.log('  Applying default policy presets:\n');
+                for (const [svc, sp] of Object.entries(policyToApply)) {
+                    console.log(formatServicePolicy(svc, sp, '    '));
+                    console.log('');
+                }
+                console.log('  Customize policies later: ~/.aquaman/config.yaml\n');
+            }
+        }
+    }
     // 4. Detect OpenClaw and install plugin
     if (options.openclaw !== false) {
         const openclawDetected = fs.existsSync(openclawStateDir);
@@ -1060,6 +1113,42 @@ program
             }
         }
     }
+    // 5.5 Policy config
+    if (config?.policy && Object.keys(config.policy).length > 0) {
+        const policyConfigDoc = loadPolicyFromConfig(config);
+        const validation = validatePolicyConfig(policyConfigDoc);
+        if (validation.valid) {
+            const serviceCount = Object.keys(policyConfigDoc).length;
+            const ruleCount = Object.values(policyConfigDoc).reduce((sum, sp) => sum + sp.rules.length, 0);
+            console.log(`  \u2713 ${aqua('Policy')} valid (${serviceCount} service${serviceCount !== 1 ? 's' : ''}, ${ruleCount} rule${ruleCount !== 1 ? 's' : ''})`);
+            for (const [svc, sp] of Object.entries(policyConfigDoc)) {
+                const denyRules = sp.rules.filter(r => r.action === 'deny');
+                if (denyRules.length > 0) {
+                    const summary = denyRules.map(r => r.method !== '*' ? `${r.action} ${r.method} ${r.path}` : `${r.action} ${r.path}`).join(', ');
+                    console.log(`      ${svc}: ${summary}`);
+                }
+            }
+            // Warn about policies for non-proxied services
+            if (config.credentials.proxiedServices) {
+                for (const svc of Object.keys(policyConfigDoc)) {
+                    if (!config.credentials.proxiedServices.includes(svc)) {
+                        console.log(`  \u26a0 ${aqua('Policy')} service "${svc}" has rules but is not in proxiedServices`);
+                        issues++;
+                    }
+                }
+            }
+        }
+        else {
+            for (const err of validation.errors) {
+                console.log(`  \u2717 ${aqua('Policy')} ${err}`);
+            }
+            issues++;
+        }
+    }
+    else {
+        console.log(`  \u2139 ${aqua('Policy')} not configured \u2014 agents can call any endpoint on proxied services`);
+        console.log('    \u2192 Run: aquaman setup (or add policy rules to ~/.aquaman/config.yaml)');
+    }
     // 6. OpenClaw detection
     let openclawDetected = false;
     let cliFound = false;
@@ -1323,6 +1412,8 @@ credentials
     .description('Add a credential')
     .option('--backend <backend>', 'Override credential backend')
     .action(async (service, key, options) => {
+    validateCredName('service', service);
+    validateCredName('key', key);
     const config = loadConfig();
     const backend = options.backend || config.credentials.backend;
     let store;
@@ -1418,6 +1509,8 @@ credentials
     .command('delete <service> <key>')
     .description('Delete a credential')
     .action(async (service, key) => {
+    validateCredName('service', service);
+    validateCredName('key', key);
     const config = loadConfig();
     let store;
     try {
@@ -1572,6 +1665,42 @@ services
         process.exit(1);
     }
 });
+// Policy commands
+const policy = program.command('policy').description('Request policy management');
+policy
+    .command('list')
+    .description('List configured policy rules')
+    .action(async () => {
+    const config = loadConfig();
+    const policyConfig = loadPolicyFromConfig(config);
+    if (Object.keys(policyConfig).length === 0) {
+        console.log('No policies configured. Run: aquaman setup');
+        return;
+    }
+    for (const [name, sp] of Object.entries(policyConfig)) {
+        console.log(formatServicePolicy(name, sp));
+    }
+});
+policy
+    .command('test <service> <method> <path>')
+    .description('Test whether a request would be allowed or denied')
+    .action(async (service, method, reqPath) => {
+    const config = loadConfig();
+    const policyConfig = loadPolicyFromConfig(config);
+    const result = matchPolicy(service, method.toUpperCase(), reqPath, policyConfig);
+    if (!policyConfig[service]) {
+        console.log(`  \u2713 ALLOWED (no policy for service "${service}")`);
+        return;
+    }
+    if (result.allowed) {
+        const svcPolicy = policyConfig[service];
+        console.log(`  \u2713 ALLOWED (no matching rule, default: ${svcPolicy.defaultAction})`);
+    }
+    else {
+        const rule = result.matchedRule;
+        console.log(`  \u2717 DENIED by rule: ${rule.method} ${rule.path} \u2192 ${rule.action}`);
+    }
+});
 // Migration commands
 const migrate = program.command('migrate').description('Migrate credentials from other sources');
 migrate
@@ -1979,6 +2108,19 @@ program
     for (const service of config.credentials.proxiedServices) {
         console.log(`  - ${service}`);
     }
+    // Policy summary
+    const policyConfig = loadPolicyFromConfig(config);
+    const policySvcCount = Object.keys(policyConfig).length;
+    if (policySvcCount > 0) {
+        const ruleCount = Object.values(policyConfig).reduce((sum, sp) => sum + sp.rules.length, 0);
+        console.log(`\nRequest policies: ${policySvcCount} service${policySvcCount !== 1 ? 's' : ''}, ${ruleCount} rule${ruleCount !== 1 ? 's' : ''}`);
+        for (const [svc, sp] of Object.entries(policyConfig)) {
+            console.log(`  - ${svc}: ${sp.rules.length} rule${sp.rules.length !== 1 ? 's' : ''} (default: ${sp.defaultAction})`);
+        }
+    }
+    else {
+        console.log('\nRequest policies: not configured');
+    }
     // Check for stored credentials
     try {
         const store = await createCredentialStore({
@@ -2007,6 +2149,16 @@ program
     const info = await integration.detectOpenClaw();
     console.log(`\nOpenClaw: ${info.installed ? `installed (${info.version})` : 'not found'}`);
 });
+/** Format a single service policy for display (used by policy list, setup, doctor) */
+function formatServicePolicy(name, sp, indent = '  ') {
+    const lines = [];
+    lines.push(`${indent}${name} (default: ${sp.defaultAction})`);
+    for (const rule of sp.rules) {
+        const method = rule.method.padEnd(6);
+        lines.push(`${indent}  ${rule.action === 'deny' ? 'deny' : 'allow'}  ${method} ${rule.path}`);
+    }
+    return lines.join('\n');
+}
 function formatEntry(entry) {
     switch (entry.type) {
         case 'tool_call':
@@ -2014,7 +2166,7 @@ function formatEntry(entry) {
         case 'tool_result':
             return `Result for ${entry.data.toolCallId}`;
         case 'credential_access':
-            return `${entry.data.service} ${entry.data.operation} ${entry.data.success ? 'OK' : 'FAIL'}`;
+            return `${entry.data.service} ${entry.data.operation} ${entry.data.success ? 'OK' : `FAIL: ${entry.data.error || 'unknown'}`}`;
         default:
             return JSON.stringify(entry.data).slice(0, 80);
     }