登入與會話

驗證碼登入

/signin 使用郵箱和六位數字驗證碼，不使用密碼。發送請求返回 challengeId、expiresInSeconds: 600 和 resendAfterSeconds: 60。驗證需要同一組郵箱、challengeId 和驗證碼；換郵箱或重新發碼後按當前頁面的新挑戰繼續。

服務端按 UTC 小時統計發送請求，每郵箱上限 5 次、每 IP 上限 20 次，並有郵箱 60 秒冷卻。共用出口的多個人可能碰到同一個 IP 上限。返回 429 時應等待，不要更換網絡或循環重試。每個挑戰最多允許 5 次錯誤驗證碼嘗試；有效驗證碼成功後只能消費一次。

| 響應 | 含義與處理 | | --- | --- | | 請求返回 202 | 已接受投遞；還需檢查實際收信 | | 驗證返回 400 | 郵箱、挑戰或六位數字格式不正確 | | 驗證返回 401 | 挑戰無效、過期或已消費；回到頁面重新申請 | | 返回 429 | 發送限流或驗證次數耗盡；按限制等待 | | 返回 503 | 身份、資料庫、Redis 或郵件依賴不可用；稍後重試並聯繫運營者 |

註冊、角色與訪問範圍

首次成功驗證時創建帳戶；已有使用者繼續使用自己的帳戶。/signup、/register、/reset-password 等兼容入口不代表仍支持密碼註冊、密碼恢復或邀請碼流程。

普通使用者進入 /account，管理員進入 /admin/overview。管理權限由服務端檢查；隱藏按鈕或修改瀏覽器里的角色不會授予權限。管理接口返回 403 表示當前身份缺少管理員權限，不應反復請求。

會話會怎樣失效

登入返回的 access token 有效期為 900 秒。瀏覽器通過 HttpOnly refresh cookie 刷新，會話空閒期限為 30 天、絕對期限為 90 天；刷新會輪換 refresh token，舊 token 重用觸發會話防護。客戶端會協調刷新，但這不保證永遠保持登入。

生產 refresh cookie 使用 Secure、SameSite=Lax，路徑為 /api/v1/auth。應從正確的 HTTPS 同源入口訪問；不要在幾個不同域名間混用登入頁面和 API。access token、Cookie、驗證碼都不要放入 URL、截圖或公開問題報告。

安全退出與常見誤解

“退出登入”調用服務端撤銷當前 refresh session 並清除 cookie，然後回到登入頁。退出不刪除檔案，也不是所有設備同時退出的承諾；已簽發 access token 有自己的有效期。當前指南沒有帳戶自助刪除或全設備會話管理操作。

郵件已發送卻無法驗證時，先核對當前郵箱和最新挑戰，保留錯誤狀態與發生時間即可；不要把驗證碼發給文件 AI。更多步驟見排錯。