🔱 O único proxy de credenciais independente para agentes de IA: isolamento bring-your-own-vault e políticas de requisição com privilégios mínimos. Suas chaves permanecem onde você já as mantém, nunca na memória do agente. Compatível com 1Password, keychain, keepassxc e muitos outros.
# 🔱 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)
🔱 O único proxy de credenciais independente para agentes de IA: isolamento bring-your-own-vault e políticas de requisição de privilégio mínimo. Suas chaves ficam onde você já as guarda, nunca na memória do agente. Compatível com 1Password, keychain, keepassxc e muitos outros.
Você configurou o Claude Code, Codex, OpenClaw, Hermes ou Docker Sandboxes, e agora está encarando arquivos `.env` com suas preciosas chaves de API expostas em texto puro. Você leu os artigos. Você sabe o que acontece quando um agente sofre prompt injection. Nós entendemos.
O Aquaman resolve isso com três camadas de defesa:
1. **Isolamento de processo**: as chaves de API ficam em um processo proxy separado que as injeta na saída. O agente carrega um marcador, nunca uma chave, então mesmo um RCE no agente não consegue lê-la. Agentes de codificação recebem apenas as referências que você declara, um comando por vez.
2. **Políticas de requisição**: regras por serviço controlam *quais endpoints* um agente pode chamar. Bloqueie APIs de administração, impeça exclusões, permita rascunhos mas negue envios. Requisições negadas nunca recebem credenciais reais.
3. **Auditoria à prova de adulteração**: cada uso de credencial é registrado com cadeias de hash SHA-256. Você pode provar o que foi acessado e detectar adulterações posteriormente.
## Escolha seu caminho
O Aquaman é distribuído como quatro pacotes coordenados, compartilhando um único vault + um único daemon. Instale apenas o que você precisa:
| Pacote | O que faz | Quando instalar |
|---|---|---|
| **[`aquaman-proxy`](https://github.com/tech4242/aquaman/blob/main/packages/proxy)** | Núcleo: vault, daemon, auditoria, política, CLI. A peça que todo mundo precisa. | Sempre. |
| **[`aquaman-plugin`](https://github.com/tech4242/aquaman/blob/main/packages/plugin)** | Adaptador do OpenClaw Gateway. Inicia o proxy na inicialização do Gateway; roteia tráfego de modelo e Telegram através dele; 25 serviços integrados em 5 modos de autenticação. | Se você executa um OpenClaw Gateway. Também disponível em https://clawhub.ai/plugins/aquaman-plugin |
| **[`aquaman-coder`](https://github.com/tech4242/aquaman/blob/main/packages/coder)** | Adaptador para agentes de codificação de IA. Referências `aquaman://service/key` com escopo de projeto resolvidas por chamada da ferramenta Bash. | Se você usa Claude Code ou Codex. |
| **[`aquaman-hermes`](https://github.com/tech4242/aquaman/blob/main/packages/hermes)** | Plugin de host de agente Hermes (Python, no PyPI). Aponta o Hermes para um listener loopback opt-in com token, através de suas variáveis nativas `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL`; adiciona um comando `/aquaman-status` em sessão, ferramenta e sonda de saúde. O isolamento é do lado do proxy; o plugin não guarda credenciais. | Se você executa o host de agente Hermes. `pip install aquaman-hermes` |
| **Docker Sandboxes** | Não é um pacote: um caminho separado que precisa apenas do `aquaman-proxy`. O próprio proxy do Docker injeta os segredos; o `aquaman get` os fornece a partir do seu vault, com a allow-list e o log de auditoria. | Se você executa agentes em Docker Sandboxes. Veja [Quick Start 5](#5-docker-sandboxes). |
Uma única CLI `aquaman` expõe todos os quatro: comandos de nível superior para vault e auditoria, `aquaman openclaw ...` para a integração com OpenClaw, `aquaman coder ...` para a integração com agentes de codificação (delegando ao `aquaman-coder` nos bastidores), bem como `aquaman hermes ...` para o pacote Python do Hermes.
## Quick Start
`aquaman help`, `aquaman doctor` são seus amigos.
### 1. Apenas o vault (somente o proxy + seus segredos)
```bash
npm install -g aquaman-proxy
aquaman setup # backend wizard + store keys
aquaman daemon & # start the proxy
aquaman credentials list # verify
```
O proxy escuta em `~/.aquaman/proxy.sock` (UDS, `chmod 0o600`). Aponte qualquer ferramenta para `http://aquaman.local/<service>/<path>` e o proxy injeta os cabeçalhos de autenticação para esse serviço a partir do backend de cofre escolhido.
### 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
```
Solução de problemas: `openclaw aquaman doctor`.
**Usando npm diretamente?** `npm install -g aquaman-proxy && aquaman openclaw setup` faz o mesmo - instala a CLI do proxy, armazena suas chaves, instala o plugin em `~/.openclaw/extensions/aquaman-plugin/` e configura as credenciais (refs SecretRef no OpenClaw ≥ 2026.6.5, o placeholder auth-profiles.json em versões mais antigas).
`aquaman openclaw setup` aponta `models.providers.<svc>.baseUrl` e `channels.telegram.apiRoot` para o listener de loopback do proxy, porque o transporte de modelo do OpenClaw e seus canais constroem cada um seu próprio cliente HTTP e ignoram o interceptor de fetch. Canais diferentes do Telegram não expõem substituição de endpoint, então seus tokens são armazenados e migrados, mas não injetados na saída (veja [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md)). Adicione canais sob a configuração do plugin em `openclaw.json`; os suportados incluem 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 mais (25 no total).
### 3. Agentes de codificação com 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
```
**Veja você mesmo (o momento "aha" de 30 segundos):** reinicie o Claude Code (ou o Codex), abra uma nova sessão dentro de `~/code/my-app` e peça ao agente para executar:
```
printenv | grep ANTHROPIC_API_KEY
```
Você verá isto na transcrição:
```
ANTHROPIC_API_KEY=[REDACTED:injected-value]
⏺ ANTHROPIC_API_KEY is set and available (injected via aquaman vault).
```
O processo *filho* viu a chave real (seus testes, builds, servidores MCP, scripts de importação - qualquer coisa que realmente precise dela funciona). O *agente* - a coisa que decide qual código executar na sua máquina - nunca vê o valor, e portanto nem o histórico da conversa, nem os logs do provedor do modelo, nem qualquer pessoa que depois tire um screenshot do seu terminal.
**Use também a partir do seu próprio terminal.** O mesmo wrapper funciona sem o agente. Basta fazer `cd` para um projeto coberto e prefixar o seu comando:
```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py
```
Mesma injeção de env, mesma redação em stdout/stderr. Coloque-o em alvos de Makefile, aliases de shell ou runners de CI - em qualquer lugar onde você, de outra forma, recorreria a um arquivo `.env`.
Quando o Claude Code ou o Codex executa um comando de shell em `~/code/my-app`, o hook do aquaman reescreve o comando via `updatedInput.command` para envolvê-lo sob `aquaman-coder exec`. Esse wrapper:
- Resolve cada referência `aquaman://service/key` via o broker (`POST /broker/resolve` sobre UDS). As credenciais são materializadas para um comando, não para o tempo de vida do agente.
- Canaliza stdout/stderr através de um redator que prefixa um padrão baseado em valor para cada valor resolvido: **qualquer string que foi injetada é redigida, independentemente da forma** (tokens do Atlassian, segredos do Notion, chaves de API internas - nenhum deles precisa corresponder a um formato de provedor conhecido). Padrões genéricos baseados em forma (sk-ant-, ghp_, sk_live_, AKIA…, JWTs, blocos PEM, ATATT3xF…) ainda são executados depois como defesa em profundidade para segredos que o filho expõe e que NÃO injetamos.
- Limpa quando o comando termina.
**Sandbox do Claude Code:** ele bloqueia sockets Unix por padrão, então `aquaman coder setup claude-code` permite o socket do proxy no macOS (`sandbox.network.allowUnixSockets`). Linux e WSL2 ignoram essa lista, onde a única opção é `sandbox.network.allowAllUnixSockets: true`, que abre todos os sockets Unix para comandos em sandbox.
**Codex:** aprove os hooks do aquaman na revisão de hooks de inicialização do Codex após a configuração (o Codex ignora novos hooks até que você confie neles). Seu sandbox também bloqueia o socket do proxy por padrão; `aquaman coder setup codex` imprime o perfil de permissões do `config.toml` que o permite. Os hooks do Codex não podem reescrever a saída do shell, então a redação acontece dentro de `aquaman-coder exec`. Detalhes em [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md#codex).
### 4. Hermes (host de agente)
Hermes é um host estrangeiro (Python) sem hook de transporte para injetar, então o isolamento é feito no lado do proxy: o proxy expõe um listener de loopback opcional, controlado por token, e o Hermes é apontado para ele através de suas próprias variáveis de 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` ativa o listener de loopback, gera um token por instalação e escreve um bloco gerenciado pelo aquaman em `~/.hermes/.env` (respeitando `HERMES_HOME`): o `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` nativo mais uma api_key placeholder igual ao token. O Hermes envia o token como sua chave de provedor; o proxy o remove, injeta sua credencial real do vault e encaminha para o upstream. Apenas provedores de LLM (Anthropic, OpenAI) atualmente.
**Açúcar opcional em sessão** - o plugin Python adiciona um comando `/aquaman-status`, uma ferramenta `aquaman_status` e uma verificação de integridade na inicialização da sessão dentro do Hermes (não mantém credenciais):
```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
```
O plugin também registra uma **secret source** `aquaman` (Hermes ≥ 0.18.1) para segredos de projeto como `GITHUB_TOKEN`. Vincule-os em `secrets.aquaman.env` no `config.yaml` do Hermes e, em seguida, declare cada ref com `aquaman broker allow aquaman://github/token` (obrigatório desde a v0.15.0; `aquaman hermes doctor` lista todos os que você deixou passar). Diferentemente das chaves de LLM acima, esses valores entram no env do Hermes. Consulte [`packages/hermes/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/hermes/README.md).
### 5. Docker Sandboxes
O Docker Sandboxes já mantém as credenciais fora do sandbox: um proxy na sua máquina as injeta nas requisições, e o agente dentro da VM vê um placeholder. Por padrão, os valores vêm do keychain do seu SO. Aponte-os para o aquaman em vez disso para obter todos os vaults suportados pelo aquaman, a allow-list de refs e uma entrada de auditoria à prova de adulteração cada vez que o sbx lê um segredo.
```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
```
O `sbx` executa esse comando a partir do seu próprio serviço em segundo plano, que não possui o `PATH` do seu shell, então o passo 5 armazena caminhos absolutos. Repita os passos 4 e 5 para cada serviço que seu sandbox utiliza.
O mesmo comando `aquaman get` funciona em qualquer lugar onde uma ferramenta solicite um comando que imprima um segredo: Codex (`model_providers.<id>.auth.command`), Claude Code (`apiKeyHelper`), provedores de segredos exec do OpenClaw e fontes de segredos por comando do Hermes.
## Como Funciona
```
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. **Armazenamento**: As credenciais residem no backend de cofre que você já executa - sem cofre próprio (Keychain, 1Password, HashiCorp Vault, Bitwarden, Keeper, KeePassXC, systemd-creds, arquivo criptografado).
2. **Política**: O proxy verifica as regras de método + caminho *antes* de tocar nas credenciais. Requisições negadas recebem um `403`, nunca cabeçalhos de autenticação reais.
3. **Injeção**: O proxy consulta a credencial e adiciona o cabeçalho de autenticação antes de encaminhar. 25 serviços integrados, 4 modos de injeção de autenticação (header, URL-path, HTTP Basic, OAuth); um 5º, `none`, é apenas em repouso (o proxy rejeita o tráfego).
4. **Broker (coder, fonte de segredos do Hermes, `aquaman get`)**: `POST /broker/resolve` materializa uma credencial por chamada de ferramenta, com escopo para o ambiente de um único comando. Apenas `aquaman daemon` o serve, e somente para refs que você declarou (`projects.yaml` ou `aquaman broker allow`). O proxy do plugin OpenClaw nunca o serve (v0.15.0+).
5. **Auditoria**: Todo uso de credencial é registrado com cadeias de hash SHA-256.
Nos caminhos do proxy, o agente vê um endpoint local mais um marcador: o placeholder `aquaman-proxy-managed`, ou o token de loopback, que só funciona contra o seu proxy local. Nunca uma chave real. No caminho do coder, o comando *filho* recebe os valores declarados e o agente vê a saída redigida.
## Modelo de Segurança
| Camada | O que faz | O que impede |
|---|---|---|
| **Isolamento de processo** | Credenciais em um processo separado, acessado por um socket Unix (`chmod 0o600`) ou um listener de loopback protegido por token | Agente comprometido não consegue ler chaves proxied: espaço de endereçamento diferente |
| **Escopo do broker** | Apenas `aquaman daemon` entrega valores, e somente para refs que você declarou; proxies hospedados no OpenClaw nunca o fazem (v0.15.0+) | Um agente não consegue puxar entradas arbitrárias do cofre pelo socket |
| **Allowlisting de serviços** | `proxiedServices` controla quais APIs o agente pode alcançar | O agente não consegue falar com serviços que você não autorizou |
| **Políticas de requisição** | Regras de método + caminho por serviço, aplicadas antes da injeção de credencial | O agente pode alcançar a Anthropic mas não sua API de administração; pode redigir e-mails mas não enviá-los |
| **Trilha de auditoria** | Logs encadeados por hash SHA-256 de todo uso de credencial | Forense pós-incidente, detecção de adulteração, evidência de conformidade |
| **Broker por chamada de ferramenta (coder)** | `aquaman-coder exec` materializa credenciais para um comando por vez | Credenciais não se espalham pelo ambiente de shell do agente |
| **Redação de saída (coder)** | `aquaman-coder exec` canaliza stdout/stderr por um redator que remove cada valor que acabou de injetar, literalmente - além de padrões genéricos de provedores como fallback | Mesmo credenciais arbitrárias e sem forma definida nunca chegam à transcrição do agente |
### Transportes e controle de acesso
| Caminho | Transporte | Controle de acesso |
|---|---|---|
| Agentes de codificação, qualquer cliente que consiga discar um socket | Socket Unix `~/.aquaman/proxy.sock` | Permissões de arquivo (`0600`): apenas processos executando como você |
| Hermes (v0.13.0+), tráfego de modelo e Telegram do OpenClaw (v0.15.0+) | Loopback TCP `127.0.0.1:<port>` | Token por instalação, verificação em tempo constante, bind em loopback |
Hermes e OpenClaw constroem cada um seu próprio cliente HTTP e não conseguem discar um socket, então usam o listener. Todo o resto usa o socket.
O token é uma capacidade de alcançar o proxy local, não uma credencial. Gerado por instalação, armazenado em `~/.aquaman/config.yaml` (`0600`), enviado pelo host como sua chave de API do provedor. O proxy o verifica, o remove, injeta sua chave real. O Telegram não tem cabeçalho de autenticação, então lá o token viaja no segmento de caminho `/bot<TOKEN>`.
Trade-off: qualquer processo local pode alcançar uma porta de loopback, incluindo outros usuários, onde o `0600` do socket os exclui. O token é o portão ali, então o listener permanece desligado até que `aquaman hermes setup` ou `aquaman openclaw setup` o ative.
### Credenciais de canal no OpenClaw 2026.7.33+
| Canal | Saída através do proxy |
|---|---|
| Telegram | Sim, desde v0.15.0 |
| Todo o resto | Não. Apenas armazenamento em cofre e migração |
Cada canal constrói seu próprio cliente HTTP por requisição, então o interceptor `fetch` do plugin não vê mais o tráfego de canal nessas versões. Rotear um canal requer uma substituição de endpoint pelo host, e o Telegram é o único que a possui: `aquaman openclaw setup` aponta `channels.telegram.apiRoot` para o proxy e substitui o token do bot pelo token de loopback.
Para o resto, seu token permanece no cofre mas o OpenClaw o usa diretamente, então o proxy não está no caminho e essas chamadas não são auditadas. `aquaman openclaw doctor` lista quais dos seus canais configurados estão em qual grupo. Provedores de modelo não são afetados.
**O que o isolamento de mesmo usuário não consegue fazer.** O `0o600` do socket mantém outros usuários fora, não outros processos executando como você. Tal processo pode enviar requisições através do proxy enquanto ele executa (limitado pela política de requisição, registrado no log de auditoria) e pode buscar refs que você declarou, que é o que declarar significa. Ele não consegue ler as chaves que o proxy injeta. Para uma fronteira mais rígida, execute o agente como um usuário de SO diferente ou em um sandbox.
Modelo detalhado - especificidades por integração (escopo do interceptor HTTP, perfis de autenticação, descobertas do scanner, nota do publicador ClawScan) - está em [`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 de conformidade
O Aquaman inclui testes de conformidade executáveis em `test/compliance/` mapeados para:
- **MITRE ATLAS** v5.4.0: técnicas 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/`)
Além de narrativas de alinhamento para CISA/Five-Eyes "Careful Adoption of Agentic AI Services" (abril de 2026), CSA MAESTRO e OWASP Top 10 for Agentic Applications. Os testes rodam como parte de `npm test`. Veja [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance) para os mapeamentos.
## Políticas de Requisição
Escopos OAuth não conseguem distinguir entre "redigir um e-mail" e "enviar um e-mail". Ambos são `gmail.send`. As políticas de requisição preenchem essa 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
```
- **Os caminhos são o caminho completo da API upstream** após o prefixo do serviço: a Web API do Slack é `/api/<method>`, a do Gmail é `/gmail/v1/...`. Presets anteriores à v0.15.0 usavam `/admin.*` e `/v1/users/*/messages/send`, que nunca correspondiam ao tráfego real. `aquaman doctor` sinaliza esses casos se ainda estiverem na sua configuração.
- **Sem política = permitir tudo** (compatível com versões anteriores)
- **A primeira correspondência vence**: as regras são avaliadas de cima para baixo, pedidos sem correspondência caem em `defaultAction`
- **Negado antes da autenticação**: pedidos bloqueados nunca recebem credenciais reais
- **Globs de caminho:** `*` corresponde dentro de um segmento, `**` corresponde a zero ou mais segmentos
- `aquaman setup` aplica predefinições seguras para serviços armazenados (`anthropic`, `openai`, `slack`, `gmail`).
- `aquaman policy list` / `aquaman policy test <svc> <method> <path>` para inspeção / simulações.
## Backends de Credenciais
Traga o seu próprio cofre - o aquaman não tem armazenamento próprio. Escolha o backend que já utiliza; os segredos ficam lá, e o proxy lê-os no local.
| Backend | Melhor Para | Configuração |
|---|---|---|
| `keychain` | Desenvolvimento local em macOS (predefinição) | Funciona imediatamente |
| `encrypted-file` | Linux, WSL2, CI/CD | AES-256-GCM, protegido por palavra-passe |
| `keepassxc` | Utilizadores existentes de KeePass | `npm i -g kdbxweb argon2` (peers opcionais desde a v0.14.1), depois defina `AQUAMAN_KEEPASS_PASSWORD` ou um ficheiro de chave |
| `1password` | Partilha de credenciais em equipa | `brew install 1password-cli && op signin`. Para agentes não assistidos use uma [conta de serviço](https://developer.1password.com/docs/service-accounts/) (`OP_SERVICE_ACCOUNT_TOKEN`) |
| `vault` | Gestão empresarial de segredos | Defina `VAULT_ADDR` + `VAULT_TOKEN` |
| `systemd-creds` | Linux com systemd ≥ 256 | Suportado por TPM2, não requer root |
| `bitwarden` | Utilizadores de Bitwarden | `bw login && export BW_SESSION=$(bw unlock --raw)` |
| `keeper` | Utilizadores do gestor de palavras-passe Keeper (v0.16.0+) | `pip install keepercommander`, inicie sessão uma vez com `keeper shell` e ative `this-device persistent-login on`, crie uma pasta para o aquaman, depois `export AQUAMAN_KEEPER_FOLDER_UID=<folder UID>`. Os registos têm o título `aquaman::<service>::<key>` |
`aquaman setup` deteta automaticamente uma predefinição sensata (macOS → `keychain`; Linux → `keychain` se libsecret, senão `systemd-creds` se systemd ≥ 256, senão `encrypted-file`).
`encrypted-file` é um último recurso para ambientes Linux/CI sem interface gráfica e sem keyring nativo. Para melhor segurança em Linux, instale `libsecret-1-dev` (GNOME Keyring), use `systemd-creds` (vinculação TPM2), ou use 1Password/Vault.
### Cache de credenciais (v0.13.1+)
Backends com um custo por acesso, como `1password` (um pedido biométrico por leitura em modo de aplicação de ambiente de trabalho), `bitwarden` (~1-2 s de arranque da CLI), `keeper` (um arranque do Commander que inicia sessão e sincroniza) e `vault` (uma ida e volta HTTP), são colocados em cache **na memória do daemon** durante 15 minutos por predefinição, para que uma sessão de agente ocupada desbloqueie o cofre uma vez por janela em vez de uma vez por pedido. Os outros backends já são rápidos ou fazem cache internamente, pelo que a cache está desativada para eles por predefinição. Ajuste com `credentials.cacheTtlSeconds` em `~/.aquaman/config.yaml` (ou `AQUAMAN_CACHE_TTL`); `0` desativa.
O compromisso honesto: um pedido biométrico por acesso é uma verificação de presença do utilizador, e a cache remove a presença por acesso durante a janela de TTL. Para agentes não assistidos esse pedido nunca é respondido, pelo que o cofre é abandonado em favor de um `.env` em texto simples, o que é estritamente pior. A cache **não** move a fronteira de isolamento: os valores vivem apenas no processo do proxy (onde já transitam em cada pedido), nunca são escritos em disco, e são invalidados imediatamente quando roda através de `aquaman credentials add`. As escritas vão sempre para o seu cofre. Testado quanto à conformidade em [`test/compliance/cache-residency.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/cache-residency.test.ts). Para zero pedidos com 1Password, use uma conta de serviço com âmbito no cofre `aquaman`; `aquaman doctor` irá indicar-lhe o caminho.
## Licença
MIT - consulte [LICENSE](https://github.com/tech4242/aquaman/blob/main/LICENSE).