2 Commits
Author SHA1 Message Date
admin 2a58d5adab docs(changelog): v1.3.3 发布说明([Unreleased] 定版 issue #7 clearance 配置) 2026-09-07 17:43:46 +08:00
admin 8388e14772 feat(access): 补 principal clearance 配置入口(采纳 issue #7)
用户报告「principal_clearances 不可配置,导致 L3 实例对所有非 manager 主体不可见」
—— 实测是 UX 缺口:

### 修复
- PUT /access/principals/:name 的 principalUpdateInput 新增 clearances 字段(nil=不动;
  非空数组(含 [])= 全量替换),与 PUT /principals/:name/clearances 同义。
- GET /access/principals/:name 响应新增 clearances 数组(保证非 nil,空集序列化为 [])。
- GET /access/principals 列表也回显 clearances,避免管理员看不到当前状态。

### 新增 MCP 工具(之前 36 个没有这一片)
- list_principals:列出全部主体及其 clearance。
- get_principal:按名取单个主体(含 description / has_api_key / clearances)。
- set_principal_clearance:全量替换主体 clearance(alias 接受 markings / clearances)。

### 不动的部分
- seedAccessControlDefaults 中 manager 默认 [L0,L1,L2,L3,L4] 已正确(CHANGELOG v1.2.0
  「manager 不受影响」依然成立)。
- classificationCond / classAllowed 对 manager 显式放行已正确;用户报告的「admin
  看不到 L3」实际是误读——真正不可见的是非 manager 主体(默认 connector L0-L2、public L0)。

### 验证
- 新增 3 个集成测试(issue7_clearance_config_test.go):
  updatePrincipal clearances / MCP 端到端 / 旧专用端点回归,全绿。
- 既有测试除 TestIntegration_ClassificationFilter 外全绿(后者预存在失败)。
2026-09-07 17:38:54 +08:00
4 changed files with 400 additions and 7 deletions

No files matched your search

+29
View File
@@ -18,6 +18,35 @@ AI 客户端在使用本平台过程中发现 bug 或有改进建议,**请提
## 版本历史
## [1.3.3] - 2026-09-07 访问控制:principal clearance 可配置(issue #7)
按 用户提交 issue #7:「principal_clearances 不可配置,导致 L3 实例对所有非 manager 主体不可见」
——实测是 UX 缺口而非模型 bug:管理界面的主体编辑入口(PUT /principals/:name)完全不接受
clearances 字段,导致管理员找不到"按主体配 clearance" 的入口(其实 PUT /principals/:name/clearances
专用端点一直存在,只是用户没找到)。
### 修复
- `PUT /api/v1/access/principals/:name` 的 `principalUpdateInput` 新增 `clearances` 字段(`[]string`)。
nil=不动;非空=全量替换(DELETE + INSERT),与 PUT /principals/:name/clearances 同义。
- `GET /api/v1/access/principals/:name` 响应新增 `clearances` 数组(保证非 nil,空集序列化为 `[]`)。
- `GET /api/v1/access/principals` 列表也回显 `clearances`,避免管理员看不到当前状态。
### 新增 MCP 工具
- `list_principals`:列出全部主体及其 clearance(之前 36 个工具没有读入口)。
- `get_principal`:按名取单个主体(含 description / has_api_key / clearances)。
- `set_principal_clearance`:全量替换主体 clearance(alias 接受 `markings` / `clearances`)。
### 不动的部分
- `seedAccessControlDefaults` 中 manager 默认 `[L0,L1,L2,L3,L4]` 已正确(CHANGELOG v1.2.0
「manager 不受影响」承诺依然成立)。
- `classificationCond` / `classAllowed` 中 `if authz.Principal == "manager" { return ... }` 已正确
豁免;用户报告的「admin 看不到 L3」实际是误读——真正不可见的是非 manager 主体(默认
connector L0-L2、public L0)。
### 验证
- 新增 3 个集成测试(issue7_clearance_config_test.go):
updatePrincipal clearances / MCP 端到端 / 旧专用端点回归,全绿。
## [1.3.2] - 2026-09-07 本体:补 update_object_type / add_object_type_property(issue #6)
按 用户提交 issue #6:「原生分级引擎无法接管存量 data_level:已存在类型无法注册 classification_property」——
+69 -7
View File
@@ -32,6 +32,8 @@ func (a *app) listPrincipals(c *gin.Context) {
HasAPIKey bool `json:"has_api_key"`
APIKeyHint string `json:"api_key_hint"`
APIKeyCreatedAt string `json:"api_key_created_at,omitempty"`
// 修复 issue #7:clearances 一并回显,否则管理员看不到当前主体的可见级别集。
Clearances []string `json:"clearances"`
}
var out []pRow
for rows.Next() {
@@ -40,7 +42,7 @@ func (a *app) listPrincipals(c *gin.Context) {
var builtin bool
if err := rows.Scan(&p.Name, &p.Description, &builtin, &key); err == nil {
p.IsBuiltin = builtin
row := pRow{Principal: p, HasAPIKey: key != ""}
row := pRow{Principal: p, HasAPIKey: key != "", Clearances: []string{}}
if key != "" {
row.APIKeyHint = maskAPIKey(key)
row.APIKeyCreatedAt = "已绑定"
@@ -48,10 +50,30 @@ func (a *app) listPrincipals(c *gin.Context) {
out = append(out, row)
}
}
// 单独查询所有 clearances(按 principal 分组),避免 N+1
if len(out) > 0 {
clRows, err := a.pool.Query(c, `SELECT principal, marking FROM principal_clearances ORDER BY principal, marking`)
if err == nil {
idx := map[string]int{}
for i, p := range out {
idx[p.Name] = i
}
for clRows.Next() {
var pn, mk string
if clRows.Scan(&pn, &mk) == nil {
if i, ok := idx[pn]; ok {
out[i].Clearances = append(out[i].Clearances, mk)
}
}
}
clRows.Close()
}
}
c.JSON(200, gin.H{"principals": out, "count": len(out)})
}
// getPrincipal 返回单个主体,manager 可拿到完整 api_key(仅展示一次以外不会在 list 中回)
// getPrincipal 返回单个主体,manager 可拿到完整 api_key(仅展示一次以外不会在 list 中回)。
// 修复 issue #7:响应同时回显 clearances 数组,否则前端拿不到主体可见级别集。
func (a *app) getPrincipal(c *gin.Context) {
name := c.Param("name")
var description string
@@ -75,6 +97,20 @@ func (a *app) getPrincipal(c *gin.Context) {
resp["api_key"] = key
resp["api_key_hint"] = maskAPIKey(key)
}
// 拉 clearances(保证非 nil,序列化成 [] 而不是 null)
cls := []string{}
clRows, clErr := a.pool.Query(c,
`SELECT marking FROM principal_clearances WHERE principal=$1 ORDER BY marking`, name)
if clErr == nil {
defer clRows.Close()
for clRows.Next() {
var m string
if clRows.Scan(&m) == nil {
cls = append(cls, m)
}
}
}
resp["clearances"] = cls
c.JSON(200, resp)
}
@@ -101,13 +137,18 @@ type principalInput struct {
}
type principalUpdateInput struct {
Description *string `json:"description"`
APIKey *string `json:"api_key"`
ClearAPIKey bool `json:"clear_api_key"`
GenerateAPIKey bool `json:"generate_api_key"`
Description *string `json:"description"`
APIKey *string `json:"api_key"`
ClearAPIKey bool `json:"clear_api_key"`
GenerateAPIKey bool `json:"generate_api_key"`
// 修复 issue #7:之前 PUT /principals/:name 完全不接受 clearances 字段(用户传时静默忽略),
// 现允许一次性替换主体的 clearance 集(与 PUT /principals/:name/clearances 同义)。
// nil=不动;[]=清空;非空=全量替换(DELETE + INSERT)。
Clearances *[]string `json:"clearances"`
}
// updatePrincipal 修改主体的说明和 api_key
// updatePrincipal 修改主体的说明、api_key、clearances(合并语义)。
// 修复 issue #7:之前 clearances 字段被静默忽略;现支持在同一次 PUT 中同时改 description / api_key / clearances。
func (a *app) updatePrincipal(c *gin.Context) {
name := c.Param("name")
var in principalUpdateInput
@@ -149,11 +190,29 @@ func (a *app) updatePrincipal(c *gin.Context) {
return
}
}
// 修复 issue #7:clearances 字段支持。nil=不动;非空数组(含 [])= 全量替换。
if in.Clearances != nil {
if _, err := tx.Exec(c, `DELETE FROM principal_clearances WHERE principal=$1`, name); err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
for _, m := range *in.Clearances {
if m = strings.TrimSpace(m); m != "" {
if _, err := tx.Exec(c,
`INSERT INTO principal_clearances(principal,marking) VALUES($1,$2) ON CONFLICT DO NOTHING`,
name, m); err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
}
}
}
if err := tx.Commit(c); err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
a.InvalidateAuthzCache(name)
// 回读,让前端能立即核对(同时验证上面 writes)
resp := gin.H{"ok": true, "name": name}
if finalKey != "" {
resp["api_key"] = finalKey
@@ -164,6 +223,9 @@ func (a *app) updatePrincipal(c *gin.Context) {
} else {
resp["has_api_key"] = finalKey != ""
}
if in.Clearances != nil {
resp["clearances"] = *in.Clearances
}
c.JSON(200, resp)
}
+77
View File
@@ -513,6 +513,40 @@ func mcpToolList() []MCPTool {
"required": []string{"id"},
},
},
// 修复 issue #7:MCP 工具集补齐主体维度的读/写入口(之前 36 个工具缺这一片)。
// list_principals / get_principal 只读;set_principal_clearance 是写入(manager 主体)。
{
Name: "list_principals",
Description: "【只读】列出全部主体及其 clearance(分级可见级别)。用于核对「哪些主体能看哪些分级」。",
InputSchema: map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{},
},
},
{
Name: "get_principal",
Description: "【只读】按名称取单个主体(含 description / has_api_key / clearances)。",
InputSchema: map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"name": map[string]interface{}{"type": "string", "description": "主体名"},
},
"required": []string{"name"},
},
},
{
Name: "set_principal_clearance",
Description: "【写入】全量替换主体的 clearance 集(nil 数组=清空)。修复 issue #7 之前 MCP 工具集完全无法配置 clearance 的缺口。可让 connector 也能看 L3 等。",
InputSchema: map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"name": map[string]interface{}{"type": "string", "description": "主体名"},
"clearances": map[string]interface{}{"type": "array", "items": map[string]interface{}{"type": "string"}, "description": "标记集,如 [L0,L1,L2,L3];传 []=清空;alias: markings"},
"markings": map[string]interface{}{"type": "array", "items": map[string]interface{}{"type": "string"}, "description": "alias 同 clearances(与 PUT /principals/:name/clearances 命名一致)"},
},
"required": []string{"name"},
},
},
}
}
@@ -813,6 +847,49 @@ func (a *app) mcpDispatchTool(c *gin.Context, name string, args map[string]inter
t, st := a.callHandler(a.addProperty, gin.Params{gin.Param{Key: "name", Value: apiName}}, body, principal)
return t, false, st >= 400
// 修复 issue #7:MCP 工具集补齐「按主体维度读/写 clearance」。
// 之前 36 个工具没有这俩,导致管理员改不了「connector 看不到 L3」之类配置。
case "list_principals":
t, st := a.callHandler(a.listPrincipals, nil, nil, principal)
return t, false, st >= 400
case "get_principal":
name, _ := args["name"].(string)
if name == "" {
return "参数错误:name 必填", false, true
}
t, st := a.callHandler(a.getPrincipal, gin.Params{gin.Param{Key: "name", Value: name}}, nil, principal)
return t, false, st >= 400
case "set_principal_clearance":
if !canWrite {
return denyWrite()
}
name, _ := args["name"].(string)
if name == "" {
return "参数错误:name 必填", false, true
}
// 接受 clearances / markings 两种命名(与 PUT /principals/:name/clearances 一致用 markings)
var marks []string
if raw, ok := args["clearances"].([]interface{}); ok {
for _, m := range raw {
if s, ok := m.(string); ok {
marks = append(marks, s)
}
}
}
if raw, ok := args["markings"].([]interface{}); ok {
marks = marks[:0]
for _, m := range raw {
if s, ok := m.(string); ok {
marks = append(marks, s)
}
}
}
body, _ := json.Marshal(map[string]interface{}{"markings": marks})
t, st := a.callHandler(a.putClearances, gin.Params{gin.Param{Key: "name", Value: name}}, body, principal)
return t, false, st >= 400
case "create_link_type":
if !canWrite {
return denyWrite()
+225
View File
@@ -0,0 +1,225 @@
//go:build integration
package main
import (
"strings"
"testing"
)
// TestIntegration_UpdatePrincipal_Clearances 修复 issue #7:
// 之前 PUT /access/principals/:name 的 clearances 字段被静默忽略,
// 用户找不到任何「编辑主体 clearance」的入口。
// 验证:clearances 数组在 PUT 时一并落库(DELETE + INSERT 全量替换),
// GET /principals/:name 和 listPrincipals 都能回显。
func TestIntegration_UpdatePrincipal_Clearances(t *testing.T) {
env, _ := setupTestEnv(t)
h := map[string]string{"X-Principal": "manager"}
// 用一个非内置主体(避免污染 manager seed)
key := "test_principal_clearance"
t.Cleanup(func() {
env.httpDo(t, "DELETE", "/api/v1/access/principals/"+key, nil, h)
})
if code, _ := env.httpDo(t, "POST", "/api/v1/access/principals",
map[string]any{"name": key, "description": "测试 clearance 配置"}, h); code != 201 {
t.Fatalf("create principal failed: %d", code)
}
// 1) PUT 设置 clearances
code, body := env.httpDo(t, "PUT", "/api/v1/access/principals/"+key,
map[string]any{"clearances": []string{"L0", "L1", "L2"}}, h)
if code != 200 {
t.Fatalf("PUT 应 200, got %d body=%v", code, body)
}
if got := body["clearances"]; got == nil {
t.Errorf("响应应回显 clearances, got %v", body)
}
// 2) GET /principals/:name 应回显
_, get := env.httpDo(t, "GET", "/api/v1/access/principals/"+key, nil, h)
cls := get["clearances"].([]any)
if len(cls) != 3 {
t.Errorf("GET 应回 3 项, got %d (%v)", len(cls), cls)
}
// 3) 再次 PUT 全量替换(含 L3)→ 验证替换语义
code, body = env.httpDo(t, "PUT", "/api/v1/access/principals/"+key,
map[string]any{"clearances": []string{"L0", "L1", "L2", "L3"}}, h)
if code != 200 {
t.Fatalf("PUT 应 200, got %d", code)
}
_, get2 := env.httpDo(t, "GET", "/api/v1/access/principals/"+key, nil, h)
cls2 := get2["clearances"].([]any)
if len(cls2) != 4 {
t.Errorf("替换后应 4 项, got %d (%v)", len(cls2), cls2)
}
// 4) PUT clearances=[] 清空
code, _ = env.httpDo(t, "PUT", "/api/v1/access/principals/"+key,
map[string]any{"clearances": []string{}}, h)
if code != 200 {
t.Fatalf("PUT 空数组应 200, got %d", code)
}
_, get3 := env.httpDo(t, "GET", "/api/v1/access/principals/"+key, nil, h)
cls3 := get3["clearances"].([]any)
if len(cls3) != 0 {
t.Errorf("清空后应 0 项, got %d (%v)", len(cls3), cls3)
}
// 5) PUT 不带 clearances 字段 → 不动(之前的 clearance 仍空)
code, _ = env.httpDo(t, "PUT", "/api/v1/access/principals/"+key,
map[string]any{"description": "只改 desc"}, h)
if code != 200 {
t.Fatalf("PUT 不带 clearances 应 200, got %d", code)
}
_, get4 := env.httpDo(t, "GET", "/api/v1/access/principals/"+key, nil, h)
cls4 := get4["clearances"].([]any)
if len(cls4) != 0 {
t.Errorf("未传 clearances 时应保留之前状态(空),got %v", cls4)
}
if get4["description"] != "只改 desc" {
t.Errorf("description 应被更新, got %v", get4["description"])
}
// 6) listPrincipals 应回显该主体的 clearance
_, list := env.httpDo(t, "GET", "/api/v1/access/principals", nil, h)
var found bool
for _, p := range list["principals"].([]any) {
m := p.(map[string]any)
if m["name"] == key {
if clsL := m["clearances"]; clsL == nil {
t.Errorf("listPrincipals 应回显 clearances, got nil")
}
found = true
}
}
if !found {
t.Errorf("listPrincipals 缺新建的 %s", key)
}
}
// TestIntegration_SetPrincipalClearance_MCP 修复 issue #7 方案 A:
// MCP set_principal_clearance 工具能写入;list_principals / get_principal 能读取。
func TestIntegration_SetPrincipalClearance_MCP(t *testing.T) {
env, _ := setupTestEnv(t)
h := map[string]string{"X-Principal": "manager"}
key := "test_mcp_clearance"
t.Cleanup(func() {
env.httpDo(t, "DELETE", "/api/v1/access/principals/"+key, nil, h)
})
if code, _ := env.httpDo(t, "POST", "/api/v1/access/principals",
map[string]any{"name": key, "description": "MCP clearance 测试"}, h); code != 201 {
t.Fatalf("create principal failed: %d", code)
}
// 1) MCP set_principal_clearance
code, body := env.httpDo(t, "POST", "/api/v1/mcp",
map[string]any{
"jsonrpc": "2.0", "id": "1", "method": "tools/call",
"params": map[string]any{
"name": "set_principal_clearance",
"arguments": map[string]any{
"name": key,
"clearances": []string{"L0", "L1", "L2", "L3"},
},
},
}, h)
if code != 200 {
t.Fatalf("MCP 应 200, got %d body=%v", code, body)
}
// 2) MCP get_principal 应回显
code, body = env.httpDo(t, "POST", "/api/v1/mcp",
map[string]any{
"jsonrpc": "2.0", "id": "2", "method": "tools/call",
"params": map[string]any{
"name": "get_principal",
"arguments": map[string]any{"name": key},
},
}, h)
if code != 200 {
t.Fatalf("get_principal 应 200, got %d", code)
}
result := body["result"].(map[string]any)
content := result["content"].([]any)
text := content[0].(map[string]any)["text"].(string)
if !strings.Contains(text, `"clearances"`) {
t.Errorf("get_principal 响应应含 clearances, got %s", text)
}
if !strings.Contains(text, `"L3"`) {
t.Errorf("get_principal 响应应含 L3, got %s", text)
}
// 3) MCP list_principals 应包含该主体
code, body = env.httpDo(t, "POST", "/api/v1/mcp",
map[string]any{
"jsonrpc": "2.0", "id": "3", "method": "tools/call",
"params": map[string]any{
"name": "list_principals",
"arguments": map[string]any{},
},
}, h)
if code != 200 {
t.Fatalf("list_principals 应 200, got %d", code)
}
result2 := body["result"].(map[string]any)
content2 := result2["content"].([]any)
text2 := content2[0].(map[string]any)["text"].(string)
if !strings.Contains(text2, key) {
t.Errorf("list_principals 应包含新建 %s, got %s", key, text2)
}
// 4) MCP 缺 name 应报错
code, body = env.httpDo(t, "POST", "/api/v1/mcp",
map[string]any{
"jsonrpc": "2.0", "id": "4", "method": "tools/call",
"params": map[string]any{
"name": "set_principal_clearance",
"arguments": map[string]any{
"clearances": []string{"L0"},
},
},
}, h)
if code != 200 {
t.Fatalf("MCP 错误应 200, got %d", code)
}
r4 := body["result"].(map[string]any)
c4 := r4["content"].([]any)
t4 := c4[0].(map[string]any)["text"].(string)
if !strings.Contains(t4, "name") {
t.Errorf("MCP 缺 name 应报错, got %s", t4)
}
}
// TestIntegration_PutClearances_Rest 顺带验证既有的
// `PUT /principals/:name/clearances` 端点仍然有效(用户不知道有这个端点)。
// 这是 issue #7 的关键发现:端点一直都在,只是用户认知里没有。
func TestIntegration_PutClearances_Rest(t *testing.T) {
env, _ := setupTestEnv(t)
h := map[string]string{"X-Principal": "manager"}
key := "test_legacy_clearance_path"
t.Cleanup(func() {
env.httpDo(t, "DELETE", "/api/v1/access/principals/"+key, nil, h)
})
if code, _ := env.httpDo(t, "POST", "/api/v1/access/principals",
map[string]any{"name": key, "description": "测试旧端点"}, h); code != 201 {
t.Fatalf("create principal failed: %d", code)
}
// 用 PUT /principals/:name/clearances(既有的专用端点)
code, _ := env.httpDo(t, "PUT", "/api/v1/access/principals/"+key+"/clearances",
map[string]any{"markings": []string{"L0", "L2"}}, h)
if code != 200 {
t.Fatalf("PUT clearances 应 200, got %d", code)
}
// GET /principals/:name/clearances(既有只读端点)
_, get := env.httpDo(t, "GET", "/api/v1/access/principals/"+key+"/clearances", nil, h)
cls := get["clearances"].([]any)
if len(cls) != 2 {
t.Errorf("既有专用端点 GET 应 2 项, got %d", len(cls))
}
}