From 38af6c774b1a09c79d1423e60c1a37e4a4a4bd9b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 17 Nov 2026 02:13:13 +0000 Subject: [PATCH 1/2] Add firmware notification system for OTA updates - Parse firmware version format '@+' in TCP login (opcode 0x09) - Store parsed project and semver on device sessions - Add POST /api/firmware/:project/notify endpoint with admin auth - Support optional notify flag on upload/current endpoints (?notify=true) - Add --notify option to tools/firmware/upload.ts CLI - Expose updateAvailable in GET /telemetry/devices - Record firmware_notify telemetry events - Send updateReady API call to devices via opcode 0x04 - Skip legacy firmware formats (never break old devices) - Comprehensive tests for version parsing, selection logic, auth, and 0x04 send - Document complete OTA flow in docs/firmware-ota.md Co-authored-by: James Brown --- docs/firmware-ota.md | 386 ++++++++++++++++++ src/__tests__/firmware-notify.test.ts | 297 ++++++++++++++ src/__tests__/firmware-version-parser.test.ts | 128 ++++++ src/api/routes.ts | 183 ++++++++- src/service/ASyncTCPService.ts | 42 ++ src/service/FirmwareVersionParser.ts | 80 ++++ src/service/TCPClient.ts | 21 + src/service/TelemetryService.ts | 21 +- tools/firmware/upload.ts | 28 +- 9 files changed, 1177 insertions(+), 9 deletions(-) create mode 100644 docs/firmware-ota.md create mode 100644 src/__tests__/firmware-notify.test.ts create mode 100644 src/__tests__/firmware-version-parser.test.ts create mode 100644 src/service/FirmwareVersionParser.ts diff --git a/docs/firmware-ota.md b/docs/firmware-ota.md new file mode 100644 index 0000000..36325fe --- /dev/null +++ b/docs/firmware-ota.md @@ -0,0 +1,386 @@ +# Firmware Over-The-Air (OTA) Updates + +SmartLayerProxy provides a complete firmware OTA update system for IoT devices. This document describes the end-to-end flow, API endpoints, and release procedures. + +## Overview + +The OTA update flow consists of three main steps: + +1. **Upload**: Upload a new firmware binary to Cloudflare R2 +2. **Notify**: Notify devices that an update is available +3. **Download**: Devices download and flash the firmware + +## Firmware Version Format + +New-style firmware must report its version in the TCP login (opcode 0x09) using this format: + +``` +@+ +``` + +**Examples:** +- `garagedoor@1.2.0+ab12cd3` +- `remotecamera@0.5.1+def4567` + +**Components:** +- `project`: Lowercase project identifier (alphanumeric, hyphens, underscores) +- `semver`: Semantic version (MAJOR.MINOR.PATCH) +- `hash`: Optional git short hash or build identifier + +**Legacy firmware** (using opcode 0x07 or other version strings) is not notified and continues to work unchanged. + +## API Endpoints + +### GET /api/firmware/:project/latest + +Get the latest firmware metadata for a project. + +**Response:** +```json +{ + "project": "garagedoor", + "version": "1.2.0", + "url": "https://r2.example.com/firmware/garagedoor/1.2.0/firmware.bin", + "sha256": "abc123...", + "size": 524288 +} +``` + +This endpoint is called by devices to check for updates and download the firmware. + +### POST /api/firmware/:project + +Upload a new firmware binary (admin authentication required). + +**Query Parameters:** +- `version` (required): Semantic version string (e.g., `1.2.3`) +- `signature` (required): Admin signature +- `message` (required): Signed message in format `firmware::::` +- `notify` (optional): If `true`, automatically notify connected devices after upload + +**Request Body:** Raw firmware binary (Content-Type: `application/octet-stream`) + +**Response:** +```json +{ + "success": true, + "project": "garagedoor", + "version": "1.2.0", + "sha256": "abc123...", + "size": 524288, + "url": "https://r2.example.com/firmware/garagedoor/1.2.0/firmware.bin", + "uploadedBy": "0x1234...", + "notified": 3 +} +``` + +The `notified` field appears only if `?notify=true` was used. + +### POST /api/firmware/:project/current + +Set a specific version as current (admin authentication required). + +**Request Body:** +```json +{ + "version": "1.1.0", + "signature": "0xabc...", + "message": "current:::" +} +``` + +**Query Parameters:** +- `notify` (optional): If `true`, automatically notify connected devices after setting current version + +**Response:** +```json +{ + "success": true, + "project": "garagedoor", + "version": "1.1.0", + "setBy": "0x1234...", + "notified": 2 +} +``` + +### POST /api/firmware/:project/notify + +Notify connected devices about available firmware updates (admin authentication required). + +**Request Body:** +```json +{ + "message": "notify::", + "signature": "0xabc...", + "devices": ["0xaaa...", "0xbbb..."], + "force": false +} +``` + +**Parameters:** +- `message` (required): Signed message `notify::` +- `signature` (required): Admin signature +- `devices` (optional): Array of device addresses to notify. If omitted, notifies all eligible devices. +- `force` (optional): If `true`, notifies all devices even if they're already on the latest version + +**Response:** +```json +{ + "success": true, + "project": "garagedoor", + "latest": "1.2.0", + "notified": [ + { "address": "0xaaa...", "version": "1.0.0" }, + { "address": "0xbbb...", "version": "1.1.0" } + ], + "skipped": [ + { "address": "0xccc...", "reason": "already up to date" }, + { "address": "0xddd...", "reason": "different project or legacy format" } + ], + "notifiedBy": "0x1234..." +} +``` + +**Selection Logic:** +1. Only devices with matching `project` are selected +2. Only devices using the new version format (`project@semver+hash`) are selected +3. By default, only devices with `semver` older than the latest version are notified +4. With `force: true`, all devices are notified regardless of version +5. Legacy firmware (opcode 0x07, non-standard version strings) is never notified + +**Notification Method:** +The proxy sends an API call to the device using opcode 0x04 with method `updateReady` and no parameters. Devices should respond by: +1. Calling `GET /api/firmware/:project/latest` to get the update metadata +2. Downloading the binary from the `url` in the response +3. Verifying the SHA256 checksum +4. Flashing the firmware (OTA) +5. Rebooting + +### GET /api/telemetry/devices + +Get metrics for all connected devices (telemetry authentication required). + +**Response:** Array of device metrics with firmware information: +```json +[ + { + "address": "0xaaa...", + "firmwareVersion": "garagedoor@1.0.0+abc123", + "project": "garagedoor", + "version": "1.0.0", + "updateAvailable": true, + ... + } +] +``` + +**Added Fields:** +- `project`: Parsed project name (if using new format) +- `version`: Parsed semver (if using new format) +- `updateAvailable`: Boolean indicating if a newer version exists + +## CLI Tool + +The `tools/firmware/upload.ts` script uploads firmware with admin authentication. + +### Usage + +```bash +npm run firmware:upload [--notify] +``` + +or + +```bash +ts-node tools/firmware/upload.ts [--notify] +``` + +**Examples:** +```bash +# Upload only +npm run firmware:upload garagedoor 1.2.0 firmware.bin + +# Upload and notify +npm run firmware:upload garagedoor 1.2.0 firmware.bin --notify +``` + +**Configuration:** +The tool requires a `.env` file (in `tools/firmware/.env` or repo root) with: +``` +PROXY_BASE_URL=https://your-proxy.com +FIRMWARE_ADMIN_KEY=0x... +``` + +The `FIRMWARE_ADMIN_KEY` is an Ethereum private key that must be in the configured admin address list. + +## End-to-End Release Steps + +### 1. Build and Test Firmware + +Build your firmware binary and ensure it reports the correct version string in the TCP login: + +```cpp +String version = "garagedoor@1.2.0+ab12cd3"; +``` + +### 2. Upload Firmware + +Upload the binary to the proxy: + +```bash +npm run firmware:upload garagedoor 1.2.0 firmware.bin +``` + +This will: +- Compute the SHA256 hash +- Sign the upload request with your admin key +- Upload the binary to Cloudflare R2 +- Set it as the current version for the project + +### 3. Notify Devices + +**Option A: Manual Notification** + +Use the notify endpoint to control exactly when devices are notified: + +```bash +curl -X POST https://proxy.example.com/api/firmware/garagedoor/notify \ + -H "Content-Type: application/json" \ + -d '{ + "message": "notify:garagedoor:", + "signature": "0x...", + "force": false + }' +``` + +**Option B: Automatic Notification** + +Use the `--notify` flag during upload: + +```bash +npm run firmware:upload garagedoor 1.2.0 firmware.bin --notify +``` + +This automatically notifies all connected devices with older versions immediately after upload. + +### 4. Monitor Updates + +Check telemetry to see which devices have updated: + +```bash +curl -H "Authorization: Bearer " \ + https://proxy.example.com/api/telemetry/devices +``` + +Look for: +- `firmwareVersion` field showing the current version +- `updateAvailable` field showing if an update is pending +- Firmware notify events in the telemetry feed + +## Device Implementation + +Devices must implement the following to support OTA: + +### 1. Report Version in Login (Opcode 0x09) + +When authenticating with the proxy, send opcode 0x09 with the version string: + +```cpp +// Format: [challenge(16)] + [version_length(1)] + [version_string(N)] +String version = "garagedoor@1.2.0+ab12cd3"; +uint8_t versionLen = version.length(); +// Build packet: challenge + [versionLen] + version bytes +``` + +### 2. Handle updateReady API Call + +When the proxy sends an `updateReady` call (opcode 0x04), the device should: + +1. Acknowledge the message (respond with opcode 0x05 or 0x08) +2. Call `GET /api/firmware/:project/latest` to get update metadata +3. Download the firmware from the `url` field +4. Verify the SHA256 hash matches the `sha256` field +5. Flash the firmware using OTA +6. Reboot + +**Example (ESP32/Arduino):** + +```cpp +void handleApiCall(String method, Map args) { + if (method == "updateReady") { + Serial.println("Firmware update available!"); + downloadAndFlashUpdate(); + } +} + +void downloadAndFlashUpdate() { + // Get latest metadata + String url = "https://proxy.example.com/api/firmware/" + PROJECT + "/latest"; + HTTPClient http; + http.begin(url); + int httpCode = http.GET(); + + if (httpCode == 200) { + DynamicJsonDocument doc(1024); + deserializeJson(doc, http.getString()); + + String firmwareUrl = doc["url"]; + String expectedSha256 = doc["sha256"]; + int size = doc["size"]; + + // Download and flash + Update.begin(size); + // ... download from firmwareUrl, verify hash, flash + ESP.restart(); + } +} +``` + +## Telemetry Events + +All firmware notifications are recorded as telemetry events with type `firmware_notify`: + +```json +{ + "id": 12345, + "timestamp": 1234567890, + "device": "0xaaa...", + "eventType": "firmware_notify", + "firmwareProject": "garagedoor", + "firmwareNotifyVersion": "1.2.0" +} +``` + +These events can be queried through the telemetry API for monitoring and analysis. + +## Security + +- All upload and notify operations require admin authentication (Ethereum signature) +- Firmware binaries are uploaded to Cloudflare R2 with unique keys +- Devices verify SHA256 checksums before flashing +- Legacy firmware is never automatically notified (prevents breaking old devices) + +## Troubleshooting + +### Device Not Notified + +Check: +1. Device is using new version format (`project@semver+hash`) +2. Device project matches the uploaded firmware project +3. Device version is older than the latest (unless using `force: true`) +4. Device is connected to the TCP proxy (check telemetry) + +### Update Failed + +Check: +1. Device can reach the firmware download URL +2. SHA256 hash matches after download +3. Device has enough free space for OTA +4. Device OTA partition is valid + +### Version Parsing Failed + +Check: +1. Version string format is exactly `@+` +2. Semver uses three numbers (e.g., `1.2.3`, not `1.2`) +3. Project name is alphanumeric with hyphens/underscores only diff --git a/src/__tests__/firmware-notify.test.ts b/src/__tests__/firmware-notify.test.ts new file mode 100644 index 0000000..530e2b5 --- /dev/null +++ b/src/__tests__/firmware-notify.test.ts @@ -0,0 +1,297 @@ +import { describe, it, expect, beforeEach, afterEach } 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 } 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-notify.db'; +const TEST_TELEMETRY_DB = './test-telemetry-notify.db'; +const ADMIN_PRIVATE_KEY = '0x0123456789012345678901234567890123456789012345678901234567890123'; + +describe('Firmware Notify API', () => { + let app: express.Application; + let adminWallet: Wallet; + + 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(); + + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + const telemetry = TelemetryService.getInstance(TEST_TELEMETRY_DB); + + process.env.ADMIN_ADDRESSES = new Wallet(ADMIN_PRIVATE_KEY).address; + + const mockService = {} as ASyncService; + const mockTcpService = { + getConnectedDevices: () => [], + sendApiCallToDevice: async () => {}, + } as unknown as ASyncTCPService; + + const router = createRouter(mockService, mockTcpService); + app = express(); + app.use('/api', router); + + adminWallet = new Wallet(ADMIN_PRIVATE_KEY); + }); + + afterEach(() => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + firmware.close(); + const telemetry = TelemetryService.getInstance(TEST_TELEMETRY_DB); + telemetry.close(); + 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; + }); + + async function getChallenge(): Promise { + const response = await request(app).get('/api/admin/challenge'); + return response.body.nonce; + } + + async function signNotifyRequest(project: string): Promise<{ message: string; signature: string }> { + const nonce = await getChallenge(); + const message = `notify:${project}:${nonce}`; + const signature = await adminWallet.signMessage(message); + return { message, signature }; + } + + it('should require authentication', async () => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + firmware.addFirmware('garagedoor', '1.0.0', 'hash', 1024, 'key', 'url'); + + const response = await request(app) + .post('/api/firmware/garagedoor/notify') + .send({}) + .expect(400); + + expect(response.body.error).toContain('signature'); + }); + + it('should reject invalid signature', async () => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + firmware.addFirmware('garagedoor', '1.0.0', 'hash', 1024, 'key', 'url'); + + const nonce = await getChallenge(); + const message = `notify:garagedoor:${nonce}`; + const wrongWallet = Wallet.createRandom(); + const signature = await wrongWallet.signMessage(message); + + const response = await request(app) + .post('/api/firmware/garagedoor/notify') + .send({ message, signature }) + .expect(403); + + expect(response.body.error).toContain('admin'); + }); + + it('should return 404 when project has no firmware', async () => { + const { message, signature } = await signNotifyRequest('nonexistent'); + + const response = await request(app) + .post('/api/firmware/nonexistent/notify') + .send({ message, signature }) + .expect(404); + + expect(response.body.error).toContain('No firmware found'); + }); + + it('should return success with empty lists when no devices connected', async () => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + firmware.addFirmware('garagedoor', '1.0.0', 'hash', 1024, 'key', 'url'); + + const { message, signature } = await signNotifyRequest('garagedoor'); + + const response = await request(app) + .post('/api/firmware/garagedoor/notify') + .send({ message, signature }) + .expect(200); + + expect(response.body.success).toBe(true); + expect(response.body.project).toBe('garagedoor'); + expect(response.body.latest).toBe('1.0.0'); + expect(response.body.notified).toEqual([]); + expect(response.body.skipped).toEqual([]); + }); + + it('should skip devices with different project', async () => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + firmware.addFirmware('garagedoor', '1.0.0', 'hash', 1024, 'key', 'url'); + + const mockTcpService = { + getConnectedDevices: () => [ + { address: '0xaaa', project: 'remotecamera', semver: '0.5.0' }, + ], + sendApiCallToDevice: async () => {}, + } as unknown as ASyncTCPService; + + const router = createRouter({} as ASyncService, mockTcpService); + const testApp = express(); + testApp.use('/api', router); + + const { message, signature } = await signNotifyRequest('garagedoor'); + + const response = await request(testApp) + .post('/api/firmware/garagedoor/notify') + .send({ message, signature }) + .expect(200); + + expect(response.body.notified).toEqual([]); + }); + + it('should skip devices with legacy firmware format', async () => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + firmware.addFirmware('garagedoor', '1.0.0', 'hash', 1024, 'key', 'url'); + + const mockTcpService = { + getConnectedDevices: () => [ + { address: '0xaaa', firmwareVersion: 'legacy-format' }, + ], + sendApiCallToDevice: async () => {}, + } as unknown as ASyncTCPService; + + const router = createRouter({} as ASyncService, mockTcpService); + const testApp = express(); + testApp.use('/api', router); + + const { message, signature } = await signNotifyRequest('garagedoor'); + + const response = await request(testApp) + .post('/api/firmware/garagedoor/notify') + .send({ message, signature }) + .expect(200); + + expect(response.body.notified).toEqual([]); + }); + + it('should skip devices already on latest version', async () => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + firmware.addFirmware('garagedoor', '1.0.0', 'hash', 1024, 'key', 'url'); + + const mockTcpService = { + getConnectedDevices: () => [ + { address: '0xaaa', project: 'garagedoor', semver: '1.0.0' }, + ], + sendApiCallToDevice: async () => {}, + } as unknown as ASyncTCPService; + + const router = createRouter({} as ASyncService, mockTcpService); + const testApp = express(); + testApp.use('/api', router); + + const { message, signature } = await signNotifyRequest('garagedoor'); + + const response = await request(testApp) + .post('/api/firmware/garagedoor/notify') + .send({ message, signature }) + .expect(200); + + expect(response.body.notified).toEqual([]); + expect(response.body.skipped.length).toBeGreaterThan(0); + expect(response.body.skipped[0].reason).toContain('up to date'); + }); + + it('should notify devices with older versions', async () => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + firmware.addFirmware('garagedoor', '1.2.0', 'hash', 1024, 'key', 'url'); + + const notifiedDevices: string[] = []; + const mockTcpService = { + getConnectedDevices: () => [ + { address: '0xaaa', project: 'garagedoor', semver: '1.0.0' }, + { address: '0xbbb', project: 'garagedoor', semver: '1.1.0' }, + ], + sendApiCallToDevice: async (address: string) => { + notifiedDevices.push(address); + }, + } as unknown as ASyncTCPService; + + const router = createRouter({} as ASyncService, mockTcpService); + const testApp = express(); + testApp.use('/api', router); + + const { message, signature } = await signNotifyRequest('garagedoor'); + + const response = await request(testApp) + .post('/api/firmware/garagedoor/notify') + .send({ message, signature }) + .expect(200); + + expect(response.body.notified.length).toBe(2); + expect(notifiedDevices).toContain('0xaaa'); + expect(notifiedDevices).toContain('0xbbb'); + }); + + it('should support force flag to notify all devices', async () => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + firmware.addFirmware('garagedoor', '1.0.0', 'hash', 1024, 'key', 'url'); + + const notifiedDevices: string[] = []; + const mockTcpService = { + getConnectedDevices: () => [ + { address: '0xaaa', project: 'garagedoor', semver: '1.0.0' }, + ], + sendApiCallToDevice: async (address: string) => { + notifiedDevices.push(address); + }, + } as unknown as ASyncTCPService; + + const router = createRouter({} as ASyncService, mockTcpService); + const testApp = express(); + testApp.use('/api', router); + + const { message, signature } = await signNotifyRequest('garagedoor'); + + const response = await request(testApp) + .post('/api/firmware/garagedoor/notify') + .send({ message, signature, force: true }) + .expect(200); + + expect(response.body.notified.length).toBe(1); + expect(notifiedDevices).toContain('0xaaa'); + }); + + it('should support device filtering', async () => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + firmware.addFirmware('garagedoor', '1.2.0', 'hash', 1024, 'key', 'url'); + + const notifiedDevices: string[] = []; + const mockTcpService = { + getConnectedDevices: () => [ + { address: '0xaaa', project: 'garagedoor', semver: '1.0.0' }, + { address: '0xbbb', project: 'garagedoor', semver: '1.0.0' }, + ], + sendApiCallToDevice: async (address: string) => { + notifiedDevices.push(address); + }, + } as unknown as ASyncTCPService; + + const router = createRouter({} as ASyncService, mockTcpService); + const testApp = express(); + testApp.use('/api', router); + + const { message, signature } = await signNotifyRequest('garagedoor'); + + const response = await request(testApp) + .post('/api/firmware/garagedoor/notify') + .send({ message, signature, devices: ['0xaaa'] }) + .expect(200); + + expect(response.body.notified.length).toBe(1); + expect(response.body.notified[0].address).toBe('0xaaa'); + expect(notifiedDevices).toEqual(['0xaaa']); + }); +}); diff --git a/src/__tests__/firmware-version-parser.test.ts b/src/__tests__/firmware-version-parser.test.ts new file mode 100644 index 0000000..f96e1cd --- /dev/null +++ b/src/__tests__/firmware-version-parser.test.ts @@ -0,0 +1,128 @@ +import { describe, it, expect } from 'vitest'; +import { FirmwareVersionParser } from '../service/FirmwareVersionParser'; + +describe('FirmwareVersionParser', () => { + describe('parse', () => { + it('should parse valid new-format version strings', () => { + const result = FirmwareVersionParser.parse('garagedoor@1.2.3+abc123'); + expect(result).toEqual({ + project: 'garagedoor', + semver: '1.2.3', + hash: 'abc123', + major: 1, + minor: 2, + patch: 3, + }); + }); + + it('should parse version without hash', () => { + const result = FirmwareVersionParser.parse('remotecamera@2.0.1'); + expect(result).toEqual({ + project: 'remotecamera', + semver: '2.0.1', + hash: undefined, + major: 2, + minor: 0, + patch: 1, + }); + }); + + it('should normalize project name to lowercase', () => { + const result = FirmwareVersionParser.parse('GarageDoor@1.0.0+abc'); + expect(result?.project).toBe('garagedoor'); + }); + + it('should return null for legacy format', () => { + expect(FirmwareVersionParser.parse('legacy-version')).toBeNull(); + expect(FirmwareVersionParser.parse('1.2.3')).toBeNull(); + expect(FirmwareVersionParser.parse('v1.2.3')).toBeNull(); + }); + + it('should return null for empty or invalid strings', () => { + expect(FirmwareVersionParser.parse('')).toBeNull(); + expect(FirmwareVersionParser.parse('invalid')).toBeNull(); + expect(FirmwareVersionParser.parse('project@')).toBeNull(); + expect(FirmwareVersionParser.parse('project@invalid')).toBeNull(); + }); + + it('should handle project names with hyphens and underscores', () => { + const result = FirmwareVersionParser.parse('my-project_v2@1.0.0'); + expect(result?.project).toBe('my-project_v2'); + }); + + it('should handle version 0.0.0', () => { + const result = FirmwareVersionParser.parse('project@0.0.0'); + expect(result).toEqual({ + project: 'project', + semver: '0.0.0', + hash: undefined, + major: 0, + minor: 0, + patch: 0, + }); + }); + }); + + describe('compareSemver', () => { + it('should return 0 for equal versions', () => { + expect(FirmwareVersionParser.compareSemver('1.2.3', '1.2.3')).toBe(0); + expect(FirmwareVersionParser.compareSemver('0.0.0', '0.0.0')).toBe(0); + }); + + it('should return negative when first version is older', () => { + expect(FirmwareVersionParser.compareSemver('1.2.3', '1.2.4')).toBeLessThan(0); + expect(FirmwareVersionParser.compareSemver('1.2.3', '1.3.0')).toBeLessThan(0); + expect(FirmwareVersionParser.compareSemver('1.2.3', '2.0.0')).toBeLessThan(0); + }); + + it('should return positive when first version is newer', () => { + expect(FirmwareVersionParser.compareSemver('1.2.4', '1.2.3')).toBeGreaterThan(0); + expect(FirmwareVersionParser.compareSemver('1.3.0', '1.2.3')).toBeGreaterThan(0); + expect(FirmwareVersionParser.compareSemver('2.0.0', '1.2.3')).toBeGreaterThan(0); + }); + + it('should handle major version differences', () => { + expect(FirmwareVersionParser.compareSemver('2.0.0', '1.9.9')).toBeGreaterThan(0); + expect(FirmwareVersionParser.compareSemver('1.0.0', '2.0.0')).toBeLessThan(0); + }); + + it('should handle minor version differences', () => { + expect(FirmwareVersionParser.compareSemver('1.3.0', '1.2.9')).toBeGreaterThan(0); + expect(FirmwareVersionParser.compareSemver('1.2.0', '1.3.0')).toBeLessThan(0); + }); + + it('should handle patch version differences', () => { + expect(FirmwareVersionParser.compareSemver('1.2.4', '1.2.3')).toBeGreaterThan(0); + expect(FirmwareVersionParser.compareSemver('1.2.3', '1.2.4')).toBeLessThan(0); + }); + }); + + describe('isOlder', () => { + it('should return true when device version is older', () => { + expect(FirmwareVersionParser.isOlder('1.2.3', '1.2.4')).toBe(true); + expect(FirmwareVersionParser.isOlder('1.2.3', '1.3.0')).toBe(true); + expect(FirmwareVersionParser.isOlder('1.2.3', '2.0.0')).toBe(true); + }); + + it('should return false when device version is equal or newer', () => { + expect(FirmwareVersionParser.isOlder('1.2.4', '1.2.3')).toBe(false); + expect(FirmwareVersionParser.isOlder('1.2.3', '1.2.3')).toBe(false); + expect(FirmwareVersionParser.isOlder('2.0.0', '1.9.9')).toBe(false); + }); + }); + + describe('isNewFormat', () => { + it('should return true for new format strings', () => { + expect(FirmwareVersionParser.isNewFormat('garagedoor@1.2.3+abc')).toBe(true); + expect(FirmwareVersionParser.isNewFormat('project@0.0.1')).toBe(true); + expect(FirmwareVersionParser.isNewFormat('my-proj@1.0.0+abc123')).toBe(true); + }); + + it('should return false for legacy format strings', () => { + expect(FirmwareVersionParser.isNewFormat('legacy')).toBe(false); + expect(FirmwareVersionParser.isNewFormat('1.2.3')).toBe(false); + expect(FirmwareVersionParser.isNewFormat('v1.2.3')).toBe(false); + expect(FirmwareVersionParser.isNewFormat('')).toBe(false); + }); + }); +}); diff --git a/src/api/routes.ts b/src/api/routes.ts index 6df8b0f..ae930c3 100644 --- a/src/api/routes.ts +++ b/src/api/routes.ts @@ -8,6 +8,7 @@ import { TelemetryService } from '../service/TelemetryService'; import { FirmwareService } from '../service/FirmwareService'; import { AdminAuthService } from '../service/AdminAuthService'; import { loadConfig } from '../config'; +import { FirmwareVersionParser } from '../service/FirmwareVersionParser'; const CHECK_CONNECTION_INTERVAL_MS = 5 * 60 * 1000; @@ -378,13 +379,147 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) return; } - res.json({ success: true, project, version, setBy: result.address }); + const shouldNotify = req.query.notify === 'true'; + let notifyResult; + + if (shouldNotify) { + try { + const latest = firmware.getLatestFirmware(project); + if (latest) { + const connectedDevices = tcpService.getConnectedDevices(); + const notified: Array<{ address: string; version: string }> = []; + + for (const device of connectedDevices) { + if (device.project?.toLowerCase() === project.toLowerCase() && device.semver) { + if (FirmwareVersionParser.isOlder(device.semver, latest.version)) { + await tcpService.sendApiCallToDevice(device.address, 'updateReady', {}); + notified.push({ address: device.address, version: device.semver }); + telemetry.recordFirmwareNotify(device.address, project, latest.version); + } + } + } + notifyResult = { notified: notified.length }; + } + } catch (err) { + console.error('[Firmware] Auto-notify error:', err); + } + } + + res.json({ + success: true, + project, + version, + setBy: result.address, + ...(notifyResult ? { notified: notifyResult.notified } : {}) + }); } catch (err) { console.error('[Firmware] Set current error:', err); res.status(500).json({ error: 'Internal error' }); } }); + router.post('/firmware/:project/notify', express.json(), async (req, res) => { + try { + if (!firmware) { + res.status(503).json({ error: 'Firmware service not initialized' }); + return; + } + + const project = req.params.project; + const { devices, force, signature, message } = req.body || {}; + + 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 expectedMessagePrefix = `notify:${project}:`; + if (!message.startsWith(expectedMessagePrefix)) { + res.status(400).json({ error: 'Message format mismatch' }); + return; + } + + const authResult = adminAuth.verifyAndBurnNonce(nonce, message, signature, adminAddresses); + if (!authResult.valid) { + res.status(403).json({ error: authResult.error || 'Signature verification failed' }); + return; + } + + const latest = firmware.getLatestFirmware(project); + if (!latest) { + res.status(404).json({ error: 'No firmware found for this project' }); + return; + } + + const connectedDevices = tcpService.getConnectedDevices(); + + const notified: Array<{ address: string; version: string }> = []; + const skipped: Array<{ address: string; reason: string }> = []; + + const targetAddresses = devices ? devices.map((d: string) => d.toLowerCase()) : null; + + for (const device of connectedDevices) { + if (targetAddresses && !targetAddresses.includes(device.address.toLowerCase())) { + continue; + } + + if (!device.project || device.project.toLowerCase() !== project.toLowerCase()) { + if (targetAddresses && targetAddresses.includes(device.address.toLowerCase())) { + skipped.push({ address: device.address, reason: 'different project or legacy format' }); + } + continue; + } + + if (!device.semver) { + skipped.push({ address: device.address, reason: 'no semver available' }); + continue; + } + + const shouldNotify = force || FirmwareVersionParser.isOlder(device.semver, latest.version); + + if (!shouldNotify) { + skipped.push({ address: device.address, reason: 'already up to date' }); + continue; + } + + try { + await tcpService.sendApiCallToDevice(device.address, 'updateReady', {}); + notified.push({ address: device.address, version: device.semver }); + telemetry.recordFirmwareNotify(device.address, project, latest.version); + console.log('Notified device', device.address, 'about firmware update:', project, latest.version); + } catch (err) { + console.error('Failed to notify device', device.address, err); + skipped.push({ address: device.address, reason: 'send failed' }); + } + } + + res.json({ + success: true, + project, + latest: latest.version, + notified, + skipped, + notifiedBy: authResult.address, + }); + } catch (err) { + console.error('[Firmware] Notify 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) { @@ -474,6 +609,29 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) true ); + const shouldNotify = req.query.notify === 'true'; + let notifyResult; + + if (shouldNotify) { + try { + const connectedDevices = tcpService.getConnectedDevices(); + const notified: Array<{ address: string; version: string }> = []; + + for (const device of connectedDevices) { + if (device.project?.toLowerCase() === project.toLowerCase() && device.semver) { + if (FirmwareVersionParser.isOlder(device.semver, version)) { + await tcpService.sendApiCallToDevice(device.address, 'updateReady', {}); + notified.push({ address: device.address, version: device.semver }); + telemetry.recordFirmwareNotify(device.address, project, version); + } + } + } + notifyResult = { notified: notified.length }; + } catch (err) { + console.error('[Firmware] Auto-notify error:', err); + } + } + res.json({ success: true, project: metadata.project, @@ -482,6 +640,7 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) size: metadata.size, url: metadata.url, uploadedBy: metadata.uploadedBy, + ...(notifyResult ? { notified: notifyResult.notified } : {}) }); } catch (err) { console.error('[Firmware] Upload error:', err); @@ -607,6 +766,28 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) return; } const devices = telemetry.getAllDeviceMetrics(since); + + if (firmware) { + for (const device of devices) { + if (device.firmwareVersion) { + const parsed = FirmwareVersionParser.parse(device.firmwareVersion); + if (parsed) { + const latest = firmware.getLatestFirmware(parsed.project); + if (latest && latest.version !== parsed.semver) { + const isOlder = FirmwareVersionParser.isOlder(parsed.semver, latest.version); + (device as any).project = parsed.project; + (device as any).version = parsed.semver; + (device as any).updateAvailable = isOlder; + } else { + (device as any).project = parsed.project; + (device as any).version = parsed.semver; + (device as any).updateAvailable = false; + } + } + } + } + } + res.json(devices); } catch (err) { console.error(err); diff --git a/src/service/ASyncTCPService.ts b/src/service/ASyncTCPService.ts index b21c821..86b9e9c 100644 --- a/src/service/ASyncTCPService.ts +++ b/src/service/ASyncTCPService.ts @@ -6,6 +6,7 @@ import { MultiValueMap } from '../types'; import { loadConfig } from '../config'; import { getEthereumMessageHash, recoverAddressFromSignature } from '../crypto/signature'; import { TelemetryService } from './TelemetryService'; +import { FirmwareVersionParser } from './FirmwareVersionParser'; // 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. @@ -350,6 +351,18 @@ export class ASyncTCPService implements TCPCallback { return; } client.setAddress(recoveredAddr); + + if (firmwareVersion) { + const parsed = FirmwareVersionParser.parse(firmwareVersion); + if (parsed) { + client.setFirmwareInfo(firmwareVersion, parsed.project, parsed.semver); + console.log('Parsed firmware:', parsed.project, parsed.semver, parsed.hash || '(no hash)'); + } else { + client.setFirmwareInfo(firmwareVersion); + console.log('Firmware version (legacy format):', firmwareVersion); + } + } + this.addToClientMap(recoveredAddr, index); this.touchPin(addrLower, ip); this.telemetry.recordDeviceConnection(addrLower, 'TCP', ip, firmwareVersion); @@ -524,6 +537,35 @@ export class ASyncTCPService implements TCPCallback { return sb.join(''); } + getConnectedDevices(): Array<{ address: string; project?: string; semver?: string; firmwareVersion?: string }> { + const devices: Array<{ address: string; project?: string; semver?: string; firmwareVersion?: string }> = []; + + for (const [address, index] of this.clientMap) { + const client = this.clientIndexList.get(index); + if (!client || !client.isAlive()) continue; + + devices.push({ + address, + project: client.getFirmwareProject(), + semver: client.getFirmwareSemver(), + firmwareVersion: client.getFirmwareVersion(), + }); + } + + return devices; + } + + async sendApiCallToDevice(address: string, method: string, argMap: MultiValueMap): Promise { + const addrLower = address.toLowerCase(); + const idx = this.clientMap.get(addrLower); + if (idx === undefined) return; + + const client = this.clientIndexList.get(idx); + if (!client || !client.isAlive()) return; + + client.sendMessage(method, argMap); + } + getLoginChallenge(remoteAddr: string): string { const challenge = createChallenge(); const thisClient = new APIClient(challenge, remoteAddr); diff --git a/src/service/FirmwareVersionParser.ts b/src/service/FirmwareVersionParser.ts new file mode 100644 index 0000000..c5b6e26 --- /dev/null +++ b/src/service/FirmwareVersionParser.ts @@ -0,0 +1,80 @@ +/** + * FirmwareVersionParser - Parse and compare firmware version strings + * + * Expected format: "@+" + * Examples: + * - garagedoor@1.2.0+ab12cd3 + * - remotecamera@0.5.1+def4567 + */ + +export interface ParsedFirmwareVersion { + project: string; + semver: string; + hash?: string; + major: number; + minor: number; + patch: number; +} + +const FIRMWARE_VERSION_REGEX = /^([a-z0-9_-]+)@(\d+\.\d+\.\d+)(?:\+([a-f0-9]+))?$/i; + +export class FirmwareVersionParser { + /** + * Parse a firmware version string in the format "@+" + * Returns null if the format doesn't match + */ + static parse(versionString: string): ParsedFirmwareVersion | null { + if (!versionString) return null; + + const match = versionString.match(FIRMWARE_VERSION_REGEX); + if (!match) return null; + + const [, project, semver, hash] = match; + const [major, minor, patch] = semver.split('.').map(n => parseInt(n, 10)); + + if (isNaN(major) || isNaN(minor) || isNaN(patch)) { + return null; + } + + return { + project: project.toLowerCase(), + semver, + hash, + major, + minor, + patch, + }; + } + + /** + * Compare two semver strings + * Returns: + * - negative if v1 < v2 + * - 0 if v1 === v2 + * - positive if v1 > v2 + */ + static compareSemver(v1: string, v2: string): number { + const parts1 = v1.split('.').map(n => parseInt(n, 10)); + const parts2 = v2.split('.').map(n => parseInt(n, 10)); + + for (let i = 0; i < 3; i++) { + const diff = (parts1[i] || 0) - (parts2[i] || 0); + if (diff !== 0) return diff; + } + return 0; + } + + /** + * Check if a device version is older than the latest version + */ + static isOlder(deviceVersion: string, latestVersion: string): boolean { + return this.compareSemver(deviceVersion, latestVersion) < 0; + } + + /** + * Check if a firmware version string is in the new format + */ + static isNewFormat(versionString: string): boolean { + return FIRMWARE_VERSION_REGEX.test(versionString); + } +} diff --git a/src/service/TCPClient.ts b/src/service/TCPClient.ts index d19781e..49adaf5 100644 --- a/src/service/TCPClient.ts +++ b/src/service/TCPClient.ts @@ -24,6 +24,9 @@ export class TCPClient { private clientIndex: number; private challenge: Buffer = Buffer.alloc(0); private isWaitingForResponse = false; + private firmwareVersion?: string; + private firmwareProject?: string; + private firmwareSemver?: string; constructor(socket: net.Socket, callback: TCPCallback, index: number) { this.socket = socket; @@ -98,6 +101,24 @@ export class TCPClient { return this.address; } + setFirmwareInfo(version: string, project?: string, semver?: string): void { + this.firmwareVersion = version; + this.firmwareProject = project; + this.firmwareSemver = semver; + } + + getFirmwareVersion(): string | undefined { + return this.firmwareVersion; + } + + getFirmwareProject(): string | undefined { + return this.firmwareProject; + } + + getFirmwareSemver(): string | undefined { + return this.firmwareSemver; + } + getRemoteIp(): string { return this.remoteIp || normalizeRemoteIp(this.socket.remoteAddress); } diff --git a/src/service/TelemetryService.ts b/src/service/TelemetryService.ts index a260800..60982a7 100644 --- a/src/service/TelemetryService.ts +++ b/src/service/TelemetryService.ts @@ -12,7 +12,7 @@ export interface DeviceEvent { id: number; timestamp: number; device: string; - eventType: 'connect' | 'disconnect' | 'api_call'; + eventType: 'connect' | 'disconnect' | 'api_call' | 'firmware_notify'; protocol?: 'UDP' | 'TCP'; disconnectReason?: DisconnectReason; apiMethod?: string; @@ -20,6 +20,8 @@ export interface DeviceEvent { apiResponseTime?: number; ipAddress?: string; firmwareVersion?: string; + firmwareProject?: string; + firmwareNotifyVersion?: string; } export interface DeviceMetrics { @@ -186,6 +188,8 @@ export class TelemetryService { { name: 'api_response_time', type: 'INTEGER', added: 'initial' }, { name: 'ip_address', type: 'TEXT', added: 'initial' }, { name: 'firmware_version', type: 'TEXT', added: 'PR #2' }, + { name: 'firmware_project', type: 'TEXT', added: 'firmware-notify' }, + { name: 'firmware_notify_version', type: 'TEXT', added: 'firmware-notify' }, ]; // Add any missing columns @@ -270,6 +274,21 @@ export class TelemetryService { stmt.run(now, normalized, method, success ? 1 : 0, responseTimeMs); } + recordFirmwareNotify( + address: string, + project: string, + version: string + ): void { + const normalized = address.toLowerCase(); + const now = Date.now(); + + const stmt = this.db.prepare(` + INSERT INTO device_events (timestamp, device, event_type, firmware_project, firmware_notify_version) + VALUES (?, ?, 'firmware_notify', ?, ?) + `); + stmt.run(now, normalized, project, version); + } + getDeviceMetrics(address: string, since?: number): DeviceMetrics | undefined { const normalized = address.toLowerCase(); const sinceTime = since || 0; diff --git a/tools/firmware/upload.ts b/tools/firmware/upload.ts index 9f9a82a..463bcd2 100644 --- a/tools/firmware/upload.ts +++ b/tools/firmware/upload.ts @@ -5,11 +5,12 @@ * Signs and uploads firmware binaries to the proxy with admin authentication * * Usage: - * npm run firmware:upload - * OR: ts-node tools/firmware/upload.ts + * npm run firmware:upload [--notify] + * OR: ts-node tools/firmware/upload.ts [--notify] * * Example: * npm run firmware:upload GarageDoor 1.2.3 firmware.bin + * npm run firmware:upload GarageDoor 1.2.3 firmware.bin --notify * * Requires .env with: * PROXY_BASE_URL=https://your-proxy.com @@ -58,7 +59,8 @@ async function getChallenge(): Promise { async function uploadFirmware( project: string, version: string, - firmwareBuffer: Buffer + firmwareBuffer: Buffer, + notify: boolean ): Promise { if (!FIRMWARE_ADMIN_KEY) { throw new Error('FIRMWARE_ADMIN_KEY not set in .env'); @@ -80,9 +82,13 @@ async function uploadFirmware( console.log(`Signing address: ${wallet.address}`); // Upload firmware - const url = `${PROXY_BASE_URL}/api/firmware/${encodeURIComponent(project)}?version=${encodeURIComponent(version)}&signature=${encodeURIComponent(signature)}&message=${encodeURIComponent(message)}`; + const notifyParam = notify ? '¬ify=true' : ''; + const url = `${PROXY_BASE_URL}/api/firmware/${encodeURIComponent(project)}?version=${encodeURIComponent(version)}&signature=${encodeURIComponent(signature)}&message=${encodeURIComponent(message)}${notifyParam}`; console.log(`Uploading ${firmwareBuffer.length} bytes to ${project} v${version}...`); + if (notify) { + console.log('Will notify connected devices after upload'); + } const response = await fetch(url, { method: 'POST', @@ -104,12 +110,15 @@ async function main() { const args = process.argv.slice(2); if (args.length < 3) { - console.error('Usage: ts-node upload.ts '); + console.error('Usage: ts-node upload.ts [--notify]'); console.error('Example: ts-node upload.ts GarageDoor 1.2.3 firmware.bin'); + console.error(' ts-node upload.ts GarageDoor 1.2.3 firmware.bin --notify'); process.exit(1); } - const [project, version, firmwarePath] = args; + const notify = args.includes('--notify'); + const fileArgs = args.filter(a => a !== '--notify'); + const [project, version, firmwarePath] = fileArgs; if (!FIRMWARE_ADMIN_KEY) { console.error('Error: FIRMWARE_ADMIN_KEY not set in .env'); @@ -119,15 +128,20 @@ async function main() { console.log(`Project: ${project}`); console.log(`Version: ${version}`); console.log(`File: ${firmwarePath}`); + console.log(`Notify: ${notify}`); const firmwareBuffer = readFileSync(firmwarePath); const stats = statSync(firmwarePath); console.log(`Size: ${stats.size} bytes (${(stats.size / 1024 / 1024).toFixed(2)} MB)`); - const result = await uploadFirmware(project, version, firmwareBuffer); + const result = await uploadFirmware(project, version, firmwareBuffer, notify); console.log('\nāœ… Upload successful!'); console.log(JSON.stringify(result, null, 2)); + + if (notify && result.notified !== undefined) { + console.log(`\nšŸ“¢ Notified ${result.notified} device(s)`); + } } main().catch(err => { From 52fb0bce6855450debb3a920b02eb3351349be1a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 17 Nov 2026 02:23:29 +0000 Subject: [PATCH 2/2] Fix version comparison and add upload validation - Extract semver from any format (plain, v-prefix, @project, +build) - compareSemver/isOlder handle different version formats - Treat unparseable latest versions as error (do not notify) - Validate upload version is plain semver MAJOR.MINOR.PATCH - Reject v-prefix, @project prefix, +build suffix at upload - Add validation in POST /firmware/:project endpoint - Add validation in tools/firmware/upload.ts with clear error messages - Update docs: version must equal device FIRMWARE_SEMVER exactly - Comprehensive tests for extractSemver, isPlainSemver, format mixing - Tests for upload validation and unparseable version handling - All 196 tests pass, typecheck passes Co-authored-by: James Brown --- docs/firmware-ota.md | 68 ++++++++++++++-- src/__tests__/firmware-api.test.ts | 77 +++++++++++++++++++ src/__tests__/firmware-notify.test.ts | 57 ++++++++++++++ src/__tests__/firmware-version-parser.test.ts | 69 +++++++++++++++++ src/api/routes.ts | 30 +++++++- src/service/FirmwareVersionParser.ts | 64 +++++++++++++-- tools/firmware/upload.ts | 20 +++++ 7 files changed, 370 insertions(+), 15 deletions(-) diff --git a/docs/firmware-ota.md b/docs/firmware-ota.md index 36325fe..1e2d908 100644 --- a/docs/firmware-ota.md +++ b/docs/firmware-ota.md @@ -12,6 +12,8 @@ The OTA update flow consists of three main steps: ## Firmware Version Format +### Device Firmware Version String + New-style firmware must report its version in the TCP login (opcode 0x09) using this format: ``` @@ -24,11 +26,27 @@ New-style firmware must report its version in the TCP login (opcode 0x09) using **Components:** - `project`: Lowercase project identifier (alphanumeric, hyphens, underscores) -- `semver`: Semantic version (MAJOR.MINOR.PATCH) +- `semver`: Semantic version (MAJOR.MINOR.PATCH) - **must match uploaded version exactly** - `hash`: Optional git short hash or build identifier **Legacy firmware** (using opcode 0x07 or other version strings) is not notified and continues to work unchanged. +### Upload Version Format + +When uploading firmware via the API or CLI tool, the version parameter must be **plain semver only**: + +**āœ… Correct:** +- `1.2.3` +- `0.5.1` +- `10.20.30` + +**āŒ Incorrect:** +- `v1.2.3` (no v prefix) +- `1.2.3+abc123` (no build suffix) +- `garagedoor@1.2.3` (no project prefix) + +The uploaded version is stored in the database and compared with device semver during notifications. The comparison logic extracts MAJOR.MINOR.PATCH from any format, but uploads must use plain semver to ensure consistent storage. + ## API Endpoints ### GET /api/firmware/:project/latest @@ -53,7 +71,12 @@ This endpoint is called by devices to check for updates and download the firmwar Upload a new firmware binary (admin authentication required). **Query Parameters:** -- `version` (required): Semantic version string (e.g., `1.2.3`) +- `version` (required): **Plain semver MAJOR.MINOR.PATCH only** (e.g., `1.2.3`). Must NOT include: + - Project name prefix (not `garagedoor@1.2.3`) + - `v` prefix (not `v1.2.3`) + - Build suffix (not `1.2.3+abc123`) + + **Important:** This version must match the `FIRMWARE_SEMVER` constant in your device firmware exactly. - `signature` (required): Admin signature - `message` (required): Signed message in format `firmware::::` - `notify` (optional): If `true`, automatically notify connected devices after upload @@ -217,12 +240,24 @@ The `FIRMWARE_ADMIN_KEY` is an Ethereum private key that must be in the configur ### 1. Build and Test Firmware -Build your firmware binary and ensure it reports the correct version string in the TCP login: +Build your firmware binary and ensure it reports the correct version string in the TCP login. + +**Define version constants in your firmware:** ```cpp -String version = "garagedoor@1.2.0+ab12cd3"; +#define FIRMWARE_PROJECT "garagedoor" +#define FIRMWARE_SEMVER "1.2.0" +#define FIRMWARE_HASH "ab12cd3" + +// Construct full version string for login +String firmwareVersion = String(FIRMWARE_PROJECT) + "@" + + String(FIRMWARE_SEMVER) + "+" + + String(FIRMWARE_HASH); +// Result: "garagedoor@1.2.0+ab12cd3" ``` +**Important:** The `FIRMWARE_SEMVER` value (e.g., `"1.2.0"`) must match the version you pass to the upload tool exactly. + ### 2. Upload Firmware Upload the binary to the proxy: @@ -369,6 +404,7 @@ Check: 2. Device project matches the uploaded firmware project 3. Device version is older than the latest (unless using `force: true`) 4. Device is connected to the TCP proxy (check telemetry) +5. Uploaded version is plain semver (not `v1.2.3` or `1.2.3+hash`) ### Update Failed @@ -381,6 +417,28 @@ Check: ### Version Parsing Failed Check: -1. Version string format is exactly `@+` +1. Device version string format is exactly `@+` 2. Semver uses three numbers (e.g., `1.2.3`, not `1.2`) 3. Project name is alphanumeric with hyphens/underscores only +4. Upload version is plain semver MAJOR.MINOR.PATCH (reject at upload if invalid) + +### Upload Rejected: Invalid Version + +If upload fails with "Version must be plain semver MAJOR.MINOR.PATCH": + +**Fix your upload command:** +```bash +# āŒ Wrong +npm run firmware:upload garagedoor v1.2.0 firmware.bin +npm run firmware:upload garagedoor 1.2.0+abc firmware.bin +npm run firmware:upload garagedoor garagedoor@1.2.0 firmware.bin + +# āœ… Correct +npm run firmware:upload garagedoor 1.2.0 firmware.bin +``` + +**Ensure device firmware matches:** +```cpp +// In your device code, FIRMWARE_SEMVER must match upload version +#define FIRMWARE_SEMVER "1.2.0" // Must match: 1.2.0 +``` diff --git a/src/__tests__/firmware-api.test.ts b/src/__tests__/firmware-api.test.ts index acb3e54..dd86455 100644 --- a/src/__tests__/firmware-api.test.ts +++ b/src/__tests__/firmware-api.test.ts @@ -273,5 +273,82 @@ describe('Firmware API', () => { .send(Buffer.alloc(0)) .expect(400); }); + + it('should reject version with v prefix', async () => { + const firmware = Buffer.from('fake firmware data'); + const sha256 = createHash('sha256').update(firmware).digest('hex'); + + const challengeResp = await request(app).get('/api/admin/challenge').expect(200); + const { nonce } = challengeResp.body; + + const message = `firmware:GarageDoor:v1.0.0:${sha256}:${nonce}`; + const signature = await wallet.signMessage(message); + + const response = await request(app) + .post(`/api/firmware/GarageDoor?version=v1.0.0&signature=${encodeURIComponent(signature)}&message=${encodeURIComponent(message)}`) + .set('Content-Type', 'application/octet-stream') + .send(firmware) + .expect(400); + + expect(response.body.error).toContain('plain semver'); + }); + + it('should reject version with build suffix', async () => { + const firmware = Buffer.from('fake firmware data'); + const sha256 = createHash('sha256').update(firmware).digest('hex'); + + const challengeResp = await request(app).get('/api/admin/challenge').expect(200); + const { nonce } = challengeResp.body; + + const message = `firmware:GarageDoor:1.0.0+abc123:${sha256}:${nonce}`; + const signature = await wallet.signMessage(message); + + const response = await request(app) + .post(`/api/firmware/GarageDoor?version=1.0.0+abc123&signature=${encodeURIComponent(signature)}&message=${encodeURIComponent(message)}`) + .set('Content-Type', 'application/octet-stream') + .send(firmware) + .expect(400); + + expect(response.body.error).toContain('plain semver'); + }); + + it('should reject version with project prefix', async () => { + const firmware = Buffer.from('fake firmware data'); + const sha256 = createHash('sha256').update(firmware).digest('hex'); + + const challengeResp = await request(app).get('/api/admin/challenge').expect(200); + const { nonce } = challengeResp.body; + + const message = `firmware:GarageDoor:garagedoor@1.0.0:${sha256}:${nonce}`; + const signature = await wallet.signMessage(message); + + const response = await request(app) + .post(`/api/firmware/GarageDoor?version=garagedoor@1.0.0&signature=${encodeURIComponent(signature)}&message=${encodeURIComponent(message)}`) + .set('Content-Type', 'application/octet-stream') + .send(firmware) + .expect(400); + + expect(response.body.error).toContain('plain semver'); + }); + + it('should accept plain semver only', async () => { + const firmware = Buffer.from('fake firmware data'); + const sha256 = createHash('sha256').update(firmware).digest('hex'); + + const challengeResp = await request(app).get('/api/admin/challenge').expect(200); + const { nonce } = challengeResp.body; + + const message = `firmware:GarageDoor:1.2.3:${sha256}:${nonce}`; + const signature = await wallet.signMessage(message); + + const response = await request(app) + .post(`/api/firmware/GarageDoor?version=1.2.3&signature=${encodeURIComponent(signature)}&message=${encodeURIComponent(message)}`) + .set('Content-Type', 'application/octet-stream') + .send(firmware) + .expect(200); + + expect(response.body.success).toBe(true); + expect(response.body.version).toBe('1.2.3'); + }); }); }); diff --git a/src/__tests__/firmware-notify.test.ts b/src/__tests__/firmware-notify.test.ts index 530e2b5..9ef10fd 100644 --- a/src/__tests__/firmware-notify.test.ts +++ b/src/__tests__/firmware-notify.test.ts @@ -294,4 +294,61 @@ describe('Firmware Notify API', () => { expect(response.body.notified[0].address).toBe('0xaaa'); expect(notifiedDevices).toEqual(['0xaaa']); }); + + it('should handle version comparison with different formats', async () => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + firmware.addFirmware('garagedoor', '1.2.0', 'hash', 1024, 'key', 'url'); + + const notifiedDevices: string[] = []; + const mockTcpService = { + getConnectedDevices: () => [ + { address: '0xaaa', project: 'garagedoor', semver: '1.0.0' }, + ], + sendApiCallToDevice: async (address: string) => { + notifiedDevices.push(address); + }, + } as unknown as ASyncTCPService; + + const router = createRouter({} as ASyncService, mockTcpService); + const testApp = express(); + testApp.use('/api', router); + + const { message, signature } = await signNotifyRequest('garagedoor'); + + const response = await request(testApp) + .post('/api/firmware/garagedoor/notify') + .send({ message, signature }) + .expect(200); + + expect(response.body.notified.length).toBe(1); + expect(notifiedDevices).toContain('0xaaa'); + }); + + it('should reject when latest version format is invalid', async () => { + const firmware = FirmwareService.getInstance(TEST_FIRMWARE_DB); + const db = (firmware as any).db; + db.prepare('INSERT INTO firmware (project, version, sha256, size, r2_key, url, uploaded_at, is_current) VALUES (?, ?, ?, ?, ?, ?, ?, ?)').run( + 'garagedoor', 'invalid-version', 'hash', 1024, 'key', 'url', Date.now(), 1 + ); + + const mockTcpService = { + getConnectedDevices: () => [ + { address: '0xaaa', project: 'garagedoor', semver: '1.0.0' }, + ], + sendApiCallToDevice: async () => {}, + } as unknown as ASyncTCPService; + + const router = createRouter({} as ASyncService, mockTcpService); + const testApp = express(); + testApp.use('/api', router); + + const { message, signature } = await signNotifyRequest('garagedoor'); + + const response = await request(testApp) + .post('/api/firmware/garagedoor/notify') + .send({ message, signature }) + .expect(500); + + expect(response.body.error).toContain('invalid'); + }); }); diff --git a/src/__tests__/firmware-version-parser.test.ts b/src/__tests__/firmware-version-parser.test.ts index f96e1cd..49a29f3 100644 --- a/src/__tests__/firmware-version-parser.test.ts +++ b/src/__tests__/firmware-version-parser.test.ts @@ -63,6 +63,52 @@ describe('FirmwareVersionParser', () => { }); }); + describe('extractSemver', () => { + it('should extract from plain semver', () => { + expect(FirmwareVersionParser.extractSemver('1.2.3')).toBe('1.2.3'); + expect(FirmwareVersionParser.extractSemver('0.0.1')).toBe('0.0.1'); + expect(FirmwareVersionParser.extractSemver('10.20.30')).toBe('10.20.30'); + }); + + it('should extract from semver with v prefix', () => { + expect(FirmwareVersionParser.extractSemver('v1.2.3')).toBe('1.2.3'); + expect(FirmwareVersionParser.extractSemver('v0.0.1')).toBe('0.0.1'); + }); + + it('should extract from full device format', () => { + expect(FirmwareVersionParser.extractSemver('garagedoor@1.2.3+abc123')).toBe('1.2.3'); + expect(FirmwareVersionParser.extractSemver('project@0.5.1')).toBe('0.5.1'); + }); + + it('should extract from semver with build suffix', () => { + expect(FirmwareVersionParser.extractSemver('1.2.3+abc123')).toBe('1.2.3'); + expect(FirmwareVersionParser.extractSemver('2.0.0+def4567')).toBe('2.0.0'); + }); + + it('should return null for invalid formats', () => { + expect(FirmwareVersionParser.extractSemver('invalid')).toBeNull(); + expect(FirmwareVersionParser.extractSemver('1.2')).toBeNull(); + expect(FirmwareVersionParser.extractSemver('a.b.c')).toBeNull(); + expect(FirmwareVersionParser.extractSemver('')).toBeNull(); + }); + }); + + describe('isPlainSemver', () => { + it('should return true for plain semver', () => { + expect(FirmwareVersionParser.isPlainSemver('1.2.3')).toBe(true); + expect(FirmwareVersionParser.isPlainSemver('0.0.0')).toBe(true); + expect(FirmwareVersionParser.isPlainSemver('10.20.30')).toBe(true); + }); + + it('should return false for non-plain semver', () => { + expect(FirmwareVersionParser.isPlainSemver('v1.2.3')).toBe(false); + expect(FirmwareVersionParser.isPlainSemver('1.2.3+abc')).toBe(false); + expect(FirmwareVersionParser.isPlainSemver('project@1.2.3')).toBe(false); + expect(FirmwareVersionParser.isPlainSemver('1.2')).toBe(false); + expect(FirmwareVersionParser.isPlainSemver('')).toBe(false); + }); + }); + describe('compareSemver', () => { it('should return 0 for equal versions', () => { expect(FirmwareVersionParser.compareSemver('1.2.3', '1.2.3')).toBe(0); @@ -95,6 +141,18 @@ describe('FirmwareVersionParser', () => { expect(FirmwareVersionParser.compareSemver('1.2.4', '1.2.3')).toBeGreaterThan(0); expect(FirmwareVersionParser.compareSemver('1.2.3', '1.2.4')).toBeLessThan(0); }); + + it('should compare versions with different formats', () => { + expect(FirmwareVersionParser.compareSemver('1.2.3', 'v1.2.4')).toBeLessThan(0); + expect(FirmwareVersionParser.compareSemver('v1.2.3', 'project@1.2.2+abc')).toBeGreaterThan(0); + expect(FirmwareVersionParser.compareSemver('1.2.3+build', '1.2.3')).toBe(0); + }); + + it('should return null for unparseable versions', () => { + expect(FirmwareVersionParser.compareSemver('invalid', '1.2.3')).toBeNull(); + expect(FirmwareVersionParser.compareSemver('1.2.3', 'invalid')).toBeNull(); + expect(FirmwareVersionParser.compareSemver('1.2', '1.2.3')).toBeNull(); + }); }); describe('isOlder', () => { @@ -109,6 +167,17 @@ describe('FirmwareVersionParser', () => { expect(FirmwareVersionParser.isOlder('1.2.3', '1.2.3')).toBe(false); expect(FirmwareVersionParser.isOlder('2.0.0', '1.9.9')).toBe(false); }); + + it('should compare versions with different formats', () => { + expect(FirmwareVersionParser.isOlder('1.2.3', 'v1.2.4')).toBe(true); + expect(FirmwareVersionParser.isOlder('v1.2.3', 'project@1.2.4+abc')).toBe(true); + expect(FirmwareVersionParser.isOlder('1.2.3', '1.2.3+build')).toBe(false); + }); + + it('should return null for unparseable versions', () => { + expect(FirmwareVersionParser.isOlder('invalid', '1.2.3')).toBeNull(); + expect(FirmwareVersionParser.isOlder('1.2.3', 'invalid')).toBeNull(); + }); }); describe('isNewFormat', () => { diff --git a/src/api/routes.ts b/src/api/routes.ts index ae930c3..0bd889e 100644 --- a/src/api/routes.ts +++ b/src/api/routes.ts @@ -385,13 +385,14 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) if (shouldNotify) { try { const latest = firmware.getLatestFirmware(project); - if (latest) { + if (latest && FirmwareVersionParser.extractSemver(latest.version)) { const connectedDevices = tcpService.getConnectedDevices(); const notified: Array<{ address: string; version: string }> = []; for (const device of connectedDevices) { if (device.project?.toLowerCase() === project.toLowerCase() && device.semver) { - if (FirmwareVersionParser.isOlder(device.semver, latest.version)) { + const isOlderResult = FirmwareVersionParser.isOlder(device.semver, latest.version); + if (isOlderResult === true) { await tcpService.sendApiCallToDevice(device.address, 'updateReady', {}); notified.push({ address: device.address, version: device.semver }); telemetry.recordFirmwareNotify(device.address, project, latest.version); @@ -464,6 +465,12 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) return; } + const latestSemver = FirmwareVersionParser.extractSemver(latest.version); + if (!latestSemver) { + res.status(500).json({ error: 'Latest version format is invalid, cannot compare versions' }); + return; + } + const connectedDevices = tcpService.getConnectedDevices(); const notified: Array<{ address: string; version: string }> = []; @@ -488,7 +495,14 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) continue; } - const shouldNotify = force || FirmwareVersionParser.isOlder(device.semver, latest.version); + const isOlderResult = FirmwareVersionParser.isOlder(device.semver, latest.version); + + if (isOlderResult === null) { + skipped.push({ address: device.address, reason: 'version comparison failed' }); + continue; + } + + const shouldNotify = force || isOlderResult; if (!shouldNotify) { skipped.push({ address: device.address, reason: 'already up to date' }); @@ -542,6 +556,13 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) 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. This version must match the FIRMWARE_SEMVER in your device firmware.' + }); + return; + } + const adminAddresses = getAdminAddresses(); if (adminAddresses.length === 0) { res.status(503).json({ error: 'Admin addresses not configured' }); @@ -619,7 +640,8 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService) for (const device of connectedDevices) { if (device.project?.toLowerCase() === project.toLowerCase() && device.semver) { - if (FirmwareVersionParser.isOlder(device.semver, version)) { + const isOlderResult = FirmwareVersionParser.isOlder(device.semver, version); + if (isOlderResult === true) { await tcpService.sendApiCallToDevice(device.address, 'updateReady', {}); notified.push({ address: device.address, version: device.semver }); telemetry.recordFirmwareNotify(device.address, project, version); diff --git a/src/service/FirmwareVersionParser.ts b/src/service/FirmwareVersionParser.ts index c5b6e26..615b3eb 100644 --- a/src/service/FirmwareVersionParser.ts +++ b/src/service/FirmwareVersionParser.ts @@ -17,6 +17,7 @@ export interface ParsedFirmwareVersion { } const FIRMWARE_VERSION_REGEX = /^([a-z0-9_-]+)@(\d+\.\d+\.\d+)(?:\+([a-f0-9]+))?$/i; +const PLAIN_SEMVER_REGEX = /^v?(\d+)\.(\d+)\.(\d+)$/; export class FirmwareVersionParser { /** @@ -47,15 +48,64 @@ export class FirmwareVersionParser { } /** - * Compare two semver strings + * Extract MAJOR.MINOR.PATCH from a version string that may be: + * - Plain semver: "1.2.3" or "v1.2.3" + * - Full device format: "project@1.2.3+hash" + * - With build suffix: "1.2.3+hash" + * + * Returns null if the version cannot be parsed + */ + static extractSemver(versionString: string): string | null { + if (!versionString) return null; + + // Try plain semver first (with optional leading v) + const plainMatch = versionString.match(PLAIN_SEMVER_REGEX); + if (plainMatch) { + const [, major, minor, patch] = plainMatch; + return `${major}.${minor}.${patch}`; + } + + // Try full device format: project@semver+hash + const fullMatch = versionString.match(/^[a-z0-9_-]+@(\d+\.\d+\.\d+)(?:\+[a-z0-9]+)?$/i); + if (fullMatch) { + return fullMatch[1]; + } + + // Try semver with build suffix: semver+hash (any alphanumeric suffix) + const buildMatch = versionString.match(/^(\d+\.\d+\.\d+)\+[a-z0-9]+$/i); + if (buildMatch) { + return buildMatch[1]; + } + + return null; + } + + /** + * Validate that a string is plain semver MAJOR.MINOR.PATCH (no v prefix, no suffix) + * Returns true if valid, false otherwise + */ + static isPlainSemver(versionString: string): boolean { + if (!versionString) return false; + const match = versionString.match(/^(\d+)\.(\d+)\.(\d+)$/); + return match !== null; + } + + /** + * Compare two version strings, extracting semver from either format * Returns: * - negative if v1 < v2 * - 0 if v1 === v2 * - positive if v1 > v2 + * - null if either version cannot be parsed */ - static compareSemver(v1: string, v2: string): number { - const parts1 = v1.split('.').map(n => parseInt(n, 10)); - const parts2 = v2.split('.').map(n => parseInt(n, 10)); + static compareSemver(v1: string, v2: string): number | null { + const semver1 = this.extractSemver(v1); + const semver2 = this.extractSemver(v2); + + if (!semver1 || !semver2) return null; + + const parts1 = semver1.split('.').map(n => parseInt(n, 10)); + const parts2 = semver2.split('.').map(n => parseInt(n, 10)); for (let i = 0; i < 3; i++) { const diff = (parts1[i] || 0) - (parts2[i] || 0); @@ -66,9 +116,11 @@ export class FirmwareVersionParser { /** * Check if a device version is older than the latest version + * Returns null if versions cannot be compared */ - static isOlder(deviceVersion: string, latestVersion: string): boolean { - return this.compareSemver(deviceVersion, latestVersion) < 0; + static isOlder(deviceVersion: string, latestVersion: string): boolean | null { + const result = this.compareSemver(deviceVersion, latestVersion); + return result !== null ? result < 0 : null; } /** diff --git a/tools/firmware/upload.ts b/tools/firmware/upload.ts index 463bcd2..556d1c4 100644 --- a/tools/firmware/upload.ts +++ b/tools/firmware/upload.ts @@ -106,6 +106,10 @@ async function uploadFirmware( return response.json() as Promise; } +function validatePlainSemver(version: string): boolean { + return /^\d+\.\d+\.\d+$/.test(version); +} + async function main() { const args = process.argv.slice(2); @@ -113,6 +117,10 @@ async function main() { console.error('Usage: ts-node upload.ts [--notify]'); console.error('Example: ts-node upload.ts GarageDoor 1.2.3 firmware.bin'); console.error(' ts-node upload.ts GarageDoor 1.2.3 firmware.bin --notify'); + console.error(''); + console.error('Version must be plain semver MAJOR.MINOR.PATCH (e.g., 1.2.3)'); + console.error('Do not include project name, v prefix, or build suffix'); + console.error('This version must match the FIRMWARE_SEMVER in your device firmware'); process.exit(1); } @@ -125,6 +133,18 @@ async function main() { process.exit(1); } + if (!validatePlainSemver(version)) { + console.error(`Error: Version "${version}" is not valid plain semver`); + console.error('Version must be MAJOR.MINOR.PATCH (e.g., 1.2.3)'); + console.error('Do not include:'); + console.error(' - Project name (not "garagedoor@1.2.3")'); + console.error(' - v prefix (not "v1.2.3")'); + console.error(' - Build suffix (not "1.2.3+abc123")'); + console.error(''); + console.error('This version must match the FIRMWARE_SEMVER constant in your device firmware.'); + process.exit(1); + } + console.log(`Project: ${project}`); console.log(`Version: ${version}`); console.log(`File: ${firmwarePath}`);