#NSIO Next · 控制资源、审批与生命周期协议

本文补齐租户控制面中不能进入 Runtime Projection、但会触发编译、准入、审批、撤销或审计的权威对象。Identity/Enrollment 分别以专项文档为准；AccessGrant 编译以 PolicyKernel 为准；本文固定 Group、AdminRoleBinding、AccessRequest、CapabilityActivation、MachinePrincipal、Posture、Publication、Share 和密钥轮换的状态与 API。

#1. 公共命令和对象字段

所有写命令遵循 共享命令信封，并在权威事务中同时写资源、revision、audit 和 outbox。控制对象最小字段：

typed_id, deployment_id, organization_id, optional network_id,
status, revision, created_at/by, updated_at/by,
owner_ref, managed_by, labels, last_operation_id

• status 是对象生命周期，不承载 availability、projection、runtime 或 freshness；
• 对象禁用/撤销使用状态与 tombstone，不靠物理删除表达安全结果；
• 所有 list/get 先按 TenantContext 过滤；无权对象与不存在对象对普通调用方使用统一不可枚举结果；
• create/update/approve/revoke/rotate/delete 分别使用独立 action，不能用一个 write；
• 高风险命令要求 step-up、impact digest 和理由；
• API 成功返回 committed revision 与 operation ID，不能宣称 runtime 已 applied。

#2. Group 与成员来源

#2.1 Group 类型

Device、Node、hostname、email 字符串不是 Group 成员；Group 成员是 UserPrincipal/MachinePrincipal。设备条件进入 AccessGrant source conditions。首版 group_ids 不能作为另一 Group 的 member，发现嵌套或循环返回 group_nesting_unsupported。

#2.2 API

批量成员更新是单 revision 和单审计操作；不能循环产生中间 policy projection。SCIM sync 使用 provider cursor/revision 和完整/增量模式，读取失败保留最后有效成员集并标记 sync_read_failed，不清空 Group。

#3. AdminRoleBinding

#3.1 对象和状态

AdminRoleBinding(subject, resource_scope, actions, conditions) 是管理权限权威。状态为 active|suspended|revoked|expired；suspended 不允许管理操作但保留对象，revoked 不可恢复。

首版 action registry：

预置角色只是创建 Binding 的模板。OrganizationOwner 不能删除最后一个有效 owner；Role 管理不能由仅持有普通资源 update 的主体完成。

#3.2 判定和 API

AdminAuthorizer 在线读取同一事务快照中的 subject、Binding、scope、condition、assurance 和 expiry。不存在 allow 即 deny；读取失败返回 admin_authorization_read_failed，不伪装 403。

API 为 /orgs/{org}/role-bindings 的 create/list/get/update/suspend/revoke/impact。任何扩大 actions/scope 或修改 Role Binding 自身要求 step-up；提交前重新计算 actor 是否仍有 role.bind。

#4. AccessRequest 与临时授权

#4.1 状态机

created → evaluating → eligible
                    ↘ denied | evaluation_error
eligible → approval_pending → approved → active
        ↘ auto_approved ───────────────→ active
approval_pending → rejected | canceled | expired
active → expired | revoked

evaluation_error 不等于 denied，可重试但不能批准。approved 是审批决议；同一事务创建一个 immutable TemporaryAccessGrant 并进入 active。Temporary Grant 使用生产 AccessCompiler，不建立第二套 allow 算法。

#4.2 请求内容

请求绑定 subject、source condition snapshot、resource/action/constraint、reason、requested duration、target Network 和 requester proof。服务端按策略限制最大时长、是否允许自助、审批角色和是否要求 ticket/step-up。

批准时重新校验：request revision、subject/Membership、resource、eligible policy、approver、Entitlement（若该工作流是商业能力）和冲突。有效期为 min(approved_at + requested_duration, policy_max_not_after)；批准不自动延长已有 session assurance。

#4.3 API 和撤销

active revoke/expire 立即停止新 credential/lease 签发，并走增量 reverse dependency 撤销；在线 99% 60 秒、旧租约最迟 5 分钟失效。Request、审批、Temporary Grant 和 projection provenance 使用同一 request/operation chain。

#5. CapabilityPolicy 与 CapabilityActivation

#5.1 分工

CapabilityPolicy 回答“谁可以申请什么最大范围、是否可自动批准”；CapabilityActivation 回答“这个具体实例是否批准、是否占配额、是否有 Lease”。Policy allow 永远不能跳过 Activation 事务。

#5.2 Activation 状态与独立轴

requested → evaluating → approval_pending | auto_approving
approval_pending | auto_approving → active
requested/evaluating/approval_pending → rejected | canceled | expired
active ↔ suspended
active|suspended → revoked

Availability=ready|degraded|unavailable，Projection=pending|applied|failed|outdated_applied，Runtime=inactive|starting|ready|draining|failed 独立存在。离线只改变 Availability；suspended 保留 used 配额占位，revoked 原子释放；可选 auto_revoke_at 必须显式设置。

#5.3 原子批准

批准和 auto approve 使用相同事务：重验 Policy → 分类 Managed Resource → 原子 quota admission/reservation consume → 写 Activation active revision → usage slot/outbox → audit → 触发 Capability Lease。任一步失败不留下 active 或计费占位。

API 位于 /networks/{net}/capability-policies 和 /capability-activations，分别提供 simulate/publish 与 request/approve/reject/suspend/resume/revoke。resume 不重新抢 quota，因为 suspended 保留占位；Entitlement 已失去能力时不能 resume，返回 feature_not_entitled 并要求影响预览后 revoke。

#6. MachinePrincipal 与 OAuth Client

#6.1 对象

MachinePrincipal 是非人类 ACL subject，OAuth Client/Workload Credential 是证明方式。两者不能合成一张长期 API key。

MachinePrincipal: principal_id, org, owner, purpose, status, labels
OAuthClient: client_id, principal_id, auth_method, allowed_scopes,
             resource/audience selectors, environments, expiry, rotation policy

状态为 active|suspended|revoked|expired。Client secret 只在创建/轮换时展示一次并 hash-at-rest；优先支持 private_key_jwt 或 mTLS，兼容 secret 也必须有 expiry。

#6.2 Token exchange

POST /oauth/token 使用 client_credentials，服务端本地验证 credential、principal、Admin/Access policy、audience 和 entitlement，签发最长 15 分钟 Access Token。Token 至少绑定 issuer、subject MachinePrincipal、organization、audience、actions/scopes、resource selector digest、credential ID、issued/expiry 和 token ID。

轮换使用 prepared → dual_valid → activated → retired，重叠窗口可配置但有上限。revoke credential 终止该 credential 派生 token/Edge session；revoke MachinePrincipal 终止其全部 credentials、Membership/Access 派生，但不删除审计。

管理 API 位于 /orgs/{org}/machine-principals 和 /oauth-clients，包含 create/read/update/suspend/revoke/rotate/last-used。Terraform/API ownership 使用 managed_by 和 expected revision，控制台不能静默覆盖 IaC 管理字段。

#7. Device Posture

#7.1 来源和信任

PostureProvider 状态为 active|suspended|revoked，来源类型为 platform_attestation|mdm|edr|ns_observation|admin_assertion。普通 ns 自报 OS managed 不能升级为受管证明。

PostureClaim 至少包含 provider、device、claim type/value、assurance、observed_at、expires_at、source evidence digest、signature 和 revision。NSD 规范化到注册 claim registry；未知 claim 不能被 Policy 当 truthy。

#7.2 求值状态

Provider read failure 不清空历史 claim。高安全 Grant 可以要求更短 freshness；Posture 改变触发受影响目标增量编译和短 lease 撤销。

API 包括 provider configure/test/suspend/revoke，Device posture view/refresh，以及 provider webhook ingestion。Webhook 必须验签、去重、限制 tenant scope 并记录 source revision。

#8. Service Publication

#8.1 三个对象

• LocalManifest：节点本地权威，不在 NSD 数据库冒充远端配置；
• ServiceDeclaration：ns 对本地事实的签名上报；
• PublicationRequest：NSD 向节点请求本地接受的工作流。

Service/Endpoint 是 declaration 被批准后的正式 Network 资源。删除 Service 不删除 LocalManifest。

#8.2 PublicationRequest 状态

created → delivered → accepted → declaration_pending → completed
                   ↘ rejected | expired
created|delivered → canceled

用户设备/普通服务器的 accept 必须由 Runtime Owner/本地管理员签名；受管服务器仅在本地 ManagedConfigAuthorization scope/revision 内 auto accept。超出范围返回 local_manifest_denied，NSD 不重试成更宽请求。

Runtime event 使用 publication.request/status；本地 API 使用 ns service request list/accept/reject。Publisher role Service projection、ServiceFlowCredential 和建流以 Data Plane Protocol §6 为准。

#9. 跨 Organization Share 与 Federation

#9.1 权威对象

状态分别为 Offer=draft|offered|accepted|suspended|revoked|expired，Federation=pending|active|disabled|revoked，Binding=pending|active|suspended|revoked|expired。读取失败不改成 revoked。

首版协议只接受 resource_kind=service。跨 Organization Node 或 Route 返回 federated_resource_kind_unsupported；它们需要独立的 L3 peer identity、双端投影和路由冲突评审，不能通过复用 Service lease 偷渡实现。

#9.2 建立 Federation

1. provider 创建不可枚举 share_id 和一次性 accept secret，Offer 链接包含 provider deployment URL、share ID 和 secret，不含资源目录；
2. consumer 管理员登录本方 NSD、查看 provider 名称/资源摘要/动作/期限并确认目标主体；
3. 两个 NSD 通过 HTTPS 获取 /.well-known/nsio-federation，交换 deployment signing key chain、capability range 和随机 challenge；
4. 双方用 Organization federation key 对 transcript 签名并 pin 对端 deployment/key fingerprint；
5. consumer 创建 ShareBinding，provider 将 Offer 标为 accepted；
6. 任一重放 secret、nonce、过期 key、目标 Organization 不匹配或 transcript 不一致都拒绝。

Federation key 轮换使用交叉签名链；disable 只停新 lease并保留对象，disable_and_revoke 立即撤所有派生 lease，delete 仅在无 Offer/Binding/lease 后允许。

#9.3 联合编译和凭据

consumer NSD 不向 provider 发送 User/Group/Device 目录，只发送由当前 ShareBinding revision 生成的 opaque external_subject_id、posture result digest、binding revision 和短期证明。provider 按同一编译快照计算：

provider resource Grant ∩ ShareOffer ∩ ShareBinding proof
∩ posture ∩ validity

provider 签发 FederatedAccessLease，claims 包含 share/offer/binding/federation revision、opaque external subject、resource/action、audiences、projection digest、issued/expiry、credential ID 和 provenance。consumer NSD 只把它投影给本地已命中 ShareBinding 的 Membership。

访问 Service 时，consumer ns 为本次短期 federation path 生成会话公钥并经 consumer NSD 的 Binding proof 提交；provider NSD 验证后签发 source_kind=federated_binding 的 ServiceFlowCredential，绑定 opaque external subject、source_session_key_hash、目标 Service/Endpoint、publisher audience、Binding/Offer revision 和最长五分钟有效期。consumer ns 在 carrier transcript 证明持有对应私钥，publisher 按数据面协议 §6本地验签。provider runtime 不看到消费方 User/Group/Device/Membership ID，建流不查询任一 NSD。

Offer/Binding/Federation 任一 revoke 立即停签 FederatedAccessLease 与派生 ServiceFlowCredential，并增量撤销。双方收到同一 opaque share ID 的 tombstone；对方控制面不可达时旧凭据最迟 5 分钟失效。Provider 资源关闭先通知 consumer 并保留审计 tombstone，不能显示“从未分享”。

#9.4 API

Provider：/share-offers create/preview/send/suspend/revoke；consumer：/share-bindings preview/accept/suspend/revoke；deployment：/federation-bindings verify/disable/disable-and-revoke/delete。所有动作带 expected revision、impact digest、step-up 和 audit。

#10. Device、Node 与 WG Key 轮换/转让

#10.1 轮换状态

所有 key rotation 使用独立 rotation_id：

requested → proof_verified → prepared → projected → dual_valid
→ activated → retired
                  ↘ failed | revoked

Device Key 轮换用 current Device Key 或管理员 recovery approval 证明；Node/WG Key 按 Membership 独立轮换。私钥始终在 ns 安全存储。prepared key 不成为 active identity，直到双方 ACK 和 activation epoch。

#10.2 设备转让

Organization-owned Device 转让先 impact preview：旧 assigned principal 的 Membership、temporary access、sessions、Service publication 和 managed config。提交事务撤旧 assignment/Membership 派生、停签旧 lease并创建新 assignment decision；节点轮换 Node/WG key 后才能恢复 active。Device ID/资产审计保留，旧 principal 不能在新 key 激活前继续使用。

user-owned Device 不直接转让；使用 revoke + 新 principal 重新 Enrollment。OS 本地 Runtime Owner Binding 与远端 owner/assignment 是不同对象，两边都必须成功才能控制 user-owned runtime。

API 位于 /devices/{id}:rotate-key、/memberships/{id}:rotate-node-key、/devices/{id}:reassign，均返回 operation、phase 和 per-target ACK 状态。

#11. PublicApplication 与 Edge Auth

该能力以现有 NSIO 已交付的 Public Application 与 Edge 认证实现为主要工程复用来源，不按“六种认证从零研发”估算。现网实现已经证明认证 handler、verifier、Envoy/NSGW 接入和 fail-closed 基础可行；Next 的新增工作是把这些成熟模块映射到以下 v1 对象、签名的 target-minimal projection、局部求值、统一会话撤销索引和 ServiceFlow 后端契约。Next 不继承旧线格式或数据库对象，复用模块仍须通过新的跨进程 fixture，现网测试证据不能替代 Next 集成证据。

工程拆分必须保持以下边界：

因此 Edge 方法矩阵本身不是本阶段最高风险的新协议；Relay、ServiceFlow 和 L3 candidate/roaming 仍先固定线格式。Edge 开工可以并行复用成熟实现，但只有对象、投影、会话和后端数据链全部接通后，Public Ingress 才算闭环。

#11.1 三个权威对象

PublicApplication:
  application_id, service_id, host, path_match, methods,
  tls_policy, region, request_limits, status, revision
EdgeAuthPolicy:
  edge_policy_id, application_id, ordered rules, auth_methods,
  session_policy, default=deny, kernel/evaluator version, revision
IngressBinding:
  binding_id, application_id, gateway_activation_id,
  service_id, endpoint selector, status, revision

Application=draft|validating|active|suspended|retired，Binding=pending|staging|active|draining|revoked|failed。DNS ownership、certificate、policy、Binding projection、gateway runtime 和 backend availability 是独立轴；其中任何一个失败都不能改写其它对象状态。PublicApplication 只能引用已存在 Service，API 拒绝任意 backend IP/port。

#11.2 六种认证材料

未知 method、缺少必需 verifier、过期 JWKS/CRL 无 last-valid 或 policy revision 不匹配时，NSGW 返回 edge_auth_configuration_unavailable/503；不能回落 Anonymous。API Key、OAuth client secret 和 signing private key 只在创建/轮换时展示或通过 secret provider 引用，普通配置 projection 不带明文。

#11.3 OIDC 与 Edge session

1. 未认证请求生成随机 state/nonce/PKCE verifier，保存 application、原始相对 URL、policy revision、created/expires；return URL 必须同 application host 且只允许相对路径；
2. callback 校验 state 单次消费、issuer、签名、audience、nonce、时间和 connector claims mapping；开放重定向或缺 verified subject 立即拒绝；
3. NSGW 使用本地已验签 EdgeAuthPolicy 对规范化 EdgeIdentity、request、assurance 和 context 求值，不逐请求调用 NSD；
4. allow 后签发 EdgeSessionCredential：session ID、application、edge identity、IdP session、policy revision、assurance、issued/expiry、credential ID；cookie 为 Secure+HttpOnly+SameSite，作用域限定 application host/path；
5. 每次请求重新校验 application/policy/session 状态和 method/path；session 不是 Network Membership，不能交换为控制 API 或 ServiceFlow 的普通 membership credential；
6. logout 只撤 Edge session；IdP/back-channel logout、identity/credential revoke 和 policy 收紧通过 session index 精确终止。

#11.4 创建、轮换与 API

API 最小集合：

创建/变更流程为 impact preview → AdminRoleBinding/step-up → Entitlement/CapabilityActivation → DNS ownership/certificate/verifier validation → Binding staging/health → atomic active → DNS enable。首次失败不发布 DNS；更新失败保留未过期旧 revision。API Key/signing key/IdP secret 轮换使用 prepared/dual-valid/activate/retire，有界重叠不允许跨 application。

NSGW 获得 target-minimal policy/verifier/secret references 和撤销索引，不获得租户完整用户目录。访问后端使用 IngressBackendCredential 与 Service publisher projection，详见数据面协议 §8.3。

#12. 稳定错误

#13. 审计、通知和完成门

每个对象必须记录 actor/proof/assurance、before/after revision、Policy/provenance、approval、quota、projection operation、result/error 和 request ID。审批待办、即将过期、撤销和 provider 故障产生 durable notification intent；通知失败不回滚权威事务。

完成需要：

1. 每个状态机穷尽状态/转移测试，非法转移反向失败；
2. API create/read/update/suspend/revoke/delete/impact 与 AdminRoleBinding 精确集合；
3. evaluation_error/read_failed 不被折叠为 deny/empty；
4. Capability auto approval 与人工批准占用相同 quota/audit；
5. AccessRequest 临时 Grant 到期/撤销走生产增量编译；
6. Machine token 跨 audience/resource 重放失败；
7. Posture provider 断线、stale、noncompliant 三态可区分；
8. Publication 远端请求不能突破 LocalManifest/ManagedConfigAuthorization；
9. 两个独立 NSD 完成 Share accept、访问、断线过期和双边 revoke，不交换目录；
10. key rotation 任一阶段崩溃可恢复，不出现两端各认不同 active key；
11. 全部真实 serializer 对共享 schema，未知 major/缺 required/跨 tenant ID 必须失败。
12. Edge 六种认证分别通过正常、过期、跨 application 重放、verifier read failure、轮换和定向长会话撤销；Anonymous 不得绕过 TLS/WAF/rate/audit。