一次收口 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]>
307 lines
10 KiB
Go
307 lines
10 KiB
Go
package main
|
||
|
||
import (
|
||
"fmt"
|
||
"sort"
|
||
"strconv"
|
||
"strings"
|
||
)
|
||
|
||
// ---------- 授权范围 Scope:把「不施加过滤」与「过滤后为空」在类型层面分开 ----------
|
||
//
|
||
// 动机(借鉴 NVIDIA auto-ontology 的 None vs [] 语义分离):
|
||
//
|
||
// 「没有配置任何过滤」与「过滤条件算出来是空集合」在 SQL 层几乎长得一样——
|
||
// 前者放行全部,后者必须拒绝。把两者混为一谈正是访问控制漏洞的经典成因:
|
||
// 一次 if len(x) == 0 的疏忽,就可能让「什么都看不到」的主体「看到全部」。
|
||
//
|
||
// 本仓过去用「空 []string + 特判」隐式表达这两件事:Clearances 为空 map 时,
|
||
// visibilityCond 生成的 SQL 恰好等价于「只看公开对象」——能跑对,但语义只存在于
|
||
// 注释里,没有类型保障,改代码时没有任何东西会提醒你「这里区分了两种空」。
|
||
//
|
||
// 现在改用显式类型 Scope 承载过滤结果,构造时必须声明语义:
|
||
//
|
||
// ScopeUnscoped —— 不施加任何过滤:看到全部
|
||
// ScopeDenyAll —— 过滤生效且拒绝全部:什么都看不到
|
||
// ScopeAllow —— 过滤生效:只放行 Values 里的取值(Values 为空 = 一个都不放行)
|
||
//
|
||
// 注意 ScopeAllow 的 Values 恒表示「**可见**的取值集合」,不表示「被拒绝的集合」。
|
||
// 屏蔽表(SQL 用)由 deniedLevels 从可见集合反推,避免两套方向相反的清单同时存在。
|
||
|
||
// ScopeKind 过滤结果的三种语义分档。
|
||
type ScopeKind int
|
||
|
||
const (
|
||
// ScopeUnscoped 不施加任何过滤(manager / 该维度不适用):看到全部。
|
||
ScopeUnscoped ScopeKind = iota
|
||
// ScopeDenyAll 过滤生效且拒绝全部:什么都看不到。
|
||
ScopeDenyAll
|
||
// ScopeAllow 过滤生效:只放行 Values 里的取值。
|
||
ScopeAllow
|
||
)
|
||
|
||
func (k ScopeKind) String() string {
|
||
switch k {
|
||
case ScopeUnscoped:
|
||
return "unscoped"
|
||
case ScopeDenyAll:
|
||
return "deny_all"
|
||
default:
|
||
return "allow"
|
||
}
|
||
}
|
||
|
||
// Scope 是「某个维度上的可见范围」。
|
||
//
|
||
// 零值 Scope{Kind: ScopeUnscoped} = 不施加过滤,这是安全的默认值(宁可多看,
|
||
// 也不要在忘了初始化时把主体判成什么都看不到);但**显式构造**是必须的,
|
||
// 这样调用点一眼能看出自己声明了哪种语义。
|
||
type Scope struct {
|
||
Kind ScopeKind
|
||
Values []string
|
||
}
|
||
|
||
// unscopedScope 构造「不施加过滤」的范围。
|
||
func unscopedScope() Scope { return Scope{Kind: ScopeUnscoped} }
|
||
|
||
// denyAllScope 构造「拒绝全部」的范围。
|
||
func denyAllScope() Scope { return Scope{Kind: ScopeDenyAll} }
|
||
|
||
// allowScope 构造「只放行 vals」的范围。
|
||
//
|
||
// vals 为空集合 = 一个都不放行(拒绝),**不是**不施加过滤——这正是 None/[] 必须
|
||
// 在类型层面分开的地方。函数会拷贝入参并排序,避免调用方事后改动切片导致语义漂移。
|
||
func allowScope(vals []string) Scope {
|
||
cp := make([]string, 0, len(vals))
|
||
cp = append(cp, vals...)
|
||
sort.Strings(cp)
|
||
return Scope{Kind: ScopeAllow, Values: cp}
|
||
}
|
||
|
||
// IsUnscoped 该范围是否不施加任何过滤。
|
||
func (s Scope) IsUnscoped() bool { return s.Kind == ScopeUnscoped }
|
||
|
||
// IsDenyAll 该范围是否拒绝全部。
|
||
func (s Scope) IsDenyAll() bool { return s.Kind == ScopeDenyAll }
|
||
|
||
// Allows 该范围是否放行给定取值。
|
||
func (s Scope) Allows(v string) bool {
|
||
switch s.Kind {
|
||
case ScopeUnscoped:
|
||
return true
|
||
case ScopeDenyAll:
|
||
return false
|
||
}
|
||
for _, x := range s.Values {
|
||
if x == v {
|
||
return true
|
||
}
|
||
}
|
||
return false
|
||
}
|
||
|
||
// AllowsMarkings 判定带一组 marking 的对象是否可见。
|
||
//
|
||
// - Unscoped:不限;
|
||
// - DenyAll:全拒(主体没有任何 clearance → 什么都看不到,含无标记对象);
|
||
// - Allow:所有 marking 都必须在可见集合内;无 marking 视为公开(可见)。
|
||
func (s Scope) AllowsMarkings(marks []string) bool {
|
||
switch s.Kind {
|
||
case ScopeUnscoped:
|
||
return true
|
||
case ScopeDenyAll:
|
||
return false
|
||
}
|
||
for _, m := range marks {
|
||
if m == "" {
|
||
continue // 空标记 = 无标记 = 公开
|
||
}
|
||
if !s.Allows(m) {
|
||
return false
|
||
}
|
||
}
|
||
return true
|
||
}
|
||
|
||
func (s Scope) String() string {
|
||
switch s.Kind {
|
||
case ScopeUnscoped:
|
||
return "unscoped(全放行)"
|
||
case ScopeDenyAll:
|
||
return "deny_all(全拒)"
|
||
}
|
||
return "allow(" + strings.Join(s.Values, ",") + ")"
|
||
}
|
||
|
||
// deniedLevels 由「可见范围」反推该维度应屏蔽的取值集合(SQL 屏蔽表用)。
|
||
//
|
||
// - Unscoped:不屏蔽;
|
||
// - DenyAll:屏蔽全部级别,并把空串(未定义级别)一并屏蔽——
|
||
// 连「级别未定义」的实例都不放行(fail-closed);
|
||
// - Allow:屏蔽 = 全部 - 可见。
|
||
func deniedLevels(sc Scope, all []string) []string {
|
||
switch sc.Kind {
|
||
case ScopeUnscoped:
|
||
return nil
|
||
case ScopeDenyAll:
|
||
return append(append([]string{}, all...), "")
|
||
}
|
||
var out []string
|
||
for _, l := range all {
|
||
if !sc.Allows(l) {
|
||
out = append(out, l)
|
||
}
|
||
}
|
||
return out
|
||
}
|
||
|
||
// ---------- 标记维度(object_markings) ----------
|
||
|
||
// markingScope 计算标记维度的可见范围。
|
||
//
|
||
// - manager:不受限(Unscoped);
|
||
// - 其余主体:可见集合 = 其 clearance 集合;
|
||
// - clearance 为空(一条记录都没有):DenyAll —— 什么都看不到,
|
||
// 而不是「没有过滤条件所以看到全部」。
|
||
//
|
||
// 「无标记即公开」的口径只对**有 clearance 的主体**成立:他们至少能看到 L0 公开对象。
|
||
// 完全没有 clearance 的主体连公开对象都不看——把 clearance 清空就应当等于「彻底失明」。
|
||
func markingScope(authz *Authz) Scope {
|
||
if authz == nil || authz.Principal == "manager" {
|
||
return unscopedScope()
|
||
}
|
||
cls := make([]string, 0, len(authz.Clearances))
|
||
for m := range authz.Clearances {
|
||
cls = append(cls, m)
|
||
}
|
||
if len(cls) == 0 {
|
||
return denyAllScope()
|
||
}
|
||
return allowScope(cls)
|
||
}
|
||
|
||
// markingCond 把标记范围下推成 SQL 条件(列表 / 检索 / 图谱邻居共用)。
|
||
//
|
||
// 三种语义在 SQL 层的落法:
|
||
// - Unscoped → TRUE(不过滤)
|
||
// - DenyAll → FALSE(该主体一条都看不到)
|
||
// - Allow → NOT EXISTS(带标记且标记不在可见集合内的行)
|
||
// 可见集合为空时该式等价于「只放行无标记对象」,与 CanRead 的逐对象判定同义。
|
||
func markingCond(sc Scope, alias, typeCol, pkCol string, args []interface{}) (string, []interface{}) {
|
||
switch sc.Kind {
|
||
case ScopeUnscoped:
|
||
return "TRUE", args
|
||
case ScopeDenyAll:
|
||
return "FALSE", args
|
||
}
|
||
args = append(args, sc.Values)
|
||
ph := "$" + strconv.Itoa(len(args))
|
||
return `NOT EXISTS (SELECT 1 FROM object_markings om
|
||
WHERE om.object_type = ` + alias + `.` + typeCol + `
|
||
AND om.object_pk = ` + alias + `.` + pkCol + `
|
||
AND NOT (om.marking = ANY(` + ph + `::text[])))`, args
|
||
}
|
||
|
||
// ---------- 分级维度(object_types.classification_* / objects.classification) ----------
|
||
|
||
// levelScope 计算某对象类型在分级维度上对主体的可见范围(可见级别集合)。
|
||
//
|
||
// - 类型未启用分级 → Unscoped(该维度不适用,不过滤);
|
||
// - manager → Unscoped;
|
||
// - 主体与该类型的级别完全无交集 → DenyAll(fail-closed:一个都看不到);
|
||
// - 已能看到最高级 → Unscoped(该类型整体放行);
|
||
// - 否则 → Allow(可见级别 = levels[:max+1])。
|
||
func levelScope(authz *Authz, cfg classConfig) Scope {
|
||
if !cfg.enabled() || len(cfg.Levels) == 0 {
|
||
return unscopedScope()
|
||
}
|
||
if authz == nil || authz.Principal == "manager" {
|
||
return unscopedScope()
|
||
}
|
||
max := principalMaxIndex(authz, cfg.Levels)
|
||
switch {
|
||
case max < 0:
|
||
return denyAllScope()
|
||
case max >= len(cfg.Levels)-1:
|
||
return unscopedScope()
|
||
default:
|
||
return allowScope(cfg.Levels[:max+1])
|
||
}
|
||
}
|
||
|
||
// effectiveLevel 计算实例的「生效分级」:自身分级为空时继承类型默认级。
|
||
//
|
||
// 这条继承是分级语义的关键一环:分级值缺失 ≠ 「无限制」,
|
||
// 而是「按类型默认级处理」。没有它,一次「先灌数据、后配分级引擎」的部署
|
||
// 会让全部存量数据对所有主体无条件可见。
|
||
func effectiveLevel(instLevel string, cfg classConfig) string {
|
||
if instLevel != "" {
|
||
return instLevel
|
||
}
|
||
return cfg.Default
|
||
}
|
||
|
||
// classCondSQL 生成分级维度的 SQL 条件。
|
||
//
|
||
// 语义:
|
||
// - 未启用分级 / manager / 该类型整体放行 → TRUE
|
||
// - 生效级别 = COALESCE(实例分级, 类型默认级)
|
||
// - 生效级别落在该类型的屏蔽表里 → 不可见
|
||
//
|
||
// 注意屏蔽表按类型用 CASE 分派,因此不同类型的可见级别互不影响;
|
||
// 生效级别取 COALESCE 后,实例分级为空时按类型默认级判,与 classAllowed 逐对象判定同义。
|
||
func classCondSQL(alias string, cfgs map[string]classConfig, authz *Authz, args []interface{}) (string, []interface{}) {
|
||
if authz == nil || authz.Principal == "manager" {
|
||
return "TRUE", args
|
||
}
|
||
types := make([]string, 0, len(cfgs))
|
||
for t := range cfgs {
|
||
types = append(types, t)
|
||
}
|
||
sort.Strings(types)
|
||
|
||
type item struct {
|
||
typ string
|
||
def string
|
||
denied []string
|
||
}
|
||
var items []item
|
||
for _, t := range types {
|
||
cfg := cfgs[t]
|
||
sc := levelScope(authz, cfg)
|
||
if sc.IsUnscoped() {
|
||
continue // 该类型对本主体不设限
|
||
}
|
||
items = append(items, item{typ: t, def: cfg.Default, denied: deniedLevels(sc, cfg.Levels)})
|
||
}
|
||
if len(items) == 0 {
|
||
return "TRUE", args
|
||
}
|
||
|
||
// 参数顺序必须与占位符出现顺序一致:先默认级 CASE,再屏蔽表 CASE。
|
||
defaultSQL := ""
|
||
for _, it := range items {
|
||
args = append(args, it.typ, it.def)
|
||
if defaultSQL != "" {
|
||
defaultSQL += " "
|
||
}
|
||
defaultSQL += fmt.Sprintf("WHEN $%d THEN $%d", len(args)-1, len(args))
|
||
}
|
||
defaultCase := "CASE " + alias + ".type_api_name " + defaultSQL + " ELSE '' END"
|
||
|
||
denySQL := ""
|
||
for _, it := range items {
|
||
args = append(args, it.typ, it.denied)
|
||
if denySQL != "" {
|
||
denySQL += " "
|
||
}
|
||
denySQL += fmt.Sprintf("WHEN $%d THEN $%d::text[]", len(args)-1, len(args))
|
||
}
|
||
denyCase := "CASE " + alias + ".type_api_name " + denySQL + " ELSE '{}'::text[] END"
|
||
|
||
// 注意:objects.classification 存的是空串而不是 NULL(列默认 ''),
|
||
// 所以必须用 NULLIF 把空串也视作「未分级」,否则 COALESCE 不会回落到类型默认级。
|
||
eff := "COALESCE(NULLIF(" + alias + ".classification, ''), " + defaultCase + ")"
|
||
return "NOT ( " + eff + " = ANY(" + denyCase + ") )", args
|
||
}
|