hs-sql-agent 的管理端授權使用 canonical permission path + action code。canonical path 是穩定的授權資源識別碼，不是 Admin UI 路由，也不是 HTTP 掛載路徑。例如 /runtime/db-management 與 /auth/role 即使導覽或 controller URL 重新整理，仍代表同一個授權身分。
相同的 canonical identifiers 支援兩種互斥的管理端授權模式。使用內建身分系統時，HsSqlAgent 的 member / role 會解析 permission/action templates；使用 host authorization 時，HsSqlAgent 會透過 HsSqlAgentPermissionResource.Permissions 把要求的 canonical permission keys 交給宿主，由宿主映射到自己的 policy model。除非特別說明，下方角色與 template 章節描述的是 內建身分模式。
實際權限組合
| 受保護操作 | 所需組合 |
|---|---|
| 查看 Database Management | /runtime/db-management → view |
| 建立 Database Management 項目 | /runtime/db-management → create |
| 編輯語意中繼資料 | /runtime/db-management/semantic → edit |
| 管理 MCP 金鑰 | /runtime/mcp-keys 搭配對應 action |
| 查看使用者 | /auth/user → view |
| 編輯角色 | /auth/role → edit |
| 查看稽核紀錄 | /runtime/audit → view |
| 匯出稽核紀錄 | /runtime/audit → export |
| 編輯安全政策 | /runtime/security → edit |
| 重試外送 | /runtime/operability → edit |
因此，只通過身分驗證仍不足以執行這些操作；所需的 path/action 組合還必須能從該成員被指派的角色中取得。
permission-action-templates 是正式權限清單
Role API 提供 permission-action-templates，它是可配置權限的正式清單。每個範本包含：
- permission 的 ID、名稱與 path；
- action 的 ID、code 與名稱。
角色資料以 { PermissionId, ActionId } 組合提交選擇。Role service 會去除重複項目，並且只保存範本清單中真實存在的組合。
角色是權限指派單位
成員會被指派一個或多個角色，而每個角色包含一組 permission/action 選擇：
Member
└─ Role(s)
└─ Permission path + Action一位成員可以同時擁有多個角色；實際可用的管理權限，是這些角色權限的聯集。
授權變更會讓舊狀態立即失效
編輯角色屬於安全敏感操作。權限改變時，Role service 會找出受影響的成員、遞增其 security version，並透過 auth runtime-state cache barrier 完成狀態更新。
這樣可以避免角色定義已變更，但既有登入工作階段仍長時間沿用舊授權結果。
受保護的 SuperUser 角色
SuperUser 是 hs-sql-agent 內建且受保護的角色，不能透過一般角色管理流程修改或刪除，以免原本具有完整控制權的角色被重新定義成另一套權限集合。
相關文件
- 成員與角色 — 成員生命週期與角色保護機制。
- Database Management — 資料庫與語意中繼資料的權限範例。
- MCP Keys — MCP 憑證與管理端角色屬於不同授權邊界。
- 安全政策 — 透過獨立的管理端權限管理 SQL、速率與並行執行政策。