🔱 Aquaman

🔱 AI एजेंट्स के लिए एकमात्र स्वतंत्र क्रेडेंशियल प्रॉक्सी: bring-your-own-vault आइसोलेशन और least-privilege अनुरोध नीतियाँ। आपकी कुंजियाँ वहीं रहती हैं जहाँ आप उन्हें पहले से रखते हैं, कभी भी एजेंट की मेमोरी में नहीं। 1Password, keychain, keepassxc और कई अन्य के साथ संगत।

आपने Claude Code, OpenClaw, या Hermes सेट अप किया, और अब आप .env फ़ाइलों को देख रहे हैं जिनमें आपकी कीमती API कुंजियाँ सादे टेक्स्ट में पड़ी हैं। आपने लेख पढ़े हैं। आप जानते हैं कि जब किसी एजेंट को prompt-injected किया जाता है तो क्या होता है। हम समझते हैं।

Aquaman इसे तीन सुरक्षा परतों के साथ ठीक करता है:

1. Process isolation: API कुंजियाँ एक अलग प्रॉक्सी प्रक्रिया में रहती हैं जो उन्हें egress पर इंजेक्ट करती है। एजेंट एक मार्कर रखता है, कभी कुंजी नहीं, इसलिए एजेंट में RCE होने पर भी कोई कुंजी नहीं पढ़ सकता। कोडिंग एजेंट्स को केवल वही refs मिलते हैं जो आप घोषित करते हैं, एक बार में एक कमांड।
2. Request policies: प्रति-सेवा नियम नियंत्रित करते हैं कि एजेंट कौन से endpoints कॉल कर सकता है। Admin APIs ब्लॉक करें, deletions रोकें, drafts की अनुमति दें लेकिन sends अस्वीकार करें। अस्वीकृत अनुरोधों को कभी वास्तविक क्रेडेंशियल नहीं मिलते।
3. Tamper-evident audit: प्रत्येक क्रेडेंशियल उपयोग SHA-256 hash chains के साथ लॉग किया जाता है। आप साबित कर सकते हैं कि क्या एक्सेस किया गया और बाद में छेड़छाड़ का पता लगा सकते हैं।

अपना रास्ता चुनें

Aquaman चार समन्वित पैकेजों के रूप में आता है, जो एक vault + एक daemon साझा करते हैं। केवल वही इंस्टॉल करें जो आपको चाहिए:

एक ही aquaman CLI चारों को सामने लाता है: vault और audit के लिए top-level कमांड, OpenClaw इंटीग्रेशन के लिए aquaman openclaw ..., कोडिंग-एजेंट इंटीग्रेशन के लिए aquaman coder ... (अंदर से aquaman-coder को डेलिगेट करता है) तथा Hermes Python पैकेज के लिए aquaman hermes ...।

Quick Start

aquaman help, aquaman doctor आपके मित्र हैं।

1. केवल Vault (बस प्रॉक्सी + आपके secrets)```bash

npm install -g aquaman-proxy aquaman setup # backend wizard + store keys aquaman daemon & # start the proxy aquaman credentials list # verify

प्रॉक्सी `~/.aquaman/proxy.sock` (UDS, `chmod 0o600`) पर सुनता है। किसी भी टूल को `http://aquaman.local/<service>/<path>` पर पॉइंट करें और प्रॉक्सी आपके चुने हुए vault बैकएंड से उस सेवा के लिए auth हेडर इंजेक्ट कर देता है।

### 2. OpenClaw Gateway```bash
openclaw plugins install aquaman-plugin           # 1. install plugin + proxy
openclaw aquaman setup                            # 2. backend + keys + plugin wire-up
openclaw                                          # 3. done - proxy starts automatically

समस्या निवारण: openclaw aquaman doctor।

सीधे npm का उपयोग कर रहे हैं? npm install -g aquaman-proxy && aquaman openclaw setup वही करता है - प्रॉक्सी CLI इंस्टॉल करता है, आपकी कुंजियाँ संग्रहीत करता है, प्लगइन को ~/.openclaw/extensions/aquaman-plugin/ में इंस्टॉल करता है, और क्रेडेंशियल्स को वायर करता है (OpenClaw ≥ 2026.6.5 पर SecretRef refs, पुराने संस्करणों पर auth-profiles.json प्लेसहोल्डर)।

aquaman openclaw setup models.providers.<svc>.baseUrl और channels.telegram.apiRoot को प्रॉक्सी के लूपबैक लिसनर पर इंगित करता है, क्योंकि OpenClaw का मॉडल ट्रांसपोर्ट और उसके चैनल प्रत्येक अपना HTTP क्लाइंट बनाते हैं और fetch इंटरसेप्टर को बायपास करते हैं। Telegram के अलावा अन्य चैनल कोई एंडपॉइंट ओवरराइड उजागर नहीं करते, इसलिए उनके टोकन संग्रहीत और माइग्रेट किए जाते हैं लेकिन egress पर इंजेक्ट नहीं किए जाते (देखें packages/plugin/README.md)। openclaw.json में प्लगइन कॉन्फ़िग के अंतर्गत चैनल जोड़ें; समर्थित चैनलों में Slack, Discord, Telegram, MS Teams, Matrix, LINE, Twitch, Twilio, BlueBubbles, Mattermost, Nostr, Tlon, Feishu, Google Chat, ElevenLabs, xAI, Cloudflare AI Gateway, Mistral, Hugging Face, और अन्य शामिल हैं (कुल 25)।

3. AI कोडिंग एजेंट (आज Claude Code)```bash

npm install -g aquaman-proxy aquaman-coder # 1. install daemon + adapter aquaman setup # 2. vault wizard aquaman daemon & # 3. start the proxy

aquaman coder project add my-app --path ~/code/my-app
--env ANTHROPIC_API_KEY=aquaman://anthropic/api_key
--env GITHUB_TOKEN=aquaman://github/token # 4. declare a project aquaman coder setup claude-code # 5. wire Claude Code hooks aquaman doctor # 6. verify - should show both vault + coder green

**इसे स्वयं देखें (30-सेकंड का अहा):** Claude Code को पुनः आरंभ करें, `~/code/my-app` के अंदर एक नया सत्र खोलें, और एजेंट से चलाने के लिए कहें:```
printenv | grep ANTHROPIC_API_KEY

आप इसे ट्रांसक्रिप्ट में देखेंगे:``` ANTHROPIC_API_KEY=[REDACTED:injected-value]

⏺ ANTHROPIC_API_KEY is set and available (injected via aquaman vault).

*child* प्रक्रिया ने असली key देखी (आपके tests, builds, MCP servers, import scripts - जो कुछ भी वास्तव में इसे चाहता है वह काम करता है)। *agent* - वह चीज़ जो तय करती है कि आपकी मशीन पर कौन सा code चलाना है - कभी भी value नहीं देखती, और इसलिए न तो conversation history देखती है, न ही model provider के logs, न ही कोई और जो बाद में आपके terminal का screenshot लेता है।

**इसे अपने खुद के terminal से भी उपयोग करें।** वही wrapper agent के बिना भी काम करता है। बस किसी covered project में `cd` करें और अपने command के आगे prefix लगाएं:```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py

Same env injection, same redaction on stdout/stderr. Drop it into Makefile targets, shell aliases, or CI runners - anywhere you'd otherwise reach for a .env file.

When Claude Code runs a Bash tool in ~/code/my-app, aquaman's hook rewrites the command via updatedInput.command to wrap it under aquaman-coder exec. That wrapper:

• Resolves each aquaman://service/key reference via the broker (POST /broker/resolve over UDS). Credentials are materialized for one command, not for the agent's lifetime.
• Pipes stdout/stderr through a redactor that prepends a value-based pattern for each resolved value: whatever string was injected gets redacted, regardless of shape (Atlassian tokens, Notion secrets, internal-API keys - none of them need to match a known provider format). Generic shape-based patterns (sk-ant-, ghp_, sk_live_, AKIA…, JWTs, PEM blocks, ATATT3xF…) still run after as defense-in-depth for secrets the child surfaces that we did NOT inject.
• Cleans up when the command exits.

Claude Code sandbox: it blocks Unix sockets by default, so aquaman coder setup claude-code allowlists the proxy socket on macOS (sandbox.network.allowUnixSockets). Linux and WSL2 ignore that list, where the only option is sandbox.network.allowAllUnixSockets: true, which opens every Unix socket to sandboxed commands.

4. Hermes (agent host)

Hermes is a foreign (Python) host with no transport hook to inject, so isolation is done proxy-side: the proxy exposes an opt-in, token-gated loopback listener and Hermes is pointed at it through its own env vars.```bash npm install -g aquaman-proxy # 1. install daemon aquaman setup # 2. vault wizard aquaman credentials add anthropic api_key sk-ant-... # 3. store a provider key

aquaman hermes setup # 4. enable loopback + write ~/.hermes/.env aquaman daemon & # 5. start the proxy (UDS + loopback) aquaman hermes doctor # 6. verify - listener + env + vault + Hermes

`aquaman hermes setup` लूपबैक लिसनर को सक्षम करता है, प्रति-इंस्टॉल टोकन जनरेट करता है, और `~/.hermes/.env` में एक aquaman-प्रबंधित ब्लॉक लिखता है (`HERMES_HOME` का सम्मान करते हुए): नेटिव `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` के साथ-साथ टोकन के बराबर एक प्लेसहोल्डर api_key। Hermes टोकन को अपनी प्रोवाइडर कुंजी के रूप में भेजता है; प्रॉक्सी इसे हटा देता है, आपके वास्तविक vault क्रेडेंशियल को इंजेक्ट करता है, और अपस्ट्रीम को अग्रेषित करता है। आज केवल LLM प्रोवाइडर (Anthropic, OpenAI)।

**वैकल्पिक इन-सेशन सुविधा** - Python प्लगइन एक `/aquaman-status` कमांड, एक `aquaman_status` टूल, और Hermes के अंदर एक सेशन-स्टार्ट हेल्थ प्रोब जोड़ता है (कोई क्रेडेंशियल नहीं रखता):```bash
pip install aquaman-hermes            # or: uv tool install aquaman-hermes
aquaman-hermes install                # drops the plugin into ~/.hermes/plugins/aquaman/
hermes plugins enable aquaman

The plugin also registers an aquaman secret source (Hermes ≥ 0.18.1) for project secrets like GITHUB_TOKEN. Bind them under secrets.aquaman.env in Hermes' config.yaml, then declare each ref with aquaman broker allow aquaman://github/token (required since v0.15.0; aquaman hermes doctor lists any you missed). Unlike the LLM keys above, these values do enter Hermes' env. See packages/hermes/README.md.

How It Works```

Agent / OpenClaw / Coding Agent Aquaman Proxy ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ │ │ ANTHROPIC_BASE_URL │═══ UDS / HTTP ════>│ Keychain / 1Pass / │ │ = aquaman.local │ │ Vault / Encrypted │ │ │<══════════════════ │ │ │ fetch() interceptor │═══ broker:resolve │ + Policy enforced │ │ (channel APIs) │ │ + Auth injected: │ │ │ │ header / url-path │ │ No credentials. │ ~/.aquaman/ │ basic / oauth │ │ No open ports. │ proxy.sock │ │ │ No keys to read. │ (chmod 0o600) │ │ └──────────────────────┘ └──┬─────────┬─────────┘ │ │ │ ▼ │ ~/.aquaman/audit/ │ (hash-chained) ▼ api.anthropic.com api.telegram.org slack.com/api …

1. **Store**: क्रेडेंशियल्स उसी vault बैकएंड में रहते हैं जो आप पहले से चलाते हैं - कोई अलग house vault नहीं (Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, encrypted-file)।
2. **Policy**: Proxy क्रेडेंशियल्स को छूने से *पहले* method + path नियम जाँचता है। अस्वीकृत अनुरोधों को `403` मिलता है, कभी असली auth headers नहीं।
3. **Inject**: Proxy क्रेडेंशियल खोजता है और forward करने से पहले auth header जोड़ता है। 25 builtin services, 4 injecting auth modes (header, URL-path, HTTP Basic, OAuth); एक 5वाँ, `none`, केवल at-rest है (proxy ट्रैफ़िक अस्वीकार करता है)।
4. **Broker (coder + Hermes secret source)**: `POST /broker/resolve` प्रति tool call एक क्रेडेंशियल materialize करता है, जो एक ही command के env तक सीमित होता है। इसे केवल `aquaman daemon` serve करता है, और केवल उन refs के लिए जिन्हें आपने declare किया है (`projects.yaml` या `aquaman broker allow`)। OpenClaw plugin का proxy इसे कभी serve नहीं करता (v0.15.0+)।
5. **Audit**: हर क्रेडेंशियल उपयोग SHA-256 hash chains के साथ लॉग किया जाता है।

Proxy paths पर agent को एक local endpoint और एक marker दिखता है: `aquaman-proxy-managed` placeholder, या loopback token, जो केवल आपके local proxy के विरुद्ध काम करता है। कभी असली key नहीं। Coder path पर *child* command को declared values मिलती हैं और agent redacted output देखता है।

## Security Model

| Layer | What it does | What it stops |
|---|---|---|
| **Process isolation** | क्रेडेंशियल्स एक अलग process में, Unix socket (`chmod 0o600`) या token-gated loopback listener के ज़रिए पहुँचे जाते हैं | Compromised agent proxied keys नहीं पढ़ सकता: अलग address space |
| **Broker scope** | केवल `aquaman daemon` values देता है, और केवल उन refs के लिए जिन्हें आपने declare किया; OpenClaw-hosted proxies कभी नहीं (v0.15.0+) | Agent socket के ज़रिए मनमाने vault entries नहीं खींच सकता |
| **Service allowlisting** | `proxiedServices` नियंत्रित करता है कि agent किन APIs तक पहुँच सकता है | Agent उन services से बात नहीं कर सकता जिन्हें आपने authorize नहीं किया |
| **Request policies** | प्रति service method + path नियम, credential injection से पहले लागू | Agent Anthropic तक पहुँच सकता है पर उसके admin API तक नहीं; emails draft कर सकता है पर भेज नहीं सकता |
| **Audit trail** | हर क्रेडेंशियल उपयोग के SHA-256 hash-chained logs | Post-incident forensics, tamper detection, compliance evidence |
| **Per-tool-call broker (coder)** | `aquaman-coder exec` एक बार में एक command के लिए creds materialize करता है | क्रेडेंशियल्स agent के shell environment में नहीं फैलते |
| **Output redaction (coder)** | `aquaman-coder exec` stdout/stderr को एक redactor से गुज़ारता है जो हर injected value को verbatim scrub करता है - साथ ही fallback के रूप में generic provider patterns | मनमाने, बिना आकार वाले क्रेडेंशियल्स भी agent transcript तक कभी नहीं पहुँचते |

### Transports and access control

| Path | Transport | Access control |
|---|---|---|
| Coding agents, कोई भी client जो socket dial कर सकता है | Unix socket `~/.aquaman/proxy.sock` | File permissions (`0600`): केवल आपके रूप में चलने वाले processes |
| Hermes (v0.13.0+), OpenClaw model और Telegram traffic (v0.15.0+) | Loopback TCP `127.0.0.1:<port>` | Per-install token, constant-time check, loopback bind |

Hermes और OpenClaw प्रत्येक अपना HTTP client बनाते हैं और socket dial नहीं कर सकते, इसलिए वे listener का उपयोग करते हैं। बाकी सब socket का उपयोग करता है।

Token local proxy तक पहुँचने की capability है, क्रेडेंशियल नहीं। प्रति install generate होता है, `~/.aquaman/config.yaml` (`0600`) में संग्रहीत, host द्वारा उसके provider api key के रूप में भेजा जाता है। Proxy इसे जाँचता है, हटाता है, आपकी असली key inject करता है। Telegram में कोई auth header नहीं है, इसलिए वहाँ token `/bot<TOKEN>` path segment में सवार होता है।

Trade-off: कोई भी local process loopback port तक पहुँच सकता है, अन्य users सहित, जहाँ socket का `0600` उन्हें बाहर रखता है। वहाँ token ही gate है, इसलिए listener तब तक बंद रहता है जब तक `aquaman hermes setup` या `aquaman openclaw setup` इसे चालू न करे।

### Channel credentials on OpenClaw 2026.7.33+

| Channel | Egress through the proxy |
|---|---|
| Telegram | हाँ, v0.15.0 से |
| बाकी सब | नहीं। केवल Vault storage और migration |

प्रत्येक channel प्रति request अपना HTTP client बनाता है, इसलिए plugin का `fetch` interceptor इन versions पर channel traffic नहीं देखता। किसी channel को route करने के लिए host से endpoint override चाहिए, और Telegram ही एकमात्र है जिसके पास यह है: `aquaman openclaw setup` `channels.telegram.apiRoot` को proxy पर point करता है और bot token को loopback token से बदल देता है।

बाकी के लिए, आपका token vault में रहता है पर OpenClaw इसे सीधे उपयोग करता है, इसलिए proxy path में नहीं है और वे calls audited नहीं हैं। `aquaman openclaw doctor` बताता है कि आपके configured channels में से कौन किस group में है। Model providers अप्रभावित हैं।

**What same-user isolation can't do.** Socket का `0o600` अन्य users को बाहर रखता है, आपके रूप में चलने वाले अन्य processes को नहीं। ऐसा process चलते समय proxy के ज़रिए requests भेज सकता है (request policy से सीमित, audit log में दर्ज) और आपके declared refs fetch कर सकता है, जिसका यही अर्थ है declaring। यह proxy द्वारा inject की गई keys नहीं पढ़ सकता। कठोर boundary के लिए, agent को किसी भिन्न OS user के रूप में या sandbox में चलाएँ।

विस्तृत model - प्रति-integration विवरण (HTTP interceptor scope, auth profiles, scanner findings, ClawScan publisher note) - [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md) और [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md) में है।

### Compliance posture

Aquaman `test/compliance/` के अंतर्गत runnable conformance tests देता है जो इनसे mapped हैं:

- **MITRE ATLAS** v5.4.0: techniques AML.T0055, T0012, T0062, T0090, T0098 (`test/compliance/atlas/`)
- **NIST SP 800-53 Rev 5**: IA-5, AC-3, AC-6, AU-2/9/10, SC-12/28, SI-10 (`test/compliance/nist/`)

साथ ही CISA/Five-Eyes "Careful Adoption of Agentic AI Services" (April 2026), CSA MAESTRO, और OWASP Top 10 for Agentic Applications के लिए alignment narratives। Tests `npm test` के हिस्से के रूप में चलते हैं। Mappings के लिए [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance) देखें।


## Request Policies

OAuth scopes "draft an email" और "send an email" में अंतर नहीं कर सकते। दोनों `gmail.send` हैं। Request policies उसी अंतराल को भरती हैं।```yaml
# ~/.aquaman/config.yaml
policy:
  anthropic:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organizations/**"
        action: deny          # block admin/billing API
  openai:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organization/**"
        action: deny
      - method: DELETE
        path: "/v1/**"
        action: deny          # no deletions
  slack:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/api/admin.*"
        action: deny          # Slack Web API admin methods
  gmail:
    defaultAction: allow
    rules:
      - method: POST
        path: "/gmail/v1/users/*/messages/send"
        action: deny          # drafts ok, sending blocked

• Paths upstream API का पूरा path होते हैं service prefix के बाद: Slack का Web API /api/<method> है, Gmail का /gmail/v1/... है। v0.15.0 से पहले के presets /admin.* और /v1/users/*/messages/send का उपयोग करते थे, जो वास्तविक traffic से कभी मेल नहीं खाते थे। aquaman doctor उन्हें flag करता है यदि वे अभी भी आपके config में हैं।
• कोई policy नहीं = सभी allow (backward compatible)
• पहला match जीतता है: rules ऊपर से नीचे evaluate होते हैं, unmatched requests defaultAction पर fall through करती हैं
• auth से पहले Denied: blocked requests को कभी वास्तविक credentials नहीं मिलते
• Path globs: * एक segment के भीतर match करता है, ** शून्य या अधिक segments match करता है
• aquaman setup stored services (anthropic, openai, slack, gmail) के लिए safe defaults लागू करता है।
• aquaman policy list / aquaman policy test <svc> <method> <path> inspection / dry-runs के लिए।

Credential Backends

अपना vault लाएं - aquaman का कोई house store नहीं है। वह backend चुनें जो आप पहले से चलाते हैं; secrets वहीं रहते हैं, और proxy उन्हें in place पढ़ता है।

aquaman setup एक उपयुक्त default auto-detect करता है (macOS → keychain; Linux → keychain यदि libsecret है, अन्यथा systemd-creds यदि systemd ≥ 256 है, अन्यथा encrypted-file)।

encrypted-file native keyring के बिना headless Linux/CI environments के लिए last-resort है। Linux पर बेहतर security के लिए, libsecret-1-dev (GNOME Keyring) install करें, systemd-creds (TPM2 binding) उपयोग करें, या 1Password/Vault उपयोग करें।

Credential caching (v0.13.1+)

प्रति-access लागत वाले backends, जैसे 1password (desktop-app mode में प्रति read एक biometric prompt), bitwarden (~1-2 s CLI spawn) और vault (एक HTTP round-trip), default रूप से 15 मिनट के लिए daemon की memory में cached होते हैं, ताकि एक busy agent session प्रति request के बजाय प्रति window एक बार vault unlock करे। अन्य backends पहले से ही तेज़ हैं या internally cache करते हैं, इसलिए उनके लिए caching default रूप से बंद है। ~/.aquaman/config.yaml में credentials.cacheTtlSeconds (या AQUAMAN_CACHE_TTL) से tune करें; 0 इसे disable करता है।

ईमानदार trade-off: प्रति-access biometric prompt एक user-presence check है, और cache TTL window के लिए प्रति-access presence हटा देता है। Unattended agents के लिए वह prompt कभी answered नहीं होता, इसलिए vault को छोड़कर plaintext .env उपयोग किया जाता है, जो स्पष्ट रूप से बदतर है। Cache isolation boundary को नहीं हटाता: values केवल proxy process में रहती हैं (जहाँ वे पहले से ही हर request पर transit करती हैं), कभी disk पर नहीं लिखी जातीं, और जब आप aquaman credentials add से rotate करते हैं तो तुरंत invalidated हो जाती हैं। Writes हमेशा आपके vault में जाती हैं। test/compliance/cache-residency.test.ts में Conformance-tested। 1Password के साथ zero prompts के लिए, aquaman vault तक scoped service account उपयोग करें; aquaman doctor आपको वहाँ इंगित करेगा।

License

MIT - देखें LICENSE।