tessl/npm-ledgerhq--errors

Comprehensive error handling system for Ledger hardware wallet applications and libraries

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Device Management Errors

Name: tessl/npm-ledgerhq--errors
Author: tessl

Error classes for Ledger device management operations including device state validation, connection issues, and hardware-specific errors.

Capabilities

Device Connection Errors

Errors related to establishing and maintaining device connections.

const CantOpenDevice: CustomErrorFunc;
const DisconnectedDevice: CustomErrorFunc;
const DisconnectedDeviceDuringOperation: CustomErrorFunc;
const DeviceSocketFail: CustomErrorFunc;
const DeviceSocketNoBulkStatus: CustomErrorFunc;

Usage Examples:

import { 
  CantOpenDevice,
  DisconnectedDevice,
  DisconnectedDeviceDuringOperation
} from "@ledgerhq/errors";

// Handle device opening failures
try {
  await openDevice();
} catch (error) {
  if (error instanceof CantOpenDevice) {
    console.log("Unable to establish connection to device");
  }
}

// Handle device disconnection
throw new DisconnectedDevice("Device was unplugged");

// Handle disconnection during operation
throw new DisconnectedDeviceDuringOperation("Device disconnected while signing transaction");

Device State Errors

Errors related to device state validation and expected device modes.

const DeviceOnDashboardExpected: CustomErrorFunc;
const DeviceOnDashboardUnexpected: CustomErrorFunc;
const DeviceInOSUExpected: CustomErrorFunc;
const DeviceHalted: CustomErrorFunc;
const UnexpectedBootloader: CustomErrorFunc;
const DeviceShouldStayInApp: CustomErrorFunc;

Usage Examples:

import { 
  DeviceOnDashboardExpected,
  DeviceOnDashboardUnexpected,
  DeviceInOSUExpected,
  DeviceHalted
} from "@ledgerhq/errors";

// Validate device is on dashboard
if (!isOnDashboard) {
  throw new DeviceOnDashboardExpected("Please navigate to the dashboard on your device");
}

// Handle unexpected dashboard state
if (isOnDashboard && needsAppOpen) {
  throw new DeviceOnDashboardUnexpected("Please open the required app on your device");
}

// OSU mode requirement
if (!isInOSUMode) {
  throw new DeviceInOSUExpected("Device must be in OS Update mode");
}

// Handle halted device
if (deviceStatus === "halted") {
  throw new DeviceHalted("Device is in halted state and cannot process requests");
}

Device Authenticity Errors

Errors related to device authenticity and security validation.

const DeviceNotGenuineError: CustomErrorFunc;
const GenuineCheckFailed: CustomErrorFunc;
const DeviceGenuineSocketEarlyClose: CustomErrorFunc;
const MCUNotGenuineToDashboard: CustomErrorFunc;

Usage Examples:

import { 
  DeviceNotGenuineError,
  GenuineCheckFailed,
  DeviceGenuineSocketEarlyClose
} from "@ledgerhq/errors";

// Handle non-genuine device
try {
  await verifyDeviceGenuine();
} catch (error) {
  if (error instanceof DeviceNotGenuineError) {
    console.log("Device failed authenticity check");
    console.log("Please ensure you are using a genuine Ledger device");
  }
}

// General genuine check failure
throw new GenuineCheckFailed("Unable to verify device authenticity");

// Socket closed during genuine check
throw new DeviceGenuineSocketEarlyClose("Connection closed during authenticity verification");

Device Configuration Errors

Errors related to device naming and configuration.

const DeviceNameInvalid: CustomErrorFunc;
const UserRefusedDeviceNameChange: CustomErrorFunc;

Usage Examples:

import { 
  DeviceNameInvalid,
  UserRefusedDeviceNameChange
} from "@ledgerhq/errors";

// Validate device name
function validateDeviceName(name: string) {
  if (!name || name.length > 20 || /[^a-zA-Z0-9\s]/.test(name)) {
    throw new DeviceNameInvalid("Device name must be 1-20 alphanumeric characters");
  }
}

// Handle user refusal to change name
try {
  await changeDeviceName("My Ledger");
} catch (error) {
  if (error instanceof UserRefusedDeviceNameChange) {
    console.log("User cancelled device name change");
  }
}

Hardware Reset Errors

Errors related to hardware reset operations.

const HardResetFail: CustomErrorFunc;

Usage Examples:

import { HardResetFail } from "@ledgerhq/errors";

// Handle hard reset failure
try {
  await performHardReset();
} catch (error) {
  throw new HardResetFail("Device hard reset operation failed");
}