Heron Device Identity System

Version: 0.3.0

Date: 2026-06-20

Status: Current. Cryptographic device attestation, fully offline

Previous version (v0.2.1): Sticker codes with cloud activation.

That system is deprecated. See docs/internal/engineering/local-crypto-provisioning.md

for the replacement design.

Overview

Every Heron device has a unique cryptographic identity burned into its chip

during manufacturing. When you set up the device, your browser verifies this

identity using a challenge-response handshake over USB. No server is involved.

The sticker on the back now shows a serial number. It identifies the device

but has no security role.

How it works

1. Manufacturing: A per-device ECDSA P-256 key pair is generated. The

private key is stored on the device. The public key is signed by

Northsline's root key to form a device certificate.

1. Setup: The setup page generates a random challenge (a 32-byte nonce)

and sends it to the device over USB. The device signs the challenge with

its private key and returns the signature plus its certificate.

1. Verification: The setup page verifies the certificate against the

Northsline root public key (embedded in the page), then verifies the

challenge signature against the device's public key. Both checks use

Web Crypto (SubtleCrypto). Standard browser APIs, no dependencies.

1. Result: If both checks pass, the device is genuine. The setup page

proceeds to Wi-Fi configuration. No network call was made.

What changed from v0.2.1

• Removed: Cloud activation backend (POST /activate, codes.db)
• Removed: Sticker codes as security tokens (now just serial numbers)
• Added: ECDSA P-256 device attestation (challenge-response over USB)
• Added: Root key infrastructure (keygen.py, root-key.ts)
• Result: Zero network calls during setup. Fully offline.

Serial number format

The sticker now shows an 8-byte hex serial number (e.g., 75E409665340A674).

This is printed on the device for reference. It has no security function: the cryptographic identity is what proves the device is genuine.

Security model

• Prevents: Counterfeit devices (can't produce valid signature without

the private key burned into the chip)

• Prevents: Replay attacks (random nonce, one-time use)
• Prevents: Server compromise (there is no server)
• Does not prevent: Physical extraction of the private key via chip

decapsulation (requires specialized lab equipment)

• Does not prevent: Firmware reflash with attacker code (secure boot

is a separate future decision)

Manufacturing flow

1. Generate root key pair: python keygen.py --init-root (once)
2. Per device: python keygen.py --device generates keys + certificate
3. Flash firmware, burn keys to device: python flash_known.py
4. Print sticker with serial number, ship

Changelog

Date	Version	Change
2026-05-31	v0.1.0	Initial draft
2026-06-01	v0.2.0	Single-use sticker codes + cloud activation
2026-06-07	v0.2.1	Dashboard decoupled from sticker codes
2026-06-20	v0.3.0	Replaced sticker codes with cryptographic device attestation. Backend removed. Fully offline.