🔱 Le seul proxy d'identification indépendant pour les agents IA : isolement de type « apportez votre propre coffre » et politiques de requêtes de moindre privilège. Vos clés restent là où vous les conservez déjà, jamais dans la mémoire de l'agent. Compatible avec 1Password, keychain, keepassxc et bien d'autres.
# 🔱 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)
🔱 Le seul proxy d'identifiants indépendant pour agents IA : isolation bring-your-own-vault et politiques de requêtes à moindre privilège. Vos clés restent là où vous les conservez déjà, jamais dans la mémoire de l'agent. Compatible avec 1Password, keychain, keepassxc et bien d'autres.
Vous avez configuré Claude Code, Codex, OpenClaw, Hermes ou Docker Sandboxes, et vous voilà devant des fichiers `.env` avec vos précieuses clés API en clair. Vous avez lu les articles. Vous savez ce qui se passe quand un agent subit une injection de prompt. On comprend.
Aquaman règle ce problème avec trois couches de défense :
1. **Isolation des processus** : les clés API résident dans un processus proxy séparé qui les injecte à la sortie. L'agent détient un marqueur, jamais une clé, donc même une RCE dans l'agent ne peut pas en lire une. Les agents de codage ne reçoivent que les références que vous déclarez, une commande à la fois.
2. **Politiques de requêtes** : des règles par service contrôlent *quels endpoints* un agent peut appeler. Bloquez les API d'administration, empêchez les suppressions, autorisez les brouillons mais refusez les envois. Les requêtes refusées ne reçoivent jamais de vrais identifiants.
3. **Audit inviolable** : chaque utilisation d'identifiant est journalisée avec des chaînes de hachage SHA-256. Vous pouvez prouver ce qui a été consulté et détecter toute altération après coup.
## Choisissez votre parcours
Aquaman est livré sous forme de quatre paquets coordonnés, partageant un seul vault + un seul daemon. Installez uniquement ce dont vous avez besoin :
| Paquet | Ce qu'il fait | Quand l'installer |
|---|---|---|
| **[`aquaman-proxy`](https://github.com/tech4242/aquaman/blob/main/packages/proxy)** | Cœur : vault, daemon, audit, politique, CLI. La pièce dont tout le monde a besoin. | Toujours. |
| **[`aquaman-plugin`](https://github.com/tech4242/aquaman/blob/main/packages/plugin)** | Adaptateur OpenClaw Gateway. Lance le proxy au démarrage de la Gateway ; achemine le trafic modèle et Telegram à travers lui ; 25 services intégrés répartis sur 5 modes d'authentification. | Si vous exécutez une OpenClaw Gateway. Également disponible sur https://clawhub.ai/plugins/aquaman-plugin |
| **[`aquaman-coder`](https://github.com/tech4242/aquaman/blob/main/packages/coder)** | Adaptateur pour agent de codage IA. Références `aquaman://service/key` à portée projet, résolues à chaque appel de l'outil Bash. | Si vous utilisez Claude Code ou Codex. |
| **[`aquaman-hermes`](https://github.com/tech4242/aquaman/blob/main/packages/hermes)** | Plugin hôte d'agent Hermes (Python, sur PyPI). Pointe Hermes vers un listener loopback opt-in protégé par jeton via ses `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` natifs ; ajoute une commande `/aquaman-status` en session, un outil et une sonde de santé. L'isolation est côté proxy ; le plugin ne détient aucun identifiant. | Si vous exécutez l'hôte d'agent Hermes. `pip install aquaman-hermes` |
| **Docker Sandboxes** | Pas un paquet : un parcours séparé qui ne nécessite que `aquaman-proxy`. Le proxy propre à Docker injecte les secrets ; `aquaman get` les fournit depuis votre vault, avec la liste d'autorisation et le journal d'audit. | Si vous exécutez des agents dans Docker Sandboxes. Voir [Quick Start 5](#5-docker-sandboxes). |
Une seule CLI `aquaman` expose les quatre : commandes de premier niveau pour le vault et l'audit, `aquaman openclaw ...` pour l'intégration OpenClaw, `aquaman coder ...` pour l'intégration agent de codage (délègue à `aquaman-coder` en interne) ainsi que `aquaman hermes ...` pour le paquet Python Hermes.
## Quick Start
`aquaman help`, `aquaman doctor` sont vos amis.
### 1. Vault uniquement (juste le proxy + vos secrets)
```bash
npm install -g aquaman-proxy
aquaman setup # backend wizard + store keys
aquaman daemon & # start the proxy
aquaman credentials list # verify
```
Le proxy écoute sur `~/.aquaman/proxy.sock` (UDS, `chmod 0o600`). Pointez n'importe quel outil vers `http://aquaman.local/<service>/<path>` et le proxy injecte les en-têtes d'authentification pour ce service depuis le backend de coffre-fort que vous avez choisi.
### 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
```
Dépannage : `openclaw aquaman doctor`.
**Utiliser npm directement ?** `npm install -g aquaman-proxy && aquaman openclaw setup` fait la même chose - installe le CLI proxy, stocke vos clés, installe le plugin dans `~/.openclaw/extensions/aquaman-plugin/`, et configure les identifiants (références SecretRef sur OpenClaw ≥ 2026.6.5, l'espace réservé auth-profiles.json sur les versions plus anciennes).
`aquaman openclaw setup` pointe `models.providers.<svc>.baseUrl` et `channels.telegram.apiRoot` vers l'écouteur loopback du proxy, car le transport de modèle d'OpenClaw et ses canaux construisent chacun leur propre client HTTP et contournent l'intercepteur fetch. Les canaux autres que Telegram n'exposent aucune substitution de point de terminaison, donc leurs jetons sont stockés et migrés mais non injectés à la sortie (voir [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md)). Ajoutez des canaux sous la configuration du plugin dans `openclaw.json` ; les canaux pris en charge incluent Slack, Discord, Telegram, MS Teams, Matrix, LINE, Twitch, Twilio, BlueBubbles, Mattermost, Nostr, Tlon, Feishu, Google Chat, ElevenLabs, xAI, Cloudflare AI Gateway, Mistral, Hugging Face, et plus encore (25 au total).
### 3. Agents de codage IA (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
```
**Voyez-le par vous-même (le déclic en 30 secondes) :** redémarrez Claude Code (ou Codex), ouvrez une nouvelle session dans `~/code/my-app`, et demandez à l'agent d'exécuter :
```
printenv | grep ANTHROPIC_API_KEY
```
Vous verrez ceci dans la transcription :
```
ANTHROPIC_API_KEY=[REDACTED:injected-value]
⏺ ANTHROPIC_API_KEY is set and available (injected via aquaman vault).
```
Le processus *enfant* voyait la vraie clé (vos tests, builds, serveurs MCP, scripts d'import - tout ce qui en a réellement besoin fonctionne). L'*agent* - la chose qui décide quel code exécuter sur votre machine - ne voit jamais la valeur, et donc l'historique de conversation non plus, les journaux du fournisseur du modèle non plus, et personne qui prendra plus tard une capture d'écran de votre terminal non plus.
**Utilisez-le aussi depuis votre propre terminal.** Le même wrapper fonctionne sans l'agent. Faites simplement `cd` dans un projet couvert et préfixez votre commande :
```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py
```
Même injection d'env, même caviardage sur stdout/stderr. Déposez-le dans des cibles Makefile, des alias shell ou des runners CI - partout où vous utiliseriez autrement un fichier `.env`.
Lorsque Claude Code ou Codex exécute une commande shell dans `~/code/my-app`, le hook d'aquaman réécrit la commande via `updatedInput.command` pour l'envelopper sous `aquaman-coder exec`. Ce wrapper :
- Résout chaque référence `aquaman://service/key` via le broker (`POST /broker/resolve` sur UDS). Les identifiants sont matérialisés pour une commande, pas pour la durée de vie de l'agent.
- Fait transiter stdout/stderr par un caviardeur qui préfixe un motif basé sur la valeur pour chaque valeur résolue : **toute chaîne injectée est caviardée, quelle que soit sa forme** (jetons Atlassian, secrets Notion, clés d'API internes - aucun d'entre eux n'a besoin de correspondre à un format de fournisseur connu). Les motifs génériques basés sur la forme (sk-ant-, ghp_, sk_live_, AKIA…, JWT, blocs PEM, ATATT3xF…) s'exécutent toujours ensuite en défense en profondeur pour les secrets que le processus enfant expose et que nous n'avons PAS injectés.
- Nettoie à la sortie de la commande.
**Bac à sable Claude Code :** il bloque les sockets Unix par défaut, donc `aquaman coder setup claude-code` autorise le socket du proxy sur macOS (`sandbox.network.allowUnixSockets`). Linux et WSL2 ignorent cette liste, où la seule option est `sandbox.network.allowAllUnixSockets: true`, ce qui ouvre tous les sockets Unix aux commandes sandboxées.
**Codex :** approuvez les hooks aquaman dans la revue des hooks de démarrage de Codex après l'installation (Codex ignore les nouveaux hooks jusqu'à ce que vous leur fassiez confiance). Son bac à sable bloque également le socket du proxy par défaut ; `aquaman coder setup codex` affiche le profil de permissions `config.toml` qui l'autorise. Les hooks Codex ne peuvent pas réécrire la sortie shell, donc le caviardage se produit à l'intérieur de `aquaman-coder exec`. Détails dans [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md#codex).
### 4. Hermes (hôte d'agent)
Hermes est un hôte étranger (Python) sans hook de transport à injecter, donc l'isolation se fait côté proxy : le proxy expose un listener loopback opt-in protégé par jeton et Hermes y est pointé via ses propres variables d'environnement.
```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` active l'écouteur loopback, génère un jeton par installation et écrit un bloc géré par aquaman dans `~/.hermes/.env` (en respectant `HERMES_HOME`) : les variables natives `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` plus une api_key fictive égale au jeton. Hermes envoie le jeton comme clé de son fournisseur ; le proxy le retire, injecte votre véritable identifiant du coffre-fort et transmet en amont. Fournisseurs LLM uniquement (Anthropic, OpenAI) pour l'instant.
**Sucre en session optionnel** - le plugin Python ajoute une commande `/aquaman-status`, un outil `aquaman_status` et une sonde de santé au démarrage de session dans Hermes (ne détient aucun identifiant) :
```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
```
Le plugin enregistre également une **source de secrets** `aquaman` (Hermes ≥ 0.18.1) pour les secrets de projet comme `GITHUB_TOKEN`. Liez-les sous `secrets.aquaman.env` dans le `config.yaml` de Hermes, puis déclarez chaque réf avec `aquaman broker allow aquaman://github/token` (requis depuis la v0.15.0 ; `aquaman hermes doctor` liste celles que vous avez manquées). Contrairement aux clés LLM ci-dessus, ces valeurs entrent dans l'environnement de Hermes. Voir [`packages/hermes/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/hermes/README.md).
### 5. Docker Sandboxes
Docker Sandboxes garde déjà les identifiants hors du bac à sable : un proxy sur votre machine les injecte dans les requêtes, et l'agent à l'intérieur de la VM voit un espace réservé. Par défaut, les valeurs proviennent du trousseau de votre système d'exploitation. Pointez-les plutôt vers aquaman pour obtenir tous les coffres-forts pris en charge par aquaman, la liste d'autorisation des réf, et une entrée d'audit inviolable chaque fois que sbx lit un secret.
```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 exécute cette commande depuis son propre service en arrière-plan, qui n'a pas le `PATH` de votre shell, donc l'étape 5 stocke des chemins absolus. Répétez les étapes 4 et 5 pour chaque service utilisé par votre sandbox.
La même commande `aquaman get` fonctionne partout où un outil demande une commande qui affiche un secret : Codex (`model_providers.<id>.auth.command`), Claude Code (`apiKeyHelper`), les fournisseurs de secrets exec d'OpenClaw et les sources de secrets par commande d'Hermes.
## Comment ça fonctionne
```
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** : Les identifiants résident dans le backend de coffre-fort que vous exécutez déjà - pas de coffre-fort maison (Keychain, 1Password, HashiCorp Vault, Bitwarden, Keeper, KeePassXC, systemd-creds, fichier chiffré).
2. **Policy** : Le proxy vérifie la méthode + les règles de chemin *avant* de toucher aux identifiants. Les requêtes refusées reçoivent un `403`, jamais de vrais en-têtes d'authentification.
3. **Inject** : Le proxy recherche l'identifiant et ajoute l'en-tête d'authentification avant de transmettre. 25 services intégrés, 4 modes d'injection d'authentification (header, URL-path, HTTP Basic, OAuth) ; un 5e, `none`, est at-rest-only (le proxy rejette le trafic).
4. **Broker (coder, source de secrets Hermes, `aquaman get`)** : `POST /broker/resolve` matérialise un identifiant par appel d'outil, limité à l'environnement d'une seule commande. Seul `aquaman daemon` le sert, et uniquement pour les refs que vous avez déclarées (`projects.yaml` ou `aquaman broker allow`). Le proxy du plugin OpenClaw ne le sert jamais (v0.15.0+).
5. **Audit** : Chaque utilisation d'identifiant est journalisée avec des chaînes de hachage SHA-256.
Sur les chemins proxy, l'agent voit un point de terminaison local plus un marqueur : le placeholder `aquaman-proxy-managed`, ou le token loopback, qui ne fonctionne que contre votre proxy local. Jamais une vraie clé. Sur le chemin coder, la commande *enfant* reçoit les valeurs déclarées et l'agent voit une sortie expurgée.
## Modèle de sécurité
| Couche | Ce qu'elle fait | Ce qu'elle arrête |
|---|---|---|
| **Isolation de processus** | Identifiants dans un processus séparé, atteint via un socket Unix (`chmod 0o600`) ou un listener loopback protégé par token | Un agent compromis ne peut pas lire les clés proxifiées : espace d'adressage différent |
| **Portée du broker** | Seul `aquaman daemon` distribue des valeurs, et uniquement pour les refs que vous avez déclarées ; les proxys hébergés par OpenClaw ne le font jamais (v0.15.0+) | Un agent ne peut pas extraire des entrées de coffre-fort arbitraires via le socket |
| **Liste blanche de services** | `proxiedServices` contrôle quelles API l'agent peut atteindre | L'agent ne peut pas parler à des services que vous n'avez pas autorisés |
| **Politiques de requête** | Règles méthode + chemin par service, appliquées avant l'injection d'identifiant | L'agent peut atteindre Anthropic mais pas son API d'administration ; peut rédiger des e-mails mais pas les envoyer |
| **Piste d'audit** | Journaux à chaînes de hachage SHA-256 de chaque utilisation d'identifiant | Forensique post-incident, détection d'altération, preuves de conformité |
| **Broker par appel d'outil (coder)** | `aquaman-coder exec` matérialise les identifiants pour une commande à la fois | Les identifiants ne se dispersent pas dans l'environnement shell de l'agent |
| **Expurgation de sortie (coder)** | `aquaman-coder exec` fait passer stdout/stderr par un expurgateur qui efface chaque valeur qu'il vient d'injecter verbatim - plus des motifs génériques de fournisseurs en secours | Même des identifiants arbitraires et sans forme n'atteignent jamais la transcription de l'agent |
### Transports et contrôle d'accès
| Chemin | Transport | Contrôle d'accès |
|---|---|---|
| Agents de codage, tout client pouvant composer un socket | Socket Unix `~/.aquaman/proxy.sock` | Permissions de fichier (`0600`) : uniquement les processus s'exécutant sous votre identité |
| Hermes (v0.13.0+), trafic modèle et Telegram d'OpenClaw (v0.15.0+) | TCP loopback `127.0.0.1:<port>` | Token par installation, vérification à temps constant, bind loopback |
Hermes et OpenClaw construisent chacun leur propre client HTTP et ne peuvent pas composer un socket, ils utilisent donc le listener. Tout le reste utilise le socket.
Le token est une capacité à atteindre le proxy local, pas un identifiant. Généré par installation, stocké dans `~/.aquaman/config.yaml` (`0600`), envoyé par l'hôte comme sa clé API de fournisseur. Le proxy le vérifie, le retire, injecte votre vraie clé. Telegram n'a pas d'en-tête d'authentification, donc là le token voyage dans le segment de chemin `/bot<TOKEN>` à la place.
Compromis : tout processus local peut atteindre un port loopback, y compris d'autres utilisateurs, là où le `0600` du socket les exclut. Le token est la barrière à cet endroit, donc le listener reste désactivé jusqu'à ce que `aquaman hermes setup` ou `aquaman openclaw setup` l'active.
### Identifiants de canaux sur OpenClaw 2026.7.33+
| Canal | Sortie via le proxy |
|---|---|
| Telegram | Oui, depuis la v0.15.0 |
| Tout le reste | Non. Stockage en coffre-fort et migration uniquement |
Chaque canal construit son propre client HTTP par requête, donc l'intercepteur `fetch` du plugin ne voit plus le trafic des canaux sur ces versions. Router un canal nécessite une substitution de point de terminaison de la part de l'hôte, et Telegram est le seul à l'avoir : `aquaman openclaw setup` pointe `channels.telegram.apiRoot` vers le proxy et remplace le token du bot par le token loopback.
Pour le reste, votre token reste dans le coffre-fort mais OpenClaw l'utilise directement, donc le proxy n'est pas dans le chemin et ces appels ne sont pas audités. `aquaman openclaw doctor` liste lesquels de vos canaux configurés sont dans quel groupe. Les fournisseurs de modèles ne sont pas affectés.
**Ce que l'isolation même-utilisateur ne peut pas faire.** Le `0o600` du socket exclut les autres utilisateurs, pas les autres processus s'exécutant sous votre identité. Un tel processus peut envoyer des requêtes via le proxy pendant son exécution (limité par la politique de requête, enregistré dans le journal d'audit) et peut récupérer les refs que vous avez déclarées, ce qui est le sens de « déclarer ». Il ne peut pas lire les clés que le proxy injecte. Pour une frontière plus stricte, exécutez l'agent sous un autre utilisateur OS ou dans un bac à sable.
Le modèle détaillé - spécificités par intégration (portée de l'intercepteur HTTP, profils d'authentification, résultats de scanner, note de l'éditeur ClawScan) - se trouve dans [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md) et [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md).
### Posture de conformité
Aquaman fournit des tests de conformité exécutables sous `test/compliance/` mappés à :
- **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/`)
Plus des narratifs d'alignement pour CISA/Five-Eyes « Careful Adoption of Agentic AI Services » (avril 2026), CSA MAESTRO, et OWASP Top 10 for Agentic Applications. Les tests s'exécutent dans le cadre de `npm test`. Voir [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance) pour les mappings.
## Politiques de requête
Les scopes OAuth ne peuvent pas distinguer entre « rédiger un e-mail » et « envoyer un e-mail ». Les deux sont `gmail.send`. Les politiques de requête comblent cette lacune.
```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
```
- **Les chemins correspondent au chemin complet de l'API en amont** après le préfixe du service : l'API Web de Slack est `/api/<method>`, celle de Gmail est `/gmail/v1/...`. Les presets antérieurs à la v0.15.0 utilisaient `/admin.*` et `/v1/users/*/messages/send`, qui ne correspondaient jamais au trafic réel. `aquaman doctor` les signale s'ils sont encore dans votre configuration.
- **Pas de politique = tout autoriser** (rétrocompatible)
- **La première correspondance gagne** : les règles sont évaluées de haut en bas, les requêtes sans correspondance retombent sur `defaultAction`
- **Refus avant authentification** : les requêtes bloquées ne reçoivent jamais de vrais identifiants
- **Globs de chemin :** `*` correspond à l'intérieur d'un segment, `**` correspond à zéro ou plusieurs segments
- `aquaman setup` applique des valeurs par défaut sûres pour les services stockés (`anthropic`, `openai`, `slack`, `gmail`).
- `aquaman policy list` / `aquaman policy test <svc> <method> <path>` pour l'inspection / les essais à blanc.
## Backends d'identifiants
Apportez votre propre coffre - aquaman n'a pas de stockage interne. Choisissez le backend que vous utilisez déjà ; les secrets y restent, et le proxy les lit sur place.
| Backend | Idéal pour | Configuration |
|---|---|---|
| `keychain` | Développement local sur macOS (par défaut) | Fonctionne immédiatement |
| `encrypted-file` | Linux, WSL2, CI/CD | AES-256-GCM, protégé par mot de passe |
| `keepassxc` | Utilisateurs KeePass existants | `npm i -g kdbxweb argon2` (pairs optionnels depuis la v0.14.1), puis définissez `AQUAMAN_KEEPASS_PASSWORD` ou un fichier de clé |
| `1password` | Partage d'identifiants en équipe | `brew install 1password-cli && op signin`. Pour les agents non supervisés, utilisez un [compte de service](https://developer.1password.com/docs/service-accounts/) (`OP_SERVICE_ACCOUNT_TOKEN`) |
| `vault` | Gestion de secrets en entreprise | Définissez `VAULT_ADDR` + `VAULT_TOKEN` |
| `systemd-creds` | Linux avec systemd ≥ 256 | Adossé au TPM2, aucun accès root requis |
| `bitwarden` | Utilisateurs Bitwarden | `bw login && export BW_SESSION=$(bw unlock --raw)` |
| `keeper` | Utilisateurs du gestionnaire de mots de passe Keeper (v0.16.0+) | `pip install keepercommander`, connectez-vous une fois avec `keeper shell` et activez `this-device persistent-login on`, créez un dossier pour aquaman, puis `export AQUAMAN_KEEPER_FOLDER_UID=<folder UID>`. Les enregistrements sont intitulés `aquaman::<service>::<key>` |
`aquaman setup` détecte automatiquement une valeur par défaut pertinente (macOS → `keychain` ; Linux → `keychain` si libsecret, sinon `systemd-creds` si systemd ≥ 256, sinon `encrypted-file`).
`encrypted-file` est une solution de dernier recours pour les environnements Linux/CI sans interface graphique et sans trousseau natif. Pour une meilleure sécurité sous Linux, installez `libsecret-1-dev` (GNOME Keyring), utilisez `systemd-creds` (liaison TPM2), ou utilisez 1Password/Vault.
### Mise en cache des identifiants (v0.13.1+)
Les backends ayant un coût par accès, comme `1password` (une invite biométrique par lecture en mode application de bureau), `bitwarden` (~1-2 s de lancement du CLI), `keeper` (un lancement de Commander qui se connecte et se synchronise) et `vault` (un aller-retour HTTP), sont mis en cache **dans la mémoire du démon** pendant 15 minutes par défaut, de sorte qu'une session d'agent chargée ne déverrouille le coffre qu'une fois par fenêtre au lieu d'une fois par requête. Les autres backends sont déjà rapides ou mettent en cache en interne, donc la mise en cache est désactivée par défaut pour eux. Ajustez avec `credentials.cacheTtlSeconds` dans `~/.aquaman/config.yaml` (ou `AQUAMAN_CACHE_TTL`) ; `0` désactive.
Le compromis honnête : une invite biométrique par accès est une vérification de présence de l'utilisateur, et le cache supprime la présence par accès pendant la fenêtre du TTL. Pour les agents non supervisés, cette invite n'obtient jamais de réponse, donc le coffre est abandonné au profit d'un `.env` en clair, ce qui est strictement pire. Le cache ne déplace **pas** la frontière d'isolation : les valeurs ne vivent que dans le processus du proxy (où elles transitent déjà à chaque requête), ne sont jamais écrites sur disque, et sont invalidées immédiatement lorsque vous effectuez une rotation via `aquaman credentials add`. Les écritures vont toujours dans votre coffre. Testé de conformité dans [`test/compliance/cache-residency.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/cache-residency.test.ts). Pour zéro invite avec 1Password, utilisez un compte de service limité au coffre `aquaman` ; `aquaman doctor` vous y orientera.
## Licence
MIT - voir [LICENSE](https://github.com/tech4242/aquaman/blob/main/LICENSE).