Architecture — csiPass

Runtime contour

Application firmware

FIDO HID, management HID, WinUSB bulk, optional CCID, autonomous UI, encrypted vault when provisioned.

Rescue

Factory recovery image: management and OTA only. No vault, CTAP, ClientPin, or eFuse symbols.

Companion

Local Gio window. Direct USB management and bulk. No HTTP listener, no cloud account, no approval surface.

csiPass-HIL

Separate operator bench binary. Same shell and USB stack as companion, plus checks catalog, runs, notes, device screenshots, and FIDO/management exercise paths for lab validation. Not a product page inside companion.

LAB contour

Marked -lab images, simulated root material, CDC or lab-card CCID composition, throwaway signing keys. Not production identity.

Board family

csiPass targets the ESP32-S3R8 SoC class used by the Waveshare family — typically 16 MB flash and 8 MB PSRAM on the measured boards — through a firmware board_profile. That is a deliberate lock-in: one firmware class, not “any MCU.”

Measured path today: Waveshare ESP32-S3-LCD-1.47 — 172×320 ST7789 panel, addressable RGB LED, USB Type-A, Confirm on GPIO2, Browse on BOOT/GPIO0. LAB boards fit a DS3231 RTC on GPIO7 (SDA) and GPIO6 (SCL). The four-wire expansion port is reserved for a fingerprint satellite (milestone 18; not implemented).

Same firmware, other boards (open): touch Confirm and Browse without soldering a separate GPIO2 button; round layouts and alternate panel controllers after a board is measured; capability-gated RTC→TOTP and SD→Files so companion and GetInfo show what hardware actually answers.

Roadmap: board family track

All-in-one capacity

One vault layout backs the shipping LAB surfaces and reserves flash for OpenPGP, PIV, and the password vault. Numbers match vault_layout_vnext.hpp / hardware features docs.

Store	Capacity	Working set / notes	Status
Resident passkeys	200	Device page only; wire pages capped	LAB
Site-side metadata	100	Bounded page; no credential secret leaves	LAB
OTP	200	Secrets and codes never return over the wire	LAB
SSH FIDO-sk	100	Summary page; private scalar never returns	LAB
Activity	1000	Filtered visible page only	LAB
Encrypted SD safe	1024 objects / index	Root files + shelves share the budget	LAB when SD present
OpenPGP	3 key roles + objects	CCID card application	LAB card image
PIV	24 key slots + containers	CCID card application	LAB card image
Password Manager	~5.5 MiB reserved	On-device vault / Safe-Type	Open (M19)

What ships in LAB builds

CTAPHID plus CTAP2 ES256, Ed25519, RS256, ML-DSA-44, and ML-DSA-65; ML-DSA-87 excluded
Client PIN, credential management, credProtect, hmac-secret, hmac-secret-mc, minPinLength
CTAP1/U2F only in the explicitly insecure lab image
HOTP and TOTP; codes on glass; TOTP refuses an untrusted RTC
Encrypted microSD file safe with streaming bulk/HID transfer
Autonomous Starting, prompts, results, local browsing, ownership erase
Native companion inventory, Files, Activity, RTC, display, PIN/UV, signed OTA, guarded REC-LAB

Known thin spots

SoC lock-in to ESP32-S3R8 board family; measured board still LCD-1.47 + GPIO2 Confirm
Touch / round / AMOLED profiles open until a second board is measured; the LilyGo T-Display-S3-AMOLED-Plus (H754) is the next target
Unreleased LAB; no FIDO certification; U2F lab-only
Host can still see management metadata; card APDUs are cleartext after VERIFY
macOS companion deferred (no Mac host)

Not production-ready

Release gates

Secure Boot v2, flash encryption, eFuse secure-version anti-rollback, production OTA/catalog keys, irreversible production provisioning, commercial attestation identity/AAGUID/VID/PID, interoperability, side-channel review, and FIDO certification are incomplete. Signed management OTA and factory rescue exist as a software path; ordinary images reject the lab throwaway signing key.

Read Security

Short comparison

Marketing-honest, not a full competitive matrix.

Question	csiPass	YubiKey	PicoKeys / pico-fido
On-device WYSIWYS display	Yes (built-in glass)	No / limited models	Depends on board
Source-available firmware	Yes	No	Yes
Host companion	Optional local	Vendor tools / none	Varies
Target SoC	ESP32-S3R8 board family	Vendor silicon	RP2040 / board ecosystem
Post-quantum algos on device	ML-DSA-44/65 in tree	Vendor roadmap	Project-dependent
Product maturity	Lab prototype	Shipping certified	DIY / ecosystem

Licensing

The repository is deliberately not under a single license. LICENSE is authoritative.

Path	License
`firmware/`, `deploy/`, documentation, public site	PolyForm Shield License 1.0.0
`cmd/`, `internal/`	GNU Affero General Public License v3.0

PolyForm Shield permits reading, building, changing, running, auditing, and internal deployment, but not using the work to provide a competing authenticator product.

Commercial use of the companion binaries the project distributes for Windows, Linux, and macOS requires a separate license. That license is the right to use the finished build, not a second edition, and the program does not check it. A companion built from source is outside those terms and stays AGPL-3.0-only. Firmware and the operator HIL tool stay on the licenses in the table above.

Every published release converts to open source four years after its publication date — code under GPL-3.0-or-later, documentation under CC BY 4.0; the commitment and its exact terms live in LICENSE.

The csiPass name is licensed to no one. A fork may state its origin factually, but it ships under its own name — the boundary is written in TRADEMARK.md.

Contributions require the CLA.

Commercial licensing, OEM, custom boards, or redistribution: a.bespalov@csilab.ru — this is the intended path for paid / product engagements.

Write about licensing Product contact

Sources of truth

Repository — code and exact development history
docs/architecture.md — layers and trust boundaries
docs/security.md — security baseline
Documents — printable manuals and geek shelf
Updates — guides and download catalog
Roadmap — open public scale

One stack. Clear trust boundaries.