NekoNest Cloud 状态模型

账号、租户与席位

一个 Cloud 账号拥有一个 tenant_instances 记录。
一个 active 且 slot_state=active 的主机占一个席位，在线与否不改变计数。
未过期的 waiting pairing 只预留容量；取消、过期或成功 claim 后释放预留。
pairing 创建与 claim 都在写入 SQL 内复核容量。第 N+1 台返回 device_capacity_exceeded。
账户所有者可以轮询自己创建的配对状态，但不能读取其他账户的请求。
等待中的请求可由所有者取消；若 daemon 已先认领，则取消失败，不能撤销已提交的设备凭据。
主机撤销将主机标记为 deactivated、撤销所有设备凭证、释放席位，并推进 authorization revision。
同一身份恢复复用原 host ID；不能因复制公开指纹而获得第二个身份。

席位允许设备成为租户成员，不自动授权任何手机读取该设备。

Placement

tenant_placements 是共享 Relay 的部署权威：

home_region_id 固定租户主区域；
relay_node_id 指向当前唯一可写节点；
generation 只能单调增加；
state 首版使用 provisioning|active|quiescing|copying|switching|draining|failed。

客户端只看到稳定 Connect origin。provisioning 时在同一地址重试，不得到后端节点 URL。

授权 revision

每个租户有一条 tenant_authorization_state：

status=active|suspended；
revision 在成功 claim、主机撤销、手机撤销或租户暂停时单调增加；
变更只有在相应设备/主机写入已经成功时才推进，避免未提交操作造成虚假撤销。

Relay 获取最长 5 分钟的签名快照，每 60 秒完整刷新、默认每 5 秒检查 revision（delta 与随后的完整刷新各限制为 3 秒）。控制面不可达时不建立新 principal；现有连接最多存活到快照到期。

节点与签名密钥

节点状态为 provisioning|active|draining|offline|retired。heartbeat 只接受非回退 generation。节点以 D1 中未撤销、未过期的 SPIFFE ID 与证书 SHA-256 指纹记录为身份。所有内部调用必须先通过受信 mTLS 终止层注入绑定 method/path 的短时 HMAC assertion；控制面不要求共享 bearer。

Ed25519 私钥不进入 D1。relay_signing_keys 只保存 public JWK、private_key_ref、kid、有效期与状态。签名密钥必须至少有效到新快照的 expires_at；轮换重叠必须长于 5 分钟最大快照 TTL，旧 public JWK 也必须保留超过最后一份旧 key 快照的 TTL，保证验证窗口不断裂。

Phone handoff

phone_handoff_tickets 生命周期：issued → consumed 或 issued → expired。ticket：

随机 256 bit；
D1 只保存 SHA-256 摘要；
绑定账号、租户、精确 PWA origin；
60 秒有效；
条件 UPDATE 原子消费一次。

控制面只允许目标 placement 节点原子消费 ticket，并向该节点返回 tenant 与手机公钥。目标 Relay Engine 创建独立 phone principal/token 后，把 routing-only handle 摘要登记回来。控制面不生成或保存 phone token。该流程不创建 device grant；route handle 只负责解析 tenant placement，不能替代 phone token。

每次 phone WS/REST 入口都必须同时校验 route handle 摘要与 phone token 摘要，并要求两者绑定同一未撤销 phone principal 和 tenant；单独持有 route handle 不构成授权。已消费或已过期 ticket 只短暂保留摘要和公开身份字段用于防重放诊断，24 小时后由维护任务删除；D1 从未保存明文 ticket。

数据边界

D1 保存账号、权益、主机身份元数据、凭证摘要、placement、授权 revision、公钥、ticket/route 摘要和审计。新增表不得出现 prompt、session、attachment 明文或私钥。

控制面 last_used_at 只证明设备凭证最近成功通过授权，不证明租户 relay、WebSocket、Relay Engine 或本地 Agent 在线。

遗留 grace_days 不参与资格、设备认证或页面判断。

加载、离线和页面失败是客户端展示状态，不得改写控制面 placement、授权或主机身份事实。

4.1 KiB Raw Permalink Blame History Unescape Escape