\n\n# @asylia/hw-trezor\n\nTrezor hardware-wallet adapter for the Asylia self-custody platform. It wraps\n`@trezor/connect-web` behind a narrow Asylia-shaped API for initialization,\nenvironment checks, xpub export, address display, live events, and PSBT signing.\n\nThe wallet UI never imports Trezor Connect directly. Every device interaction\nthat can influence a Bitcoin vault passes through this package, making the\nsecurity boundary easy to audit and reuse outside the Vue app.\n\nKeywords: Trezor, Bitcoin hardware wallet, Trezor Connect, PSBT signing, P2WSH\nmultisig, BIP-48, BIP-380 descriptor, xpub export, self-custody, TypeScript.\n\n## Maintainer And Support\n\n`@asylia/hw-trezor` is maintained by [Asylian21](https://github.com/Asylian21).\n\n> **Support Asylia Bitcoin tooling**\n>\n> If this work helps your wallet, audit, integration, or research, you can\n> support ongoing development with a Bitcoin donation:\n> `bc1qrdchup8497xz0972v35q4nr0fx5egghf0z23c3`\n\n## Status\n\n`1.0.0`. Initialization, environment detection, xpub export, address\ndisplay, live events, and `wsh(sortedmulti(...))` PSBT signing are implemented.\n\n## Installation\n\n```bash\nnpm install @asylia/hw-trezor @asylia/btc-core\n```\n\n## Why This Package Exists\n\nHardware-wallet code is a hard security boundary:\n\n- It speaks to a physical device the user trusts.\n- It requests xpub material and master fingerprints.\n- It maps PSBT data into device prompts.\n- It receives signatures that may authorize Bitcoin spends.\n- It must normalize vendor failures into predictable application states.\n\nPulling the Trezor integration out of the wallet SPA keeps the audited surface\nsmall, isolates vendor SDK upgrades, and leaves room for a future Capacitor\nsigner to reuse the same logic.\n\n## Public API\n\nEvery public export is defined by the source barrel and published from the\npackage root.\n\n| Export | Purpose |\n| --- | --- |\n| `initTrezor(manifest)` | Idempotent Trezor Connect bootstrap. |\n| `detectTrezorEnvironment()` | Browser/transport capability probe for UX guidance. |\n| `recommendationFromEnvironment()` | Converts environment state into recommended next steps. |\n| `exportTrezorRoot({ derivationPath, scriptType })` | Prompts the device for the BIP-48 multisig root xpub and master fingerprint. |\n| `displayWshSortedMultiAddress(input)` | Requests an on-device display of a derived P2WSH multisig address. |\n| `signWshSortedMultiPsbt(input)` | Translates a PSBT v2 into Trezor's transaction format, collects signatures, verifies ownership, and merges partial signatures back into the PSBT. |\n| `subscribeToTrezorEvents(handler)` | Streams device, prompt, and transport events for UI steppers and diagnostics. |\n| Public types | Adapter result, manifest, device info, script type, export/sign/display inputs, and normalized errors. |\n\nAll high-level flows return `AdapterResult`: `{ ok: true, data }` or\n`{ ok: false, error }`. UI code should render adapter errors directly instead of\ncatching and pattern-matching raw vendor exceptions.\n\n## Example\n\n```ts\nimport {\n exportTrezorRoot,\n initTrezor,\n signWshSortedMultiPsbt,\n} from '@asylia/hw-trezor';\n\nawait initTrezor({\n appName: 'Asylia Wallet',\n appUrl: 'https://wallet.asylia.io',\n email: 'support@asylia.io',\n});\n\nconst exported = await exportTrezorRoot({\n derivationPath: \"m/48'/0'/0'/2'\",\n scriptType: 'p2wsh',\n});\n\nif (exported.ok) {\n const { xpub, masterFingerprint, device } = exported.data;\n // Persist xpub + masterFingerprint as signer metadata.\n}\n\nconst signed = await signWshSortedMultiPsbt({\n psbtBase64,\n vault: {\n requiredSignatures: 2,\n keys: descriptorKeys,\n },\n signerFingerprint: 'd34db33f',\n});\n```\n\n## Derivation and Script Policy\n\nAsylia targets native-SegWit BIP-48 multisig only:\n\n```text\nwsh(sortedmulti(...)) at m/48'/0'/0'/2'\n```\n\nFrom that xpub depth, the wallet derives receive and change addresses with\nunhardened `/0/i` and `/1/i` children without asking the device again.\n\nThe nested-SegWit BIP-48 branch (`m/48'/0'/0'/1'`, `sh(wsh(...))`) is not\nsupported. The `TrezorScriptType` union intentionally exposes only `p2wsh`.\n\n## Master Fingerprint\n\nTrezor returns descriptor-shaped public-key metadata. The adapter parses the\nleading 8-character hex fingerprint and returns it as\n`masterFingerprint`, which is the signer identity Asylia stores for matching\nfuture signatures.\n\nTrezor Model One cannot return the descriptor field required for this flow. The\nadapter returns `descriptor_unavailable` so the wallet can show precise upgrade\nguidance instead of a generic failure.\n\n## Web Transport Model\n\nThe adapter uses Trezor Connect's `coreMode: 'auto'` resolution:\n\n- local Trezor service or Suite transport available: iframe mode with event\n streaming into the SPA,\n- otherwise: popup mode, with Trezor Connect owning browser-side prompts.\n\nPIN, passphrase, permission, and export approval prompts are owned by Trezor\nConnect and the physical Trezor device. `@trezor/connect-web` is USB-only in the\nbrowser; Bluetooth belongs to a future native mobile signer path.\n\n## Signing Model\n\nTrezor Connect does not sign PSBT payloads directly. It signs a Trezor-native\ntransaction shape. `signWshSortedMultiPsbt` bridges that gap:\n\n1. Inspect the PSBT v2 with `@asylia/btc-core`.\n2. Translate inputs into Trezor `SPENDWITNESS` entries with multisig metadata.\n3. Translate external outputs and vault change outputs into device-readable\n prompts. No-change spends are represented without a wallet change output.\n4. Preserve PSBT version and locktime so signatures are over the transaction the\n wallet will actually finalize.\n5. Verify returned signatures against the expected cosigner pubkeys.\n6. Re-attribute signatures when a different valid passphrase wallet signs from\n the same physical device.\n7. Merge verified signatures back into the PSBT with the SIGHASH_ALL byte.\n\nIf no vault cosigner owns a returned signature, the adapter refuses it. Broken\nor misattributed partial signatures should never reach the proposal store.\n\nFor native-SegWit PSBTs, the adapter does not ship previous full transactions\nas Trezor `refTxs`; witness UTXO data from the inspected PSBT is enough for the\ndevice signing flow. That keeps the package dependency boundary narrow:\nPSBT/transaction parsing remains in `@asylia/btc-core`, while this package owns\nonly the Trezor Connect mapping and post-flight signature attribution.\n\n## Error Model\n\nVendor failures are normalized into stable `TrezorErrorCode` values:\n\n```text\ninit_failed | manifest_required | cancelled | device_disconnected |\ndevice_not_found | device_in_use | device_locked | device_timeout |\nfirmware_too_old | descriptor_unavailable | invalid_multisig |\ninvalid_path | message_signing_forbidden_path | transport_unavailable |\nunknown\n```\n\nThe wallet renders the adapter's user-facing message. It should not depend on\nTrezor Connect's raw error strings.\n\n## Not in Scope\n\nThis package does not:\n\n- persist xpubs, fingerprints, or signatures,\n- store seed phrases or private keys,\n- render UI,\n- fetch chain data,\n- build descriptors or PSBTs from scratch,\n- support non-Asylia script families.\n\nDescriptor construction and PSBT helpers live in `@asylia/btc-core`.\n\n## Testing\n\n```bash\nyarn workspace @asylia/hw-trezor type-check\nyarn workspace @asylia/hw-trezor test\n```\n\n## Versioning and Audit Stance\n\nThe package uses semver for stable releases. See [`SECURITY.md`](./SECURITY.md)\nfor the disclosure process and security scope.\n\n## License\n\nMIT - see [`LICENSE`](./LICENSE).\n","readmeFilename":"README.md"}
![\"Asylia\"](\"../../apps/wallet/resources/logo.svg\"){kind=logo}
\n