🔱 Единственный независимый прокси-сервер учётных данных для AI-агентов: изоляция по принципу «принеси свой собственный сейф» и политики запросов с минимальными привилегиями. Ваши ключи остаются там, где вы их уже храните, и никогда не попадают в память агента. Совместим с 1Password, keychain, keepassxc и многими другими.
# 🔱 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)
🔱 Единственный независимый прокси для учётных данных AI-агентов: изоляция с собственным хранилищем секретов (bring-your-own-vault) и политики запросов по принципу наименьших привилегий. Ваши ключи остаются там, где вы их уже храните, и никогда не попадают в память агента. Совместим с 1Password, keychain, keepassxc и многими другими.
Вы настроили Claude Code, Codex, OpenClaw, Hermes или Docker Sandboxes, и теперь смотрите на файлы `.env`, где ваши драгоценные API-ключи лежат открытым текстом. Вы читали статьи. Вы знаете, что происходит, когда агент подвергается prompt injection. Мы понимаем.
Aquaman решает эту проблему с помощью трёх уровней защиты:
1. **Изоляция процессов**: API-ключи хранятся в отдельном процессе-прокси, который внедряет их на выходе. Агент держит только маркер, а не ключ, поэтому даже RCE в агенте не позволит прочитать ключ. Кодирующие агенты получают только те ссылки, которые вы объявили, по одной команде за раз.
2. **Политики запросов**: Правила для каждого сервиса контролируют, *к каким эндпоинтам* может обращаться агент. Блокируйте административные API, запрещайте удаления, разрешайте черновики, но запрещайте отправку. Отклонённые запросы никогда не получают реальных учётных данных.
3. **Аудит с защитой от подделки**: Каждое использование учётных данных регистрируется с помощью цепочек хешей SHA-256. Вы можете доказать, к чему был получен доступ, и обнаружить подделку постфактум.
## Выберите свой путь
Aquaman поставляется в виде четырёх согласованных пакетов, использующих одно хранилище + один демон. Устанавливайте только то, что вам нужно:
| Пакет | Что он делает | Когда устанавливать |
|---|---|---|
| **[`aquaman-proxy`](https://github.com/tech4242/aquaman/blob/main/packages/proxy)** | Ядро: хранилище, демон, аудит, политики, CLI. Часть, которая нужна всем. | Всегда. |
| **[`aquaman-plugin`](https://github.com/tech4242/aquaman/blob/main/packages/plugin)** | Адаптер для OpenClaw Gateway. Запускает прокси при старте Gateway; маршрутизирует трафик моделей и Telegram через него; 25 встроенных сервисов с 5 режимами аутентификации. | Если вы используете OpenClaw Gateway. Также доступен по адресу https://clawhub.ai/plugins/aquaman-plugin |
| **[`aquaman-coder`](https://github.com/tech4242/aquaman/blob/main/packages/coder)** | Адаптер для AI-агентов-кодеров. Ссылки `aquaman://service/key` в области проекта, разрешаемые при каждом вызове инструмента Bash. | Если вы используете Claude Code или Codex. |
| **[`aquaman-hermes`](https://github.com/tech4242/aquaman/blob/main/packages/hermes)** | Плагин для агент-хоста Hermes (Python, на PyPI). Направляет Hermes на опциональный loopback-слушатель с токен-гейтом через его нативные `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL`; добавляет внутрисессионную команду `/aquaman-status`, инструмент и проверку работоспособности. Изоляция на стороне прокси; плагин не хранит учётных данных. | Если вы используете агент-хост Hermes. `pip install aquaman-hermes` |
| **Docker Sandboxes** | Не пакет: отдельный путь, требующий только `aquaman-proxy`. Собственный прокси Docker внедряет секреты; `aquaman get` предоставляет их из вашего хранилища, с allow-list и журналом аудита. | Если вы запускаете агентов в Docker Sandboxes. См. [Quick Start 5](#5-docker-sandboxes). |
Единый CLI `aquaman` объединяет все четыре: команды верхнего уровня для хранилища и аудита, `aquaman openclaw ...` для интеграции с OpenClaw, `aquaman coder ...` для интеграции с агентами-кодерами (под капотом делегирует `aquaman-coder`), а также `aquaman hermes ...` для Python-пакета Hermes.
## Быстрый старт
`aquaman help`, `aquaman doctor` — ваши друзья.
### 1. Только хранилище (просто прокси + ваши секреты)
```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>`, и прокси внедрит заголовки аутентификации для этого сервиса из выбранного вами бэкенда хранилища.
### 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/` и прописывает учётные данные (ссылки SecretRef в OpenClaw ≥ 2026.6.5, заглушка auth-profiles.json в более старых версиях).
`aquaman openclaw setup` направляет `models.providers.<svc>.baseUrl` и `channels.telegram.apiRoot` на loopback-слушатель прокси, потому что транспорт моделей OpenClaw и его каналы каждый строят собственный HTTP-клиент и обходят перехватчик fetch. Каналы, отличные от Telegram, не предоставляют переопределения эндпоинта, поэтому их токены сохраняются и мигрируются, но не внедряются на исходящем трафике (см. [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/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, 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
```
**Убедитесь сами (озарение за 30 секунд):** перезапустите Claude Code (или Codex), откройте новую сессию внутри `~/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).
```
*Дочерний* процесс видел настоящий ключ (ваши тесты, сборки, MCP-серверы, скрипты импорта — всё, что действительно в нём нуждается, работает). *Агент* — то, что решает, какой код запускать на вашей машине, — никогда не видит значение, а значит, его не видит ни история диалога, ни логи провайдера модели, ни кто-либо, кто позже сделает скриншот вашего терминала.
**Используйте его и из собственного терминала.** Тот же wrapper работает и без агента. Просто выполните `cd` в покрытый проект и добавьте префикс к вашей команде:
```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py
```
Та же инъекция переменных окружения, та же редакция вывода stdout/stderr. Встраивайте это в цели Makefile, shell-алиасы или CI-раннеры — везде, где иначе вы бы обратились к файлу `.env`.
Когда Claude Code или Codex выполняет shell-команду в `~/code/my-app`, хук aquaman переписывает команду через `updatedInput.command`, оборачивая её в `aquaman-coder exec`. Эта обёртка:
- Разрешает каждую ссылку `aquaman://service/key` через брокер (`POST /broker/resolve` по UDS). Учётные данные материализуются для одной команды, а не на всё время жизни агента.
- Пропускает stdout/stderr через редактор, который добавляет шаблон на основе значения для каждого разрешённого значения: **любая строка, которая была внедрена, будет отредактирована, независимо от формы** (токены Atlassian, секреты Notion, ключи внутренних API — ни один из них не обязан соответствовать известному формату провайдера). Обобщённые шаблоны на основе формы (sk-ant-, ghp_, sk_live_, AKIA…, JWT, блоки PEM, ATATT3xF…) всё равно применяются после как эшелонированная защита для секретов, которые дочерний процесс выводит, но которые мы НЕ внедряли.
- Выполняет очистку при завершении команды.
**Песочница Claude Code:** по умолчанию она блокирует Unix-сокеты, поэтому `aquaman coder setup claude-code` добавляет прокси-сокет в белый список на macOS (`sandbox.network.allowUnixSockets`). Linux и WSL2 игнорируют этот список, где единственный вариант — `sandbox.network.allowAllUnixSockets: true`, что открывает все Unix-сокеты для команд в песочнице.
**Codex:** одобрите хуки aquaman в проверке хуков при запуске Codex после настройки (Codex пропускает новые хуки, пока вы не доверитесь им). Его песочница также по умолчанию блокирует прокси-сокет; `aquaman coder setup codex` выводит профиль разрешений `config.toml`, который его разрешает. Хуки Codex не могут переписывать вывод shell, поэтому редакция происходит внутри `aquaman-coder exec`. Подробности в [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md#codex).
### 4. Hermes (хост агента)
Hermes — это сторонний (Python) хост без транспортного хука для инъекции, поэтому изоляция выполняется на стороне прокси: прокси предоставляет опциональный, защищённый токеном loopback-слушатель, и Hermes направляется на него через свои собственные переменные окружения.
```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` включает loopback-слушатель, генерирует токен для каждой установки и записывает управляемый aquaman блок в `~/.hermes/.env` (с учётом `HERMES_HOME`): нативные `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` плюс placeholder 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
```
Плагин также регистрирует **источник секретов** `aquaman` (Hermes ≥ 0.18.1) для секретов проекта, таких как `GITHUB_TOKEN`. Привяжите их в разделе `secrets.aquaman.env` в `config.yaml` Hermes, затем объявите каждую ссылку с помощью `aquaman broker allow aquaman://github/token` (требуется начиная с v0.15.0; `aquaman hermes doctor` перечислит все пропущенные). В отличие от ключей LLM выше, эти значения действительно попадают в окружение Hermes. См. [`packages/hermes/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/hermes/README.md).
### 5. Docker Sandboxes
Docker Sandboxes уже не допускает учётные данные в песочницу: прокси на вашей машине внедряет их в запросы, а агент внутри виртуальной машины видит только заполнитель. По умолчанию значения берутся из связки ключей вашей ОС. Направьте их на aquaman вместо этого, чтобы получить все хранилища, поддерживаемые aquaman, список разрешённых ссылок и защищённую от подделки запись аудита при каждом чтении секрета в sbx.
```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 запускает эту команду из собственной фоновой службы, у которой нет `PATH` вашей оболочки, поэтому на шаге 5 сохраняются абсолютные пути. Повторите шаги 4 и 5 для каждой службы, которую использует ваша песочница.
Та же команда `aquaman get` работает везде, где инструмент запрашивает команду, выводящую секрет: Codex (`model_providers.<id>.auth.command`), Claude Code (`apiKeyHelper`), провайдеры секретов exec в OpenClaw и источники секретов команд в Hermes.
## Как это работает
```
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. **Хранилище**: Учётные данные хранятся в том бэкенде хранилища, который вы уже используете — никакого собственного хранилища (Keychain, 1Password, HashiCorp Vault, Bitwarden, Keeper, KeePassXC, systemd-creds, encrypted-file).
2. **Политика**: Прокси проверяет правила метода + пути *до* обращения к учётным данным. Отклонённые запросы получают `403`, а не реальные заголовки аутентификации.
3. **Инъекция**: Прокси находит учётные данные и добавляет заголовок аутентификации перед пересылкой. 25 встроенных сервисов, 4 режима инъекции аутентификации (header, URL-path, HTTP Basic, OAuth); пятый, `none`, только для хранения в покое (прокси отклоняет трафик).
4. **Брокер (coder, источник секретов Hermes, `aquaman get`)**: `POST /broker/resolve` материализует учётные данные для каждого вызова инструмента, ограничивая их окружением одной команды. Их выдаёт только `aquaman daemon`, и только для объявленных вами ссылок (`projects.yaml` или `aquaman broker allow`). Прокси плагина OpenClaw их никогда не выдаёт (v0.15.0+).
5. **Аудит**: Каждое использование учётных данных регистрируется в журнале с цепочками хешей SHA-256.
На путях через прокси агент видит локальную конечную точку плюс маркер: плейсхолдер `aquaman-proxy-managed` или loopback-токен, который работает только с вашим локальным прокси. Никогда — реальный ключ. На пути coder *дочерняя* команда получает объявленные значения, а агент видит отредактированный вывод.
## Модель безопасности
| Уровень | Что делает | Что останавливает |
|---|---|---|
| **Изоляция процессов** | Учётные данные в отдельном процессе, доступном через Unix-сокет (`chmod 0o600`) или привязанный к loopback слушатель с токеном | Скомпрометированный агент не может прочитать проксируемые ключи: другое адресное пространство |
| **Область брокера** | Только `aquaman daemon` выдаёт значения, и только для объявленных вами ссылок; прокси, размещённые в OpenClaw, никогда этого не делают (v0.15.0+) | Агент не может вытащить произвольные записи хранилища через сокет |
| **Белый список сервисов** | `proxiedServices` управляет тем, к каким API может обращаться агент | Агент не может обращаться к сервисам, которые вы не авторизовали |
| **Политики запросов** | Правила метода + пути для каждого сервиса, применяемые до инъекции учётных данных | Агент может обращаться к Anthropic, но не к его admin API; может создавать черновики писем, но не отправлять их |
| **Журнал аудита** | Журналы каждого использования учётных данных с цепочками хешей SHA-256 | Пост-инцидентная криминалистика, обнаружение подделки, доказательства соответствия |
| **Брокер на каждый вызов инструмента (coder)** | `aquaman-coder exec` материализует учётные данные для одной команды за раз | Учётные данные не расползаются по окружению оболочки агента |
| **Редактирование вывода (coder)** | `aquaman-coder exec` пропускает stdout/stderr через редактор, который дословно вычищает каждое только что внедрённое значение — плюс обобщённые шаблоны провайдеров как запасной вариант | Даже произвольные учётные данные без чёткой формы никогда не попадают в транскрипт агента |
### Транспорты и контроль доступа
| Путь | Транспорт | Контроль доступа |
|---|---|---|
| Агенты для кодинга, любой клиент, способный подключиться к сокету | Unix-сокет `~/.aquaman/proxy.sock` | Права доступа к файлу (`0600`): только процессы, запущенные от вашего имени |
| Hermes (v0.13.0+), трафик модели и Telegram OpenClaw (v0.15.0+) | Loopback TCP `127.0.0.1:<port>` | Токен для каждой установки, проверка с постоянным временем, привязка к loopback |
Hermes и OpenClaw каждый создают собственный HTTP-клиент и не могут подключиться к сокету, поэтому они используют слушатель. Всё остальное использует сокет.
Токен — это возможность доступа к локальному прокси, а не учётные данные. Генерируется при каждой установке, хранится в `~/.aquaman/config.yaml` (`0600`), отправляется хостом как его api key провайдера. Прокси проверяет его, удаляет, внедряет ваш реальный ключ. У Telegram нет заголовка аутентификации, поэтому там токен передаётся в сегменте пути `/bot<TOKEN>`.
Компромисс: любой локальный процесс может достичь loopback-порта, включая других пользователей, тогда как `0600` сокета закрывает им доступ. Токен здесь служит воротами, поэтому слушатель остаётся выключенным, пока `aquaman hermes setup` или `aquaman openclaw setup` не включит его.
### Учётные данные каналов в OpenClaw 2026.7.33+
| Канал | Исходящий трафик через прокси |
|---|---|
| Telegram | Да, начиная с v0.15.0 |
| Всё остальное | Нет. Только хранение в хранилище и миграция |
Каждый канал создаёт собственный HTTP-клиент для каждого запроса, поэтому перехватчик `fetch` плагина больше не видит трафик каналов в этих версиях. Для маршрутизации канала требуется переопределение конечной точки от хоста, и только у Telegram оно есть: `aquaman openclaw setup` направляет `channels.telegram.apiRoot` на прокси и заменяет токен бота на loopback-токен.
Для остальных ваш токен остаётся в хранилище, но OpenClaw использует его напрямую, поэтому прокси не находится на пути и эти вызовы не аудируются. `aquaman openclaw doctor` показывает, какие из ваших настроенных каналов в какой группе. Провайдеры моделей не затронуты.
**Чего не может изоляция в пределах одного пользователя.** `0o600` сокета не пускает других пользователей, но не другие процессы, запущенные от вашего имени. Такой процесс может отправлять запросы через прокси, пока он работает (в пределах политики запросов, с записью в журнал аудита), и может получать объявленные вами ссылки — это и означает «объявить». Он не может прочитать ключи, которые внедряет прокси. Для более жёсткой границы запускайте агента от имени другого пользователя ОС или в песочнице.
Подробная модель — особенности каждой интеграции (область перехватчика HTTP, профили аутентификации, находки сканера, примечание издателя ClawScan) — описана в [`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).
### Соответствие требованиям
Aquaman поставляет запускаемые тесты соответствия в `test/compliance/`, сопоставленные с:
- **MITRE ATLAS** v5.4.0: техники 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» (апрель 2026), CSA MAESTRO и OWASP Top 10 for Agentic Applications. Тесты запускаются в рамках `npm test`. См. [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance) для сопоставлений.
## Политики запросов
Области OAuth не могут отличить «создать черновик письма» от «отправить письмо». Оба — `gmail.send`. Политики запросов восполняют этот пробел.
```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
```
- **Пути — это полный путь upstream API** после префикса сервиса: Web API Slack — `/api/<method>`, Gmail — `/gmail/v1/...`. Пресеты до v0.15.0 использовали `/admin.*` и `/v1/users/*/messages/send`, которые никогда не совпадали с реальным трафиком. `aquaman doctor` помечает их, если они всё ещё в вашей конфигурации.
- **Нет политики = разрешить всё** (обратная совместимость)
- **Первое совпадение побеждает**: правила вычисляются сверху вниз, несовпавшие запросы переходят к `defaultAction`
- **Запрет до аутентификации**: заблокированные запросы никогда не получают реальные учётные данные
- **Глобы путей:** `*` совпадает в пределах сегмента, `**` совпадает с нулём или более сегментов
- `aquaman setup` применяет безопасные значения по умолчанию для хранимых сервисов (`anthropic`, `openai`, `slack`, `gmail`).
- `aquaman policy list` / `aquaman policy test <svc> <method> <path>` для проверки / пробных запусков.
## Бэкенды учётных данных
Принесите свой vault — у aquaman нет собственного хранилища. Выберите бэкенд, который вы уже используете; секреты остаются там, а прокси читает их на месте.
| Бэкенд | Лучше всего подходит для | Настройка |
|---|---|---|
| `keychain` | Локальная разработка на macOS (по умолчанию) | Работает из коробки |
| `encrypted-file` | Linux, WSL2, CI/CD | AES-256-GCM, защищён паролем |
| `keepassxc` | Существующие пользователи KeePass | `npm i -g kdbxweb argon2` (опциональные peer-зависимости с v0.14.1), затем задайте `AQUAMAN_KEEPASS_PASSWORD` или файл ключа |
| `1password` | Совместное использование учётных данных командой | `brew install 1password-cli && op signin`. Для необслуживаемых агентов используйте [сервисный аккаунт](https://developer.1password.com/docs/service-accounts/) (`OP_SERVICE_ACCOUNT_TOKEN`) |
| `vault` | Корпоративное управление секретами | Задайте `VAULT_ADDR` + `VAULT_TOKEN` |
| `systemd-creds` | Linux с systemd ≥ 256 | На базе TPM2, root не требуется |
| `bitwarden` | Пользователи Bitwarden | `bw login && export BW_SESSION=$(bw unlock --raw)` |
| `keeper` | Пользователи менеджера паролей Keeper (v0.16.0+) | `pip install keepercommander`, войдите один раз через `keeper shell` и включите `this-device persistent-login on`, создайте папку для aquaman, затем `export AQUAMAN_KEEPER_FOLDER_UID=<folder UID>`. Записи называются `aquaman::<service>::<key>` |
`aquaman setup` автоматически определяет разумное значение по умолчанию (macOS → `keychain`; Linux → `keychain`, если есть libsecret, иначе `systemd-creds`, если systemd ≥ 256, иначе `encrypted-file`).
`encrypted-file` — крайняя мера для headless-сред Linux/CI без нативного keyring. Для лучшей безопасности на Linux установите `libsecret-1-dev` (GNOME Keyring), используйте `systemd-creds` (привязка к TPM2) или используйте 1Password/Vault.
### Кэширование учётных данных (v0.13.1+)
Бэкенды с затратами на каждое обращение, такие как `1password` (биометрический запрос на каждое чтение в режиме десктопного приложения), `bitwarden` (~1-2 с на запуск CLI), `keeper` (запуск Commander, который выполняет вход и синхронизацию) и `vault` (HTTP-обмен), кэшируются **в памяти демона** на 15 минут по умолчанию, так что занятая сессия агента разблокирует vault один раз за окно, а не один раз за запрос. Остальные бэкенды уже быстрые или кэшируют внутри себя, поэтому для них кэширование по умолчанию отключено. Настройте через `credentials.cacheTtlSeconds` в `~/.aquaman/config.yaml` (или `AQUAMAN_CACHE_TTL`); `0` отключает.
Честный компромисс: биометрический запрос на каждое обращение — это проверка присутствия пользователя, а кэш убирает присутствие на каждое обращение в течение окна TTL. Для необслуживаемых агентов на этот запрос никогда не отвечают, поэтому vault забрасывается ради plaintext `.env`, что строго хуже. Кэш **не** сдвигает границу изоляции: значения живут только в процессе прокси (где они и так проходят при каждом запросе), никогда не записываются на диск и немедленно инвалидируются, когда вы выполняете ротацию через `aquaman credentials add`. Записи всегда идут в ваш vault. Проверено на соответствие в [`test/compliance/cache-residency.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/cache-residency.test.ts). Для нуля запросов с 1Password используйте сервисный аккаунт, ограниченный vault `aquaman`; `aquaman doctor` укажет вам туда.
## Лицензия
MIT — см. [LICENSE](https://github.com/tech4242/aquaman/blob/main/LICENSE).