Skip to content

feat: add passphrase session support#1

Open
redsh4de wants to merge 3 commits into
cake-tech:trunkfrom
redsh4de:passphrase-session
Open

feat: add passphrase session support#1
redsh4de wants to merge 3 commits into
cake-tech:trunkfrom
redsh4de:passphrase-session

Conversation

@redsh4de

@redsh4de redsh4de commented Jun 8, 2026

Copy link
Copy Markdown

What

Adds passphrase support to both protocol clients.

Previously the package hardcoded an empty passphrase: V1 auto-ACKED every PassphraseRequest with "", and THP sent ThpCreateNewSession(passphrase: "") during pairing.

How

  • New TrezorPassphrase type with three cases. empty() selects the standard wallet. value() carries a passphrase typed in the app. onDevice() requests entry on the Trezor itself. Typed passphrases are NFKD-normalized and limited to 50 bytes, matching trezor-connect.

  • New TrezorClient.createSession(passphrase) on both clients. Connecting and creating a session are now separate steps. createChannel() only sets up the connection and pairing. createSession() then ties a passphrase to it. On V1 the device asks for the passphrase at the first call that needs the seed. The client answers from what was given to createSession. V1 sessions can also be resumed with a previously returned session id. The user is then not asked again after a reconnect.

  • The clients now read the device's Features and expose passphraseAlwaysOnDevice. V1 gets them from Initialize. THP requests them after connecting. When the setting is on, the session request is sent without a passphrase field. That is the only form the firmware accepts.

  • THP error frames now throw a typed TrezorChannelException instead of plain Exception strings. Apps can tell the connection died and reconnect.

  • A passphrase typed in the app stays in memory only until used once. If the device asks again later, the client throws TrezorSessionExpiredException and the app must ask the user again. Only the session id, which contains no secret, may be kept.

Notes

  • Consumers must call createSession after createChannel (see example app).

redsh4de added 3 commits June 10, 2026 11:40
Add TrezorClient.cancel() so the host can abort a prompt the device is showing (e.g. on-device passphrase entry) and send it back to its home screen
@redsh4de redsh4de force-pushed the passphrase-session branch from ad6bea3 to cc156c9 Compare June 10, 2026 10:21
@redsh4de

Copy link
Copy Markdown
Author

@konstantinullrich Would appreciate a look when you have a chance.

This adds on-device entry support and NFKD normalization for passphrases to match trezor-suite's reference implementation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant