Design — add-auth-foundation

規格與設計

Arova Nexus

Context

EN01 Epic 是 V1 的 root。在 bootstrap 之前平台沒有任何身分；在密碼策略就位之前沒辦法強制金融業合規要求。本 change 處理這兩塊 foundation：

Bootstrap：一次性流程，把「無身分」狀態轉成「有第一個 Admin」狀態。完成後流程必須失效（防止後門）。
密碼策略：是後續所有「需要密碼」的流程（user 建立、改密、Admin 重置、SSO fallback、API Key 使用者驗證）的共用 invariant。先把策略框架定下，後續 capability 直接套用。

audit-log 在這個 change 一起進來，因為 bootstrap 和密碼動作都必須立即留稽核 — 沒有 audit-log capability 存在，bootstrap 寫的稽核紀錄就無處可去。等於是「auth 用到的 audit-log 必須同時存在」的硬依賴。

[[../../../Audit_Trail_Business_Requirements]] §2.1 規定身分動作必記稽核。EN08 是稽核 UI 的主場，但 framework 必須在 EN01 就位（不能等 EN08 才有 audit-log 寫入介面）。

見 proposal.md ## Non-Goals。

選項：A. SPA /bootstrap 頁面（拍板）/ B. CLI 命令初始化（拒）

決定 A：金融客戶交付場景是 IT 主管或交付工程師現場操作，SPA 比 CLI 直覺。CLI 適合自動化 deploy 但金融地端通常是手動 install。

反向考量：失敗自動化 deploy 場景時可補 CLI fallback（V1.5+），不在本 change。

選項：A. bootstrap_completed = true flag（拍板）/ B. 查「是否有任何 Admin」推論

決定 A：明確、不依賴 user 狀態。B 看似聰明但有 edge case（Admin 全被刪 → bootstrap 又能跑 → 災難）。

選項：A. 8 字 + 數字（拍板，符合 NIST 800-63B base）/ B. 12 字 + 大小寫 + 數字（金管會嚴格版）

決定 A 作為產品下限，金融生產建議預設值 = 12 字 + 大小寫 + 數字 + 特殊符號。下限是「不可低於」的硬鎖，預設值是「first install 時的合理 starting point」。客戶可以調到預設值之間的任意組合，但不能低於下限。

選項：A. 同帳號鎖（拍板）/ B. per-IP rate limit / C. 兩者並用

決定 A：per-IP 防不了同帳號 brute force from botnet（每個 IP 試 4 次再換 IP 永遠不觸發 per-IP）。同帳號鎖能擋這場景。Per-IP 是 EN09 Rate Limiting 的工作，本 change 不做。

Trade-off：誠實使用者用兩台機器，A 失敗鎖了會影響 B → 接受此風險，因為金管會 baseline 是同帳號鎖；Admin 緊急解鎖管道彌補。

選項：A. Admin 在 User Management 點「解鎖」（拍板）/ B. 寄連結讓 user 自助解鎖

決定 A：B 需要 SMTP（依賴 EN14，1b 範圍），1a 範圍只能走 A。1b 上線後 B 可以追加但 A 永遠保留（金融客戶要求「人為審核 + 留痕」）。

選項：A. 同 transaction（拍板）/ B. async queue

決定 A：bootstrap 與密碼變更動作頻率低（一輩子一次 / 季 1 次），async 沒效能必要。同 transaction 保證「動作成功 = 稽核也寫了」。B 適合高頻動作（EN02 webhook、EN03 alert），本 change 不需要。

選項：A. DB 層 INSERT only（無 UPDATE/DELETE grant）+ 應用層拒絕（拍板）/ B. 只靠應用層 / C. 加 hash chain

決定 A：雙保險（DB grant + 應用層 enforce）足夠 V1。C hash chain 是「可證明性更強」的技術，但增加實作複雜度且金管會稽核 baseline 不要求。V2+ 再考慮 C。

風險	影響	Mitigation
Bootstrap 失敗（網路 / 後端錯）user 無法重試	first impression 災難	失敗時 keep state in browser session，明確錯誤訊息 + 重試 btn；不清空表單
密碼策略下限太鬆，客戶反映「金管會稽核員不買單」	簽約風險	文件清楚標示「產品下限 ≠ 推薦值」，install guide 預設用嚴格版
Admin 全部被鎖（極端 case）→ 無人能解	系統死鎖	bootstrap_completed flag 為 false 時 `/bootstrap` 路由仍開（重新 bootstrap 走廊備案 — 但會清空所有資料，明確警告）
Audit-log 表寫入失敗（disk full）導致 bootstrap 也失敗	install 卡死	預檢 disk space；audit-log 寫入失敗 → 整個 transaction rollback，使用者看到「儲存失敗 — 請聯絡支援」