07 · 常見問題與排錯
錯誤碼總表
verifyWsa 拋的 WsaVerificationError.code
| code | 常見原因 | 怎麼排查 |
|---|---|---|
InvalidSignature |
金鑰錯、令牌被竄改、Tier1/Tier2 用錯金鑰 | 確認後端用的金鑰與註冊/分發的一致；per-app 金鑰原樣字串傳入，不要 hex 解碼 |
WrongAudience |
audience 與令牌 aud 不一致 |
audience 必須精確等於註冊 URL 的 host（如 app.example.com），不含連接埠/協定 |
WrongIssuer |
issuer 設定被改 |
保持預設 gptbots-workspace |
Expired |
令牌超 5 分鐘、伺服器時鐘偏差 | NTP 同步伺服器時鐘；wsa 是一次性引導令牌，別快取後再用 |
NotYetValid |
iat/nbf 在未來 |
通常是簽發方/校驗方時鐘嚴重不同步 |
MissingClaim |
缺 exp/sub/role/workspace_id |
正常平台令牌不會缺；出現說明令牌來源可疑 |
UnsupportedAlgorithm |
alg 不在白名單 |
預設僅 HS256；RS256 需顯式 algorithms:['RS256'] + publicKey |
InvalidToken |
令牌為空/結構非法/被截斷 | 檢查前端是否正確取到完整 wsa，URL 是否被中間層改寫 |
/token 換取階段（拉式）
| code | 含義 | 觸發條件 |
|---|---|---|
403209 |
Invalid grant | code 缺失、過期或已被使用（重放）。code 只能用一次 |
403210 |
Invalid verifier | PKCE codeVerifier 與發起時的 code_challenge 不匹配 |
推式 sign-token（由工作空間前端呼叫，了解即可）
| code | 含義 | 觸發條件 |
|---|---|---|
40000 |
Parameter error | URL 不在冊、auth_mode 不是 workspace_account |
40100 |
Permission deny | 未登入或工作階段失效 |
40105 |
Require member of project | 點擊人不是該工作空間的成員 |
40320 |
Member not found | 帳號被登出/刪除 |
FAQ
Q：我該選推式還是拉式？
A：入口在工作空間「擴充」頁裡、想做「內嵌應用程式」→ 推式（最簡單）。若你的應用程式是獨立站點、想放「用 GPTBots 登入」按鈕 → 拉式（M-Auth，更安全，wsa 不進瀏覽器）。見 02。
Q：能不能在前端直接解 JWT 拿使用者資訊？
A：可以解開看，但不能當可信身份——沒有金鑰無法驗簽，payload 可被偽造。任何授權判斷必須以後端 verifyWsa 結果為準。見 05 §5。
Q：wsa 過期了怎麼辦？
A：wsa 只是一次性引導令牌（5 分鐘）。落地時驗一次、換成你自己的工作階段，之後都用你的工作階段，不要再依賴 wsa。使用者下次從擴充頁點開會拿到新的 wsa。
Q：落地頁 consumeHandoff 拋「no handoff token present」？
A：說明目前 URL 沒有 ?wsa=——可能是使用者直接存取、或 wsa 已被上一次成功交換抹除。區分「首次帶令牌落地」與「普通存取」，後者走你自己的登入/匿名分支。
Q：拉式登入回呼報 StateMismatch / MissingRequest？
A：MissingRequest = 沒先在同一瀏覽器工作階段呼叫 startWorkspaceLogin（PKCE verifier 存在 sessionStorage，換分頁/清了儲存就會丟）。StateMismatch = 回呼 state 與儲存的不一致（CSRF 保護），確認沒跨裝置/跨工作階段。
Q：拉式登入報 CryptoUnavailable？
A：PKCE 需要 Web Crypto，只在安全上下文（HTTPS 或 localhost）可用。用 HTTPS 或本地 localhost 偵錯。
Q：redirect_uri 報 invalid_request / 回到組織選擇頁？
A：redirect_uri 的 scheme + host 必須與 client_id（註冊 URL）精確相同。https 應用程式不能配 http 回呼；host 必須一致。平台絕不跳到未校驗位址，所以會回組織選擇頁帶 ?error=invalid_request。
Q：per-app 金鑰怎麼當 HMAC key？要不要 base64/hex 解碼？
A：原樣字串傳入（SDK 與平台均按 UTF-8 位元組直接作 HMAC key）。Tier 2 金鑰形如 wext_+64 hex，整串就是金鑰，不要再解碼。
Q：CommonJS 專案能用 SDK 嗎？
A：SDK 是 ESM。CJS 專案用動態 import()，或把相關模組改為 ESM。
Q：圖示/名稱怎麼改？
A：Tier 2 在空間管理裡編輯；Tier 1 聯絡平台運維改字典條目。
Q：管理員停用了我的應用程式會怎樣？
A：組織管理員在空間管理裡可停用應用程式（含平台公共應用程式在本組織的可見性）。停用後該組織成員在擴充頁看不到入口，平台也不會再為該組織簽發 wsa（推式與拉式都拒絕）。
聯調清單
-
audience== 註冊 URL 的 host（最常見的WrongAudience來源） - 後端金鑰與註冊/分發一致，且只在後端
- 伺服器時鐘 NTP 同步（
Expired/NotYetValid多因時鐘） - 落地後
history.replaceState抹除wsa/code - 換成自有工作階段，後續請求不透傳
wsa - 拉式：HTTPS/localhost 安全上下文；
redirect_uri與client_id同域 - 多租戶按
workspace_id隔離