| name | bff-auth |
| description | このモノレポ（project-template-2026）の認証の唯一の実装ガイド。OAuth 2.0 authorization code + PKCE を confidential client として実装した BFF（Backend-For-Frontend）パターン（draft-ietf-oauth-browser-based-apps §6 準拠）。ブラウザには不透明・署名付きの HttpOnly セッション Cookie だけを渡し、アクセス／リフレッシュ／id トークンはサーバ側（DynamoDB）にのみ保持する。以下のいずれかのとき必ず読むこと —— (1) 認証・ログイン・ログアウト・セッション・Cookie・OIDC/OAuth/PKCE・トークンリフレッシュ・`@icasu/backend-auth`・Cognito・oidc-server-mock について質問された、(2) ログイン/ログアウト/セッション/保護ルート/認可などの認証関連機能を実装・変更・レビューする、(3) `packages/backend-auth`・`apps/frontend` の `features/auth`・`entities/session`・`apps/iac` の Cognito/CloudFront/DynamoDB セッション周りを触る、(4) 認証の設計判断（なぜ Cookie にトークンを載せないか、なぜ /auth と /api を分けるか等）や落とし穴を知りたい。 |
BFF 認証（project-template-2026）
このモノレポの認証は BFF（Backend-For-Frontend）パターンで実装されている。
出典は OAuth 2.0 for Browser-Based Applications（IETF draft）の
§6 "Backend For Frontend (BFF)"、Cookie 属性は §6.1.3.2。
作業を始める前にまずこの SKILL.md 全体を読み、深掘りが必要になったら下記の reference を開く。
このスキルと各ソースの doc コメント／各 CLAUDE.md が認証の正典で、記憶や一般論で
認証コードを書かない。
破ってはいけない中心不変条件
ブラウザが手にするトークンはゼロ。 ブラウザが持つのは不透明・署名付きの session id を
載せた HttpOnly Cookie 1つだけ。access / refresh / id トークンはすべてサーバ側
（DynamoDB のセッション行）にだけ存在する。
この一線を崩す提案（トークンを JSON で返す、localStorage に入れる、API Gateway に JWT
authorizer を付ける、Cookie にアクセストークンを載せる等）は BFF パターンの否定であり、
XSS によるトークン窃取への構造的防御を失う。実装・レビューではこれを最優先で守る。
全体像（1 段落）
Cognito（本番）/ oidc-server-mock（ローカル）を OIDC プロバイダ、Hono BFF を
confidential client（client secret 保持）とする authorization code + PKCE フロー。
ログインは BFF の /auth/login → プロバイダ hosted UI → /auth/callback へフルページ遷移し、
BFF が code をトークンに交換して DynamoDB にセッション行を作り、署名付き session Cookie を
発行する。以後 SPA は credentials: 'include' で /api/*（JSON API）を叩き、BFF の
requireSession ミドルウェアが Cookie → セッション検証（＋失効間近なら透過リフレッシュ）を行う。
パッケージと責務（どこを触るか）
| 場所 | 役割 |
|---|
packages/backend-auth（@icasu/backend-auth） | 認証の本体。createAuth(config) が合成点。認証の仕様はここのテストが正典。 |
packages/backend-auth/src/route.ts | createAuthRoute（/login・/callback・/logout = ブラウザ遷移）と createMeRoute（/me = JSON API）。 |
packages/backend-auth/src/middleware.ts | createRequireSession。保護ルート用。セッション検証＋アクセストークン自動リフレッシュ＋ローテーション。 |
packages/backend-auth/src/libs/ | config（DI 設定 + env ロード）/ cookie（署名付き Cookie）/ oidc（token endpoint・URL 組み立て）/ jwks（id_token 検証）/ pkce（乱数・PKCE）/ session（DynamoDB ストア）。 |
apps/backend/src/app.ts | ホストの合成点。createAuth を呼び /auth・/me・/tasks をマウント。AppType を export。 |
apps/frontend/src/features/auth | AuthGuard（/api/me が 401 のときログインへ全画面遷移）・logout-button・authUrls。 |
apps/frontend/src/entities/session | sessionQuery（TanStack Query で /api/me）・UnauthorizedError。 |
apps/frontend/src/shared/api | Hono RPC クライアント（credentials: 'include'）。 |
apps/iac/src/stacks/web | cognito（confidential client + hosted UI）・cdn（CloudFront の /api と /auth 振り分け）・sessions（DynamoDB）・api（Lambda。authorizer なし）。 |
絶対に外せない設計ポイント
- 設定は注入（DI）。パッケージは
process.env を読まない。 ホスト（apps/backend）が
loadAuthConfigFromEnv() を起動時に一度呼び、不足 env を全件まとめて報告して fail fast する。
同じコードが本番（Cognito）とローカル（mock）で動くのは差分をすべて AuthConfig に寄せているから。
- ルート定義はメソッドチェーンで書く（変数に分解しない）。 チェーンを崩すと推論型
AppType
が失われ、フロントの Hono RPC 型連携が壊れる。route.ts / app.ts / tasks/route.ts 共通の規約。
/auth（ブラウザ遷移）と /api（JSON）は別系統。 混同禁止。理由と振り分けは
references/architecture.md。- ステートフルな部品（DynamoDB クライアント・リモート JWKS）は
createAuth で1度だけ構築し、
リクエストごとに作らない。
深掘りリファレンス
- 各フローのシーケンス図 —— login / logout / refresh / API 保護の手順・順序・分岐を mermaid で
図解したリポジトリ内ドキュメント。フロー（手順）はここが単一の真実源（正典はコード＝テスト
だが、フローの記述はこの1箇所に集約し、architecture.md には重複させない）。フローを変えたら
まずここを直す。→
docs/specs/authentication.md
- アーキテクチャ全体 ——
/auth vs /api の分離と CloudFront/Vite の振り分け、セッションストア／
Cookie 仕様、ローカル↔本番の切り替え、DI 設計、フロント連携、draft との対応（＝設計判断が中心。
各フローの手順は上のドキュメントを見る）。→ references/architecture.md
- 落とし穴・注意点 ——
__Host- Cookie 削除時の Secure 必須、SameSite=Strict が成立する理由、
DynamoDB Local の TTL、redirect_uri を strip しない理由、invalid_grant の扱い、Node strip-only
TS の制約、open-redirect ガード 等（既に踏んで直したものを含む）。→
references/gotchas.md
変更するときの入口
- 保護 API を追加 → ルートに
auth.requireSession を挟み c.get('session') で userSub/email
を取る（tasks/route.ts と同型）。app.ts へメソッドチェーンでマウント。
- セッションに項目を増やす →
libs/session.ts の SessionData と読み書き、route.ts の
saveSession、必要なら middleware.ts の SessionContext を揃える。
- プロバイダ／スコープ変更 → env（
OIDC_* / AUTH_*）と apps/iac の Cognito、
apps/backend/.env.example を一緒に更新。DI のためパッケージ側コードは基本不要。
- 認証を触ったら必ず
pnpm --filter @icasu/backend-auth test（＋ apps/backend のテスト）を
実行し、テスト＝仕様を満たすことを確認する。
