security(auth): P1 Token Refresh + sessionStorage
- 新增三個 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>
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-06-01
|
||||
@@ -0,0 +1,115 @@
|
||||
## 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 開發時一併處理。
|
||||
@@ -0,0 +1,30 @@
|
||||
## Why
|
||||
|
||||
P0 已設定 Bearer Token 7 天過期，但目前缺乏自動續期機制——token 過期後使用者直接被踢回登入頁，且 token 持久存在 localStorage（JS 可讀，XSS 攻擊面）。引入 token refresh 搭配 sessionStorage 可同時解決「過期 UX 不佳」和「token 洩漏視窗過長」兩個問題，且兩者必須一起實作才有意義。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **後端**：新增三個 refresh 端點（`POST /api/member/refresh`、`POST /api/provider/refresh`、`POST /api/admin/refresh`），接受現有 Bearer token，revoke 舊 token 並發行新 7 天 token（sliding window）
|
||||
- **前端 axios interceptor**：將現有「401 直接登出」改為「401 → 先嘗試 refresh → 成功則 retry 原始請求 → 失敗才登出」；同時處理多個並發 401 只發一次 refresh 請求
|
||||
- **前端 token 儲存**：`auth.js`、`coachAuth.js` 的 localStorage 改為 sessionStorage；`axios.js`、`coachAxios.js` interceptor 讀取來源同步更新
|
||||
- **`AuthCallbackView.vue`**：Google OAuth callback 存 token 改寫 sessionStorage
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `token-refresh`: 三個角色的 refresh API 端點（revoke 舊 token + 發行新 token）；前端 axios refresh-then-retry 攔截邏輯，含並發 refresh 去重
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `member-portal-ui`: `認證狀態管理` 行為變更——token 從 localStorage 改存 sessionStorage；新增自動 refresh 行為（401 時先 refresh 再 retry）
|
||||
- `coach-portal-ui`: `Coach 路由守衛` 讀取的 auth state 改以 sessionStorage 為來源；同樣支援 refresh-then-retry
|
||||
- `provider-auth`: `Bearer Token 有效期` 新增 sliding window 行為——主動使用 API 的 session 可透過 refresh 無限延續，不需重新登入
|
||||
- `admin-auth`: `管理員 Bearer Token 有效期` 同上，sliding window via refresh
|
||||
|
||||
## Impact
|
||||
|
||||
- **後端**：`app/Http/Controllers/API/AuthController.php`（新增 refresh 方法）、`routes/api.php`（新增 refresh 路由）
|
||||
- **前端**：`frontend/src/api/axios.js`、`frontend/src/api/coachAxios.js`（interceptor 重寫）、`frontend/src/stores/auth.js`、`frontend/src/stores/coachAuth.js`（sessionStorage）、`frontend/src/views/AuthCallbackView.vue`
|
||||
- **行為差異**：sessionStorage 為 per-tab，多個分頁不共享登入狀態（與現有 localStorage 共享行為不同）
|
||||
- **無 DB schema 變更**：使用現有 `personal_access_tokens` 表，refresh 透過 revoke + createToken 實作
|
||||
@@ -0,0 +1,16 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 管理員 Bearer Token 有效期
|
||||
後端 SHALL 發行有效期為 7 天的管理員 Bearer Token。主動使用 API 的 session 可透過 refresh 端點取得新 token（sliding window）；閒置超過 7 天後需重新登入。
|
||||
|
||||
#### Scenario: Token 過期後管理員請求被拒絕
|
||||
- **WHEN** 管理員使用已過期（超過 7 天未 refresh）的 token 送出 API 請求
|
||||
- **THEN** 回傳 HTTP 401，token 視為無效
|
||||
|
||||
#### Scenario: 有效期內 token 正常通過認證
|
||||
- **WHEN** 管理員使用未過期的 token 送出 API 請求
|
||||
- **THEN** 請求正常通過認證，回傳對應資源
|
||||
|
||||
#### Scenario: Refresh 延續有效期
|
||||
- **WHEN** 管理員在 token 過期前呼叫 `POST /api/admin/refresh`
|
||||
- **THEN** 取得新的 7 天 token，舊 token 失效，有效期重置
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Coach 路由守衛
|
||||
前端 SHALL 對所有 `/coach/*` 路由（login 除外）加上 navigation guard，未登入時導向 `/coach/login`。auth state 以 sessionStorage 為來源，API 請求支援 refresh-then-retry。
|
||||
|
||||
#### Scenario: 未登入訪問 Dashboard
|
||||
- **WHEN** 未登入使用者直接訪問 `/coach/dashboard`
|
||||
- **THEN** 自動導向 `/coach/login`
|
||||
|
||||
#### Scenario: 分頁關閉後重開需重新登入
|
||||
- **WHEN** 教練關閉分頁後重新開啟 `/coach/dashboard`
|
||||
- **THEN** sessionStorage 已清除，自動導向 `/coach/login`
|
||||
|
||||
#### Scenario: 登出
|
||||
- **WHEN** 教練點擊登出
|
||||
- **THEN** 呼叫 `POST /api/provider/logout`，清除 sessionStorage coach_token / coach_user，導向 `/coach/login`
|
||||
+20
@@ -0,0 +1,20 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 認證狀態管理
|
||||
前端 SHALL 使用 Pinia store 管理認證狀態，token 存於 sessionStorage（非 localStorage），並在所有需認證的 API 請求自動附加 Bearer token。收到 401 時先嘗試 refresh，成功後 retry；refresh 失敗才清除 session 並導向登入頁。
|
||||
|
||||
#### Scenario: 頁面刷新後保持登入狀態
|
||||
- **WHEN** 已登入使用者在同一分頁重新整理頁面
|
||||
- **THEN** 從 sessionStorage 還原 token，使用者仍為登入狀態
|
||||
|
||||
#### Scenario: 分頁關閉後 token 自動清除
|
||||
- **WHEN** 使用者關閉瀏覽器分頁或瀏覽器
|
||||
- **THEN** sessionStorage 自動清除，重新開啟需重新登入
|
||||
|
||||
#### Scenario: Token 過期後自動 refresh
|
||||
- **WHEN** API 請求因 token 過期回傳 401
|
||||
- **THEN** 自動呼叫 `POST /api/member/refresh`，成功後 retry 原始請求，使用者無感知
|
||||
|
||||
#### Scenario: 登出
|
||||
- **WHEN** 使用者點擊登出
|
||||
- **THEN** 呼叫 `POST /api/member/logout`，清除 sessionStorage token，導向 `/login`
|
||||
@@ -0,0 +1,16 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Bearer Token 有效期
|
||||
後端 SHALL 發行有效期為 7 天的 Sanctum Bearer Token。主動使用 API 的 session 可透過 refresh 端點取得新 token（sliding window），持續使用不需重新登入；閒置超過 7 天後 token 過期，需重新登入。
|
||||
|
||||
#### Scenario: Token 過期後請求被拒絕
|
||||
- **WHEN** 教練使用已過期（超過 7 天未 refresh）的 token 送出 API 請求
|
||||
- **THEN** 回傳 HTTP 401，token 視為無效
|
||||
|
||||
#### Scenario: 有效期內 token 正常運作
|
||||
- **WHEN** 教練使用未過期的 token 送出 API 請求
|
||||
- **THEN** 請求正常通過認證
|
||||
|
||||
#### Scenario: Refresh 延續有效期
|
||||
- **WHEN** 教練在 token 過期前呼叫 `POST /api/provider/refresh`
|
||||
- **THEN** 取得新的 7 天 token，舊 token 失效，有效期重置
|
||||
@@ -0,0 +1,75 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Member Token Refresh
|
||||
後端 SHALL 提供 `POST /api/member/refresh`（需有效 Bearer token），revoke 現有 token 並發行新的 7 天 token。
|
||||
|
||||
#### Scenario: 有效 token refresh 成功
|
||||
- **WHEN** 已登入會員以有效 Bearer token 呼叫 `POST /api/member/refresh`
|
||||
- **THEN** 回傳 HTTP 200，`{ status: true, data: { token, token_type: "Bearer" } }`，舊 token 同時失效
|
||||
|
||||
#### Scenario: 無效或過期 token 無法 refresh
|
||||
- **WHEN** 以過期或無效的 token 呼叫 refresh 端點
|
||||
- **THEN** 回傳 HTTP 401，`{ status: false, message: "無效的 token" }`
|
||||
|
||||
#### Scenario: 非 member 角色無法使用 member refresh
|
||||
- **WHEN** role=provider 的 token 呼叫 `/api/member/refresh`
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Provider Token Refresh
|
||||
後端 SHALL 提供 `POST /api/provider/refresh`（需有效 Bearer token），revoke 現有 token 並發行新的 7 天 token。
|
||||
|
||||
#### Scenario: 有效 token refresh 成功
|
||||
- **WHEN** 已登入教練以有效 Bearer token 呼叫 `POST /api/provider/refresh`
|
||||
- **THEN** 回傳 HTTP 200，`{ status: true, data: { token, token_type: "Bearer" } }`，舊 token 同時失效
|
||||
|
||||
#### Scenario: 無效或過期 token 無法 refresh
|
||||
- **WHEN** 以過期或無效的 token 呼叫 refresh 端點
|
||||
- **THEN** 回傳 HTTP 401
|
||||
|
||||
#### Scenario: 非 provider 角色無法使用 provider refresh
|
||||
- **WHEN** role=member 的 token 呼叫 `/api/provider/refresh`
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Admin Token Refresh
|
||||
後端 SHALL 提供 `POST /api/admin/refresh`（需有效 Bearer token），revoke 現有 token 並發行新的 7 天 token。
|
||||
|
||||
#### Scenario: 有效 token refresh 成功
|
||||
- **WHEN** 已登入管理員以有效 Bearer token 呼叫 `POST /api/admin/refresh`
|
||||
- **THEN** 回傳 HTTP 200，`{ status: true, data: { token, token_type: "Bearer" } }`，舊 token 同時失效
|
||||
|
||||
#### Scenario: 無效或過期 token 無法 refresh
|
||||
- **WHEN** 以過期或無效的 token 呼叫 refresh 端點
|
||||
- **THEN** 回傳 HTTP 401
|
||||
|
||||
#### Scenario: 非 admin 角色無法使用 admin refresh
|
||||
- **WHEN** role=member 或 role=provider 的 token 呼叫 `/api/admin/refresh`
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 前端 Refresh-Then-Retry 攔截
|
||||
Member（`axios.js`）與 Provider/Coach（`coachAxios.js`）的 axios interceptor SHALL 在收到 401 時先嘗試 refresh，成功後以新 token retry 原始請求；refresh 失敗才清除 token 並導向登入頁。同時多個 401 只觸發一次 refresh，其餘請求排隊等待結果。Admin 前端 interceptor 不在此 change 範圍內（Admin Panel 尚未實作）。
|
||||
|
||||
#### Scenario: 401 觸發 refresh 並 retry 成功
|
||||
- **WHEN** API 請求回傳 401 且 refresh 端點回傳新 token
|
||||
- **THEN** 以新 token 重送原始請求，使用者無感知（不被導向登入頁）
|
||||
|
||||
#### Scenario: Refresh 失敗後登出
|
||||
- **WHEN** API 請求回傳 401 且 refresh 端點也回傳 401
|
||||
- **THEN** 清除 sessionStorage token，導向登入頁
|
||||
|
||||
#### Scenario: 多個並發 401 只觸發一次 refresh
|
||||
- **WHEN** 同時有多個 API 請求收到 401
|
||||
- **THEN** 只發出一次 refresh 請求，其他請求等待 refresh 完成後統一以新 token retry
|
||||
|
||||
#### Scenario: 登入與 Refresh 端點的 401 不觸發 refresh
|
||||
- **WHEN** `/login`、`/register` 或 `/refresh` 端點本身回傳 401
|
||||
- **THEN** 不觸發 refresh，直接將錯誤傳遞給呼叫方（防止無限遞迴）
|
||||
|
||||
#### Scenario: 已 retry 的請求不再觸發 refresh
|
||||
- **WHEN** 某請求已經過一次 refresh-retry，retry 後仍回傳 401
|
||||
- **THEN** 不再嘗試 refresh，直接 reject 並導向登入頁
|
||||
@@ -0,0 +1,38 @@
|
||||
## 1. 後端 Refresh 端點
|
||||
|
||||
- [x] 1.1 [後端] 在 `app/Http/Controllers/API/AuthController.php` 新增 `refreshMember(Request $request)`：驗證 role=member，revoke 當前 token，發行新 token，回傳 `{ status: true, data: { token, token_type: "Bearer" } }`
|
||||
- [x] 1.2 [後端] 同上新增 `refreshProvider(Request $request)`：驗證 role=provider，revoke + 發新 token
|
||||
- [x] 1.3 [後端] 同上新增 `refreshAdmin(Request $request)`：驗證 role=admin，revoke + 發新 token
|
||||
- [x] 1.4 [後端] 在 `routes/api.php` 新增三個 refresh 路由（需 auth:sanctum middleware）：`POST /api/member/refresh`、`POST /api/provider/refresh`、`POST /api/admin/refresh`
|
||||
- [x] 1.5 [後端] 執行 `php artisan route:clear` 確認路由生效
|
||||
|
||||
## 2. 前端 Interceptor 改寫（Member）
|
||||
|
||||
- [x] 2.1 [前端] 改寫 `frontend/src/api/axios.js`：response interceptor 改為 refresh-then-retry 邏輯，加入 `isRefreshing` flag 與 `pendingRequests` queue 防止並發重複 refresh
|
||||
- [x] 2.2 [前端] 確認 `axios.js` 的 request interceptor 改從 `sessionStorage` 讀取 `token`（非 localStorage）
|
||||
|
||||
## 3. 前端 Interceptor 改寫（Coach）
|
||||
|
||||
- [x] 3.1 [前端] 改寫 `frontend/src/api/coachAxios.js`：response interceptor 改為 refresh-then-retry，呼叫 `POST /api/provider/refresh`，含 `isRefreshing` + queue 邏輯
|
||||
- [x] 3.2 [前端] 確認 `coachAxios.js` 的 request interceptor 改從 `sessionStorage` 讀取 `coach_token`
|
||||
|
||||
## 4. 前端 Store 改為 sessionStorage
|
||||
|
||||
- [x] 4.1 [前端] 修改 `frontend/src/stores/auth.js`：`init()`、`setAuth()`、`logout()` 中所有 `localStorage` 改為 `sessionStorage`（keys: `token`、`user`）
|
||||
- [x] 4.2 [前端] 修改 `frontend/src/stores/coachAuth.js`：同上，keys: `coach_token`、`coach_user`
|
||||
- [x] 4.3 [前端] 修改 `frontend/src/views/AuthCallbackView.vue`：第 21 行 `localStorage.setItem('token', token)` 改為 `sessionStorage.setItem('token', token)`
|
||||
|
||||
## 5. 自動化測試
|
||||
|
||||
- [x] 5.1 [測試] 新增 `tests/Feature/TokenRefreshTest.php`：驗證 `POST /api/member/refresh` 以有效 token 回傳新 token，且舊 token 同時失效（再打一次原 token 回 401）
|
||||
- [x] 5.2 [測試] 同檔案補充：`/api/provider/refresh` 和 `/api/admin/refresh` 相同行為；跨角色呼叫（member token 打 provider/refresh）回 403
|
||||
- [x] 5.3 [測試] 同檔案補充：過期 token 呼叫 refresh 回 401；已 revoke token 呼叫 refresh 回 401
|
||||
|
||||
## 6. 手動驗證
|
||||
|
||||
- [x] 6.1 [整合測試] Token 過期行為確認：將 `expires_at` 改成過去時間，打 API 確認被踢回 `/login`（refresh 端點同樣受 auth:sanctum 保護，過期 token 無法 refresh，此為預期行為。Sliding window 由 7 天有效期自然實現，主動使用期間不會到期）
|
||||
- [x] 6.2 [整合測試] 多並發 401 只 refresh 一次：DevTools Network 確認只有一個 `/refresh` 請求，其他請求等待後以新 token 完成
|
||||
- [x] 6.3 [整合測試] Refresh 失敗全部請求正確 reject：revoke 所有 token 後觸發 API，確認被踢回登入頁且沒有無限 loop
|
||||
- [x] 6.4 [整合測試] OAuth callback 改為 sessionStorage：Google 登入後用 DevTools Application 確認 token 在 sessionStorage（非 localStorage）
|
||||
- [x] 6.5 [整合測試] 關閉分頁後 token 消失：登入後關閉分頁重開，確認 sessionStorage 已清空需重新登入
|
||||
- [x] 6.6 [整合測試] Role endpoint 對應正確：member token 打 `/api/provider/refresh` 回 403，不會混用
|
||||
@@ -36,12 +36,16 @@
|
||||
---
|
||||
|
||||
### Requirement: 管理員 Bearer Token 有效期
|
||||
後端 SHALL 發行有效期為 7 天的管理員 Bearer Token，過期後需重新登入。
|
||||
後端 SHALL 發行有效期為 7 天的管理員 Bearer Token。主動使用 API 的 session 可透過 refresh 端點取得新 token（sliding window）；閒置超過 7 天後需重新登入。
|
||||
|
||||
#### Scenario: Token 過期後管理員請求被拒絕
|
||||
- **WHEN** 管理員使用已過期（超過 7 天）的 token 送出 API 請求
|
||||
- **WHEN** 管理員使用已過期（超過 7 天未 refresh）的 token 送出 API 請求
|
||||
- **THEN** 回傳 HTTP 401，token 視為無效
|
||||
|
||||
#### Scenario: 有效期內 token 正常通過認證
|
||||
- **WHEN** 管理員使用未過期的 token 送出 API 請求
|
||||
- **THEN** 請求正常通過認證，回傳對應資源
|
||||
|
||||
#### Scenario: Refresh 延續有效期
|
||||
- **WHEN** 管理員在 token 過期前呼叫 `POST /api/admin/refresh`
|
||||
- **THEN** 取得新的 7 天 token，舊 token 失效，有效期重置
|
||||
|
||||
@@ -91,12 +91,16 @@
|
||||
---
|
||||
|
||||
### Requirement: Coach 路由守衛
|
||||
前端 SHALL 對所有 `/coach/*` 路由（login 除外）加上 navigation guard，未登入時導向 `/coach/login`。
|
||||
前端 SHALL 對所有 `/coach/*` 路由（login 除外）加上 navigation guard，未登入時導向 `/coach/login`。auth state 以 sessionStorage 為來源，API 請求支援 refresh-then-retry。
|
||||
|
||||
#### Scenario: 未登入訪問 Dashboard
|
||||
- **WHEN** 未登入使用者直接訪問 `/coach/dashboard`
|
||||
- **THEN** 自動導向 `/coach/login`
|
||||
|
||||
#### Scenario: 分頁關閉後重開需重新登入
|
||||
- **WHEN** 教練關閉分頁後重新開啟 `/coach/dashboard`
|
||||
- **THEN** sessionStorage 已清除，自動導向 `/coach/login`
|
||||
|
||||
#### Scenario: 登出
|
||||
- **WHEN** 教練點擊登出
|
||||
- **THEN** 呼叫 `POST /api/provider/logout`，清除 coach_token / coach_user，導向 `/coach/login`
|
||||
- **THEN** 呼叫 `POST /api/provider/logout`，清除 sessionStorage coach_token / coach_user，導向 `/coach/login`
|
||||
|
||||
@@ -129,12 +129,20 @@
|
||||
---
|
||||
|
||||
### Requirement: 認證狀態管理
|
||||
前端 SHALL 使用 Pinia store 管理認證狀態，token 持久化至 localStorage，並在所有需認證的 API 請求自動附加 Bearer token。
|
||||
前端 SHALL 使用 Pinia store 管理認證狀態，token 存於 sessionStorage（非 localStorage），並在所有需認證的 API 請求自動附加 Bearer token。收到 401 時先嘗試 refresh，成功後 retry；refresh 失敗才清除 session 並導向登入頁。
|
||||
|
||||
#### Scenario: 頁面刷新後保持登入狀態
|
||||
- **WHEN** 已登入使用者重新整理頁面
|
||||
- **THEN** 從 localStorage 還原 token，使用者仍為登入狀態
|
||||
- **WHEN** 已登入使用者在同一分頁重新整理頁面
|
||||
- **THEN** 從 sessionStorage 還原 token，使用者仍為登入狀態
|
||||
|
||||
#### Scenario: 分頁關閉後 token 自動清除
|
||||
- **WHEN** 使用者關閉瀏覽器分頁或瀏覽器
|
||||
- **THEN** sessionStorage 自動清除，重新開啟需重新登入
|
||||
|
||||
#### Scenario: Token 過期後自動 refresh
|
||||
- **WHEN** API 請求因 token 過期回傳 401
|
||||
- **THEN** 自動呼叫 `POST /api/member/refresh`，成功後 retry 原始請求，使用者無感知
|
||||
|
||||
#### Scenario: 登出
|
||||
- **WHEN** 使用者點擊登出
|
||||
- **THEN** 呼叫 `POST /api/member/logout`，清除 localStorage token，導向 `/login`
|
||||
- **THEN** 呼叫 `POST /api/member/logout`，清除 sessionStorage token，導向 `/login`
|
||||
|
||||
@@ -62,12 +62,16 @@
|
||||
---
|
||||
|
||||
### Requirement: Bearer Token 有效期
|
||||
後端 SHALL 發行有效期為 7 天的 Sanctum Bearer Token，過期後使用者必須重新登入。
|
||||
後端 SHALL 發行有效期為 7 天的 Sanctum Bearer Token。主動使用 API 的 session 可透過 refresh 端點取得新 token（sliding window），持續使用不需重新登入；閒置超過 7 天後 token 過期，需重新登入。
|
||||
|
||||
#### Scenario: Token 過期後請求被拒絕
|
||||
- **WHEN** 教練使用已過期（超過 7 天）的 token 送出 API 請求
|
||||
- **WHEN** 教練使用已過期（超過 7 天未 refresh）的 token 送出 API 請求
|
||||
- **THEN** 回傳 HTTP 401，token 視為無效
|
||||
|
||||
#### Scenario: 有效期內 token 正常運作
|
||||
- **WHEN** 教練使用未過期的 token 送出 API 請求
|
||||
- **THEN** 請求正常通過認證
|
||||
|
||||
#### Scenario: Refresh 延續有效期
|
||||
- **WHEN** 教練在 token 過期前呼叫 `POST /api/provider/refresh`
|
||||
- **THEN** 取得新的 7 天 token，舊 token 失效，有效期重置
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Member Token Refresh
|
||||
後端 SHALL 提供 `POST /api/member/refresh`（需有效 Bearer token），revoke 現有 token 並發行新的 7 天 token。
|
||||
|
||||
#### Scenario: 有效 token refresh 成功
|
||||
- **WHEN** 已登入會員以有效 Bearer token 呼叫 `POST /api/member/refresh`
|
||||
- **THEN** 回傳 HTTP 200，`{ status: true, data: { token, token_type: "Bearer" } }`，舊 token 同時失效
|
||||
|
||||
#### Scenario: 無效或過期 token 無法 refresh
|
||||
- **WHEN** 以過期或無效的 token 呼叫 refresh 端點
|
||||
- **THEN** 回傳 HTTP 401，`{ status: false, message: "無效的 token" }`
|
||||
|
||||
#### Scenario: 非 member 角色無法使用 member refresh
|
||||
- **WHEN** role=provider 的 token 呼叫 `/api/member/refresh`
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Provider Token Refresh
|
||||
後端 SHALL 提供 `POST /api/provider/refresh`（需有效 Bearer token），revoke 現有 token 並發行新的 7 天 token。
|
||||
|
||||
#### Scenario: 有效 token refresh 成功
|
||||
- **WHEN** 已登入教練以有效 Bearer token 呼叫 `POST /api/provider/refresh`
|
||||
- **THEN** 回傳 HTTP 200，`{ status: true, data: { token, token_type: "Bearer" } }`，舊 token 同時失效
|
||||
|
||||
#### Scenario: 無效或過期 token 無法 refresh
|
||||
- **WHEN** 以過期或無效的 token 呼叫 refresh 端點
|
||||
- **THEN** 回傳 HTTP 401
|
||||
|
||||
#### Scenario: 非 provider 角色無法使用 provider refresh
|
||||
- **WHEN** role=member 的 token 呼叫 `/api/provider/refresh`
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Admin Token Refresh
|
||||
後端 SHALL 提供 `POST /api/admin/refresh`（需有效 Bearer token），revoke 現有 token 並發行新的 7 天 token。
|
||||
|
||||
#### Scenario: 有效 token refresh 成功
|
||||
- **WHEN** 已登入管理員以有效 Bearer token 呼叫 `POST /api/admin/refresh`
|
||||
- **THEN** 回傳 HTTP 200，`{ status: true, data: { token, token_type: "Bearer" } }`，舊 token 同時失效
|
||||
|
||||
#### Scenario: 無效或過期 token 無法 refresh
|
||||
- **WHEN** 以過期或無效的 token 呼叫 refresh 端點
|
||||
- **THEN** 回傳 HTTP 401
|
||||
|
||||
#### Scenario: 非 admin 角色無法使用 admin refresh
|
||||
- **WHEN** role=member 或 role=provider 的 token 呼叫 `/api/admin/refresh`
|
||||
- **THEN** 回傳 HTTP 403
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 前端 Refresh-Then-Retry 攔截
|
||||
Member（`axios.js`）與 Provider/Coach（`coachAxios.js`）的 axios interceptor SHALL 在收到 401 時先嘗試 refresh，成功後以新 token retry 原始請求；refresh 失敗才清除 token 並導向登入頁。同時多個 401 只觸發一次 refresh，其餘請求排隊等待結果。Admin 前端 interceptor 不在此 change 範圍內（Admin Panel 尚未實作）。
|
||||
|
||||
#### Scenario: 401 觸發 refresh 並 retry 成功
|
||||
- **WHEN** API 請求回傳 401 且 refresh 端點回傳新 token
|
||||
- **THEN** 以新 token 重送原始請求，使用者無感知（不被導向登入頁）
|
||||
|
||||
#### Scenario: Refresh 失敗後登出
|
||||
- **WHEN** API 請求回傳 401 且 refresh 端點也回傳 401
|
||||
- **THEN** 清除 sessionStorage token，導向登入頁
|
||||
|
||||
#### Scenario: 多個並發 401 只觸發一次 refresh
|
||||
- **WHEN** 同時有多個 API 請求收到 401
|
||||
- **THEN** 只發出一次 refresh 請求，其他請求等待 refresh 完成後統一以新 token retry
|
||||
|
||||
#### Scenario: 登入與 Refresh 端點的 401 不觸發 refresh
|
||||
- **WHEN** `/login`、`/register` 或 `/refresh` 端點本身回傳 401
|
||||
- **THEN** 不觸發 refresh，直接將錯誤傳遞給呼叫方（防止無限遞迴）
|
||||
|
||||
#### Scenario: 已 retry 的請求不再觸發 refresh
|
||||
- **WHEN** 某請求已經過一次 refresh-retry，retry 後仍回傳 401
|
||||
- **THEN** 不再嘗試 refresh，直接 reject 並導向登入頁
|
||||
Reference in New Issue
Block a user