🔱 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をセットアップして、大事なAPIキーが平文で置かれた`.env`ファイルを眺めている――そんな状況ではありませんか。あの記事を読んだはずです。エージェントがプロンプトインジェクションを受けたときに何が起きるか、ご存じのはずです。私たちも承知しています。
Aquamanはこれを3層の防御で解決します：
1. **プロセス分離**：APIキーは別のプロキシプロセスに存在し、送信時に注入されます。エージェントが保持するのはマーカーであり、キーそのものではありません。そのため、エージェント内でRCEが発生してもキーを読み取ることはできません。コーディングエージェントは、あなたが宣言した参照だけを、一度に1コマンドずつ取得します。
2. **リクエストポリシー**：サービスごとのルールが、エージェントが*どのエンドポイント*を呼び出せるかを制御します。管理APIをブロックし、削除を防ぎ、下書きは許可しつつ送信は拒否する――といったことが可能です。拒否されたリクエストに本物のクレデンシャルが渡ることはありません。
3. **改ざん検知可能な監査**：すべてのクレデンシャル使用はSHA-256ハッシュチェーンで記録されます。何がアクセスされたかを証明でき、事後に改ざんを検知できます。
## パスを選ぶ
Aquamanは4つの連携パッケージとして提供され、1つのvaultと1つのdaemonを共有します。必要なものだけをインストールしてください：
| パッケージ | 機能 | インストールすべき場合 |
|---|---|---|
| **[`aquaman-proxy`](https://github.com/tech4242/aquaman/blob/main/packages/proxy)** | コア：vault、daemon、監査、ポリシー、CLI。誰もが必要とする部分。 | 常に。 |
| **[`aquaman-plugin`](https://github.com/tech4242/aquaman/blob/main/packages/plugin)** | OpenClaw Gatewayアダプター。Gateway起動時にプロキシを起動し、モデルとTelegramのトラフィックをプロキシ経由でルーティングします。5つの認証モードにまたがる25の組み込みサービス。 | 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を、ネイティブの`ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL`経由で、オプトインのトークンゲート付きループバックリスナーに向けます。セッション内`/aquaman-status`コマンド、ツール、ヘルスプローブを追加します。分離はプロキシ側で行われ、プラグインはクレデンシャルを保持しません。 | Hermesエージェントホストを運用している場合。`pip install aquaman-hermes` |
| **Docker Sandboxes** | パッケージではありません：`aquaman-proxy`のみを必要とする別のパスです。Docker自身のプロキシがシークレットを注入し、`aquaman get`があなたのvaultからそれらを供給します。許可リストと監査ログ付き。 | Docker Sandboxesでエージェントを運用している場合。[クイックスタート5](#5-docker-sandboxes)を参照。 |
単一の`aquaman` CLIがこれら4つすべてを表面化します：vaultと監査用のトップレベルコマンド、OpenClaw統合用の`aquaman openclaw ...`、コーディングエージェント統合用の`aquaman coder ...`（内部で`aquaman-coder`に委譲）、そしてHermes Pythonパッケージ用の`aquaman hermes ...`です。
## クイックスタート
`aquaman help`、`aquaman doctor`が頼りになります。
### 1. Vaultのみ（プロキシ + あなたのシークレットだけ）
```bash
npm install -g aquaman-proxy
aquaman setup # backend wizard + store keys
aquaman daemon & # start the proxy
aquaman credentials list # verify
```
プロキシは `~/.aquaman/proxy.sock`（UDS、`chmod 0o600`）で待ち受けます。任意のツールを `http://aquaman.local/<service>/<path>` に向けると、プロキシが選択した vault バックエンドからそのサービス用の認証ヘッダーを注入します。
### 2. OpenClaw Gateway
```bash
openclaw plugins install aquaman-plugin # 1. install plugin + proxy
openclaw aquaman setup # 2. backend + keys + plugin wire-up
openclaw # 3. done - proxy starts automatically
```
トラブルシューティング: `openclaw aquaman doctor`。
**npm を直接使いますか?** `npm install -g aquaman-proxy && aquaman openclaw setup` も同じことを行います - プロキシ CLI をインストールし、キーを保存し、プラグインを `~/.openclaw/extensions/aquaman-plugin/` にインストールし、認証情報を配線します (OpenClaw ≥ 2026.6.5 では SecretRef 参照、古いバージョンでは auth-profiles.json プレースホルダー)。
`aquaman openclaw setup` は `models.providers.<svc>.baseUrl` と `channels.telegram.apiRoot` をプロキシのループバックリスナーに向けます。なぜなら OpenClaw のモデルトランスポートとそのチャネルはそれぞれ独自の HTTP クライアントを構築し、fetch インターセプターをバイパスするからです。Telegram 以外のチャネルはエンドポイントのオーバーライドを公開していないため、それらのトークンは保存および移行されますが、egress 時に注入されません ([`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サーバー、インポートスクリプトなど、実際にキーを必要とするものはすべて動作します）。*エージェント*、つまりあなたのマシンでどのコードを実行するかを決定するものは、その値を決して見ることはなく、したがって会話履歴も、モデルプロバイダーのログも、後であなたのターミナルをスクリーンショットする誰も見ることはありません。
**自分のターミナルからも使えます。** 同じラッパーはエージェントなしでも動作します。対象のプロジェクトに `cd` して、コマンドの前にプレフィックスを付けるだけです：
```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py
```
同じ環境変数注入、同じ stdout/stderr の秘匿化。Makefile のターゲット、シェルエイリアス、CI ランナーなど、通常 `.env` ファイルに手を伸ばすあらゆる場所にこれを組み込めます。
Claude Code や Codex が `~/code/my-app` でシェルコマンドを実行すると、aquaman のフックが `updatedInput.command` を介してコマンドを書き換え、`aquaman-coder exec` の下にラップします。このラッパーは:
- 各 `aquaman://service/key` 参照をブローカー経由（UDS 上の `POST /broker/resolve`）で解決します。認証情報はエージェントの生存期間ではなく、1 つのコマンドのために実体化されます。
- 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:** セットアップ後、Codex の起動時フックレビューで aquaman フックを承認してください（Codex は信頼するまで新しいフックをスキップします）。そのサンドボックスもデフォルトでプロキシソケットをブロックしますが、`aquaman coder setup codex` がそれを許可する `config.toml` のパーミッションプロファイルを出力します。Codex のフックはシェル出力を書き換えられないため、秘匿化は `aquaman-coder exec` の内部で行われます。詳細は [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md#codex) を参照してください。
### 4. Hermes（エージェントホスト）
Hermes は注入するトランスポートフックを持たない外部（Python）ホストであるため、分離はプロキシ側で行われます: プロキシはオプトインのトークンゲート付きループバックリスナーを公開し、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` はループバックリスナーを有効化し、インストールごとのトークンを生成し、aquaman 管理のブロックを `~/.hermes/.env` に書き込みます（`HERMES_HOME` を尊重）：ネイティブの `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` に加えて、トークンと等しいプレースホルダーの api_key です。Hermes はこのトークンをプロバイダーキーとして送信し、プロキシはそれを除去して、実際の vault 認証情報を注入し、上流へ転送します。現在は LLM プロバイダー（Anthropic、OpenAI）のみです。
**オプションのセッション内シュガー** - Python プラグインは `/aquaman-status` コマンド、`aquaman_status` ツール、および Hermes 内でのセッション開始時のヘルスプローブを追加します（認証情報は保持しません）：
```bash
pip install aquaman-hermes # or: uv tool install aquaman-hermes
aquaman-hermes install # drops the plugin into ~/.hermes/plugins/aquaman/
hermes plugins enable aquaman
```
プラグインはまた、`GITHUB_TOKEN` のようなプロジェクトシークレット用の `aquaman` **シークレットソース**（Hermes ≥ 0.18.1）を登録します。これらを Hermes の `config.yaml` 内の `secrets.aquaman.env` の下にバインドし、各 ref を `aquaman broker allow aquaman://github/token` で宣言します（v0.15.0 以降で必須。`aquaman hermes doctor` は見落としたものを一覧表示します）。上記の LLM キーとは異なり、これらの値は Hermes の env に入ります。詳細は [`packages/hermes/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/hermes/README.md) を参照してください。
### 5. Docker Sandboxes
Docker Sandboxes はすでに認証情報をサンドボックスの外に保っています。マシン上のプロキシがリクエストにそれらを注入し、VM 内のエージェントはプレースホルダーを見ます。デフォルトでは値は OS のキーチェーンから取得されます。代わりにそれらを aquaman に向けることで、aquaman がサポートするすべての vault、ref 許可リスト、そして 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`)、OpenClaw exec secret providers、Hermes command secret sources。
## 仕組み
```
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、暗号化ファイル）は不要です。
2. **ポリシー**：プロキシは認証情報に触れる前にメソッドとパスのルールをチェックします。拒否されたリクエストには `403` が返され、実際の認証ヘッダーが送信されることはありません。
3. **注入**：プロキシは認証情報を参照し、転送する前に認証ヘッダーを追加します。組み込みサービスは25種類、認証モードは4つ（header、URL-path、HTTP Basic、OAuth）用意されており、5つ目の `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` プレースホルダー、またはループバックトークン）のみを確認できます。このトークンはローカルプロキシに対してのみ機能し、実際のキーが露出することはありません。コード生成（coder）パスの場合、*子*プロセスが宣言された値を受け取り、エージェントには伏字処理された出力が表示されます。
## セキュリティモデル
| レイヤー | 機能 | 防止対象 |
|---|---|---|
| **プロセス分離** | 認証情報を別プロセスに格納し、Unix ソケット（`chmod 0o600`）またはトークン管理のループバックリスナー経由でアクセス | 侵害されたエージェントからプロキシ経由のキーを読み取れない：異なるアドレス空間 |
| **ブローカーのスコープ** | 値の配布は `aquaman daemon` のみが行い、宣言した参照先のみを対象とする；OpenClaw ホスト型プロキシは行わない（v0.15.0以降） | エージェントがソケット経由で任意のバックエンドエントリを取得できない |
| **サービスのホワイトリスト** | `proxiedServices` でエージェントが到達可能な API を制御 | エージェントが承認していないサービスと通信できない |
| **リクエストポリシー** | サービスごとにメソッドとパスのルールを設定し、認証情報注入前に適用 | エージェントは Anthropic に到達できるが管理用 API にはアクセス不可、メールの下書きは作成できるが送信は不可 |
| **監査証跡** | 認証情報の使用履歴を SHA-256 ハッシュチェーンで記録 | インシデント後のフォレンジック、改ざん検知、コンプライアンス証拠 |
| **ツール呼び出しごとのブローカー（coder）** | `aquaman-coder exec` は一度に1つのコマンド用に認証情報を生成 | 認証情報がエージェントのシェル環境全体に拡散しない |
| **出力の伏字処理（coder）** | `aquaman-coder exec` は stdout/stderr をフィルターに通し、直前に注入した値をそのまま除去する - 代替として汎用プロバイダーパターンも適用 | 形式が決まらない任意の認証情報でも、エージェントのトランスクリプトに漏洩しない |
### トランスポートとアクセス制御
| パス | トランスポート | アクセス制御 |
|---|---|---|
| コーディングエージェント、ソケット接続が可能なすべてのクライアント | Unix ソケット `~/.aquaman/proxy.sock` | ファイル権限（`0600`）：自分自身で実行されているプロセスのみ |
| Hermes（v0.13.0以降）、OpenClaw モデルおよび Telegram トラフィック（v0.15.0以降） | ループバック TCP `127.0.0.1:<port>` | インストールごとのトークン、定数時間チェック、ループバックバインド |
Hermes と OpenClaw はそれぞれ独自の HTTP クライアントを構築しており、ソケット接続ができないため、リスナーを使用します。それ以外はすべてソケットを使用します。
トークンはローカルプロキシへの到達権限であり、認証情報ではありません。インストールごとに生成され、`~/.aquaman/config.yaml`（`0600`）に保存され、ホスト側からプロバイダー API キーとして送信されます。プロキシはこれを検証し、削除してから実際のキーを注入します。Telegram には認証ヘッダーがないため、その場合はトークンを `/bot<TOKEN>` パスセグメント内で伝送します。
トレードオフ：ループバックポートには他のユーザーを含むすべてのローカルプロセスから到達可能ですが、ソケットの `0600` 権限ではこれを遮断します。トークンがそこでゲート役割を果たすため、リスナーは `aquaman hermes setup` または `aquaman openclaw setup` で有効になるまでオフのままになります。
### OpenClaw 2026.7.33 以降のチャンネル認証情報
| チャンネル | プロキシ経由の送信 |
|---|---|
| Telegram | はい、v0.15.0 から |
| その他 | いいえ。バックエンドの保存と移行のみ |
各チャンネルはリクエストごとに独自の HTTP クライアントを構築するため、これらのバージョンではプラグインの `fetch` インターセプターがチャンネルトラフィックを認識できなくなります。チャンネルのルーティングにはホストからのエンドポイントオーバーライドが必要であり、Telegram のみがこれに対応しています：`aquaman openclaw setup` は `channels.telegram.apiRoot` をプロキシに向け、ボットトークンをループバックトークンに置き換えます。
それ以外の場合、トークンはバックエンドに保持されたまま OpenClaw が直接使用するため、プロキシは経路に含まれず、それらの呼び出しは監査されません。`aquaman openclaw doctor` は、設定済みのチャンネルがどのグループに属するかを一覧表示します。モデルプロバイダーへの影響はありません。
**同一ユーザー分離で実現できないこと**。ソケットの `0o600` は他のユーザーを遮断しますが、同じユーザーで実行されている他のプロセスまでは遮断しません。そのようなプロセスは実行中にプロキシ経由でリクエストを送信可能ですが（リクエストポリシーで制限され、監査ログに記録）、宣言した参照先を取得することは可能です（これが宣言の意味です）。ただし、プロキシが注入するキーを読み取ることはできません。より厳密な境界が必要な場合は、エージェントを別の OS ユーザーとして実行するか、サンドボックス内で実行してください。
詳細なモデル - 統合ごとの仕様（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年4月）、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
```
- **パスはサービスプレフィックス以降の上流APIのフルパスです**：SlackのWeb APIは`/api/<method>`、Gmailは`/gmail/v1/...`です。v0.15.0より前のプリセットは`/admin.*`や`/v1/users/*/messages/send`を使用しており、実際のトラフィックと一致しませんでした。`aquaman doctor`は、それらがまだ設定に残っている場合に警告します。
- **ポリシーなし = すべて許可**（後方互換）
- **最初の一致が優先**：ルールは上から下へ評価され、一致しないリクエストは`defaultAction`にフォールスルーします
- **認証前に拒否**：ブロックされたリクエストは実際の認証情報を取得しません
- **パスグロブ：** `*`はセグメント内で一致、`**`は0個以上のセグメントに一致
- `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`（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` | systemd ≥ 256のLinux | 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 → libsecretがあれば`keychain`、なければsystemd ≥ 256なら`systemd-creds`、それ以外は`encrypted-file`）。
`encrypted-file`は、ネイティブキーリングのないヘッドレスLinux/CI環境向けの最後の手段です。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をアンロックします。他のバックエンドはすでに高速か内部でキャッシュするため、デフォルトではキャッシュはオフです。`~/.aquaman/config.yaml`の`credentials.cacheTtlSeconds`（または`AQUAMAN_CACHE_TTL`）で調整できます。`0`で無効化されます。
正直なトレードオフ：アクセスごとの生体認証プロンプトはユーザー存在確認であり、キャッシュはTTLウィンドウの間、アクセスごとの存在確認を排除します。無人エージェントではそのプロンプトに応答が返ることがないため、Vaultは放棄されて平文の`.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でプロンプトをゼロにするには、`aquaman` Vaultにスコープされたサービスアカウントを使用してください。`aquaman doctor`がその方法を案内します。
## ライセンス
MIT - [LICENSE](https://github.com/tech4242/aquaman/blob/main/LICENSE)を参照。