一次收口 2026-11-06 的九项能力(CHANGELOG 1.5.4 → 1.8.0): - 自检探针(readiness.go):check_readiness / check_answerable 两个只读探针,把 「本体里没有」「我没权限看」「模型没抽全」三种空结果原因拆开 - 读路径语义钉死(scope.go):标记与分级的可见范围统一由 Scope 产出,实例分级 为空时继承类型默认级(fail-closed),列表与详情口径一致 - 行级可改性轴(object_owner.go):归属只收窄不宽于 grants,所有对象写路径统一 走 canWriteObject,归属查询失败即拒绝 - 公理第 6 类 certification:认证位保护人工策展内容,AI 重摄取不再覆盖已认证条目 - 跨版本结构 diff(schema_diff.go):schema_snapshots 全量快照 + diff 端点,机器 事实与人工策展分组呈现 - 分区维度 zone:分区绑类型、命中任一即可见,读路径一律带 zone 条件 - 统一分页信封(pagination.go):列表回包统一 count/total/limit/offset/has_more/ truncated,total 与 items 同源 - MCP 长任务进度(mcp_progress.go):客户端带 progressToken 才走 SSE 进度帧 - 本体 schema 导入(ontology_import.go):Turtle 导入 + 四道 fail-fast 闸门 + 整事务 + (source, external_id) 幂等 + IRI 往返不变式 MCP 工具清单并入单一注册表(mcp_registry.go),对外声明与实际可调不再各说各话; 工具数 42 → 54(只读 27 / 写入 27),注册表与分发 case 的双向漂移由 AST 单测拦截。 CHANGELOG 编号整理:新「认证位 + 行级归属」条目由 1.6.0 改为 1.5.6(1.6.x 留给 分区与结构 diff),2026-09-20 的 GB/T 规划稿改标「规划稿·未发布」——该能力已并入 v1.5.1,避免与正式发布的版本号重复。 Co-Authored-By: Claude Code <[email protected]>
277 lines
9.2 KiB
Go
277 lines
9.2 KiB
Go
package main
|
||
|
||
// 分区维度(zone):目录分区 + 授权边界。
|
||
//
|
||
// 借鉴 NVIDIA auto-ontology 的 zone(`dal/schema.py:729-790`、`dal/terms.py:82-104`):
|
||
// zone 不是「相关度过滤」(相关度过滤是排序问题),而是**授权边界**——
|
||
// 「落在 zone 之外的实体被完全隐藏,而不是排在后面」。
|
||
//
|
||
// 与本仓另两个维度的关系(三个维度叠加,AND,不是互斥):
|
||
//
|
||
// marking / clearance —— 「这一行有多敏」 (实例级,object_markings + principal_clearances)
|
||
// classification —— 「这一行有多级」 (实例级 + 类型默认值)
|
||
// zone —— 「这一类属于哪个目录」 (类型级,object_zones + principal_zones)
|
||
//
|
||
// 三个维度各管一件事,任何一个拒绝即不可见。zone 与 marking 不互斥:
|
||
// 一个实例可以既在「财务」分区里、又被标了 L2 敏级——要看到它,
|
||
// 主体既得持有该分区、也得有 L2 的 clearance。
|
||
//
|
||
// **分区绑定在对象类型上**(不是实例上),这是本仓的取舍:
|
||
// - 本仓的「数据资产层」就是对象类型(承载业务实体/资产的类);
|
||
// 分区到类型 ⇒ 一次查询即可判定该请求内全部实例的可见性;
|
||
// - 实例级分区需要给每一行单独打标,且极易在新增读路径时漏掉 ⇒
|
||
// NVIDIA 的 zone 之所以「半成品」,正是全局关闭后没人再管它
|
||
// (benchmark 文档 §3.4)。类型级分区能保证**每个读路径都带得上一条条件**。
|
||
//
|
||
// 判定口径(命中任一即可见,与「目录分区」的直觉一致):
|
||
//
|
||
// - 类型不属于任何分区 → 公共区,所有主体可见;
|
||
// - 类型属于分区集合 Z → 主体持有 Z 中**至少一个**分区即可见;
|
||
// - 主体一个分区都没有 → 所有被分区的类型都不可见(fail-closed)。
|
||
//
|
||
// 「命中任一」而不是「必须全中」:类型同时属于两个目录(财务 + 集团共享)时,
|
||
// 持有任一目录的主体都应看得到——若要求「全中」,往类型上加第二个分区会
|
||
// 静默夺走已有主体的可见性(这类静默失权比泄露更难排查)。
|
||
|
||
import (
|
||
"context"
|
||
"errors"
|
||
"log"
|
||
"sort"
|
||
"strconv"
|
||
"strings"
|
||
)
|
||
|
||
// 分区名校验错误。
|
||
var (
|
||
errZoneNameEmpty = errors.New("分区名必填")
|
||
errZoneNameTooLong = errors.New("分区名最长 64 字符")
|
||
)
|
||
|
||
// Zone 分区配置(对外形状)。
|
||
type Zone struct {
|
||
Name string `json:"name"`
|
||
Description string `json:"description"`
|
||
Types []string `json:"types"` // 落在本分区的对象类型
|
||
Principals []string `json:"principals"` // 持有本分区的主体
|
||
}
|
||
|
||
// zoneFilter 一次请求内的分区判定结果。
|
||
//
|
||
// 分区绑在类型上 ⇒ 判定一次即可覆盖该请求里的全部实例,无需逐对象查库。
|
||
type zoneFilter struct {
|
||
denied map[string]bool // 主体无权访问的对象类型
|
||
// failClosed 为真表示分区配置读取失败:此时一律拒绝(读不到配置 ≠ 可以看)。
|
||
failClosed bool
|
||
}
|
||
|
||
// allows 该对象类型对主体是否可见。
|
||
func (f *zoneFilter) allows(objType string) bool {
|
||
if f == nil {
|
||
return true
|
||
}
|
||
if f.failClosed {
|
||
return false
|
||
}
|
||
return !f.denied[objType]
|
||
}
|
||
|
||
// deniedTypes 无权访问的类型(有序)。
|
||
func (f *zoneFilter) deniedTypes() []string {
|
||
if f == nil || len(f.denied) == 0 {
|
||
return nil
|
||
}
|
||
out := make([]string, 0, len(f.denied))
|
||
for t := range f.denied {
|
||
out = append(out, t)
|
||
}
|
||
sort.Strings(out)
|
||
return out
|
||
}
|
||
|
||
// zoneDeniedTypes 算出主体无权访问的对象类型集合(纯函数,便于单测)。
|
||
//
|
||
// principalZones:主体持有的分区;typeZones:对象类型 → 其所属分区列表。
|
||
// 见文件头「判定口径」:类型无分区 → 公共区;否则命中任一即可见。
|
||
func zoneDeniedTypes(principalZones map[string]bool, typeZones map[string][]string) map[string]bool {
|
||
denied := map[string]bool{}
|
||
for typ, zs := range typeZones {
|
||
if len(zs) == 0 {
|
||
continue // 公共区
|
||
}
|
||
hit := false
|
||
for _, z := range zs {
|
||
if principalZones[z] {
|
||
hit = true
|
||
break
|
||
}
|
||
}
|
||
if !hit {
|
||
denied[typ] = true
|
||
}
|
||
}
|
||
return denied
|
||
}
|
||
|
||
// zoneCondSQL 生成分区维度的 SQL 条件(与 visibilityCond / classificationCond 同构)。
|
||
//
|
||
// alias:表别名;typeCol:该表中承载「对象类型」的列名
|
||
// (objects 表为 type_api_name,links 表为 source_type / target_type)。
|
||
// 无权访问的类型集合为空 → 返回 "TRUE"(不过滤,保证「不配置分区 = 零影响」)。
|
||
func zoneCondSQL(alias, typeCol string, denied []string, args []interface{}) (string, []interface{}) {
|
||
if len(denied) == 0 {
|
||
return "TRUE", args
|
||
}
|
||
args = append(args, denied)
|
||
ph := "$" + strconv.Itoa(len(args))
|
||
return `NOT (` + alias + `.` + typeCol + ` = ANY(` + ph + `::text[]))`, args
|
||
}
|
||
|
||
// loadZoneTypeMap 取「对象类型 → 所属分区列表」。
|
||
func (a *app) loadZoneTypeMap(ctx context.Context) (map[string][]string, error) {
|
||
out := map[string][]string{}
|
||
rows, err := a.pool.Query(ctx,
|
||
`SELECT object_type, zone_name FROM object_zones ORDER BY object_type, zone_name`)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
defer rows.Close()
|
||
for rows.Next() {
|
||
var typ, zone string
|
||
if err := rows.Scan(&typ, &zone); err != nil {
|
||
continue
|
||
}
|
||
out[typ] = append(out[typ], zone)
|
||
}
|
||
return out, rows.Err()
|
||
}
|
||
|
||
// zoneFilterOf 计算当前主体在分区维度上的可见范围。
|
||
//
|
||
// 每次请求现查分区配置(object_zones 体量小、且要求「改了立刻生效」,
|
||
// 不吃缓存);主体持有的分区取自 Authz(principal_zones,变更时清缓存)。
|
||
//
|
||
// fail-closed:分区配置读不出来 → 一律拒绝。读不到配置不等于可以看。
|
||
func (a *app) zoneFilterOf(ctx context.Context, authz *Authz) *zoneFilter {
|
||
if authz == nil || authz.Principal == "manager" {
|
||
return &zoneFilter{}
|
||
}
|
||
typeZones, err := a.loadZoneTypeMap(ctx)
|
||
if err != nil {
|
||
log.Printf("[zone] 读取分区配置失败,按 fail-closed 处理: %v", err)
|
||
return &zoneFilter{failClosed: true}
|
||
}
|
||
return &zoneFilter{denied: zoneDeniedTypes(authz.Zones, typeZones)}
|
||
}
|
||
|
||
// zoneCond 把分区过滤下推成 SQL 条件(列表 / 检索 / 图谱邻居共用)。
|
||
func (a *app) zoneCond(ctx context.Context, authz *Authz, alias, typeCol string, args []interface{}) (string, []interface{}) {
|
||
zf := a.zoneFilterOf(ctx, authz)
|
||
if zf.failClosed {
|
||
// 配置读不出来:条件恒假 = 什么都看不到(与 fail-closed 一致)。
|
||
return "FALSE", args
|
||
}
|
||
return zoneCondSQL(alias, typeCol, zf.deniedTypes(), args)
|
||
}
|
||
|
||
// zoneAllowed 单个对象类型是否对主体可见(详情路径用)。
|
||
//
|
||
// 与 zoneCond 同口径:列表看不到的类型,详情也必须 404(不泄漏存在性)。
|
||
func (a *app) zoneAllowed(ctx context.Context, authz *Authz, objType string) bool {
|
||
return a.zoneFilterOf(ctx, authz).allows(objType)
|
||
}
|
||
|
||
// ---------- 分区配置的读写 ----------
|
||
|
||
// normalizeZoneName 规整分区名(去空白;不允许空)。
|
||
func normalizeZoneName(s string) (string, error) {
|
||
name := strings.TrimSpace(s)
|
||
if name == "" {
|
||
return "", errZoneNameEmpty
|
||
}
|
||
if len(name) > 64 {
|
||
return "", errZoneNameTooLong
|
||
}
|
||
return name, nil
|
||
}
|
||
|
||
// normalizeNameList 规整字符串清单:去空白、去重、保序。
|
||
func normalizeNameList(in []string) []string {
|
||
out := []string{}
|
||
seen := map[string]bool{}
|
||
for _, s := range in {
|
||
s = strings.TrimSpace(s)
|
||
if s == "" || seen[s] {
|
||
continue
|
||
}
|
||
seen[s] = true
|
||
out = append(out, s)
|
||
}
|
||
return out
|
||
}
|
||
|
||
// loadZones 取全部分区配置(含类型与主体清单)。
|
||
func (a *app) loadZones(ctx context.Context) ([]Zone, error) {
|
||
zones := map[string]*Zone{}
|
||
rows, err := a.pool.Query(ctx, `SELECT zone_name, description FROM zones ORDER BY zone_name`)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
for rows.Next() {
|
||
var name, desc string
|
||
if err := rows.Scan(&name, &desc); err != nil {
|
||
continue
|
||
}
|
||
zones[name] = &Zone{Name: name, Description: desc, Types: []string{}, Principals: []string{}}
|
||
}
|
||
rows.Close()
|
||
if err := rows.Err(); err != nil {
|
||
return nil, err
|
||
}
|
||
|
||
trows, err := a.pool.Query(ctx, `SELECT zone_name, object_type FROM object_zones ORDER BY zone_name, object_type`)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
for trows.Next() {
|
||
var z, t string
|
||
if err := trows.Scan(&z, &t); err != nil {
|
||
continue
|
||
}
|
||
if zones[z] == nil {
|
||
zones[z] = &Zone{Name: z, Types: []string{}, Principals: []string{}}
|
||
}
|
||
zones[z].Types = append(zones[z].Types, t)
|
||
}
|
||
trows.Close()
|
||
if err := trows.Err(); err != nil {
|
||
return nil, err
|
||
}
|
||
|
||
prows, err := a.pool.Query(ctx, `SELECT zone_name, principal FROM principal_zones ORDER BY zone_name, principal`)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
for prows.Next() {
|
||
var z, p string
|
||
if err := prows.Scan(&z, &p); err != nil {
|
||
continue
|
||
}
|
||
if zones[z] == nil {
|
||
zones[z] = &Zone{Name: z, Types: []string{}, Principals: []string{}}
|
||
}
|
||
zones[z].Principals = append(zones[z].Principals, p)
|
||
}
|
||
prows.Close()
|
||
if err := prows.Err(); err != nil {
|
||
return nil, err
|
||
}
|
||
|
||
out := make([]Zone, 0, len(zones))
|
||
for _, z := range zones {
|
||
out = append(out, *z)
|
||
}
|
||
sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
|
||
return out, nil
|
||
}
|