Skill: maverick-software/ocmap-pairing-auth (version 1.1.0)

--- name: ocmap-pairing-auth description: Implement one-time pairing-code authentication between an OpenClaw gateway and a desktop or remote client such as OCMAP. Use when adding or updating pairing.createCode / pairing.exchangeCode / pairing.revokeDevice, short-lived bootstrap auth for connect-first handshakes, trusted-device persistence, the OpenClaw Control UI Clawpodz tab, client-side signed device proof, or recovery/revocation flows for persistent trusted device enrollment. --- # OCMAP Pairing Auth Implement the feature as a thin pairing-code layer on top of OpenClaw's existing signed device identity and trusted-device token flow. Do not invent a second long-lived auth system. ## Workflow 1. Read `references/protocol.md` first. 2. If working on OpenClaw gateway or Control UI, read `references/server-openclaw.md`. 3. If working on OCMAP or another desktop client, read `references/client-ocmap.md`. 4. Keep server and client aligned on the exact request/response contract before wiring UI. ## Required design - Generate a short-lived one-time code on the server. - Also mint a short-lived bootstrap auth value during `pairing.createCode`. - Preserve OpenClaw's connect-first rule: - client must send the bootstrap value during `connect.auth` - complete handshake normally - only then call `pairing.exchangeCode` - Bind exchange to a device identity proof: - `deviceId` - `publicKey` - `signature` - `signedAt` - `nonce` - On success, mint or reuse the normal OpenClaw trusted-device token path. - Persist trust on the client outside the renderer/UI process. - Support revoke on the server and forget-device on the client. - Return structured error codes instead of generic failures. ## Non-negotiable rules - Keep pairing codes short-lived: 2-5 minutes. - Make bootstrap auth values short-lived as well. - Make codes single-use. - Rate-limit failed exchange attempts. - Never expose the long-lived trusted token in renderer/browser UI state. - Do not require manual approval after a successful code exchange; the code exchange is the approval. - Do not bypass OpenClaw's existing device token verification model; extend it. - Do not bypass OpenClaw's connect-first handshake rule just to make pairing work. ## OpenClaw implementation checklist - Add gateway methods: - `pairing.createCode` - `pairing.exchangeCode` - `pairing.revokeDevice` - Return `code`, `nonce`, and short-lived bootstrap auth from `pairing.createCode`. - Store pairing-code state separately from generic device pending/paired records. - Surface Clawpodz pairing UI in its own Control UI tab under Integrations, with recent pairings and trusted desktop clients there. - Keep generic paired devices / nodes / exec approvals in the Devices tab. - Add feature-flag or config gating for rollout. - Return structured failure codes such as: - `PAIRING_DISABLED` - `CODE_INVALID` - `CODE_EXPIRED` - `CODE_ALREADY_USED` - `DEVICE_REVOKED` ## Client implementation checklist - Use the returned bootstrap auth during `connect.auth` so the client can satisfy the connect-first handshake. - Open the websocket and complete the gateway handshake before attempting pairing exchange. - Submit the full signed payload; `code + deviceId` alone is insufficient. - After exchange, persist the returned trusted-device token in main/backend storage. - Reconnect using the stored token and transition auth state cleanly. - Distinguish `UNPAIRED`, `PAIRING_IN_PROGRESS`, `PAIRED_CONNECTED`, `PAIRED_DISCONNECTED`, and `REVOKED`. ## Validation Run this matrix before calling the feature done: - Fresh pair with valid code succeeds. - Reuse same code fails with `CODE_ALREADY_USED`. - Expired code fails with `CODE_EXPIRED`. - Invalid signature/public key/device mismatch fails with `CODE_INVALID`. - Restart client after success reconnects automatically. - Revoke device on server forces client back to unpaired/revoked flow. - Gateway restart does not lose trusted device records. ## References - Server details: `references/server-openclaw.md` - Client details: `references/client-ocmap.md` - Protocol contract: `references/protocol.md`


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)