hololake-system-architecture/product-source/hololake-platform/architecture/HOLOLAKE-NODE-KEYSTORE-BRIDGE-CONTRACT-20260810.md

HoloLake 节点密钥库桥契约 · 2026-08-10

阶段：DEV-20260809-007 / NODE-KEYSTORE-BRIDGE-001

上游：HOLOLAKE-NODE-REGISTRATION-CONTRACT-20260810 阶段 003

状态：IMPLEMENTATION_STAGE_ACCEPTANCE_BASELINE

验收标准

1. 正式域登录只读取本机明确登记的节点密钥记录；记录缺失、加密存储不可用、解密失败、 字段不完整或任一绑定不一致时返回无证明，禁止自动生成或自动登记生产节点身份。
2. 节点密钥记录必须精确绑定 nodeId、nodeType、Ed25519 公钥与其 SPKI DER SHA-256 指纹；挑战中的节点编号、类型和指纹必须与记录完全一致。
3. 私钥以 PKCS#8 DER 形式进入签名边界，只允许 Ed25519；实现必须从私钥重新导出公钥并 核对登记指纹，签名结束后立即覆写临时私钥字节。
4. 桥对外只能返回 gh-aios.node-possession-response/v1 的挑战编号、公钥和签名；不得返回 私钥、解密结果、加密载荷、密钥路径或底层错误细节。
5. 未知字段、复制的挑战对象、过期挑战、节点绑定错误、公私钥不配对、无效 Base64、错误 密钥类型及签名异常全部失败关闭为 null，不得抛出秘密相关错误进入产品投影。
6. Electron 适配层只在密钥记录已经存在时读取；当前阶段不得创建真实生产密钥文件、不得 发起钥匙串或隐私确认，也不得把测试密钥安装到桌面数据目录。
7. 当前正式数据目录没有已登记节点密钥记录，因此本阶段完成后的生产判断仍为 NODE_KEYSTORE_BRIDGE_NOT_ENROLLED_0；代码可运行不等于生产节点身份、灯塔登记、域会话或 运行体连接已经存在。

本地记录边界

记录 schema 固定为 gh-aios.node-keystore-record/v1，只允许：

• nodeId、nodeType；
• nodeKeyFingerprint、publicKeyPem；
• encryptedPrivateKeyPkcs8；
• schema。

加密私钥字段由宿主安全存储保护，明文是严格 Base64 的 PKCS#8 DER。记录文件本身必须以 0600 权限保存，但本阶段只实现已有记录的读取与证明，不实现登记写入。

当前现实边界

• 当前公共锚点仍没有节点登记端点与域运行体交接端点映射；
• 当前桌面没有本阶段 schema 的生产节点密钥记录；
• 当前没有生产节点登记声明、节点证明、域会话能力或在线连接回执；
• 因而域入口继续停留在登录/登记门，这是正确的失败关闭结果。