diff --git a/README.md b/README.md index a91f74e..4a477b1 100644 --- a/README.md +++ b/README.md @@ -87,9 +87,14 @@ Admin-protected operations require a signed challenge. The flow: - For Zigbee ack: `zbgw-ack::` - For Zigbee command queue: `zbgw-cmd:::` (`restart` | `ota_check`) - For firmware upload: `firmware::::` + - For setup firmware upload: `setup-firmware::::` - For firmware rollback: `current:::` + - For device revoke: `revoke::::` + - For revoke cancel: `revoke-cancel:::` 3. Submit signature with request (nonce is single-use and burned after verification) +See [docs/firmware-ota.md](docs/firmware-ota.md) for OTA notify, setup firmware, and **device revocation** (notice format for firmware agents). + ### Zigbee Gateway Diagnostics Host-independent routes used by ESP32-C6 gateways (firmware `diag.c`). Devices may call diff --git a/docs/firmware-ota.md b/docs/firmware-ota.md index e38982c..3dc1706 100644 --- a/docs/firmware-ota.md +++ b/docs/firmware-ota.md @@ -81,7 +81,7 @@ The uploaded version is stored in the database and compared with device semver d ### GET /api/firmware/:project/latest -Get the latest firmware metadata for a project. +Get the latest **app** firmware metadata for a project. **Response:** ```json @@ -96,6 +96,10 @@ Get the latest firmware metadata for a project. This endpoint is called by devices to check for updates and download the firmware. +### GET /api/firmware/:project/setup + +Get the current **setup** (provisioning portal) firmware metadata for a project. Same JSON shape as `/latest`, plus `"channel": "setup"`. Distinct from app latest — used after a revoke notice. + ### POST /api/firmware/:project Upload a new firmware binary (admin authentication required). @@ -418,11 +422,147 @@ All firmware notifications are recorded as telemetry events with type `firmware_ These events can be queried through the telemetry API for monitoring and analysis. +## Device Revocation (REVOCATION) + +An admin can revoke a specific device by address. The proxy sends an **admin-signed revoke notice** over the existing OTA notify channel (TCP opcode `0x04` / `updateReady`). The device must OTA-install that project's **setup firmware** and reboot into the provisioning portal. + +### Setup firmware (distinct from app `latest`) + +Setup (provisioning portal) firmware is stored per project alongside app firmware in R2, but **never** becomes `/api/firmware/:project/latest`. + +| | App firmware | Setup firmware | +|---|---|---| +| GET metadata | `/api/firmware/:project/latest` | `/api/firmware/:project/setup` | +| Upload | `POST /api/firmware/:project` | `POST /api/firmware/:project/setup` | +| Signed message | `firmware::::` | `setup-firmware::::` | +| R2 key | `firmware///firmware.bin` | `firmware//setup//firmware.bin` | +| CLI | `npm run firmware:upload ...` | `npm run firmware:upload-setup ...` | + +**Post-revoke boot (setup firmware contract):** app sets NVS `web3e_boot` / `stay_portal=1` before OTA to setup. Setup stays in the captive portal until the user taps **Done**, then clears the flag and re-pulls app firmware. Setup typically does **not** TCP-login to the proxy while in the portal — do not rely on a setup-firmware login for telemetry. + +### Exact revoke notice format (for firmware agents) + +Transport is the **same** as OTA notify: TCP opcode `0x04`, method name `updateReady`, length-prefixed key/value args (Web3E `APIReturn` params). + +**Normal OTA notify (unchanged):** + +| Field | Value | +|---|---| +| method | `updateReady` | +| args | _(none)_ | +| device response | `checking` or `rate_limited` | + +**Revoke notice (extension):** + +| Field | Value | +|---|---| +| method | `updateReady` | +| `purpose` | `revoke` | +| `version` | setup firmware plain semver (e.g. `1.0.0`) | +| `sha256` | setup firmware SHA-256 hex (lowercase, 64 chars) | +| `size` | setup firmware size in bytes (decimal string) | +| `message` | `revoke::::` | +| `signature` | EIP-191 `personal_sign` of `message` by an `ADMIN_ADDRESSES` key | +| device response | `revoking` (required ack before OTA) | + +Notes: + +- `` is the lowercase `0x`-prefixed device address (the device's KeyID address). +- `` in `message` is the **setup** firmware hash (binds the notice to a specific binary). +- `` is a 64-char hex challenge from `GET /api/admin/challenge` (same admin auth flow as upload/notify). +- URL is **not** sent on the wire (255-byte arg limit). After verifying the signature, the device MUST `GET /api/firmware//setup`, confirm `sha256`/`size`/`version` match the notice, then download `url`, verify SHA-256, flash, and reboot. +- Devices MUST treat `purpose=revoke` as an instruction to install setup firmware **even if** that means replacing newer app firmware (revoke is not a semver upgrade). +- Devices SHOULD verify `signature` recovers an address in their local admin list before flashing. +- **App firmware sequence:** respond `revoking` → set NVS `web3e_boot`/`stay_portal=1` → OTA setup → reboot. (Aligned with [Web3E-Setup-Firmware#3](https://github.com/JamesSmartCell/Web3E-Setup-Firmware/pull/3).) + +### Admin HTTP API + +**POST `/api/firmware/:project/revoke`** + +```json +{ + "device": "0xaaa...", + "message": "revoke::::", + "signature": "0x..." +} +``` + +Response: + +```json +{ + "success": true, + "project": "garagedoor", + "device": "0xaaa...", + "status": "delivered", + "queued": false, + "setup": { "version": "1.0.0", "sha256": "...", "size": 12345, "url": "https://..." }, + "revokeId": 1, + "revokedBy": "0xadmin..." +} +``` + +- If the device is **online**, the notice is sent immediately (`status: delivered`). +- If the device is **offline**, the signed notice is queued (`status: pending`, `queued: true`) and delivered automatically on the device's next TCP login. +- A new revoke for the same device cancels any previous pending/delivered revoke. + +**POST `/api/firmware/:project/revoke/cancel`** + +```json +{ + "device": "0xaaa...", + "message": "revoke-cancel:::", + "signature": "0x..." +} +``` + +Cancels a pending or delivered-but-not-completed revoke so it will not be (re)delivered. + +**GET `/api/firmware/:project/revokes`** — list revoke records (`?device=`, `?status=`). + +### CLI + +```bash +# Upload setup firmware (does not change app latest) +npm run firmware:upload-setup garagedoor 1.0.0 setup-firmware.bin + +# Revoke a device (queues if offline) +npm run firmware:revoke garagedoor 0xaaa... + +# Cancel a pending revoke +npm run firmware:revoke:cancel garagedoor 0xaaa... +``` + +Requires the same `.env` as upload: `PROXY_BASE_URL`, `FIRMWARE_ADMIN_KEY`. + +### Queueing behaviour + +1. Admin calls revoke → proxy verifies signature, records `firmware_revoke_requested`, stores notice. +2. If connected → send `updateReady` args, mark `delivered`, record `firmware_revoke_delivered`. +3. If offline → leave `pending`; on next TCP auth (opcode `0x09`/`0x07`), deliver and mark `delivered`. +4. When the device responds to the API call with a body starting with `revoking`, mark `acknowledged` and record `firmware_revoke_acknowledged` (observable outcome **before** OTA). +5. Disconnect after delivery/ack is noted (expected when the device reboots into setup/portal). +6. When the **app** firmware later TCP-logs in again for the same project (after ack, or after a post-delivery disconnect), mark `completed` and record `firmware_revoke_completed`. Setup firmware usually does **not** appear on the TCP channel while `stay_portal=1`. +7. Cancel moves active revokes to `cancelled` (`firmware_revoke_cancelled`) and stops delivery. + +### Revoke telemetry events + +| `eventType` | When | +|---|---| +| `firmware_revoke_requested` | Admin revoke accepted | +| `firmware_revoke_delivered` | Notice written to device TCP channel | +| `firmware_revoke_acknowledged` | Device replied `revoking` (pre-OTA ack) | +| `firmware_revoke_completed` | App firmware re-appeared after revoke (post-portal re-provision) | +| `firmware_revoke_cancelled` | Admin cancelled pending/delivered/acknowledged revoke | + +`firmware_project` = app project; `firmware_notify_version` = setup version; `firmware_version` on completed = reported app login string. + ## Security -- All upload and notify operations require admin authentication (Ethereum signature) +- All upload, notify, setup-upload, and revoke operations require admin authentication (Ethereum signature) - Firmware binaries are uploaded to Cloudflare R2 with unique keys - Devices verify SHA256 checksums before flashing +- Revoke notices are admin-signed and bound to a specific setup SHA-256 - Legacy firmware is never automatically notified (prevents breaking old devices) ## Troubleshooting diff --git a/package.json b/package.json index 0da8ca0..86a79b3 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,10 @@ "telemetry:zigbee:pull": "ts-node tools/telemetry/pull-zigbee.ts", "telemetry:zigbee:analyse": "ts-node tools/telemetry/analyse-zigbee.ts", "telemetry:all": "ts-node tools/telemetry/all.ts", - "firmware:upload": "ts-node tools/firmware/upload.ts" + "firmware:upload": "ts-node tools/firmware/upload.ts", + "firmware:upload-setup": "ts-node tools/firmware/upload-setup.ts", + "firmware:revoke": "ts-node tools/firmware/revoke.ts", + "firmware:revoke:cancel": "ts-node tools/firmware/revoke.ts --cancel" }, "engines": { "node": ">=20.0.0" diff --git a/src/__tests__/firmware-api.test.ts b/src/__tests__/firmware-api.test.ts index e8f89c0..2c62e37 100644 --- a/src/__tests__/firmware-api.test.ts +++ b/src/__tests__/firmware-api.test.ts @@ -73,6 +73,10 @@ describe('Firmware API', () => { getDeviceAddress: async () => '', handleDeviceConnection: () => '', getLoginChallenge: () => '', + getConnectedDevices: () => [], + sendApiCallToDevice: async () => {}, + trySendApiCallToDevice: () => false, + deliverPendingRevoke: () => false, } as any; app.use('/api', createRouter(mockService, mockTcpService)); diff --git a/src/__tests__/firmware-revoke.test.ts b/src/__tests__/firmware-revoke.test.ts new file mode 100644 index 0000000..5f0c59f --- /dev/null +++ b/src/__tests__/firmware-revoke.test.ts @@ -0,0 +1,437 @@ +import { describe, it, expect, beforeEach, afterEach, beforeAll, afterAll, vi } from 'vitest'; +import express from 'express'; +import request from 'supertest'; +import { createRouter } from '../api/routes'; +import { ASyncService } from '../service/ASyncService'; +import { ASyncTCPService } from '../service/ASyncTCPService'; +import { + FirmwareService, + buildRevokeNoticeMessage, + normalizeDeviceAddress, + setupFirmwareProjectId, +} from '../service/FirmwareService'; +import { TelemetryService } from '../service/TelemetryService'; +import { AdminAuthService } from '../service/AdminAuthService'; +import { Wallet } from 'ethers'; +import { unlinkSync, existsSync } from 'fs'; + +const TEST_FIRMWARE_DB = './test-firmware-revoke.db'; +const TEST_TELEMETRY_DB = './test-telemetry-revoke.db'; +const ADMIN_PRIVATE_KEY = '0x0123456789012345678901234567890123456789012345678901234567890123'; +const DEVICE = '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'; + +describe('Firmware revoke helpers', () => { + it('builds revoke notice message with normalized device address', () => { + const msg = buildRevokeNoticeMessage( + 'garagedoor', + 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA', + 'abc123', + 'n'.repeat(64) + ); + expect(msg).toBe( + `revoke:garagedoor:0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:abc123:${'n'.repeat(64)}` + ); + }); + + it('builds setup firmware project id helper', () => { + expect(setupFirmwareProjectId('GarageDoor')).toBe('garagedoor-setup'); + }); +}); + +describe('Firmware Revoke API', () => { + let app: express.Application; + let adminWallet: Wallet; + let sentCalls: Array<{ address: string; method: string; args: any }>; + let connected: Array<{ address: string; project?: string; semver?: string; firmwareVersion?: string }>; + + beforeAll(() => { + vi.mock('../service/CloudflareR2', () => ({ + uploadToR2: vi.fn(async (key: string) => `https://example.r2.dev/${key}`), + uploadFirmwareToR2: vi.fn(async (_project: string, key: string) => `https://example.r2.dev/${key}`), + isR2Configured: vi.fn(() => true), + getFirmwareBucketName: vi.fn(() => 'test-bucket'), + getFirmwareStorageConfig: vi.fn(() => ({ + bucket: 'test-bucket', + publicUrl: 'https://example.r2.dev', + credentials: { accountId: 'a', accessKeyId: 'k', secretAccessKey: 's' }, + isDedicatedFirmwareBucket: true, + })), + })); + }); + + beforeEach(() => { + if (existsSync(TEST_FIRMWARE_DB)) unlinkSync(TEST_FIRMWARE_DB); + if (existsSync(TEST_TELEMETRY_DB)) unlinkSync(TEST_TELEMETRY_DB); + + FirmwareService.resetInstance(); + TelemetryService.resetInstance(); + AdminAuthService.resetInstance(); + + process.env.ADMIN_ADDRESSES = new Wallet(ADMIN_PRIVATE_KEY).address; + process.env.TELEMETRY_DB_PATH = TEST_TELEMETRY_DB; + + FirmwareService.getInstance(TEST_FIRMWARE_DB); + TelemetryService.getInstance(TEST_TELEMETRY_DB); + + sentCalls = []; + connected = []; + + const mockTcpService = { + getConnectedDevices: () => connected, + sendApiCallToDevice: async (address: string, method: string, args: any) => { + sentCalls.push({ address, method, args }); + }, + trySendApiCallToDevice: (address: string, method: string, args: any) => { + const hit = connected.some(d => d.address.toLowerCase() === address.toLowerCase()); + if (hit) sentCalls.push({ address, method, args }); + return hit; + }, + deliverPendingRevoke: (deviceAddress: string) => { + const firmware = FirmwareService.getInstance(); + const pending = firmware.getPendingRevoke(deviceAddress); + if (!pending) return false; + const hit = connected.some( + d => d.address.toLowerCase() === normalizeDeviceAddress(deviceAddress).toLowerCase() + ); + if (!hit) return false; + const args = firmware.buildRevokeNoticeArgs(pending); + sentCalls.push({ address: pending.device, method: 'updateReady', args }); + firmware.markRevokeDelivered(pending.id); + TelemetryService.getInstance().recordFirmwareRevoke( + pending.device, + pending.project, + 'delivered', + pending.setupVersion + ); + return true; + }, + } as unknown as ASyncTCPService; + + const router = createRouter({} as ASyncService, mockTcpService); + app = express(); + app.use(express.json()); + app.use('/api', router); + + adminWallet = new Wallet(ADMIN_PRIVATE_KEY); + }); + + afterEach(() => { + try { + FirmwareService.getInstance().close(); + } catch { + /* ignore */ + } + try { + TelemetryService.getInstance().close(); + } catch { + /* ignore */ + } + if (existsSync(TEST_FIRMWARE_DB)) unlinkSync(TEST_FIRMWARE_DB); + if (existsSync(TEST_TELEMETRY_DB)) unlinkSync(TEST_TELEMETRY_DB); + FirmwareService.resetInstance(); + TelemetryService.resetInstance(); + AdminAuthService.resetInstance(); + delete process.env.ADMIN_ADDRESSES; + delete process.env.TELEMETRY_DB_PATH; + }); + + afterAll(() => { + vi.restoreAllMocks(); + }); + + async function getChallenge(): Promise { + const response = await request(app).get('/api/admin/challenge'); + return response.body.nonce; + } + + async function seedSetupFirmware( + project = 'garagedoor', + version = '1.0.0', + sha256 = 'aa'.repeat(32) + ) { + const firmware = FirmwareService.getInstance(); + firmware.addSetupFirmware( + project, + version, + sha256, + 2048, + `firmware/${project}/setup/${version}/firmware.bin`, + `https://example.r2.dev/firmware/${project}/setup/${version}/firmware.bin` + ); + return { project, version, sha256 }; + } + + async function signRevoke(project: string, device: string, sha256: string) { + const nonce = await getChallenge(); + const message = buildRevokeNoticeMessage(project, device, sha256, nonce); + const signature = await adminWallet.signMessage(message); + return { message, signature }; + } + + it('GET /setup returns 404 when no setup firmware registered', async () => { + await request(app).get('/api/firmware/garagedoor/setup').expect(404); + }); + + it('GET /setup returns current setup firmware metadata', async () => { + await seedSetupFirmware(); + const response = await request(app).get('/api/firmware/garagedoor/setup').expect(200); + expect(response.body.version).toBe('1.0.0'); + expect(response.body.sha256).toBe('aa'.repeat(32)); + expect(response.body.channel).toBe('setup'); + }); + + it('rejects revoke without auth', async () => { + await seedSetupFirmware(); + const response = await request(app) + .post('/api/firmware/garagedoor/revoke') + .send({ device: DEVICE }) + .expect(400); + expect(response.body.error).toContain('signature'); + }); + + it('rejects revoke when no setup firmware registered', async () => { + const nonce = await getChallenge(); + const message = buildRevokeNoticeMessage('garagedoor', DEVICE, 'deadbeef', nonce); + const signature = await adminWallet.signMessage(message); + + const response = await request(app) + .post('/api/firmware/garagedoor/revoke') + .send({ device: DEVICE, message, signature }) + .expect(404); + + expect(response.body.error).toContain('setup firmware'); + }); + + it('rejects revoke with wrong signature', async () => { + const { sha256 } = await seedSetupFirmware(); + const nonce = await getChallenge(); + const message = buildRevokeNoticeMessage('garagedoor', DEVICE, sha256, nonce); + const wrong = Wallet.createRandom(); + const signature = await wrong.signMessage(message); + + await request(app) + .post('/api/firmware/garagedoor/revoke') + .send({ device: DEVICE, message, signature }) + .expect(403); + }); + + it('queues revoke when device is offline', async () => { + const { sha256, version } = await seedSetupFirmware(); + const { message, signature } = await signRevoke('garagedoor', DEVICE, sha256); + + const response = await request(app) + .post('/api/firmware/garagedoor/revoke') + .send({ device: DEVICE, message, signature }) + .expect(200); + + expect(response.body.success).toBe(true); + expect(response.body.status).toBe('pending'); + expect(response.body.queued).toBe(true); + expect(response.body.setup.version).toBe(version); + expect(sentCalls).toHaveLength(0); + + const firmware = FirmwareService.getInstance(); + const pending = firmware.getPendingRevoke(DEVICE); + expect(pending).not.toBeNull(); + expect(pending!.noticeMessage).toBe(message); + + const telemetry = TelemetryService.getInstance(); + const events = telemetry.getEvents({ device: DEVICE, limit: 10 }); + expect(events.events.some(e => e.eventType === 'firmware_revoke_requested')).toBe(true); + }); + + it('delivers revoke notice immediately when device is online', async () => { + const { sha256 } = await seedSetupFirmware(); + connected = [{ address: DEVICE, project: 'garagedoor', semver: '1.2.0' }]; + + const { message, signature } = await signRevoke('garagedoor', DEVICE, sha256); + + const response = await request(app) + .post('/api/firmware/garagedoor/revoke') + .send({ device: DEVICE, message, signature }) + .expect(200); + + expect(response.body.status).toBe('delivered'); + expect(response.body.queued).toBe(false); + expect(sentCalls).toHaveLength(1); + expect(sentCalls[0].method).toBe('updateReady'); + expect(sentCalls[0].args.purpose).toEqual(['revoke']); + expect(sentCalls[0].args.sha256).toEqual([sha256]); + expect(sentCalls[0].args.message).toEqual([message]); + expect(sentCalls[0].args.signature).toEqual([signature]); + + const firmware = FirmwareService.getInstance(); + const active = firmware.getActiveRevoke(DEVICE); + expect(active?.status).toBe('delivered'); + + const telemetry = TelemetryService.getInstance(); + const events = telemetry.getEvents({ device: DEVICE, limit: 10 }); + const types = events.events.map(e => e.eventType); + expect(types).toContain('firmware_revoke_requested'); + expect(types).toContain('firmware_revoke_delivered'); + }); + + it('cancels a pending revoke', async () => { + const { sha256 } = await seedSetupFirmware(); + const { message, signature } = await signRevoke('garagedoor', DEVICE, sha256); + await request(app) + .post('/api/firmware/garagedoor/revoke') + .send({ device: DEVICE, message, signature }) + .expect(200); + + const nonce = await getChallenge(); + const cancelMessage = `revoke-cancel:garagedoor:${normalizeDeviceAddress(DEVICE)}:${nonce}`; + const cancelSig = await adminWallet.signMessage(cancelMessage); + + const response = await request(app) + .post('/api/firmware/garagedoor/revoke/cancel') + .send({ device: DEVICE, message: cancelMessage, signature: cancelSig }) + .expect(200); + + expect(response.body.status).toBe('cancelled'); + expect(FirmwareService.getInstance().getActiveRevoke(DEVICE)).toBeNull(); + + const events = TelemetryService.getInstance().getEvents({ device: DEVICE, limit: 10 }); + expect(events.events.some(e => e.eventType === 'firmware_revoke_cancelled')).toBe(true); + }); + + it('lists revokes for a project', async () => { + const { sha256 } = await seedSetupFirmware(); + const { message, signature } = await signRevoke('garagedoor', DEVICE, sha256); + await request(app) + .post('/api/firmware/garagedoor/revoke') + .send({ device: DEVICE, message, signature }) + .expect(200); + + const response = await request(app).get('/api/firmware/garagedoor/revokes').expect(200); + expect(response.body.revokes).toHaveLength(1); + expect(response.body.revokes[0].device).toBe(normalizeDeviceAddress(DEVICE)); + expect(response.body.revokes[0].status).toBe('pending'); + }); + + it('uploads setup firmware with admin signature', async () => { + const binary = Buffer.from('setup-firmware-binary-contents'); + const sha256 = FirmwareService.computeSha256(binary); + const nonce = await getChallenge(); + const message = `setup-firmware:garagedoor:1.0.0:${sha256}:${nonce}`; + const signature = await adminWallet.signMessage(message); + + const response = await request(app) + .post( + `/api/firmware/garagedoor/setup?version=1.0.0&signature=${encodeURIComponent(signature)}&message=${encodeURIComponent(message)}` + ) + .set('Content-Type', 'application/octet-stream') + .send(binary) + .expect(200); + + expect(response.body.success).toBe(true); + expect(response.body.channel).toBe('setup'); + expect(response.body.sha256).toBe(sha256); + expect(response.body.url).toContain('/setup/1.0.0/'); + + const latestApp = FirmwareService.getInstance().getLatestFirmware('garagedoor'); + expect(latestApp).toBeNull(); + const setup = FirmwareService.getInstance().getSetupFirmware('garagedoor'); + expect(setup?.version).toBe('1.0.0'); + }); + + it('does not replace app latest when uploading setup firmware', async () => { + const firmware = FirmwareService.getInstance(); + firmware.addFirmware( + 'garagedoor', + '2.0.0', + 'bb'.repeat(32), + 4096, + 'firmware/garagedoor/2.0.0/firmware.bin', + 'https://example.r2.dev/app.bin' + ); + + const binary = Buffer.from('setup-bin'); + const sha256 = FirmwareService.computeSha256(binary); + const nonce = await getChallenge(); + const message = `setup-firmware:garagedoor:1.0.0:${sha256}:${nonce}`; + const signature = await adminWallet.signMessage(message); + + await request(app) + .post( + `/api/firmware/garagedoor/setup?version=1.0.0&signature=${encodeURIComponent(signature)}&message=${encodeURIComponent(message)}` + ) + .set('Content-Type', 'application/octet-stream') + .send(binary) + .expect(200); + + expect(firmware.getLatestFirmware('garagedoor')?.version).toBe('2.0.0'); + expect(firmware.getSetupFirmware('garagedoor')?.version).toBe('1.0.0'); + }); +}); + +describe('FirmwareService revoke queue', () => { + beforeEach(() => { + if (existsSync(TEST_FIRMWARE_DB)) unlinkSync(TEST_FIRMWARE_DB); + FirmwareService.resetInstance(); + }); + + afterEach(() => { + try { + FirmwareService.getInstance().close(); + } catch { + /* ignore */ + } + if (existsSync(TEST_FIRMWARE_DB)) unlinkSync(TEST_FIRMWARE_DB); + FirmwareService.resetInstance(); + }); + + it('marks delivered, acknowledged, then completed', () => { + const fw = FirmwareService.getInstance(TEST_FIRMWARE_DB); + fw.addSetupFirmware('garagedoor', '1.0.0', 'aa'.repeat(32), 100, 'key', 'url'); + const setup = fw.getSetupFirmware('garagedoor')!; + + const revoke = fw.requestRevoke({ + project: 'garagedoor', + device: DEVICE, + setup, + noticeMessage: 'msg', + noticeSignature: 'sig', + requestedBy: '0xadmin', + }); + expect(revoke.status).toBe('pending'); + + const delivered = fw.markRevokeDelivered(revoke.id); + expect(delivered?.status).toBe('delivered'); + + const acknowledged = fw.markRevokeAcknowledged(revoke.id); + expect(acknowledged?.status).toBe('acknowledged'); + + fw.markRevokeDisconnectedAfterDelivery(DEVICE); + expect(fw.getActiveRevoke(DEVICE)?.disconnectedAfterDelivery).toBe(true); + + const completed = fw.markRevokeCompleted(revoke.id); + expect(completed?.status).toBe('completed'); + expect(fw.getActiveRevoke(DEVICE)).toBeNull(); + }); + + it('supersedes previous pending revoke for same device', () => { + const fw = FirmwareService.getInstance(TEST_FIRMWARE_DB); + fw.addSetupFirmware('garagedoor', '1.0.0', 'aa'.repeat(32), 100, 'key', 'url'); + const setup = fw.getSetupFirmware('garagedoor')!; + + const first = fw.requestRevoke({ + project: 'garagedoor', + device: DEVICE, + setup, + noticeMessage: 'msg1', + noticeSignature: 'sig1', + }); + const second = fw.requestRevoke({ + project: 'garagedoor', + device: DEVICE, + setup, + noticeMessage: 'msg2', + noticeSignature: 'sig2', + }); + + expect(fw.getRevokeById(first.id)?.status).toBe('cancelled'); + expect(second.status).toBe('pending'); + expect(fw.getPendingRevoke(DEVICE)?.id).toBe(second.id); + }); +}); diff --git a/src/api/routes.ts b/src/api/routes.ts index e0a48b4..f41536e 100644 --- a/src/api/routes.ts +++ b/src/api/routes.ts @@ -5,7 +5,11 @@ import * as passkey from './passkey'; import { uploadToR2, uploadFirmwareToR2, isR2Configured } from '../service/CloudflareR2'; import { randomUUID } from 'crypto'; import { TelemetryService } from '../service/TelemetryService'; -import { FirmwareService } from '../service/FirmwareService'; +import { + FirmwareService, + buildRevokeNoticeMessage, + normalizeDeviceAddress, +} from '../service/FirmwareService'; import { AdminAuthService } from '../service/AdminAuthService'; import { ZigbeeDiagnosticsService, @@ -352,6 +356,29 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) } }); + // Current setup (provisioning portal) firmware for a project — distinct from app /latest + router.get('/firmware/:project/setup', (req, res) => { + try { + if (!firmware) { + res.status(503).json({ error: 'Firmware service not initialized' }); + return; + } + + const project = req.params.project; + const setup = firmware.getSetupFirmware(project); + + if (!setup) { + res.status(404).json({ error: 'No setup firmware found for this project' }); + return; + } + + res.json(setup); + } catch (err) { + console.error('[Firmware] Setup query error:', err); + res.status(500).json({ error: 'Internal error' }); + } + }); + router.get('/firmware/:project', (req, res) => { try { if (!firmware) { @@ -361,8 +388,9 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) const project = req.params.project; const versions = firmware.listVersions(project); + const setupVersions = firmware.listSetupVersions(project); - res.json({ project, versions }); + res.json({ project, versions, setupVersions }); } catch (err) { console.error('[Firmware] List versions error:', err); res.status(500).json({ error: 'Internal error' }); @@ -577,6 +605,319 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) } }); + // Upload setup (provisioning) firmware — same admin signing scheme as app firmware, + // message format: setup-firmware:::: + router.post( + '/firmware/:project/setup', + express.raw({ + type: ['application/octet-stream', 'application/x-binary'], + limit: `${config.firmwareUploadMaxSizeMb}mb`, + }), + async (req, res) => { + try { + if (!firmware) { + res.status(503).json({ error: 'Firmware service not initialized' }); + return; + } + + if (!isR2Configured(req.params.project)) { + res.status(503).json({ error: 'R2 storage not configured' }); + return; + } + + const project = req.params.project; + const version = req.query.version as string; + const signature = req.query.signature as string; + const message = req.query.message as string; + + if (!version) { + res.status(400).json({ error: 'Missing version query parameter' }); + return; + } + + if (!FirmwareVersionParser.isPlainSemver(version)) { + res.status(400).json({ + error: + 'Version must be plain semver MAJOR.MINOR.PATCH (e.g., 1.2.3). Do not include project name, v prefix, or build suffix.', + }); + return; + } + + const adminAddresses = getAdminAddresses(); + if (adminAddresses.length === 0) { + res.status(503).json({ error: 'Admin addresses not configured' }); + return; + } + + if (!signature || !message) { + res.status(400).json({ error: 'Missing signature or message query parameters' }); + return; + } + + const body = req.body as Buffer | undefined; + if (!body || body.length === 0) { + res.status(400).json({ error: 'No firmware data' }); + return; + } + + const sha256 = FirmwareService.computeSha256(body); + + const nonceMatch = message.match(/:([a-f0-9]{64})$/); + if (!nonceMatch) { + res.status(400).json({ error: 'Message does not contain valid nonce' }); + return; + } + const nonce = nonceMatch[1]; + + const expectedMessage = `setup-firmware:${project}:${version}:${sha256}:${nonce}`; + if (message !== expectedMessage) { + res.status(400).json({ + error: + 'Message format mismatch (expected setup-firmware::::)', + }); + return; + } + + const authResult = adminAuth.verifyAndBurnNonce(nonce, message, signature, adminAddresses); + if (!authResult.valid) { + res.status(403).json({ error: authResult.error || 'Signature verification failed' }); + return; + } + + if (firmware.setupFirmwareExists(project, version)) { + res.status(409).json({ error: 'Setup version already exists' }); + return; + } + + const r2Key = `firmware/${project}/setup/${version}/firmware.bin`; + const url = await uploadFirmwareToR2(project, r2Key, body); + if (!url) { + res.status(500).json({ error: 'R2 upload failed' }); + return; + } + + const metadata = firmware.addSetupFirmware( + project, + version, + sha256, + body.length, + r2Key, + url, + authResult.address, + true + ); + + res.json({ + success: true, + channel: 'setup', + project: metadata.project, + version: metadata.version, + sha256: metadata.sha256, + size: metadata.size, + url: metadata.url, + uploadedBy: metadata.uploadedBy, + }); + } catch (err) { + console.error('[Firmware] Setup upload error:', err); + res.status(500).json({ error: 'Internal error' }); + } + } + ); + + // Revoke a device: push admin-signed updateReady(purpose=revoke) notice, or queue if offline + router.post('/firmware/:project/revoke', express.json(), async (req, res) => { + try { + if (!firmware) { + res.status(503).json({ error: 'Firmware service not initialized' }); + return; + } + + const project = req.params.project; + const { device, signature, message } = req.body || {}; + + if (!device || typeof device !== 'string') { + res.status(400).json({ error: 'Missing device address' }); + return; + } + + const adminAddresses = getAdminAddresses(); + if (adminAddresses.length === 0) { + res.status(503).json({ error: 'Admin addresses not configured' }); + return; + } + + if (!signature || !message) { + res.status(400).json({ error: 'Missing signature or message' }); + return; + } + + const setup = firmware.getSetupFirmware(project); + if (!setup) { + res.status(404).json({ error: 'No setup firmware registered for this project' }); + return; + } + + const nonceMatch = message.match(/:([a-f0-9]{64})$/); + if (!nonceMatch) { + res.status(400).json({ error: 'Message does not contain valid nonce' }); + return; + } + const nonce = nonceMatch[1]; + + const expectedMessage = buildRevokeNoticeMessage(project, device, setup.sha256, nonce); + if (message !== expectedMessage) { + res.status(400).json({ + error: + 'Message format mismatch (expected revoke::::)', + }); + return; + } + + const authResult = adminAuth.verifyAndBurnNonce(nonce, message, signature, adminAddresses); + if (!authResult.valid) { + res.status(403).json({ error: authResult.error || 'Signature verification failed' }); + return; + } + + const revoke = firmware.requestRevoke({ + project, + device, + setup, + noticeMessage: message, + noticeSignature: signature, + requestedBy: authResult.address, + }); + + telemetry.recordFirmwareRevoke( + revoke.device, + project, + 'requested', + setup.version + ); + + const delivered = tcpService.deliverPendingRevoke(normalizeDeviceAddress(device)); + + res.json({ + success: true, + project, + device: revoke.device, + status: delivered ? 'delivered' : 'pending', + setup: { + version: setup.version, + sha256: setup.sha256, + size: setup.size, + url: setup.url, + }, + revokeId: revoke.id, + revokedBy: authResult.address, + queued: !delivered, + }); + } catch (err) { + console.error('[Firmware] Revoke error:', err); + res.status(500).json({ error: 'Internal error' }); + } + }); + + // Cancel a pending or delivered-but-not-completed revoke + router.post('/firmware/:project/revoke/cancel', express.json(), async (req, res) => { + try { + if (!firmware) { + res.status(503).json({ error: 'Firmware service not initialized' }); + return; + } + + const project = req.params.project; + const { device, signature, message } = req.body || {}; + + if (!device || typeof device !== 'string') { + res.status(400).json({ error: 'Missing device address' }); + return; + } + + const adminAddresses = getAdminAddresses(); + if (adminAddresses.length === 0) { + res.status(503).json({ error: 'Admin addresses not configured' }); + return; + } + + if (!signature || !message) { + res.status(400).json({ error: 'Missing signature or message' }); + return; + } + + const nonceMatch = message.match(/:([a-f0-9]{64})$/); + if (!nonceMatch) { + res.status(400).json({ error: 'Message does not contain valid nonce' }); + return; + } + const nonce = nonceMatch[1]; + + const normalizedDevice = normalizeDeviceAddress(device); + const expectedMessage = `revoke-cancel:${project}:${normalizedDevice}:${nonce}`; + if (message !== expectedMessage) { + res.status(400).json({ + error: + 'Message format mismatch (expected revoke-cancel:::)', + }); + return; + } + + const authResult = adminAuth.verifyAndBurnNonce(nonce, message, signature, adminAddresses); + if (!authResult.valid) { + res.status(403).json({ error: authResult.error || 'Signature verification failed' }); + return; + } + + const cancelled = firmware.cancelRevoke(normalizedDevice, project); + if (!cancelled) { + res.status(404).json({ error: 'No active revoke found for this device' }); + return; + } + + telemetry.recordFirmwareRevoke( + cancelled.device, + project, + 'cancelled', + cancelled.setupVersion + ); + + res.json({ + success: true, + project, + device: cancelled.device, + status: 'cancelled', + revokeId: cancelled.id, + cancelledBy: authResult.address, + }); + } catch (err) { + console.error('[Firmware] Revoke cancel error:', err); + res.status(500).json({ error: 'Internal error' }); + } + }); + + router.get('/firmware/:project/revokes', (req, res) => { + try { + if (!firmware) { + res.status(503).json({ error: 'Firmware service not initialized' }); + return; + } + + const project = req.params.project; + const device = typeof req.query.device === 'string' ? req.query.device : undefined; + const status = typeof req.query.status === 'string' ? req.query.status : undefined; + const revokes = firmware.listRevokes(project, { + device, + status: status as any, + limit: 100, + }); + + res.json({ project, revokes }); + } catch (err) { + console.error('[Firmware] List revokes error:', err); + res.status(500).json({ error: 'Internal error' }); + } + }); + router.post('/firmware/:project', express.raw({ type: ['application/octet-stream', 'application/x-binary'], limit: `${config.firmwareUploadMaxSizeMb}mb` }), async (req, res) => { try { if (!firmware) { diff --git a/src/service/ASyncTCPService.ts b/src/service/ASyncTCPService.ts index 1ffc88c..1b60bbf 100644 --- a/src/service/ASyncTCPService.ts +++ b/src/service/ASyncTCPService.ts @@ -7,6 +7,10 @@ import { loadConfig } from '../config'; import { getEthereumMessageHash, recoverAddressFromSignature } from '../crypto/signature'; import { TelemetryService } from './TelemetryService'; import { FirmwareVersionParser } from './FirmwareVersionParser'; +import { + FirmwareService, + normalizeDeviceAddress, +} from './FirmwareService'; // ESP TcpBridge treats 5 minutes without a server packet as a dead session, and // it checks that *before* reading the inbound 0x06. Send keepalives sooner. @@ -373,6 +377,11 @@ export class ASyncTCPService implements TCPCallback { this.touchPin(addrLower, ip); console.log('Authenticated #' + index, addrLower, firmwareVersion ? `fw=${firmwareVersion}` : '(legacy)'); this.telemetry.recordDeviceConnection(addrLower, 'TCP', ip, firmwareVersion); + // Deliver queued revoke notices / detect setup-firmware reappearance after auth. + // Defer so the auth response path is not blocked by the outbound API call. + setImmediate(() => { + void this.handlePostLoginRevoke(addrLower, firmwareVersion); + }); return; } this.dropUnauth(client, index, 'bad signature'); @@ -428,13 +437,15 @@ export class ASyncTCPService implements TCPCallback { } const addrLower = client.getAddress().toLowerCase(); this.touchPin(addrLower, client.getRemoteIp()); + const responseText = message.subarray(0, 1024).toString('utf-8'); let list = this.clientResponse.get(addrLower); if (!list) { list = []; this.clientResponse.set(addrLower, list); } if (list.length > 8) list.shift(); - list.push(message.subarray(0, 1024).toString('utf-8')); + list.push(responseText); + this.maybeAcknowledgeRevoke(addrLower, responseText); return; } case 0x06: @@ -480,6 +491,11 @@ export class ASyncTCPService implements TCPCallback { const addr = client.getAddress()?.toLowerCase(); if (addr) { this.telemetry.recordDeviceDisconnect(addr, reason); + try { + FirmwareService.getInstance().markRevokeDisconnectedAfterDelivery(addr); + } catch { + // Firmware DB may not be initialized in some test setups + } } this.clientIndexList.delete(index); if (addr && this.clientMap.get(addr) === index) { @@ -567,6 +583,135 @@ export class ASyncTCPService implements TCPCallback { client.sendMessage(method, argMap); } + /** + * Returns true if the device is currently connected and accepted the write. + * Unlike sendApiCallToDevice, this reports whether a live client was found. + */ + trySendApiCallToDevice(address: string, method: string, argMap: MultiValueMap): boolean { + const addrLower = address.toLowerCase(); + const idx = this.clientMap.get(addrLower); + if (idx === undefined) return false; + + const client = this.clientIndexList.get(idx); + if (!client || !client.isAlive()) return false; + + client.sendMessage(method, argMap); + return true; + } + + /** + * Attempt immediate delivery of a pending revoke notice to a connected device. + * Returns true if the notice was written to the TCP socket. + */ + deliverPendingRevoke(deviceAddress: string): boolean { + let firmware: FirmwareService; + try { + firmware = FirmwareService.getInstance(); + } catch { + return false; + } + + const pending = firmware.getPendingRevoke(deviceAddress); + if (!pending) return false; + + const args = firmware.buildRevokeNoticeArgs(pending); + const sent = this.trySendApiCallToDevice(pending.device, 'updateReady', args); + if (!sent) return false; + + firmware.markRevokeDelivered(pending.id); + this.telemetry.recordFirmwareRevoke( + pending.device, + pending.project, + 'delivered', + pending.setupVersion + ); + console.log( + 'Delivered revoke notice to', + pending.device, + 'project', + pending.project, + 'setup', + pending.setupVersion + ); + return true; + } + + /** + * Device API response after updateReady(purpose=revoke). App firmware should + * reply with "revoking" before setting stay_portal and OTA-installing setup. + */ + private maybeAcknowledgeRevoke(deviceAddress: string, responseText: string): void { + const trimmed = responseText.trim().toLowerCase(); + if (!trimmed.startsWith('revoking')) return; + + let firmware: FirmwareService; + try { + firmware = FirmwareService.getInstance(); + } catch { + return; + } + + const active = firmware.getActiveRevoke(deviceAddress); + if (!active) return; + if (active.status !== 'pending' && active.status !== 'delivered') return; + + const updated = firmware.markRevokeAcknowledged(active.id); + if (!updated || updated.status !== 'acknowledged') return; + + this.telemetry.recordFirmwareRevoke( + active.device, + active.project, + 'acknowledged', + active.setupVersion + ); + console.log('Revoke acknowledged by device', active.device, 'project', active.project); + } + + private handlePostLoginRevoke(deviceAddress: string, firmwareVersion?: string): void { + let firmware: FirmwareService; + try { + firmware = FirmwareService.getInstance(); + } catch { + return; + } + + const device = normalizeDeviceAddress(deviceAddress); + const active = firmware.getActiveRevoke(device); + if (!active) return; + + const parsed = firmwareVersion ? FirmwareVersionParser.parse(firmwareVersion) : null; + + // Setup firmware stays in captive portal (NVS stay_portal) and typically does + // NOT TCP-login. Observable completion is the *app* reappearing after the + // device disconnected post-delivery/ack (OTA → portal → Done → app OTA). + const appReappeared = + !!parsed && parsed.project.toLowerCase() === active.project.toLowerCase(); + const revokeSettled = + active.status === 'acknowledged' || + (active.status === 'delivered' && active.disconnectedAfterDelivery); + if (appReappeared && revokeSettled) { + firmware.markRevokeCompleted(active.id); + this.telemetry.recordFirmwareRevoke( + device, + active.project, + 'completed', + active.setupVersion, + firmwareVersion + ); + console.log( + 'Revoke completed — app firmware reappeared for', + device, + firmwareVersion || '(no version)' + ); + return; + } + + // Still on app firmware with a pending revoke: deliver now. + if (active.status === 'pending') { + this.deliverPendingRevoke(device); + } + } + getLoginChallenge(remoteAddr: string): string { const challenge = createChallenge(); const thisClient = new APIClient(challenge, remoteAddr); diff --git a/src/service/FirmwareService.ts b/src/service/FirmwareService.ts index b785a3b..abd4334 100644 --- a/src/service/FirmwareService.ts +++ b/src/service/FirmwareService.ts @@ -1,5 +1,5 @@ /** - * FirmwareService - Manages firmware metadata and coordinates with R2 storage + * FirmwareService - Manages firmware metadata, setup firmware, and revoke queue */ import Database from 'better-sqlite3'; @@ -7,6 +7,8 @@ import { existsSync, mkdirSync } from 'fs'; import { dirname } from 'path'; import { createHash } from 'crypto'; +export type FirmwareChannel = 'app' | 'setup'; + export interface FirmwareMetadata { id: number; project: string; @@ -18,6 +20,7 @@ export interface FirmwareMetadata { uploadedAt: number; uploadedBy?: string; isCurrent: boolean; + channel: FirmwareChannel; } export interface FirmwareVersion { @@ -26,6 +29,61 @@ export interface FirmwareVersion { url: string; sha256: string; size: number; + channel?: FirmwareChannel; +} + +export type RevokeStatus = + | 'pending' + | 'delivered' + | 'acknowledged' + | 'completed' + | 'cancelled'; + +export interface DeviceRevoke { + id: number; + project: string; + device: string; + status: RevokeStatus; + setupVersion: string; + setupSha256: string; + setupSize: number; + setupUrl: string; + noticeMessage: string; + noticeSignature: string; + requestedAt: number; + requestedBy?: string; + deliveredAt?: number; + acknowledgedAt?: number; + /** Set when the device disconnects after delivery/ack (typical OTA reboot). */ + disconnectedAfterDelivery: boolean; + completedAt?: number; + cancelledAt?: number; +} + +/** Build the EIP-191 message an admin signs for a device revoke notice. */ +export function buildRevokeNoticeMessage( + project: string, + deviceAddress: string, + setupSha256: string, + nonce: string +): string { + const device = normalizeDeviceAddress(deviceAddress); + return `revoke:${project}:${device}:${setupSha256}:${nonce}`; +} + +/** Setup firmware TCP/login identity: "-setup@+" */ +export function setupFirmwareProjectId(project: string): string { + return `${project.trim().toLowerCase()}-setup`; +} + +export function isSetupFirmwareIdentity(project: string | undefined, appProject: string): boolean { + if (!project) return false; + return project.toLowerCase() === setupFirmwareProjectId(appProject); +} + +export function normalizeDeviceAddress(addr: string): string { + const hex = addr.replace(/^0x/i, '').toLowerCase(); + return `0x${hex}`; } export class FirmwareService { @@ -77,7 +135,63 @@ export class FirmwareService { CREATE INDEX IF NOT EXISTS idx_project ON firmware(project); CREATE INDEX IF NOT EXISTS idx_project_current ON firmware(project, is_current); + + CREATE TABLE IF NOT EXISTS setup_firmware ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + project TEXT NOT NULL, + version TEXT NOT NULL, + sha256 TEXT NOT NULL, + size INTEGER NOT NULL, + r2_key TEXT NOT NULL, + url TEXT NOT NULL, + uploaded_at INTEGER NOT NULL, + uploaded_by TEXT, + is_current INTEGER NOT NULL DEFAULT 0, + UNIQUE(project, version) + ); + + CREATE INDEX IF NOT EXISTS idx_setup_project ON setup_firmware(project); + CREATE INDEX IF NOT EXISTS idx_setup_project_current ON setup_firmware(project, is_current); + + CREATE TABLE IF NOT EXISTS device_revokes ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + project TEXT NOT NULL, + device TEXT NOT NULL, + status TEXT NOT NULL, + setup_version TEXT NOT NULL, + setup_sha256 TEXT NOT NULL, + setup_size INTEGER NOT NULL, + setup_url TEXT NOT NULL, + notice_message TEXT NOT NULL, + notice_signature TEXT NOT NULL, + requested_at INTEGER NOT NULL, + requested_by TEXT, + delivered_at INTEGER, + acknowledged_at INTEGER, + disconnected_after_delivery INTEGER NOT NULL DEFAULT 0, + completed_at INTEGER, + cancelled_at INTEGER + ); + + CREATE INDEX IF NOT EXISTS idx_revoke_device ON device_revokes(device); + CREATE INDEX IF NOT EXISTS idx_revoke_status ON device_revokes(status); + CREATE INDEX IF NOT EXISTS idx_revoke_device_status ON device_revokes(device, status); `); + + this.migrateRevokeSchema(); + } + + private migrateRevokeSchema(): void { + const columns = this.db.prepare('PRAGMA table_info(device_revokes)').all() as Array<{ name: string }>; + const names = new Set(columns.map(c => c.name)); + if (!names.has('acknowledged_at')) { + this.db.exec('ALTER TABLE device_revokes ADD COLUMN acknowledged_at INTEGER'); + } + if (!names.has('disconnected_after_delivery')) { + this.db.exec( + 'ALTER TABLE device_revokes ADD COLUMN disconnected_after_delivery INTEGER NOT NULL DEFAULT 0' + ); + } } static computeSha256(buffer: Buffer): string { @@ -132,6 +246,57 @@ export class FirmwareService { uploadedAt, uploadedBy, isCurrent: markCurrent, + channel: 'app' as FirmwareChannel, + }; + })(); + + return result; + } + + addSetupFirmware( + project: string, + version: string, + sha256: string, + size: number, + r2Key: string, + url: string, + uploadedBy?: string, + markCurrent = true + ): FirmwareMetadata { + const uploadedAt = Date.now(); + + const result = this.db.transaction(() => { + if (markCurrent) { + this.db.prepare(`UPDATE setup_firmware SET is_current = 0 WHERE project = ?`).run(project); + } + + const info = this.db.prepare(` + INSERT INTO setup_firmware (project, version, sha256, size, r2_key, url, uploaded_at, uploaded_by, is_current) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) + `).run( + project, + version, + sha256, + size, + r2Key, + url, + uploadedAt, + uploadedBy || null, + markCurrent ? 1 : 0 + ); + + return { + id: info.lastInsertRowid as number, + project, + version, + sha256, + size, + r2Key, + url, + uploadedAt, + uploadedBy, + isCurrent: markCurrent, + channel: 'setup' as FirmwareChannel, }; })(); @@ -155,6 +320,27 @@ export class FirmwareService { url: row.url, sha256: row.sha256, size: row.size, + channel: 'app', + }; + } + + getSetupFirmware(project: string): FirmwareVersion | null { + const row = this.db.prepare(` + SELECT project, version, url, sha256, size + FROM setup_firmware + WHERE project = ? AND is_current = 1 + LIMIT 1 + `).get(project) as any; + + if (!row) return null; + + return { + project: row.project, + version: row.version, + url: row.url, + sha256: row.sha256, + size: row.size, + channel: 'setup', }; } @@ -166,7 +352,24 @@ export class FirmwareService { ORDER BY uploaded_at DESC, id DESC `); - return stmt.all(project) as any[]; + return (stmt.all(project) as any[]).map(row => ({ + ...row, + channel: 'app' as FirmwareChannel, + })); + } + + listSetupVersions(project: string): FirmwareVersion[] { + const rows = this.db.prepare(` + SELECT project, version, url, sha256, size, is_current as isCurrent + FROM setup_firmware + WHERE project = ? + ORDER BY uploaded_at DESC, id DESC + `).all(project) as any[]; + + return rows.map(row => ({ + ...row, + channel: 'setup' as FirmwareChannel, + })); } setCurrentVersion(project: string, version: string): boolean { @@ -195,6 +398,21 @@ export class FirmwareService { return result; } + setCurrentSetupVersion(project: string, version: string): boolean { + return this.db.transaction(() => { + const exists = this.db.prepare(` + SELECT id FROM setup_firmware WHERE project = ? AND version = ? + `).get(project, version); + if (!exists) return false; + + this.db.prepare(`UPDATE setup_firmware SET is_current = 0 WHERE project = ?`).run(project); + this.db.prepare(` + UPDATE setup_firmware SET is_current = 1 WHERE project = ? AND version = ? + `).run(project, version); + return true; + })(); + } + firmwareExists(project: string, version: string): boolean { const stmt = this.db.prepare(` SELECT id FROM firmware WHERE project = ? AND version = ? LIMIT 1 @@ -202,6 +420,201 @@ export class FirmwareService { return !!stmt.get(project, version); } + setupFirmwareExists(project: string, version: string): boolean { + return !!this.db.prepare(` + SELECT id FROM setup_firmware WHERE project = ? AND version = ? LIMIT 1 + `).get(project, version); + } + + /** + * Queue or immediately-record a revoke. Replaces any existing pending/delivered + * revoke for the same device (cancelled/completed history is retained). + */ + requestRevoke(params: { + project: string; + device: string; + setup: FirmwareVersion; + noticeMessage: string; + noticeSignature: string; + requestedBy?: string; + }): DeviceRevoke { + const device = normalizeDeviceAddress(params.device); + const requestedAt = Date.now(); + + return this.db.transaction(() => { + // Supersede active revokes for this device + this.db.prepare(` + UPDATE device_revokes + SET status = 'cancelled', cancelled_at = ? + WHERE device = ? AND status IN ('pending', 'delivered', 'acknowledged') + `).run(requestedAt, device); + + const info = this.db.prepare(` + INSERT INTO device_revokes ( + project, device, status, setup_version, setup_sha256, setup_size, setup_url, + notice_message, notice_signature, requested_at, requested_by + ) VALUES (?, ?, 'pending', ?, ?, ?, ?, ?, ?, ?, ?) + `).run( + params.project, + device, + params.setup.version, + params.setup.sha256, + params.setup.size, + params.setup.url, + params.noticeMessage, + params.noticeSignature, + requestedAt, + params.requestedBy || null + ); + + return this.getRevokeById(info.lastInsertRowid as number)!; + })(); + } + + getRevokeById(id: number): DeviceRevoke | null { + const row = this.db.prepare(`SELECT * FROM device_revokes WHERE id = ?`).get(id) as any; + return row ? this.mapRevoke(row) : null; + } + + getActiveRevoke(device: string): DeviceRevoke | null { + const normalized = normalizeDeviceAddress(device); + const row = this.db.prepare(` + SELECT * FROM device_revokes + WHERE device = ? AND status IN ('pending', 'delivered', 'acknowledged') + ORDER BY requested_at DESC + LIMIT 1 + `).get(normalized) as any; + return row ? this.mapRevoke(row) : null; + } + + getPendingRevoke(device: string): DeviceRevoke | null { + const normalized = normalizeDeviceAddress(device); + const row = this.db.prepare(` + SELECT * FROM device_revokes + WHERE device = ? AND status = 'pending' + ORDER BY requested_at DESC + LIMIT 1 + `).get(normalized) as any; + return row ? this.mapRevoke(row) : null; + } + + markRevokeDelivered(id: number): DeviceRevoke | null { + const deliveredAt = Date.now(); + this.db.prepare(` + UPDATE device_revokes + SET status = 'delivered', delivered_at = ? + WHERE id = ? AND status = 'pending' + `).run(deliveredAt, id); + return this.getRevokeById(id); + } + + /** + * Device acknowledged the revoke notice over TCP (before OTA to setup). + * Expected API response body: "revoking" (or prefix). + */ + markRevokeAcknowledged(id: number): DeviceRevoke | null { + const acknowledgedAt = Date.now(); + this.db.prepare(` + UPDATE device_revokes + SET status = 'acknowledged', acknowledged_at = ? + WHERE id = ? AND status IN ('pending', 'delivered') + `).run(acknowledgedAt, id); + return this.getRevokeById(id); + } + + markRevokeDisconnectedAfterDelivery(device: string): void { + const active = this.getActiveRevoke(device); + if (!active) return; + if (active.status !== 'delivered' && active.status !== 'acknowledged') return; + this.db.prepare(` + UPDATE device_revokes + SET disconnected_after_delivery = 1 + WHERE id = ? + `).run(active.id); + } + + markRevokeCompleted(id: number): DeviceRevoke | null { + const completedAt = Date.now(); + this.db.prepare(` + UPDATE device_revokes + SET status = 'completed', completed_at = ? + WHERE id = ? AND status IN ('pending', 'delivered', 'acknowledged') + `).run(completedAt, id); + return this.getRevokeById(id); + } + + cancelRevoke(device: string, project?: string): DeviceRevoke | null { + const normalized = normalizeDeviceAddress(device); + const active = this.getActiveRevoke(normalized); + if (!active) return null; + if (project && active.project.toLowerCase() !== project.toLowerCase()) { + return null; + } + + const cancelledAt = Date.now(); + this.db.prepare(` + UPDATE device_revokes + SET status = 'cancelled', cancelled_at = ? + WHERE id = ? AND status IN ('pending', 'delivered', 'acknowledged') + `).run(cancelledAt, active.id); + + return this.getRevokeById(active.id); + } + + listRevokes(project: string, options: { device?: string; status?: RevokeStatus; limit?: number } = {}): DeviceRevoke[] { + const { device, status, limit = 100 } = options; + let sql = `SELECT * FROM device_revokes WHERE project = ?`; + const params: any[] = [project]; + + if (device) { + sql += ` AND device = ?`; + params.push(normalizeDeviceAddress(device)); + } + if (status) { + sql += ` AND status = ?`; + params.push(status); + } + + sql += ` ORDER BY requested_at DESC LIMIT ?`; + params.push(limit); + + return (this.db.prepare(sql).all(...params) as any[]).map(row => this.mapRevoke(row)); + } + + /** Build the updateReady arg map for a revoke notice (opcode 0x04). */ + buildRevokeNoticeArgs(revoke: DeviceRevoke): Record { + return { + purpose: ['revoke'], + version: [revoke.setupVersion], + sha256: [revoke.setupSha256], + size: [String(revoke.setupSize)], + message: [revoke.noticeMessage], + signature: [revoke.noticeSignature], + }; + } + + private mapRevoke(row: any): DeviceRevoke { + return { + id: row.id, + project: row.project, + device: row.device, + status: row.status, + setupVersion: row.setup_version, + setupSha256: row.setup_sha256, + setupSize: row.setup_size, + setupUrl: row.setup_url, + noticeMessage: row.notice_message, + noticeSignature: row.notice_signature, + requestedAt: row.requested_at, + requestedBy: row.requested_by || undefined, + deliveredAt: row.delivered_at || undefined, + acknowledgedAt: row.acknowledged_at || undefined, + disconnectedAfterDelivery: !!row.disconnected_after_delivery, + completedAt: row.completed_at || undefined, + cancelledAt: row.cancelled_at || undefined, + }; + } + close(): void { this.db.close(); } diff --git a/src/service/TelemetryService.ts b/src/service/TelemetryService.ts index 60982a7..3822f12 100644 --- a/src/service/TelemetryService.ts +++ b/src/service/TelemetryService.ts @@ -8,11 +8,22 @@ import { dirname } from 'path'; export type DisconnectReason = 'timeout' | 'socket_error' | 'auth_failure' | 'signature_failure' | 'client_close' | 'terminated' | 'unknown'; +export type TelemetryEventType = + | 'connect' + | 'disconnect' + | 'api_call' + | 'firmware_notify' + | 'firmware_revoke_requested' + | 'firmware_revoke_delivered' + | 'firmware_revoke_acknowledged' + | 'firmware_revoke_completed' + | 'firmware_revoke_cancelled'; + export interface DeviceEvent { id: number; timestamp: number; device: string; - eventType: 'connect' | 'disconnect' | 'api_call' | 'firmware_notify'; + eventType: TelemetryEventType; protocol?: 'UDP' | 'TCP'; disconnectReason?: DisconnectReason; apiMethod?: string; @@ -289,6 +300,32 @@ export class TelemetryService { stmt.run(now, normalized, project, version); } + recordFirmwareRevoke( + address: string, + project: string, + phase: 'requested' | 'delivered' | 'acknowledged' | 'completed' | 'cancelled', + setupVersion?: string, + firmwareVersion?: string + ): void { + const normalized = address.toLowerCase(); + const now = Date.now(); + const eventType = `firmware_revoke_${phase}` as TelemetryEventType; + + const stmt = this.db.prepare(` + INSERT INTO device_events ( + timestamp, device, event_type, firmware_project, firmware_notify_version, firmware_version + ) VALUES (?, ?, ?, ?, ?, ?) + `); + stmt.run( + now, + normalized, + eventType, + project, + setupVersion || null, + firmwareVersion || null + ); + } + getDeviceMetrics(address: string, since?: number): DeviceMetrics | undefined { const normalized = address.toLowerCase(); const sinceTime = since || 0; diff --git a/tools/firmware/revoke.ts b/tools/firmware/revoke.ts new file mode 100644 index 0000000..1f85e99 --- /dev/null +++ b/tools/firmware/revoke.ts @@ -0,0 +1,187 @@ +#!/usr/bin/env ts-node +/** + * Firmware Revoke Tool + * + * Revokes a device so it OTA-installs the project's setup firmware and reboots + * into the provisioning portal. Uses the same admin auth as firmware upload. + * + * Usage: + * npm run firmware:revoke + * npm run firmware:revoke:cancel + * + * Or: + * ts-node tools/firmware/revoke.ts + * ts-node tools/firmware/revoke.ts --cancel + * + * Requires .env with: + * PROXY_BASE_URL=https://your-proxy.com + * FIRMWARE_ADMIN_KEY=0x... (private key for signing) + * + * .env locations (checked in order): + * 1. tools/firmware/.env + * 2. .env (repo root) + */ + +import { config } from 'dotenv'; +import { existsSync } from 'fs'; +import { join } from 'path'; +import { Wallet } from 'ethers'; + +const envPaths = [ + join(__dirname, '.env'), + join(__dirname, '..', '..', '.env'), +]; + +for (const envPath of envPaths) { + if (existsSync(envPath)) { + config({ path: envPath }); + break; + } +} + +const PROXY_BASE_URL = process.env.PROXY_BASE_URL || 'http://localhost:8081'; +const FIRMWARE_ADMIN_KEY = process.env.FIRMWARE_ADMIN_KEY || ''; + +function normalizeDeviceAddress(addr: string): string { + const hex = addr.replace(/^0x/i, '').toLowerCase(); + return `0x${hex}`; +} + +async function getChallenge(): Promise { + const response = await fetch(`${PROXY_BASE_URL}/api/admin/challenge`); + if (!response.ok) { + throw new Error(`Challenge request failed: ${response.status} ${response.statusText}`); + } + const { nonce } = (await response.json()) as { nonce: string }; + return nonce; +} + +async function getSetupFirmware(project: string): Promise<{ + version: string; + sha256: string; + size: number; + url: string; +}> { + const response = await fetch( + `${PROXY_BASE_URL}/api/firmware/${encodeURIComponent(project)}/setup` + ); + if (!response.ok) { + const error = await response.text(); + throw new Error(`Setup firmware lookup failed: ${response.status} - ${error}`); + } + return response.json() as Promise<{ + version: string; + sha256: string; + size: number; + url: string; + }>; +} + +async function revokeDevice(project: string, device: string): Promise { + if (!FIRMWARE_ADMIN_KEY) { + throw new Error('FIRMWARE_ADMIN_KEY not set in .env'); + } + + const setup = await getSetupFirmware(project); + console.log(`Setup firmware: v${setup.version} sha256=${setup.sha256}`); + + const nonce = await getChallenge(); + const normalized = normalizeDeviceAddress(device); + const message = `revoke:${project}:${normalized}:${setup.sha256}:${nonce}`; + + const wallet = new Wallet(FIRMWARE_ADMIN_KEY); + console.log(`Signing message: ${message}`); + const signature = await wallet.signMessage(message); + console.log(`Signing address: ${wallet.address}`); + + const response = await fetch( + `${PROXY_BASE_URL}/api/firmware/${encodeURIComponent(project)}/revoke`, + { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ device: normalized, message, signature }), + } + ); + + if (!response.ok) { + const error = await response.text(); + throw new Error(`Revoke failed: ${response.status} - ${error}`); + } + + return response.json(); +} + +async function cancelRevoke(project: string, device: string): Promise { + if (!FIRMWARE_ADMIN_KEY) { + throw new Error('FIRMWARE_ADMIN_KEY not set in .env'); + } + + const nonce = await getChallenge(); + const normalized = normalizeDeviceAddress(device); + const message = `revoke-cancel:${project}:${normalized}:${nonce}`; + + const wallet = new Wallet(FIRMWARE_ADMIN_KEY); + console.log(`Signing message: ${message}`); + const signature = await wallet.signMessage(message); + console.log(`Signing address: ${wallet.address}`); + + const response = await fetch( + `${PROXY_BASE_URL}/api/firmware/${encodeURIComponent(project)}/revoke/cancel`, + { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ device: normalized, message, signature }), + } + ); + + if (!response.ok) { + const error = await response.text(); + throw new Error(`Cancel failed: ${response.status} - ${error}`); + } + + return response.json(); +} + +async function main() { + const args = process.argv.slice(2); + const cancel = args.includes('--cancel'); + const positional = args.filter(a => a !== '--cancel'); + + if (positional.length < 2) { + console.error('Usage: ts-node revoke.ts '); + console.error(' ts-node revoke.ts --cancel '); + console.error('Example: ts-node revoke.ts garagedoor 0xabc123...'); + process.exit(1); + } + + const [project, device] = positional; + + if (!FIRMWARE_ADMIN_KEY) { + console.error('Error: FIRMWARE_ADMIN_KEY not set in .env'); + process.exit(1); + } + + console.log(`Project: ${project}`); + console.log(`Device: ${normalizeDeviceAddress(device)}`); + console.log(`Action: ${cancel ? 'cancel' : 'revoke'}`); + + const result = cancel + ? await cancelRevoke(project, device) + : await revokeDevice(project, device); + + console.log('\n✅ Success!'); + console.log(JSON.stringify(result, null, 2)); + + if (!cancel) { + if (result.queued) { + console.log('\n⏳ Device offline — revoke queued for next login'); + } else { + console.log('\n📢 Revoke notice delivered to connected device'); + } + } +} + +main().catch(err => { + console.error('\n❌ Error:', err.message); + process.exit(1); +}); diff --git a/tools/firmware/upload-setup.ts b/tools/firmware/upload-setup.ts new file mode 100644 index 0000000..3de1168 --- /dev/null +++ b/tools/firmware/upload-setup.ts @@ -0,0 +1,144 @@ +#!/usr/bin/env ts-node +/** + * Setup Firmware Upload Tool + * + * Uploads provisioning-portal (setup) firmware for a project. Stored alongside + * app firmware in R2 but does NOT become the app's /latest. + * + * Usage: + * npm run firmware:upload-setup + * OR: ts-node tools/firmware/upload-setup.ts + * + * Signed message: setup-firmware:::: + * + * Requires .env with: + * PROXY_BASE_URL=https://your-proxy.com + * FIRMWARE_ADMIN_KEY=0x... (private key for signing) + */ + +import { config } from 'dotenv'; +import { readFileSync, statSync, existsSync } from 'fs'; +import { join } from 'path'; +import { Wallet } from 'ethers'; +import { createHash } from 'crypto'; + +const envPaths = [ + join(__dirname, '.env'), + join(__dirname, '..', '..', '.env'), +]; + +for (const envPath of envPaths) { + if (existsSync(envPath)) { + config({ path: envPath }); + break; + } +} + +const PROXY_BASE_URL = process.env.PROXY_BASE_URL || 'http://localhost:8081'; +const FIRMWARE_ADMIN_KEY = process.env.FIRMWARE_ADMIN_KEY || ''; + +function computeSha256(buffer: Buffer): string { + return createHash('sha256').update(buffer).digest('hex'); +} + +function validatePlainSemver(version: string): boolean { + return /^\d+\.\d+\.\d+$/.test(version); +} + +async function getChallenge(): Promise { + const response = await fetch(`${PROXY_BASE_URL}/api/admin/challenge`); + if (!response.ok) { + throw new Error(`Challenge request failed: ${response.status} ${response.statusText}`); + } + const { nonce } = (await response.json()) as { nonce: string }; + return nonce; +} + +async function uploadSetupFirmware( + project: string, + version: string, + firmwareBuffer: Buffer +): Promise { + if (!FIRMWARE_ADMIN_KEY) { + throw new Error('FIRMWARE_ADMIN_KEY not set in .env'); + } + + const sha256 = computeSha256(firmwareBuffer); + console.log(`SHA256: ${sha256}`); + + console.log('Getting challenge nonce...'); + const nonce = await getChallenge(); + + const wallet = new Wallet(FIRMWARE_ADMIN_KEY); + const message = `setup-firmware:${project}:${version}:${sha256}:${nonce}`; + console.log(`Signing message: ${message}`); + const signature = await wallet.signMessage(message); + console.log(`Signature: ${signature}`); + console.log(`Signing address: ${wallet.address}`); + + const url = + `${PROXY_BASE_URL}/api/firmware/${encodeURIComponent(project)}/setup` + + `?version=${encodeURIComponent(version)}` + + `&signature=${encodeURIComponent(signature)}` + + `&message=${encodeURIComponent(message)}`; + + console.log(`Uploading ${firmwareBuffer.length} bytes of setup firmware to ${project} v${version}...`); + + const response = await fetch(url, { + method: 'POST', + headers: { + 'Content-Type': 'application/octet-stream', + }, + body: new Uint8Array(firmwareBuffer), + }); + + if (!response.ok) { + const error = await response.text(); + throw new Error(`Upload failed: ${response.status} - ${error}`); + } + + return response.json() as Promise; +} + +async function main() { + const args = process.argv.slice(2); + + if (args.length < 3) { + console.error('Usage: ts-node upload-setup.ts '); + console.error('Example: ts-node upload-setup.ts garagedoor 1.0.0 setup-firmware.bin'); + console.error(''); + console.error('Version must be plain semver MAJOR.MINOR.PATCH (e.g., 1.0.0)'); + process.exit(1); + } + + const [project, version, firmwarePath] = args; + + if (!FIRMWARE_ADMIN_KEY) { + console.error('Error: FIRMWARE_ADMIN_KEY not set in .env'); + process.exit(1); + } + + if (!validatePlainSemver(version)) { + console.error(`Error: Version "${version}" is not valid plain semver`); + process.exit(1); + } + + console.log(`Project: ${project}`); + console.log(`Version: ${version}`); + console.log(`File: ${firmwarePath}`); + console.log(`Channel: setup`); + + const firmwareBuffer = readFileSync(firmwarePath); + const stats = statSync(firmwarePath); + console.log(`Size: ${stats.size} bytes (${(stats.size / 1024 / 1024).toFixed(2)} MB)`); + + const result = await uploadSetupFirmware(project, version, firmwareBuffer); + + console.log('\n✅ Setup firmware upload successful!'); + console.log(JSON.stringify(result, null, 2)); +} + +main().catch(err => { + console.error('\n❌ Error:', err.message); + process.exit(1); +});