Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,17 @@ ZBGW_DIAG_TOKENS=
# R2_SECRET_ACCESS_KEY=
# R2_BUCKET_NAME=garage-camera
# R2_PUBLIC_URL=
# Global firmware defaults (do NOT repurpose these for a single project):
# R2_FIRMWARE_BUCKET_NAME= # Optional: separate bucket for firmware (defaults to R2_BUCKET_NAME)
# R2_FIRMWARE_PUBLIC_URL= # Optional: public URL for firmware bucket (e.g., https://pub-xxxx.r2.dev)
#
# Per-project firmware overrides (project "zigbee-gateway" → suffix ZIGBEE_GATEWAY):
# R2_FIRMWARE_BUCKET_NAME__ZIGBEE_GATEWAY=esp-firmware
# R2_FIRMWARE_PUBLIC_URL__ZIGBEE_GATEWAY=https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev
# Optional bucket-scoped credentials (fall back to global R2_* if unset):
# R2_ACCESS_KEY_ID__ZIGBEE_GATEWAY=
# R2_SECRET_ACCESS_KEY__ZIGBEE_GATEWAY=
# R2_ACCOUNT_ID__ZIGBEE_GATEWAY=

# Firmware upload configuration
FIRMWARE_UPLOAD_MAX_SIZE_MB=10
Expand Down
12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,12 @@ Environment variables (or `application.properties` file):
- `R2_SECRET_ACCESS_KEY` - R2 secret key (REQUIRED for R2)
- `R2_BUCKET_NAME` - R2 bucket name (default: `garage-camera`)
- `R2_PUBLIC_URL` - Public URL for R2 bucket (e.g., `https://pub-xxx.r2.dev`)
- `R2_FIRMWARE_BUCKET_NAME` - Optional separate bucket for firmware (defaults to `R2_BUCKET_NAME`)
- `R2_FIRMWARE_BUCKET_NAME` - Optional **global** firmware bucket default (defaults to `R2_BUCKET_NAME`; not project-specific)
- `R2_FIRMWARE_PUBLIC_URL` - Optional **global** firmware public URL
- Per-project overrides (project `zigbee-gateway` → env suffix `ZIGBEE_GATEWAY`):
- `R2_FIRMWARE_BUCKET_NAME__ZIGBEE_GATEWAY=esp-firmware`
- `R2_FIRMWARE_PUBLIC_URL__ZIGBEE_GATEWAY=https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev`
- Optional bucket-scoped creds: `R2_ACCESS_KEY_ID__ZIGBEE_GATEWAY`, `R2_SECRET_ACCESS_KEY__ZIGBEE_GATEWAY`, `R2_ACCOUNT_ID__ZIGBEE_GATEWAY`

- **Passkey (GarageDoorKey):**
- `PASSKEY_RP_ID` - Relying party ID (default: percolate.one)
Expand Down Expand Up @@ -136,8 +141,9 @@ reserved for a future per-device P-256 signing scheme (admin-approved pubkey); n

**OTA:** Upload project `zigbee-gateway` via the existing firmware coordinator /
`npm run firmware:upload zigbee-gateway <semver> firmware.bin`. Devices (or tooling) can query
`GET /api/firmware/zigbee-gateway/latest` → `{version,url,sha256,size}`. No special-casing beyond
the project name.
`GET /api/firmware/zigbee-gateway/latest` → `{version,url,sha256,size}`. Set per-project R2 overrides
(`R2_FIRMWARE_BUCKET_NAME__ZIGBEE_GATEWAY` / `R2_FIRMWARE_PUBLIC_URL__ZIGBEE_GATEWAY`) so uploads
land in the `esp-firmware` bucket; other projects keep the global firmware/camera defaults.

### Telemetry Feed & Acknowledgement

Expand Down
24 changes: 21 additions & 3 deletions docs/firmware-ota.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,30 @@ The OTA update flow consists of three main steps:
Firmware OTA requires the following environment variables:

- `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`: Cloudflare R2 credentials
- `R2_FIRMWARE_BUCKET_NAME`: Bucket name for firmware storage (optional, defaults to `R2_BUCKET_NAME`)
- `R2_FIRMWARE_PUBLIC_URL`: Public URL for the firmware bucket (e.g., `https://pub-xxxx.r2.dev`)
- `R2_FIRMWARE_BUCKET_NAME`: **Global** firmware bucket default (optional, defaults to `R2_BUCKET_NAME`)
- `R2_FIRMWARE_PUBLIC_URL`: **Global** firmware public URL (optional)
- If not set, falls back to `R2_PUBLIC_URL`
- If neither is set, uses the private `r2.cloudflarestorage.com` endpoint (devices won't be able to download)

When using a separate firmware bucket (`R2_FIRMWARE_BUCKET_NAME`), you must configure `R2_FIRMWARE_PUBLIC_URL` or `R2_PUBLIC_URL` to allow devices to download firmware. The proxy will log a warning at first firmware upload if no public URL is configured.
### Per-project firmware buckets

Projects can override the global firmware bucket/URL (and optionally credentials) without changing
GarageDoor/Web3E defaults. Project name `zigbee-gateway` maps to env suffix `ZIGBEE_GATEWAY`
(uppercase; non-alphanumeric → `_`):

```bash
R2_FIRMWARE_BUCKET_NAME__ZIGBEE_GATEWAY=esp-firmware
R2_FIRMWARE_PUBLIC_URL__ZIGBEE_GATEWAY=https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev
# Optional if the R2 API token is bucket-scoped:
# R2_ACCESS_KEY_ID__ZIGBEE_GATEWAY=...
# R2_SECRET_ACCESS_KEY__ZIGBEE_GATEWAY=...
# R2_ACCOUNT_ID__ZIGBEE_GATEWAY=...
```

Resolution order for each project: per-project override → global `R2_FIRMWARE_*` → `R2_BUCKET_NAME` / `R2_PUBLIC_URL`.
Do not repurpose the global `R2_FIRMWARE_BUCKET_NAME` / `R2_FIRMWARE_PUBLIC_URL` for a single project.

When a dedicated firmware bucket is used without a public URL, the proxy logs a warning at upload time.

## Firmware Version Format

Expand Down
159 changes: 153 additions & 6 deletions src/__tests__/cloudflare-r2-url.test.ts
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';

const mockSend = vi.fn();
const mockS3Client = vi.fn().mockImplementation(() => ({
send: mockSend,
}));
const mockPutObjectCommand = vi.fn().mockImplementation((input) => input);

vi.mock('@aws-sdk/client-s3', () => ({
S3Client: vi.fn().mockImplementation(() => ({
send: mockSend,
})),
PutObjectCommand: vi.fn(),
S3Client: mockS3Client,
PutObjectCommand: mockPutObjectCommand,
}));

describe('CloudflareR2 URL selection', () => {
Expand All @@ -16,6 +18,8 @@ describe('CloudflareR2 URL selection', () => {
originalEnv = { ...process.env };
mockSend.mockClear();
mockSend.mockResolvedValue({});
mockS3Client.mockClear();
mockPutObjectCommand.mockClear();
vi.resetModules();
});

Expand Down Expand Up @@ -156,7 +160,7 @@ describe('CloudflareR2 URL selection', () => {

expect(consoleWarnSpy).toHaveBeenCalledTimes(1);
expect(consoleWarnSpy).toHaveBeenCalledWith(
expect.stringContaining('R2_FIRMWARE_BUCKET_NAME is set but neither R2_FIRMWARE_PUBLIC_URL nor R2_PUBLIC_URL is configured')
expect.stringContaining('neither R2_FIRMWARE_PUBLIC_URL nor R2_PUBLIC_URL is configured')
);

consoleWarnSpy.mockRestore();
Expand All @@ -183,10 +187,153 @@ describe('CloudflareR2 URL selection', () => {
);

const warningCalls = consoleWarnSpy.mock.calls.filter(call =>
call[0]?.includes?.('R2_FIRMWARE_BUCKET_NAME')
typeof call[0] === 'string' && call[0].includes('neither R2_FIRMWARE_PUBLIC_URL nor R2_PUBLIC_URL')
);
expect(warningCalls).toHaveLength(0);

consoleWarnSpy.mockRestore();
});
});

describe('CloudflareR2 per-project firmware buckets', () => {
let originalEnv: NodeJS.ProcessEnv;

beforeEach(() => {
originalEnv = { ...process.env };
mockSend.mockClear();
mockSend.mockResolvedValue({});
mockS3Client.mockClear();
mockPutObjectCommand.mockClear();
vi.resetModules();
});

afterEach(() => {
process.env = originalEnv;
vi.resetModules();
});

function setBaseEnv(): void {
process.env.R2_ACCOUNT_ID = 'acct-global';
process.env.R2_ACCESS_KEY_ID = 'key-global';
process.env.R2_SECRET_ACCESS_KEY = 'secret-global';
process.env.R2_BUCKET_NAME = 'camera-bucket';
process.env.R2_PUBLIC_URL = 'https://camera.r2.dev';
process.env.R2_FIRMWARE_BUCKET_NAME = 'global-firmware';
process.env.R2_FIRMWARE_PUBLIC_URL = 'https://global-firmware.r2.dev';
}

it('maps zigbee-gateway project to ZIGBEE_GATEWAY env suffix', async () => {
const { projectToEnvSuffix } = await import('../service/CloudflareR2');
expect(projectToEnvSuffix('zigbee-gateway')).toBe('ZIGBEE_GATEWAY');
expect(projectToEnvSuffix('GarageDoor')).toBe('GARAGEDOOR');
});

it('uses per-project bucket and public URL for zigbee-gateway', async () => {
setBaseEnv();
process.env.R2_FIRMWARE_BUCKET_NAME__ZIGBEE_GATEWAY = 'esp-firmware';
process.env.R2_FIRMWARE_PUBLIC_URL__ZIGBEE_GATEWAY =
'https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev';

const { uploadFirmwareToR2, getFirmwareStorageConfig } = await import('../service/CloudflareR2');

const config = getFirmwareStorageConfig('zigbee-gateway');
expect(config.bucket).toBe('esp-firmware');
expect(config.publicUrl).toBe('https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev');

const url = await uploadFirmwareToR2(
'zigbee-gateway',
'firmware/zigbee-gateway/1.0.1/firmware.bin',
Buffer.from('bin')
);

expect(url).toBe(
'https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev/firmware/zigbee-gateway/1.0.1/firmware.bin'
);
expect(mockPutObjectCommand).toHaveBeenCalledWith(
expect.objectContaining({
Bucket: 'esp-firmware',
Key: 'firmware/zigbee-gateway/1.0.1/firmware.bin',
})
);
});

it('falls back to global firmware defaults for other projects (GarageDoor unchanged)', async () => {
setBaseEnv();
process.env.R2_FIRMWARE_BUCKET_NAME__ZIGBEE_GATEWAY = 'esp-firmware';
process.env.R2_FIRMWARE_PUBLIC_URL__ZIGBEE_GATEWAY =
'https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev';

const { uploadFirmwareToR2, getFirmwareStorageConfig } = await import('../service/CloudflareR2');

const config = getFirmwareStorageConfig('GarageDoor');
expect(config.bucket).toBe('global-firmware');
expect(config.publicUrl).toBe('https://global-firmware.r2.dev');

const url = await uploadFirmwareToR2(
'GarageDoor',
'firmware/GarageDoor/1.2.3/firmware.bin',
Buffer.from('bin')
);

expect(url).toBe('https://global-firmware.r2.dev/firmware/GarageDoor/1.2.3/firmware.bin');
expect(mockPutObjectCommand).toHaveBeenCalledWith(
expect.objectContaining({
Bucket: 'global-firmware',
Key: 'firmware/GarageDoor/1.2.3/firmware.bin',
})
);
});

it('does not repurpose global R2_FIRMWARE_* when only per-project vars are set', async () => {
process.env.R2_ACCOUNT_ID = 'acct-global';
process.env.R2_ACCESS_KEY_ID = 'key-global';
process.env.R2_SECRET_ACCESS_KEY = 'secret-global';
process.env.R2_BUCKET_NAME = 'camera-bucket';
delete process.env.R2_FIRMWARE_BUCKET_NAME;
delete process.env.R2_FIRMWARE_PUBLIC_URL;
process.env.R2_FIRMWARE_BUCKET_NAME__ZIGBEE_GATEWAY = 'esp-firmware';
process.env.R2_FIRMWARE_PUBLIC_URL__ZIGBEE_GATEWAY =
'https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev';

const { getFirmwareStorageConfig } = await import('../service/CloudflareR2');

// GarageDoor keeps camera/default bucket — global firmware vars untouched/unset
expect(getFirmwareStorageConfig('GarageDoor').bucket).toBe('camera-bucket');
expect(getFirmwareStorageConfig('zigbee-gateway').bucket).toBe('esp-firmware');
});

it('supports per-project bucket-scoped credentials', async () => {
setBaseEnv();
process.env.R2_FIRMWARE_BUCKET_NAME__ZIGBEE_GATEWAY = 'esp-firmware';
process.env.R2_FIRMWARE_PUBLIC_URL__ZIGBEE_GATEWAY =
'https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev';
process.env.R2_ACCESS_KEY_ID__ZIGBEE_GATEWAY = 'key-zigbee';
process.env.R2_SECRET_ACCESS_KEY__ZIGBEE_GATEWAY = 'secret-zigbee';
process.env.R2_ACCOUNT_ID__ZIGBEE_GATEWAY = 'acct-zigbee';

const { uploadFirmwareToR2, getFirmwareStorageConfig } = await import('../service/CloudflareR2');

const config = getFirmwareStorageConfig('zigbee-gateway');
expect(config.credentials).toEqual({
accountId: 'acct-zigbee',
accessKeyId: 'key-zigbee',
secretAccessKey: 'secret-zigbee',
});

await uploadFirmwareToR2(
'zigbee-gateway',
'firmware/zigbee-gateway/1.0.1/firmware.bin',
Buffer.from('bin')
);

expect(mockS3Client).toHaveBeenCalledWith(
expect.objectContaining({
endpoint: 'https://acct-zigbee.r2.cloudflarestorage.com',
credentials: {
accessKeyId: 'key-zigbee',
secretAccessKey: 'secret-zigbee',
},
})
);
});
});
61 changes: 59 additions & 2 deletions src/__tests__/firmware-api.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,29 @@ describe('Firmware API', () => {
process.env.TELEMETRY_DB_PATH = TEST_TELEMETRY_DB;

vi.mock('../service/CloudflareR2', () => ({
uploadToR2: vi.fn(async (key: string, body: Buffer) => {
uploadToR2: vi.fn(async (key: string) => {
return `https://example.r2.dev/${key}`;
}),
uploadFirmwareToR2: vi.fn(async (project: string, key: string) => {
if (project === 'zigbee-gateway') {
return `https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev/${key}`;
}
return `https://example.r2.dev/${key}`;
}),
isR2Configured: vi.fn(() => true),
getFirmwareBucketName: vi.fn(() => 'test-bucket'),
getFirmwareBucketName: vi.fn((project?: string) =>
project === 'zigbee-gateway' ? 'esp-firmware' : 'test-bucket'
),
getFirmwareStorageConfig: vi.fn((project?: string) => ({
project,
bucket: project === 'zigbee-gateway' ? 'esp-firmware' : 'test-bucket',
publicUrl:
project === 'zigbee-gateway'
? 'https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev'
: 'https://example.r2.dev',
credentials: { accountId: 'a', accessKeyId: 'k', secretAccessKey: 's' },
isDedicatedFirmwareBucket: true,
})),
}));
});

Expand Down Expand Up @@ -221,6 +239,45 @@ describe('Firmware API', () => {
expect(response.body.sha256).toBe(sha256);
expect(response.body.size).toBe(firmware.length);
expect(response.body.uploadedBy).toBe(wallet.address.toLowerCase());
expect(response.body.url).toBe('https://example.r2.dev/firmware/GarageDoor/1.0.0/firmware.bin');
});

it('should store zigbee-gateway firmware against the per-project public bucket URL', async () => {
const firmware = Buffer.from('zigbee firmware bytes');
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:zigbee-gateway:1.0.1:${sha256}:${nonce}`;
const signature = await wallet.signMessage(message);

const response = await request(app)
.post(`/api/firmware/zigbee-gateway?version=1.0.1&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.project).toBe('zigbee-gateway');
expect(response.body.version).toBe('1.0.1');
expect(response.body.sha256).toBe(sha256);
expect(response.body.size).toBe(firmware.length);
expect(response.body.url).toBe(
'https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev/firmware/zigbee-gateway/1.0.1/firmware.bin'
);

const latest = await request(app)
.get('/api/firmware/zigbee-gateway/latest')
.expect(200);

expect(latest.body).toMatchObject({
project: 'zigbee-gateway',
version: '1.0.1',
sha256,
size: firmware.length,
url: 'https://pub-862b54f8a0134f8d8276f74732be8015.r2.dev/firmware/zigbee-gateway/1.0.1/firmware.bin',
});
});

it('should reject duplicate version', async () => {
Expand Down
6 changes: 3 additions & 3 deletions src/api/routes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import express, { Router, Request, Response, NextFunction } from 'express';
import { ASyncService } from '../service/ASyncService';
import { ASyncTCPService } from '../service/ASyncTCPService';
import * as passkey from './passkey';
import { uploadToR2, isR2Configured, getFirmwareBucketName } from '../service/CloudflareR2';
import { uploadToR2, uploadFirmwareToR2, isR2Configured } from '../service/CloudflareR2';
import { randomUUID } from 'crypto';
import { TelemetryService } from '../service/TelemetryService';
import { FirmwareService } from '../service/FirmwareService';
Expand Down Expand Up @@ -652,9 +652,9 @@ export function createRouter(service: ASyncService, tcpService: ASyncTCPService)
return;
}

// Upload to R2
// Upload to R2 (per-project bucket/URL/creds via R2_FIRMWARE_*__PROJECT overrides)
const r2Key = `firmware/${project}/${version}/firmware.bin`;
const url = await uploadToR2(r2Key, body, 'application/octet-stream', getFirmwareBucketName());
const url = await uploadFirmwareToR2(project, r2Key, body);

if (!url) {
res.status(500).json({ error: 'R2 upload failed' });
Expand Down
Loading
Loading