セキュリティとプライバシー：auth_mode、allow_lan_access、そして「アカウント情報を漏らさない」設計

Antigravity Tools を「ローカル AI ゲートウェイ」として使用するとき、セキュリティ問題は通常 2 つのことだけです：サービスを誰に公開するか（ローカルのみか、LAN/インターネット全体か）、そして外部リクエストに API Key を持たせる必要があるかどうかです。このレッスンでは、ソースコード内のルールを明確に解説し、そのまま使える最小セキュリティベースラインを提供します。

学んだ後できること

適切な allow_lan_access を選択できる：リッスンアドレス（127.0.0.1 vs 0.0.0.0）に影響することを理解する
適切な auth_mode を選択できる：off/strict/all_except_health/auto の実際の動作を明確にする
api_key を設定し検証できる：curl を使って「認証が有効かどうか」を一目で確認できる
プライバシー保護の境界を理解できる：ローカル proxy key は上流に転送されない；API クライアントへのエラーメッセージでアカウントメールの漏洩を回避する

現在の悩み

スマートフォン/別の PC からアクセスしたいが、LAN アクセスを有効にすると「露出」するのではないかと心配
認証を有効にしたいが、/healthz を除外すべきかどうか不明で、ヘルスチェックを失敗させるのではないかと心配
ローカル key、cookie、アカウントメールが外部クライアントや上流プラットフォームに漏洩することを心配

この方法をいつ使うか

allow_lan_access を有効にする準備をしている場合（NAS、家庭 LAN、チーム内ネットワーク）
cloudflared/リバースプロキシを使ってローカルサービスをインターネットに公開する場合（先に Cloudflared 一発トンネル を参照してください）
401 に遭遇し、「key を持っていない」か「モードが一致していない」かを確認する必要がある場合

🎒 始める前の準備

前提条件

GUI で API Proxy を起動できること（まだ動作していない場合は、先に ローカルリバースプロキシを起動して最初のクライアントを接続 を参照してください）。
自分が解決したい問題を知っていること：ローカルのみか、LAN/インターネットアクセスか。

このレッスンで頻繁に登場する 3 つのフィールド

allow_lan_access：LAN アクセスを許可するかどうか。
auth_mode：認証戦略（どのルートで key を持つ必要があるかを決定）。
api_key：ローカルプロキシの API Key（ローカルプロキシ認証のみに使用され、上流には転送されません）。

auth_mode とは？

auth_mode は Antigravity Tools の「プロキシ認証スイッチ + 除外戦略」です。外部クライアントがローカルプロキシエンドポイントにアクセスするとき、どのリクエストが proxy.api_key を持つ必要があり、/healthz のようなヘルスチェックルートが認証なしアクセスを許可するかを決定します。

コアコンセプト

まず「公開面」を決める：allow_lan_access=false の時は 127.0.0.1 のみリッスン；true の時は 0.0.0.0 をリッスン。
次に「入り口キー」を決める：auth_mode が key を持つ必要があるか、および /healthz を除外するかを決定。
最後に「プライバシー収集」をする：ローカル proxy key/cookie を上流に転送しない；外部エラーメッセージにはアカウントメールを含めない。

さあやってみよう

ステップ 1：まず LAN アクセスを有効にするかどうかを決める（allow_lan_access）

理由「他のデバイスからアクセスが必要」な時だけ LAN アクセスを有効にするべきで、そうでない場合はデフォルトでローカルのみアクセスするのが最も簡単なセキュリティ戦略です。

ProxyConfig では、リッスンアドレスは allow_lan_access で決まります：

rust

pub fn get_bind_address(&self) -> &str {
    if self.allow_lan_access {
        "0.0.0.0"
    } else {
        "127.0.0.1"
    }
}

GUI の API Proxy ページで、必要に応じて「Allow LAN Access」スイッチを設定してください。

確認すべきもの

無効時：「ローカルのみアクセス」の意味のヒントが表示されます（具体的な文言は言語パックによります）
有効時：インターフェースに目立つリスク警告が表示されます（これは「公開面の拡大」であることを提醒）

ステップ 2：auth_mode を選択する（まずは auto を推奨）

理由auth_mode は「認証のオン/オフ」だけでなく、/healthz のようなヘルスチェックエンドポイントを除外するかどうかも決定します。

プロジェクトは 4 種類のモードをサポートしています（docs/proxy/auth.md から）：

off：すべてのルートで認証不要
strict：すべてのルートで認証必要
all_except_health：/healthz を除き、他のルートすべてで認証必要
auto：自動モード、allow_lan_access に基づいて実際の戦略を導出

auto の導出ロジックは ProxySecurityConfig::effective_auth_mode() にあります：

rust

match self.auth_mode {
    ProxyAuthMode::Auto => {
        if self.allow_lan_access {
            ProxyAuthMode::AllExceptHealth
        } else {
            ProxyAuthMode::Off
        }
    }
    ref other => other.clone(),
}

推奨アプローチ

ローカルのみアクセス：allow_lan_access=false + auth_mode=auto（最終的に off と同等）
LAN アクセス：allow_lan_access=true + auth_mode=auto（最終的に all_except_health と同等）

確認すべきもの

API Proxy ページで、「Auth Mode」ドロップダウンに off/strict/all_except_health/auto の 4 つのオプションがあること

ステップ 3：api_key を確認する（必要に応じて再生成）

理由プロキシが外部アクセス（LAN/インターネット）を必要とする場合、api_key はパスワードとして管理すべきです。

デフォルトでは ProxyConfig::default() が sk-... 形式の key を生成します：

rust

api_key: format!("sk-{}", uuid::Uuid::new_v4().simple()),

API Proxy ページで、現在の api_key を編集、再生成、コピーできます。

確認すべきもの

ページに api_key 入力フィールド、および編集/再生成/コピーボタンがあること

ステップ 4：/healthz で「除外戦略」が期待通りか検証する

理由/healthz は最短のクローズドループです：モデルを実際に呼び出さなくても、「サービス到達可能 + 認証戦略が正しい」ことを確認できます。

<PORT> を自分のポートに置き換えてください（デフォルト 8045）：

macOS/LinuxWindows

bash

curl -sS "http://127.0.0.1:<PORT>/healthz"

powershell

curl.exe -sS "http://127.0.0.1:<PORT>/healthz"

確認すべきもの

json

{"status":"ok"}

auth_mode を strict に設定した場合

strict は /healthz を除外しません。key を持つ必要があります：

bash

curl -sS "http://127.0.0.1:<PORT>/healthz" \
  -H "Authorization: Bearer <API_KEY>"

ステップ 5：「非 health エンドポイント」で 401 を検証する（key を持った後は 401 でない）

理由認証ミドルウェアが本当に有効になっていることを確認したい場合、UI でモードを選択しても実際には機能していない可能性があります。

以下のリクエストボディは意図的に不完全に書かれており、その目的は「呼び出し成功」ではなく、認証でインターセプトされているかを検証することです：

bash

#key なし：auth_mode != off の時、直接 401 になるはず
curl -i "http://127.0.0.1:<PORT>/v1/messages" \
  -H "Content-Type: application/json" \
  -d "{}"

#key あり：401 でなくなるはず（リクエストボディが不完全なので 400/422 が返る可能性）
curl -i "http://127.0.0.1:<PORT>/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d "{}"

確認すべきもの

key なし：HTTP/1.1 401 Unauthorized
key あり：ステータスコードが 401 でなくなる

チェックポイント ✅

現在の公開面を明確に説明できる：ローカルのみ（127.0.0.1）か LAN（0.0.0.0）か
auth_mode=auto の時、実際の有効モードを予測できる（LAN → all_except_health、ローカル → off）
2 つの curl コマンドで「key なしの 401」を再現できる

よくある落とし穴

間違った方法 vs 推奨方法

シナリオ	❌ よくある間違い	✓ 推奨方法
LAN アクセスが必要	`allow_lan_access=true` だけを有効にするが、`auth_mode=off`	`auth_mode=auto` を使用し、強力な `api_key` を設定する
認証を有効にしても常に 401	クライアントが key を持っているが、ヘッダー名が互換性がない	プロキシは `Authorization`/`x-api-key`/`x-goog-api-key` の 3 種類のヘッダーに互換性がある
認証を有効にしているが key を設定していない	`api_key` が空でも認証を有効にしている	バックエンドは直接拒否する（ログで key が空であることが示される）

/healthz の除外は all_except_health でのみ有効

ミドルウェアは「有効モード」が all_except_health でパスが /healthz の時に通過を許可します；これを「ヘルスチェックポート」として扱い、ビジネス API として使わないでください。

プライバシーと「アカウント情報を漏らさない」設計

1) ローカル proxy key は上流に転送されない

認証はローカルプロキシ入り口でのみ発生；docs/proxy/auth.md には明記されています：proxy API key は上流には転送されません。

リクエストが z.ai（Anthropic 互換）に転送されるとき、コードは少数の header のみを通過させ、ローカル proxy key または cookie を転送することを回避します：

rust

// Only forward a conservative set of headers to avoid leaking the local proxy key or cookies.

3) Token 更新失敗のエラーメッセージでアカウントメールを含めない

Token 更新が失敗したとき、ログには具体的なアカウントが記録されますが、API クライアントに返されるエラーはメールを含まない形式に書き換えられます：

rust

// Avoid leaking account emails to API clients; details are still in logs.
last_error = Some(format!("Token refresh failed: {}", e));

このレッスンのまとめ

まず公開面を決める（allow_lan_access）、次に入り口キーを決める（auth_mode + api_key）
auth_mode=auto のルールは簡単：LAN は少なくとも all_except_health、ローカルのみは off
プライバシーのボトムラインは「ローカル key を外部に持たない、アカウントメールは外部エラーで漏らさない」、詳細はミドルウェアと上流転送コードにある

次のレッスンの予告

次のレッスンでは 高可用性スケジューリング：ローテーション、固定アカウント、スティッキーセッションと失敗時再試行 を見て、「セキュリティ入り口」の後の「安定出口」を補完します。

付録：ソースコード参考

クリックしてソースコードの場所を展開

更新日時：2026-01-23

機能	ファイルパス	行番号
auth_mode の 4 種類のモードと auto の意味説明	`docs/proxy/auth.md`	10-24
ProxyAuthMode 列挙型とデフォルト値（デフォルト off）	`src-tauri/src/proxy/config.rs`	5-18
ProxyConfig の重要フィールドとデフォルト値（allow_lan_access、api_key）	`src-tauri/src/proxy/config.rs`	174-259
リッスンアドレス導出（127.0.0.1 vs 0.0.0.0）	`src-tauri/src/proxy/config.rs`	281-292
---	---	---
認証ミドルウェア（OPTIONS 通過、/healthz 除外、3 種類の header 互換）	`src-tauri/src/proxy/middleware/auth.rs`	14-78
UI：allow_lan_access と auth_mode のスイッチ/ドロップダウン	`src/pages/ApiProxy.tsx`	943-1046
UI：api_key の編集/リセット/コピー	`src/pages/ApiProxy.tsx`	1048-1120
invalid_grant 自動無効化と「メール漏洩回避」エラー書き換え	`src-tauri/src/proxy/token_manager.rs`	841-940
disable_account：disabled/disabled_at/disabled_reason を書き込み、メモリプールから削除	`src-tauri/src/proxy/token_manager.rs`	942-969
z.ai 転送時転送可能な header 収縮（ローカル key/cookies の漏洩回避）	`src-tauri/src/proxy/providers/zai_anthropic.rs`	70-89
アカウントプール無効化と UI 表示の動作説明（ドキュメント）	`docs/proxy/accounts.md`	9-44

ゼロから始める

エラーに遭遇したら

アップグレードのトラブル回避ガイド

あなたの AI プラットフォームを接続

システムを本番環境レベルにアップグレード

技術用語集

セキュリティとプライバシー：auth_mode、allow_lan_access、そして「アカウント情報を漏らさない」設計

学んだ後できること

現在の悩み

この方法をいつ使うか

🎒 始める前の準備

auth_mode とは？

コアコンセプト

さあやってみよう

ステップ 1：まず LAN アクセスを有効にするかどうかを決める（allow_lan_access）

ステップ 2：auth_mode を選択する（まずは auto を推奨）

ステップ 3：api_key を確認する（必要に応じて再生成）

ステップ 4：/healthz で「除外戦略」が期待通りか検証する

ステップ 5：「非 health エンドポイント」で 401 を検証する（key を持った後は 401 でない）

チェックポイント ✅

よくある落とし穴

プライバシーと「アカウント情報を漏らさない」設計

1) ローカル proxy key は上流に転送されない

2) z.ai に転送するとき、転送可能な header を意図的に収縮する

3) Token 更新失敗のエラーメッセージでアカウントメールを含めない

このレッスンのまとめ

次のレッスンの予告

付録：ソースコード参考

セキュリティとプライバシー：auth_mode、allow_lan_access、そして「アカウント情報を漏らさない」設計 ​

学んだ後できること ​

現在の悩み ​

この方法をいつ使うか ​

🎒 始める前の準備 ​

auth_mode とは？ ​

コアコンセプト ​

さあやってみよう ​

ステップ 1：まず LAN アクセスを有効にするかどうかを決める（allow_lan_access） ​

ステップ 2：auth_mode を選択する（まずは auto を推奨） ​

ステップ 3：api_key を確認する（必要に応じて再生成） ​

ステップ 4：/healthz で「除外戦略」が期待通りか検証する ​

ステップ 5：「非 health エンドポイント」で 401 を検証する（key を持った後は 401 でない） ​

チェックポイント ✅ ​

よくある落とし穴 ​

プライバシーと「アカウント情報を漏らさない」設計 ​

1) ローカル proxy key は上流に転送されない ​

2) z.ai に転送するとき、転送可能な header を意図的に収縮する ​

3) Token 更新失敗のエラーメッセージでアカウントメールを含めない ​

このレッスンのまとめ ​

次のレッスンの予告 ​

付録：ソースコード参考 ​

セキュリティとプライバシー：auth_mode、allow_lan_access、そして「アカウント情報を漏らさない」設計

学んだ後できること

現在の悩み

この方法をいつ使うか

🎒 始める前の準備

auth_mode とは？

コアコンセプト

さあやってみよう

ステップ 1：まず LAN アクセスを有効にするかどうかを決める（allow_lan_access）

ステップ 2：auth_mode を選択する（まずは auto を推奨）

ステップ 3：api_key を確認する（必要に応じて再生成）

ステップ 4：/healthz で「除外戦略」が期待通りか検証する

ステップ 5：「非 health エンドポイント」で 401 を検証する（key を持った後は 401 でない）

チェックポイント ✅

よくある落とし穴

プライバシーと「アカウント情報を漏らさない」設計

1) ローカル proxy key は上流に転送されない

2) z.ai に転送するとき、転送可能な header を意図的に収縮する

3) Token 更新失敗のエラーメッセージでアカウントメールを含めない

このレッスンのまとめ

次のレッスンの予告

付録：ソースコード参考