📦 OCMAP Pairing Auth — 一次性配对码认证

# OCMAP 配对认证 在 OpenClaw 现有的签名设备身份与可信设备令牌流程之上，实现一层轻量的配对码功能。不要另建一套长期有效的认证体系。 ## 工作流程 1. 先阅读 references/protocol.md。 2. 若开发 OpenClaw 网关或 Control UI，阅读 references/server-openclaw.md。 3. 若开发 OCMAP 或其他桌面客户端，阅读 references/client-ocmap.md。 4. 在连接 UI 之前，确保服务端与客户端对请求/响应契约完全一致。 ## 必要设计 - 服务端生成一次性的短时配对码。 - 在调用 pairing.createCode 时同时生成一个短时 bootstrap auth 值。 - 遵循 OpenClaw 的“先连接”规则： - 客户端必须在 connect.auth 中先发送 bootstrap 值 - 正常完成握手 - 然后才能调用 pairing.exchangeCode - 将兑换与设备身份凭证绑定： - deviceId - publicKey - signature - signedAt - nonce - 成功后，走正常的 OpenClaw 可信设备令牌路径（新建或复用）。 - 在客户端的渲染进程之外持久化信任凭据。 - 服务端支持撤销，客户端支持遗忘设备。 - 返回结构化错误码，而非通用失败信息。 ## 不可协商的规则 - 配对码必须短时：2–5 分钟。 - bootstrap auth 值同样短时。 - 配对码一次性使用。 - 对失败的兑换尝试做速率限制。 - 绝不在渲染器/浏览器 UI 状态中暴露长期可信令牌。 - 成功兑换后无需人工确认；兑换本身即视为确认。 - 不得绕过 OpenClaw 现有设备令牌验证模型；只能扩展。 - 不得为了配对而绕过 OpenClaw 的“先连接”握手规则。 ## OpenClaw 实现清单 - 新增网关方法： - pairing.createCode - pairing.exchangeCode - pairing.revokeDevice - pairing.createCode 返回 code、nonce 及短时 bootstrap auth。 - 将配对码状态与通用设备待配对/已配对记录分开存储。 - 在 Control UI 的 Integrations 下新增 Clawpodz 配对标签页，展示最近配对与可信桌面客户端。 - 通用已配对设备/节点/执行授权仍保留在 Devices 标签页。 - 通过特性开关或配置控制灰度发布。 - 返回结构化失败码，例如： - PAIRING_DISABLED - CODE_INVALID - CODE_EXPIRED - CODE_ALREADY_USED - DEVICE_REVOKED ## 客户端实现清单 - 在 connect.auth 中使用返回的 bootstrap auth，以满足“先连接”握手。 - 先打开 websocket 并完成网关握手，再发起配对兑换。 - 提交完整签名载荷；仅 code + deviceId 不足。 - 兑换成功后，将返回的可信设备令牌持久化到主进程/后端存储。 - 后续使用已存令牌重连，并平滑切换认证状态。 - 区分 UNPAIRED、PAIRING_IN_PROGRESS、PAIRED_CONNECTED、PAIRED_DISCONNECTED、REVOKED。 ## 验证 在功能完成前运行以下矩阵： - 使用全新有效码配对成功。 - 复用同一码失败，返回 CODE_ALREADY_USED。 - 过期码失败，返回 CODE_EXPIRED。 - 签名/公钥/设备不匹配失败，返回 CODE_INVALID。 - 成功后重启客户端可自动重连。 - 在服务端撤销设备后，客户端回到未配对/已撤销流程。 - 网关重启不丢失可信设备记录。 ## 参考资料 - 服务端细节：references/server-openclaw.md - 客户端细节：references/client-ocmap.md - 协议契约：references/protocol.md