2026-08-10 07:01:36 +08:00
|
|
|
|
# HoloLake 节点登记与验证来源契约 · 2026-08-10
|
|
|
|
|
|
|
|
|
|
|
|
> 阶段：`DEV-20260809-007 / NODE-REGISTRATION-CONTRACT-001`
|
|
|
|
|
|
>
|
|
|
|
|
|
> 上游：`HLP-CURRENT-ARCH-001` 第 5 节“节点与登录协议”
|
|
|
|
|
|
>
|
|
|
|
|
|
> 状态：`IMPLEMENTATION_STAGE_ACCEPTANCE_BASELINE`
|
|
|
|
|
|
|
|
|
|
|
|
## 验收标准
|
|
|
|
|
|
|
|
|
|
|
|
1. 账号验证源只能返回账号身份与用户选择的节点编号，不能直接声明节点已经登记。
|
|
|
|
|
|
2. HoloLake 只读取 REPO-012 当前公共锚点同一提交声明的
|
|
|
|
|
|
`GH-AIOS-NODE-REGISTRATION-ENDPOINTS-001`；任意本地配置、账号响应或未登记 URL 都不能成为
|
|
|
|
|
|
节点登记权威。
|
|
|
|
|
|
3. 节点登记声明使用 Ed25519 签名，并精确绑定账号、域、节点编号、节点类型、节点公钥
|
|
|
|
|
|
SHA-256 指纹、登记端点、签发者、签发时间与过期时间。
|
|
|
|
|
|
4. 注册表缺失、来源降级、端点撤销、端点范围不匹配、声明过期、未知字段、签名错误或任一
|
|
|
|
|
|
绑定字段不匹配时，`nodeRegistrationVerified` 必须保持 `false`，且不得请求域运行体交接。
|
|
|
|
|
|
5. 当前 REPO-012 锚点尚未登记此端点注册表，因此当前生产判断必须是
|
|
|
|
|
|
`NODE_REGISTRATION_NOT_EXISTS_0`；本阶段代码完成不得冒充生产登记服务、节点密钥证明、
|
|
|
|
|
|
域会话或在线运行已经存在。
|
|
|
|
|
|
|
|
|
|
|
|
## 注册表契约
|
|
|
|
|
|
|
|
|
|
|
|
注册表固定路径为 `routing/node-registration-endpoints.json`，由公共锚点的
|
|
|
|
|
|
`maps.node_registration_endpoints` 指向。每个端点声明：
|
|
|
|
|
|
|
|
|
|
|
|
- `endpointId`、`signerId`、`Ed25519 publicKeyPem`；
|
|
|
|
|
|
- HTTPS `guanghulab.com/api/ai/v1/...` 端点；
|
|
|
|
|
|
- 允许的 `domainIds` 与 `local-terminal / cloud-resident` 节点类型；
|
|
|
|
|
|
- `ACTIVE / REVOKED` 状态。
|
|
|
|
|
|
|
|
|
|
|
|
同一域与节点类型不得存在两个活跃端点，避免客户端自行猜测权威。
|
|
|
|
|
|
|
|
|
|
|
|
## 登记声明契约
|
|
|
|
|
|
|
|
|
|
|
|
`gh-aios.node-registration-claim/v1` 只表达灯塔登记服务已经验证的账号—节点—公钥绑定。
|
|
|
|
|
|
声明最长有效 24 小时，必须周期刷新。它不代替后续登录挑战中的实时节点私钥持有证明，也不
|
|
|
|
|
|
代替域成员权限、短期会话能力、签名域清单和在线连接回执。
|
|
|
|
|
|
|
|
|
|
|
|
## 当前现实边界
|
|
|
|
|
|
|
|
|
|
|
|
- 当前公共锚点没有 `maps.node_registration_endpoints`；
|
|
|
|
|
|
- 当前桌面没有可调用的登记声明端点；
|
|
|
|
|
|
- 当前没有生产节点登记签发公钥、登记声明或节点密钥挑战回执；
|
|
|
|
|
|
- 因而 Forgejo 账号验证以后仍停留在“需要节点登记”，这是正确的失败关闭结果。
|
2026-08-10 07:28:11 +08:00
|
|
|
|
|
|
|
|
|
|
## 登记声明读取传输 · 阶段 002
|
|
|
|
|
|
|
|
|
|
|
|
登记声明读取不是“创建节点登记”，也不携带账号密码、访问令牌、验证码或节点私钥。客户端
|
|
|
|
|
|
只在当前锚点注册表为 `CURRENT` 且解析出唯一活跃端点后，向该端点发送固定结构的无凭据
|
|
|
|
|
|
`POST`：账号标识、域、节点编号、节点类型、端点编号、一次性请求编号与签发时间。
|
|
|
|
|
|
|
|
|
|
|
|
传输必须同时满足：禁止重定向、5 秒超时、`application/json`、响应不超过 64 KiB、响应
|
|
|
|
|
|
请求编号与原请求一致。响应只允许 `ISSUED + claim` 或 `NOT_FOUND + null`；前者仍必须经过
|
|
|
|
|
|
阶段 001 的 Ed25519 声明验证，后者不能升级任何权限。HTTP 错误、未知字段、超限、绑定不
|
|
|
|
|
|
一致及解析失败全部关闭为“未验证节点登记”，并且不触发运行体交接。
|
|
|
|
|
|
|
|
|
|
|
|
当前公共锚点仍未登记端点，所以该传输在生产运行中不可达，也不会发出请求；实现存在不等于
|
|
|
|
|
|
端点服务、节点登记或域运行体已经存在。
|
2026-08-10 08:00:53 +08:00
|
|
|
|
|
|
|
|
|
|
## 节点私钥持有证明 · 阶段 003
|
|
|
|
|
|
|
|
|
|
|
|
签名登记声明只证明灯塔曾登记“节点编号—节点公钥指纹”，不能证明当前发起登录的终端此刻
|
|
|
|
|
|
仍持有对应私钥。HoloLake 必须在声明验证以后创建一次性
|
|
|
|
|
|
`gh-aios.node-possession-challenge/v1`：精确绑定账号、登记声明、域、节点编号、节点类型、
|
|
|
|
|
|
公钥指纹、随机 256 位 nonce、挑战编号、签发时间与到期时间；有效期最多 60 秒且不得超过
|
|
|
|
|
|
登记声明自身到期时间。
|
|
|
|
|
|
|
|
|
|
|
|
节点返回 `gh-aios.node-possession-response/v1`，只包含挑战编号、Ed25519 公钥和对完整挑战
|
|
|
|
|
|
规范字节的签名。验证器必须确认：
|
|
|
|
|
|
|
|
|
|
|
|
1. 挑战确由当前 HoloLake 进程创建，调用方复制相同字段不能伪造来源；
|
|
|
|
|
|
2. 响应公钥的 SPKI DER SHA-256 与签名登记声明中的 `nodeKeyFingerprint` 完全一致；
|
|
|
|
|
|
3. Ed25519 签名、挑战编号、账号、声明、域、节点、类型、nonce 和有效期全部匹配；
|
|
|
|
|
|
4. 未知字段、错误公钥、过期挑战、跨挑战重放、复制的登记对象或任一解析错误全部失败关闭。
|
|
|
|
|
|
|
|
|
|
|
|
只有“账号验证 + 签名节点登记 + 当前节点私钥持有证明”三者同时成立，客户端才允许请求域
|
|
|
|
|
|
运行体交接。当前桌面尚无生产节点密钥库桥，正式运行源固定返回无证明，因此即使未来出现一份
|
|
|
|
|
|
有效登记声明，也不能越过 `verified_node_possession_missing`。代码验证器存在不等于节点密钥、
|
|
|
|
|
|
生产密钥库桥、灯塔会话签发或域连接已经存在。
|
2026-08-10 08:25:34 +08:00
|
|
|
|
|
|
|
|
|
|
## 私钥证明到域交接的证据链 · 阶段 004
|
|
|
|
|
|
|
|
|
|
|
|
本地布尔值 `nodePossessionVerified=true` 不能作为灯塔签发域会话的请求证据。节点证明验证器
|
|
|
|
|
|
现在生成进程内不可伪造的 `VerifiedNodePossession`：包含已验证登记声明、一次性挑战、节点
|
|
|
|
|
|
签名响应和验证时间，并通过内部来源集合阻止调用方复制字段冒充验证结果。
|
|
|
|
|
|
|
|
|
|
|
|
域运行体交接源只接受这个验证对象，并构造固定
|
|
|
|
|
|
`gh-aios.domain-runtime-handoff-request/v1` 请求包：账号、域、节点编号、节点类型、完整签名
|
|
|
|
|
|
登记声明、挑战、节点响应、一次性请求编号和请求时间。它不包含账号密码、访问令牌、验证码
|
|
|
|
|
|
或节点私钥。每份节点证明最多发起一次交接请求；失败重试必须重新完成新挑战，不能重放旧证明。
|
|
|
|
|
|
|
|
|
|
|
|
响应固定为 `gh-aios.domain-runtime-handoff-response/v1`，并必须回绑请求编号。只允许
|
|
|
|
|
|
`ISSUED + handoff + signer_lookup` 或 `NOT_AUTHORIZED + null + null`。客户端仍须使用当前
|
|
|
|
|
|
REPO-012 信任快照独立验证 handoff 中的域清单签名、短期会话能力和在线连接回执；服务端
|
|
|
|
|
|
返回的 signer 名称、公钥字段或自授权布尔值都不能成为信任来源。
|
|
|
|
|
|
|
|
|
|
|
|
本阶段闭合的是“证明能够被带到交接边界”的客户端证据结构，不是生产 HTTP 端点。当前公共
|
|
|
|
|
|
锚点没有域交接端点注册表，桌面运行源仍返回空结果，因此生产会话签发、域运行体连接与在线
|
|
|
|
|
|
回执继续为 `NOT_EXISTS_0`。
|
2026-08-10 09:04:58 +08:00
|
|
|
|
|
|
|
|
|
|
## 域运行体交接端点锚定与严格传输 · 阶段 005
|
|
|
|
|
|
|
|
|
|
|
|
本阶段先固定以下验收标准，再进入实现：
|
|
|
|
|
|
|
|
|
|
|
|
1. 域交接 URL 只能来自 REPO-012 当前公共锚点同一提交声明的
|
|
|
|
|
|
`GH-AIOS-DOMAIN-RUNTIME-HANDOFF-ENDPOINTS-001`，账号响应、调用方参数、本地配置和复制对象
|
|
|
|
|
|
都不能指定或替换 URL。
|
|
|
|
|
|
2. 注册表只允许无凭据的 `https://guanghulab.com/api/ai/v1/...` 端点；禁止端口、用户名、密码、
|
|
|
|
|
|
查询串、片段和重定向。同一域与节点类型最多一个活跃端点。
|
|
|
|
|
|
3. 只有来源状态为 `CURRENT` 的已登记快照和已登记端点才能发起请求；注册表缺失、来源降级、
|
|
|
|
|
|
范围不匹配、端点撤销或调用方伪造对象时必须在网络请求前失败关闭。
|
|
|
|
|
|
4. 交接传输固定为无凭据 `POST application/json`，5 秒超时、`redirect=manual`、
|
|
|
|
|
|
`credentials=omit`、`cache=no-store`、`referrerPolicy=no-referrer`；响应必须是 JSON 且不超过
|
|
|
|
|
|
256 KiB。HTTP 错误、重定向、非 JSON、超限和响应绑定错误均返回空结果。
|
|
|
|
|
|
5. 请求包必须增加并绑定 `endpointId`，已验证节点证明只有在解析到当前活跃端点后才被消耗，
|
|
|
|
|
|
且一次证明仍最多发起一次网络请求。
|
|
|
|
|
|
6. 当前公共锚点尚未登记域交接端点映射，生产桌面必须不发送交接请求并继续返回
|
|
|
|
|
|
`NOT_EXISTS_0`；代码完成不得冒充生产端点、会话签发、域运行体连接或在线健康已经存在。
|
