#NSD · 身份、策略与控制面实现规格

NSD 是 NSIO Next 的租户权威控制面。它保存 Organization/Network 资源、验证身份与准入、编译最小授权投影、签名分发、记录审计并执行 Entitlement。NSD 永不进入业务数据路径，也不持有节点私钥。

全部能力的权威对象、审批事务和跨组件责任见产品能力目录与实现闭环；对象状态与 API 见控制资源生命周期，credential、建流与 generation 见数据面协议。本文件不得通过控制面实现便利改变其中的用户或失败语义。

#1. 职责边界

NSD 负责：

• Identity Authority 接入、账号/会话、Organization 与角色；
• Device Enrollment、Network Membership、地址与名称分配；
• User/Group/Device/MachinePrincipal/Node/Service/Route/Gateway/Share 的权威状态；
• AccessGrant、CapabilityPolicy、EdgeAuthPolicy、AdminRoleBinding 的创作、模拟、审批、版本和执行；
• CapabilityActivation 的逐实例批准、配额占用、租约和审计；
• Service、Route、Gateway 声明/审批/健康的控制器；
• 每个目标节点的最小 snapshot/delta 投影和签名；
• 审计、通知、Webhook、Entitlement、Quota 和 Capability Lease；
• 数据导出/删除编排、Legal Hold、备份恢复水位、服务 SLI 与商业签发关联；
• 租户 API、成员 Portal API 和管理控制台后端。

NSD 不负责：

• 承载节点间、服务、入口或出口业务流量；
• 生成或托管 Device/Node/WireGuard 私钥；
• 绕过 Local Manifest 强制节点发布服务；
• 用前端过滤代替仓储层租户和授权过滤；
• 因计费服务、读取或编译故障扩大权限或拒绝服务启动。

#2. 服务模块

模块通过事务事件和明确接口协作，不共享“随便查表”的全局数据库句柄。编译器只读权威快照，写 projection/outbox，不在计算中修改资源。

#3. 部署模型

首版支持：

• Cloud hosted：多租户 PostgreSQL、托管 Identity/SMTP/NSGW；
• Community self-hosted：单部署、多 Organization，SQLite 或 PostgreSQL；
• Enterprise self-hosted：PostgreSQL、企业 OIDC/SCIM、外部密钥/审计集成。

首版不以“多 NSD 同时控制一台设备”作为核心能力。一个 active Profile 对应一个 NSD deployment；用户可以保存多个 Profile，但系统路由/DNS 不做跨权威 union。

SQLite 与 PostgreSQL 必须具有相同事务语义。SQLite 写入会串行排队，不能以随机 busy 错误暴露给用户；批量注册通过 Reservation 降低长事务。

#4. 请求处理管线

所有租户写请求按固定顺序：

1. 认证 Session/Device/Gateway；
2. 解析 deployment、Organization、Network 作用域；
3. 仓储层按作用域加载资源；
4. 通过对应生产 PolicyKernel consumer 执行 RBAC/AccessGrant/Capability/Edge/本地 proof 校验；
5. Entitlement admission；
6. expected revision / impact digest；
7. 单事务提交权威对象、outbox 和 audit；
8. 返回 committed revision 与 operation ID；
9. 异步 compiler/controller 消费 outbox；
10. projection ack 更新 operation 状态。

任何异常在步骤 7 前不得留下正式资源；步骤 7 后重试必须通过 idempotency key 返回同一结果。

#5. Identity 与空间

Identity Authority 对外只暴露标准 OAuth/OIDC 会话。首版登录方式为邮箱密码、Google、GitHub 和企业 OIDC；社会登录不要求先填邮箱。Passkey 主登录后续增加，WebAuthn 首版用于 MFA/step-up。外部身份主键是 (issuer, subject)，验证邮箱全局唯一但不用于静默合并账号。

首次个人登录事务：创建 Account → Personal Organization → default Network → owner membership → 安全默认 Grant template → audit。全部成功才提交。邀请第一位成员、开始试用或升级套餐都在同一 Organization 原地发生，不迁移资源 ID。

logout、登录方式解绑、SCIM deprovision 和 Device revoke 是四种不同事务。会话过期默认不撤销数据面 Membership；企业可显式启用更严格策略。

#6. Enrollment

Enrollment 完整行为以专项文档为准。NSD 实现要点：

• Request 与 Grant 是两台状态机；approved 是持久决议，Grant 在已认证客户端轮询时惰性签发；
• polling、commit 都要求 Device Key 签名并绑定 request/device/target；
• 同一 request 任一时刻最多一个有效 issued Grant，重复轮询返回同一 grant identity；
• commit 重新校验 Grant state、approval revision、Membership 目标、Entitlement 和 quota reservation；
• rejected 只留下短期 Request/安全证据，不创建 Device/Membership/席位；
• Network target 在 proof 完成后选择；Device Code 选择发生在已认证确认页；
• Device Code 可被 Network 策略禁用，生产 Network 的 user-owned server 产生告警；
• Device Key 按 Organization 隔离，同一物理设备在两个组织中是两个 Device。

#7. Device、Membership 与地址

Device 表示组织内的设备身份与生命周期所有权；Node Membership 表示该 Device 加入一个 Network 后的数据面身份。一个 Device 可有多个 Network Membership，但每个 Membership 有独立 Node/WG Key、Node IP、Grant 和 lease。

地址分配事务需要：池级锁/原子 claim、唯一约束、释放隔离期和审计。Node FQDN 由 node-name.network-slug... 生成，重命名更新 DNS alias 但不改变 Node IP/ID。Service VIP 从独立池分配，不能与 Node IP 混用。

Device offline 不等于 revoke。Peer lease 过期使其移出活跃 projection；重新认证可恢复。Organization-owned Device 在员工离职时保留，撤该员工 Membership/assignment 后等待重新分配。

#8. 分层策略模型与创作

AccessGrant 编辑器收集五元组：subject、source/device condition、resource、action、constraint。CapabilityPolicy、EdgeAuthPolicy 和 AdminRoleBinding 使用各自的动作与资源 schema，但共享同一个 PolicyKernel 的 selector、condition、规范化、版本、provenance 和错误语义。NSD 保存 author intent 与 normalized form，并生成 immutable version。

发布前必须：

1. schema 和引用校验；
2. selector 展开预览；
3. 检测永远不命中、过宽、循环 share 和冲突；
4. 模拟新增/丢失访问集合；
5. 高风险规则走审批/step-up；
6. 提交 version + audit + compiler job。

默认策略：Personal 初始模板允许本人设备基础互访；企业默认拒绝横向 L3，只开放明确 Service/管理流量。模板是可见、可修改的普通 AccessGrant version，不是隐藏后门。PublicApplication、能力申请和控制台管理权限不得塞入 AccessGrant。

#9. PolicyKernel 与生产执行器

选择器、规范化、命中和撤销语义以Grant 与策略编译实现规格为权威。本节只定义 NSD 模块边界。

AccessCompiler 输入为同一 revision 视图中的 principal、Group、Membership、Service/Endpoint、Route、Gateway、Share、health、posture 和 Entitlement。输出按目标 Membership/Connector/NSGW 最小化：

• netmap：需要建立路径的 peer 公钥和 endpoint；
• grants：本节点需执行的源/目标动作；
• services：当前主体可见的 Service 与 endpoint token；
• dns：Node/Service/Route 最小记录；
• routes：被批准且被授权的 CIDR/域名；
• gateway：被授权候选、selection 和 runtime config。

各执行器在固定 kernel/evaluator version 下纯函数化，同一输入 revision 产生同一 canonical output。读失败、引用缺失或未知安全语义时不发布新 revision，保留最后有效 projection 并产生对应 *_evaluation_failed。不能用 unwrap_or_default 把失败编译成空授权。

共享 selector/condition 只在 PolicyKernel 实现一次；AccessCompiler、CapabilityCompiler、EdgePolicyEvaluator 和 AdminAuthorizer 是独立生产消费者，不互相冒充。模拟和 Effective Access 必须 dry-run/读取这些生产实现，不能在控制台复制“看起来一样”的 allow 算法。

#10. Service Controller

声明来源是 ns Local Manifest 或受管 publication request。NSD 先用 CapabilityPolicy 判断申请资格，再以逐实例 CapabilityActivation 完成批准、配额占用、审计和租约；自动批准也走同一事务。随后校验协议、backend 元数据、名称和本地同意，创建 Service/Endpoint 并分配 VIP/FQDN。

状态轴：declaration、approval、publisher health、projection、consumer authorization。online 只由健康 Endpoint 决定；无 ACL 不等于 offline，无 endpoint 不等于 unauthorized。

每个 Service 至少生成两类互补投影：consumer projection 含目录/VIP、可选 Endpoint、action 和 ServiceFlowCredential 获取/携带材料；publisher projection 含本 Service、Endpoint、本地 backend 约束、允许 consumer 范围、验签键、generation/digest/revision/expiry。publisher 不获得完整成员目录。两侧共享同一 grant_rule_id、generation 和 digest，任一侧缺失时 fail-closed；NSD 不进入 ServiceFlow 建流路径。

Service 修改使用 revision，协议/域名/网络等高影响字段先预览。删除 Service 会撤目录和租约，但不远程删除节点本地 manifest。Endpoint 离线只移出健康集合，不删除 Service。

成员 Portal API 必须复用 compiler 的 services_visible_to_principal 结果，站点/节点由可见 Service 推导，只返回成员自己的 Device，不返回完整 policy。

#11. Route 与 Application Controller

Route advertisement 进入 pending，管理员看到 publisher、CIDR/domain、冲突和预计受众。批准只创建可授权资源，用户仍需 Route Grant。

CIDR 冲突按 Network、route kind、prefix、priority 和 publisher health 计算；不静默随机选择。Domain Route 对 DNS answer 设置数量/TTL 上限并记录 origin resolver；禁止解析回 Service VIP。

Route lease 短期续租。publisher unhealthy、approval revoke、Grant revoke 或 lease expire 都重编译。NSD 不宣称终端已安装，只在 ack 后展示 applied 数量。

每条批准 Route 生成客户端投影和 Connector 投影。Connector 投影包含允许来源、精确目的地、协议/端口、NAT、generation/digest/revision/expiry；客户端获得绑定同一 digest 的签名 RouteAccessCredential。Connector 本地验签和校验实际目的地，建流时不得回查 NSD。

变更通过 current/next/previous generation 编排。Compiler 区分 additive、restrictive、metadata-only 和 mixed；Network 默认 security_first，可选 bounded_drain。NSD 负责 staging、ACK、activation epoch 和审计，不能把新旧目的地集合合并，也不能为消除切换窗口进入流路径。

#12. Gateway Controller

Gateway 注册报告独立 capability：relay、managed_relay、egress、exit、ingress。每项有配置 schema、health、capacity 和 Entitlement lease；拥有 relay 不自动拥有其他 capability。

#12.1 Candidate 与 Selection

Gateway Exit candidate 按当前 principal、gateway、profile、scope 和可用性投影。集合状态明确区分 available、no_authorized_candidates、temporarily_unavailable 和 read_failed。gateway_name 是可选展示字段，缺失不影响旧一版 Next consumer；实际选择仍绑定 gateway ID + scope。

提交 selection 时授权失败硬拒不落库；已授权但暂时离线可以保存 suspended。已保存 selection 不自动切换到另一个 gateway，恢复授权/健康后可重新生效。

#12.2 Egress/Ingress

Egress 被建模为 Service backend，AccessGrant 决定谁可用。Ingress 由 PublicApplication + EdgeAuthPolicy + IngressBindingLease 绑定已存在 Service，不能填任意内网地址。证书、WAF、域名、区域和配额是 PublicApplication 自己的对象，不污染 Service 生命周期。

EdgeAuthPolicy 支持 OIDC、API Key、Service Credential、Signed URL、mTLS 和显式 Anonymous。访客形成 EdgeIdentity/ExternalPrincipal，但不创建 Network Membership；NSGW 使用最小 Gateway 身份与 Binding Lease 访问后端。内部 AccessGrant 和公网 EdgeAuthPolicy 分别求值、分别撤销，控制台必须交叉展示。

NSD 保存/规范化 policy、运行 dry-run 与签名投影，但不参与每个访客请求。NSGW 使用同版本 PolicyKernel/Edge evaluator 本地验证 method credential 和 request context；NSD 读取失败只阻止发布新 revision，不能让 NSGW 回查后临时放行。

Egress 作为 Service publisher 获得同一 publisher projection、ServiceFlowCredential 验签材料和本地 EgressOriginLease；该 lease 绑定实际 origin allowlist/DNS/TLS/generation，不发送给公网 origin。Ingress 获得 IngressBindingLease、IngressBackendCredential 和最小 publisher projection，不获得 Network peer map。NSD 为 NSGW 编译按 application、policy revision、binding lease、edge identity、credential 和 IdP session 可索引的撤销材料。安全撤销要求 NSGW 在 SLA 内终止长连接；策略读取失败返回 503，不伪装成 403。

#12.3 Relay 与 Exit credential

Relay 调度只向 NSGW 暴露 RelayRouteLease 中的 opaque relay_route_id/relay_session_id、direction、流量上限、revision 和 expiry；稳定 Membership/Node/WG 身份只留在 NSD 与端点投影中。Exit 为终端和 NSGW 签发同一 selection/profile/scope/generation 的 ExitTunnelLease，两侧独立校验。credential 签发读取已提交且已编译的投影快照，不从未经批准对象临时拼装，也不把 NSD 放进每流路径。

#13. Entitlement 与 Quota

验签通过的 bundle 事务化激活为 head 与 quota projection。防回滚 high-water mark、当前 revision 和 quota limit 使用同一权威字段。新 bundle 缺失旧 resource type 时保留 used/reserved，更新 revision 并标记 feature_not_entitled，不伪装成 limit=0。

注册热路径只做一次原子条件更新，零行后分类回读为 missing required quota、entitlement quota projection revision stale 或 limit reached。该事务 revision 不一致最多重试一次。批量部署先建 Reservation，再逐台消费，未消费差额到期归还。

计费/签发服务故障不得阻止 NSD 启动。最后有效 bundle 与签名持久化，grace 过期后的行为按 feature/managed capability 分别处理，不提供远程 kill switch。

#14. Projection Delivery

每个目标 Membership 的 projections 用独立 stream/type/revision。权威对象提交写 transactional outbox；delivery worker canonical serialize、签名、存 snapshot/delta、发送并追踪 ack。

断线重连通过客户端水位选择 delta 或 snapshot。服务端保留窗口不足时发送新 snapshot。ack 不能反向修改权威资源，只更新交付状态和管理端可观测性。

背压策略：同类型未发送 delta 可合并为最新 snapshot；Enrollment/撤销/安全事件不能被普通状态更新覆盖。单个慢节点不能阻塞 Organization 编译或其他节点分发。

#15. API 表面

列表 API 使用 cursor、稳定排序和作用域过滤。批量导出异步生成，下载 URL 短期签名。错误统一使用共享信封。

#16. 审计与通知

权威事务与审计同事务写入，外部通知通过 outbox。每个事件记录 actor、proof/assurance、action、resource、before/after revision、result、request ID 和 origin，不记录 secret。

通知是可重试副作用，不能决定权威提交是否成功。站内、邮件和 Webhook 使用同一 event ID 去重。高风险安全事件不可被用户普通通知偏好关闭。

#17. 可用性与恢复

• 数据库不可用：写请求明确失败，读取可展示带 revision 的缓存但不伪装最新；
• compiler 失败：不发布部分 projection，保留最后有效并告警；
• delivery 失败：权威已提交，operation 显示 pending delivery；
• Identity Provider 不可用：已有 Device Membership 数据面不受影响；
• Entitlement issuer 不可用：使用最后有效/grace，不拒绝 NSD 启动；
• 审计导出失败：不丢原始审计，任务可重试；
• 单租户毒性数据：隔离 job，不阻塞其他租户。

Hosted/Self-hosted 备份和 restore epoch 以备份与灾难恢复为权威。恢复后必须重新应用撤销、deletion tombstone、最高 Entitlement revision 和新 projection epoch。状态页/SLA 所需 SLI 只输出服务事实，不泄露租户目录；事故与支持流程见服务运营规格。

#18. 安全与租户隔离

所有 repository 方法要求显式 TenantContext。SQL 唯一键和外键包含 tenant/network scope。跨组织 Share 使用 opaque binding 和最小复制，不允许 join 两边完整目录。

管理员 API、租户 API、控制流和 Gateway API 使用不同 audience/credential。支持人员访问必须 just-in-time、带理由、审批和全审计，默认不可见业务资源。

#19. 测试与完成条件

• 仓储层跨租户存在性和 ID 重放；
• 事务幂等、revision、impact digest、outbox 与崩溃点；
• Enrollment/Quota/Reservation 并发；
• 四个 PolicyKernel consumer 的精确集合、模拟复用生产实现和授权放宽反向注入；
• Route 客户端/Connector 双投影、generation rollout、目的地白名单和 NSD 不在建流路径；
• Service consumer/publisher 双投影、ServiceFlowCredential claims/digest/generation 与 NSD 不在建流路径；
• EgressOriginLease 的 origin allowlist/DNS/TLS/generation 绑定、过期与跨 gateway/Service 重放反测；
• RelayRouteLease 不向 NSGW 暴露稳定身份，opaque attach/session 轮换、过期和跨 relay 重放反测；
• ExitTunnelLease 两侧 scope 一致、selection/profile 撤销和旧 generation 不可扩大；
• CapabilityPolicy/Activation auto approval 仍占配额、计量和审计；
• Edge 按应用/策略/Binding/身份/凭据撤销在途会话；
• policy engine shadow evaluation 同地域、差异确认和 provenance version；
• Service/Route/Gateway 状态不互相折叠；
• snapshot/delta、背压、断档、签名和回滚；
• Identity logout/unlink/SCIM/revoke 四路径；
• Entitlement downgrade、grace、旧 quota tombstone 和对账修复；
• SQLite/PostgreSQL 语义一致；
• Portal 成员边界与 Admin 403；
• 故障不变空列表、不扩大授权、不阻止启动。
• export/delete/Legal Hold、restore epoch、防授权复活和 service SLI。

NSD 功能完成必须同时有权威事务、最小 projection、Client 可解释状态、撤销 SLA 和审计证据。