Sapwood

Shape your signer -- browser-based management UI for the Heartwood ESP32 signing device.

Connect your Heartwood via USB, open sapwood.dev in Chrome, and manage your signing device from the browser. No server, no install, no dependencies.

Features

• Masters -- view provisioned master slots, npubs, and derivation modes
• Clients -- list, revoke, and update TOFU-approved client policies
• Firmware -- OTA updates with SHA-256 verification and progress bar
• Logs -- real-time ESP-IDF log output from the device
• Factory Reset -- erase all keys (requires physical button confirmation)

How it works

Sapwood connects directly to the ESP32 via the Web Serial API (Chrome/Edge 89+). It speaks the Heartwood frame protocol over USB -- the same protocol used by the provision CLI and bridge. No server component, no bridge required.

Browser (Sapwood)  --Web Serial-->  ESP32 USB-Serial-JTAG

The frame protocol is a TypeScript port of heartwood-common/src/frame.rs, with 19 tests verifying byte-level compatibility with the Rust implementation.

Security

Secrets never leave the ESP32. The serial protocol only carries public keys, policy metadata, unsigned events, and signatures. All destructive operations (factory reset, OTA, provisioning) require physical button confirmation on the device. A compromised web UI cannot extract keys or perform destructive actions without someone pressing the button.

Quick start

Visit forgesworn.github.io/sapwood in Chrome or Edge, plug in your Heartwood, and click Connect USB.

Local development

git clone https://github.com/forgesworn/sapwood.git
cd sapwood
npm install
npm run dev       # dev server at localhost:5173
npm test          # 19 frame protocol tests
npm run build     # production build to dist/

Stack

• Svelte 5 (runes mode) -- compiles to vanilla JS, 21KB gzipped total
• Vite -- build tool
• TypeScript (strict mode)
• Vitest -- test framework
• Web Serial API -- Chrome/Edge 89+

Ecosystem

Sapwood is part of the Heartwood signing device ecosystem:

Named after the living, active layer of wood between bark and heartwood.

Browser support

Web Serial API is required. Currently supported in:

• Chrome 89+
• Edge 89+
• Opera 76+

Firefox and Safari do not support Web Serial. BLE connectivity for portable mode is planned.

Licence

MIT