a620906209
d9f0fe11c6
- 新增三個 refresh 端點（member/provider/admin），revoke 舊 token 發行新 7 天 token - axios.js / coachAxios.js：401 interceptor 改為 refresh-then-retry，含 isRefreshing queue 防並發、isRedirecting flag 防雙重 redirect - auth.js / coachAuth.js / AuthCallbackView.vue：localStorage 全改為 sessionStorage - echo.js / notificationAxios.js：同步改為 sessionStorage - notifications.js：401 時停止 polling（stopPolling），不印 error log - 新增 TokenRefreshTest.php（11 tests / 24 assertions）：refresh 成功/失效/跨角色 403 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
116 lines
6.4 KiB
Markdown
116 lines
6.4 KiB
Markdown
## 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 開發時一併處理。
|