#NSIO Next · 产品能力目录与跨组件闭环

本文是 NSIO Next 的功能分解索引和实现预演基线。它回答“产品最终有哪些能力、每项能力由谁负责、用户怎样操作、失败与撤销怎样闭环”，并把一个营销名称拆成可独立失败、可独立撤销和可独立验收的子能力。

本文不替代专项协议：对象与信任边界以架构为权威，交互旅程以产品闭环为权威，控制对象状态/API 以控制资源生命周期为权威，建流/凭据/传输以数据面协议为权威，逐功能证据状态以功能闭环总账为权威。本文发现冲突时必须先修上层权威，不能用矩阵掩盖矛盾。

#0. 使用方法

每个功能在进入实现任务前必须回答以下问题：

任何一项只能“创建”但不能变更、暂停、撤销、删除和恢复，或只在成功态有 UI，都不算闭环。

#1. 竞品校准与 NSIO 取舍

#1.1 可借鉴的成熟模式

官方参考：

• Tailscale Route injection
• Tailscale Services
• Tailscale device visibility
• Tailscale policy syntax
• ZeroTier Rules Engine
• NetBird Access Control
• NetBird Control Center
• Twingate Resources
• Twingate Security Policies
• Cloudflare Access policies
• Cloudflare One routes

#1.2 明确不照搬

1. 不采用默认全员全设备互通；Personal 默认仅本人设备，企业默认无横向 L3。
2. 不让一个 Network ID 或长期通用 Key 代替用户身份、设备归属和审批。
3. 不把所有 L4 需求降级为 IP:port ACL；Service 始终有独立身份、VIP、目录、Endpoint 和本地发布上限。
4. 不把设备 tag 同时当用户组；人类主体使用 User/Group，服务器与工作负载使用 MachinePrincipal/Tag。
5. 不提供跳过认证同时跳过日志的公网 Bypass；确需公开的路径创建独立 Anonymous PublicApplication。
6. 不让控制台、模拟器或 App 重写一套策略求值；所有解释来自生产 PolicyKernel、Compiler/Evaluator 和 provenance。

#2. 产品对象和状态公理

#2.1 对象分层

Device、Node、Service、Membership、Principal 不能因 UI 简化而合并。显示名、hostname、邮箱和客户端自报 tag 不是授权主键。

#2.2 独立状态轴

产品不得用一个 active 覆盖以下事实：

读取失败不是 denied，离线不是 revoked，配额不足不是 unauthorized，daemon 存活不是 connected。Client 必须保留这些区别。

#2.3 可见性、授权和执行材料

三种“看见”必须分开：

1. 管理可见性：AdminRoleBinding 允许管理员看到组织对象；不产生数据面权限。
2. 成员目录可见性：成员只看到 AccessGrant 已授权资源，或管理员显式标为 requestable 的最小资源占位；requestable 占位不含 VIP、Endpoint、IP、backend 或 peer key。
3. 数据面 peer material：为了双端执行，目标节点可能需要知道一个只允许入站的源公钥；这不代表目标用户能在 Nodes 页面浏览或主动连接该源。

控制台不能把“编译器给 runtime 的最小验签材料”直接当成员目录返回。

#3. 跨组件责任矩阵

图例：A 权威，C 编译/签发，E 最终执行，U 用户交互，O 观测/运营，T 独立验收。

一项能力不能出现两个 A。NSGW 对 session 的最终执行不使其成为租户策略权威；ns 对 Local Manifest 的本地权威不允许它自行创建远端 Service 授权。

#3.1 共享契约模块

跨团队不能把本矩阵中的 flow schema、lease/token 或 E 当作待实现者自行补全的占位符。所有 Relay、ServiceFlow、RouteFlow、Egress、Exit 和 Ingress backend 都必须填满数据面协议的六要素矩阵；所有 Group、Role、AccessRequest、Activation、MachinePrincipal、Posture、Publication、Share/Federation 和 key rotation 都必须使用控制资源生命周期的状态/API。 | fixtures | 正向/反向/演进样本 | Producer 与 Consumer 共用但不自洽造假 |

Shared 不定义数据库模型或 UI 文案，不引入“万能状态”。每个协议面的版本独立，跨面依赖用 feature discovery 表达。

#3.2 NSD 内部模块

这些模块可以部署成一个服务或拆分进程，但权威与事务边界不随部署拓扑变化。任何 controller 都不能直接写另一模块表来绕过其事务。

#3.3 ns 内部模块

#3.4 Client 内部模块

Client 使用一个领域状态层承接结构化结果：auth/enrollment、connection、directory、publisher、exit、admin、billing、diagnostics。页面只能发 command 和渲染 view state；不能在 Widget/Controller 中实现 Group 展开、CIDR contains、supports_scope、effective access 或路由冲突。

每个异步操作有 operation ID、阶段、取消边界和互斥范围。会改变 runtime 的流程禁用冲突按钮，但不冻结无关页面；App 被杀后从 daemon/NSD 权威恢复，不靠内存补写成功状态。

#3.5 NSGW 内部模块

#3.6 QA 与联调环境

QA 维护跨仓库版本矩阵、真实序列化契约、故障注入代理、NAT/UDP/WSS 网络实验室、Windows/macOS/Linux/iOS/Android 真机、外部 VPN 冲突环境、长连接测试应用、计费/身份 provider sandbox 和证据归档。

单仓库 green 不能替代 Slice green。每个版本发布必须记录 Shared/NSD/ns/Client/NSGW commit、协议 capability、测试环境和已知范围。

#4. 身份、账号与会话

#4.1 人类登录

首版托管登录方式：邮箱密码、Google、GitHub、企业 OIDC。App 不放密码表单，只用系统浏览器 Authorization Code + PKCE。Web 控制台和 Member Portal 使用同一 Identity Authority；登录成功不等于 Device 已注册。

#4.2 会话、MFA 和 resource assurance

登录 assurance 与资源授权分开。AccessGrant 可声明 min_assurance、reauth_within 和 posture 条件，但执行方式必须符合数据面：

• 控制台高风险操作：服务端在提交事务前要求绑定具体 action/resource/digest 的 step-up；
• Service/Edge 新会话：签发短期 Flow Credential 前检查 assurance，不足时 Client/浏览器提示重新认证；
• 原始 L3 TCP/UDP/ICMP：不能在第一包弹浏览器。reauth_within 约束 peer lease/新流凭据签发；过期后阻止新流并在 Client 显示需要重新认证；已有流按 Grant 的 revoke/drain 策略处理；
• MachinePrincipal 不满足人类 MFA。自动化使用 workload credential、attestation、来源环境和短 token 条件。

Client 必须把“身份需要重新验证”与“管理员没有授权”分开显示。

#4.3 账号与组织成员生命周期

撤销 SLA 默认不超过 5 分钟，由 peer/flow lease TTL 与 projection delivery 共同保证。

#4.4 MachinePrincipal 与控制 API

控制 API 的非人类调用统一使用 Organization-owned MachinePrincipal：

1. 管理员创建 OAuth Client，选择精确 API scopes、Network/资源范围和有效期；
2. client secret 只显示一次，服务端只存 hash；
3. client credentials 换取不超过 1 小时的 access token；
4. token 绑定 audience、principal、scope、organization、credential ID 和 revision；
5. 轮换允许短重叠，撤销 credential 立即停止签发并在 token TTL 内收敛；
6. 首版不提供无限期、继承创建者全部权限的 Personal Access Token。

边缘 API Key 是 PublicApplication 的访客凭据，不可调用租户控制 API；Enrollment Key 只注册设备，也不可调用控制 API。

#5. Organization、Network、成员、Group 与角色

#5.1 Personal 到企业原地成长

首次用户不需要先创建 Organization。Personal Organization 是真实租户，只在 UI 隐藏术语。邀请成员、升级套餐、配置 SSO 时继续使用同一 Organization/Network/Node IP/Service ID/Grant；只有账单、法律或安全边界确实独立时才新建 Organization。

#5.2 Network

Network 是地址、DNS、Membership、Grant 和路由冲突域。一个 Organization 可有多个 Network；首版一个 runtime Profile 同时只激活一个主 Network，不把多个 Network 自动桥接。切换前显示将撤销和安装的 DNS、route、Exit 与本地系统权限影响。

#5.3 Group 类型

约束：

• User Group 只包含 User/Organization Membership；Machine 使用 Tag/MachinePrincipal selector；
• 首版不支持 Group 嵌套，避免循环、隐式放大和难以解释的 effective access；
• synced Group 不允许控制台手工改成员；管理员可复制为 manual Group，但获得新 ID；
• dynamic Group 不读取 hostname、自由文本 tag 或未经映射的 IdP claim；规则变更必须模拟影响；
• Device posture/ownership/managed state 不用于改变 User Group 成员，而作为 AccessGrant 的 source condition 求值；
• 删除/同步移除成员触发新 directory revision 和受影响 projection，不篡改历史 GrantSet；
• 同名 Group 以 ID 和来源 badge 区分，规则不按名称绑定。

#5.4 AdminRoleBinding

角色是起始模板，持久化使用 resource/action/scope 明确的 AdminRoleBinding。用户不能自行提高角色；高风险权限变更需要 step-up、影响预览和审计。

#5.5 Access Request 与临时授权

JIT 访问是 AccessGrant 的工作流，不新增第五个执行策略平面：

1. 资源默认 authorized_only，未授权成员不可见；管理员可设 requestable 并配置最小展示、eligible selector、最长时长、审批人和是否要求理由/ticket；
2. eligible 用户只看到名称、用途、owner 和可申请时长，不得到地址、VIP、Endpoint 或 peer material；
3. 提交 AccessRequest，服务端重新求值 eligible 条件并进入 pending/approved/rejected/expired；
4. 批准事务创建有 not_after 的独立 GrantSet revision，正常进入 Compiler、projection、audit 和撤销；
5. 到期或提前撤销停止新流并按资源策略处理在途流；
6. Request Policy 只决定能否申请和审批流程，不能直接让数据面放行。

个人产品可隐藏 JIT；企业按 Entitlement 开启审批、ticket 与最长时长治理，但基础 time-bounded Grant 语义保持一致。

#5.6 跨 Organization 分享

外部合作优先分享一个 Service，不把对方加入整个 Network。资源方创建 ShareOffer，接收方接受后创建 ShareBinding；有效权限始终是资源方 Grant、Offer 范围、接收方主体/姿态 Binding 和有效期的交集。

1. 资源方选择一个 Service、目标 Organization、允许动作、到期和是否可续期；
2. 系统生成不可枚举 share link/ID，不泄露资源目录；
3. 接收方管理员核对资源方显示身份和范围，绑定本地 User/Group；
4. 两方 NSD 以 federation key 验证短声明，签发面向接收方 Membership 的短访问租约；
5. 接收方成员只在自己的目录看到被分享 Service，不看到资源方 Node、用户或策略图；
6. 任一方暂停/撤销后停止续租，在 SLA 内收敛；双方用同一 opaque share ID 写最小审计；
7. 删除 Federation Binding 仅在没有派生 Share 时允许；停用、停用并撤销、删除是三个动作。

首版不让 Service Share 隐式创建跨组织 Node 或 Route。跨组织 Node 分享与 Network federation 是后续独立高风险能力，必须重新做 L3 信任面和路由冲突评审。

#5.7 Network 关闭与 Organization 删除

Network 关闭不是数据库级联删除，而是权威 NetworkClosureRequest：

draft → impact_ready → approved → revoking → address_quarantine
      → deleted
      ↘ deletion_failed

1. 只有 Organization Owner 或有明确 network.delete 的管理员可发起，提交前 step-up；
2. NSD 在同一 revision 快照计算 Membership、Device/Node 关系、Service/Endpoint、Route/Connector、Gateway/Exit selection、Grant、DNS、CapabilityActivation、PublicApplication、Share 和配额影响；任一必需数据读取失败不生成“影响为零”摘要；
3. 确认请求绑定 impact digest。进入 revoking 后冻结该 Network 的新 Enrollment、Grant、Activation、Share 和 Lease；
4. 先撤新流签发，再推送最小删除投影；在线执行者按撤销 SLA 收敛，离线执行者不能在旧 lease 过期后继续；
5. ShareOffer/Binding 双方收到同一 opaque share ID 的 resource_closing/resource_revoked 事件，接收方保留 tombstone 和审计，不把读取失败显示成“从未分享”；
6. PublicApplication 先撤 DNS/listener/Binding Lease，Service/Route/Exit 按各自安全撤销规则关闭；系统 route、split DNS 和 capture 必须由终端 journal 证明已清理；
7. Network ID、对象 ID 和 DNS slug 永不复用。Node IP、Service VIP 与地址子段进入 quarantine：默认 30 天，且不得短于最大相关 lease TTL、DNS TTL、回滚窗口和删除 tombstone 传播上限；
8. 达到 address_quarantine 时 active Network quota 可释放；Managed Resource 等配额只在对应 Activation revoked 后释放。隔离地址属于内部安全保留，不继续向客户计活动资源；
9. Audit、Security Event、Billing 和法定保留记录继续使用原 Organization/Network ID 与 closure request ID，不能挪到无作用域的“已删除”桶；
10. 任一步失败进入 deletion_failed，显示已完成与未完成对象、可重试动作和 request ID，不回滚已经生效的安全撤销。

Organization 删除是对全部 Network closure、Organization-level identity/Share/Edge/Billing/data workflow 的编排，不是另一套直接级联。所有 Network 至少到 address_quarantine、外部 Share 已失效、托管 NSGW tenant config 已清理后，才删除 active Organization 数据；发票、Legal Hold、备份过期和法定审计按信任与数据权利独立收口。

#6. Device、Node、所有权与姿态

#6.1 Device 与 Node 的实际关系

一台物理安装在每个 Organization 中有独立 Device Key 和 Device 对象；加入一个 Network 才创建 NodeMembership、Node IP 和 Node Key。同一 Device 可加入同组织多个 Network，但每个 Membership 有独立地址、key、Grant 和状态。

管理员识别设备依赖已验证 owner、注册方式、Device Key 指纹、平台 attestation、序列号/MDM ID（若有）和首次/最近活动；hostname 只作为显示建议，不能证明“是谁的设备”。

#6.2 注册与审批

Enrollment 完成只创建身份与 Membership，不自动创建 Node/Service/Route AccessGrant。Personal 默认模板的 self 是显式普通 Grant revision。

#6.3 生命周期

Device suspend、posture fail、Node offline、key expired 是不同事实，不能都显示“设备离线”。

#6.4 Posture

Posture 输入只接受平台 attestation、ns 可验证平台事实、MDM/EDR Provider 和管理员映射后的 claim。每条信号包含 source、observed_at、expires_at、confidence/verification 与 stable reason。

• 自报 hostname、进程名或客户端 capability 不能直接变成信任结论；
• 规则要求的信号 unknown、expired、provider read_failed 时不满足该条件；
• 未过期的最后验证信号可在明确 TTL 内使用，UI 显示 stale；
• Client 展示逐项修复动作，例如升级客户端、启用磁盘加密、重新同步 MDM；
• 管理员看结论和必要证据，不默认获得终端完整进程/软件清单；
• Posture 变化触发 effective input revision，不重写原 GrantSet。

高安全 Network 可启用客户控制的 Node Key 签名/透明日志能力，使控制面不能单方面插入新 peer；该能力是 Device admission 的附加验证，不替代 Enrollment 和 AccessGrant。

#7. L3 节点组网

#7.1 用户交互

连接后用户通过短名、Node FQDN 或 Node IP 访问节点。Nodes 页面只列：本人节点、可主动访问的节点、明确分享给本人的节点；仅因目标端入站校验而下发的源 peer material 不出现在可访问列表。

Node 详情显示被允许的协议/端口摘要，并只提供真实可用动作：

身份感知 SSH、临时 UNIX 用户、会话录制和数据库凭据代理属于后续 privileged access 产品，不能把“打开本机 ssh 命令”营销为已实现这些能力。

#7.2 数据路径与授权

Application packet
  → OS route to TUN/WG interface
  → ns source egress rule
  → encrypted direct / base relay / WSS path
  → target ns ingress rule + signed peer material
  → target OS/service

AccessGrant connect 可限制 ICMP、TCP/UDP 和端口。源端用于快速拒绝，目标端最终执行；Relay 只校验路径 token 和转发密文。未授权目标不进入源端可用 peer map，伪造目的 IP/公钥仍在目标端失败。

#7.3 可用性与失败

路径状态：direct_lan、direct_wan、relay、wss_relay、no_path。路径变化不改变授权。Client 用“直连/中继/受限网络”表达，不要求普通用户理解 STUN、candidate 或 WireGuard endpoint。

• 控制面断线：未过期 peer lease 和已建连接继续；不能新获授权；
• Relay 容量不足：尝试其他候选，显示容量故障，不显示未授权；
• Network 切换：路径重选，不改 Node 身份；
• 外部 VPN route 冲突：不抢占，显示精确 CIDR/接口和可选恢复；
• Grant revoke：新流立即拒绝，旧流按 revoke/drain policy，最长受 lease SLA 约束；
• target offline：显示 unavailable，不删除 Node/Grant。

#7.4 双向访问不是默认对称授权

A → B tcp/22 不自动产生 B → A tcp/22。B runtime 会得到验证 A 入站所需的最小材料，但 B 用户不能因此主动访问 A。若产品模板需要互访，应显式创建双向 Grant 或两个规范化方向。

#8. 地址、DNS 与名称

#8.1 名称空间

短名仅在当前 Network 内解析。同名 Node 与 Service 时短名 withheld，Client 要求使用 FQDN并显示冲突对象；不能随机命中。

#8.2 Split DNS

ns 只为当前 Profile 接管明确 zone/record，不将所有 DNS 强制送入 NSD。NSD 编译当前主体可见的 Node/Service 记录；本地 resolver 按最具体 suffix 匹配，其他查询走系统原 resolver。

DNS projection 包含 source、revision、TTL、record kind 和 expiry。读取失败保留未过期缓存并标 freshness=stale_valid；过期后不返回假记录。切换 Profile 前先撤旧 zone，再安装新 zone，不能让两个 Network 同名记录做 union。

#8.3 自定义域名和内部 resolver

• Service 自定义域名：split DNS 直接返回 Service VIP，保持原 SNI/Host；
• DomainRoute：Connector 用 origin resolver 解析并发布有 TTL 上限的 IP 集，属于 best-effort L3；
• 私有 DNS zone：管理员配置明确 suffix → resolver/Connector，且 resolver IP 本身必须有 Route；
• backend/origin 解析：必须绕过 Service split DNS 使用 origin resolver，防止解析回 Service VIP 形成环；
• 共享 CDN：DomainRoute 页面必须提示解析 IP 可能承载其他域名；要求严格 Host/path 时使用 DomainService/Egress Proxy。

#8.4 DNS 冲突交互

创建/切换前服务端和 runtime 分别检测：同 suffix 不同权威、Node/Service 短名、VPN 系统 resolver、search domain、Route answer overlap。结果分为 safe、shadowed、conflict、external_owned。conflict 不自动覆盖；用户看到来源和可执行动作。

#9. L4 Service

#9.1 对象和入口

Service 是稳定逻辑资源；ServiceEndpoint 是一个 ns/NSGW 承载实例；Local Manifest 是发布节点不受 NSD 扩大的本地上限。

发布入口统一写同一份 Local Manifest：App 向导、ns service add、services.toml、受管 desired manifest。NSD 远程请求在 user-owned 设备上必须本地接受；managed device 只能在未撤销的 ManagedConfigAuthorization 范围内自动接受。

#9.2 Frontend 模式与可执行策略

硬规则：AccessGrant 含 HTTP path/method 时，Service 必须选择可信 L7 终结模式。原始 TUN TCP 或 TLS passthrough 看不到 HTTP path，NSD 必须拒绝发布不可执行的规则，不能接受后在 UI 声称已保护。

https_terminated 的 user-facing hostname 需要有效证书。NSIO 托管 svc.ns.io 可由部署级内部/公开 CA 自动签发；自定义域名要求 DNS ownership 和 ACME/上传证书。到 origin 的 TLS 有独立验证策略（system CA、pinned CA/SPKI 或明确 insecure-dev），不能复用边缘证书假装验证后端。

#9.3 发布向导

1. 选择本机端口、远程 URL/IP、Unix socket、容器/Kubernetes discovery 或 Gateway Egress；
2. 选择 frontend mode，表单只展示该模式真正支持的字段；
3. 本地 health probe，显示 DNS、TLS、端口和身份结果；
4. 设置名称、说明、owner、catalog presentation、可选自定义域名；
5. 设置本地允许上限和是否允许 managed updates；
6. 预览将创建/更新的 Service、Endpoint、证书和 CapabilityActivation；
7. 本地保存后上报，进入 waiting_control / waiting_approval / active / backend_failed；
8. 创建 AccessGrant 是独立步骤，可在同一向导最后跳转但不能暗中自动全员开放。

#9.4 Catalog presentation

目录展示是 Service 元数据，不是新的授权平面：

只有已获 AccessGrant 的用户能得到完整目录项；requestable 用户只得到第 5.5 节的最小占位。presentation 绝不能让未授权用户获得 VIP/Endpoint。

#9.5 多 Endpoint、健康和 HA

同一 Service 可有多个 Endpoint，必须声明相同 frontend contract。Endpoint 单独经历 requested/approved/healthy/draining/offline/revoked；添加 host 不重建 Service ID/VIP/DNS。

默认选择策略为健康优先 + 会话黏性 + region/path cost；可选 round-robin/weighted/region-pinned。HTTP 请求、TCP connection 和 UDP association 是最小调度单位，不在一个流中切 Endpoint。

• 新 Endpoint 必须逐实例 Activation/approval，即使 CapabilityPolicy 可 auto approve；
• health check 从发布端本地执行，NSD 只相信签名且短期的结果，并可结合消费者失败；
• 修改 backend 使用 next generation，健康后原子切换；
• drain 停止新流，等待上限后关闭旧流；安全 revoke 不等待普通 drain；
• 全部 Endpoint 不健康显示“暂无可用后端”，不删除 Service、不改 unauthorized。

#9.6 消费路径

TUN 与 Local Proxy 共用同一 Service Directory、Flow Credential、Endpoint 选择和目标端校验：

TUN: App → Service VIP → ns flow credential → encrypted path → publisher proxy/forwarder
Proxy: App/PAC → 127.0.0.1 → Host/SNI lookup → same flow credential/path → publisher

Proxy 入口不接受任意 CONNECT，只接受已授权 Service/DomainService。获得 Service 不获得 host Node 的通用端口权限。

#9.7 修改、停用和删除

后端读取失败、NSD 目录读取失败、没有 Grant、全部离线必须分别显示。

#10. Route 与 Connector

#10.1 对象分类

DomainRoute 是 best-effort IP 捕获，不是严格的应用身份。共享 CDN、DNS 快速变更或同 IP 多域名场景必须使用 DomainService；控制台不能只因用户填写了域名就宣称实现了域名级隔离。

#10.2 创建和审批闭环

1. 节点所有者在本机声明可连接的 CIDR、zone/origin resolver、协议、端口、NAT mode 和健康检查上限；
2. CapabilityPolicy 判断该节点是否可以申请 connector；
3. NSD 计算地址、DNS、现有 VPN 和其他 Route 冲突；
4. 管理员查看可达面、来源保留要求、返回路由和受影响 Grant 后批准；
5. 逐实例 CapabilityActivation 占受管资源配额并签发 Lease；
6. 创建逻辑 Route/ConnectorSet，随后单独创建 use_route AccessGrant；
7. NSD 生成客户端和 Connector 两份投影；两边 ACK 后才进入 ready；
8. Client 只为获得 Grant 的主体安装精确路由/DNS 规则。

“节点已声明”“管理员已批准”“用户已获授权”“Route 当前可用”是四件事，列表和 API 必须分别表示。

#10.3 双端执行

客户端投影只包含被授权 Route、精确目标、Connector 候选和短期 RouteAccessCredential。Connector 投影包含 source membership → allowed destination/protocol/port/NAT 白名单。凭据自证并绑定两端 projection digest；Connector 本地验签和判定，建流时不查询 NSD。

Application packet
  → Client route match + source egress rule
  → signed RouteAccessCredential
  → encrypted path to selected Connector
  → Connector validates source, route, generation and exact destination
  → origin network

任一端缺投影、revision/digest 不匹配、凭据过期或实际目的地越界时不转发。客户端“知道 Route”绝不能令被攻陷客户端访问 Connector 所在网络的其他地址。

#10.4 HA、NAT 和冲突

同一 ConnectorSet 可有多个已批准实例。选择按 ready、region/path cost、priority 和会话黏性；现有 TCP/UDP association 不在中途迁移，新流避开 draining/unavailable 实例。

• 默认 snat，远端只需返回到 Connector；
• preserve_source 仅在管理员提供并验证返回路由时允许；
• 多 Route 重叠按 longest-prefix，再按显式 priority；同 prefix 同 priority 且目标权威不同为 conflict；
• 与本机 LAN、系统 VPN、Exit、Service VIP 重叠时显示所有权来源，不静默抢占；
• additive 更新可有界双代重叠；restrictive 更新默认 security-first，允许短暂 fail-closed；
• Connector 全部不可用时 Route 保持已授权但显示 unavailable，不自动把目的地改走公网。

#10.5 用户交互

普通成员只看到“企业网络 10.20.0.0/16 · 已连接/暂不可用”，不看到 Connector 私网地址。管理员页面分别列 Route、ConnectorSet、实例健康、授权主体和最近流量；点击某条 Route 可以从任一用户/设备做 Effective Access 模拟。

撤销 Grant 只影响对应消费者；暂停一个 Connector 让新流切到其他实例；撤销最后一个 Activation 先展示会中断的 Route、Service 和 DNS zone。读取故障显示“暂时无法刷新”，不能显示成“没有 Route”。

#11. 直连、Relay 与路径选择

#11.1 路径不是授权

P2P、community relay、managed relay、dedicated relay 只是同一授权流的传输路径。RelayRouteLease 只允许转发端到端密文，不能获得 Node/Service/Route/Exit 权限；AccessGrant 也不能让一个未分配给该 Network 的 Relay 承载流量。

#11.2 建链顺序

1. 应用请求命中已授权 Node/Service/Route；
2. ns 检查本地投影和 Flow/Route credential；
3. 通过候选交换做 UDP hole punching，首选已验证直连；
4. 超时后并行尝试受策略允许的 Relay；
5. UDP 被封锁时才尝试 WSS fallback；
6. 更优路径可在连接内迁移，但不能改变授权或流身份；
7. UI 显示 direct/relayed、区域、延迟和最近切换原因。

路径发现材料有独立短 TTL。NSD 失联时，未过期 session 可以继续；新建路径只能使用仍有效的授权和候选材料，不能为了“恢复连接”绕过目标端校验。

#11.3 Relay 产品闭环

• 个人和自建环境可使用明确标注的基础 Relay；
• 付费区域、容量、SLA 和专属实例属于 Managed Relay entitlement；
• 管理员可限制 Network 可用区域、禁止跨地域或只允许专属 Relay；
• Client 不提供“信任此 Relay”的安全开关，因为 Relay 从来不是明文信任方；
• 容量不足、区域不可达、token 错误和无授权必须是不同诊断；
• Relay 故障只触发重选路径，不修改 Grant、Node 状态或 Service 目录。

#12. Gateway Egress 与 Gateway Exit

#12.1 两种能力不能合并

访问 IP 白名单 SaaS 优先使用 Gateway Egress，避免把整机公网交给出口。Exit 不能自动获得 Service 目录，Egress 也不能变成通用 CONNECT 代理。

#12.2 Gateway Egress 闭环

1. 管理员/发布者创建 Service，backend 选择 Gateway Egress；
2. 配置 origin hostname、port、TLS 校验、允许 IP 分类和固定 region；
3. NSGW 用受控 origin resolver 解析，防 DNS rebinding 并健康探测；
4. Activation 批准后生成 Egress Lease；
5. 用户必须另有 Service AccessGrant；
6. 流量经 Service 路径到 NSGW，再以验证过的固定公网 IP 连接 origin；
7. UI 展示“经新加坡固定出口访问”，但不把用户整机状态显示为 Exit。

origin 超出允许目标、DNS 结果变成私网/保留地址、证书失败时该 Endpoint unavailable，不能尝试任意其他目标。需要对方白名单的是 NSGW 的固定公网 IP，不是用户设备或发布节点的公网 IP。

#12.3 Exit 的五个独立事实

任何 UI、API 或审计记录都不能压成一个 exit_enabled 布尔值。特别是“有保存配置”不等于“正在使用”，“被授权”不等于“必须使用”。

#12.4 管理员连接策略

策略由 Network/Device policy 决定，用户偏好只在 optional 下生效。策略改变必须预览影响并写审计；从 optional 变 required 不能等同于普通设置同步。

#12.5 可选出口交互

设置页“互联网出口”开关是唯一用户意图源；开启联动 TUN。首次连接先建立可明确展示的标准 TUN 连接，获取已授权候选后弹出单选列表；确认配置后重启为 Exit。取消会恢复原数据面，恢复完成后才提交偏好。

已保存 selection 正常时直接由 daemon 读取并启动；App 的“上次使用”缓存只用于未连接展示，不参与启动或授权。候选失效后不自动替换：连接前已知失效则直接重选；已进入 capture 后出现 mismatch/timed_out 则保持当前事实，并给“重新选择出口”和“关闭出口”两个明确动作。

no_authorized_candidates 是确定状态：optional 用户可明确提示后关闭开关并恢复原数据面；not_ready、read_failed、temporarily_unavailable 保持意图并允许重试，不能伪装成未授权。

#12.6 IPv4、IPv6、DNS 和私网

Exit scope 必须逐项展示：公网 IPv4、IPv6、CIDR、DNS、private networks。UI 只陈述 runtime 证据：

• capture ready：出口范围内流量已被捕获；
• capture inactive/not_ready：出口范围内流量当前未经过公司出口；
• IPv6 external_unmanaged：IPv6 由其他 VPN/网络管理，未经过公司出口；
• unknown/not_applicable：不宣称 IPv6 已走出口并记录诊断。

macOS/Windows/Linux 与外部 VPN 冲突时默认 fail-closed。兼容策略可允许 external-managed，但本次运行内必须黏性保持，不能在外部 TUN 短暂重启时抢回黑洞路由。

#12.7 关闭、换网关和撤销

• 断开连接不清 selection；
• 关闭 optional Exit 只停止使用，不删除保存选择；
• 换网关先取最新候选，单选确认后原子写配置并重连；当前失效时不预选；
• 管理员撤权后停止新 Lease；capture 已建立则按 required/optional 策略保持阻断或等待用户明确关闭；
• Gateway drain 停新 flow 并在有候选时按策略迁移，不能未经用户/策略授权跨 region 自动换；
• 清除 selection 是独立的破坏性管理动作，不作为普通关闭流程的一部分。

#13. Public Application 与 Edge Auth

#13.1 对象和信任边界

公网发布只能绑定已有 Service：

PublicApplication(host/path)
  + EdgeAuthPolicy
  + IngressBindingLease
  → NSGW listener/TLS/WAF
  → restricted Gateway identity
  → one Service

不能直接填写任意 backend IP/port 绕开 Service 本地 manifest。EdgeIdentity 只描述这次外部访问，不获得 Organization Membership、Node IP、peer map 或横向网络权限。内部 AccessGrant 与 EdgeAuthPolicy 独立；一个应用可同时有内部员工入口和公网访客入口，两边授权互不替代。

#13.2 六种认证方法的准确语义

不提供名为 Bypass 的生产模式。Anonymous 仍执行 TLS、host/path、WAF、rate limit、body/header limits、request audit 和 backend binding；策略或存储故障返回 503，不能因为“无认证”而跳过控制。

API Key 是兼容方式，不是推荐的机器身份：默认最长有效期、最小 scope、可轮换重叠和最后使用时间；高安全应用可禁用。Service Credential 是自动化首选，短期 token 不把 client secret 直接带到每个请求。Signed URL 不能升级为目录浏览权，也不能被换成长期 session。

#13.3 Policy 创作

EdgeAuthPolicy 顺序表达 deny-risk/require-auth/allow 结果，但安全默认仍是无匹配拒绝。条件可引用：应用/path/method、EdgeIdentity、IdP group/claim、认证强度、设备 posture 信号、地理/网络、时间、credential scope 和风险结果。

表单只允许当前 frontend 可执行的条件；高级编辑器保存前调用真实 EdgePolicyEvaluator dry-run。模拟输出匹配规则、身份、条件、结论、kernel/evaluator version 和 provenance；提交时重新计算 digest，不能信任浏览器模拟结果。

#13.4 创建闭环

1. Edge Admin 选择一个 active/degraded Service；
2. 选择域名/path，完成 DNS ownership；
3. 选择 TLS、WAF、region、限流和请求体上限；
4. 选择认证方法并配置 IdP/client/cert/key/signing issuer；
5. 预览公网暴露范围、后端 Service Grant 无关性和费用；
6. NSD 做 RBAC、Entitlement、CapabilityActivation 和冲突检查；
7. NSGW staging listener、secret、证书和后端 health；
8. readiness 后再切 DNS/启用路由；
9. 从外部探针验证 TLS、认证、拒绝路径和后端；
10. 控制台显示 active，提供访问 URL、策略 revision 和最近请求。

任何一步失败保留上一个有效 revision；首次创建失败不留下指向未就绪 listener 的 DNS。

#13.5 撤销和在途会话

NSGW 会话索引至少支持按 application、policy revision、binding lease、EdgeIdentity、credential、IdP session 定向终止。安全撤销在 SLA 内影响新请求并主动关闭长连接：HTTP 401/403、WebSocket 1008、gRPC UNAUTHENTICATED/PERMISSION_DENIED、raw stream FIN/RST。

#13.6 访客体验

OIDC 页面先显示应用名、请求 Organization、将共享的基本身份信息和返回域名，防止开放重定向和登录钓鱼。无权访问返回企业可配置但不泄露资源存在性的页面；已知登录用户可显示“没有此应用权限”，匿名探测默认统一响应。

Signed URL 过期页面说明链接已过期并允许联系签发者，不提供猜测新 token 的入口。API/机器请求返回稳定 JSON 错误码和 request ID，不重定向 HTML 登录页。

#14. Client、CLI 与管理控制台交互

#14.1 产品表面分工

App 和 CLI 是同一 daemon 的控制客户端，不各自启动一套 TUN/WireGuard。单实例锁、owner binding 和操作租约决定谁能控制；系统管理员只能进入 maintenance namespace，不能自动继承当前用户的目录和网络权限。

#14.2 App 首次使用

1. 首屏输入/发现控制服务器；云端默认 NSIO Cloud，私有部署显示其 NSD；
2. 点击登录，系统浏览器完成邮箱密码、Google、GitHub 或企业 OIDC；
3. Authorization Code + PKCE 通过 loopback/App Link 回 App；App 不接触密码；
4. 若账号首次出现，创建 Personal Organization 和默认 Network；
5. App 展示设备名称、Organization、Network、Device Key 指纹和申请能力；
6. 用户确认，完成 Enrollment；
7. 默认连接 TUN，状态依次显示认证、注册、获取策略、建立路径、应用 DNS/路由；
8. 成功后首页显示当前 Network、Node 名/IP、直连/中继和可用服务。

已有有效 session 时重复注册可由 session + Device Key 签名证明，不强制再次打开浏览器；跨 Organization 必须创建独立 Device Key，并在清晰的 Organization 选择后注册。

#14.3 CLI

有浏览器环境执行 ns up 时打开系统浏览器并用 loopback 回调。无头但有人操作时使用 Device Code：CLI 显示 URL、短码、指纹和校验短语；用户在另一设备登录、选择 Network 并确认；CLI 用 staging Device Key 签名轮询。

无人值守服务器使用单用途/有边界的 Enrollment Key，不使用人的 Device Code。命令必须显式选择 Network、ownership mode、requested capabilities 和 local manifest；默认 server 是 managed_device，但获得 Membership 不自动获得 service_host/subnet_router 等 Activation。

所有命令支持机器可读 JSON、稳定 error code、request ID 和无颜色模式。交互取消不留下正式 Device/Membership，但可恢复 EnrollmentRequest 和 staging key 按 TTL 清理。

#14.4 状态模型和文案

Client 只根据下层事实组合页面，不重新实现授权：

connecting 不能只有一个无限旋转状态。每个阶段有来源、超时、取消和重试；超时后显示停在哪一轴，不猜测根因。

#14.5 管理控制台信息架构

Overview
Users & Groups
Networks
  Nodes & Devices
  Services
  Routes & Connectors
  Gateways & Exit
  Access Policies
  DNS
Applications
Identity & Security
Automation
Audit & Diagnostics
Billing & Usage

资源详情页统一包含：身份/owner、授权、Activation、Availability、Projection、Runtime、依赖、审计和危险动作。列表过滤和详情状态使用同一后端 view，不让列表显示 active、详情显示 unavailable。

删除/撤销必须先做 impact preview；确认框说清受影响用户、节点、Service、Route、Gateway 和现有会话。读失败时禁止把空列表作为影响为零。

#14.6 安装、更新、卸载和多用户

• Windows/macOS/Linux 安装一个 daemon，App、CLI、helper 复用；移动端由一个 App/系统 Tunnel Extension 持有 VPN；
• 包、二进制、driver/extension 和 update manifest 全部验签；下载成功不等于可安装；
• 更新先检查本地 API/状态 schema/系统扩展兼容，staging 后原子切换，失败回旧 slot；
• user-owned 机器开机时 daemon 可启动，但 owner 未登录/未验证前停在 owner_inactive，不建数据面；managed_device 按 system identity 无人值守恢复；
• OS 用户切换先撤 TUN/DNS/Route/Exit 并证明清理，再交出 owner console；不能只锁 UI；
• 卸载先停止新流、撤系统网络并验证恢复，再删程序/状态；清理失败显示 repair action，不能报告已卸载；
• App Store、官网包、package manager 和 MDM 发行使用同一安装 ID/daemon 仲裁，不允许并存两套 runtime。

#15. API、自动化与基础设施即代码

#15.1 机器身份

自动化使用 MachinePrincipal 与 OAuth Client/工作负载身份，不复用 Human User 的长期登录 token。OAuth Client 绑定 Organization、允许 action/resource selectors、环境、owner、expiry 和 rotation policy；换取短 Access Token，审计记录 client 与触发流水线。

首版不把一个无限期 Personal Access Token 作为推荐入口。确需 API Key 兼容时，必须有 scope、expiry、hash-at-rest、一次展示、轮换、last_used、IP/网络条件和明确弃用路径。

#15.2 API 语义

• Console、CLI、Terraform/SDK 调同一业务 API 和事务，不存在 UI 专用绕过；
• 所有写操作支持 idempotency key、乐观 revision、dry-run/impact preview 和稳定错误；
• 创建与批准是不同 action；自动批准仍经过 Activation/Grant 事务；
• 列表使用游标分页和服务端筛选；导出是异步 job；
• webhook/outbox 至少一次投递，事件有 event ID、revision 和可验证签名；
• API 返回权威 ID 与 display name，自动化永远用 ID，不用可改名短名。

#15.3 管理归属

资源声明 management_mode = console | api | gitops | local_manifest 和 manager identity。GitOps/API 管理资源在控制台默认只读或通过“接管管理”显式转换；控制台不能悄悄修改后被下一次 reconcile 覆盖。

接管前展示 diff、停止旧 manager lease、提升 revision 并写审计。Local Manifest 是发布节点安全上限，即使 NSD 资源由 GitOps 管理也不能扩大它。

#15.4 常见自动化闭环

• Terraform 创建 Organization/Network/Group/Grant，不负责生成 Device 私钥；
• CI 创建 Service 元数据和 AccessGrant，节点以 manifest 上报 Endpoint；
• 云主机批量注册先获 Reservation，再逐机消费，失败退回未消费占位；
• Secret Manager 保存 Enrollment/OAuth credential，日志和 state 不输出明文；
• 自动化变更先 dry-run，生产 Network 可要求第二人审批或 step-up。

#16. 审计、日志、通知与诊断

#16.1 四种记录不能混成一张表

日志有 Organization/Network、actor/principal、resource、action、decision、reason code、policy/projection/kernel/evaluator revision、request/flow/session ID 和时间。默认不记录 payload、密码、token、私钥、完整敏感 URL query。

#16.2 审计闭环

管理写事务与 audit/outbox 原子提交；审计写失败时高风险写操作失败，不能先改资源再补日志。导出使用独立授权、watermark 和校验哈希；保留期清理、Legal Hold、手动修正配额和归档销毁本身都写不可变审计。

审计详情提供 provenance 跳转：从一次 deny 可查看命中的 Grant/Edge rule、输入 revision、posture、编译器版本和执行组件，但按管理员角色脱敏其他组织/用户信息。

#16.3 通知

通知只针对可执行事件：邀请、待审批、凭据将过期、设备隔离、Service 全部后端失败、Connector/Exit 无可用实例、策略发布失败、配额阈值、安全事件。每类支持 owner/admin/security/billing 路由、站内/邮件/webhook 和去重窗口。

“管理员后来给了 Exit/Service 权限”可以在已连接客户端观察到从无到有后轻提示一次，但绝不自动启用 Exit、切数据面或打开应用。

#16.4 诊断包

用户可生成脱敏诊断包：版本、平台、Profile、状态轴、最近错误码、路由/DNS 所有权摘要、路径和时间窗口。默认排除 key/token、完整成员目录、业务 payload 和无关系统日志；上传前显示内容清单并需用户确认。

管理员远程诊断只能请求采集，user-owned 设备需本地同意；managed device 按预授权策略采集并留审计。诊断读取失败不能被报告为“未发现问题”。

#17. Entitlement、部署与运营闭环

#17.1 商业边界不改变安全对象

Personal、Team、Enterprise 使用同一套 Organization、Network、Membership、Node、Service、Route、Grant 和 Edge policy。套餐只通过 features、quotas、limits、service_levels 控制能力资格、资源量、托管成本、治理和 SLA；购买不创建 AccessGrant，降档不暗中扩大或删除访问。

CapabilityPolicy 与逐实例 Activation 分工固定：Policy 定义“可以申请什么”，Activation 定义“本实例是否批准”，并承担配额占位、计量、审计和 Lease。auto approval 只是同一事务的一条分支。

#17.2 配额和批量部署

单资源准入使用 used + reserved + delta <= limit 的原子条件；缺 quota、投影陈旧、功能不包含和额度已满返回不同错误。Entitlement 激活事务负责 current head、防回滚和 quota projection；注册热路径不选择版本。

批量注册先创建有 TTL 的 QuotaReservation，一次预留 N，再逐设备短事务把 reserved 转 used。默认请求窗口 60 分钟、服务端硬上限 2 小时；接近到期显示未消费数量，结束/到期原子退还差额。SQLite 与 PostgreSQL 语义一致，吞吐不同。

#17.3 降档和欠费

• block 只阻止新增/扩大，存量安全流默认不立即切断；
• 新声明缺失的旧 quota 投影为 not_entitled tombstone，保留 used，不能伪装成 limit=0；
• 欠费、合同终止和安全撤销是不同事件，具有不同 grace 和会话处理；
• suspended Activation 保留占位/计费并保证可恢复，revoked 才释放；
• 数据清理按独立 retention policy、Legal Hold 和可审计销毁工作流执行。

#17.4 三种部署

协议和安全语义相同；托管价值来自身份治理、区域、容量、固定 IP、合规、支持和 SLA。私有部署的 Google/GitHub 登录需客户自有 OAuth application 或不启用；NSIO 共享 secret 不能覆盖任意客户回调域名。

#17.5 升级和回滚

每个协议面独立版本和 feature discovery；未知 additive 字段按本面规则处理，不能因 Entitlement 版本升级联动 bump 控制面/FFI。Capability Manifest 只用于协商，不能降低 Device Key 绑定、owner authorization、签名、replay 或 MFA 基线。

策略引擎升级先在相同数据驻留边界做 shadow evaluation；确认差异后发布 policy_engine_upgrade，即使策略文本未变也重新投影。运行配置使用 staging/ACK/atomic activate，旧有效版本保留到新版本可证明 ready；安全回滚不能越过已接受单调 revision。

#17.6 采购、支持与数据权利

免费注册不要求付款方式。自助购买和企业 Quote/PO/Invoice 最终都只产生可追溯的 Effective Entitlement revision；支付状态不直接创建 Grant。付款成功但能力尚未激活显示处理中并对账，不能重复扣款。

支持系统通过用户授权的诊断包、request ID 和脱敏租户视图排障，不能借 Platform Admin 身份越权进入客户 Network。客户可分别执行 Organization 导出、账号注销、Subscription 取消和 Organization 删除，这四者不是同一动作。

Organization 删除走 step-up、影响预览、可选导出、撤 Membership/Grant/Lease、关闭 Edge、等待期、active data 删除、backup expiry 和 completion report。Legal Hold 只保留明确覆盖的数据；删除失败列出未完成数据集，不显示成功。灾难恢复后以 restore epoch、防回滚水位和删除 tombstone 防止已撤销身份/资源复活。

#18. 端到端场景预演

本节不是教程，而是架构可实现性检查。每个场景都列出权威事实、执行点和收口；任一步依赖尚未存在的后续对象即判定不闭环。

#18.1 个人用户 Clark，两台电脑互访

1. Clark 在 NSD 登录；User 和 Personal Organization/默认 Network 创建；
2. Mac App 生成该 Organization 独立 Device Key，申请 user-owned Membership；
3. 默认 Personal Grant 模板允许 Clark 的 Membership 访问自己的 Node；
4. Windows 重复注册，获得另一 Node IP/FQDN；
5. NSD 编译双端最小 peer/ACL，Mac 与 Windows 优先 P2P，失败走基础 Relay；
6. App 的设备页显示 win.personal.clark.node.ns.io，Clark 可 ping/SSH/访问被授权端口；
7. Clark 禁用默认 Grant 后两台节点仍在线，并继续出现在“我的设备”管理页；可连接节点目录移除对端且不可互连，说明资产可见、目录授权和运行可达已分离。

闭环判断：不需要管理员手工复制 Network ID 或查询虚拟 IP；注册、命名、授权、路径和撤销都有独立权威。

#18.2 企业邀请 Bob，限制设备横向访问

1. Acme 管理员邀请 Bob，Bob 登录后获得 Organization Membership；
2. Bob 的笔记本注册到 Work Network，Device posture 显示 managed；
3. 默认无 Node-to-Node Grant，所以 Bob 看得到自己的设备和被授权资源，不枚举同事节点；
4. 管理员建组 developers，Grant 允许 developers 访问 service:git，不允许连接 git host Node；
5. Bob 从 Service 目录打开 Git，Service credential 在 publisher 端最终校验；
6. Bob 离职，SCIM 禁用用户，事务撤 session/token family、Membership、未消费 Grant，并重编译；公司所有 Device 保留待重新指派；
7. 短 peer/flow lease 到期前完成撤销 SLA。

闭环判断：用户、设备、Node 和 Service 没有合并成一个主体；离职不会误删公司资产，也不会因 Service Grant 获得宿主机横向权限。

#18.3 无头 Linux 发布生产 Service

1. 运维为生产 Network 创建 scoped Enrollment Key，限制 tag、次数、TTL 和 service_host 申请范围；
2. cloud-init 安装 ns，以 managed_device 注册；无需保存运维个人身份；
3. services.toml 声明 git-origin:127.0.0.1:3000 和本地上限；
4. CapabilityPolicy 允许申请，Activation auto 分支仍占配额、写审计并签 Lease；
5. health ready 后 Service Endpoint active；管理员另建 developers Service Grant；
6. 主机重启后 daemon 校验 system identity 并无人值守恢复；
7. 本地 manifest 删除 Endpoint 后 NSD 不能把它远程复活，除非存在未撤销的 ManagedConfigAuthorization。

闭环判断：Enrollment Key 只注册身份，不能直接发布或开放服务；本地同意、审批、授权和运行健康四关完整。

#18.4 只开放 L4，不允许 L3 横向

1. Network 不创建任何 Node connect Grant；
2. 创建 db TCP Service，只给 finance group invoke；
3. finance Client 获得 Service VIP/credential，不获得 publisher Node 的通用 peer 目录或端口；
4. 非 finance 用户查目录只得到无授权/可申请占位，不得到 VIP；
5. publisher 最终按 Service credential 接受 flow；直接访问 Node IP:5432 被双方投影拒绝。

闭环判断：L3 和 L4 共用隧道但不是同一授权；保留了 NSIO 相比纯节点 VPN 的核心差异。

#18.5 访问企业子网 Route

1. 两台 Connector 本地声明 10.20.0.0/16，逐实例批准后组成 ConnectorSet；
2. 管理员只允许 support group 使用 TCP 22/443；
3. Client 只安装该 CIDR 路由并携带短 credential；
4. Connector 本地校验 source、destination、port 和 digest，不查 NSD；
5. 一台 drain 后新连接选择另一台；两台离线时 Route 显示 unavailable 且目标不走公网；
6. 攻陷客户端尝试 10.30.0.1 或 UDP 53，Connector 投影拒绝。

闭环判断：Route 的权限在两端取交集，NSD 不在每流关键路径，HA 不扩大目的地。

#18.6 固定 IP 访问 SaaS

1. SaaS 只接受 NSGW 新加坡固定 IP；管理员创建 HTTPS Service，backend 选择 Gateway Egress；
2. NSGW 验证 origin DNS、证书和允许地址；
3. 用户获得 Service Grant 后从目录打开；只有该应用流量经过 NSGW；
4. SaaS 白名单填写 NSGW 固定 IP，不填写用户设备或发布节点的公网 IP；
5. origin DNS 被污染到私网地址时 Egress 拒绝，用户看到后端安全校验失败。

闭环判断：满足固定源 IP 需求而无需整机 Exit，也不暴露任意代理。

#18.7 可选和强制 Exit

个人可选：Clark 在设置开启出口，连接后选择香港 Gateway，确认后重连；IPv4 capture ready、IPv6 external-managed 时 UI 明确两种去向。Gateway 下线后保持事实和意图，不静默换新加坡或本地直出。

企业强制：Acme 对受管笔记本配置 always-on-required。机器开机先安装策略允许的 guard，owner/Device 认证和 Gateway projection ready 后才放行；用户不能关闭。控制面故障使用未过期材料，过期后范围内流量阻断并显示管理员策略要求。

闭环判断：用户偏好、管理员要求、授权、选择、捕获和可用性彼此独立；每句流量文案都有 runtime 证据。

#18.8 公网发布合作方应用

1. Service Publisher 已发布 admin-web HTTPS terminated Service；
2. Edge Admin 创建 admin.example.com PublicApplication，选择合作方 OIDC 和 partner-admins claim；
3. NSGW staging TLS/WAF/Policy/backend，外部探针通过后切 DNS；
4. 合作方登录形成 EdgeIdentity，仅能访问该 host/path，不获得 Network Membership；
5. 移出 IdP group 后新请求拒绝，已有 WebSocket 在撤销 SLA 内 1008 关闭；
6. 内部员工 Service Grant 完全不受该 Edge policy 变化影响。

闭环判断：公网身份、内部身份和 Gateway 后端身份三层隔离；停入口不删 Service。

#18.9 自动化创建策略

1. 平台团队创建 scoped OAuth Client，只允许管理 dev Network 的 Service/Grant；
2. Terraform dry-run 返回新增对象、影响主体和 digest；
3. apply 使用 idempotency key 和 expected revision；
4. NSD 事务写对象、audit、outbox；Compiler 生成投影；
5. 控制台将资源显示为 gitops-managed，只读；
6. 管理员要手改时先执行接管并确认 diff；
7. secret 泄漏后撤 OAuth Client，短 token 到期，资源本身不被误删。

闭环判断：自动化拥有明确机器身份和管理边界，不借用离职员工 token，也不与控制台互相覆盖。

#18.10 控制面故障与恢复

闭环判断：每个组件都能独立区分“读不到”“没有权限”“不可用”和“版本不兼容”，恢复路径不依赖先破坏当前有效状态。

#18.11 跨组织 Service 分享

1. Acme 将 service:reports Offer 给 PartnerCo，动作仅 invoke、有效 30 天；
2. PartnerCo 管理员接受并只绑定 group:auditors；
3. Alice 属于 auditors，得到短租约并在自己目录看到“Acme Reports（外部分享）”；
4. Alice 不知道 Acme 的 publisher Node、其他 Service 或员工；Acme 只看到稳定外部别名和必要姿态结论；
5. PartnerCo 移除 Alice 或 Acme 撤 Offer，任一动作都在 SLA 内停止续租；
6. federation 暂时不可用时只允许未过期材料，不把读取失败显示成分享已删除。

闭环判断：两边各自管理自己有权管理的半边，权限取交集，没有目录 union 或隐式 Network 桥接。

#18.12 更新失败与设备转让

1. Windows App 下载新 daemon，签名/架构校验通过后 staging；
2. helper 更新中断，安装器保留旧 slot，当前网络继续或可证明恢复；
3. 重启后 daemon 读 journal，不能把“进程运行”显示成“网络已连接”；
4. 公司把 Bob 的笔记本交给 Carol：先撤 Bob Membership/owner session，保留 Organization-owned Device，清除 assigned principal；
5. Carol 登录并经管理员指派获得新 Membership/Node Key；旧密钥和旧 Profile 不能复用；
6. 卸载时先清 TUN/DNS/route/helper，验证后再删文件。

闭环判断：发行生命周期和身份生命周期使用同一 owner/lease/journal 事实，不会因升级或转让留下前用户网络权限。

#18.13 NSD 读取失败时的目录和授权

1. Bob 已连接，持有仍在有效期内的 Service projection revision 18；
2. Client 刷新目录时 NSD 存储超时，返回 service_directory_read_failed，不是空 services=[]；
3. ns 保留 revision 18，projection=outdated_applied，Client 显示“暂时无法刷新，当前显示 10:32 的已验证目录”；
4. revision 18 内已授权 Service 在 Flow Credential/Projection 未过期时可继续新建流；读取故障不能扩大到未在 revision 18 中的资源；
5. 到期仍无法刷新时停止签发新 flow，现有流按 lease/drain 规则处理，目录项显示已过期而不是 unauthorized/offline；
6. 存储恢复后下发 revision 19，原子应用并把 freshness 恢复为 fresh；
7. 反向测试把读取故障改成空目录时，必须因授权被伪撤销和错误状态折叠而失败。

闭环判断：最后有效投影、展示缓存和权威新鲜度是三个事实；用户能知道现在看到的是什么，也不会因系统故障被误告知“管理员没授权”。

#18.14 Route 策略更新与 generation 窗口

Additive：管理员在 Route R 增加 10.20.8.0/24。Connector 先 staging generation N+1 并 ACK；旧 credential N 仍只能访问 N 的目的地，新 credential N+1 才能访问新增网段。两代集合不做 union，切换窗口内旧业务不中断。

Restrictive：管理员从 R 移除 10.20.4.0/24。security-first 流程先把 N+1 窄投影装到 Connector，随后发布 activation epoch；到点后 Connector 拒绝 N 的新流。未收到 N+1 的 Client 保持 fail-closed，不能拿旧 credential 继续。需立即撤销时终止相关在途流；允许 bounded drain 时 UI 明示旧权限最晚失效时间且不得超过 credential TTL。

故障：某 Connector 未 ACK N+1，NSD 将它移出候选但不阻塞其他健康 Connector。全部未 ACK 时 Route 显示 projection failed/unavailable，客户端不把目的地送公网。策略读取失败保留未过期 N，不生成空目的地集合。

闭环判断：更新窗口可能短暂 fail-closed，但不会短暂放宽；管理员可以从 provenance 看到每个 generation 的范围、执行者和最晚失效时间。

#18.15 Edge 策略收紧并终止 WebSocket

1. Alice 通过 OIDC 打开 PublicApplication，并建立 WebSocket；NSGW session index 记录 application、policy revision、EdgeIdentity、IdP session 和 credential；
2. Security Admin 撤销 Alice 的 EdgeIdentity，或发布不再允许 Alice 的 policy revision；提交事务立即停止新 session/credential；
3. 撤销事件到达 NSGW 后按身份或旧 revision 找到在途 WebSocket，在在线目标 60 秒门内发送 close code 1008 并结束后端流；
4. 事件暂时丢失时，旧 Edge session/Binding Lease 最迟 5 分钟过期，不能无限存活；
5. Alice 重连得到 403/明确无权页；NSGW 策略读取故障返回 503，不能伪装成 Alice 被拒绝；
6. 内部员工通过 Service AccessGrant 的会话不在 Edge session index 撤销范围内，不被误断。

闭环判断：策略收紧同时覆盖新请求和长连接，又不越界影响内部 Service 授权；60 秒在线目标与 5 分钟硬上限均可真测。

#19. 实现分工与完成门

#19.1 按能力切片，而不是按页面切片

每个实施任务必须纵向覆盖 Shared schema → NSD 事务/Compiler → ns/NSGW 执行 → Client/Console 展示 → 测试/审计。只做页面或只加数据库表不能宣布能力完成。

#19.2 每个 Slice 的 Definition of Done

1. 对象 schema、状态机、revision、ownership 和删除语义已发布；
2. API 有创建、读取、更新、停用、撤销、impact preview 和稳定错误；
3. 权威判定只实现一处，Client/Console 不复制；
4. 目标组件只获得最小签名投影，且有 expiry/rollback/replay 防护；
5. 正常、等待、无权、不可用、读取失败、版本不兼容状态可区分；
6. 用户入口、取消、重试、恢复、切换和破坏性确认可完成；
7. audit、metrics、logs、notification 和 support diagnosis 可关联；
8. Entitlement/Quota 在事务层执行且不替代 Grant；
9. 单元、契约、属性、故障注入、跨组件和真机测试通过；
10. 文档中的角色场景已用真实构建执行并保存证据。

#19.3 不能接受的“完成”

• UI 有开关但 runtime 没有独立状态轴；
• NSD 返回 allow 但目标端没有最终校验；
• 只测 fixture，不用真实 serializer 对 schema；
• 用空列表表达读取失败；
• 用套餐、角色或设备名代替 AccessGrant；
• 为旧实现增加 Next 运行时双协议/双对象；
• 模拟器、控制台或 App 复制生产求值逻辑；
• 只在 mock 中通过，不做系统路由、DNS、权限、VPN 冲突和长连接真机测试。

#19.4 技术可行性闸门

Gate 通过只证明其技术前提，不自动完成上层 Slice。每份证据必须绑定 commit、平台/拓扑、配置、时间和原始结果；测试目标只能经版本化架构决议调整，不能因实现困难在单个仓库里降低。

#19.5 首发规模、设计上限与验证值

三个数字的含义不同：首发目标是 GA 前必须通过的支持规模；设计上限要求 ID、schema、分页、流式传输和分片边界不能把系统锁死在首发规模，但不是性能承诺；已验证值只能来自可复现 benchmark，不能用估算填写。

#对象规模

设计不得把 subjects × resources 的 effective edge 全量持久化。Grant 保留 selector/revision，Compiler 按受影响目标增量展开；Effective Access/模拟使用分页查询和真实 Compiler dry-run，否则 10 万成员与 50 万规则会产生不可控笛卡尔积。

#投影与时延

地址 schema 使用完整 IPv4/IPv6 与可扩展多地址块，不把一个 Network 固化成单个小前缀。默认地址规划必须容纳首发 Node + Service 峰值、30 天删除隔离和至少 2 倍运维余量。

具体扩容闸门：当 12 个月容量预测中 active Node + Service 超过 20,000，或已分配 IPv4 块把 active、quarantine 和保留余量计入后达到 75% 占用时，Network 必须进入 address_capacity_plan_required，禁止继续无提示分配。管理员必须选择并验证：IPv6-first、追加一个或多个不重叠 IPv4 地址块，或客户自定义地址池。IPv6-first 要求所有新 Node/Service 具备稳定 IPv6，IPv4 只作为显式兼容资源分配；依赖 IPv4 的 Route/应用在影响预览中逐项列出。销售和 API 不能在没有已批准 capacity plan 时承诺或创建超过 20,000 个稳定 IPv4 资源的单 Network。

Benchmark 固定数据生成器、拓扑、硬件、数据库、缓存冷热、变更类型和编译器版本。每次回填“已验证值”追加日期与证据链接，不降低原目标；达不到目标时先优化或形成版本化架构决议。

#20. 当前结论

上述能力在结构上可实现，且没有要求 NSD 进入业务流量路径，也没有要求 NSGW 获得整个 Network 权限。最关键的闭环依赖是：统一 ns daemon、Organization-scoped Device Key、Membership、PolicyKernel、短期签名投影、目标端最终执行和多轴状态。

实现顺序必须先完成身份/注册、L3 和 Policy Kernel，再构建 Service、Route、Gateway 与 Edge。后面的能力可以复用前面的身份、租约、投影和审计机制，但不能用“共用底层”把不同授权平面合成一个布尔开关。