Skip to content

Device revoke OTA: setup firmware channel + admin-signed notice - #16

Open
JamesSmartCell wants to merge 2 commits into
masterfrom
cursor/device-revoke-ota-dfce
Open

JamesSmartCell wants to merge 2 commits into
masterfrom
cursor/device-revoke-ota-dfce

Conversation

@JamesSmartCell

Copy link
Copy Markdown
Owner

Summary

Proxy-side REVOCATION: an admin can revoke a device by address so it OTA-installs the project's setup firmware and reboots into the provisioning portal (stay_portal=1 per Web3E-Setup-Firmware#3).

Aligned with setup firmware: setup stays in the portal and typically does not TCP-login, so telemetry completion is device ack (revoking) and/or app re-appearance after portal Done — not a setup-firmware login.

Door firmware PR was not open yet when this landed; notice format below is the contract for NFT-Gated-ESP-Control.

Exact revoke notice format (firmware agents)

Same transport as OTA notify: TCP opcode 0x04, method updateReady.

Normal OTA Revoke
method updateReady updateReady
args (none) see below
device response checking / rate_limited revoking (required before OTA)

Revoke args (length-prefixed key/value):

Key Value
purpose revoke
version setup plain semver
sha256 setup SHA-256 hex (64 chars)
size setup size (decimal string)
message revoke:<project>:<device>:<sha256>:<nonce>
signature EIP-191 personal_sign of message by an admin key
  • <device> = lowercase 0x-prefixed KeyID address
  • <sha256> in message = setup binary hash
  • URL is not on the wire (255-byte limit). After verifying signature, device GET /api/firmware/<project>/setup, confirm metadata matches notice, download url, verify SHA-256, set NVS web3e_boot/stay_portal=1, flash setup, reboot.

Endpoints / CLI

Action HTTP CLI
Upload setup firmware POST /api/firmware/:project/setup — message setup-firmware:<project>:<version>:<sha256>:<nonce> npm run firmware:upload-setup <project> <version> <bin>
Get setup metadata GET /api/firmware/:project/setup —
Revoke device POST /api/firmware/:project/revoke — message revoke:<project>:<device>:<setupSha256>:<nonce> npm run firmware:revoke <project> <device>
Cancel revoke POST /api/firmware/:project/revoke/cancel — message revoke-cancel:<project>:<device>:<nonce> npm run firmware:revoke:cancel <project> <device>
List revokes GET /api/firmware/:project/revokes —

Setup firmware is stored under firmware/<project>/setup/<version>/firmware.bin and never becomes app /latest. Same admin auth / R2 env as existing firmware upload (no secrets committed).

Queueing behaviour

  1. Revoke accepted → firmware_revoke_requested; notice stored
  2. Online → send notice immediately → delivered / firmware_revoke_delivered
  3. Offline → pending; delivered on next TCP login
  4. Device replies revoking → acknowledged / firmware_revoke_acknowledged
  5. Disconnect after delivery/ack noted (OTA reboot)
  6. App firmware TCP-logs in again (after ack, or after post-delivery disconnect) → completed / firmware_revoke_completed
  7. Cancel → cancelled / firmware_revoke_cancelled (stops delivery)

Full detail: docs/firmware-ota.md.

Tests

  • npm test — 281 passing (includes new firmware-revoke.test.ts)
  • npm run typecheck:tools — clean
Open in Web Open in Cursor 

cursoragent and others added 2 commits November 19, 2026 21:39
Admins can upload per-project setup firmware (distinct from app latest),
revoke a device with an admin-signed updateReady(purpose=revoke) notice,
queue delivery for offline devices, and cancel pending revokes. Telemetry
tracks requested/delivered/acknowledged/completed outcomes aligned with
setup stay_portal (ack before OTA; app reappear after portal Done).

Co-authored-by: James Brown <[email protected]>
Avoid comparing active.status to 'acknowledged' after it was
already excluded by a prior equality check (TS2367).

Co-authored-by: James Brown <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants