@ledgerhq/device-management-kit 0.0.0-develop-20240925001059

package/lib/esm/src/api/apdu/utils/ByteArrayBuilder.js

@@ -0,0 +1,301 @@
+import { hexaStringToBuffer } from "../../utils/HexaString";
+import { DataOverflowError, HexaStringEncodeError, ValueOverflowError, } from "./AppBuilderError";
+const MAX_32_BIT_UINT = 0xffffffff;
+/**
+ * ByteArrayBuilder is a utility class to help build APDU payloads.
+ * It allows to easily add data to the payload of an APDU command
+ * and to encode this data in different formats.
+ *
+ * @example
+ * ```
+ * const builder = new ByteArrayBuilder(255)
+ *  .add8BitUIntToData(0x05)
+ *  .add16BitUIntToData(0x0607)
+ *  .addHexaStringToData("0x0809")
+ *  .addAsciiStringToData("hello")
+ *
+ * const payload = builder.build();
+ * const builderErrors = builder.getErrors();
+ * ```
+ */
+export class ByteArrayBuilder {
+    maxPayloadSize;
+    data = new Uint8Array();
+    errors = []; // Custom Error
+    constructor(maxPayloadSize = MAX_32_BIT_UINT) {
+        this.maxPayloadSize = maxPayloadSize;
+    }
+    // ==========
+    // Public API
+    // ==========
+    /**
+     * Build a new payload instance with the current state of the builder
+     * @returns {payload} - Returns a new payload instance
+     */
+    build = () => this.data;
+    /**
+     * Try to build a new payload instance with the current state of the builder
+     * if the builder don't contain any error.
+     * @returns {payload | undefined} - Returns a new payload instance or undefined
+     */
+    tryBuild = () => {
+        return this.hasErrors() ? undefined : this.data;
+    };
+    /**
+     * Add a 8-bit unsigned integer to the payload (max value 0xff = 255)
+     * @param value: number | bigint - The value to add to the data
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    add8BitUIntToData = (value) => {
+        return this.addNumberToData(value, 8n, false, false);
+    };
+    /**
+     * Add a 16-bit unsigned integer to the payload (max value 0xffff = 65535)
+     * @param value: number | bigint - The value to add to the data
+     * @param bigEndian: boolean - True to encode in big endian, false for little endian
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    add16BitUIntToData = (value, bigEndian = true) => {
+        return this.addNumberToData(value, 16n, false, bigEndian);
+    };
+    /**
+     * Add a 32-bit unsigned integer to the payload (max value 0xffffffff = 4294967295)
+     * @param value: number | bigint - The value to add to the data
+     * @param bigEndian: boolean - True to encode in big endian, false for little endian
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    add32BitUIntToData = (value, bigEndian = true) => {
+        return this.addNumberToData(value, 32n, false, bigEndian);
+    };
+    /**
+     * Add a 64-bit unsigned integer to the payload (max value 0xffffffffffffffff = 18446744073709551615)
+     * @param value: number | bigint - The value to add to the data
+     * @param bigEndian: boolean - True to encode in big endian, false for little endian
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    add64BitUIntToData = (value, bigEndian = true) => {
+        return this.addNumberToData(value, 64n, false, bigEndian);
+    };
+    /**
+     * Add a 16-bit signed integer to the payload (value between -0x8000 to 0x7fff)
+     * @param value: number | bigint - The value to add to the data
+     * @param bigEndian: boolean - True to encode in big endian, false for little endian
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    add16BitIntToData = (value, bigEndian = true) => {
+        return this.addNumberToData(value, 16n, true, bigEndian);
+    };
+    /**
+     * Add a 32-bit signed integer to the payload (value between -0x80000000 to 0x7fffffff)
+     * @param value: number | bigint - The value to add to the data
+     * @param bigEndian: boolean - True to encode in big endian, false for little endian
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    add32BitIntToData = (value, bigEndian = true) => {
+        return this.addNumberToData(value, 32n, true, bigEndian);
+    };
+    /**
+     * Add a 64-bit signed integer to the payload (value between -0x8000000000000000 to 0x7fffffffffffffff)
+     * @param value: number | bigint - The value to add to the data
+     * @param bigEndian: boolean - True to encode in big endian, false for little endian
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    add64BitIntToData = (value, bigEndian = true) => {
+        return this.addNumberToData(value, 64n, true, bigEndian);
+    };
+    /**
+     * Add a Uint8Array to the payload if it has enough remaining space
+     * @param value: Uint8Array - The value to add to the data
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    addBufferToData = (value) => {
+        if (!this.hasEnoughLengthRemaining(value)) {
+            this.errors.push(new DataOverflowError(value.toString()));
+            return this;
+        }
+        this.data = Uint8Array.from([...this.data, ...value]);
+        return this;
+    };
+    /**
+     * Add a string to the payload if it has enough remaining space
+     * and it can be formatted as a hexadecimal string
+     * @param value: string - The value to add to the data
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    addHexaStringToData = (value) => {
+        const result = hexaStringToBuffer(value);
+        if (result === null || result.length === 0) {
+            this.errors.push(new HexaStringEncodeError(value));
+            return this;
+        }
+        this.addBufferToData(result);
+        return this;
+    };
+    /**
+     * Add an ascii string to the data field if it has enough remaining space
+     * @param value: string - The value to add to the data
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    addAsciiStringToData = (value) => {
+        const bytes = new TextEncoder().encode(value);
+        this.addBufferToData(bytes);
+        return this;
+    };
+    /**
+     * Add a Length-Value encoded hexadecimal string to the data field if it has enough remaining space
+     * Length-Value encoding is a way to encode data in a binary format with the first byte
+     * being the length of the data and the following bytes being the data itself
+     * @param value: string - The value to add to the data
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    encodeInLVFromHexa = (value) => {
+        const result = hexaStringToBuffer(value);
+        if (result === null || result.length === 0) {
+            this.errors.push(new HexaStringEncodeError(value));
+            return this;
+        }
+        if (!this.hasEnoughLengthRemaining(result, true)) {
+            this.errors.push(new DataOverflowError(value));
+            return this;
+        }
+        // values are always being well formatted at this point
+        // therefore no status test is needed
+        this.add8BitUIntToData(result.length);
+        this.addBufferToData(result);
+        return this;
+    };
+    /**
+     * Add a Length-Value encoded buffer to the data field if it has enough remaining space
+     * Length-Value encoding is a way to encode data in a binary format with the first byte
+     * being the length of the data and the following bytes being the data itself
+     * @param value: Uint8Array - The value to add to the data
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    encodeInLVFromBuffer = (value) => {
+        if (!this.hasEnoughLengthRemaining(value, true)) {
+            this.errors.push(new DataOverflowError(value.toString()));
+            return this;
+        }
+        this.add8BitUIntToData(value.length);
+        this.addBufferToData(value);
+        return this;
+    };
+    /**
+     * Add a Length-Value encoded ascii string to the data field if it has enough remaining space
+     * Length-Value encoding is a way to encode data in a binary format with the first byte
+     * being the length of the data and the following bytes being the data itself
+     * @param value: string - The value to add to the data
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    encodeInLVFromAscii = (value) => {
+        if (!this.hasEnoughLengthRemaining(value, true)) {
+            this.errors.push(new DataOverflowError(value));
+            return this;
+        }
+        this.add8BitUIntToData(value.length);
+        this.addAsciiStringToData(value);
+        return this;
+    };
+    /**
+     * Returns the remaining payload length
+     * @returns {number}
+     */
+    getAvailablePayloadLength = () => {
+        return this.maxPayloadSize - this.data.length;
+    };
+    /**
+     * Returns the current errors
+     * @returns {AppBuilderError[]} - Returns an array of errors
+     */
+    getErrors = () => this.errors;
+    /**
+     * Verifies if the builder contains errors
+     * @returns {boolean} - Returns wether the builder contains errors or not
+     */
+    hasErrors = () => this.errors.length !== 0;
+    // ===========
+    // Private API
+    // ===========
+    /**
+     * Check if there is enough space to add a value to the data field
+     * @param value {string | Uint8Array | number[]} - Value to add to the data
+     * @param hasLv {boolean} - Length-Value encoding flag
+     * @returns {boolean} - Returns true if there is enough space to add the value
+     */
+    hasEnoughLengthRemaining = (value, hasLv = false) => {
+        return (this.data.length + value.length + (hasLv ? 1 : 0) <= this.maxPayloadSize);
+    };
+    /**
+     * Add a number to the payload
+     * @param value: number | bigint - The value to add to the data
+     * @param sizeInBits: bigint - The number size in bits, for example 16 for a uint16
+     * @param signed: boolean - Whether the value is signed or unsigned.
+     * @param bigEndian: boolean - True to encode in big endian, false for little endian
+     * @returns {ByteArrayBuilder} - Returns the current instance of ByteArrayBuilder
+     */
+    addNumberToData(value, sizeInBits, signed, bigEndian) {
+        // Convert the number to two's complement and check its bounds
+        let converted = this.checkBoundsAndConvert(value, sizeInBits, signed);
+        if (converted === undefined) {
+            return this;
+        }
+        // Compute the buffer
+        const sizeInBytes = Number(sizeInBits) / 8;
+        const buffer = new Uint8Array(sizeInBytes);
+        if (bigEndian) {
+            for (let i = sizeInBytes - 1; i >= 0; i--) {
+                buffer[i] = Number(converted & 0xffn);
+                converted >>= 8n;
+            }
+        }
+        else {
+            for (let i = 0; i < sizeInBytes; i++) {
+                buffer[i] = Number(converted & 0xffn);
+                converted >>= 8n;
+            }
+        }
+        return this.addBufferToData(buffer);
+    }
+    /**
+     * Checks the bounds of a signed or unsigned integer value and converts it to two's complement if it is signed and negative.
+     * @param value The value to check and convert.
+     * @param sizeInBits The size of the value in bits.
+     * @param signed Whether the value is signed or unsigned.
+     * @returns The converted value, or null if the value is out of bounds.
+     */
+    checkBoundsAndConvert(value, sizeInBits, signed) {
+        // Normalize the value to a bigint
+        if (typeof value === "number") {
+            if (!Number.isInteger(value) || value > Number.MAX_SAFE_INTEGER) {
+                this.errors.push(new ValueOverflowError(value.toString()));
+                return;
+            }
+            value = BigInt(value);
+        }
+        if (!signed) {
+            // Check if the value is within the bounds of an unsigned integer
+            const limit = 1n << sizeInBits;
+            if (value < 0 || value >= limit) {
+                this.errors.push(new ValueOverflowError(value.toString(), limit - 1n));
+                return;
+            }
+        }
+        else {
+            // Check if the value is within the bounds of a signed integer
+            const limit = 1n << (sizeInBits - 1n);
+            if (value >= limit || value < -limit) {
+                this.errors.push(new ValueOverflowError(value.toString(), limit - 1n));
+                return;
+            }
+            // Convert the value to two's complement if it is negative
+            // https://en.wikipedia.org/wiki/Two%27s_complement
+            if (value < 0n) {
+                const mask = (1n << sizeInBits) - 1n;
+                value = -value;
+                value = (~value & mask) + 1n;
+            }
+        }
+        return value;
+    }
+}
+//# sourceMappingURL=ByteArrayBuilder.js.map

package/lib/esm/src/api/apdu/utils/ByteArrayBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ByteArrayBuilder.js","sourceRoot":"","sources":["../../../../../../src/api/apdu/utils/ByteArrayBuilder.ts"],"names":[],"mappings":"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"}

package/lib/esm/src/api/apdu/utils/ByteArrayParser.d.ts

@@ -0,0 +1,128 @@
+import { HexaString } from "../../utils/HexaString";
+export type TaggedField = {
+    readonly tag: number;
+    readonly value: Uint8Array;
+};
+/**
+ * ByteArrayParser is a utility class to help parse a byte array.
+ *
+ * It provides methods to extract fields of different types from the buffer.
+ *
+ * @example
+ * ```
+ * const parser = new ByteArrayParser(buffer);
+ * const targetId = parser.encodeToHexaString(parser.extractFieldByLength(4));
+ * const seVersion = parser.encodeToString(parser.extractFieldLVEncoded());
+ * ```
+ */
+export declare class ByteArrayParser {
+    private readonly buffer;
+    private index;
+    constructor(buffer: Uint8Array);
+    /**
+     * Test if the length is greater than the response length
+     * @param length: number
+     * @returns {boolean} - Returns false if the length is greater than the response length
+     */
+    testMinimalLength(length: number): boolean;
+    /**
+     * Extract a single byte from the response
+     * @returns {number | undefined} - Returns the byte extracted from the response
+     */
+    extract8BitUInt(): number | undefined;
+    /**
+     * Extract a 16-bit unsigned integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 16-bit unsigned integer extracted from the response
+     */
+    extract16BitUInt(bigEndian?: boolean): number | undefined;
+    /**
+     * Extract a 16-bit signed integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 16-bit signed integer extracted from the response
+     */
+    extract16BitInt(bigEndian?: boolean): number | undefined;
+    /**
+     * Extract a 32-bit unsigned integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 32-bit unsigned integer extracted from the response
+     */
+    extract32BitUInt(bigEndian?: boolean): number | undefined;
+    /**
+     * Extract a 32-bit signed integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 32-bit signed integer extracted from the response
+     */
+    extract32BitInt(bigEndian?: boolean): number | undefined;
+    /**
+     * Extract a 64-bit unsigned integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 64-bit unsigned integer extracted from the response
+     */
+    extract64BitUInt(bigEndian?: boolean): bigint | undefined;
+    /**
+     * Extract a 64-bit signed integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 64-bit signed integer extracted from the response
+     */
+    extract64BitInt(bigEndian?: boolean): bigint | undefined;
+    /**
+     * Extract a field of a specified length from the response
+     * @param length: number - The length of the field to extract
+     * @returns {Uint8Array | undefined} - Returns the field extracted from the response
+     */
+    extractFieldByLength(length: number): Uint8Array | undefined;
+    /**
+     * Extract a field from the response that is length-value encoded
+     * @returns {Uint8Array | undefined} - Returns the field extracted from the response
+     */
+    extractFieldLVEncoded(): Uint8Array | undefined;
+    /**
+     * Extract a field from the response that is tag-length-value encoded
+     * @returns {TaggedField | undefined} - Returns the field extracted from the response
+     */
+    extractFieldTLVEncoded(): TaggedField | undefined;
+    /**
+     * Encode a value to a hexadecimal string
+     * @param value {Uint8Array} - The value to encode
+     * @param prefix {boolean} - Whether to add a prefix to the encoded value
+     * @returns {string} - The encoded value as a hexadecimal string
+     */
+    encodeToHexaString(value?: Uint8Array, prefix?: false): string;
+    encodeToHexaString(value?: Uint8Array, prefix?: true): HexaString;
+    /**
+     * Encode a value to an ASCII string
+     * @param value {Uint8Array} - The value to encode
+     * @returns {string} - The encoded value as an ASCII string
+     */
+    encodeToString(value?: Uint8Array): string;
+    /**
+     * Get the current index of the parser
+     * @returns {number} - The current index of the parser
+     */
+    getCurrentIndex(): number;
+    /**
+     * Reset the index of the parser to 0
+     */
+    resetIndex(): void;
+    /**
+     * Get the remaining length of the response
+     * @returns {number} - The remaining length of the response
+     */
+    getUnparsedRemainingLength(): number;
+    /**
+     * Check whether the expected length is out of range
+     * @param length: number
+     * @returns {boolean} - Returns true if the expected length is out of range
+     */
+    private outOfRange;
+    /**
+     * Extract a number from the buffer
+     * @param sizeInBits: bigint - The number size in bits, for example 16 for a uint16
+     * @param signed: boolean - True is the number can be signed and converted to two's compliment
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {bigint | undefined} - Returns the number extracted from the buffer
+     */
+    private extractNumber;
+}
+//# sourceMappingURL=ByteArrayParser.d.ts.map

package/lib/esm/src/api/apdu/utils/ByteArrayParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ByteArrayParser.d.ts","sourceRoot":"","sources":["../../../../../../src/api/apdu/utils/ByteArrayParser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEvE,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,KAAK,CAAa;gBAEG,MAAM,EAAE,UAAU;IAM/C;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI1C;;;OAGG;IACH,eAAe,IAAI,MAAM,GAAG,SAAS;IAKrC;;;;OAIG;IACH,gBAAgB,CAAC,SAAS,GAAE,OAAc,GAAG,MAAM,GAAG,SAAS;IAK/D;;;;OAIG;IACH,eAAe,CAAC,SAAS,GAAE,OAAc,GAAG,MAAM,GAAG,SAAS;IAK9D;;;;OAIG;IACH,gBAAgB,CAAC,SAAS,GAAE,OAAc,GAAG,MAAM,GAAG,SAAS;IAK/D;;;;OAIG;IACH,eAAe,CAAC,SAAS,GAAE,OAAc,GAAG,MAAM,GAAG,SAAS;IAK9D;;;;OAIG;IACH,gBAAgB,CAAC,SAAS,GAAE,OAAc,GAAG,MAAM,GAAG,SAAS;IAI/D;;;;OAIG;IACH,eAAe,CAAC,SAAS,GAAE,OAAc,GAAG,MAAM,GAAG,SAAS;IAI9D;;;;OAIG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAQ5D;;;OAGG;IACH,qBAAqB,IAAI,UAAU,GAAG,SAAS;IAW/C;;;OAGG;IACH,sBAAsB,IAAI,WAAW,GAAG,SAAS;IAajD;;;;;OAKG;IACH,kBAAkB,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM;IAC9D,kBAAkB,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,IAAI,GAAG,UAAU;IAUjE;;;;OAIG;IACH,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM;IAe1C;;;OAGG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,UAAU;IAIV;;;OAGG;IACH,0BAA0B,IAAI,MAAM;IAQpC;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAIlB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;CAiCtB"}

package/lib/esm/src/api/apdu/utils/ByteArrayParser.js

@@ -0,0 +1,229 @@
+import { bufferToHexaString } from "../../utils/HexaString";
+/**
+ * ByteArrayParser is a utility class to help parse a byte array.
+ *
+ * It provides methods to extract fields of different types from the buffer.
+ *
+ * @example
+ * ```
+ * const parser = new ByteArrayParser(buffer);
+ * const targetId = parser.encodeToHexaString(parser.extractFieldByLength(4));
+ * const seVersion = parser.encodeToString(parser.extractFieldLVEncoded());
+ * ```
+ */
+export class ByteArrayParser {
+    buffer;
+    index = 0;
+    constructor(buffer) {
+        this.buffer = buffer;
+    }
+    // ==========
+    // Public API
+    // ==========
+    /**
+     * Test if the length is greater than the response length
+     * @param length: number
+     * @returns {boolean} - Returns false if the length is greater than the response length
+     */
+    testMinimalLength(length) {
+        return length <= this.buffer.length - this.index;
+    }
+    /**
+     * Extract a single byte from the response
+     * @returns {number | undefined} - Returns the byte extracted from the response
+     */
+    extract8BitUInt() {
+        if (this.outOfRange(1))
+            return;
+        return this.buffer[this.index++];
+    }
+    /**
+     * Extract a 16-bit unsigned integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 16-bit unsigned integer extracted from the response
+     */
+    extract16BitUInt(bigEndian = true) {
+        const value = this.extractNumber(16n, false, bigEndian);
+        return value === undefined ? undefined : Number(value);
+    }
+    /**
+     * Extract a 16-bit signed integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 16-bit signed integer extracted from the response
+     */
+    extract16BitInt(bigEndian = true) {
+        const value = this.extractNumber(16n, true, bigEndian);
+        return value === undefined ? undefined : Number(value);
+    }
+    /**
+     * Extract a 32-bit unsigned integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 32-bit unsigned integer extracted from the response
+     */
+    extract32BitUInt(bigEndian = true) {
+        const value = this.extractNumber(32n, false, bigEndian);
+        return value === undefined ? undefined : Number(value);
+    }
+    /**
+     * Extract a 32-bit signed integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 32-bit signed integer extracted from the response
+     */
+    extract32BitInt(bigEndian = true) {
+        const value = this.extractNumber(32n, true, bigEndian);
+        return value === undefined ? undefined : Number(value);
+    }
+    /**
+     * Extract a 64-bit unsigned integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 64-bit unsigned integer extracted from the response
+     */
+    extract64BitUInt(bigEndian = true) {
+        return this.extractNumber(64n, false, bigEndian);
+    }
+    /**
+     * Extract a 64-bit signed integer from the response
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {number | undefined} - Returns the 64-bit signed integer extracted from the response
+     */
+    extract64BitInt(bigEndian = true) {
+        return this.extractNumber(64n, true, bigEndian);
+    }
+    /**
+     * Extract a field of a specified length from the response
+     * @param length: number - The length of the field to extract
+     * @returns {Uint8Array | undefined} - Returns the field extracted from the response
+     */
+    extractFieldByLength(length) {
+        if (this.outOfRange(length))
+            return;
+        if (length === 0)
+            return new Uint8Array();
+        const field = this.buffer.slice(this.index, this.index + length);
+        this.index += length;
+        return field;
+    }
+    /**
+     * Extract a field from the response that is length-value encoded
+     * @returns {Uint8Array | undefined} - Returns the field extracted from the response
+     */
+    extractFieldLVEncoded() {
+        // extract Length field
+        const length = this.extract8BitUInt();
+        if (length === undefined)
+            return;
+        else if (length === 0)
+            return new Uint8Array();
+        const field = this.extractFieldByLength(length);
+        // if the field is inconsistent then roll back to the initial point
+        if (field === undefined)
+            this.index--;
+        return field;
+    }
+    /**
+     * Extract a field from the response that is tag-length-value encoded
+     * @returns {TaggedField | undefined} - Returns the field extracted from the response
+     */
+    extractFieldTLVEncoded() {
+        if (this.outOfRange(2))
+            return;
+        const tag = this.extract8BitUInt();
+        const value = this.extractFieldLVEncoded();
+        if (tag === undefined || value === undefined) {
+            this.index--;
+            return;
+        }
+        return { tag, value };
+    }
+    encodeToHexaString(value, prefix = false) {
+        if (value === undefined || value.length === 0)
+            return "";
+        const result = bufferToHexaString(value);
+        return prefix ? result : result.slice(2);
+    }
+    /**
+     * Encode a value to an ASCII string
+     * @param value {Uint8Array} - The value to encode
+     * @returns {string} - The encoded value as an ASCII string
+     */
+    encodeToString(value) {
+        let result = "";
+        let index = 0;
+        if (!value)
+            return result;
+        while (index <= value.length) {
+            const item = value[index];
+            if (item)
+                result += String.fromCharCode(item);
+            index++;
+        }
+        return result;
+    }
+    /**
+     * Get the current index of the parser
+     * @returns {number} - The current index of the parser
+     */
+    getCurrentIndex() {
+        return this.index;
+    }
+    /**
+     * Reset the index of the parser to 0
+     */
+    resetIndex() {
+        this.index = 0;
+    }
+    /**
+     * Get the remaining length of the response
+     * @returns {number} - The remaining length of the response
+     */
+    getUnparsedRemainingLength() {
+        return this.buffer.length - this.index;
+    }
+    // ===========
+    // Private API
+    // ===========
+    /**
+     * Check whether the expected length is out of range
+     * @param length: number
+     * @returns {boolean} - Returns true if the expected length is out of range
+     */
+    outOfRange(length) {
+        return this.index + length > this.buffer.length;
+    }
+    /**
+     * Extract a number from the buffer
+     * @param sizeInBits: bigint - The number size in bits, for example 16 for a uint16
+     * @param signed: boolean - True is the number can be signed and converted to two's compliment
+     * @param bigEndian: boolean - True to decode in big endian, false for little endian
+     * @returns {bigint | undefined} - Returns the number extracted from the buffer
+     */
+    extractNumber(sizeInBits, signed, bigEndian) {
+        // Check the range
+        const sizeInBytes = Number(sizeInBits) / 8;
+        if (this.outOfRange(sizeInBytes))
+            return;
+        // Compute the number
+        let value = 0n;
+        if (bigEndian) {
+            for (let i = 0; i < sizeInBytes; i++) {
+                value = (value << 8n) | BigInt(this.buffer[i + this.index]);
+            }
+        }
+        else {
+            for (let i = sizeInBytes - 1; i >= 0; i--) {
+                value = (value << 8n) | BigInt(this.buffer[i + this.index]);
+            }
+        }
+        // Convert the value to two's complement if it is negative
+        // https://en.wikipedia.org/wiki/Two%27s_complement
+        if (signed) {
+            const limit = 1n << (sizeInBits - 1n);
+            if (value & limit) {
+                value -= limit << 1n;
+            }
+        }
+        this.index += sizeInBytes;
+        return value;
+    }
+}
+//# sourceMappingURL=ByteArrayParser.js.map