nekonest-cloud/docs/implementation-plan.md

NekoNest Cloud 共享 Relay 实施状态

已完成：控制面契约

• 复用账号、entitlement、pairing 和原子主机席位逻辑。
• 注册响应改为同一端点的 ready|provisioning，移除 activation poll 与 relay URL。
• D1 增加 region、node、placement、authorization revision、签名公钥元数据与节点凭证摘要。
• D1 增加 60 秒单次 PWA handoff、routing-only handle 与 phone credential 摘要；phone principal/token 明确留在目标 Relay Engine。
• Dashboard 创建 fragment handoff；目标 Relay 节点通过内部 consume/complete API 同步 Engine，且不创建 device grant。
• 内部 API 只接受 mTLS 终止层注入的短时可信断言，并绑定 D1 中节点、SPIFFE、证书指纹、有效期与撤销状态；无共享 bearer。
• 规范 JSON + WebCrypto Ed25519 签名快照，TTL 上限 5 分钟。
• claim/revoke 成功才推进租户 authorization revision。
• 通用 API 错误包含 error_code/message/retryable 和可选重试/action 字段。
• 数据模型不保存 prompt、session、attachment 明文或签名私钥。
• D1 schema 完整对齐的控制平面数据清单，并覆盖 handoff ticket 的 24 小时保留清理。
• 空、加载、失败、离线、待核实和无资格状态均有明确恢复动作。
• 配对页自动确认认领、过期、锁定或取消，并立即清除一次性页面状态。
• 管理员后台即时汇总启用主机的控制面签到，但不冒充 Relay 在线状态。

已完成：单区域 Relay 代码路径

• 私有 Go Cloud Relay 引用精确版本 Relay Core，不提交本地 replace。
• TenantEngineRegistry：每租户唯一 Engine、独立 SQLite/附件目录、路径与符号链接防护。
• 同一 device_id 并发采用 reject_new。
• 稳定 Connect origin 的 WSS/REST/附件路由。
• mTLS 终止层与可信头剥离部署实证、节点 bootstrap/轮换、KMS 私钥加载。
• PWA 用 handoff response 保存独立 phone token，并继续逐设备 E2E 配对。
• 一席位/两席位、撤销、重启、附件、Push、重连端到端验证。

已完成：区域与生命周期代码路径

• home-region pinning、实时 placement 解析与认证内部 HTTPS/WSS 转发；客户端不重定向。
• quiesce/copy/switch/drain 迁移与 generation fencing；切换后不回滚到落后的源节点。
• 每租户 SQLite/附件备份、逐文件校验、幂等恢复与切换前回滚。
• 注销 Purge 覆盖 Engine 数据、附件、全部租户备份、device/phone/route/handoff 凭据与注册重放密文。

待完成：真实基础设施与运营证据

• 两区域共享备份传输层、mTLS 终止层、头剥离和真实迁移/回滚/Purge 演练。
• 容量、heartbeat、快照刷新与撤销延迟告警。
• 真实 relay 接通后采集重连成功率、Relay 延迟、资源成本和实际支持工时。
• 最终账户身份清除、防重建、法定保留例外与云存储物理生命周期政策。

验收重点

• 第 N+1 台主机被拒；撤销释放席位并推进 revision。
• ticket 过期、重放、错误 origin 均失败；URL fragment 在 PWA 网络请求前清除。
• 新连接在控制面故障时立即失败；已有连接最迟在 5 分钟快照过期时关闭。
• 任意跨租户 device、phone、route handle、history、attachment、key package 均不能越权。
• 区域迁移中永远只有一个 generation 的一个可写 Engine。

Worker 只承载控制面；WSS 与数据面由 Go Relay 承载。旧 provisioner、公开 activation 注册路径、管理员执行入口及相关运行时类型已删除；历史 migration 仅用于安全升级旧 D1。

Daemon 下载仍使用 fail-closed 发布清单；Windows 发布者代码签名尚未完成，仍属于扩大公测前门禁。 公开下载未就绪时，只允许已经取得并核验兼容闭测构建的参与者继续配对。