feat: add Ledger DMK bridge (#473)

<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?

Are there any issues or other links reviewers should consult to
understand this pull request better? For instance:

* Fixes #12345
* See: #67890
-->

This PR introduces the DMK bridge and middleware for the ledger keyring.

Fixes: https://consensyssoftware.atlassian.net/browse/MUL-1857

<!--
Are there any examples of this change being used in another repository?

When considering changes to the MetaMask module template, it's strongly
preferred that the change be experimented with in another repository
first. This gives reviewers a better sense of how the change works,
making it less likely the change will need to be reverted or adjusted
later.
-->


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **High Risk**
> New hardware-wallet transport and signing path touches all Ledger
operations (keys, txs, typed data, EIP-7702); incorrect session or error
mapping could break device flows or misreport user rejections.
> 
> **Overview**
> Adds a **Ledger Device Management Kit (DMK)** path to
`@metamask/eth-ledger-bridge-keyring` so hosts can talk to Ledger
through an injected transport factory instead of only the legacy
iframe/mobile bridges.
> 
> **`LedgerDmkBridge`** implements the shared `LedgerBridge` contract:
it builds DMK internally, delegates discovery/connect/session work to
**`LedgerDmkTransportMiddleware`** (cached `SignerEth` per session), and
routes address derivation plus tx, personal message, EIP-712, and
**EIP-7702 delegation** signing through the Ethereum signer kit.
DMK/RxJS failures are normalized via **`translateDmkError`** into
`TransportStatusError` so existing keyring error handling still applies.
A custom **`EthGetAppConfigurationCommand`** reads Ethereum-app config
(e.g. blind signing) over DMK because the signer kit does not expose
that APDU publicly. The bridge also exposes **`onSessionStateChange`**,
**`isDeviceConnected`**, and session monitoring with backoff so
unplugged devices do not leave a stale connected state.
> 
> The package **exports** the new bridge, middleware, and error helpers;
**`ledger-keyring`** now types `SignTransactionPayload` against generic
**`LedgerBridgeOptions`** (not iframe-only options). Dependencies add
Ledger DMK/signer/context packages and **rxjs**; changelog and lockfile
reflect the new stack. Large Jest coverage accompanies the new `dmk/`
module.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
c5e413a. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Gustavo Antunes <17601467+gantunesr@users.noreply.github.com>

Author: montelaidev

eslint-suppressions.json

@@ -62,14 +62,6 @@
       "count": 4
     }
   },
-  "packages/keyring-eth-ledger-bridge/src/ledger-keyring.test.ts": {
-    "@typescript-eslint/no-explicit-any": {
-      "count": 2
-    },
-    "promise/always-return": {
-      "count": 1
-    }
-  },
   "packages/keyring-eth-ledger-bridge/src/ledger-keyring.ts": {
     "import-x/no-nodejs-modules": {
       "count": 1

packages/keyring-eth-ledger-bridge/CHANGELOG.md

@@ -9,12 +9,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add `LedgerDmkBridge` and `LedgerDmkTransportMiddleware` for Ledger Device Management Kit (DMK) support ([#473](https://github.com/MetaMask/accounts/pull/473))
+  - New `LedgerDmkBridge` class implementing the `LedgerBridge` interface via Ledger's DMK.
+  - New `LedgerDmkTransportMiddleware` managing sessions, device discovery, and Ethereum signer lifecycle.
+  - DMK error translation utilities (`translateDmkError`, `isDeviceExchangeError`) mapping to `TransportStatusError`.
+  - Custom `EthGetAppConfigurationCommand` for retrieving Ethereum app config via DMK.
+  - Session state monitoring with `onSessionStateChange` observable and `isDeviceConnected` getter.
+  - Exports `LedgerDmkBridge`, `LedgerDmkBridgeOptions`, `LedgerDmkTransportMiddleware`, and DMK error utilities from the package root.
 - Add EIP-7702 authorization signing to the Ledger keyring ([#564](https://github.com/MetaMask/accounts/pull/564))
   - Not yet functional: both iframe and mobile bridges throw until DMK support lands.
   - Fixes hex `v` parsing (`'1b'`) for personal_sign and typed data.
 
 ### Changed
 
+- Widen `SignTransactionPayload` type from `LedgerIframeBridgeOptions` to `LedgerBridgeOptions` for bridge compatibility ([#473](https://github.com/MetaMask/accounts/pull/473))
+- Remove unused `LedgerIframeBridgeOptions` import from `ledger-keyring.ts` ([#473](https://github.com/MetaMask/accounts/pull/473))
 - Bump `@metamask/keyring-api` from `^23.1.0` to `^23.3.0` ([#562](https://github.com/MetaMask/accounts/pull/562), [#569](https://github.com/MetaMask/accounts/pull/569))
 - Bump `@metamask/keyring-sdk` from `^2.1.1` to `^2.2.0` ([#562](https://github.com/MetaMask/accounts/pull/562))
 

packages/keyring-eth-ledger-bridge/package.json

@@ -71,13 +71,17 @@
     "@ethereumjs/rlp": "^5.0.2",
     "@ethereumjs/tx": "^5.4.0",
     "@ethereumjs/util": "^9.1.0",
+    "@ledgerhq/context-module": "2.1.0",
+    "@ledgerhq/device-management-kit": "1.5.1",
+    "@ledgerhq/device-signer-kit-ethereum": "1.16.0",
     "@ledgerhq/hw-app-eth": "^6.42.0",
     "@ledgerhq/hw-transport": "^6.31.3",
     "@metamask/eth-sig-util": "^8.2.0",
     "@metamask/hw-wallet-sdk": "^0.8.0",
     "@metamask/keyring-api": "^23.3.0",
     "@metamask/keyring-sdk": "^2.2.0",
-    "hdkey": "^2.1.0"
+    "hdkey": "^2.1.0",
+    "rxjs": "^7.8.2"
   },
   "devDependencies": {
     "@ethereumjs/common": "^4.4.0",
@@ -94,8 +98,8 @@
     "@types/ethereumjs-tx": "^1.0.1",
     "@types/hdkey": "^2.0.1",
     "@types/jest": "^29.5.12",
-    "@types/node": "^20.12.12",
     "@types/web": "^0.0.69",
+    "@types/ws": "^8.18.1",
     "deepmerge": "^4.2.2",
     "depcheck": "^1.4.7",
     "ethereum-cryptography": "^2.2.1",

packages/keyring-eth-ledger-bridge/src/dmk/__testhelpers__/mock-error.ts

@@ -0,0 +1,24 @@
+import type { DeviceExchangeError } from '@ledgerhq/device-management-kit';
+
+import { ETH_APP_COMMAND_ERROR_TAG } from '../eth-get-app-configuration-command';
+
+/**
+ * Construct a mock {@link DeviceExchangeError} for tests.
+ *
+ * The DMK `DeviceExchangeError` is normally raised inside the DMK runtime;
+ * tests need a structurally-equivalent value without going through DMK.
+ * This helper centralises the cast so test files don't each roll their own.
+ *
+ * @param errorCode - The hex error code to embed (e.g. `'6985'`).
+ * @returns A mock `DeviceExchangeError<TErrorCode>`.
+ */
+export function createMockDeviceExchangeError<TErrorCode = string>(
+  errorCode: TErrorCode,
+): DeviceExchangeError<TErrorCode> {
+  return {
+    _tag: ETH_APP_COMMAND_ERROR_TAG,
+    message: `DMK error: ${String(errorCode)}`,
+    errorCode,
+    originalError: undefined,
+  } as unknown as DeviceExchangeError<TErrorCode>;
+}

packages/keyring-eth-ledger-bridge/src/dmk/dmk-error-translator.test.ts

@@ -0,0 +1,145 @@
+import { TransportStatusError } from '@ledgerhq/hw-transport';
+
+import { createMockDeviceExchangeError } from './__testhelpers__/mock-error';
+import { translateDmkError } from './dmk-error-translator';
+
+describe('translateDmkError', () => {
+  describe('EthAppCommandError (DeviceExchangeError with EthErrorCodes)', () => {
+    it('translates error code "6985" to TransportStatusError with statusCode 0x6985', () => {
+      const dmkError = createMockDeviceExchangeError('6985');
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6985);
+    });
+
+    it('translates error code "6a80" to TransportStatusError with statusCode 0x6a80', () => {
+      const dmkError = createMockDeviceExchangeError('6a80');
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6a80);
+    });
+
+    it('translates error code "6a84" to TransportStatusError with statusCode 0x6a84', () => {
+      const dmkError = createMockDeviceExchangeError('6a84');
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6a84);
+    });
+
+    it('translates error code "6982" to TransportStatusError with statusCode 0x6982', () => {
+      const dmkError = createMockDeviceExchangeError('6982');
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6982);
+    });
+
+    it('translates error code "6b00" to TransportStatusError with statusCode 0x6b00', () => {
+      const dmkError = createMockDeviceExchangeError('6b00');
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6b00);
+    });
+
+    it('translates error code "6d00" to TransportStatusError with statusCode 0x6d00', () => {
+      const dmkError = createMockDeviceExchangeError('6d00');
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6d00);
+    });
+
+    it('translates error code "6e00" to TransportStatusError with statusCode 0x6e00', () => {
+      const dmkError = createMockDeviceExchangeError('6e00');
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6e00);
+    });
+
+    it('translates error code "6f00" to TransportStatusError with statusCode 0x6f00', () => {
+      const dmkError = createMockDeviceExchangeError('6f00');
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6f00);
+    });
+
+    it('translates error code "6a00" to TransportStatusError with statusCode 0x6a00', () => {
+      const dmkError = createMockDeviceExchangeError('6a00');
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6a00);
+    });
+
+    it('translates error code "6a88" to TransportStatusError with statusCode 0x6a88', () => {
+      const dmkError = createMockDeviceExchangeError('6a88');
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6a88);
+    });
+  });
+
+  describe('unknown DMK error codes', () => {
+    it('translates unknown error code to TransportStatusError with numeric conversion', () => {
+      const dmkError = createMockDeviceExchangeError('ffff');
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0xffff);
+    });
+  });
+
+  describe('non-DeviceExchangeError errors', () => {
+    it('wraps generic Error instances in TransportStatusError with status 0x6f00', () => {
+      const error = new Error('something went wrong');
+
+      const result = translateDmkError(error);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6f00);
+    });
+
+    it('wraps non-Error values in TransportStatusError with status 0x6f00', () => {
+      const result = translateDmkError('string error');
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6f00);
+    });
+
+    it('wraps null/undefined in TransportStatusError with status 0x6f00', () => {
+      const result = translateDmkError(null);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6f00);
+    });
+  });
+
+  describe('DeviceExchangeError without error code', () => {
+    it('wraps DeviceExchangeError with void error code in TransportStatusError', () => {
+      const dmkError = createMockDeviceExchangeError<void>(undefined);
+
+      const result = translateDmkError(dmkError);
+
+      expect(result).toBeInstanceOf(TransportStatusError);
+      expect(result.statusCode).toBe(0x6f00);
+    });
+  });
+});

packages/keyring-eth-ledger-bridge/src/dmk/dmk-error-translator.ts

@@ -0,0 +1,39 @@
+import { DeviceExchangeError } from '@ledgerhq/device-management-kit';
+import { TransportStatusError } from '@ledgerhq/hw-transport';
+
+const GENERIC_ERROR_STATUS_CODE = 0x6f00;
+
+/**
+ * Translates a DMK error (DeviceExchangeError with hex error codes) into a
+ * TransportStatusError that the Ledger keyring error handler can process.
+ *
+ * @param error - The error from a DMK device action or command.
+ * @returns A TransportStatusError with the corresponding APDU status code.
+ */
+export function translateDmkError(error: unknown): TransportStatusError {
+  if (isDeviceExchangeError(error)) {
+    const statusCode = parseHexErrorCode(error.errorCode);
+    return new TransportStatusError(statusCode);
+  }
+
+  return new TransportStatusError(GENERIC_ERROR_STATUS_CODE);
+}
+
+export function isDeviceExchangeError(
+  error: unknown,
+): error is DeviceExchangeError<string> {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    '_tag' in error &&
+    'errorCode' in error
+  );
+}
+
+function parseHexErrorCode(errorCode: unknown): number {
+  if (typeof errorCode === 'string' && /^[0-9a-fA-F]{4}$/u.test(errorCode)) {
+    return parseInt(errorCode, 16);
+  }
+
+  return GENERIC_ERROR_STATUS_CODE;
+}

packages/keyring-eth-ledger-bridge/src/dmk/eth-get-app-configuration-command.test.ts

@@ -0,0 +1,92 @@
+import {
+  CommandResultStatus,
+  InvalidStatusWordError,
+} from '@ledgerhq/device-management-kit';
+
+import {
+  ETH_APP_COMMAND_ERROR_TAG,
+  EthGetAppConfigurationCommand,
+} from './eth-get-app-configuration-command';
+
+describe('EthGetAppConfigurationCommand', () => {
+  const command = new EthGetAppConfigurationCommand();
+
+  it('uses the Ethereum getAppConfiguration APDU', () => {
+    expect(command.name).toBe('getAppConfiguration');
+    expect(command.getApdu().getRawApdu()).toStrictEqual(
+      Uint8Array.from([0xe0, 0x06, 0x00, 0x00, 0x00]),
+    );
+  });
+
+  it('parses blind signing and web3 check flags', () => {
+    const result = command.parseResponse({
+      statusCode: Uint8Array.from([0x90, 0x00]),
+      data: Uint8Array.from([0x31, 0x01, 0x02, 0x03]),
+    });
+
+    expect(result).toStrictEqual({
+      status: CommandResultStatus.Success,
+      data: {
+        blindSigningEnabled: true,
+        web3ChecksEnabled: true,
+        web3ChecksOptIn: true,
+        version: '1.2.3',
+      },
+    });
+  });
+
+  it('returns a DMK-style exchange error for APDU status errors', () => {
+    const result = command.parseResponse({
+      statusCode: Uint8Array.from([0x69, 0x85]),
+      data: Uint8Array.from([]),
+    });
+
+    expect(result).toStrictEqual({
+      status: CommandResultStatus.Error,
+      error: {
+        _tag: ETH_APP_COMMAND_ERROR_TAG,
+        errorCode: '6985',
+        message: 'Ledger Ethereum app command failed with status 0x6985.',
+        originalError: undefined,
+      },
+    });
+  });
+
+  it('returns an invalid status word error when config flags are missing', () => {
+    const result = command.parseResponse({
+      statusCode: Uint8Array.from([0x90, 0x00]),
+      data: Uint8Array.from([]),
+    });
+
+    expect(result.status).toBe(CommandResultStatus.Error);
+    const error =
+      result.status === CommandResultStatus.Error ? result.error : undefined;
+    expect(error).toBeInstanceOf(InvalidStatusWordError);
+    expect(error).toStrictEqual(
+      expect.objectContaining({
+        originalError: new Error(
+          'Cannot extract config flags from response body',
+        ),
+      }),
+    );
+  });
+
+  it('returns an invalid status word error when version bytes are missing', () => {
+    const result = command.parseResponse({
+      statusCode: Uint8Array.from([0x90, 0x00]),
+      data: Uint8Array.from([0x01]),
+    });
+
+    expect(result.status).toBe(CommandResultStatus.Error);
+    const error =
+      result.status === CommandResultStatus.Error ? result.error : undefined;
+    expect(error).toBeInstanceOf(InvalidStatusWordError);
+    expect(error).toStrictEqual(
+      expect.objectContaining({
+        originalError: new Error(
+          'Cannot extract version bytes from response body',
+        ),
+      }),
+    );
+  });
+});