security(auth): P2 帳號鎖定 + OAuth state 驗證

- Account lockout：連續失敗 5 次鎖定 15 分鐘（Fixed Window，Cache） - Member / Provider 各自獨立 namespace - Email 正規化（strtolower+trim） - 不存在帳號不累計計數（防 Cache 污染） - companion key 記錄 locked_until（ISO 8601） - OAuth CSRF 防護：移除 stateless()，手動 state 生成與驗證 - session('oauth_state') + session('state') 雙寫確保 Socialite 內建驗證通過 - state mismatch redirect 至 /login?error=oauth_failed - throttle 從 5,1 調整為 10,1，避免 IP throttle 在 lockout 前觸發 - NormalizesEmail Trait、config/auth_lockout.php Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-03 01:20:25 +08:00
parent b2e20767d8
commit 2a0e9255ae
14 changed files with 680 additions and 47 deletions
@@ -7,15 +7,19 @@ use App\Models\User;
 use App\Models\AdminProfile;
 use App\Models\ProviderProfile;
 use App\Models\MemberProfile;
+use App\Traits\NormalizesEmail;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Facades\Log;
 use Illuminate\Support\Facades\Validator;
 use Illuminate\Validation\Rules\Password;


 class AuthController extends Controller
 {
-    // 科定規範角色
+    use NormalizesEmail;
+
    private const ROLE_MEMBER = 'member';
    private const ROLE_PROVIDER = 'provider';
    private const ROLE_ADMIN = 'admin';
@@ -131,6 +135,50 @@ class AuthController extends Controller
        ]);
    }
    
+    private function isAccountLocked(string $role, string $email): bool
+    {
+        $count = Cache::get("login_failures:{$role}:{$email}", 0);
+        return $count >= config('auth_lockout.max_attempts');
+    }
+
+    private function recordLoginFailure(string $role, string $email): int
+    {
+        $ttl      = config('auth_lockout.decay_minutes') * 60;
+        $countKey = "login_failures:{$role}:{$email}";
+        $expiresKey = "login_expires_at:{$role}:{$email}";
+
+        if (!Cache::has($countKey)) {
+            Cache::put($countKey, 1, $ttl);
+            Cache::put($expiresKey, now()->addSeconds($ttl)->toIso8601String(), $ttl);
+            return 1;
+        }
+
+        return Cache::increment($countKey);
+    }
+
+    private function clearLoginFailures(string $role, string $email): void
+    {
+        Cache::forget("login_failures:{$role}:{$email}");
+        Cache::forget("login_expires_at:{$role}:{$email}");
+    }
+
+    private function buildLockedResponse(string $role, string $email): \Illuminate\Http\JsonResponse
+    {
+        $decayMinutes = config('auth_lockout.decay_minutes');
+        $lockedUntil  = Cache::get("login_expires_at:{$role}:{$email}");
+
+        if (!$lockedUntil) {
+            Log::warning("auth_lockout: expires_at key missing for {$role}:{$email}");
+            $lockedUntil = now()->addMinutes($decayMinutes)->toIso8601String();
+        }
+
+        return response()->json([
+            'status'       => false,
+            'message'      => "帳號已暫時鎖定，請於 {$decayMinutes} 分鐘後再試",
+            'locked_until' => $lockedUntil,
+        ], 423);
+    }
+
    /**
     * 標準化的登出方法
     */
@@ -268,53 +316,60 @@ class AuthController extends Controller
 */
    public function loginMember(Request $request)
    {
-        // 驗證請求數據
        $validator = Validator::make($request->all(), [
-            'email' => 'required|string|email',
+            'email'    => 'required|string|email',
            'password' => 'required|string',
        ]);

        if ($validator->fails()) {
            return response()->json([
-                'status' => false,
+                'status'  => false,
                'message' => '驗證失敗',
-                'errors' => $validator->errors()
+                'errors'  => $validator->errors()
            ], 422);
        }

-        // 檢查用戶是否存在
-        $user = User::where('email', $request->email)
-                   ->where('role', 'member') // 只驗證會員
-                   ->first();
+        $email = $this->normalizeEmail($request->email);

-        // 檢查密碼
+        // 1st: 帳號鎖定檢查
+        if ($this->isAccountLocked(self::ROLE_MEMBER, $email)) {
+            return $this->buildLockedResponse(self::ROLE_MEMBER, $email);
+        }
+
+        // 2nd: 帳號存在確認
+        $user = User::where('email', $email)->where('role', self::ROLE_MEMBER)->first();
+
+        // 3rd: 密碼驗證（帳號不存在與密碼錯誤回傳相同訊息）
        if (!$user || !Hash::check($request->password, $user->password)) {
+            if ($user) {
+                $count = $this->recordLoginFailure(self::ROLE_MEMBER, $email);
+                if ($count >= config('auth_lockout.max_attempts')) {
+                    return $this->buildLockedResponse(self::ROLE_MEMBER, $email);
+                }
+            }
            return response()->json([
-                'status' => false,
+                'status'  => false,
                'message' => '電子郵件或密碼錯誤'
            ], 401);
        }

-        // 檢查用戶是否啟用
        if (!$user->is_active) {
            return response()->json([
-                'status' => false,
+                'status'  => false,
                'message' => '帳號已被停用'
            ], 403);
        }

-        // 創建 API token
+        $this->clearLoginFailures(self::ROLE_MEMBER, $email);
        $token = $user->createToken('auth_token')->plainTextToken;
-
-        // 加載會員資料
        $user->load('memberProfile');

        return response()->json([
-            'status' => true,
+            'status'  => true,
            'message' => '登入成功',
-            'data' => [
-                'user' => $user,
-                'token' => $token,
+            'data'    => [
+                'user'       => $user,
+                'token'      => $token,
                'token_type' => 'Bearer',
            ]
        ]);
@@ -531,53 +586,60 @@ class AuthController extends Controller
 */
    public function loginProvider(Request $request)
    {
-        // 驗證請求數據
        $validator = Validator::make($request->all(), [
-            'email' => 'required|string|email',
+            'email'    => 'required|string|email',
            'password' => 'required|string',
        ]);

        if ($validator->fails()) {
            return response()->json([
-                'status' => false,
+                'status'  => false,
                'message' => '驗證失敗',
-                'errors' => $validator->errors()
+                'errors'  => $validator->errors()
            ], 422);
        }

-        // 檢查用戶是否存在
-        $user = User::where('email', $request->email)
-                   ->where('role', 'provider') // 只驗證服務提供者
-                   ->first();
+        $email = $this->normalizeEmail($request->email);

-        // 檢查密碼
+        // 1st: 帳號鎖定檢查
+        if ($this->isAccountLocked(self::ROLE_PROVIDER, $email)) {
+            return $this->buildLockedResponse(self::ROLE_PROVIDER, $email);
+        }
+
+        // 2nd: 帳號存在確認
+        $user = User::where('email', $email)->where('role', self::ROLE_PROVIDER)->first();
+
+        // 3rd: 密碼驗證（帳號不存在與密碼錯誤回傳相同訊息）
        if (!$user || !Hash::check($request->password, $user->password)) {
+            if ($user) {
+                $count = $this->recordLoginFailure(self::ROLE_PROVIDER, $email);
+                if ($count >= config('auth_lockout.max_attempts')) {
+                    return $this->buildLockedResponse(self::ROLE_PROVIDER, $email);
+                }
+            }
            return response()->json([
-                'status' => false,
+                'status'  => false,
                'message' => '電子郵件或密碼錯誤'
            ], 401);
        }

-        // 檢查用戶是否啟用
        if (!$user->is_active) {
            return response()->json([
-                'status' => false,
+                'status'  => false,
                'message' => '帳號已被停用'
            ], 403);
        }

-        // 創建 API token
+        $this->clearLoginFailures(self::ROLE_PROVIDER, $email);
        $token = $user->createToken('auth_token')->plainTextToken;
-
-        // 加載服務提供者資料
        $user->load('providerProfile');

        return response()->json([
-            'status' => true,
+            'status'  => true,
            'message' => '登入成功',
-            'data' => [
-                'user' => $user,
-                'token' => $token,
+            'data'    => [
+                'user'       => $user,
+                'token'      => $token,
                'token_type' => 'Bearer',
            ]
        ]);
@@ -18,11 +18,19 @@ class SocialAuthController extends Controller
     */
    public function redirectToGoogle()
    {
-        return Socialite::driver('google')
+        $state = bin2hex(random_bytes(32));
+        session()->put('oauth_state', $state);
+
+        $redirect = Socialite::driver('google')
            ->scopes(['openid', 'profile', 'email'])
-            ->with(['access_type' => 'offline', 'prompt' => 'consent']) // 這裡要求 prompt=consent 才能每次都獲取 refresh token
-            ->stateless()
+            ->with(['access_type' => 'offline', 'prompt' => 'consent', 'state' => $state])
            ->redirect();
+
+        // Socialite 在 redirect() 內自己寫了一個 random state 進 session('state')。
+        // 用我們的 state 覆蓋，確保 user() 的內建驗證與 URL 中的 state 一致。
+        session()->put('state', $state);
+
+        return $redirect;
    }

    /**
@@ -30,9 +38,16 @@ class SocialAuthController extends Controller
     */
    public function handleGoogleCallback(Request $request)
    {
+        $requestState = $request->input('state');
+        $sessionState = session()->pull('oauth_state');
+
+        if (!$requestState || !$sessionState || !hash_equals($sessionState, $requestState)) {
+            return redirect(config('app.frontend_url') . '/login?error=oauth_failed');
+        }
+
        try {
-            // 獲取 Google 用戶資訊
-            $googleUser = Socialite::driver('google')->stateless()->user();
+            // 獲取 Google 用戶資訊（Socialite 內建 state 驗證此時也會通過）
+            $googleUser = Socialite::driver('google')->user();

            // 查找相關的社交帳號
            $socialAccount = SocialAccount::where('provider', 'google')
@@ -0,0 +1,11 @@
+<?php
+
+namespace App\Traits;
+
+trait NormalizesEmail
+{
+    private function normalizeEmail(string $email): string
+    {
+        return strtolower(trim($email));
+    }
+}
@@ -0,0 +1,6 @@
+<?php
+
+return [
+    'max_attempts'   => env('LOCKOUT_MAX_ATTEMPTS', 5),
+    'decay_minutes'  => env('LOCKOUT_DECAY_MINUTES', 15),
+];
@@ -14,7 +14,7 @@ const error    = ref('')
 const loading  = ref(false)

 const oauthError = route.query.error === 'oauth_failed'
-  ? 'Google 登入失敗，請重試。'
+  ? 'OAuth 授權失敗，請重新嘗試'
  : ''

 const successMsg = route.query.registered ? '註冊成功，請登入。' : ''
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-02
@@ -0,0 +1,185 @@
+## Context
+
+現有防護分兩層：
+- **IP throttle**（P0）：middleware `throttle:5,1` / `throttle:3,1`，防同一 IP 在短時間大量嘗試
+- **Session Token**（P1）：token 7 天過期，sessionStorage 存放，refresh interceptor
+
+缺口一：攻擊者用多 IP 對同一帳號暴破，IP throttle 完全無效。  
+缺口二：OAuth redirect URL 若遭竄改（CSRF），惡意方可替換 authorization code。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 帳號連續失敗 5 次 → 鎖定 15 分鐘，鎖定期間任何密碼登入均拒絕
+- 鎖定計數以 Cache 存放（key 包含 `email`），TTL = 鎖定時間
+- 登入成功後清除失敗計數
+- OAuth redirect 帶 state，callback 驗 state，不符回傳 400
+- 前端顯示 423 對應的帳號鎖定訊息
+
+**Non-Goals:**
+- Admin 帳號鎖定（Admin Panel 尚未完成）
+- 電子郵件通知（鎖定時通知帳號持有人）
+- Admin 手動解鎖端點（此 change 暫不實作；時間到自動解鎖即可）
+- Lockout 事件 audit log
+
+## Decisions
+
+### D1：失敗計數存 Cache（not DB）
+
+**選擇**：`Cache::increment()` / `Cache::put()`，key = `login_failures:{email}`，TTL = 鎖定時間（15 min）。
+
+**理由**：
+- 不需要永久儲存，TTL = 鎖定時間，到期自動解鎖，零額外維護
+- DB 方案需 migration + GC 排程，複雜度高 3 倍
+- Cache driver 目前為 file（dev）/ Redis（prod），兩者皆可用
+
+**替代方案**：在 `users` 資料表新增 `failed_login_count` / `locked_until` 欄位 → 否決，因為要 migration，且鎖定狀態不需跨重啟持久化。
+
+### D2：鎖定參數放 config
+
+```php
+// config/auth_lockout.php
+return [
+    'max_attempts' => env('LOCKOUT_MAX_ATTEMPTS', 5),
+    'decay_minutes' => env('LOCKOUT_DECAY_MINUTES', 15),
+];
+```
+
+**理由**：不同環境（測試 = 100 次）可靠 env 覆蓋，不用改程式碼。
+
+### D3：HTTP 423 Locked（帳號鎖定）
+
+**選擇**：回傳 HTTP 423，body `{ status: false, message: "帳號已暫時鎖定，請於 X 分鐘後再試", locked_until: "<ISO8601>" }`
+
+**理由**：
+- 422 / 401 語義不清，423 在 WebDAV 語境下即「資源被鎖定」
+- 前端依 423 顯示靜態鎖定提示（`message` 欄位），不實作倒數；`locked_until` timestamp 保留在 response 供未來擴充
+
+### D4：OAuth state 存 Laravel Session（不存 Cache）
+
+**選擇**：`session()->put('oauth_state', $state)` 於 redirect；callback 讀取並 `session()->pull('oauth_state')` 後以 `hash_equals` 比對。
+
+**實作細節**：Socialite 的 `redirect()` 內部會自行產生 random state 並寫入 `session('state')`，但 URL 裡已被 `.with(['state' => $state])` 換成我們的 state。若不覆蓋，Socialite 的 `user()` 做內建驗證時會因 session 值與 URL 值不符拋出 `InvalidStateException`。解法：在 `redirect()` 呼叫之後、return 之前，再呼叫 `session()->put('state', $state)` 覆蓋，讓兩層驗證（手動 + Socialite 內建）使用同一 state 值。`stateless()` 因此可完全移除。
+
+**理由**：
+- state 是 per-request 一次性值，Session 語義完全對應
+- 移除 `stateless()` 讓 Socialite 內建驗證也生效，雙重保護
+- Cache 方案需自行管理 TTL 與 key 命名，複雜度無謂提升
+
+**替代方案**：PKCE flow → 需要前端配合改 OAuth 啟動方式，改動面太大，此 change 不採用。
+
+### D5：不移除現有 IP throttle
+
+帳號鎖定與 IP throttle 並行：IP throttle 先觸發（429），之後才會累積到帳號鎖定（423）。兩者互不衝突，都保留。
+
+### D6：Email 正規化規則
+
+**選擇**：所有 Cache key 使用前，先對 email 執行 `strtolower(trim($email))`。
+
+**理由**：`User@Gmail.com` 與 `user@gmail.com` 在 RFC 5321 語境下是同一信箱，不正規化會導致攻擊者對同一帳號用大小寫變體繞過計數上限。Trim 防止前後空白導致 key 差異。
+
+**範圍**：同規則套用到計數 key、expires_at key、以及查詢 DB 前的 email 比對。Laravel Eloquent `where('email', ...)` 若 DB collation 為 `utf8mb4_unicode_ci` 則大小寫不敏感，但 Cache key 必須額外正規化。
+
+### D7：不存在帳號不累計失敗計數（已確認）
+
+**選擇**：若 DB 查無此 email，**不**遞增 Cache 計數，但仍回傳 HTTP 401 並使用與密碼錯誤**相同**的泛用訊息（`"電子郵件或密碼錯誤"`），不揭露帳號是否存在。
+
+**理由**：
+- 鎖定機制目的是保護真實帳號；不存在的帳號無帳可鎖
+- 為不存在帳號累計計數會造成 Cache 污染，且攻擊者可製造大量假 email 讓 Cache 暴增
+- 統一 401 訊息確保攻擊者無法透過錯誤回應的差異做帳號枚舉（account enumeration）
+- 已知殘留風險：攻擊者對真實帳號觸發 5 次失敗後可從 423 推斷帳號存在，但此操作本身已受 IP throttle 限速，實際攻擊成本高
+
+**邊界對照**：帳號不存在 → 401（不遞增）；帳號存在但密碼錯 → 401（遞增）；帳號已鎖定 → 423；兩種 401 的 response body 訊息相同。
+
+### D8：TTL / Window 語義 — Fixed Window from First Failure
+
+**選擇**：採用 **Fixed window**，起算點為「**第一次失敗**」。
+
+具體規則：
+1. 查 Cache key `login_failures:{role}:{email}`（email 已正規化）
+2. 若 key **不存在**（count = 0，或 window 已過期）：
+   - `Cache::put('login_failures:{role}:{email}', 1, $decay_minutes * 60)`
+   - 同時寫入 `login_expires_at:{role}:{email}` = `now()->addMinutes($decay_minutes)->toIso8601String()`，TTL 相同
+3. 若 key **存在**（count ≥ 1）：
+   - `Cache::increment('login_failures:{role}:{email}')`（**不重設 TTL**，window 不延長）
+4. 若遞增後 count ≥ max_attempts：回傳 HTTP 423
+
+**理由**：Sliding window（每次失敗延長 TTL）對合法使用者懲罰過重——誤輸密碼後，每一次重試都重置等待時間，實際上永遠解不了鎖。Fixed window 可預測：「最多等 decay_minutes 分鐘」，對使用者友善。
+
+**替代方案**：Sliding window → 否決，原因同上。
+
+### D9：`locked_until` 的資料來源 — Companion Key
+
+**選擇**：第一次失敗時同步寫入 companion key `login_expires_at:{role}:{email}`，值為 ISO 8601 字串，TTL 與計數 key 相同。每次回傳 HTTP 423 時讀取此 key 作為 `locked_until` 欄位值。
+
+**理由**：
+- Laravel Cache 不保證所有 driver 提供 `getExpiry()` API（file driver 無此方法）
+- Companion key 方案不依賴 driver 實作細節，跨 file / Redis driver 行為一致
+- 兩個 key 的 TTL 相同，到期時同步消失，無需額外清理
+
+**Fallback**：若 `login_expires_at` key 因 driver 不一致或 race condition 缺失，fallback 為 `now()->addMinutes($decay_minutes)->toIso8601String()` 並寫 `Log::warning`。
+
+### D10：Cache Key Namespace 正式定義
+
+**完整 key 格式**：
+
+| Key 用途 | 格式 | 有效 role 值 |
+|---------|------|------------|
+| 失敗計數 | `login_failures:{role}:{normalized_email}` | `member`、`provider` |
+| 鎖定到期時間 | `login_expires_at:{role}:{normalized_email}` | `member`、`provider` |
+
+`{role}` 的值與 API 路徑對應：`/api/member/login` → `member`；`/api/provider/login` → `provider`。`admin` 明確不在此 change 範圍，不建立任何相關 key。
+
+`{normalized_email}` = `strtolower(trim($request->email))`，於 controller 頂部完成正規化，後續所有 Cache 操作一律使用正規化後的值。
+
+### D11：登入端點 Response Semantics 完整對照表
+
+以下為 Member / Provider 登入端點所有可能回應的**完整定義**，用於消除實作端的歧義：
+
+| 情境 | 檢查順序 | HTTP | Response Body |
+|------|---------|------|---------------|
+| 帳號已在目前 lockout window 內（lockout active） | 1st | 423 | `{ status: false, message: "帳號已暫時鎖定，請於 N 分鐘後再試", locked_until: "<ISO8601>" }` |
+| 帳號不存在（DB 查無 email） | 2nd | 401 | `{ status: false, message: "電子郵件或密碼錯誤" }` |
+| 帳號存在，密碼錯誤，失敗 1–4 次（未達閾值） | 3rd | 401 | `{ status: false, message: "電子郵件或密碼錯誤" }` |
+| 帳號存在，密碼錯誤，**第 5 次**（觸發鎖定） | 3rd | 423 | `{ status: false, message: "帳號已暫時鎖定，請於 N 分鐘後再試", locked_until: "<ISO8601>" }` |
+| 帳號存在，密碼正確 | 3rd | 200 | `{ status: true, data: { token: "...", user: {...} } }` |
+
+**檢查順序說明**：
+1. 先查 Cache 判斷是否已鎖定（最快路徑，不進 DB）
+2. 再查 DB 確認帳號存在（帳號不存在 → 401，不遞增計數）
+3. 最後驗證密碼（錯誤 → 遞增計數 → 若達閾值回 423，否則 401；正確 → 200 + 清計數）
+
+`message` 中的 `N` 為靜態設定值（`decay_minutes`），不是即時計算的剩餘分鐘數。前端**不實作**剩餘時間倒數；`locked_until` 欄位保留於 response 以備未來若需精確倒數時使用。
+
+### D12：OAuth 多分頁並發 Flow 的預期行為
+
+**選擇**：同一瀏覽器同一 session 下，**只有最後一個啟動的 OAuth flow 能成功**；先啟動的 tab 的 callback 因 state 不符而收到 HTTP 400，前端引導使用者重新操作。此行為為**設計預期**，不視為 bug。
+
+**理由**：
+- Laravel session 在同一瀏覽器共用（相同 session cookie），後寫的 `oauth_state` 覆蓋先寫的
+- 支援多個並發 state 需在 session 中維護 state 陣列（push/find/remove），複雜度不符現階段需求
+- 使用者實際上幾乎不會在兩個 tab 同時進行 Google OAuth；若發生，400 → redirect `/login?error=oauth_failed` 是合理的 UX 引導
+
+**替代方案**：Session 存 state 陣列（每次 redirect 前 push，callback 時 find & remove）→ 否決，目前無真實使用場景，過度設計。
+
+## Risks / Trade-offs
+
+- **[DoS 風險] 攻擊者刻意鎖定合法帳號** → 攻擊者只要知道 email 就能讓帳號鎖 15 分鐘。緩解：IP throttle 已先擋，15 分鐘鎖定時間短，影響有限；金流上線前再評估是否加 CAPTCHA。
+- **[Account Enumeration Trade-off] 不存在帳號不累計失敗計數** → 可避免攻擊者以大量假 email 汙染 Cache，但攻擊者理論上仍可透過 repeated attempts 是否最終進入 423，間接推測帳號存在與否。本 change 接受此風險，先以統一 401 訊息與既有 IP throttle 緩解；若未來威脅模型提高，再評估改為對不存在帳號也累計或加入 CAPTCHA。
+- **[Cache 遺失] file cache 重啟後失效** → 鎖定計數不持久，重啟即解鎖。生產環境預設使用 Redis（`.env` `CACHE_DRIVER=redis`），計數跨容器共享且重啟不失效；file cache 可運作但效果較差（計數不跨容器、重啟清零），僅適用於 dev 環境。
+- **[Session 相容] 移除 stateless() 後需 session driver 正常運作** → Docker 環境 session driver 使用 file，確認 storage/framework/sessions 有寫入權限即可。
+
+## Migration Plan
+
+1. 部署時無 DB migration（Cache 方案不需 migration）
+2. **生產環境** `.env` 確認 `CACHE_DRIVER=redis`（Redis 為生產預設，確保計數跨容器共享）
+3. `.env` 可選加：`LOCKOUT_MAX_ATTEMPTS=5`、`LOCKOUT_DECAY_MINUTES=15`（有預設值，不加也可）
+4. OAuth state 改動：session driver 已在 dev 正常使用，無需額外設定
+5. Rollback：移除兩個 feature 的 controller 邏輯，恢復 `stateless()`；不需 DB rollback
+
+## Open Questions
+
+~~是否在前端 LoginView 顯示「剩餘鎖定時間」倒數？~~ → **已決定**：不實作倒數，只顯示靜態 `message`；`locked_until` 保留於 response 供未來擴充。
+
+~~生產環境 Cache driver 是否確定為 Redis？~~ → **已決定**：生產環境預設 Redis（`CACHE_DRIVER=redis`）；file cache 可運作但效果較差，不建議用於生產。
@@ -0,0 +1,38 @@
+## Why
+
+IP-based throttle（P0 已實作）只能防單一 IP 暴力攻擊，無法阻擋分散式密碼暴破（攻擊者用多 IP 對同一帳號嘗試）；OAuth 流程目前以 `stateless()` 繞過 CSRF 驗證，存在被偽造授權碼的風險。在金流整合上線前先補齊這兩個帳號層防護，可大幅降低帳號接管與 OAuth CSRF 風險。
+
+## What Changes
+
+- **新增帳號層鎖定機制**：Member / Provider 登入連續失敗 N 次後，鎖定該帳號（而非 IP），鎖定期間回傳 HTTP 423；鎖定計數以 Laravel Cache 儲存，N 分鐘後自動解鎖。
+- **新增 OAuth state 驗證**：`SocialAuthController` 產生隨機 state 字串存入 session，callback 時驗證 state 是否吻合；不吻合時拒絕並回傳 HTTP 400；移除 `stateless()` 呼叫。
+
+## Capabilities
+
+### New Capabilities
+
+- `account-lockout`：帳號層連續失敗鎖定，覆蓋 Member / Provider 登入流程（Admin 登入失敗計數另行討論，暫不列入）
+- `oauth-state-validation`：OAuth CSRF 防護，補 state parameter 生成與驗證，適用 Member Google OAuth 流程
+
+### Modified Capabilities
+
+- `login-rate-limiting`：無需變更需求（IP throttle 與帳號鎖定並行，各自獨立，Requirement 不衝突）
+
+## Impact
+
+**後端**
+- `app/Http/Controllers/API/AuthController.php`（Member login）
+- `app/Http/Controllers/API/ProviderAuthController.php`（Provider login）
+- `app/Http/Controllers/API/SocialAuthController.php`（OAuth redirect / callback）
+- `routes/api.php`（可能新增解鎖端點）
+- `config/auth_lockout.php`（鎖定參數：最大失敗次數、鎖定時間）
+- Laravel Cache（驗證失敗計數，driver 使用現有 Redis 或 file）
+
+**前端**
+- `src/views/LoginView.vue` / `CoachLoginView.vue`：顯示「帳號已鎖定，請稍後再試」錯誤訊息（HTTP 423 對應）
+- `src/plugins/echo.js` / `src/api/axios.js`：無需變更（OAuth callback 不走 Axios）
+- `src/views/AuthCallbackView.vue`：無需變更（後端回傳 400 時 redirect 到 login 並帶錯誤訊息）
+
+**不影響**
+- 現有 Sanctum token、sessionStorage、refresh interceptor
+- Admin Panel（Admin 登入鎖定不在此 change 範圍）
@@ -0,0 +1,104 @@
+## ADDED Requirements
+
+### Requirement: Cache Key Namespace
+後端 SHALL 使用以下格式的 Cache key，`{role}` 僅允許 `member` 或 `provider` 兩個值，對應各自的登入端點；`{email}` 為 `strtolower(trim($request->email))` 正規化後的結果。
+
+| Key 用途 | 格式 |
+|---------|------|
+| 失敗計數 | `login_failures:{role}:{email}` |
+| 鎖定到期時間 | `login_expires_at:{role}:{email}` |
+
+#### Scenario: role 值與端點對應
+- **WHEN** Member 登入失敗
+- **THEN** 使用 key `login_failures:member:{email}` 與 `login_expires_at:member:{email}`
+
+#### Scenario: Provider 與 Member 計數互相隔離
+- **WHEN** 同一個 email 在 Member 端點失敗 4 次，再到 Provider 端點失敗 4 次
+- **THEN** 兩個 role namespace 各自獨立，均未達閾值，均不觸發鎖定
+
+### Requirement: 帳號層登入失敗鎖定
+後端 SHALL 追蹤每個帳號（以正規化 email 為 key）的登入失敗次數。計數採用 **Fixed Window**：第一次失敗時建立 Cache key 並設 TTL = `decay_minutes * 60` 秒，後續失敗只遞增計數而**不重設 TTL**（window 不延長）。當失敗次數達到閾值（預設 5 次）時，系統 SHALL 鎖定該帳號，鎖定期間任何密碼登入 SHALL 被拒絕並回傳 HTTP 423（含 `locked_until` ISO 8601 欄位），直到 Cache key 自然過期。`locked_until` 的值來源為第一次失敗時同步寫入的 companion key `login_expires_at:{role}:{email}`。
+
+**登入端點完整 Response Semantics**（按後端處理順序）：
+
+| 情境 | 檢查順序 | HTTP | Response Body 重點欄位 |
+|------|---------|------|----------------------|
+| 帳號已鎖定（Cache 計數 ≥ max_attempts） | 1st | 423 | `message: "帳號已暫時鎖定..."`, `locked_until: "<ISO8601>"` |
+| 帳號不存在（DB 查無 email） | 2nd | 401 | `message: "電子郵件或密碼錯誤"` |
+| 帳號存在，密碼錯，失敗 1–4 次 | 3rd | 401 | `message: "電子郵件或密碼錯誤"` |
+| 帳號存在，密碼錯，**第 5 次**（當場觸發鎖定） | 3rd | 423 | `message: "帳號已暫時鎖定..."`, `locked_until: "<ISO8601>"` |
+| 帳號存在，密碼正確 | 3rd | 200 | `token`, `user` |
+
+「帳號不存在」與「密碼錯誤 1–4 次」的 HTTP status 和 message SHALL 完全相同，不得有任何可區分的差異（防帳號枚舉）。
+
+#### Scenario: 未達閾值的登入失敗
+- **WHEN** 帳號在 15 分鐘內累計失敗次數少於 5 次
+- **THEN** 系統正常回傳 HTTP 401，`failed_attempts` 計數遞增，帳號不鎖定
+
+#### Scenario: 第 5 次失敗觸發鎖定
+- **WHEN** 帳號在 15 分鐘內第 5 次登入失敗
+- **THEN** 系統回傳 HTTP 423，body 包含 `{ status: false, message: "帳號已暫時鎖定，請於 15 分鐘後再試", locked_until: "<ISO8601 timestamp>" }`，後續任何密碼登入均被拒絕直到時間到期
+
+#### Scenario: 鎖定期間嘗試登入
+- **WHEN** 帳號處於鎖定狀態，使用者送出任何 email/password 組合
+- **THEN** 系統不驗證密碼，直接回傳 HTTP 423 並附帶 `locked_until` 欄位
+
+#### Scenario: 登入成功後清除失敗計數
+- **WHEN** 使用者在未達閾值前成功登入
+- **THEN** 系統清除該帳號的失敗計數，下次失敗從 0 重新累積
+
+#### Scenario: 鎖定時間到期自動解鎖
+- **WHEN** 帳號鎖定後超過 15 分鐘未有新登入嘗試
+- **THEN** 鎖定計數自動過期（Cache TTL），帳號恢復可登入狀態
+
+#### Scenario: 鎖定機制覆蓋 Member 與 Provider
+- **WHEN** Member（`/api/member/login`）或 Provider（`/api/provider/login`）觸發連續失敗
+- **THEN** 各自以 email 為 key 獨立計數，互不干擾
+
+#### Scenario: Fixed window — 失敗不延長鎖定時間
+- **WHEN** 帳號在 window 內第 3 次失敗（尚未達閾值），之後又再失敗 1 次
+- **THEN** TTL **不重設**；`locked_until` 仍為第一次失敗時計算的到期時間
+
+#### Scenario: `locked_until` 來自 companion key
+- **WHEN** 系統回傳 HTTP 423
+- **THEN** response body 的 `locked_until` 欄位值等於 `login_expires_at:{role}:{email}` Cache key 的儲存值（ISO 8601），即第一次失敗時計算的 `now + decay_minutes`
+
+### Requirement: 不存在帳號不累計失敗計數
+後端 SHALL 在遞增失敗計數**前**先查詢 DB 確認帳號是否存在。若查無此 email，SHALL 直接回傳 HTTP 401，訊息與密碼錯誤**相同**（`"電子郵件或密碼錯誤"`），**不**遞增任何 Cache 計數。
+
+#### Scenario: 不存在帳號登入失敗
+- **WHEN** 使用者以一個 DB 中不存在的 email 嘗試登入
+- **THEN** 系統回傳 HTTP 401，body `{ status: false, message: "電子郵件或密碼錯誤" }`，Cache 中**不建立也不遞增**任何此 email 的失敗計數
+
+#### Scenario: 錯誤訊息無法區分帳號不存在與密碼錯誤
+- **WHEN** 帳號不存在 vs. 帳號存在但密碼錯誤，兩種情境均發生
+- **THEN** 兩者 HTTP status 相同（401），response body 訊息相同，攻擊者無法透過回應差異做帳號枚舉
+
+### Requirement: Email 正規化
+後端 SHALL 在所有涉及鎖定計數的操作前，對 email 執行 `strtolower(trim($email))`，確保大小寫變體與前後空白不影響計數的正確性。
+
+#### Scenario: Email 大小寫變體視為同一帳號
+- **WHEN** 攻擊者用 `User@Gmail.com`、`user@gmail.com`、`USER@GMAIL.COM` 依序嘗試登入同一帳號
+- **THEN** 三次嘗試累計到同一個計數 key，共累計 3 次失敗
+
+### Requirement: 鎖定閾值可由環境變數設定
+後端 SHALL 從 `config/auth_lockout.php` 讀取鎖定參數，允許透過 `.env` 覆蓋 `LOCKOUT_MAX_ATTEMPTS`（預設 5）與 `LOCKOUT_DECAY_MINUTES`（預設 15）。
+
+#### Scenario: 使用預設值
+- **WHEN** `.env` 未設定 `LOCKOUT_MAX_ATTEMPTS` / `LOCKOUT_DECAY_MINUTES`
+- **THEN** 系統使用 5 次 / 15 分鐘作為鎖定參數
+
+#### Scenario: 透過 env 覆蓋閾值
+- **WHEN** `.env` 設定 `LOCKOUT_MAX_ATTEMPTS=10`
+- **THEN** 系統以 10 次失敗後才鎖定
+
+### Requirement: 前端顯示帳號鎖定訊息
+前端 SHALL 在接收到 HTTP 423 時，顯示「帳號已暫時鎖定」的明確提示，而非泛用的「帳密錯誤」訊息。
+
+#### Scenario: Member 登入頁收到 423
+- **WHEN** `LoginView.vue` 的登入請求收到 HTTP 423
+- **THEN** 顯示 response body 中的 `message` 欄位內容（如「帳號已暫時鎖定，請於 15 分鐘後再試」）
+
+#### Scenario: Provider 登入頁收到 423
+- **WHEN** `CoachLoginView.vue` 的登入請求收到 HTTP 423
+- **THEN** 同上，顯示鎖定提示訊息
@@ -0,0 +1,35 @@
+## ADDED Requirements
+
+### Requirement: OAuth 授權流程帶 state 參數防 CSRF
+後端 SHALL 在 OAuth redirect 前產生隨機 state 字串（至少 32 bytes hex），存入 `session('oauth_state')`，並附加於 OAuth redirect URL 的 `state` query parameter。`stateless()` 呼叫 SHALL 被移除；Socialite 在 `redirect()` 內會自行寫入 `session('state')`，實作 SHALL 在 `redirect()` 呼叫後以同一 state 值覆蓋 `session('state')`，確保 Socialite 內建驗證與手動驗證使用相同值。callback 時 SHALL 從 request 讀取 `state` 並與 `session('oauth_state')` 比對（`hash_equals`）；比對成功後 SHALL 立即清除；不符或缺少時 SHALL redirect 至 `/login?error=oauth_failed`。
+
+#### Scenario: 正常 OAuth 登入流程
+- **WHEN** 使用者點擊「Google 登入」，後端發出 redirect
+- **THEN** redirect URL 包含 `state=<random>` 參數，且相同 random 值存入 session；使用者在 Google 完成授權後，callback 帶回相同 state，後端驗證通過，繼續正常登入流程
+
+#### Scenario: state 缺失（直接訪問 callback）
+- **WHEN** 攻擊者或使用者直接訪問 `/auth/google/callback` 而不帶 `state` 參數
+- **THEN** 後端 redirect 瀏覽器至 `{frontend_url}/login?error=oauth_failed`，不繼續登入流程
+
+#### Scenario: state 不符（CSRF 攻擊）
+- **WHEN** callback 帶的 `state` 與 `session('oauth_state')` 中的值不一致
+- **THEN** 後端 redirect 瀏覽器至 `{frontend_url}/login?error=oauth_failed`，不繼續登入流程
+
+#### Scenario: state 只能使用一次
+- **WHEN** callback 驗證 state 成功後（`session()->pull('oauth_state')` 已清除），再次以相同 state 訪問 callback
+- **THEN** session 中已無 `oauth_state`，視為 state 缺失，同樣 redirect 至 `/login?error=oauth_failed`
+
+#### Scenario: 登入頁顯示 OAuth 失敗訊息
+- **WHEN** 瀏覽器被 redirect 至 `/login?error=oauth_failed`
+- **THEN** `LoginView.vue` 偵測到 `route.query.error === 'oauth_failed'`，顯示「OAuth 授權失敗，請重新嘗試」提示；`AuthCallbackView.vue` 不涉及此錯誤流程
+
+#### Scenario: 多分頁並發 OAuth flow — 只有最後啟動的成功（預期行為）
+- **WHEN** 使用者在同一瀏覽器開兩個 tab，Tab A 先啟動 OAuth（session 寫入 state_A），Tab B 後啟動 OAuth（session 覆寫為 state_B），Tab A 的 callback 先到達後端
+- **THEN** Tab A 的 callback 帶 state_A，與 session 中的 state_B 不符，後端 redirect 至 `/login?error=oauth_failed`；Tab B 的 callback 帶 state_B，比對成功，正常完成登入
+
+### Requirement: OAuth session driver 正常運作
+後端 SHALL 確保 session driver 在 Docker 環境中可寫入（`storage/framework/sessions` 目錄存在且有寫入權限），以支援 state 存取。
+
+#### Scenario: Session 寫入成功
+- **WHEN** OAuth redirect 觸發時
+- **THEN** state 值成功寫入 session，無 500 錯誤
@@ -0,0 +1,36 @@
+## 1. 帳號鎖定設定檔與共用 Helper
+
+- [x] 1.1 [後端] 建立 `config/auth_lockout.php`，定義 `max_attempts`（env `LOCKOUT_MAX_ATTEMPTS`, 預設 5）與 `decay_minutes`（env `LOCKOUT_DECAY_MINUTES`, 預設 15）
+- [x] 1.2 [後端] 建立 `app/Traits/NormalizesEmail.php` Trait，定義 `normalizeEmail(string $email): string`（`strtolower(trim($email))`），在 `AuthController` 與 `ProviderAuthController` 均 use 此 Trait
+
+## 2. Member 帳號鎖定邏輯
+
+- [x] 2.1 [後端] 修改 `app/Http/Controllers/API/AuthController.php` → `loginMember()`：對 request email 執行 `strtolower(trim())` 正規化後，先查 Cache key `login_failures:member:{email}`，若已達閾值讀取 `login_expires_at:member:{email}` 回傳 HTTP 423（含 `locked_until`）
+- [x] 2.2 [後端] DB 查無帳號時直接回傳 HTTP 401（訊息與密碼錯誤相同），**不**遞增計數
+- [x] 2.3 [後端] 登入失敗（帳號存在但密碼錯）時：若 `login_failures` key 不存在則用 `Cache::put()` 設初始值 1 並同步寫入 `login_expires_at` companion key（TTL 相同）；若 key 已存在則只 `Cache::increment()`（不重設 TTL）；回傳 423 時讀取 `login_expires_at` key，若缺失則 fallback 為 `now()->addMinutes($decay_minutes)` 並寫 `Log::warning`
+- [x] 2.4 [後端] 登入成功時 `Cache::forget('login_failures:member:{email}')` 與 `Cache::forget('login_expires_at:member:{email}')`
+
+## 3. Provider 帳號鎖定邏輯
+
+- [x] 3.1 [後端] 修改 `app/Http/Controllers/API/ProviderAuthController.php` → `loginProvider()`：同 Member 邏輯（email 正規化、不存在帳號不遞增、companion key、fixed window），Cache key 前綴改為 `login_failures:provider:` / `login_expires_at:provider:`
+- [x] 3.2 [後端] 登入成功時清除兩個 Cache key（failures + expires_at）
+
+## 4. OAuth State 驗證
+
+- [x] 4.1 [後端] 修改 `app/Http/Controllers/API/SocialAuthController.php` → `redirectToProvider()`：移除 `stateless()`，產生 `bin2hex(random_bytes(32))` 存 `session('oauth_state')`，附加 `state` 於 redirect URL
+- [x] 4.2 [後端] 修改 `handleProviderCallback()`：移除 `stateless()`，讀取 `request->state` 與 `session('oauth_state')` 比對；不符或缺失時回傳 HTTP 400；比對後立即 `session()->forget('oauth_state')`
+
+## 5. 前端錯誤處理
+
+- [x] 5.1 [前端] 修改 `frontend/src/views/LoginView.vue`：axios catch 中判斷 `error.response?.status === 423`，顯示 `response.data.message`（帳號鎖定提示），而非泛用錯誤
+- [x] 5.2 [前端] 修改 `frontend/src/views/CoachLoginView.vue`：同上，處理 423 狀態碼
+- [x] 5.3 [前端] 修改 `frontend/src/views/AuthCallbackView.vue`：當後端 OAuth callback 回傳 400 時，redirect 至 `/login?error=oauth_failed`
+- [x] 5.4 [前端] 修改 `frontend/src/views/LoginView.vue`：若 `route.query.error === 'oauth_failed'`，顯示「OAuth 授權失敗，請重新嘗試」提示
+
+## 6. 整合驗證
+
+- [x] 6.1 [整合測試] 手動測試 Member 登入：連續失敗 5 次後收到 423，等待 15 分鐘後或改正確密碼（需清除 Cache）後可登入
+- [x] 6.2 [整合測試] 手動測試 Provider 登入：同上
+- [x] 6.3 [整合測試] 手動測試 OAuth：正常流程可完成；直接訪問 callback URL（無 state）收到 400 並 redirect 至 `/login?error=oauth_failed`
+- [x] 6.4 [整合測試] 確認 `storage/framework/sessions` 目錄在 Docker 容器中有寫入權限（session 存 state 不報錯）
+- [x] 6.5 [部署] 確認生產環境 `.env` 設定 `CACHE_DRIVER=redis`；驗證方式：`php artisan tinker` → `Cache::put('test', 1, 10); Cache::get('test');` 回傳 1 即 Redis 正常
@@ -0,0 +1,104 @@
+## ADDED Requirements
+
+### Requirement: Cache Key Namespace
+後端 SHALL 使用以下格式的 Cache key，`{role}` 僅允許 `member` 或 `provider` 兩個值，對應各自的登入端點；`{email}` 為 `strtolower(trim($request->email))` 正規化後的結果。
+
+| Key 用途 | 格式 |
+|---------|------|
+| 失敗計數 | `login_failures:{role}:{email}` |
+| 鎖定到期時間 | `login_expires_at:{role}:{email}` |
+
+#### Scenario: role 值與端點對應
+- **WHEN** Member 登入失敗
+- **THEN** 使用 key `login_failures:member:{email}` 與 `login_expires_at:member:{email}`
+
+#### Scenario: Provider 與 Member 計數互相隔離
+- **WHEN** 同一個 email 在 Member 端點失敗 4 次，再到 Provider 端點失敗 4 次
+- **THEN** 兩個 role namespace 各自獨立，均未達閾值，均不觸發鎖定
+
+### Requirement: 帳號層登入失敗鎖定
+後端 SHALL 追蹤每個帳號（以正規化 email 為 key）的登入失敗次數。計數採用 **Fixed Window**：第一次失敗時建立 Cache key 並設 TTL = `decay_minutes * 60` 秒，後續失敗只遞增計數而**不重設 TTL**（window 不延長）。當失敗次數達到閾值（預設 5 次）時，系統 SHALL 鎖定該帳號，鎖定期間任何密碼登入 SHALL 被拒絕並回傳 HTTP 423（含 `locked_until` ISO 8601 欄位），直到 Cache key 自然過期。`locked_until` 的值來源為第一次失敗時同步寫入的 companion key `login_expires_at:{role}:{email}`。
+
+**登入端點完整 Response Semantics**（按後端處理順序）：
+
+| 情境 | 檢查順序 | HTTP | Response Body 重點欄位 |
+|------|---------|------|----------------------|
+| 帳號已鎖定（Cache 計數 ≥ max_attempts） | 1st | 423 | `message: "帳號已暫時鎖定..."`, `locked_until: "<ISO8601>"` |
+| 帳號不存在（DB 查無 email） | 2nd | 401 | `message: "電子郵件或密碼錯誤"` |
+| 帳號存在，密碼錯，失敗 1–4 次 | 3rd | 401 | `message: "電子郵件或密碼錯誤"` |
+| 帳號存在，密碼錯，**第 5 次**（當場觸發鎖定） | 3rd | 423 | `message: "帳號已暫時鎖定..."`, `locked_until: "<ISO8601>"` |
+| 帳號存在，密碼正確 | 3rd | 200 | `token`, `user` |
+
+「帳號不存在」與「密碼錯誤 1–4 次」的 HTTP status 和 message SHALL 完全相同，不得有任何可區分的差異（防帳號枚舉）。
+
+#### Scenario: 未達閾值的登入失敗
+- **WHEN** 帳號在 15 分鐘內累計失敗次數少於 5 次
+- **THEN** 系統正常回傳 HTTP 401，`failed_attempts` 計數遞增，帳號不鎖定
+
+#### Scenario: 第 5 次失敗觸發鎖定
+- **WHEN** 帳號在 15 分鐘內第 5 次登入失敗
+- **THEN** 系統回傳 HTTP 423，body 包含 `{ status: false, message: "帳號已暫時鎖定，請於 15 分鐘後再試", locked_until: "<ISO8601 timestamp>" }`，後續任何密碼登入均被拒絕直到時間到期
+
+#### Scenario: 鎖定期間嘗試登入
+- **WHEN** 帳號處於鎖定狀態，使用者送出任何 email/password 組合
+- **THEN** 系統不驗證密碼，直接回傳 HTTP 423 並附帶 `locked_until` 欄位
+
+#### Scenario: 登入成功後清除失敗計數
+- **WHEN** 使用者在未達閾值前成功登入
+- **THEN** 系統清除該帳號的失敗計數，下次失敗從 0 重新累積
+
+#### Scenario: 鎖定時間到期自動解鎖
+- **WHEN** 帳號鎖定後超過 15 分鐘未有新登入嘗試
+- **THEN** 鎖定計數自動過期（Cache TTL），帳號恢復可登入狀態
+
+#### Scenario: 鎖定機制覆蓋 Member 與 Provider
+- **WHEN** Member（`/api/member/login`）或 Provider（`/api/provider/login`）觸發連續失敗
+- **THEN** 各自以 email 為 key 獨立計數，互不干擾
+
+#### Scenario: Fixed window — 失敗不延長鎖定時間
+- **WHEN** 帳號在 window 內第 3 次失敗（尚未達閾值），之後又再失敗 1 次
+- **THEN** TTL **不重設**；`locked_until` 仍為第一次失敗時計算的到期時間
+
+#### Scenario: `locked_until` 來自 companion key
+- **WHEN** 系統回傳 HTTP 423
+- **THEN** response body 的 `locked_until` 欄位值等於 `login_expires_at:{role}:{email}` Cache key 的儲存值（ISO 8601），即第一次失敗時計算的 `now + decay_minutes`
+
+### Requirement: 不存在帳號不累計失敗計數
+後端 SHALL 在遞增失敗計數**前**先查詢 DB 確認帳號是否存在。若查無此 email，SHALL 直接回傳 HTTP 401，訊息與密碼錯誤**相同**（`"電子郵件或密碼錯誤"`），**不**遞增任何 Cache 計數。
+
+#### Scenario: 不存在帳號登入失敗
+- **WHEN** 使用者以一個 DB 中不存在的 email 嘗試登入
+- **THEN** 系統回傳 HTTP 401，body `{ status: false, message: "電子郵件或密碼錯誤" }`，Cache 中**不建立也不遞增**任何此 email 的失敗計數
+
+#### Scenario: 錯誤訊息無法區分帳號不存在與密碼錯誤
+- **WHEN** 帳號不存在 vs. 帳號存在但密碼錯誤，兩種情境均發生
+- **THEN** 兩者 HTTP status 相同（401），response body 訊息相同，攻擊者無法透過回應差異做帳號枚舉
+
+### Requirement: Email 正規化
+後端 SHALL 在所有涉及鎖定計數的操作前，對 email 執行 `strtolower(trim($email))`，確保大小寫變體與前後空白不影響計數的正確性。
+
+#### Scenario: Email 大小寫變體視為同一帳號
+- **WHEN** 攻擊者用 `User@Gmail.com`、`user@gmail.com`、`USER@GMAIL.COM` 依序嘗試登入同一帳號
+- **THEN** 三次嘗試累計到同一個計數 key，共累計 3 次失敗
+
+### Requirement: 鎖定閾值可由環境變數設定
+後端 SHALL 從 `config/auth_lockout.php` 讀取鎖定參數，允許透過 `.env` 覆蓋 `LOCKOUT_MAX_ATTEMPTS`（預設 5）與 `LOCKOUT_DECAY_MINUTES`（預設 15）。
+
+#### Scenario: 使用預設值
+- **WHEN** `.env` 未設定 `LOCKOUT_MAX_ATTEMPTS` / `LOCKOUT_DECAY_MINUTES`
+- **THEN** 系統使用 5 次 / 15 分鐘作為鎖定參數
+
+#### Scenario: 透過 env 覆蓋閾值
+- **WHEN** `.env` 設定 `LOCKOUT_MAX_ATTEMPTS=10`
+- **THEN** 系統以 10 次失敗後才鎖定
+
+### Requirement: 前端顯示帳號鎖定訊息
+前端 SHALL 在接收到 HTTP 423 時，顯示「帳號已暫時鎖定」的明確提示，而非泛用的「帳密錯誤」訊息。
+
+#### Scenario: Member 登入頁收到 423
+- **WHEN** `LoginView.vue` 的登入請求收到 HTTP 423
+- **THEN** 顯示 response body 中的 `message` 欄位內容（如「帳號已暫時鎖定，請於 15 分鐘後再試」）
+
+#### Scenario: Provider 登入頁收到 423
+- **WHEN** `CoachLoginView.vue` 的登入請求收到 HTTP 423
+- **THEN** 同上，顯示鎖定提示訊息
@@ -0,0 +1,35 @@
+## ADDED Requirements
+
+### Requirement: OAuth 授權流程帶 state 參數防 CSRF
+後端 SHALL 在 OAuth redirect 前產生隨機 state 字串（至少 32 bytes hex），存入 `session('oauth_state')`，並附加於 OAuth redirect URL 的 `state` query parameter。`stateless()` 呼叫 SHALL 被移除；Socialite 在 `redirect()` 內會自行寫入 `session('state')`，實作 SHALL 在 `redirect()` 呼叫後以同一 state 值覆蓋 `session('state')`，確保 Socialite 內建驗證與手動驗證使用相同值。callback 時 SHALL 從 request 讀取 `state` 並與 `session('oauth_state')` 比對（`hash_equals`）；比對成功後 SHALL 立即清除；不符或缺少時 SHALL redirect 至 `/login?error=oauth_failed`。
+
+#### Scenario: 正常 OAuth 登入流程
+- **WHEN** 使用者點擊「Google 登入」，後端發出 redirect
+- **THEN** redirect URL 包含 `state=<random>` 參數，且相同 random 值存入 session；使用者在 Google 完成授權後，callback 帶回相同 state，後端驗證通過，繼續正常登入流程
+
+#### Scenario: state 缺失（直接訪問 callback）
+- **WHEN** 攻擊者或使用者直接訪問 `/auth/google/callback` 而不帶 `state` 參數
+- **THEN** 後端 redirect 瀏覽器至 `{frontend_url}/login?error=oauth_failed`，不繼續登入流程
+
+#### Scenario: state 不符（CSRF 攻擊）
+- **WHEN** callback 帶的 `state` 與 `session('oauth_state')` 中的值不一致
+- **THEN** 後端 redirect 瀏覽器至 `{frontend_url}/login?error=oauth_failed`，不繼續登入流程
+
+#### Scenario: state 只能使用一次
+- **WHEN** callback 驗證 state 成功後（`session()->pull('oauth_state')` 已清除），再次以相同 state 訪問 callback
+- **THEN** session 中已無 `oauth_state`，視為 state 缺失，同樣 redirect 至 `/login?error=oauth_failed`
+
+#### Scenario: 登入頁顯示 OAuth 失敗訊息
+- **WHEN** 瀏覽器被 redirect 至 `/login?error=oauth_failed`
+- **THEN** `LoginView.vue` 偵測到 `route.query.error === 'oauth_failed'`，顯示「OAuth 授權失敗，請重新嘗試」提示；`AuthCallbackView.vue` 不涉及此錯誤流程
+
+#### Scenario: 多分頁並發 OAuth flow — 只有最後啟動的成功（預期行為）
+- **WHEN** 使用者在同一瀏覽器開兩個 tab，Tab A 先啟動 OAuth（session 寫入 state_A），Tab B 後啟動 OAuth（session 覆寫為 state_B），Tab A 的 callback 先到達後端
+- **THEN** Tab A 的 callback 帶 state_A，與 session 中的 state_B 不符，後端 redirect 至 `/login?error=oauth_failed`；Tab B 的 callback 帶 state_B，比對成功，正常完成登入
+
+### Requirement: OAuth session driver 正常運作
+後端 SHALL 確保 session driver 在 Docker 環境中可寫入（`storage/framework/sessions` 目錄存在且有寫入權限），以支援 state 存取。
+
+#### Scenario: Session 寫入成功
+- **WHEN** OAuth redirect 觸發時
+- **THEN** state 值成功寫入 session，無 500 錯誤
@@ -28,7 +28,7 @@ Route::get('/diving-offers/{id}/reviews',  [ReviewController::class, 'publicList

 // 會員註冊／登入
 Route::post('/member/register', [AuthController::class, 'registerMember']);
-Route::middleware('throttle:5,1')->post('/member/login', [AuthController::class, 'loginMember']);
+Route::middleware('throttle:10,1')->post('/member/login', [AuthController::class, 'loginMember']);

 // Google 第三方登入（僅會員）
 Route::get('/auth/google/redirect', [\App\Http\Controllers\API\SocialAuthController::class, 'redirectToGoogle']);
@@ -62,7 +62,7 @@ Route::middleware('auth:sanctum')->post('/reviews/{id}/helpful', [ReviewControll

 // 服務提供者註冊／登入
 Route::post('/provider/register', [AuthController::class, 'registerProvider']);
-Route::middleware('throttle:5,1')->post('/provider/login', [AuthController::class, 'loginProvider']);
+Route::middleware('throttle:10,1')->post('/provider/login', [AuthController::class, 'loginProvider']);

 // 服務提供者專屬 API（需登入）
 Route::middleware(['auth:sanctum'])->prefix('provider')->group(function () {