{"_id":"@asylia/hw-ledger","_rev":"3-049c0f04274267219396b435bf972e65","name":"@asylia/hw-ledger","dist-tags":{"latest":"1.0.1"},"versions":{"0.1.0":{"name":"@asylia/hw-ledger","version":"0.1.0","keywords":["bitcoin","ledger","@ledgerhq/ledger-bitcoin","webhid","hardware-wallet","wallet-policy","xpub","bip48","p2wsh","multisig","psbt","psbt-signing","typescript","self-custody","asylia"],"author":{"name":"Asylia"},"license":"MIT","_id":"@asylia/hw-ledger@0.1.0","maintainers":[{"name":"asylion21","email":"infodavidzita@gmail.com"}],"homepage":"https://github.com/Asylia/bitcoin-toolkit/tree/main/packages/hw-ledger#readme","bugs":{"url":"https://github.com/Asylia/bitcoin-toolkit/issues"},"dist":{"shasum":"befbaa2cc18e430a7e65fa8ca0beeb10386690bd","tarball":"https://registry.npmjs.org/@asylia/hw-ledger/-/hw-ledger-0.1.0.tgz","fileCount":8,"integrity":"sha512-a4+kw3QQX/2KmPatogkoX2cMtGYwS8rt7HI2V4BGS8vnWd7M9+hsRSJe+MupGeHR/jRbeY9GOmHJbTTIgMO8xg==","signatures":[{"sig":"MEUCIAhQt4FCjqKnAEOmOX9qL10eyQ76ndw4UzEbMO9a+uCsAiEAxU0RCZ2Z3p4ws5rX2jkkGbmsccKk+AnwajlSqwvzo10=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":207148},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"lint":"eslint .","test":"vitest run","build":"tsup src/index.ts --format esm --dts --sourcemap --clean --out-dir dist --tsconfig tsconfig.build.json","clean":"rimraf dist .turbo node_modules/.tmp","type-check":"tsc --noEmit","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"asylion21","email":"infodavidzita@gmail.com"},"repository":{"url":"git+https://github.com/Asylia/bitcoin-toolkit.git","type":"git","directory":"packages/hw-ledger"},"_npmVersion":"10.9.2","description":"Auditable Ledger hardware-wallet TypeScript adapter for WebHID environment checks, xpub export, wallet-policy registration, address display, and P2WSH multisig PSBT signing.","directories":{},"_nodeVersion":"22.14.0","dependencies":{"tslib":"^2.8.1","bs58check":"^4.0.0","@ledgerhq/errors":"^6.34.0","@ledgerhq/hw-transport":"^6.35.1","@ledgerhq/ledger-bitcoin":"^0.3.1","@ledgerhq/hw-transport-webhid":"^6.35.1"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","rimraf":"^6.1.3","vitest":"^4.1.5","typescript":"^6.0.3","@asylia/btc-core":"*","@vitest/coverage-v8":"^4.1.5"},"peerDependencies":{"@asylia/btc-core":"^0.1.0"},"_npmOperationalInternal":{"tmp":"tmp/hw-ledger_0.1.0_1777723333992_0.027838647325292287","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@asylia/hw-ledger","version":"1.0.0","keywords":["bitcoin","ledger","@ledgerhq/ledger-bitcoin","webhid","web-bluetooth","ble","hardware-wallet","wallet-policy","xpub","bip48","p2wsh","multisig","psbt","psbt-signing","typescript","self-custody","asylia"],"author":{"name":"Asylia"},"license":"MIT","_id":"@asylia/hw-ledger@1.0.0","maintainers":[{"name":"asylion21","email":"infodavidzita@gmail.com"}],"homepage":"https://github.com/Asylia/bitcoin-toolkit/tree/main/packages/hw-ledger#readme","bugs":{"url":"https://github.com/Asylia/bitcoin-toolkit/issues"},"dist":{"shasum":"957eb83f3fad94b8eea9305b1df7964e4478d14c","tarball":"https://registry.npmjs.org/@asylia/hw-ledger/-/hw-ledger-1.0.0.tgz","fileCount":8,"integrity":"sha512-I8mo0fkC7eP/Rzumv8aJjXCS8RH0w7re28fDU/bXYtKJWVUy31FS9gNnIoWJ3Nm+ymcWW9PoDYJ/jPge3mFLDQ==","signatures":[{"sig":"MEUCIQCIkOJf7uOH9OQ0QqTX5Mneu1ZuEXqqTAl28r0o0PduugIgaOvLMDdYgnt3fZx0NWX0fuxCyFTOPe6OXVWfthvJ2EE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":249004},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"9472028259c7ecd4e1becd42fd837267dfdd7fca","scripts":{"lint":"eslint .","test":"vitest run","build":"tsup src/index.ts --format esm --dts --sourcemap --clean --out-dir dist --tsconfig tsconfig.build.json","clean":"rimraf dist .turbo node_modules/.tmp","type-check":"tsc --noEmit","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"asylion21","email":"infodavidzita@gmail.com"},"repository":{"url":"git+https://github.com/Asylia/bitcoin-toolkit.git","type":"git","directory":"packages/hw-ledger"},"_npmVersion":"10.9.2","description":"Auditable Ledger hardware-wallet TypeScript adapter for WebHID/Web Bluetooth environment checks, xpub export, wallet-policy registration, address display, and P2WSH multisig PSBT signing.","directories":{},"_nodeVersion":"22.14.0","dependencies":{"tslib":"^2.8.1","bs58check":"^4.0.0","@ledgerhq/errors":"^6.34.0","@ledgerhq/hw-transport":"^6.35.1","@ledgerhq/ledger-bitcoin":"^0.3.1","@ledgerhq/hw-transport-webhid":"^6.35.1","@ledgerhq/hw-transport-web-ble":"^6.34.1"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","rimraf":"^6.1.3","vitest":"^4.1.5","typescript":"^6.0.3","@asylia/btc-core":"^1.0.0","@vitest/coverage-v8":"^4.1.5"},"peerDependencies":{"@asylia/btc-core":"^1.0.0"},"_npmOperationalInternal":{"tmp":"tmp/hw-ledger_1.0.0_1777891162351_0.3647108215333137","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@asylia/hw-ledger","version":"1.0.1","type":"module","description":"Auditable Ledger hardware-wallet TypeScript adapter for WebHID/Web Bluetooth environment checks, xpub export, wallet-policy registration, address display, and P2WSH multisig PSBT signing.","license":"MIT","author":{"name":"Asylia"},"repository":{"type":"git","url":"git+https://github.com/Asylia/bitcoin-toolkit.git","directory":"packages/hw-ledger"},"homepage":"https://github.com/Asylia/bitcoin-toolkit/tree/main/packages/hw-ledger#readme","bugs":{"url":"https://github.com/Asylia/bitcoin-toolkit/issues"},"keywords":["bitcoin","ledger","@ledgerhq/ledger-bitcoin","webhid","web-bluetooth","ble","hardware-wallet","wallet-policy","xpub","bip48","p2wsh","multisig","psbt","psbt-signing","typescript","self-custody","asylia"],"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsup src/index.ts --format esm --dts --sourcemap --clean --out-dir dist --tsconfig tsconfig.build.json","type-check":"tsc --noEmit","lint":"eslint .","test":"vitest run","test:coverage":"vitest run --coverage","clean":"rimraf dist .turbo node_modules/.tmp"},"peerDependencies":{"@asylia/btc-core":"^1.0.1"},"devDependencies":{"@asylia/btc-core":"^1.0.1","@vitest/coverage-v8":"^4.1.6","eslint":"^10.3.0","rimraf":"^6.1.3","tsup":"^8.5.1","typescript":"^6.0.3","vitest":"^4.1.6"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"dependencies":{"@ledgerhq/errors":"^6.35.0","@ledgerhq/hw-transport":"^6.35.2","@ledgerhq/hw-transport-web-ble":"^6.34.2","@ledgerhq/hw-transport-webhid":"^6.35.2","@ledgerhq/ledger-bitcoin":"^0.3.1","bs58check":"^4.0.0","tslib":"^2.8.1"},"_id":"@asylia/hw-ledger@1.0.1","gitHead":"d269e09a317e911fc1438e068c02a209abc5dac4","_nodeVersion":"21.7.3","_npmVersion":"10.7.0","dist":{"integrity":"sha512-2Romh2wi+tzYoAzxdhVboKYxpO6Nzg415rGmUgKREHfTSSv63MpWcmpxqFe4KbLOdG/A89Sj5P8knhmNVBxykQ==","shasum":"0f9ac03342a0d6a7b2cb97a5f33d9bab06939eb2","tarball":"https://registry.npmjs.org/@asylia/hw-ledger/-/hw-ledger-1.0.1.tgz","fileCount":8,"unpackedSize":270444,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICmVZmU2yWqlgUIM+Jxz8GniWb4q/jEkb3eZJ9YYhdIuAiAnY8D3iGxTDf6+Jpa8wtup4/jbi4if400O3CS0zlEh7w=="}]},"_npmUser":{"name":"asylion21","email":"infodavidzita@gmail.com"},"directories":{},"maintainers":[{"name":"asylion21","email":"infodavidzita@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hw-ledger_1.0.1_1778785887212_0.7711004808878137"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-02T12:02:13.919Z","modified":"2026-05-14T19:11:27.516Z","0.1.0":"2026-05-02T12:02:14.143Z","1.0.0":"2026-05-04T10:39:22.529Z","1.0.1":"2026-05-14T19:11:27.381Z"},"bugs":{"url":"https://github.com/Asylia/bitcoin-toolkit/issues"},"author":{"name":"Asylia"},"license":"MIT","homepage":"https://github.com/Asylia/bitcoin-toolkit/tree/main/packages/hw-ledger#readme","keywords":["bitcoin","ledger","@ledgerhq/ledger-bitcoin","webhid","web-bluetooth","ble","hardware-wallet","wallet-policy","xpub","bip48","p2wsh","multisig","psbt","psbt-signing","typescript","self-custody","asylia"],"repository":{"type":"git","url":"git+https://github.com/Asylia/bitcoin-toolkit.git","directory":"packages/hw-ledger"},"description":"Auditable Ledger hardware-wallet TypeScript adapter for WebHID/Web Bluetooth environment checks, xpub export, wallet-policy registration, address display, and P2WSH multisig PSBT signing.","maintainers":[{"name":"asylion21","email":"infodavidzita@gmail.com"}],"readme":"

\n \"Asylia\"\n

\n\n# @asylia/hw-ledger\n\nLedger hardware-wallet adapter for the Asylia self-custody platform. It wraps\n`@ledgerhq/ledger-bitcoin` and `@ledgerhq/hw-transport-webhid` behind a narrow\nAsylia-shaped API for environment checks, xpub export, wallet-policy\nregistration, address display, and PSBT signing.\n\nThe wallet UI never imports LedgerHQ packages directly. Every Ledger protocol\ninteraction that can influence funds passes through this package, which keeps\nthe audit boundary explicit and reusable outside the Vue app.\n\nKeywords: Ledger, Bitcoin hardware wallet, WebHID, Ledger Bitcoin app v2,\nwallet policy, PSBT signing, P2WSH multisig, BIP-48, self-custody, TypeScript.\n\n## Maintainer And Support\n\n`@asylia/hw-ledger` 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`. Environment detection, xpub export, wallet-policy registration,\naddress display, live events, and PSBT signing are implemented.\n\n## Installation\n\n```bash\nnpm install @asylia/hw-ledger @asylia/btc-core\n```\n\n## Why This Package Exists\n\nHardware-wallet code is a hard security boundary:\n\n- It opens the browser transport to a physical device.\n- It requests xpub material and fingerprints.\n- It maps a wallet policy into device-approved Ledger state.\n- It turns PSBT data into device-side prompts.\n- It receives signatures that may authorize Bitcoin spends.\n\nKeeping this code outside the wallet SPA makes the boundary auditable,\nupgradeable in isolation, and portable to a future mobile signer.\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| `initLedger(options?)` | Idempotent pre-flight for secure origin and WebHID availability. |\n| `detectLedgerEnvironment()` | Pure browser capability probe. It never opens a permission prompt. |\n| `recommendationFromEnvironment()` | Maps browser/device capability into UI guidance. |\n| `exportLedgerRoot({ derivationPath, scriptType })` | Opens WebHID, verifies the Bitcoin app, reads the master fingerprint, and exports the requested BIP-32 public root. |\n| `buildLedgerWalletPolicy(input)` | Builds the deterministic Ledger multisig policy preview. |\n| `registerLedgerWalletPolicy(input)` | Registers the policy on device and returns the HMAC Asylia must persist for future signing. |\n| `displayWshSortedMultiAddress(input)` | Requests an on-device address display for a derived P2WSH multisig address. |\n| `signWshSortedMultiPsbt(input)` | Signs a PSBT with a registered policy and merges verified partial signatures back into the PSBT. |\n| `subscribeToLedgerEvents(handler)` | Streams device, app, prompt, finalization, and transport events for UI steppers and support diagnostics. |\n| `findAuthorisedLedgerDevice()`, `hasAuthorisedLedgerDevice()` | Silent `navigator.hid.getDevices()` helpers. |\n| `friendlyProductName(info)` | Converts HID descriptors into user-facing Ledger model names. |\n\nAll high-level flows return `AdapterResult`: `{ ok: true, data }` or\n`{ ok: false, error }`. Callers do not need to catch vendor SDK exceptions in\nUI code.\n\n## Ledger Signing Model\n\nLedger's modern Bitcoin app signs multisig spends through wallet policies. The\nAsylia flow is:\n\n1. Build the canonical `wsh(sortedmulti(...))` policy from the vault descriptor\n data.\n2. Register that policy once on the Ledger device.\n3. Persist the returned policy HMAC in wallet metadata.\n4. Build PSBT v2 inputs with witness scripts, BIP-32 derivation records, and raw\n funding transactions when available.\n5. Open WebHID for signing, verify the connected Ledger and Bitcoin app, sign\n with the stored policy HMAC, verify returned partial signatures, and merge\n them into the PSBT.\n\nThe adapter requires `@asylia/btc-core` for PSBT inspection, script metadata,\nand signature verification. Bitcoin script logic does not live in this package.\n\n## Error Model\n\nLedger SDK failures, APDU status words, transport errors, browser capability\nfailures, and user cancellations are normalized into the `LedgerErrorCode`\nunion:\n\n```text\ninit_failed | cancelled | device_disconnected | device_not_found |\ndevice_in_use | device_locked | device_timeout | app_not_open |\nwrong_app | wrong_device | app_outdated | firmware_too_old |\ndescriptor_unavailable | invalid_path | transport_unavailable |\npermission_denied | gesture_required | unknown\n```\n\nThe wallet renders adapter-provided messages. It should not inspect raw LedgerHQ\nerror strings.\n\n## Events and Diagnostics\n\n`subscribeToLedgerEvents` returns an `UnsubscribeFn` and emits events such as:\n\n- `device_connected` / `device_disconnected`,\n- `app_connected`,\n- `awaiting_button`,\n- `finalising`,\n- `transport_error`.\n\nThe wallet's Ledger wizard uses this stream to drive step-by-step UI. Adapter\nlogs use the `[hw-ledger]` prefix so support can reconstruct UI -> service ->\nadapter -> device behavior from browser console output.\n\n## Not in Scope\n\nThis package does not:\n\n- persist xpubs, fingerprints, policy HMACs, or signatures,\n- store seed phrases or private keys,\n- render UI,\n- own descriptor policy construction beyond Ledger's device policy format,\n- fetch blockchain data,\n- support non-Asylia script families.\n\n## Testing\n\n```bash\nyarn workspace @asylia/hw-ledger type-check\nyarn workspace @asylia/hw-ledger test\n```\n\n## Versioning and Audit Stance\n\nThe package uses semver for stable releases. Upstream Ledger dependencies are\nintentionally pinned to specific minor versions. See\n[`SECURITY.md`](./SECURITY.md) for the disclosure process and scope.\n\n## License\n\nMIT - see [`LICENSE`](./LICENSE).\n","readmeFilename":"README.md"}