api/firmware: support host passphrase entry - #188
Open
benma-agent wants to merge 2 commits into
Open
benma-agent wants to merge 2 commits into
benma-agent wants to merge 2 commits into
Conversation
Disconnecting after an intermediate signing response leaves the firmware waiting for a continuation while the device stays powered. On reconnect, the old workflow consumes the first attestation request and returns an encrypted error, causing the attestation check to fail. Send HWW_REQ_RESET (0x03) after version discovery and before attestation, unlock, and Noise pairing on firmware v9.28.0 or newer. Keep the helper private, retry BUSY responses once per second, and require an ACK without a payload. Older firmware keeps its existing connection flow. Add a simulator regression that disconnects with signing unfinished, reconnects to the same running process, checks the real attestation response, pairs, and reads the root fingerprint. Older simulator versions exercise ordinary reconnects. The regression uses the locally built v9.28.0 C simulator and fails if the reset call is disabled. Firmware counterpart: BitBoxSwiss/bitbox02-firmware#2111
This was referenced Sep 20, 2026
Unlock through the paired Noise channel on firmware 9.28.0 and later, keeping the legacy unlock command for older firmware. The new workflow starts device entry when the optional passphrase feature is enabled and lets the host request device consent to enter the passphrase on the host. Uninitialized and already unlocked devices finish immediately. Expose two callbacks through PassphraseConfig. The availability callback receives a callable that queues a host-entry request and wakes the polling loop without doing transport I/O. Notify once per entry phase, withdraw when consent starts or device entry finishes, and offer a fresh callable on retry. Separate buffered channels keep delayed or duplicate clicks from affecting later phases. Without an availability callback, request host entry once automatically and fall back to device entry on rejection or cancellation. Call the blocking input callback only after device approval. A string, including the empty string, submits input; nil cancels and resumes device entry. The device confirms the actual passphrase. Keep protocol handling and device-entry polling inside the library, holding the API lock for the entire unlock so other queries cannot interrupt its continuations. Notify clients when device passphrase entry finishes, before confirmation starts. This lets the app show the confirmation prompt even when device entry wins a simultaneous host-entry request. Use the device lifetime context to release host input on Close, and make Close idempotent because disconnect handling and unlock cancellation can both close the transport. Ignore repeated pairing approvals to avoid starting duplicate unlocks. Clear temporary protobuf plaintext buffers after each query. On local failure, withdraw availability, attempt RESET and close the connection; reconnect uses the preceding session-reset commit. Keep resetSession's explicit firmware version check independent of host-passphrase support. Add simulator coverage for initialization, device passphrase entry, disabled passphrases, simultaneous host requests, stale clicks, repeated unlocks and repeated closes.
benma-agent
force-pushed
the
benma-agent/host-passphrase
branch
from
September 20, 2026 09:00
00d8217 to
3a80376
Compare
benma
marked this pull request as ready for review
September 25, 2026 15:48
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Support host entry of the optional BIP39 passphrase on firmware 9.28.0 and later. Device entry remains available while the host can request approval to enter the passphrase. Invoke host input only after device consent, and let the device confirm the submitted value before unlocking.
Keep polling and protocol handling in the library. Withdraw host-entry availability during consent and confirmation, notify clients when device entry finishes, and handle cancellation, retries and reconnects without reusing stale requests. Preserve the legacy unlock flow on older firmware.
Includes the session-reset prerequisite from #187.
Related PRs: