FR-048 Phase 2a — 全站端點授權矩陣

性質：純盤點（零 code 變更）。全站 api/ 寫入端點（POST/PUT/DELETE/PATCH）+ 敏感 GET（匯出/下載/報表/qrcode/token）逐支判軸，供 user 過目定調。 上游設計：../../analysis/2026-07-07-unified-auth-guard-design.md（§2 軸模型、§3.2 決策表、§5.0 scope、§7 phase）。 交叉驗證：../../analysis/2026-07-07-known-pits-remediation-tracker.md §SEC 六族 75 條。 建立：2026-07-07，branch fix/v1.8.0-bugs。逐模組事實底稿在 _partials/（route/method/呼叫 service/守門 file:line 皆已實查引用）。 盤點法：8 個 subagent 按模組分工，追 route → app service body 找守門呼叫；主 session 判軸 + 交叉驗證。

軸別（設計 §2）：

• ①platform — root tenant 平台管理員（純 context，require_platform_admin）。全域共用資源（框架、平台設定、LOG）。
• ②super-admin — 帳號層 super_admin（純 context，require_super_admin）。租戶級系統設定 / 範本 / 管理頁；Phase 3 過渡、Phase 4 換 capability。
• ③project-role — 專案/SSP/workflow 成員資格（resolve 資源，assert_project_manager / SspPermissionChecker / workflow guard）。
• ④capability — RBAC 能力點（Phase 4，尚未實作）。
• ⑤signed-token — 簽章短期憑證（Phase 4，瀏覽器原生 GET）。
• owner — 資源擁有者個案（D 族，逐案）。
• F — 刻意不擋（health / OAuth callback / 公開登入流程 / FR-039 控制面）。

狀態：

• 已守 — 已有正確守門，本案不動。
• 待補 — 軸別明確、目前裸奔，待掛守門（Phase 2b/3/4）。
• 待定調 — 軸別或角色層級未定，集中在 §1 問 user。
• no-action — 刻意公開/自我 scope/低風險，確認即可。
• dead — route 未註冊（註解停用）或 service 為 stub，無 live 風險。

Phase：2b=軸③專案域補守門｜3=軸①②主體域 decorator｜4=軸④capability+軸⑤signed-token｜—=已守/no-action/dead。

「已守」大宗＝Phase 1 之前已鋪守門的三塊（participant / SSP / audit-round）＋framework。裸奔集中在系統管理頁（軸②）與部分專案域寫入（軸③），與設計 §5.0 判斷一致。

判定規則：spec 權限矩陣有寫→照 spec；spec 沒寫 / FE-BE 粒度不一致 / 權限主體不明→集中在此，不自己猜。

定調結果（全數同意建議案）：

D1 是最大結構性問題：module_frame 43 支全裸奔且軸別本身有爭議（tracker 軸③ vs 程式碼軸②），必須先定調才能規劃 Phase 2b/3 分工。

tracker §SEC 六族 + 漏網 8 條，每條對映到矩陣模組/狀態。對不上的回頭補。

A 族（未認證，3 條）

B 族（系統設定僅 JWT，→ 軸②/④ Phase 3/4）

C 族（GRC 專案寫入無角色守門，→ 軸③ Phase 2b）

交叉驗證發現：C 族的 5 條 project-ssp-* pit 在實查中已有 require_manager 守門（SSP-scoped 34 支全數已守）——這些 pit 可能是 spec §12 撰寫時的舊觀察、之後已補。建議 user 定調時將其標為「已解，複驗即可」。真正待補的 C 族集中在 grc（job/review/update_project/batch）與 flow_engine。

D 族（資訊洩漏，逐案）

E 族（驗證只在 FE）

forget-password#2、device-manage#6、survey-v2-fill#1、project-task-edit#2、project-ssp-basic#1 — 非授權缺口，屬 FE 驗證，本案不處理，維持 tracker E 族後排。

F 族（刻意不擋 / no-action）

cloud-integrations#4/#2（OAuth callback state token / webhook channel token，實查確認）、my-audits#8（SQL 已鎖自己）、remote-agent-manage#4（FR-039 控制面 register/heartbeat）、evidence/_overview#6/#7（FR-039 demo）、ai-dashboard#6/#2（health 公開）、background-services#1、_overview#5、login#7/#3（captcha 順序 / 設計）→ 全數 no-action，已於各模組矩陣標明理由（防下次重查）。

漏網 8 條

compliance-framework-manage#5（A）、user-profile#3（A）、information-system-manage#1（B/D13）、planning-status#1（D6）、user-profile#6（LDAP 綁定不驗本人，低風險→逐案）、user-manage#2（排序唯讀，非缺口）、ai-dashboard#2（F）、login#7（F）——8 條全部對映到矩陣列（無漏）。

每支端點一列。事實欄（現況守門/呼叫 service）源自 _partials/，此處補「軸別/角色/Phase/狀態」判斷欄。dead（未註冊/stub）僅列關鍵者，完整 dead 清單見各 partial。

3.1 api/oscal（framework 已守軸①、SSP 已守軸③；缺口 3）

3.2 api/module_frame（全裸奔，軸別待定調 D1）

3.3 api/project（audit-round 家族已守軸③；缺口＝建專案定調）

3.4 api/project_summary_report + subtask_status_history（軸③，缺口）

3.5 api/grc（缺口集中；多項待定調）

3.6 api/flow_engine（證據&任務守門停用待復活；範本待定調）

3.7 api/auth + user_auth_provider + captcha（B 族軸②，tenant 待定調 D4）

3.8 api/survey + task_survey（survey 設計待定調 D9；填答待定調 D10）

3.9 api/participant + remote_agent（participant 已守；agent 待定調 D11）

3.10 api/misc（cloud_integration 多已守；系統設定 B 族待補；新發現未認證）

「已守」~110 支不是同一套寫法，分三類處理：

1. user 逐項定調 §1 ✅ 已定調（見 §1 定調結果）。
2. D14 schedule-report/preview（任意檔讀取）插隊優先處理。
3. Phase 2b（軸③補守門＋A 類換路徑，含 flow_engine guard 復活）與 Phase 3（軸①② decorator＋C 類 inline is_admin 收編）並行推進，逐列銷帳。
4. Phase 2c（B 類收編：assert_project_role 泛化＋7 份 check* 委派）排 2b 收尾後。
5. §3 標「待補」者為 Phase 2b/3 工作面；「已守」複驗即可；「dead」不動。

本檔為 living tracker：Phase 2b/3/4 落地時逐列更新狀態欄（待補→已守）。

主體域 route decorator 建置 + 掛點完成。decorator 本體：common/authz/decorators.py （require_platform_admin_route / require_super_admin_route，後者支援 error_code= 覆寫）， 委派 platform.py / admin.py 純 context 判定，掛在 @jwt_required() 之內、@inject 之外。 單元測試 test/test_authz_decorators.py（7 案：raise/pass/fail-closed/custom-code 全綠）。 pytest test/ 對比 baseline 零新增失敗（既有 71 fail / 43 err 全為 stale/env，與本案無關）。

掛點統計：軸① platform 7 支、軸② super-admin 109 支（含 flow-template 6 支用 alias）， 共 116 支，分佈 16 模組。

6.1 插隊件

6.2 軸① platform-admin（@require_platform_admin_route，7 支）

6.3 軸② super-admin 過渡名單 → ✅ Phase 4a 已換能力點（軸④）

掛 @require_super_admin_route 皆為過渡；Phase 4 能力點 seed 齊後逐支換 2026-07-07 Phase 4a 完成換裝（見 §8）。策略（user 定調）＝復用既有 granular cap、精準對 HTTP verb（POST→<res>.create／PUT→<res>.update／DELETE→<res>.delete／敏感 GET→.read）， resource 用模組既有 DB resource_type；只 3 組缺口新 seed（system_config／feedback.export／ notification.test）。下表「建議能力點」欄的 .manage 命名為原始草案，實作採 granular verb 映射。

6.4 C 類 inline is_admin 收編（帳號層語意，零行為變更）

已收編（14 處，全為 ambient get_user_context().is_admin 請求路徑讀取 → common.authz canonical）：

• notify_config_test_service.test_channel：inline gate → require_super_admin(NOTIFY_CHANNEL_TEST_FORBIDDEN)（測試 patch 路徑同步改指 common.authz.admin.get_user_context）
• cloud_integration route：google_drive_sync_route（3 param 讀 + webhook/register inline gate require_super_admin()）、google_drive_integration_route（disconnect/auth-url 2 param 讀）→ viewer_is_super_admin()
• grc route：project_route（4）、job_route（1）、job_import_route（1）、user_route（1，update user）→ viewer_is_super_admin()

刻意不收（scope 邊界）：

• import service 的 user_context.is_admin（ap_docx/ar/ssp_excel/ssp_docx 共 8 處）：user_context 是顯式參數（route 傳入），非 ambient；已是正確帳號層 DTO 讀取。改成 viewer_is_super_admin()（讀 ambient ContextVar）會回退成 ambient 依賴、破壞可測試性與 worker-thread 安全 → 維持顯式參數形式。
• common/decorator/common_decorator.py:superuser_required：讀 legacy Flask session（非 UserContextDTO），且全站無 caller（dead）→ 不動。

6.5 本波未處理（列出回報，非默默略過）

軸③ 資源域守門，一律 app service 層、common.authz canonical import。

7.1 已完成（已修待驗）

單測：test_fr048_ssp_export_guard（2）、test_fr048_grc_guards（4）。pytest test/ 對比 baseline 零新增失敗（76 fail / 41 err 全為既有 stale/env；passed 662→675＝本波 6 + Phase 3 的 7）。DI 全 boot 驗證受限於本 sandbox 缺 GITLAB/GITHUB token（jedi_issue import 期實例化，Phase 3 已記同狀況）；wiring 以嚴格 inspection 確認（participant_role_service / associations_container.project_domain_service 皆既有 provider）。

7.2 留待下一波（列出回報，非默默略過）

關鍵待辦：common/authz/project.py 增 assert_project_participant（任一參與者放行）＝解鎖 jobs/export、comments、project_summary_report、subtask 四組的前置。這是小 canonical 補強（design §2.1 已認可「任一參與者」為軸③一支），非新軸。

完成 2b 交棒單剩餘 + 跨 phase 縫隙。守門一律 common.authz canonical。

已完成（已修待驗）

單測新增 16 案（participant 5 / evidence 5 / workflow 政策 6）全綠。回歸驗證：對 baseline f1ea97c3 比對 FAILED/ERROR 集合，76 failed / 41 errors 逐一相同（零新增失敗），passed 675→691＝本波 16 新測；無既有通過測試回歸。

留待下一波（列出回報，非默默略過）

收掉 2b-2 §7.3 尾巴。守門一律 common.authz canonical。

已完成（已修待驗）

單測新增 7 案（PSR 4 / job 留言 3）全綠。batch-complete 守門＝既有 assert_project_manager 呼叫（test_fr048_grc_guards 已覆蓋；本 service import WorkflowExecutionService 有既有循環 import，不另單獨 import 測）。回歸：對 baseline c05ed713 比對，76 failed / 41 errors 相同（零新增失敗），passed 691→698＝本波 7 新測。

FE 查證結論（檔案下載類，逐支）

留待後續（非默默略過）

Phase 2b（含 2b/2b-2/2b-3）軸③ 資源域收口大致完成；剩餘為 v1-dead（subtask）、套件下沉（process/comments）、Phase 4 signed-token（原生下載）三類非本軸工作。

§4 B 類收編完成：app/grc/service/ 7 份私有 _check_* 複製品 → 委派 common.authz canonical，行為保真、零行為變更、call site 全不動。

canonical：common/authz/project.py 新增 assert_project_role(participant_domain_service, project_id, user_id, allowed_roles=("manager",), error_code=None)——project 層 participant 精確查詢守門，不做 control→group→project fallback（那是 assert_project_manager 的軸，兩支並列在 __init__.py 決策表、語意不可互相冒充）。error_code 未給時按 allowed_roles 選預設（含 auditor→GRC_NOT_AUDITOR，否則 GRC_NOT_MANAGER）；manager override 由 caller 用 allowed_roles=("auditor","manager") 明示。

7 份對映：

✅ 已定調並對齊（2026-07-07 user 拍板「讓 manager 可代行」）：audit_service._check_role 原為 exact match 無 manager override（與 audit_round / assessment_* 不同調），收編時先保真並標註。user 定調後已對齊：auditor 端點改 allowed_roles=(required_role, "manager")，manager 可代行 AR 相關寫入（generate-draft / judge / observation / risk），全站 override 語意一致。此為 2c 收尾唯一的行為變更（放寬，非收緊）。

驗證：baseline worktree（2c 前 commit 8068d954）集合 diff——pytest test/ --continue-on-collection-errors FAILED/ERROR 節點集比對，新增失敗 0；2 支 task_execution 測試在全套跑 FAILED→PASSED 為既有跨測試順序 flakiness（隔離跑兩樹皆 5 綠），與本案無關。7 份方法體皆只剩委派一行＋註解，殘留複製邏輯 0；now-unused import（ForbiddenError / ProjectParticipantQueryEntity）順手清除。

軸④ capability guard 建置 + §6.3 過渡名單換裝完成。

① guard 本體：common/authz/capability.py — @require_capability(*names, mode="any"/"all", error_code=?)。 委派 DI CapabilityGuard（auth_container.capability_guard，自帶 @transaction），走 web-menu 既有查詢鏈 user→roles→role.capabilities→cap.name（不另立查詢路徑）；flask.g per-request memoize；帳號層 super_admin break-glass 直接放行（viewer_is_super_admin()）。錯誤碼 GRC_CAPABILITY_REQUIRED(GRC_403022)。單測 test_authz_capability.py 14 案全綠。commit eb590ae4。

② 能力點策略（user 定調）：復用既有 121 顆 granular cap（<resource>.<action>）、精準對 HTTP verb（POST→create／PUT→update／DELETE→delete／敏感 GET→read），不新造 .manage 平行方案 （避免與 FE 選單所讀的 granular RBAC 分裂＝第五套）。Administrator[root,id=2] 已全持有既有 write cap， 換裝零 role_capabilities 變更。只 3 組缺口新 seed（migration 2026-07-07-fr048-phase4a-capability-seed.sql， 已套 DEV、驗冪等）：system_config.{create,update,delete}（is_platform，泛用設定寫入觸及平台級）、 feedback.export（feedback.create 語意為使用者提交、不可復用）、notification.test（無 notification resource）。commit 7828653e。

③ 換裝（35 檔，commit e8b28a4a）：@require_super_admin_route → @require_capability("<res>.<verb-action>")。 模組→resource：auth user/role/department、bulletin、device、information-system、system-menu、 remote-agent-manage、module-frame（15 檔）、survey（4 檔，survey_route 見下）、ldap-config、report、 system_config、feedback.export、notification.test。flow_template 用 3 支 verb-specific alias 保留自訂碼 GRC_FLOW_TEMPLATE_NO_PERMISSION。軸① platform decorator 本波不換（tenant/log/framework 維持 @require_platform_admin_route）。

④ 語意變化（重要，須手測確認）：判定從「帳號層 super_admin」→「持有能力點 或 super_admin break-glass」。持 Administrator 角色的一般帳號現在也能過（原本 403）——放寬到 RBAC 正軌，符合設計 §2.0；但權限面「誰能過」變了，須讓 user 知悉。

⑤ 驗證：clean worktree 集合 diff（baseline c29acbd0 無 4a／test e8b28a4a 4a-only，隔離 4b 未 commit 干擾）——FAILED/ERROR 節點集 128↔︎128 新增失敗 0，passed +14（capability 單測）；17 支換裝 route 模組 import smoke 全過。DEV live 403/pass 三態測列手測 checklist（BE user 自起）。

⚠️ 與 Phase 4b（signed-token）同 working tree 交錯：api/survey/routes/survey_route.py 的 survey CRUD 換裝已在工作區完成，但該檔 import 行同時被 4b 改（issue_signed_token/signed_token_required）、且依賴 4b 未 commit 的 common/authz/signed_token.py → 暫不納入 4a commit，待與 4b 協調後一併 commit。其餘 35 檔 不受影響。

未處理／延後：tenant.* 標 is_platform（Phase 5 併軸鋪路，有存量副作用，刻意延後）；STG/POC migration （待 user 指示）；FE 角色矩陣新 cap 顯示 / i18n（查 FE 慣例後回報）。

軸⑤ signed-token 機制＋五件收口。BE 40a7d9c5、FE 79c0133（compliance-manager-fe，17 檔含共用 signedDownloadUtil.js）。

機制：common/authz/signed_token.py — itsdangerous.URLSafeTimedSerializer，key 自 JWT_SECRET_KEY 派生、scope 當 salt（跨 scope 重放無效），payload {scope, resource_uid, user_id}，TTL 120s。issue_signed_token / verify_signed_token / @signed_token_required（純簽章軌，bind_uid_arg 可綁 path 參數）/ @signed_token_or_jwt（雙軌，bearer 軌刻意不吞例外→保留 TOKEN_401002 觸發 FE refresh）。錯誤碼 GRC_401011。單測 test_authz_signed_token.py 12 案。

五件：①otp-qrcode（發放端 /otp-qrcode-token＋token 綁發放者本人 uid＝自我限定，修掉「知 uid 拿他人 TOTP」本體洞）②framework OSCAL download（.../oscal/<uid>/token）③file download/pdf-preview（/file/access-token/<uid>＋雙軌，既有 axios 呼叫方零改動）④survey import-template（LIVE window.location 件）⑤task-survey import-template（實查 consumer 僅 _archived＝dead → 直接補 @jwt_required，不上 token）。

Review 補核（2026-07-07）：全套件 baseline 集合 diff（c29acbd0→HEAD，涵蓋 4a+4b）新增失敗 0、passed 692→724；signed-token/capability 單測 26 案獨立跑全綠。

⚠️ 4b 未完項（待補）：

1. e2e 未寫（4b prompt/設計 §6 明定前科件必附）：test repo 補「登入→個人資料頁 QR 有載出」「框架管理頁 OSCAL 下載成功」＋負向案（登出直打資源 URL→401）。
2. token 過期行為未實測（發 token→過 TTL→401）。
3. 手測 checklist 由 review session 代出（見交付訊息）。

主體收尾後的裸奔稽核（5 群 subagent + 主導逐條驗 code）挖出的真漏網——大多數 agent 報的裸奔是誤判 （只看 route 沒追 service 層守門）。逐條先驗 live 再改，通過驗證的真缺口 4 條處置如下。

10.1 已補 / 已處置

驗證：新增單測 test/test_fr048_task_survey_guard.py（6 案：writer assignee/manager-override/deny、manager pass/deny/unresolvable）全綠；test_audit_event_instrumentation.py 補守門 fixture（1 案回綠 + _build_* 注入 guard deps）。回歸：baseline worktree（起點 108df8f8）集合 diff——FAILED/ERROR 128↔︎126（新增失敗 0；少 2 為既有 test_task_execution_service 跨測序 flaky，隔離跑綠），passed 724→730＝本波 6 新測。

10.2 稽核誤判澄清（備查，避免下次重查）

裸奔稽核 agent 報的其餘「缺口」經主導逐條追 service 層後確認已守 / 非缺口，記此免重查：

本 §10 收口後，Phase 2b 軸③ 資源域含裸奔稽核補洞大致封版；剩 v1-dead（subtask）、套件下沉（process/comments）、Phase 4 signed-token（原生下載）三類非本軸工作（見 §7.4 末）。