🔱 L'unico proxy di credenziali indipendente per agenti AI: isolamento bring-your-own-vault e politiche di richiesta con privilegio minimo. Le tue chiavi rimangono dove già le conservi, mai nella memoria dell'agente. Compatibile con 1Password, keychain, keepassxc e molti altri.
# 🔱 Aquaman
[](https://github.com/tech4242/aquaman/actions/workflows/ci.yml)
[](https://codecov.io/gh/tech4242/aquaman)
[](https://www.npmjs.com/package/aquaman-proxy)
[](https://www.npmjs.com/package/aquaman-proxy)
[](https://github.com/tech4242/aquaman#security-model)
[](https://www.typescriptlang.org/)
[](LICENSE)
🔱 L'unico proxy indipendente per le credenziali dedicato agli agenti AI: isolamento bring-your-own-vault e policy di richiesta a privilegio minimo. Le tue chiavi restano dove le conservi già, mai nella memoria dell'agente. Compatibile con 1Password, keychain, keepassxc e molti altri.
Hai configurato Claude Code, Codex, OpenClaw, Hermes o Docker Sandboxes, e ora ti ritrovi davanti a file `.env` con le tue preziose chiavi API in chiaro. Hai letto gli articoli. Sai cosa succede quando un agente subisce un prompt injection. Ti capiamo.
Aquaman risolve il problema con tre livelli di difesa:
1. **Isolamento dei processi**: le chiavi API risiedono in un processo proxy separato che le inietta in uscita. L'agente possiede un marker, mai una chiave, quindi nemmeno un RCE nell'agente può leggerne una. Gli agenti di coding ricevono solo i riferimenti che dichiari, una richiesta alla volta.
2. **Policy di richiesta**: regole per singolo servizio controllano *quali endpoint* un agente può chiamare. Blocca le API di amministrazione, impedisci le cancellazioni, consenti le bozze ma nega gli invii. Le richieste negate non ricevono mai credenziali reali.
3. **Audit a prova di manomissione**: ogni utilizzo di credenziali viene registrato con catene di hash SHA-256. Puoi dimostrare cosa è stato accesso e rilevare manomissioni a posteriori.
## Scegli il tuo percorso
Aquaman viene distribuito come quattro pacchetti coordinati, che condividono un unico vault + un unico daemon. Installa solo ciò che ti serve:
| Pacchetto | Cosa fa | Quando installarlo |
|---|---|---|
| **[`aquaman-proxy`](https://github.com/tech4242/aquaman/blob/main/packages/proxy)** | Core: vault, daemon, audit, policy, CLI. Il pezzo che serve a tutti. | Sempre. |
| **[`aquaman-plugin`](https://github.com/tech4242/aquaman/blob/main/packages/plugin)** | Adattatore per OpenClaw Gateway. Avvia il proxy all'avvio del Gateway; instrada il traffico del modello e di Telegram attraverso di esso; 25 servizi integrati su 5 modalità di autenticazione. | Se esegui un OpenClaw Gateway. Disponibile anche su https://clawhub.ai/plugins/aquaman-plugin |
| **[`aquaman-coder`](https://github.com/tech4242/aquaman/blob/main/packages/coder)** | Adattatore per agenti di coding AI. Riferimenti `aquaman://service/key` con ambito di progetto, risolti a ogni chiamata dello strumento Bash. | Se usi Claude Code o Codex. |
| **[`aquaman-hermes`](https://github.com/tech4242/aquaman/blob/main/packages/hermes)** | Plugin per l'agent-host Hermes (Python, su PyPI). Punta Hermes verso un listener loopback opt-in, protetto da token, tramite le sue native `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL`; aggiunge un comando in-sessione `/aquaman-status`, uno strumento e una sonda di salute. L'isolamento è lato proxy; il plugin non detiene credenziali. | Se esegui l'agent host Hermes. `pip install aquaman-hermes` |
| **Docker Sandboxes** | Non è un pacchetto: è un percorso separato che richiede solo `aquaman-proxy`. Il proxy di Docker inietta i segreti; `aquaman get` li fornisce dal tuo vault, con la allow-list e il registro di audit. | Se esegui agenti in Docker Sandboxes. Vedi [Quick Start 5](#5-docker-sandboxes). |
Un'unica CLI `aquaman` espone tutti e quattro: comandi di primo livello per vault e audit, `aquaman openclaw ...` per l'integrazione OpenClaw, `aquaman coder ...` per l'integrazione con gli agenti di coding (che delega a `aquaman-coder` dietro le quinte) e `aquaman hermes ...` per il pacchetto Python Hermes.
## Quick Start
`aquaman help`, `aquaman doctor` sono tuoi amici.
### 1. Solo vault (solo il proxy + i tuoi segreti)
```bash
npm install -g aquaman-proxy
aquaman setup # backend wizard + store keys
aquaman daemon & # start the proxy
aquaman credentials list # verify
```
Il proxy ascolta su `~/.aquaman/proxy.sock` (UDS, `chmod 0o600`). Punta qualsiasi strumento su `http://aquaman.local/<service>/<path>` e il proxy inietta gli header di autenticazione per quel servizio dal backend vault scelto.
### 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
```
Troubleshooting: `openclaw aquaman doctor`.
**Usi npm direttamente?** `npm install -g aquaman-proxy && aquaman openclaw setup` fa la stessa cosa - installa la CLI del proxy, memorizza le tue chiavi, installa il plugin in `~/.openclaw/extensions/aquaman-plugin/` e collega le credenziali (riferimenti SecretRef su OpenClaw ≥ 2026.6.5, il segnaposto auth-profiles.json sulle versioni precedenti).
`aquaman openclaw setup` punta `models.providers.<svc>.baseUrl` e `channels.telegram.apiRoot` verso il listener di loopback del proxy, perché il trasporto dei modelli di OpenClaw e i suoi canali costruiscono ciascuno il proprio client HTTP e bypassano l'intercettore fetch. I canali diversi da Telegram non espongono alcun override dell'endpoint, quindi i loro token vengono memorizzati e migrati ma non iniettati in uscita (vedi [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md)). Aggiungi i canali nella configurazione del plugin in `openclaw.json`; tra quelli supportati ci sono Slack, Discord, Telegram, MS Teams, Matrix, LINE, Twitch, Twilio, BlueBubbles, Mattermost, Nostr, Tlon, Feishu, Google Chat, ElevenLabs, xAI, Cloudflare AI Gateway, Mistral, Hugging Face e altri (25 in totale).
### 3. Agenti di coding AI (Claude Code, Codex)
```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
# (or: aquaman coder setup codex)
aquaman doctor # 6. verify - should show both vault + coder green
```
**Provalo tu stesso (l'effetto "aha" in 30 secondi):** riavvia Claude Code (o Codex), apri una nuova sessione all'interno di `~/code/my-app` e chiedi all'agente di eseguire:
```
printenv | grep ANTHROPIC_API_KEY
```
Lo vedrai nella trascrizione:
```
ANTHROPIC_API_KEY=[REDACTED:injected-value]
⏺ ANTHROPIC_API_KEY is set and available (injected via aquaman vault).
```
Il processo *figlio* vedeva la chiave reale (i tuoi test, le build, i server MCP, gli script di importazione - qualsiasi cosa che ne abbia effettivamente bisogno funziona). L'*agente* - la cosa che decide quale codice eseguire sulla tua macchina - non vede mai il valore, e quindi non lo vedono nemmeno la cronologia della conversazione, né i log del provider del modello, né chiunque in seguito faccia uno screenshot del tuo terminale.
**Usalo anche dal tuo terminale.** Lo stesso wrapper funziona senza l'agente. Basta fare `cd` in un progetto coperto e anteporre il comando:
```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py
```
Stessa iniezione di env, stessa redazione su stdout/stderr. Inseriscilo nei target dei Makefile, negli alias della shell o nei runner CI - ovunque altrimenti faresti ricorso a un file `.env`.
Quando Claude Code o Codex esegue un comando shell in `~/code/my-app`, l'hook di aquaman riscrive il comando tramite `updatedInput.command` per avvolgerlo sotto `aquaman-coder exec`. Quel wrapper:
- Risolve ogni riferimento `aquaman://service/key` tramite il broker (`POST /broker/resolve` su UDS). Le credenziali vengono materializzate per un singolo comando, non per l'intera durata dell'agente.
- Convoglia stdout/stderr attraverso un redattore che antepone un pattern basato sul valore per ogni valore risolto: **qualunque stringa sia stata iniettata viene redatta, indipendentemente dalla forma** (token Atlassian, segreti Notion, chiavi di API interne - nessuno di essi deve corrispondere a un formato di provider noto). I pattern generici basati sulla forma (sk-ant-, ghp_, sk_live_, AKIA…, JWT, blocchi PEM, ATATT3xF…) vengono comunque eseguiti in seguito come difesa in profondità per i segreti che il processo figlio espone e che NON abbiamo iniettato.
- Esegue la pulizia all'uscita del comando.
**Sandbox di Claude Code:** blocca i socket Unix per impostazione predefinita, quindi `aquaman coder setup claude-code` inserisce nella allowlist il socket del proxy su macOS (`sandbox.network.allowUnixSockets`). Linux e WSL2 ignorano quella lista, dove l'unica opzione è `sandbox.network.allowAllUnixSockets: true`, che apre ogni socket Unix ai comandi in sandbox.
**Codex:** approva gli hook di aquaman nella revisione degli hook di avvio di Codex dopo il setup (Codex salta i nuovi hook finché non li consideri attendibili). Anche la sua sandbox blocca il socket del proxy per impostazione predefinita; `aquaman coder setup codex` stampa il profilo di permessi di `config.toml` che lo consente. Gli hook di Codex non possono riscrivere l'output della shell, quindi la redazione avviene all'interno di `aquaman-coder exec`. Dettagli in [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md#codex).
### 4. Hermes (agent host)
Hermes è un host esterno (Python) senza hook di trasporto da iniettare, quindi l'isolamento avviene lato proxy: il proxy espone un listener loopback opt-in, protetto da token, e Hermes viene puntato ad esso tramite le proprie variabili d'ambiente.
```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` abilita il listener di loopback, genera un token per installazione e scrive un blocco gestito da aquaman in `~/.hermes/.env` (rispettando `HERMES_HOME`): il nativo `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` più un api_key segnaposto uguale al token. Hermes invia il token come chiave del provider; il proxy lo rimuove, inietta la tua credenziale reale dal vault e inoltra a monte. Solo provider LLM (Anthropic, OpenAI) al momento.
**Zuccherino opzionale in-session** - il plugin Python aggiunge un comando `/aquaman-status`, uno strumento `aquaman_status` e una sonda di salute all'avvio della sessione dentro Hermes (non detiene credenziali):
```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
```
Il plugin registra anche una **sorgente di segreti** `aquaman` (Hermes ≥ 0.18.1) per i segreti di progetto come `GITHUB_TOKEN`. Associali sotto `secrets.aquaman.env` nel `config.yaml` di Hermes, poi dichiara ogni ref con `aquaman broker allow aquaman://github/token` (richiesto dalla v0.15.0; `aquaman hermes doctor` elenca quelli che hai dimenticato). A differenza delle chiavi LLM sopra, questi valori entrano nell'env di Hermes. Vedi [`packages/hermes/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/hermes/README.md).
### 5. Docker Sandboxes
Docker Sandboxes tiene già le credenziali fuori dalla sandbox: un proxy sulla tua macchina le inietta nelle richieste, e l'agente all'interno della VM vede un placeholder. Per impostazione predefinita i valori provengono dal keychain del tuo sistema operativo. Puntali invece su aquaman per ottenere ogni vault supportato da aquaman, la allow-list dei ref e una voce di audit a prova di manomissione ogni volta che sbx legge un segreto.
```bash
npm install -g aquaman-proxy
aquaman setup # 1. vault wizard
aquaman daemon & # 2. start the proxy
aquaman credentials add github token # 3. store the secret (if not already there)
aquaman broker allow aquaman://github/token # 4. allow it to be handed out
sbx secret set github \
--command "$(command -v node) $(command -v aquaman) get aquaman://github/token" \
--refresh on-demand # 5. sbx reads it from aquaman
```
sbx esegue quel comando dal proprio servizio in background, che non ha il `PATH` della tua shell, quindi il passaggio 5 memorizza percorsi assoluti. Ripeti i passaggi 4 e 5 per ogni servizio utilizzato dalla tua sandbox.
Lo stesso comando `aquaman get` funziona ovunque uno strumento richieda un comando che stampi un segreto: Codex (`model_providers.<id>.auth.command`), Claude Code (`apiKeyHelper`), i provider di segreti exec di OpenClaw e le sorgenti di segreti da comando di Hermes.
## Come funziona
```
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**: Le credenziali risiedono nel backend del vault che già utilizzi - nessun vault proprietario (Keychain, 1Password, HashiCorp Vault, Bitwarden, Keeper, KeePassXC, systemd-creds, encrypted-file).
2. **Policy**: Il proxy verifica le regole di metodo + path *prima* di toccare le credenziali. Le richieste negate ricevono un `403`, mai header di autenticazione reali.
3. **Inject**: Il proxy cerca la credenziale e aggiunge l'header di autenticazione prima dell'inoltro. 25 servizi integrati, 4 modalità di iniezione dell'autenticazione (header, URL-path, HTTP Basic, OAuth); una quinta, `none`, è solo at-rest (il proxy rifiuta il traffico).
4. **Broker (coder, sorgente di segreti Hermes, `aquaman get`)**: `POST /broker/resolve` materializza una credenziale per ogni chiamata di tool, limitata all'env di un singolo comando. Solo `aquaman daemon` lo serve, e solo per i ref che hai dichiarato (`projects.yaml` o `aquaman broker allow`). Il proxy del plugin OpenClaw non lo serve mai (v0.15.0+).
5. **Audit**: Ogni utilizzo di credenziali viene registrato con catene di hash SHA-256.
Sui path del proxy l'agente vede un endpoint locale più un marker: il placeholder `aquaman-proxy-managed`, oppure il token di loopback, che funziona solo contro il tuo proxy locale. Mai una chiave reale. Sul path del coder il comando *figlio* riceve i valori dichiarati e l'agente vede output redatto.
## Modello di sicurezza
| Livello | Cosa fa | Cosa blocca |
|---|---|---|
| **Isolamento dei processi** | Credenziali in un processo separato, raggiunto tramite un socket Unix (`chmod 0o600`) o un listener di loopback protetto da token | Un agente compromesso non può leggere le chiavi proxate: spazio di indirizzamento diverso |
| **Ambito del broker** | Solo `aquaman daemon` distribuisce valori, e solo per i ref che hai dichiarato; i proxy ospitati da OpenClaw non lo fanno mai (v0.15.0+) | Un agente non può estrarre voci arbitrarie dal vault attraverso il socket |
| **Allowlisting dei servizi** | `proxiedServices` controlla quali API l'agente può raggiungere | L'agente non può comunicare con servizi che non hai autorizzato |
| **Policy delle richieste** | Regole di metodo + path per servizio, applicate prima dell'iniezione delle credenziali | L'agente può raggiungere Anthropic ma non la sua admin API; può redigere email ma non inviarle |
| **Audit trail** | Log con catene di hash SHA-256 di ogni utilizzo di credenziali | Forense post-incidente, rilevamento di manomissioni, evidenza di conformità |
| **Broker per chiamata di tool (coder)** | `aquaman-coder exec` materializza le credenziali per un comando alla volta | Le credenziali non si diffondono nell'ambiente shell dell'agente |
| **Redazione dell'output (coder)** | `aquaman-coder exec` convoglia stdout/stderr attraverso un redattore che ripulisce ogni valore appena iniettato alla lettera - più pattern generici dei provider come fallback | Anche credenziali arbitrarie e senza forma non raggiungono mai il transcript dell'agente |
### Trasporti e controllo degli accessi
| Path | Trasporto | Controllo degli accessi |
|---|---|---|
| Agenti di coding, qualsiasi client in grado di contattare un socket | Socket Unix `~/.aquaman/proxy.sock` | Permessi file (`0600`): solo i processi eseguiti come te |
| Hermes (v0.13.0+), traffico modello e Telegram di OpenClaw (v0.15.0+) | Loopback TCP `127.0.0.1:<port>` | Token per installazione, controllo a tempo costante, bind su loopback |
Hermes e OpenClaw costruiscono ciascuno il proprio client HTTP e non possono contattare un socket, quindi usano il listener. Tutto il resto usa il socket.
Il token è una capability per raggiungere il proxy locale, non una credenziale. Generato per installazione, memorizzato in `~/.aquaman/config.yaml` (`0600`), inviato dall'host come sua api key del provider. Il proxy lo verifica, lo rimuove, inietta la tua chiave reale. Telegram non ha header di autenticazione, quindi lì il token viaggia nel segmento di path `/bot<TOKEN>`.
Trade-off: qualsiasi processo locale può raggiungere una porta di loopback, inclusi altri utenti, dove il `0600` del socket li esclude. Il token è il gate lì, quindi il listener resta spento finché `aquaman hermes setup` o `aquaman openclaw setup` non lo attiva.
### Credenziali dei canali su OpenClaw 2026.7.33+
| Canale | Egress attraverso il proxy |
|---|---|
| Telegram | Sì, dalla v0.15.0 |
| Tutto il resto | No. Solo archiviazione nel vault e migrazione |
Ogni canale costruisce il proprio client HTTP per richiesta, quindi l'intercettore `fetch` del plugin non vede più il traffico dei canali su queste versioni. Instradare un canale richiede un override dell'endpoint da parte dell'host, e Telegram è l'unico che ce l'ha: `aquaman openclaw setup` punta `channels.telegram.apiRoot` al proxy e sostituisce il token del bot con il token di loopback.
Per il resto, il tuo token resta nel vault ma OpenClaw lo usa direttamente, quindi il proxy non è nel path e quelle chiamate non vengono auditate. `aquaman openclaw doctor` elenca quali dei tuoi canali configurati sono in quale gruppo. I provider di modelli non sono interessati.
**Cosa non può fare l'isolamento tra utenti dello stesso account.** Il `0o600` del socket tiene fuori gli altri utenti, non gli altri processi eseguiti come te. Un tale processo può inviare richieste attraverso il proxy mentre è in esecuzione (limitato dalla policy delle richieste, registrato nell'audit log) e può recuperare i ref che hai dichiarato, che è ciò che significa dichiarare. Non può leggere le chiavi che il proxy inietta. Per un confine più solido, esegui l'agente come utente OS diverso o in una sandbox.
Il modello dettagliato - specifiche per integrazione (ambito dell'intercettore HTTP, profili di autenticazione, risultati dello scanner, nota del publisher ClawScan) - si trova in [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md) e [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md).
### Postura di conformità
Aquaman fornisce test di conformità eseguibili sotto `test/compliance/` mappati a:
- **MITRE ATLAS** v5.4.0: tecniche 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/`)
Più narrative di allineamento per CISA/Five-Eyes "Careful Adoption of Agentic AI Services" (aprile 2026), CSA MAESTRO e OWASP Top 10 for Agentic Applications. I test vengono eseguiti come parte di `npm test`. Vedi [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance) per le mappature.
## Policy delle richieste
Gli scope OAuth non riescono a distinguere tra "redigere un'email" e "inviare un'email". Sono entrambi `gmail.send`. Le policy delle richieste colmano questa lacuna.
```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
```
- **I percorsi sono il percorso completo dell'API upstream** dopo il prefisso del servizio: la Web API di Slack è `/api/<method>`, quella di Gmail è `/gmail/v1/...`. I preset precedenti alla v0.15.0 usavano `/admin.*` e `/v1/users/*/messages/send`, che non corrispondevano mai al traffico reale. `aquaman doctor` li segnala se sono ancora nella tua configurazione.
- **Nessuna policy = consenti tutto** (retrocompatibile)
- **Vince la prima corrispondenza**: le regole vengono valutate dall'alto verso il basso, le richieste non corrispondenti ricadono su `defaultAction`
- **Negato prima dell'autenticazione**: le richieste bloccate non ricevono mai credenziali reali
- **Glob dei percorsi:** `*` corrisponde all'interno di un segmento, `**` corrisponde a zero o più segmenti
- `aquaman setup` applica impostazioni predefinite sicure per i servizi memorizzati (`anthropic`, `openai`, `slack`, `gmail`).
- `aquaman policy list` / `aquaman policy test <svc> <method> <path>` per l'ispezione / le prove a vuoto.
## Backend delle credenziali
Porta il tuo vault - aquaman non ha un archivio interno. Scegli il backend che già utilizzi; i segreti restano lì e il proxy li legge sul posto.
| Backend | Ideale per | Configurazione |
|---|---|---|
| `keychain` | Sviluppo locale su macOS (predefinito) | Funziona subito |
| `encrypted-file` | Linux, WSL2, CI/CD | AES-256-GCM, protetto da password |
| `keepassxc` | Utenti KeePass esistenti | `npm i -g kdbxweb argon2` (peer opzionali dalla v0.14.1), poi imposta `AQUAMAN_KEEPASS_PASSWORD` o un file di chiave |
| `1password` | Condivisione delle credenziali di team | `brew install 1password-cli && op signin`. Per agenti non presidiati usa un [service account](https://developer.1password.com/docs/service-accounts/) (`OP_SERVICE_ACCOUNT_TOKEN`) |
| `vault` | Gestione dei segreti aziendale | Imposta `VAULT_ADDR` + `VAULT_TOKEN` |
| `systemd-creds` | Linux con systemd ≥ 256 | Basato su TPM2, non richiede root |
| `bitwarden` | Utenti Bitwarden | `bw login && export BW_SESSION=$(bw unlock --raw)` |
| `keeper` | Utenti del gestore di password Keeper (v0.16.0+) | `pip install keepercommander`, accedi una volta con `keeper shell` e attiva `this-device persistent-login on`, crea una cartella per aquaman, poi `export AQUAMAN_KEEPER_FOLDER_UID=<folder UID>`. I record sono intitolati `aquaman::<service>::<key>` |
`aquaman setup` rileva automaticamente un valore predefinito sensato (macOS → `keychain`; Linux → `keychain` se libsecret, altrimenti `systemd-creds` se systemd ≥ 256, altrimenti `encrypted-file`).
`encrypted-file` è l'ultima risorsa per ambienti Linux/CI headless senza un keyring nativo. Per una maggiore sicurezza su Linux, installa `libsecret-1-dev` (GNOME Keyring), usa `systemd-creds` (binding TPM2) oppure usa 1Password/Vault.
### Caching delle credenziali (v0.13.1+)
I backend con un costo per accesso, come `1password` (un prompt biometrico per lettura in modalità app desktop), `bitwarden` (~1-2 s per l'avvio della CLI), `keeper` (un avvio di Commander che effettua il login e sincronizza) e `vault` (un round-trip HTTP), vengono memorizzati nella cache **in memoria del daemon** per 15 minuti per impostazione predefinita, così una sessione intensa di un agente sblocca il vault una volta per finestra invece che una volta per richiesta. Gli altri backend sono già veloci o memorizzano internamente, quindi per loro la cache è disattivata per impostazione predefinita. Regola con `credentials.cacheTtlSeconds` in `~/.aquaman/config.yaml` (o `AQUAMAN_CACHE_TTL`); `0` disabilita.
Il compromesso onesto: un prompt biometrico per accesso è un controllo di presenza dell'utente, e la cache rimuove la presenza per accesso per la finestra del TTL. Per gli agenti non presidiati quel prompt non riceve mai risposta, quindi il vault viene abbandonato in favore di un `.env` in chiaro, che è decisamente peggio. La cache **non** sposta il confine di isolamento: i valori vivono solo nel processo del proxy (dove già transitano a ogni richiesta), non vengono mai scritti su disco e vengono invalidati immediatamente quando ruoti tramite `aquaman credentials add`. Le scritture vanno sempre nel tuo vault. Testato per conformità in [`test/compliance/cache-residency.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/cache-residency.test.ts). Per zero prompt con 1Password, usa un service account con ambito limitato al vault `aquaman`; `aquaman doctor` ti indicherà la strada.
## Licenza
MIT - vedi [LICENSE](https://github.com/tech4242/aquaman/blob/main/LICENSE).