Table of Contents

hub 数据权限使用指南(key 前缀 ACL+租户/成员准入)

hub 治理轴第五支柱(对标 Redis ACL/Kafka authorizer):HubAccessPolicy 是 INodeAuthorizer 在产品层的策略模型落地——底层钩子只做允许/拒绝判定面(Core.Net H4), 规则表/主体/动词/缺省档全部归本策略对象。直连形态 = ◇(宿主进程边界承担—— product-mode-model-design §5),本能力按 hub 形态供给。 交叉阅读:组装总概、TierHub、 hub 原生能力总览、 直连 raft 挂载。

定位(是什么 / 不是什么)

  • 是:hub raft 承载位的数据权限面——成员/租户准入(链路级)+协议域准入(域级)+ key 前缀 ACL(数据面,读/写动词)三层判定,一棵规则表同源承载;拒绝全量审计。
  • 不是:认证(身份由传输握手/安全档确立——TLS/KeyPair 见 Core.Net 安全文档); 账号体系(主体 = 节点身份 NodeId 与其租户映射,无口令/凭证管理);行级/字段级授权; hub·单机形态的权限(纯 standalone hub 无传输身份面——同直连◇,宿主进程边界承担)。

快速开始

// ── ① 策略:规则表声明(Builder → Build 产出不可变策略)──
var audit = new MyAuditSink();                       // 实现 KernLab.Tier.Core.Net.Security.IAuditSink
var policy = new HubAccessPolicy.Builder()
    .WithAudit(audit)                                 // 产品面拒绝审计落点
    .WithTenant(memberB, "tenant-b")                  // 租户映射(节点 → 租户名)
    .DenyKey(HubSubject.OfTenant("tenant-b"), "tenant-a:", HubVerb.Read | HubVerb.Write)
    .DenyKey(HubSubject.All, "sealed:", HubVerb.Write)
    .AddLinkRule(HubSubject.OfNode(rogueNode), HubEffect.Deny)   // 成员准入(链路级)
    .AddDomainRule(HubSubject.OfNode(witness), 0x62, HubEffect.Deny) // 域级准入(0x62 事务域)
    .Build();

// ── ② 注入宿主:一处注入,三层判定面全链生效 ──
var host = TierRaftHost.Create(self, new TierRaftHostOptions
{
    ListenEndPoint = endpoint,
    GroupFileSystemFactory = gid => TierFs.New($"local:///{gid.Value:X16}"),
    AccessPolicy = policy,      // 自建传输形态:注入 ClusterTransport(链路/域级消费口)
    Audit = audit,              // 传输面事件审计(authz_link_denied / authz_request_denied)
});
await host.StartAsync();

// ── ③ hub 装配成员:副本经宿主承袭策略(key 前缀 ACL 判定点随之在位)──
var hub = await new TierHubBuilder(TierFs.New("memory:")).StartAsync();
var kv = await hub.AddRaftKvAsync<long>(host, "orders", groupId, config);

await kv.PutAsync(42, "v"u8.ToArray());                    // 缺省档 Allow——正常
await kv.PutAsync(43, "v"u8.ToArray());                    // 命中拒绝规则时抛
// HubAccessDeniedException : UnauthorizedAccessException(subject/verb/命中规则随异常携带)

三层判定面

层 消费口 主体 拒绝语义 审计事件
成员/租户准入(链路级) INodeAuthorizer.AuthorizeLink 对端节点 传输断连(握手完成、身份已知后) authz_link_denied(传输落)
域级准入 INodeAuthorizer.AuthorizeRequest 来源节点 × 协议域 请求无应答丢弃(对端超时自愈) authz_request_denied(传输落)
key 前缀 ACL(数据面) HubAccessPolicy.AuthorizeKey 本端节点(门面)/转发对端(入口) 门面抛 HubAccessDeniedException;入口确定性拒绝应答 authz_key_denied(策略落)

传输面两个消费口是 Core.Net 既有钩子(null = 全放行既有语义);策略对象即 INodeAuthorizer 实现——注入 TierRaftHostOptions.AccessPolicy 后传输自动消费。

判定点落位(hub 形态的数据通路)

本端消费方 ──①门面判定(subject=本端节点)──▶ 提案/转发管道
   follower ──转发──▶ leader 入站 ──②入口判定(subject=转发对端)──▶ 提案管道 ──▶ raft 复制(③不判定)
  • ① 门面判定点(副本公开 API 头部):写面 Put/Delete/IncrBy/Persist 按写动词、 读面 TryGet/TryGetTimeToLive/ScanByPrefix/Watch 按读动词;主体 = 本端节点自身 (本进程消费方共享本节点身份——租户即节点分组)。拒绝 fail-fast,命令不进提案管道。
  • ② 入口判定点(leader 收转发写命令):按转发对端主体判定——对端策略失配/ 被攻陷节点绕过其本端守卫的写命令在 leader 入口被拒,确定性拒绝应答回传 (纵深防御线;正常部署两端策略同构,本端守卫先行拦截)。
  • ③ 共识复制面不判定:raft 日志复制/快照/选举是全组一致性的机制面(核心域 0x01-0x04), 任何 key 级裁决都会破坏"全组同日志同状态"——策略只辖命令面,不辖共识面。

规则模型

AddKeyRule(subject, keyPrefix, verbs, effect)   // 数据面:主体 × 键前缀 × 动词 → 效果
AddLinkRule(subject, effect)                    // 链路面:主体 → 效果(成员/租户准入)
AddDomainRule(subject, protocolId, effect)      // 域级面:主体 × 协议域 → 效果
  • 主体选择器(特异性递增):HubSubject.All(全体)< HubSubject.OfTenant(name) (租户——经 WithTenant(node, name) 显式映射或 WithTenantResolver(func) 外部身份源解析) < HubSubject.OfNode(id)(节点)。
  • 键前缀:字节序 StartsWith 语义(非 glob);ReadOnlySpan<byte>/byte[]/UTF-8 文本 三种供给形态;空前缀 = 全键空间通配。定长键(TierKv long 等)按小端线字节匹配—— 例如前缀 [0x00] 命中值域 [2^56, 2^63) 的键(键 5 的线字节是 05 00…,首字节为值本体)。
  • 动词:HubVerb.Read(TryGet/TTL/Scan/Watch)/ HubVerb.Write(Put/Delete/IncrBy/Persist), 位标志可组合;规则动词未覆盖的调用不由该规则裁决。
  • 效果:Allow / Deny 显式二档。

判定顺序(三层同序,确定性可复算)

  1. 主体特异性优先:节点 > 租户 > 全体——关于「你」的规则恒压过关于「大家」的规则;
  2. 前缀最长优先(仅 key 面);
  3. 同序相撞拒绝优先(同特异性同前缀长的 Allow/Deny 相撞 = Deny——fail-closed);
  4. 无匹配归缺省档:WithDefaultKeyAccess(key 面,缺省 Allow)/ WithDefaultLinkAccess (链路面,缺省 Allow = 既有集群语义保持;封闭集群显式收为 Deny+白名单)。 二档均为装配期显式配置——判定无静默分支。

域级准入叠加

链路未准入的节点全域连带拒绝;已准入节点按域级规则裁决(如 witness 拒入 0x62 事务域)。 协议域号分配表见 Products.Net/COORDINATION.md(0x60-0x69 产品复制档——0x69=TierBlob、0x62 事务参与组;0x70 管理面)。

审计事件

事件名 落点 actor detail
authz_link_denied 传输(TierRaftHostOptions.Audit) 对端节点 授权钩子拒绝链路
authz_request_denied 传输(同上) 来源节点 domain=0x…
authz_key_denied 策略(Builder.WithAudit) 主体节点(租户标注) verb= rule= reason= hex=(键十六进制截断 16B)

审计实现归使用方(结构化落盘/导出)——IAuditSink.OnAudit(event, actor, detail) 单行契约。

成本形态(热路径)

  • 判定 = 预排序规则表首条命中即终局的线性扫描:主体过滤 → 动词位测试 → 前缀 StartsWith;判定路径零分配零锁(策略 Build 后不可变;租户解析并发字典缓存)。 成本量级 = O(命中前规则数),规则表常规规模(几十条)下单次判定为亚微秒级标量比较, 相对提案/共识往返可忽略。
  • 门面判定在提案之前(拒绝 = 零共识开销);入口判定在 leader 侧多一次命令解码 (取键判定用)——仅转发写入站的纵深路径,本端守卫在位的正常部署极少触达。
  • 策略缺位(AccessPolicy = null)= 判定点一次空引用检查直通,零开销既有语义。

边界与已知边界

  • Scan/Watch 前缀参数按整区域判定(区域全含校验,W-scan 落地):扫描/订阅前缀按 区域 [prefix‖00…, prefix‖FF…] 裁决——区域内任一键被 Deny 规则覆盖即整体拒绝 (HubAccessPolicy.CheckRange/AuthorizeRange,拒绝审计 authz_range_denied; 漏判方向 fail-closed)。保守口径:区域内存在排序上永不裁决的 Deny 规则(更长 Allow 前缀遮蔽)也整体拒绝——规则阴影分析归后续波次。定长键范围扫描 [start, end) 按 字节序区间整体判定(CheckRange 区间形态)。
  • 事务域(0x62)不判 key:事务 Stage 批内命令的键级裁决归事务波次;域级准入仍可 整域拒入。
  • hub·单机无权限:纯 standalone hub 无传输身份面——宿主进程边界承担(与直连同位)。
  • 辖权回收不受 ACL:到期回收是 hub 治理动作(全组一致的机制面),非主体访问。
  • 九产品收口范围:Kv/VarKv 两键模式为 W-perm 判例件(本波交付);其余复制档 (Queue/Hash/Set/ZSet/Series/Log/Blob)的门面/入口判定点随同构波次铺开。

反模式(禁止重蹈)

❌ 把 key 前缀 ACL 写在共识面

  • 症状:在状态机 apply 或 raft 复制路径里做授权判定。
  • 为什么错:全组必须应用同一日志——判定分歧 = 分脑;拒绝已复制命令 = 状态不可逆分叉。
  • 正解:判定点只在门面(提案前)与转发入口(提案前);共识面永不裁决。

❌ 用 key ACL 替代认证

  • 症状:明文传输上配 Deny 规则,期待"拒绝"兜住伪造身份。
  • 为什么错:主体 = 节点身份;身份可伪造时规则表只是给攻击者的说明书。
  • 正解:先落传输安全档(TLS/KeyPair 握手——身份真实性),再叠权限面。

❌ 缺省档 Deny 而不给白名单

  • 症状:WithDefaultKeyAccess(Deny) 后所有成员写不进任何键。
  • 为什么错:缺省档 Deny = 无匹配即拒——包括发起写的成员自己。
  • 正解:Deny 缺省档必须配套 Allow 规则(按节点/租户/前缀授予);封闭集群同理 (WithDefaultLinkAccess(Deny) + 成员白名单)。

❌ 规则表运行期可变共享

  • 症状:持有 Builder 在请求路径上边收请求边加规则。
  • 为什么错:策略 Build 后不可变是判定面无锁的前提;可变规则表 = 判定不确定。
  • 正解:规则变更 = 重新 Build + 重启/滚动生效(规则表随装配期定型——与 hub 治理面"域归属装配期收口"同纪律);动态权限面归未来独立设计。

❌ 在直连形态期待权限面

  • 症状:TierKvReplicaBuilder 直连装配后要求 key ACL 生效。
  • 为什么错:直连 = ◇(宿主进程边界承担——§5);策略随宿主选项供给,直连宿主 未配策略即无判定,且直连无准入/租户治理语义。
  • 正解:要权限 = 选 hub 形态(3C 选型判据:数据权限/租户管控 → hub)。