Architecture
Firmware on Waveshare ESP32-S3-LCD-1.47 owns FIDO HID, CTAP parsing, the encrypted credential vault, the ST7789 trusted UI, Confirm / Browse buttons, and the status LED. Drawing and approval do not depend on any host application.
Companion is an optional Go service on loopback with a native WebView shell. It opens a dedicated USB management channel for inventory, PIN / UV policy, display preferences, and erase guidance. It cannot export private keys, PINs, seeds, or decrypted vault records.
Hardware target
Current development board: Waveshare ESP32-S3-LCD-1.47 — ESP32-S3R8, 16 MB flash, 8 MB PSRAM, 172×320 ST7789 panel, addressable RGB LED, USB Type-A, dedicated Confirm on GPIO2, Browse on BOOT (GPIO0).
Board-family display variants are planned once the panel abstraction is exercised on a second controller. Expansion-port peripherals (RTC, fingerprint) are later roadmap milestones.
Implemented today
Development builds (not a public release). Exact identities live in the repository build journal.
- CTAPHID framing and a CTAP2 ES256 MakeCredential / GetAssertion path
- Client PIN, credential management,
credProtect,hmac-secret,minPinLength - CTAP1 / U2F with a derived attestation certificate (development material)
- AES-256-GCM vault rooted in a provisioned HMAC_UP eFuse; 64 resident slots; non-discoverable credentials carried in the credential ID
- Autonomous device UI: Ready, approval, result, local browse, security posture
- Management protocol: Display settings, PIN / UV policy, credential rename, erase / recovery copy
- Screensaver presets: None, csiPass Logo, Breathing Dot (in phase with the idle LED)
- Companion milestones 0–1: shell, Passkeys / Device panels, WaitingOnDevice without host Approve
Not ready
- Secure Boot v2, flash encryption, and irreversible production provisioning
- Signed recovery image and authenticated firmware-update transport
- Interoperability, side-channel, or FIDO certification review
- Commercial attestation identity, VID/PID, and sealed industrial design
Until those land, treat every build as a lab prototype.
Licensing
The repository is not under a single license. Path map from
LICENSE:
| Path | License |
|---|---|
firmware/**, deploy/**, docs, this site |
PolyForm Shield 1.0.0 |
cmd/**, internal/** (companion) |
GNU Affero General Public License v3.0 |
PolyForm Shield permits reading, building, changing, running, auditing, and internal deployment. It does not permit using the work to provide a competing authenticator product, hardware or software, whether or not you charge for it. Neither Shield nor the project’s AGPL choice pretends to be OSI “open source.”
Contributions require the CLA so commercial licenses remain possible. Inquiries: a.bespalov@csilab.ru.
Source of truth
- GitHub repository
- Tracked docs under
docs/— features, security, management protocol, roadmap, user manual - Updates — roadmap snapshot and download catalog