API 設計＆エラーハンドリング

このドキュメントでは、バックエンド（api_internal/）における Express ミドルウェアパイプライン、CORS ポリシー、認証・レート制限、標準化されたエラー階層、および Sentry によるエラー監視体制について解説します。

1. ミドルウェアパイプラインの構成

バックエンド API は、受信したリクエストを以下のパイプラインを通じて安全に処理します。

追跡識別子とセキュリティの初期検証
リクエスト受信直後に一意の x-request-id を付与してログ追跡を可能にし、CORS によるオリジン確認と IP / ユーザー別のレート制限を実施します。
多重防御による認証と認可
App Check による正規クライアントの確認、Firebase Auth による JWT トークンの署名検証、およびメール確認完了の有無を順次確認します。
例外の捕捉と一元処理
コントローラー内部で発生した同期・非同期の例外はすべてグローバルエラーハンドラーへ集約され、Sentry へのエラー送信とクライアントへの標準エラー応答を執り行います。

x-request-id による分散トレーシング
すべてのリクエストに UUID を割り当て、クライアント・サーバー・Sentry ログ間で同一リクエストを正確に照合します。
レート制限 (express-rate-limit)
- 全体制限: 15 分間に最大 300 リクエスト。
- 招待・参加制限: 1 時間に最大 15 回（総当たり攻撃防止）。
- AI リクエスト制限: 1 時間に最大 100 回。
App Check 検証 (verifyAppCheck)
正規の Web / モバイルクライアントからのアクセスであることを検証します。
Firebase JWT 認証 (authenticate)
Authorization: Bearer <token> を検証し、認証済みユーザー情報を req.user に注入します。
メール確認ガード (requireEmailVerified)
パスワード認証ユーザーのメール確認状況を検証します（Google 認証およびテスト環境では自動バイパス）。

場当たり的な例外返却を廃止し、HTTP ステータスコードとエラーコードを内包する AppError 階層を通じて一貫したレスポンスを返却します。

内部情報のマスキング
予期せぬ内部エラー（500）が発生した場合、スタックトレースやデータベース接続情報などの機密ログを秘匿し、安全なエラーメッセージと requestId のみをクライアントへ返却します。
Sentry との連携
本番環境での例外発生時には、スタックトレース、実行コンテキスト、ユーザー識別子（req.user.uid）、および requestId を Sentry へ即時送信し、迅速な原因究明を可能にします。