CFDivePlatform/openspec/changes/archive/2026-06-02-auth-p1-token-refresh/design.md

Context

P0 完成後，Bearer Token 有 7 天過期保護，但缺少自動續期機制，且 token 仍存於 localStorage（XSS 可讀）。此 change 引入 sliding window refresh 搭配 sessionStorage，兩者互相依賴：sessionStorage 在分頁/瀏覽器關閉後清除 token；refresh 機制確保 token 在主動使用期間不過期，兩者缺一則安全性或 UX 有所折損。

Goals / Non-Goals

Goals:

• Token 在主動使用期間無限 sliding，不需手動重新登入
• Token 改存 sessionStorage，關閉分頁/瀏覽器後自動清除
• 多個並發 401 只觸發一次 refresh，其他請求排隊等待結果
• member、provider、admin 三個角色統一行為

Non-Goals:

• 不引入獨立的 refresh token（避免 token 儲存複雜度倍增）
• 不實作 token rotation 以外的安全機制（如 device binding）
• 不處理 admin panel（尚未實作）的 refresh 前端邏輯
• 不改變 7 天的 token 有效期設定

Decisions

1. 使用現有 Bearer Token 做 refresh（無獨立 refresh token）

選擇：POST /api/{role}/refresh 接受現有 Bearer token → revoke → 發新 token

原因：

• 不需新增 DB 欄位或 token 類型
• 實作最簡單：後端 3 個端點各約 5 行
• 安全性足夠：refresh 需要有效 token，無法憑空 refresh
• 缺點：token 只要還有效就能 refresh（不區分「剛登入」vs「長期 refresh」），可接受

替代方案：獨立 refresh token（長效 + 短效 access token 組合）——更安全但需儲存兩個 token、多一層 DB 查詢，複雜度不值得在此階段引入。

---

2. Refresh 在 axios response interceptor 觸發（401 時）

選擇：interceptor 攔截 401 → 呼叫 refresh → 成功則以新 token retry 原請求 → 失敗才登出

原因：

• 對所有 API 呼叫自動生效，不需每個頁面個別處理
• 延遲 refresh 到實際需要時（lazy），不需 proactive timer

並發問題：多個 API 同時 401 時，只允許一個 refresh 進行中。實作方式：module-level refreshing flag + pendingRequests queue。refresh 進行中的其他 401 請求排入 queue，refresh 完成後統一 retry。

替代方案：Proactive refresh（token 快過期前主動 refresh）——需要 timer 或每次請求檢查過期時間，複雜度較高，且 sessionStorage 無法跨分頁共享計時狀態。

Refresh 觸發條件

下列情況回傳 401 時觸發 refresh：

• 任何需要認證的 API 請求（/api/member/*、/api/provider/*、/api/admin/*）

下列情況回傳 401 時不觸發 refresh（直接傳遞錯誤給呼叫方）：

• /login、/register 端點（帳密錯誤，非 token 問題）
• /refresh 端點本身（防止無限遞迴）

Refresh 端點接受的 token 狀態

• 接受：expires_at 尚未過期、personal_access_tokens 中記錄存在且未被 revoke
• 拒絕：expires_at 已過期、token 已被 revoke（前次 refresh 或登出時）、token 格式不合法

Refresh 失敗後的前端清理流程

1. 清除 sessionStorage 中的 token（與 user）
2. 將 pendingRequests queue 中所有等待的 request 以 error reject
3. 重設 isRefreshing = false
4. 導向 /login（或 /coach/login）

Interceptor 實作約束（Invariants）

約束	說明
同時間只允許一個 refresh	isRefreshing flag 確保並發 401 不重複發 refresh
Refresh request 不進入 refresh 流程	偵測 config.url.includes('/refresh') 跳過
每個原始 request 最多 retry 一次	config._retry flag，已 retry 的請求不再觸發 refresh
Refresh 失敗時清除 token + 全部登出	清 sessionStorage → reject all pending → redirect

---

3. sessionStorage 取代 localStorage

選擇：sessionStorage.setItem('token', ...) 取代 localStorage.setItem('token', ...)

原因：

• 分頁關閉後自動清除，攻擊視窗縮短
• 重整頁面（F5）sessionStorage 仍保留，token 不會消失，不需 refresh
• Refresh 機制是為了處理 token 過期（7 天未使用）回傳 401 的情況，與頁面重整無關

副作用：多個分頁不共享登入狀態（在一個分頁登入，另一個分頁需重新登入）。可接受——per-tab session 對安全性更好。

---

4. AuthCallbackView 改用 sessionStorage

Google OAuth callback 目前直接呼叫 localStorage.setItem('token', token)（在 auth.setAuth 之前）。需同步改為 sessionStorage，否則 callback 存的位置與 axios interceptor 讀取的位置不一致。

Risks / Trade-offs

• 多分頁體驗退化：使用者在 Tab A 登入，Tab B 不會自動登入。對大部分使用情境可接受，但若使用者習慣多分頁操作會需要適應。
• Refresh 端點被濫用：攻擊者持有有效 token 時可持續呼叫 refresh。refresh 端點目前沒有 rate limiting，這是本次 change 的明確決策：先以較低複雜度完成 sliding refresh 流程；若後續觀察到濫用或異常流量，再於 P2 補上 rate limiting。
• Refresh 失敗的 edge case：網路短暫中斷時 refresh 失敗 → 強制登出。比起讓使用者停在壞狀態，主動登出更安全，可接受。
• Queue 實作複雜度：pendingRequests queue 需正確處理 promise resolve/reject，實作錯誤會導致請求永久 pending。需要仔細測試。

Migration Plan

1. 後端：新增 refreshMember、refreshProvider、refreshAdmin 方法至 AuthController.php，新增對應路由至 routes/api.php
2. 前端：改寫 axios.js 和 coachAxios.js 的 interceptor（refresh-then-retry + queue）
3. 前端：更新 auth.js、coachAuth.js、AuthCallbackView.vue 的 storage 讀寫改為 sessionStorage
4. 驗證：手動測試 token 過期後自動 refresh、多並發 401、分頁關閉後 token 清除

Rollback：各項獨立可回滾。storage 改回 localStorage 不影響功能，只影響安全性。

Open Questions

• Refresh 端點是否需要 rate limiting？ → 決策：此 change 不加。 持有有效 token 才能 refresh，攻擊面有限；P0 已對登入端點加 throttle。若未來觀察到濫用再加 throttle:10,1。
• Admin refresh 前端邏輯是否需要？ → 決策：此 change 只建後端端點（POST /api/admin/refresh），不實作前端 interceptor。 Admin panel 尚未實作，前端邏輯待 admin panel 開發時一併處理。