@sidhujag/sysweb3-keyring 1.0.627 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 2.0.0
+
+- Add `SoftwareKeyring.deriveEvmHdRuntimeAccount` for host-allocated Ethereum BIP44 indices. It returns the existing password-encrypted runtime account record without installing an account, writing storage or querying a network. The method binds session, selection and network identity and requires a synchronous host guard. Hosts must strip encrypted `xprv` before producing public metadata.
+
+- Add `SoftwareKeyring.signPreparedEvmTransaction` for offline signing of fully specified legacy/EIP-1559 envelopes. The request binds the selected software account and exact network/endpoint, requires synchronous host admission, validates all signed fields and recovered identity, and returns immutable signed bytes plus their local hash. It never estimates fees, resolves names, fills fields or broadcasts; hosts must durably retain the result before submission and reconcile uncertain broadcasts by hash.
+
+- Breaking: Ledger signing requires an explicitly injected semantic `LedgerHost`. Raw LedgerJS transports/clients are removed; use the isolated browser ESM host entry for device access.
+- Adopt current Device Management Kit and Ethereum signer packages while preserving the custom Syscoin/Bitcoin protocol. Serialize device operations and reject stale, wrong-account, malformed and mismatched-sighash responses.
+- Disable remote Ledger metadata/transaction checks/telemetry by default. Require fresh per-intent consent for transaction/typed-data signing that may fall back to blind signing.
+- Bind receive addresses to public account derivation, preserve on-device approval for unusual paths, and snapshot queued UTXO requests before connection awaits.
+- Existing software-only entry, vault formats and account derivation remain compatible. Host/device and native-runtime qualification are separate requirements.
+
+- Remove the legacy Trezor UTXO library. Reuse Bitcoinjs address decoding with a checksum-verified two-byte-version compatibility path, and encode witness vectors with the public CompactSize codec.
+
+- Move Trezor hardware integration to Connect 10.0.1 and remove the redundant direct Connect Web dependency.
+- Load the browser transport only inside a supported MV3 extension. Preserve CommonJS/ESM and software-entry imports without browser globals or device initialization.
+- Preserve the existing SDK failure payload while retaining Connect error codes; stop retrying cancellations, disconnects and unsupported hosts/coins.
+- Replace removed Connect device events with status updates from request outcomes and disposal. Immediate physical unplug notifications are no longer exposed by upstream.
+- Reject pending calls locally on lock/disposal and discard late responses. Defer remote cleanup while requests are outstanding; return `HARDWARE_SIGNER_BUSY` until they settle rather than opening another approval prompt.
+- Normalize Trezor hexadecimal recovery values without mutating signed responses; preserve approved transaction and session checks.
+- Physical device qualification and consuming-extension Suite Web permissions remain release gates.
+
+## 1.0.628
+
+- Add the `cjs/software` entry with explicit asynchronous host storage and an opaque wallet-authority handle. Software keyrings do not load browser hardware transports or global storage.
+- Keep the legacy `KeyringManager` entry and normal device defaults. The software entry rejects unavailable hardware, storage rebinding, direct session injection and cross-authority session transfer.
+- Expose reusable vault persistence and software transaction cores with typed deep imports. Preserve vault encryption formats, KDF profiles, private-record domains and account derivation.
+- Move Pali's existing cancellation fee-consent safeguards into source: optional unsigned preview and selected payer, required approved fee ceiling for sending, and final populated-envelope validation.
+- Preserve the original value of a MAX-send replacement; return `REPLACEMENT_VALUE_WOULD_CHANGE` if the higher fee cannot be funded without reducing it.
+- Add an optional synchronous final validator to local transaction sending. Promise/thenable decisions are rejected before signing; the existing five-argument call remains supported.
+- Exclude compiled test fixtures from the published package; runtime code and declarations are unchanged.
+
+### Cancellation callers
+
+A cancellation send now requires `approvedMaximumFee` (decimal wei), in addition to the existing synchronous `assertCurrentContext` and `validateOriginal` callbacks. `previewOnly: true` returns `maximumFee` without requesting credentials, device signing or broadcast. After the user deliberately reviews and approves that fee ceiling, pass the approved value when sending; a later higher fee is rejected. `targetAccount` selects the supported outer payer while the host's selected-account context remains guarded.
+
+Pali already enforces these rules through its 1.0.627 package patch. It may remove that patch only when adopting this release and validating the actual installed package.
+
+### Host integration limits
+
+The software entry is a low-level SDK, not a native-wallet security boundary by itself. The host must invalidate its authorization generation immediately on lock/background, clear late unlock results, and control public-state publication. Native cryptographic/storage adapters, biometrics, device behavior and full mobile functionality still require their own implementation and qualification. See `docs/software-entry.md` and `docs/storage-core.md` in the source repository.
+
 ## 1.0.626
 
 - Add an optional synchronous host guard to formatted EVM transaction submission. The SDK captures it once and rechecks it with the existing account, network and session guards before signing and broadcast.

package/README.md

@@ -150,6 +150,32 @@ const signature = await keyringManager.ethereumTransaction.signPersonalMessage([
 
 ### Hardware Wallet Support
 
+Trezor uses `@trezor/connect-webextension` 10.0.1. The hardware adapter loads it
+only when a supported MV3 extension invokes Trezor; ordinary Node CommonJS/ESM
+imports and the software entry do not initialize browser transports. Unsupported
+hosts reject hardware operations instead of falling back to software signing.
+
+The extension must configure `externally_connectable` for
+`https://suite.trezor.io/*` and host access to that origin, as required by the
+[published Connect 10 webextension package](https://www.npmjs.com/package/@trezor/connect-webextension/v/10.0.1).
+Connect selects Suite Desktop or the Suite Web popup. The old Connect 9 iframe,
+content script, and `connectSrc` settings are not part of this integration.
+
+Connect 10 does not expose the old device event emitter. SDK connection status
+and cached model information update from request results and disposal; they are
+not immediate physical unplug notifications. Disposal immediately rejects pending
+SDK operations and fences late replies. Suite Web may leave its popup open; a
+late approval there is discarded locally rather than treated as a fresh approval.
+When an underlying request is still active, transport cleanup is deferred to avoid
+triggering an automatic fallback popup. New initialization fails with
+`HARDWARE_SIGNER_BUSY` until that request settles; local lock/disposal does not
+wait for the remote prompt. An upstream transport failure can still trigger remote
+fallback UI while that old request is pending; the local SDK will reject its result.
+A failed or cancelled operation
+never authorizes a cached transaction, and terminal disconnect/unsupported-host
+errors are not retried. Device pairing, display verification, signing, and
+reconnection still require physical-device qualification in the consuming host.
+
 ```javascript
 // Import Trezor account
 const trezorAccount = await keyringManager.importTrezorAccount(
@@ -293,3 +319,43 @@ collection rather than guaranteed memory erasure.
 ## License
 
 MIT License
+
+### Ledger platform host
+
+Ledger device access uses the Device Management Kit. The regular and software
+entries do not load a Ledger transport or device SDK. Browser integrations must
+create the heavy host from `@sidhujag/sysweb3-keyring/esm/ledger-host` in a visible
+extension page and inject its semantic `LedgerHost` port into the wallet authority:
+
+```ts
+// Visible device page only:
+import { createLedgerDmkHost } from '@sidhujag/sysweb3-keyring/esm/ledger-host';
+const host = createLedgerDmkHost({
+  confirmBlindSigning: async (intent, signal) => {
+    // Show the exact immutable intent and an explicit blind-signing warning.
+    // Return true only after a fresh user decision; cancellation must return false.
+    return showTrustedWalletConfirmation(intent, signal);
+  },
+});
+
+// Wallet authority: use a secured semantic port to that page, not a raw APDU port.
+const wallet = new KeyringManager(undefined, authorizedLedgerHostPort);
+```
+
+Use only the ESM host entry with a browser bundler and its required platform
+polyfills. `cjs/ledger-host` is not a supported entry. A service worker cannot own
+the WebHID device picker. The platform must bind the host to its own trusted page,
+revoke pending operations on lock/close, and never expose this port to dapps.
+A missing host fails with `HARDWARE_SIGNER_UNAVAILABLE`; there is no legacy
+LedgerJS fallback. Pass either a shared hardware manager or a Ledger host to
+`KeyringManager`, not both.
+
+The default host performs no remote metadata lookup, transaction checks, or
+signing telemetry. The current Ethereum signer library can fall back to blind
+signing, so transaction and typed-data signing require per-request approval
+through the trusted `confirmBlindSigning` callback. Omitting it fails closed.
+Personal-message signing and address retrieval remain available offline.
+Signatures are checked against the expected account; UTXO signatures must also
+match the approved PSBT and its requested sighash coverage. The custom UTXO host
+supports the existing Syscoin and Bitcoin app protocols. Physical-device and
+firmware qualification remain separate from source and mocked-device tests.