feat: use hw wallet error for ledger keyring and add getAppNameAndVersion and getAppConfiguration (#446)

<!--
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 add a new method `getAppNameAndVersion` and
`getAppConfiguration` to the ledger keyring and uses the hardware wallet
errors.

## Examples

<!--
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]
> **Medium Risk**
> Touches Ledger signing error handling and public error
shapes/messages, which can affect downstream consumers’ error parsing
and UX; adds new bridge commands that depend on correct iframe/mobile
transport support.
> 
> **Overview**
> Switches `@metamask/eth-ledger-bridge-keyring` from its custom
`LedgerStatusError` flow to **standardized** `@metamask/hw-wallet-sdk`
error mapping, introducing
`createLedgerError`/`handleLedgerTransportError` that consistently
throws `HardwareWalletError` (with selective `Ledger:` message prefixing
for compatibility) and updating tests/messages accordingly.
> 
> Extends the Ledger bridge/keyring surface area with
`getAppNameAndVersion()` and `getAppConfiguration()` across iframe and
mobile bridges (new iframe message actions included), and wires
workspace dependency/build references so the keyring consumes the shared
SDK types/mappings (including exporting the new `ErrorMapping` type from
the SDK).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
61d895d. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: montelaidev

.syncpackrc

@@ -41,6 +41,7 @@
       ],
       "dependencies": [
         "@metamask/account-**",
+        "@metamask/hw-wallet-sdk",
         "@metamask/keyring-**",
         "@metamask/eth-**-keyring"
       ],

README.md

@@ -57,6 +57,7 @@ linkStyle default opacity:0.5
   eth_hd_keyring --> keyring_api;
   eth_hd_keyring --> keyring_utils;
   eth_hd_keyring --> account_api;
+  eth_ledger_bridge_keyring --> hw_wallet_sdk;
   eth_ledger_bridge_keyring --> keyring_api;
   eth_ledger_bridge_keyring --> keyring_utils;
   eth_ledger_bridge_keyring --> account_api;

packages/hw-wallet-sdk/CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- export `ErrorMapping` type ([#446](https://github.com/MetaMask/accounts/pull/446))
 - Add hardware wallet connection types and improved error handling ([#456](https://github.com/MetaMask/accounts/pull/456))
   - Add `HardwareWalletType`, `ConnectionStatus`, `DeviceEvent` enums and `HardwareWalletConnectionState`, `DeviceEventPayload` types.
   - Add Ledger error mappings for device locked and Ethereum app closed states.

packages/hw-wallet-sdk/src/hardware-error-mappings.test.ts

@@ -3,11 +3,19 @@ import {
   BLE_ERROR_MAPPINGS,
   MOBILE_ERROR_MAPPINGS,
 } from './hardware-error-mappings';
+import type { ErrorMapping } from './hardware-error-mappings';
 import { ErrorCode, Severity, Category } from './hardware-errors-enums';
 
 describe('HARDWARE_ERROR_MAPPINGS', () => {
   describe('Ledger mappings', () => {
     const errorMappings = LEDGER_ERROR_MAPPINGS;
+    const getLedgerMapping = (code: string): ErrorMapping => {
+      const mapping = errorMappings[code];
+      if (!mapping) {
+        throw new Error(`Missing Ledger mapping for ${code}`);
+      }
+      return mapping;
+    };
 
     it('has errorMappings object', () => {
       expect(errorMappings).toBeDefined();
@@ -16,7 +24,7 @@ describe('HARDWARE_ERROR_MAPPINGS', () => {
 
     describe('success codes', () => {
       it('map 0x9000 to success', () => {
-        const mapping = errorMappings['0x9000'];
+        const mapping = getLedgerMapping('0x9000');
         expect(mapping).toBeDefined();
         expect(mapping.code).toBe(ErrorCode.Success);
         expect(mapping.severity).toBe(Severity.Info);
@@ -26,58 +34,58 @@ describe('HARDWARE_ERROR_MAPPINGS', () => {
 
     describe('authentication errors', () => {
       it('map 0x6300 to authentication failed', () => {
-        const mapping = errorMappings['0x6300'];
+        const mapping = getLedgerMapping('0x6300');
         expect(mapping.code).toBe(ErrorCode.AuthenticationFailed);
         expect(mapping.severity).toBe(Severity.Err);
         expect(mapping.category).toBe(Category.Authentication);
         expect(mapping.userMessage).toBeDefined();
       });
 
       it('map 0x63c0 to PIN attempts remaining', () => {
-        const mapping = errorMappings['0x63c0'];
+        const mapping = getLedgerMapping('0x63c0');
         expect(mapping.code).toBe(ErrorCode.AuthenticationPinAttemptsRemaining);
         expect(mapping.severity).toBe(Severity.Warning);
       });
 
       it('map 0x5515 to device locked', () => {
-        const mapping = errorMappings['0x5515'];
+        const mapping = getLedgerMapping('0x5515');
         expect(mapping.code).toBe(ErrorCode.AuthenticationDeviceLocked);
         expect(mapping.severity).toBe(Severity.Err);
         expect(mapping.userMessage).toContain('unlock');
       });
 
       it('map 0x9840 to device blocked', () => {
-        const mapping = errorMappings['0x9840'];
+        const mapping = getLedgerMapping('0x9840');
         expect(mapping.code).toBe(ErrorCode.AuthenticationDeviceBlocked);
         expect(mapping.severity).toBe(Severity.Critical);
       });
     });
 
     describe('user action errors', () => {
       it('map 0x6985 to user rejected', () => {
-        const mapping = errorMappings['0x6985'];
+        const mapping = getLedgerMapping('0x6985');
         expect(mapping.code).toBe(ErrorCode.UserRejected);
         expect(mapping.severity).toBe(Severity.Warning);
         expect(mapping.category).toBe(Category.UserAction);
       });
 
       it('map 0x5501 to user refused', () => {
-        const mapping = errorMappings['0x5501'];
+        const mapping = getLedgerMapping('0x5501');
         expect(mapping.code).toBe(ErrorCode.UserRejected);
         expect(mapping.severity).toBe(Severity.Warning);
       });
     });
     describe('connection errors', () => {
       it('map 0x650f to connection issue', () => {
-        const mapping = errorMappings['0x650f'];
+        const mapping = getLedgerMapping('0x650f');
         expect(mapping.code).toBe(ErrorCode.ConnectionClosed);
         expect(mapping.category).toBe(Category.Connection);
       });
     });
 
     describe('device state errors', () => {
       it('maps 0x6f00 to device unresponsive', () => {
-        const mapping = errorMappings['0x6f00'];
+        const mapping = getLedgerMapping('0x6f00');
         expect(mapping.code).toBe(ErrorCode.DeviceUnresponsive);
         expect(mapping.severity).toBe(Severity.Err);
         expect(mapping.category).toBe(Category.DeviceState);
@@ -86,7 +94,7 @@ describe('HARDWARE_ERROR_MAPPINGS', () => {
     });
 
     it('has valid structure for all mappings', () => {
-      Object.entries(errorMappings).forEach(([_, mapping]) => {
+      Object.values(errorMappings).forEach((mapping) => {
         expect(mapping).toHaveProperty('code');
         expect(mapping).toHaveProperty('message');
         expect(mapping).toHaveProperty('severity');
@@ -173,7 +181,7 @@ describe('HARDWARE_ERROR_MAPPINGS', () => {
     });
 
     it('has valid structure for all mappings', () => {
-      Object.entries(errorMappings).forEach(([_, mapping]) => {
+      Object.values(errorMappings).forEach((mapping) => {
         expect(mapping).toHaveProperty('code');
         expect(mapping).toHaveProperty('message');
         expect(mapping).toHaveProperty('severity');
@@ -206,7 +214,7 @@ describe('HARDWARE_ERROR_MAPPINGS', () => {
     });
 
     it('has valid structure for all mappings', () => {
-      Object.entries(errorMappings).forEach(([_, mapping]) => {
+      Object.values(errorMappings).forEach((mapping) => {
         expect(mapping).toHaveProperty('code');
         expect(mapping).toHaveProperty('message');
         expect(mapping).toHaveProperty('severity');

packages/hw-wallet-sdk/src/hardware-error-mappings.ts

@@ -1,6 +1,14 @@
 import { ErrorCode, Severity, Category } from './hardware-errors-enums';
 
-export const LEDGER_ERROR_MAPPINGS = {
+export type ErrorMapping = {
+  code: ErrorCode;
+  message: string;
+  severity: Severity;
+  category: Category;
+  userMessage?: string;
+};
+
+export const LEDGER_ERROR_MAPPINGS: Record<string, ErrorMapping> = {
   '0x9000': {
     code: ErrorCode.Success,
     message: 'Operation successful',

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

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Integrate `@metamask/hw-wallet-sdk` for standardized hardware wallet error handling ([#446](https://github.com/MetaMask/accounts/pull/446))
+  - Replace custom error handling with `HardwareWalletError` from the SDK.
+  - Use `LEDGER_ERROR_MAPPINGS` from the SDK for consistent error code mapping.
+  - Re-export `HardwareWalletError`, `ErrorCode`, `Severity`, `Category`, and error mappings for consumer convenience.
+  - Deprecate `LedgerStatusError` in favor of `HardwareWalletError`.
+  - Prefix Ledger transport error messages for compatibility
+
 ## [11.2.0]
 
 ### Added
@@ -15,7 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Wraps legacy `LedgerKeyring` to expose accounts via the unified `KeyringV2` API and the `KeyringAccount` type.
   - Extends `EthKeyringWrapper` for common Ethereum logic.
 
-### Fixed
+### Changed
 
 - Normalize signature `v` value from Ledger devices for proper recovery ([#449](https://github.com/MetaMask/accounts/pull/449))
 

packages/keyring-eth-ledger-bridge/jest.config.js

@@ -15,18 +15,21 @@ module.exports = merge(baseConfig, {
   displayName,
 
   // An array of regexp pattern strings used to skip coverage collection
-  coveragePathIgnorePatterns: ['./src/tests'],
+  coveragePathIgnorePatterns: [
+    './src/tests',
+    './src/type.ts', // Deprecated, kept for backwards compatibility
+  ],
 
   // The glob patterns Jest uses to detect test files
   testMatch: ['**/*.test.[jt]s?(x)'],
 
   // An object that configures minimum threshold enforcement for coverage results
   coverageThreshold: {
     global: {
-      branches: 93.61,
-      functions: 98.18,
-      lines: 97.74,
-      statements: 97.76,
+      branches: 93.36,
+      functions: 98.29,
+      lines: 97.86,
+      statements: 97.88,
     },
   },
 });

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

@@ -51,6 +51,7 @@
     "@ethereumjs/util": "^9.1.0",
     "@ledgerhq/hw-app-eth": "^6.42.0",
     "@metamask/eth-sig-util": "^8.2.0",
+    "@metamask/hw-wallet-sdk": "workspace:^",
     "@metamask/keyring-api": "workspace:^",
     "@metamask/keyring-utils": "workspace:^",
     "hdkey": "^2.1.0"

packages/keyring-eth-ledger-bridge/src/errors.test.ts

@@ -0,0 +1,97 @@
+import {
+  HardwareWalletError,
+  ErrorCode as ErrorCodeEnum,
+} from '@metamask/hw-wallet-sdk';
+
+import {
+  createLedgerError,
+  isKnownLedgerError,
+  getLedgerErrorMapping,
+} from './errors';
+
+describe('createLedgerError', () => {
+  describe('known error codes', () => {
+    it('creates HardwareWalletError for user rejection (0x6985)', () => {
+      const error = createLedgerError('0x6985');
+
+      expect(error).toBeInstanceOf(HardwareWalletError);
+      expect(error.code).toBe(ErrorCodeEnum.UserRejected);
+      expect(error.message).toBe('User rejected action on device');
+    });
+
+    it('creates HardwareWalletError for device locked (0x5515)', () => {
+      const error = createLedgerError('0x5515');
+
+      expect(error).toBeInstanceOf(HardwareWalletError);
+      expect(error.code).toBe(ErrorCodeEnum.AuthenticationDeviceLocked);
+      expect(error.message).toBe('Device is locked');
+    });
+
+    it('includes context in message when provided', () => {
+      const error = createLedgerError('0x6985', 'during sign transaction');
+
+      expect(error.message).toBe(
+        'User rejected action on device (during sign transaction)',
+      );
+    });
+
+    it('uses error message as userMessage when userMessage is not provided in mapping', () => {
+      // 0x9000 is success code which doesn't have a userMessage in the mapping
+      const error = createLedgerError('0x9000');
+
+      expect(error).toBeInstanceOf(HardwareWalletError);
+      // userMessage should fallback to the message
+      expect(error.userMessage).toBeDefined();
+    });
+  });
+
+  describe('unknown error codes', () => {
+    it('creates fallback error for unknown code without context', () => {
+      const error = createLedgerError('0x9999');
+
+      expect(error).toBeInstanceOf(HardwareWalletError);
+      expect(error.code).toBe(ErrorCodeEnum.Unknown);
+      expect(error.message).toBe('Unknown Ledger error: 0x9999');
+    });
+
+    it('creates fallback error for unknown code with context', () => {
+      const error = createLedgerError('0x9999', 'during operation');
+
+      expect(error).toBeInstanceOf(HardwareWalletError);
+      expect(error.code).toBe(ErrorCodeEnum.Unknown);
+      expect(error.message).toBe(
+        'Unknown Ledger error: 0x9999 (during operation)',
+      );
+    });
+  });
+});
+
+describe('isKnownLedgerError', () => {
+  it('returns true for known error codes', () => {
+    expect(isKnownLedgerError('0x6985')).toBe(true);
+    expect(isKnownLedgerError('0x5515')).toBe(true);
+    expect(isKnownLedgerError('0x6a80')).toBe(true);
+  });
+
+  it('returns false for unknown error codes', () => {
+    expect(isKnownLedgerError('0x9999')).toBe(false);
+    expect(isKnownLedgerError('invalid')).toBe(false);
+    expect(isKnownLedgerError('')).toBe(false);
+  });
+});
+
+describe('getLedgerErrorMapping', () => {
+  it('returns mapping for known error codes', () => {
+    const mapping = getLedgerErrorMapping('0x6985');
+
+    expect(mapping).toBeDefined();
+    expect(mapping?.code).toBe(ErrorCodeEnum.UserRejected);
+    expect(mapping?.message).toBe('User rejected action on device');
+  });
+
+  it('returns undefined for unknown error codes', () => {
+    const mapping = getLedgerErrorMapping('0x9999');
+
+    expect(mapping).toBeUndefined();
+  });
+});

packages/keyring-eth-ledger-bridge/src/errors.ts

@@ -0,0 +1,69 @@
+import {
+  ErrorMapping,
+  ErrorCode,
+  Severity,
+  Category,
+  HardwareWalletError,
+  LEDGER_ERROR_MAPPINGS,
+} from '@metamask/hw-wallet-sdk';
+
+/**
+ * Factory function to create a HardwareWalletError from a Ledger error code.
+ *
+ * @param ledgerErrorCode - The Ledger error code (e.g., '0x6985', '0x5515')
+ * @param context - Optional additional context to append to the error message
+ * @returns A HardwareWalletError instance with mapped error details
+ */
+export function createLedgerError(
+  ledgerErrorCode: string,
+  context?: string,
+): HardwareWalletError {
+  const errorMapping = getLedgerErrorMapping(ledgerErrorCode);
+
+  if (errorMapping) {
+    const message = context
+      ? `${errorMapping.message} (${context})`
+      : errorMapping.message;
+
+    return new HardwareWalletError(message, {
+      code: errorMapping.code,
+      severity: errorMapping.severity,
+      category: errorMapping.category,
+      userMessage: errorMapping.userMessage ?? message,
+    });
+  }
+
+  // Fallback for unknown error codes
+  const fallbackMessage = context
+    ? `Unknown Ledger error: ${ledgerErrorCode} (${context})`
+    : `Unknown Ledger error: ${ledgerErrorCode}`;
+
+  return new HardwareWalletError(fallbackMessage, {
+    code: ErrorCode.Unknown,
+    severity: Severity.Err,
+    category: Category.Unknown,
+    userMessage: fallbackMessage,
+  });
+}
+
+/**
+ * Checks if a Ledger error code exists in the error mappings.
+ *
+ * @param ledgerErrorCode - The Ledger error code to check
+ * @returns True if the error code is mapped, false otherwise
+ */
+export function isKnownLedgerError(ledgerErrorCode: string): boolean {
+  return ledgerErrorCode in LEDGER_ERROR_MAPPINGS;
+}
+
+/**
+ * Gets the error mapping details for a Ledger error code without creating an error instance.
+ *
+ * @param ledgerErrorCode - The Ledger error code to look up
+ * @returns The error mapping details or undefined if not found
+ */
+export function getLedgerErrorMapping(
+  ledgerErrorCode: string,
+): ErrorMapping | undefined {
+  return LEDGER_ERROR_MAPPINGS[ledgerErrorCode];
+}