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>

app/Http/Controllers/API/AuthController.php

@@ -1051,6 +1051,63 @@ class AuthController extends Controller
         ]);
     }
 
+    /**
+     * 會員 Token Refresh
+     */
+    public function refreshMember(Request $request): \Illuminate\Http\JsonResponse
+    {
+        $user = $request->user();
+        if ($user->role !== self::ROLE_MEMBER) {
+            return $this->getUnauthorizedResponse();
+        }
+
+        $request->user()->currentAccessToken()->delete();
+        $token = $user->createToken('auth_token')->plainTextToken;
+
+        return response()->json([
+            'status' => true,
+            'data'   => ['token' => $token, 'token_type' => 'Bearer'],
+        ]);
+    }
+
+    /**
+     * 服務提供者 Token Refresh
+     */
+    public function refreshProvider(Request $request): \Illuminate\Http\JsonResponse
+    {
+        $user = $request->user();
+        if ($user->role !== self::ROLE_PROVIDER) {
+            return $this->getUnauthorizedResponse();
+        }
+
+        $request->user()->currentAccessToken()->delete();
+        $token = $user->createToken('auth_token')->plainTextToken;
+
+        return response()->json([
+            'status' => true,
+            'data'   => ['token' => $token, 'token_type' => 'Bearer'],
+        ]);
+    }
+
+    /**
+     * 管理員 Token Refresh
+     */
+    public function refreshAdmin(Request $request): \Illuminate\Http\JsonResponse
+    {
+        $user = $request->user();
+        if ($user->role !== self::ROLE_ADMIN) {
+            return $this->getUnauthorizedResponse();
+        }
+
+        $request->user()->currentAccessToken()->delete();
+        $token = $user->createToken('auth_token')->plainTextToken;
+
+        return response()->json([
+            'status' => true,
+            'data'   => ['token' => $token, 'token_type' => 'Bearer'],
+        ]);
+    }
+
     /**
      * 查詢會員資料
      * 只有管理員可以使用這個方法

frontend/src/api/axios.js

@@ -6,26 +6,75 @@ const api = axios.create({
 })
 
 api.interceptors.request.use((config) => {
-  const token = localStorage.getItem('token')
+  const token = sessionStorage.getItem('token')
   if (token) {
     config.headers.Authorization = `Bearer ${token}`
   }
   return config
 })
 
+let isRefreshing   = false
+let isRedirecting  = false
+let pendingRequests = []
+
+function resolvePending(token) {
+  pendingRequests.forEach((cb) => cb(token))
+  pendingRequests = []
+}
+
+function rejectPending(error) {
+  pendingRequests.forEach((cb) => cb(null, error))
+  pendingRequests = []
+}
+
 api.interceptors.response.use(
   (response) => response,
-  (error) => {
+  async (error) => {
-    if (
+    const config = error.config
-      error.response?.status === 401 &&
+    const status = error.response?.status
-      !error.config.url.includes('/login') &&
+
-      !error.config.url.includes('/register')
+    const isAuthEndpoint =
-    ) {
+      config.url.includes('/login') ||
-      localStorage.removeItem('token')
+      config.url.includes('/register') ||
-      localStorage.removeItem('user')
+      config.url.includes('/refresh')
+
+    if (status !== 401 || isAuthEndpoint || config._retry) {
+      return Promise.reject(error)
+    }
+
+    if (isRefreshing) {
+      return new Promise((resolve, reject) => {
+        pendingRequests.push((token, err) => {
+          if (err) return reject(err)
+          config.headers.Authorization = `Bearer ${token}`
+          resolve(api(config))
+        })
+      })
+    }
+
+    config._retry = true
+    isRefreshing = true
+
+    try {
+      const { data } = await api.post('/member/refresh')
+      const newToken = data.data.token
+      sessionStorage.setItem('token', newToken)
+      api.defaults.headers.common['Authorization'] = `Bearer ${newToken}`
+      resolvePending(newToken)
+      config.headers.Authorization = `Bearer ${newToken}`
+      return api(config)
+    } catch {
+      rejectPending(error)
+      if (!isRedirecting) {
+        isRedirecting = true
+        sessionStorage.removeItem('token')
+        sessionStorage.removeItem('user')
         window.location.href = '/login'
       }
       return Promise.reject(error)
+    } finally {
+      isRefreshing = false
+    }
   }
 )
 

frontend/src/api/coachAxios.js

@@ -6,26 +6,75 @@ const coachApi = axios.create({
 })
 
 coachApi.interceptors.request.use((config) => {
-  const token = localStorage.getItem('coach_token')
+  const token = sessionStorage.getItem('coach_token')
   if (token) {
     config.headers.Authorization = `Bearer ${token}`
   }
   return config
 })
 
+let isRefreshing   = false
+let isRedirecting  = false
+let pendingRequests = []
+
+function resolvePending(token) {
+  pendingRequests.forEach((cb) => cb(token))
+  pendingRequests = []
+}
+
+function rejectPending(error) {
+  pendingRequests.forEach((cb) => cb(null, error))
+  pendingRequests = []
+}
+
 coachApi.interceptors.response.use(
   (response) => response,
-  (error) => {
+  async (error) => {
-    if (
+    const config = error.config
-      error.response?.status === 401 &&
+    const status = error.response?.status
-      !error.config.url.includes('/login') &&
+
-      !error.config.url.includes('/register')
+    const isAuthEndpoint =
-    ) {
+      config.url.includes('/login') ||
-      localStorage.removeItem('coach_token')
+      config.url.includes('/register') ||
-      localStorage.removeItem('coach_user')
+      config.url.includes('/refresh')
+
+    if (status !== 401 || isAuthEndpoint || config._retry) {
+      return Promise.reject(error)
+    }
+
+    if (isRefreshing) {
+      return new Promise((resolve, reject) => {
+        pendingRequests.push((token, err) => {
+          if (err) return reject(err)
+          config.headers.Authorization = `Bearer ${token}`
+          resolve(coachApi(config))
+        })
+      })
+    }
+
+    config._retry = true
+    isRefreshing = true
+
+    try {
+      const { data } = await coachApi.post('/provider/refresh')
+      const newToken = data.data.token
+      sessionStorage.setItem('coach_token', newToken)
+      coachApi.defaults.headers.common['Authorization'] = `Bearer ${newToken}`
+      resolvePending(newToken)
+      config.headers.Authorization = `Bearer ${newToken}`
+      return coachApi(config)
+    } catch {
+      rejectPending(error)
+      if (!isRedirecting) {
+        isRedirecting = true
+        sessionStorage.removeItem('coach_token')
+        sessionStorage.removeItem('coach_user')
         window.location.href = '/coach/login'
       }
       return Promise.reject(error)
+    } finally {
+      isRefreshing = false
+    }
   }
 )
 

frontend/src/api/notificationAxios.js

@@ -10,8 +10,8 @@ notificationApi.interceptors.request.use((config) => {
   // 兩者都存在時（測試情境），以當前頁面路徑決定：/coach 開頭用 coach_token，其餘用 token
   const isCoachPage = window.location.pathname.startsWith('/coach')
   const token = isCoachPage
-    ? (localStorage.getItem('coach_token') || localStorage.getItem('token'))
+    ? (sessionStorage.getItem('coach_token') || sessionStorage.getItem('token'))
-    : (localStorage.getItem('token') || localStorage.getItem('coach_token'))
+    : (sessionStorage.getItem('token') || sessionStorage.getItem('coach_token'))
   if (token) {
     config.headers.Authorization = `Bearer ${token}`
   }

frontend/src/plugins/echo.js

@@ -4,7 +4,7 @@ import Pusher from 'pusher-js'
 window.Pusher = Pusher
 
 function getAuthToken() {
-    return localStorage.getItem('coach_token') || localStorage.getItem('token') || null
+    return sessionStorage.getItem('coach_token') || sessionStorage.getItem('token') || null
 }
 
 const echo = new Echo({

frontend/src/stores/auth.js

@@ -11,8 +11,8 @@ export const useAuthStore = defineStore('auth', () => {
   const isLoggedIn = computed(() => !!token.value)
 
   function init() {
-    const saved = localStorage.getItem('token')
+    const saved = sessionStorage.getItem('token')
-    const savedUser = localStorage.getItem('user')
+    const savedUser = sessionStorage.getItem('user')
     if (saved) {
       token.value = saved
       user.value  = savedUser ? JSON.parse(savedUser) : null
@@ -25,8 +25,8 @@ export const useAuthStore = defineStore('auth', () => {
   function setAuth(userData, tokenValue) {
     user.value  = userData
     token.value = tokenValue
-    localStorage.setItem('token', tokenValue)
+    sessionStorage.setItem('token', tokenValue)
-    localStorage.setItem('user', JSON.stringify(userData))
+    sessionStorage.setItem('user', JSON.stringify(userData))
     const ns = useNotificationStore()
     ns.startPolling()
     updateEchoToken()
@@ -42,8 +42,8 @@ export const useAuthStore = defineStore('auth', () => {
     ns.stopPolling()
     user.value  = null
     token.value = null
-    localStorage.removeItem('token')
+    sessionStorage.removeItem('token')
-    localStorage.removeItem('user')
+    sessionStorage.removeItem('user')
   }
 
   return { user, token, isLoggedIn, init, setAuth, logout }

frontend/src/stores/coachAuth.js

@@ -11,8 +11,8 @@ export const useCoachAuthStore = defineStore('coachAuth', () => {
   const isLoggedIn = computed(() => !!token.value)
 
   function init() {
-    const savedToken = localStorage.getItem('coach_token')
+    const savedToken = sessionStorage.getItem('coach_token')
-    const savedUser  = localStorage.getItem('coach_user')
+    const savedUser  = sessionStorage.getItem('coach_user')
     if (savedToken) {
       token.value = savedToken
       user.value  = savedUser ? JSON.parse(savedUser) : null
@@ -25,8 +25,8 @@ export const useCoachAuthStore = defineStore('coachAuth', () => {
   function setAuth(userData, tokenValue) {
     user.value  = userData
     token.value = tokenValue
-    localStorage.setItem('coach_token', tokenValue)
+    sessionStorage.setItem('coach_token', tokenValue)
-    localStorage.setItem('coach_user', JSON.stringify(userData))
+    sessionStorage.setItem('coach_user', JSON.stringify(userData))
     const ns = useNotificationStore()
     ns.startPolling()
     updateEchoToken()
@@ -42,8 +42,8 @@ export const useCoachAuthStore = defineStore('coachAuth', () => {
     ns.stopPolling()
     user.value  = null
     token.value = null
-    localStorage.removeItem('coach_token')
+    sessionStorage.removeItem('coach_token')
-    localStorage.removeItem('coach_user')
+    sessionStorage.removeItem('coach_user')
   }
 
   return { user, token, isLoggedIn, init, setAuth, logout }

frontend/src/stores/notifications.js

@@ -25,6 +25,7 @@ export const useNotificationStore = defineStore('notifications', () => {
         }
       }
     } catch (e) {
+      if (e?.response?.status === 401) { stopPolling(); return }
       console.error('[NotificationStore] fetchUnreadCount failed:', e?.response?.status, e?.message)
     }
   }
@@ -35,6 +36,7 @@ export const useNotificationStore = defineStore('notifications', () => {
       notifications.value = res.data.data
       unreadCount.value   = res.data.unread_count
     } catch (e) {
+      if (e?.response?.status === 401) { stopPolling(); return }
       console.error('[NotificationStore] fetchNotifications failed:', e?.response?.status, e?.message)
     }
   }

frontend/src/views/AuthCallbackView.vue

@@ -18,7 +18,7 @@ onMounted(async () => {
   }
 
   // 存 token 先，再拉 profile
-  localStorage.setItem('token', token)
+  sessionStorage.setItem('token', token)
   try {
     const res = await api.get('/member/profile')
     auth.setAuth(res.data.data, token)

openspec/changes/archive/2026-06-02-auth-p1-token-refresh/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-01

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

@@ -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 開發時一併處理。

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

@@ -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 實作

openspec/changes/archive/2026-06-02-auth-p1-token-refresh/specs/admin-auth/spec.md

@@ -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 失效，有效期重置

openspec/changes/archive/2026-06-02-auth-p1-token-refresh/specs/coach-portal-ui/spec.md

@@ -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`

openspec/changes/archive/2026-06-02-auth-p1-token-refresh/specs/member-portal-ui/spec.md

@@ -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`

openspec/changes/archive/2026-06-02-auth-p1-token-refresh/specs/provider-auth/spec.md

@@ -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 失效，有效期重置

openspec/changes/archive/2026-06-02-auth-p1-token-refresh/specs/token-refresh/spec.md

@@ -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 並導向登入頁

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

@@ -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，不會混用

openspec/specs/admin-auth/spec.md

@@ -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 失效，有效期重置

openspec/specs/coach-portal-ui/spec.md

@@ -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`

openspec/specs/member-portal-ui/spec.md

@@ -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** 已登入使用者重新整理頁面
+- **WHEN** 已登入使用者在同一分頁重新整理頁面
-- **THEN** 從 localStorage 還原 token，使用者仍為登入狀態
+- **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`

openspec/specs/provider-auth/spec.md

@@ -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 失效，有效期重置

openspec/specs/token-refresh/spec.md

@@ -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 並導向登入頁

routes/api.php

@@ -38,6 +38,8 @@ Route::get('/auth/google/callback', [\App\Http\Controllers\API\SocialAuthControl
 Route::middleware(['auth:sanctum'])->prefix('member')->group(function () {
     // 會員登出
     Route::post('/logout', [AuthController::class, 'logoutMember']);
+    // Token Refresh
+    Route::post('/refresh', [AuthController::class, 'refreshMember']);
     // 取得會員個人資料
     Route::get('/profile', [AuthController::class, 'memberProfile']);
     // 更新會員個人資料
@@ -66,6 +68,8 @@ Route::middleware('throttle:5,1')->post('/provider/login', [AuthController::clas
 Route::middleware(['auth:sanctum'])->prefix('provider')->group(function () {
     // 服務提供者登出
     Route::post('/logout', [AuthController::class, 'logoutProvider']);
+    // Token Refresh
+    Route::post('/refresh', [AuthController::class, 'refreshProvider']);
     // 取得服務提供者資料
     Route::get('/profile', [AuthController::class, 'providerProfile']);
     // 更新服務提供者資料
@@ -104,6 +108,8 @@ Route::middleware('throttle:3,1')->post('/admin/login', [AuthController::class,
 Route::middleware(['auth:sanctum', 'admin'])->prefix('admin')->group(function () {
     // 管理員登出
     Route::post('/logout', [AuthController::class, 'logoutAdmin']);
+    // Token Refresh
+    Route::post('/refresh', [AuthController::class, 'refreshAdmin']);
     // 取得管理員個人資料
     Route::get('/profile', [AuthController::class, 'adminProfile']);
     // 更新管理員個人資料

tests/Feature/TokenRefreshTest.php

@@ -0,0 +1,153 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Laravel\Sanctum\PersonalAccessToken;
+use Tests\TestCase;
+
+class TokenRefreshTest extends TestCase
+{
+    use RefreshDatabase;
+
+    // ── helpers ─────────────────────────────────────────────
+
+    private function memberWithToken(): array
+    {
+        $user  = User::factory()->create(['role' => 'member', 'is_active' => true]);
+        $token = $user->createToken('auth_token')->plainTextToken;
+        return [$user, $token];
+    }
+
+    private function providerWithToken(): array
+    {
+        $user  = User::factory()->create(['role' => 'provider', 'is_active' => true]);
+        $token = $user->createToken('auth_token')->plainTextToken;
+        return [$user, $token];
+    }
+
+    private function adminWithToken(): array
+    {
+        $user  = User::factory()->create(['role' => 'admin', 'is_active' => true]);
+        $token = $user->createToken('auth_token')->plainTextToken;
+        return [$user, $token];
+    }
+
+    // ── member refresh ───────────────────────────────────────
+
+    public function test_member_refresh_returns_new_token(): void
+    {
+        [, $token] = $this->memberWithToken();
+
+        $response = $this->withToken($token)->postJson('/api/member/refresh');
+
+        $response->assertStatus(200)
+                 ->assertJsonStructure(['status', 'data' => ['token', 'token_type']]);
+
+        $this->assertNotEquals($token, $response->json('data.token'));
+    }
+
+    public function test_member_refresh_revokes_old_token(): void
+    {
+        [, $token] = $this->memberWithToken();
+        $tokenId   = explode('|', $token, 2)[0];
+
+        $this->withToken($token)->postJson('/api/member/refresh');
+
+        $this->assertDatabaseMissing('personal_access_tokens', ['id' => $tokenId]);
+    }
+
+    // ── provider refresh ─────────────────────────────────────
+
+    public function test_provider_refresh_returns_new_token(): void
+    {
+        [, $token] = $this->providerWithToken();
+
+        $response = $this->withToken($token)->postJson('/api/provider/refresh');
+
+        $response->assertStatus(200)
+                 ->assertJsonStructure(['status', 'data' => ['token', 'token_type']]);
+    }
+
+    public function test_provider_refresh_revokes_old_token(): void
+    {
+        [, $token] = $this->providerWithToken();
+        $tokenId   = explode('|', $token, 2)[0];
+
+        $this->withToken($token)->postJson('/api/provider/refresh');
+
+        $this->assertDatabaseMissing('personal_access_tokens', ['id' => $tokenId]);
+    }
+
+    // ── admin refresh ────────────────────────────────────────
+
+    public function test_admin_refresh_returns_new_token(): void
+    {
+        [, $token] = $this->adminWithToken();
+
+        $response = $this->withToken($token)->postJson('/api/admin/refresh');
+
+        $response->assertStatus(200)
+                 ->assertJsonStructure(['status', 'data' => ['token', 'token_type']]);
+    }
+
+    public function test_admin_refresh_revokes_old_token(): void
+    {
+        [, $token] = $this->adminWithToken();
+        $tokenId   = explode('|', $token, 2)[0];
+
+        $this->withToken($token)->postJson('/api/admin/refresh');
+
+        $this->assertDatabaseMissing('personal_access_tokens', ['id' => $tokenId]);
+    }
+
+    // ── cross-role 403 ───────────────────────────────────────
+
+    public function test_member_token_cannot_use_provider_refresh(): void
+    {
+        [, $token] = $this->memberWithToken();
+
+        $this->withToken($token)->postJson('/api/provider/refresh')
+             ->assertStatus(403);
+    }
+
+    public function test_member_token_cannot_use_admin_refresh(): void
+    {
+        [, $token] = $this->memberWithToken();
+
+        $this->withToken($token)->postJson('/api/admin/refresh')
+             ->assertStatus(403);
+    }
+
+    public function test_provider_token_cannot_use_member_refresh(): void
+    {
+        [, $token] = $this->providerWithToken();
+
+        $this->withToken($token)->postJson('/api/member/refresh')
+             ->assertStatus(403);
+    }
+
+    // ── expired / revoked token ──────────────────────────────
+
+    public function test_expired_token_cannot_refresh(): void
+    {
+        [$user,] = $this->memberWithToken();
+        $pat = $user->tokens()->latest()->first();
+        $pat->update(['expires_at' => now()->subDay()]);
+
+        $expiredToken = $pat->token;
+        $this->postJson('/api/member/refresh', [], [
+            'Authorization' => 'Bearer ' . $expiredToken,
+        ])->assertStatus(401);
+    }
+
+    public function test_revoked_token_cannot_refresh(): void
+    {
+        [$user, $token] = $this->memberWithToken();
+        $user->tokens()->delete();
+
+        $this->withToken($token)->postJson('/api/member/refresh')
+             ->assertStatus(401);
+    }
+}