Add support for multibyte versions + tests + docs (#23)

* correst testing script

* add support for multibyte versions + tests + docs

* fix bip32 tests

Author: jleni

bun.lockb

@@ -21,17 +21,17 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist/**"
+    "dist/**",
+    "LICENSE",
+    "package.json"
   ],
   "scripts": {
     "build": "tsc",
     "format": "FORCE_COLOR=1 prettier --write . && sort-package-json",
     "format:check": "FORCE_COLOR=1 prettier --check .",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
-    "supported": "ts-node src/cmd/cli.ts supported",
-    "test:integration": "yarn build && jest -t 'Integration'",
-    "test:key-derivation": "yarn build && jest -t 'KeyDerivation'",
+    "test": "yarn build && ts-jest",
     "upgrade": "bunx npm-check-updates -i"
   },
   "dependencies": {
@@ -46,14 +46,15 @@
     "@typescript-eslint/parser": "^7.8.0",
     "eslint": "^9.2.0",
     "eslint-config-prettier": "^9.1.0",
-    "eslint-config-standard-with-typescript": "^34.0.1",
+    "eslint-config-standard-with-typescript": "^39.0.0",
     "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-n": "^17.6.0",
+    "eslint-plugin-n": "^17.7.0",
     "eslint-plugin-promise": "^6.1.1",
     "eslint-plugin-tsdoc": "^0.2.17",
     "eslint-plugin-unused-imports": "^3.2.0",
     "prettier": "^3.2.5",
     "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
     "typescript": "^5.4.5"
   },
   "volta": {
@@ -62,5 +63,9 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "moduleDirectories": [
+    "node_modules",
+    "dist"
+  ]
 }

package.json

@@ -43,7 +43,7 @@ describe('BaseApp', () => {
   })
 
   describe('getVersion', () => {
-    it('should retrieve version information', async () => {
+    it('should retrieve version information (5 bytes)', async () => {
       const responseBuffer = Buffer.concat([
         Buffer.from([0, 1, 2, 3, 0]), // Version information
         Buffer.from([0x90, 0x00]), // Status code for no errors (0x9000)
@@ -63,6 +63,66 @@ describe('BaseApp', () => {
       })
     })
 
+    it('should retrieve version information (9 bytes)', async () => {
+      const responseBuffer = Buffer.concat([
+        Buffer.from([1, 2, 3, 4, 0, 0, 0, 0, 0]), // Version information
+        Buffer.from([0x90, 0x00]), // Status code for no errors (0x9000)
+      ])
+
+      const transport = new MockTransport(responseBuffer)
+      const app = new BaseApp(transport, params)
+      const version = await app.getVersion()
+
+      expect(version).toEqual({
+        major: 2,
+        minor: 3,
+        patch: 4,
+        deviceLocked: false,
+        targetId: '00000000',
+        testMode: true,
+      })
+    })
+
+    it('should retrieve version information (8 bytes)', async () => {
+      const responseBuffer = Buffer.concat([
+        Buffer.from([1, 0, 7, 0, 8, 0, 9, 1]), // Version information
+        Buffer.from([0x90, 0x00]), // Status code for no errors (0x9000)
+      ])
+
+      const transport = new MockTransport(responseBuffer)
+      const app = new BaseApp(transport, params)
+      const version = await app.getVersion()
+
+      expect(version).toEqual({
+        major: 7,
+        minor: 8,
+        patch: 9,
+        deviceLocked: true,
+        targetId: '',
+        testMode: true,
+      })
+    })
+
+    it('should retrieve version information (12 bytes)', async () => {
+      const responseBuffer = Buffer.concat([
+        Buffer.from([1, 1, 5, 0, 6, 0, 7, 0, 0, 0xa, 0xb, 0xc]), // Version information
+        Buffer.from([0x90, 0x00]), // Status code for no errors (0x9000)
+      ])
+
+      const transport = new MockTransport(responseBuffer)
+      const app = new BaseApp(transport, params)
+      const version = await app.getVersion()
+
+      expect(version).toEqual({
+        major: 261,
+        minor: 6,
+        patch: 7,
+        deviceLocked: false,
+        targetId: '000a0b0c',
+        testMode: true,
+      })
+    })
+
     it('should handle missing data', async () => {
       const responseBuffer = Buffer.concat([
         Buffer.from([0, 1, 2, 3]), // Version information
@@ -72,7 +132,7 @@ describe('BaseApp', () => {
       const transport = new MockTransport(responseBuffer)
       const app = new BaseApp(transport, params)
 
-      await expect(app.getVersion()).rejects.toEqual(new ResponseError(LedgerError.UnknownError, 'Attempt to read beyond buffer length'))
+      await expect(app.getVersion()).rejects.toEqual(new ResponseError(LedgerError.UnknownError, 'Invalid response length'))
     })
 
     it('should handle errors correctly', async () => {

src/app.test.ts

@@ -29,6 +29,9 @@ import {
   type ResponseVersion,
 } from './types'
 
+/**
+ * Base class for interacting with a Ledger device.
+ */
 export default class BaseApp {
   readonly transport: Transport
   readonly CLA: number
@@ -37,6 +40,11 @@ export default class BaseApp {
   readonly REQUIRED_PATH_LENGTHS?: number[]
   readonly CHUNK_SIZE: number
 
+  /**
+   * Constructs a new BaseApp instance.
+   * @param transport - The transport mechanism to communicate with the device.
+   * @param params - The constructor parameters.
+   */
   constructor(transport: Transport, params: ConstructorParams) {
     this.transport = transport
     this.CLA = params.cla
@@ -46,6 +54,11 @@ export default class BaseApp {
     this.REQUIRED_PATH_LENGTHS = params.acceptedPathLengths
   }
 
+  /**
+   * Serializes a derivation path into a buffer.
+   * @param path - The derivation path in string format.
+   * @returns A buffer representing the serialized path.
+   */
   serializePath(path: string): Buffer {
     return serializePath(path, this.REQUIRED_PATH_LENGTHS)
   }
@@ -54,7 +67,7 @@ export default class BaseApp {
    * Prepares chunks of data to be sent to the device.
    * @param path - The derivation path.
    * @param message - The message to be sent.
-   * @returns An array of buffers ready to be sent.
+   * @returns An array of buffers that are ready to be sent.
    */
   prepareChunks(path: string, message: Buffer): Buffer[] {
     const chunks = []
@@ -114,20 +127,43 @@ export default class BaseApp {
       const responseBuffer = await this.transport.send(this.CLA, this.INS.GET_VERSION, 0, 0)
       const response = processResponse(responseBuffer)
 
-      const testMode = response.readBytes(1).readUInt8() !== 0
-      const major = response.readBytes(1).readUInt8()
-      const minor = response.readBytes(1).readUInt8()
-      const patch = response.readBytes(1).readUInt8()
+      // valid options are
+      // test mode: 1 byte
+      // major, minor, patch: 3 byte total
+      // device locked: 1 byte
+      // targetId: 4 bytes
+      // total: 5 or 9 bytes
+      // -----
+      // test mode: 1 byte
+      // major, minor, patch: 6 byte total
+      // device locked: 1 byte
+      // targetId: 4 bytes
+      // total: 8 or 12 bytes
+
+      let testMode
+      let major, minor, patch
+
+      if (response.length() === 5 || response.length() === 9) {
+        testMode = response.readBytes(1).readUInt8() !== 0
+        major = response.readBytes(1).readUInt8()
+        minor = response.readBytes(1).readUInt8()
+        patch = response.readBytes(1).readUInt8()
+      } else if (response.length() === 8 || response.length() === 12) {
+        testMode = response.readBytes(1).readUInt8() !== 0
+        major = response.readBytes(2).readUInt16BE()
+        minor = response.readBytes(2).readUInt16BE()
+        patch = response.readBytes(2).readUInt16BE()
+      } else {
+        throw new ResponseError(LedgerError.TechnicalProblem, 'Invalid response length')
+      }
 
       const deviceLocked = response.readBytes(1).readUInt8() === 1
 
       let targetId = ''
       if (response.length() >= 4) {
-        targetId = response.readBytes(4).readUInt32BE().toString(16)
+        targetId = response.readBytes(4).readUInt32BE().toString(16).padStart(8, '0')
       }
 
-      // FIXME: Add support for devices with multibyte version numbers
-
       return {
         testMode,
         major,
@@ -140,7 +176,6 @@ export default class BaseApp {
       throw processErrorResponse(error)
     }
   }
-
   /**
    * Retrieves application information from the device.
    * @returns A promise that resolves to the application information.