認証境界ポリシー

NENE2 は認証を、フレームワークのマジックに隠すのではなく、明示的なアプリケーション境界として扱います。

このポリシーでは、マシンクライアント・MCP ツール・将来の認証ミドルウェアに対する最初の API キーとトークンの方向性を定義します。

ポジション

認証と認可は明示的なミドルウェア境界です。

デフォルトの方向性:

• API キーはマシンクライアントと MCP ツール向け。
• Bearer トークンは、アプリケーションが採用する場合のユーザーまたはサービス認証向け。
• セッション認証は、サーバーサイドのブラウザセッションが必要なアプリケーション向け。
• OpenAPI セキュリティスキームは、対応するミドルウェアの動作が存在する場合にのみ追加する。
• シークレットはコミット・ログ記録・MCP メタデータを通じた公開を禁止する。

最初に実装されるミドルウェアパスは、以下を使用するマシンクライアントエンドポイントへの API キーチェックです:

X-NENE2-API-Key

キーの値は、設定されている場合に NENE2_MACHINE_API_KEY から読み込まれます。パブリックのみのローカル開発では未設定のままにし、保護されたルートをテストする際はリポジトリの外で設定します。

最初の保護パスのローカルスモークワークフローは docs/development/machine-client-smoke.md に記載されています。

API キー

API キーは非人間クライアント向けの長期有効な認証情報です。

API キーの用途:

• ローカル HTTP API を呼び出すローカル MCP ツール
• サービス間の検査ツール
• 安定したスコープアクセスが必要なマシンクライアント

API キーには以下が必要です:

• 所有者
• 環境
• スコープリスト
• 作成日時
• ストレージが存在する場合は最終使用日時
• ローテーションまたは失効パス

生の API キーを OpenAPI の例・MCP ツールカタログ・ログ・スクリーンショット・コミットされた設定に含めないでください。

Bearer トークン

Bearer トークンは Authorization ヘッダーで送信されるリクエスト認証情報です。

Bearer トークンの用途:

• 短期有効なユーザートークン
• 明示的なスコープを持つサービストークン
• 将来の OAuth またはファーストパーティトークンフロー

Bearer トークンは短期有効であっても、シークレットとして扱う必要があります。

認証アダプターが存在する前に、フレームワークは特定のトークン形式を規定すべきではありません。JWT・オペークトークン・外部 ID プロバイダートークンは後でアダプターによってサポートできます。

スコープ

スコープは許可された機能を記述します。

初期のスコープ命名は小さく読みやすく保つ:

• read:system
• read:health
• read:docs
• write:* は書き込みツールが設計された後のみ
• admin:* は管理ポリシーが文書化された後のみ

MCP ツールは本番使用前に必要な最小スコープを宣言する必要があります。

ローカル開発

ローカル開発では、明らかに非シークレットで例として文書化されている場合にのみプレースホルダー認証情報を使用できます。

ローカルツールで許可される操作:

• エンドポイントが意図的にパブリックである場合、認証情報なしでパブリックローカル HTTP エンドポイントを呼び出す
• リポジトリの外で生成されたテスト専用の API キーを使用する
• 値なしで必要な環境変数名を文書化する

ローカルツールで禁止される操作:

• MCP ツールを通じて .env の値を読み取る
• コマンド出力に認証情報を出力する
• 開発者の非公開認証情報ストレージに依存する
• 本番動作に似た方法で認証をバイパスする

本番環境の要件

本番認証は実装前に明示的な設計が必要です。

本番認証情報を有効にする前に、以下を文書化してください:

• 認証情報の種類
• 所有者とローテーションプロセス
• 許可される環境
• 必要なスコープ
• ストレージバックエンド
• 監査フィールド
• 欠損・無効・期限切れ・不十分な認証情報に対する失敗動作

認証情報の検証失敗は Problem Details レスポンスを使用し、シークレット値の存在を明かしてはなりません。

ロギングとオブザーバビリティ

ログに含めてよいもの:

• request id
• 認証情報の種類
• 安全な場合の認証情報所有者 ID
• スコープ名
• 認証結果
• 失敗理由のカテゴリ

ログに含めてはいけないもの:

• 生の API キー
• Bearer トークン
• Cookie
• Authorization ヘッダー
• 攻撃の助けになる可能性がある認証情報ハッシュ

OpenAPI と MCP

OpenAPI セキュリティスキームは実装済みのミドルウェアと一致する必要があります。

追加する場合、OpenAPI は以下を記述すべきです:

• 認証情報の場所
• 必要なスコープ
• 401 と 403 の Problem Details レスポンス
• 実際のシークレットを含まない例

MCP メタデータは生の認証情報ではなく、必要なスコープを参照する必要があります。

Write・admin・destructive の MCP ツールは、実装前に認証・認可・監査・request id 伝播・確認動作が必要です。