Files
adminandClaude Code d14440a3ed feat(server): v1.8.0 本体导入 + 分区 + 行级归属 + 认证位 + 结构 diff + 分页 + 进度回报
一次收口 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]>
2026-11-06 13:51:48 +08:00

307 lines
10 KiB
Go
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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
}