lucia-auth

Lucia Auth

Lucia Auth と The Copenhagen Book のパターンを用いて、安全で本番環境向けの認証を実装します。

概要

ブラウザーで動作するウェブアプリでは、認証をログイン用ルートの組み合わせではなく、システムとして扱ってください。ユーザーから「認証を追加して」と依頼され、明示的に簡易的なサンプルを求められていない場合は、デフォルトで本番環境向けのベースラインを実装してください。

ウェブアプリ向けの本番環境用ベースライン

リポジトリに同等の機能がない場合、デフォルトのベースラインは次のとおりです。

1. メールアドレスとパスワードによるサインアップ、サインイン、サインアウト
2. HttpOnly、Secure、SameSite Cookie を使ったサーバーサイドセッション
3. メール認証と認証メールの再送フロー
4. パスワードリセットフロー
5. すべての認証エンドポイントとメール送信エンドポイントに対するレート制限
6. 状態を変更するすべてのルートに対する CSRF 保護または厳格な Origin 検証
7. パスワード変更、メール認証・変更、権限変更時のセッション無効化
8. パスワードやメールアドレスの変更、アカウントの削除、MFA の無効化、API キーの表示などの機密性の高い操作に対する再認証（「sudo モード」）
9. オープンリダイレクト対策を施した安全な認証後リダイレクト
10. 要望に応じて追加する OAuth、TOTP、または WebAuthn

通常のウェブアプリでは、デフォルトで localStorage に JWT を保存しないでください。アーキテクチャ上、ステートレスなトークンが明らかに必要な場合を除き、サーバーサイドセッションを優先してください。

必ず参照するドキュメント

ブラウザーで動作するウェブ認証のタスクでは、必ず最初に次のドキュメントを読んでください。

• references/copenhagen-book/password-authentication.md
• references/copenhagen-book/sessions.md
• references/copenhagen-book/csrf.md
• references/copenhagen-book/email-verification.md
• references/copenhagen-book/password-reset.md
• references/copenhagen-book/open-redirect.md
• references/lucia/sessions-basic.md
• references/lucia/sessions-inactivity-timeout.md
• references/lucia/rate-limit-token-bucket.md

該当する場合は、次のドキュメントを読んでください。

• OAuth：references/copenhagen-book/oauth.md、続けて references/lucia/tutorial-github-oauth.md または references/lucia/tutorial-google-oauth.md
• MFA：references/copenhagen-book/mfa.md
• WebAuthn／パスキー：references/copenhagen-book/webauthn.md、続けて references/lucia/example-email-password-2fa-webauthn.md
• セッションのトレードオフ：references/lucia/sessions-overview.md、references/lucia/sessions-stateless-tokens.md

実装ワークフロー

1. リポジトリを調べ、既存の認証、ユーザー、メール、セッション、ミドルウェア、データベースのパターンを確認します。
2. 認証の対象範囲を決めます。 標準的なウェブアプリでは、デフォルトで上記の本番環境用ベースラインを採用します。
3. まず認証スキーマを作成または更新します。 最低限、user、session、email_verification、password_reset が必要です。 oauth_account、user_totp、user_recovery_code、または WebAuthn のテーブルは、必要な場合にのみ追加します。
4. 次に、安全な基本機能を実装します。 パスワードのハッシュ化、セッションの発行・検証、CSRF／Origin チェック、レート制限、トークン生成、リダイレクト検証を行います。
5. ユーザーフローを一通り実装します。 登録、ログイン、ログアウト、メール認証、認証メールの再送、パスワードを忘れた場合の手続き、パスワードのリセット、パスワード変更、セッションの無効化を実装します。
6. 機密性の高い操作には再認証を追加します。 メールアドレスやパスワードの変更、アカウントの削除、MFA の無効化、セキュリティ設定の変更には、新しいセッションまたは新たな認証情報のチャレンジを必須にしてください。
7. 動作を検証します。 Cookie のフラグ、レート制限、無効化の動作、期限切れトークンの処理、異常系を確認してください。

セキュリティルール

パスワード

• パスワードは Argon2id でハッシュ化してください。代替手段として Scrypt を使用できます。bcrypt はレガシーな制約がある場合に限ります。
• 最小文字数は 8 文字です。上限を低く設定しないでください。64～256 文字が妥当な範囲です。
• パスワードを暗黙的にトリミング、正規化、または切り詰めないでください。
• コピー＆ペーストとパスワードマネージャーの使用を許可してください。
• 実用上可能な場合は、haveibeenpwned で漏えいしたパスワードを確認してください。
• セキュリティが重要なアプリでは MFA を推奨し、アプリで実質的に必要な場合は必須にしてください。

メールアドレス

• 保存または比較する前に、メールアドレスを小文字に正規化します。
• ReDoSを避けるため、検証はシンプルにします。
• +tag の部分を黙って削除しないでください。
• メールアドレスを本人確認の復旧に使用する場合は、信頼できるものとして扱う前に検証を実装します。

セッション

• ログイン時に新しいセッションを作成します。認証後に認証前または匿名のセッションを再利用しないでください。
• セッションシークレットの生の値ではなく、ハッシュを保存します。
• アイドル時の有効期限と絶対有効期間の併用を推奨します。
• 再認証フローのために、セッションの鮮度を追跡します。
• 認証情報や権限が変更されたら、すべてのセッションを無効にします。
• URL経由でセッショントークンを受け付けないでください。

Cookie

• デフォルトでは HttpOnly、Secure、Path=/、SameSite=Lax を使用します。
• UX上のトレードオフが許容できる場合に限り、SameSite=Strict を使用します。
• サーバーがセッションの非アクティブ期間を更新したら、有効期間の長いCookieも更新します。

CSRF

• GET で状態を変更しないでください。
• GET 以外のすべてのブラウザーリクエストで Origin を確認し、値がない場合や信頼できない場合は拒否します。
• フォームを多用するアプリでは、第2の防御層としてCSRFトークンを追加します。
• CSRFトークンがクロスオリジンで取得されないよう、CORSを厳格に設定します。

OAuth / OIDC

• Authorization Code + PKCEを使用します。
• コールバック時に state とコード検証子を検証します。
• プロバイダーがサポートしている場合は、client_secret_basic を推奨します。
• アカウントはまずプロバイダーのサブジェクトで紐付け、メールアドレスによる自動紐付けは、プロバイダーがメールアドレスを検証済みと明示している場合に限ります。
• ログイン後の returnTo または redirect_to の値をサニタイズし、同一オリジンのパスのみ許可します。

検証トークンとリセットトークン

• リンクには十分なエントロピーを持つランダムなトークンを使用します。
• 保存前に、リンクトークンをSHA-256でハッシュ化します。
• トークンは1回限り使用できるようにし、自動的に有効期限切れにします。
• トークンを含むページには Referrer-Policy: strict-origin を設定します。
• メール送信エンドポイントには、厳格なレート制限を適用します。

テンプレート一覧

以下のアセットを出発点として使用し、リポジトリにすでにあるフレームワークとORMに合わせて調整してください。

• パスワードのハッシュ化とパスワードポリシー：assets/password-utils.ts
• セッションの発行、検証、非アクティブタイムアウト、新しいセッションのヘルパー：assets/session-manager.ts
• コアSQLスキーマ：assets/session-schema.sql
• メール検証リンクとコード：assets/email-verification.ts
• パスワードリセットフロー：assets/password-reset.ts
• OAuth + PKCEフローヘルパー：assets/oauth-handler.ts
• CSRFとオリジン検証のヘルパー：assets/csrf-protection.ts
• トークンバケットによるレート制限：assets/rate-limit.ts
• TOTP MFAと復旧コード：assets/totp-mfa.ts

基本方針を超える対応が必要な場合

次の場合は、WebAuthnまたはパスキーを追加します。

• ユーザーがパスキーまたはWebAuthnを明示的に求めている
• セキュリティが重要な製品である
• フィッシング耐性のあるMFAをアプリが必要としている

次の場合は、OAuthを追加します。

• 製品がすでに外部IDプロバイダーを使用している
• ユーザーがソーシャルログインを明示的に求めている
• アプリにとって、サインアップの手間を減らすメリットがある

次の場合に限り、ステートレスなトークンを使用します。

• アプリがAPIファーストのシステムで、同一オリジンのCookieに依存できない、または
• マルチサービスアーキテクチャを採用する明確な理由がある

出力に関する要件

このスキルを使用する場合、最終回答では以下を明確にしてください。

1. 実装した認証フロー
2. デフォルトで含めたセキュリティ対策
3. 残っている前提条件、またはユーザーが指定する必要のあるプロバイダー固有の設定
4. ローカルで検証した内容と、今後インテグレーションテストが必要な内容