@reversense/dxc-struct 1.0.7

package/src/StructDecoder.ts

@@ -0,0 +1,199 @@
+/*
+ *
+ *     Reversense platform / dxc-struct :  Reversense is an automated reverse engineering and analysis platform
+ *     focused on security, privacy, quality, accessibility and safety assessment of software, including mobile app and firmware.
+ *     Copyright (C) 2026  Reversense SAS
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Affero General Public License as published
+ *     by the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     GNU Affero General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Affero General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+import {Endianness} from "./common.js";
+import {Operation} from "./Struct.js";
+
+
+/**
+ * A utility class for decoding structured binary data into various data types.
+ * This class provides methods for byte-level transformations and conversions,
+ * mainly focusing on interpreting raw binary arrays as different primitive types.
+ */
+export class StructDecoder {
+
+    // Raw byte arrays
+    /**
+     * Creates a subarray from the provided array, starting at the specified offset and including the defined number of elements.
+     *
+     * @param {any[]} pArr - The source array from which to extract elements.
+     * @param {number} pOffset - The starting index in the source array for extraction.
+     * @param {number} pLength - The number of elements to include in the subarray.
+     * @return {any[]} A new array containing elements extracted from the source array.
+     */
+    static byteArray(pArr:any[], pOffset:number, pLength:number):any[] {
+        return [pArr.slice(pOffset,pOffset+pLength)];
+    }
+
+
+    /**
+     * Converts the character code at the specified offset in the provided array to a character.
+     *
+     * @param {number[]} pArr - An array of numbers representing character codes.
+     * @param {number} pOffset - The index of the character code within the array to be converted.
+     * @return {string} The character corresponding to the character code at the specified offset.
+     */
+    static chr(pArr:number[], pOffset:number):string {
+        return String.fromCharCode(pArr[pOffset]);
+    }
+
+
+    // Read an (un)signed integers up to 32 bits.
+    /**
+     * Processes an array of bytes to extract an integer value based on endianness and operation specifications.
+     *
+     * @param {Endianness} pEndianness The endianness for reading the bytes (BIG_ENDIAN or LITTLE_ENDIAN).
+     * @param {Operation} pOp The operation specification that includes options like size and signedness.
+     * @param {any} pArr The array or buffer containing the bytes to process.
+     * @param {number} pOffset The starting offset in the array from where to begin processing.
+     * @return {number} The resulting integer value derived from the provided byte array and operation.
+     */
+    static int(pEndianness:Endianness, pOp:Operation, pArr: any, pOffset: number) : number {
+        let lsb:number, nsb:number;
+        if(pEndianness==Endianness.BIG_ENDIAN){
+            lsb = pOp.opts.size-1;
+            nsb = -1;
+        }else{
+            lsb = 0;
+            nsb = 1;
+        }
+
+        let stop = lsb+nsb*pOp.opts.size, rv, i, f;
+        for (rv = 0, i = lsb, f = 1; i != stop; rv+=(pArr[pOffset+i]*f), i+=nsb, f*=256);
+
+        // todo : replace by lsl
+        if (pOp.opts.bSigned && (rv & Math.pow(2, pOp.opts.size*8-1))) {
+            rv -= Math.pow(2, pOp.opts.size*8);
+        }
+        return rv;
+    };
+
+    // Read an (un)signed integers. This functions can support integers of more than 64 bits.
+    /**
+     * Decodes a sequence of bytes into a bigint value, with support for endianness and signed/unsigned formats.
+     *
+     * @param {Endianness} pEndianness The byte order, either LITTLE_ENDIAN or BIG_ENDIAN.
+     * @param {Operation} pOp An object describing the operation details (e.g., size and signed/unsigned format).
+     * @param {any} pArr The array or buffer containing the bytes to decode.
+     * @param {number} pOffset The offset in the array where decoding should begin.
+     * @return {bigint} The decoded bigint value.
+     */
+    static bigintDecoder(pEndianness:Endianness, pOp:Operation, pArr: any, pOffset: number) : bigint {
+
+        let lsb:number, nsb:number;
+        if(pEndianness==Endianness.BIG_ENDIAN){
+            lsb = pOp.opts.size-1;
+            nsb = -1;
+        }else{
+            lsb = 0;
+            nsb = 1;
+        }
+
+        let stop : number = lsb+nsb*pOp.opts.size;
+        let i : number;
+        let rv : bigint = BigInt(0);
+        let f : bigint = BigInt(1);
+        for (i = lsb; i != stop; i += nsb) {
+            rv += BigInt(pArr[pOffset + i]) * f;
+            f *= BigInt(256);
+        }
+        // Checks if it is a signed format, and if MSB is 1.
+        if (pOp.opts.bSigned && (rv >> BigInt(pOp.opts.size * 8 - 1)) == BigInt(1)) {
+            rv -= BigInt(1) << BigInt(pOp.opts.size*8);
+        }
+        return rv;
+    };
+
+
+    // ASCII character strings
+    /**
+     * Converts a segment of an array of numbers into a string, where each number is treated
+     * as the Unicode value of a character.
+     *
+     * @param {number[]} pArr - The array of numbers representing character Unicode values.
+     * @param {number} pOffset - The starting index in the array from where to begin processing.
+     * @param {number} pLen - The length of the segment to process from the array.
+     * @return {string} A string created by converting the specified segment of the number array.
+     */
+    static str(pArr:number[], pOffset:number, pLen:number):string {
+        let s:any[] = new Array(pLen);
+        for (let i = 0; i < pLen; s[i] = String.fromCharCode(pArr[pOffset+i]), i++);
+        return s.join('');
+    };
+
+
+    // ASCII character strings null terminated
+    /**
+     * Converts a portion of a given array into a null-terminated string, removing the trailing null character.
+     *
+     * @param {number[]} pArr - The array containing the string data.
+     * @param {number} pOffset - The starting index in the array to process.
+     * @param {number} pLen - The length of the portion of the array to process.
+     * @return {string} A null-terminated string extracted from the array.
+     */
+    static nullTerminatedStr(pArr:number[], pOffset:number, pLen:number) {
+        let str = StructDecoder.str(pArr, pOffset, pLen);
+        return str.substring(0, str.length - 1);
+    };
+
+    // Little-endian N-bit IEEE 754 floating point
+    /**
+     * Converts a floating-point number represented in IEEE 754 format based on the provided endianness and operation configuration.
+     *
+     * @param {Endianness} pEndianness The endianness of the byte array, either big-endian or little-endian.
+     * @param {Operation} pOp An object containing operation configuration, including size and mantissa length (mLen).
+     * @param {any[]} pArr The byte array containing the floating-point number in IEEE 754 format.
+     * @param {number} pOffset The offset within the byte array to start reading the floating-point number.
+     * @return {number} The resulting floating-point number in JavaScript's native format, or NaN/Infinity for special cases.
+     */
+    static ieee754_fp(pEndianness:Endianness, pOp:Operation, pArr:any[], pOffset:number):number {
+        let s, e, m, i, d, nBits, mLen, eLen, eBias, eMax;
+        mLen = pOp.opts.mLen, eLen = pOp.opts.size*8-pOp.opts.mLen-1, eMax = (1<<eLen)-1, eBias = eMax>>1;
+
+        i = (pEndianness==Endianness.BIG_ENDIAN)?0:(pOp.opts.size-1);
+        d = (pEndianness==Endianness.BIG_ENDIAN)?1:-1;
+        s = pArr[pOffset+i];
+        i+=d;
+        nBits = -7;
+
+        for (e = s&((1<<(-nBits))-1), s>>=(-nBits), nBits += eLen; nBits > 0; e=e*256+pArr[pOffset+i], i+=d, nBits-=8);
+        for (m = e&((1<<(-nBits))-1), e>>=(-nBits), nBits += mLen; nBits > 0; m=m*256+pArr[pOffset+i], i+=d, nBits-=8);
+
+        switch (e) {
+            case 0:
+                // Zero, or denormalized number
+                /**
+                 *
+                 */
+                e = 1-eBias;
+                break;
+            case eMax:
+                // NaN, or +/-Infinity
+                return m?NaN:((s?-1:1)*Infinity);
+            default:
+                // Normalized number
+                m = m + Math.pow(2, mLen);
+                e = e - eBias;
+                break;
+        }
+        return (s?-1:1) * m * Math.pow(2, e-mLen);
+    };
+}

package/src/StructEncoder.ts

@@ -0,0 +1,185 @@
+/*
+ *
+ *     Reversense platform / dxc-struct :  Reversense is an automated reverse engineering and analysis platform
+ *     focused on security, privacy, quality, accessibility and safety assessment of software, including mobile app and firmware.
+ *     Copyright (C) 2026  Reversense SAS
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Affero General Public License as published
+ *     by the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     GNU Affero General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Affero General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+import {Endianness} from "./common.js";
+import {Operation} from "./Struct.js";
+
+/**
+ * A utility class for encoding various data types into byte arrays, supporting operations on strings, integers, floating-point numbers,
+ * and big integers. This class provides methods for handling data representation with specific endianness and constraints.
+ */
+export class StructEncoder {
+
+
+    /**
+     *
+     * Copy from array source `pSourceArr` to another array `pDestArr`, from offset
+     *
+     * @param {number[]} pDestArr Array where data are wrote
+     * @param {number} pOffset
+     * @param {number} pLen
+     * @param {number[]} pSourceArr Array to copy from offset 0 to `pLen`. Read 0 if out of bound.
+     */
+    static byteArray(pDestArr:number[], pOffset:number, pLen:number, pSourceArr:number[]) {
+        for (let i = 0; i < pLen; pDestArr[pOffset+i] = pSourceArr[i]?pSourceArr[i]:0, i++);
+    }
+
+
+    /**
+     * Copy a char `pChar` to `pDestArr`at offset `pOffset`
+     *
+     * @param pDestArr
+     * @param pOffset
+     * @param pChar
+     */
+    static chr(pDestArr:number[], pOffset:number, pChar:string):void {
+        pDestArr[pOffset] = pChar.charCodeAt(0);
+    };
+
+
+    /**
+     * Copies characters from a source string to a destination array.
+     *
+     * @param {number[]} pDestArr - The destination array to copy the characters to.
+     * @param {number} pOffset - The starting offset in the destination array.
+     * @param {number} pLen - The length of characters to copy.
+     * @param {string} pSourceStr - The source string to copy characters from.
+     * @returns {void}
+     */
+    static str(pDestArr:number[], pOffset:number, pLen:number, pSourceStr:string):void {
+        for (let t, i = 0; i < pLen; pDestArr[pOffset+i] = (t=pSourceStr.charCodeAt(i))?t:0, i++);
+    };
+
+    /**
+     * Encodes an integer value into a specified array in accordance with the provided endianness and operation configuration.
+     *
+     * @param {Endianness} pEndianness The endianness (BIG_ENDIAN or LITTLE_ENDIAN) to be used for encoding the integer.
+     * @param {Operation} pOp An operation object containing options such as size, minimum, and maximum permissible values for the integer.
+     * @param {any[]} pArr The array in which the encoded integer will be stored.
+     * @param {number} pOffset The offset in the array where the encoded integer will be written.
+     * @param {number} v The integer value to be encoded into the array.
+     * @return {void} This method does not return a value.
+     */
+    static int(pEndianness:Endianness, pOp:Operation, pArr:any[], pOffset:number, v:number):void {
+        let lsb:number, nsb:number; // lsb = (pEndianness==Endianness.BIG_ENDIAN)?(pOp.opts.size-1) : 0;
+        //let nsb = bBE?-1:1;
+        if(pEndianness==Endianness.BIG_ENDIAN){
+            lsb = pOp.opts.size-1;
+            nsb = -1;
+        }else{
+            lsb = 0;
+            nsb = 1;
+        }
+        let stop = lsb+nsb*pOp.opts.size, i;
+
+        v = (v<pOp.opts.min)?pOp.opts.min:(v>pOp.opts.max)?pOp.opts.max:v;
+        for (i = lsb; i != stop; pArr[pOffset+i]=v&0xff, i+=nsb, v>>=8);
+    };
+
+    // Encode bigInt into an array.
+
+    /**
+     * Encodes a bigint value into a byte array based on specified endianness and operation parameters.
+     *
+     * @param {Endianness} pEndianness - Specifies the byte order (either BIG_ENDIAN or LITTLE_ENDIAN).
+     * @param {Operation} pOp - Contains options such as size, minimum, and maximum allowed values for encoding.
+     * @param {any[]} pArr - The target array where the encoded bytes should be stored.
+     * @param {number} pOffset - The starting position in the target array for storing the encoded bytes.
+     * @param {bigint} v - The bigint value to be encoded within bounds specified by the operation.
+     * @return {void} This method does not return any value.
+     */
+    static bigintEncoder(pEndianness:Endianness, pOp:Operation, pArr:any[], pOffset:number, v:bigint):void {
+        let lsb:number, nsb:number; // lsb = (pEndianness==Endianness.BIG_ENDIAN)?(pOp.opts.size-1) : 0;
+        if(pEndianness==Endianness.BIG_ENDIAN){
+            lsb = pOp.opts.size-1;
+            nsb = -1;
+        }else{
+            lsb = 0;
+            nsb = 1;
+        }
+        let stop = lsb+nsb*pOp.opts.size, i;
+
+        v = BigInt((v<pOp.opts.min)?pOp.opts.min:(v>pOp.opts.max)?pOp.opts.max:v);
+        for (i = lsb; i != stop; pArr[pOffset+i]=v&BigInt(0xff), i+=nsb, v>>=BigInt(8));
+    }
+
+
+    // Little-endian N-bit IEEE 754 floating point
+    /**
+     * Converts a given floating point number to IEEE754 format and stores it in a destination array.
+     *
+     * @param {Endianness} pEndianness - The endianness of the destination array.
+     * @param {Operation} pOp - The operation to perform during conversion (e.g., single precision, double precision, etc.).
+     * @param {any[]} pDestArr - The destination array to store the converted value.
+     * @param {number} pOffset - The offset in the destination array to start storing the converted value.
+     * @param {number} pValue - The floating point number to convert.
+     * @return {void}
+     */
+    static ieee754_fp(pEndianness:Endianness, pOp:Operation, pDestArr:any[], pOffset:number, pValue:number) {
+        let s, e, m, i, d, c, mLen, eLen, eBias, eMax, abs:number;
+        mLen = pOp.opts.mLen, eLen = pOp.opts.size*8-pOp.opts.mLen-1, eMax = (1<<eLen)-1, eBias = eMax>>1;
+
+        // signed
+        s = pValue<0?1:0;
+        // abs
+        abs = Math.abs(pValue);
+        if (isNaN(abs) || (abs == Infinity)) {
+            m = isNaN(abs)?1:0;
+            e = eMax;
+        } else {
+            e = Math.floor(Math.log(abs)/Math.LN2);			// Calculate log2 of the value
+
+            if (abs*(c = Math.pow(2, -e)) < 1) {
+                e--; c*=2;						// Math.log() isn't 100% reliable
+            }
+
+            // Round by adding 1/2 the significand's LSD
+            if (e+eBias >= 1) {
+                abs += pOp.opts.rt/c;                                           // Normalized:  mLen significand digits
+            } else {
+                abs += pOp.opts.rt*Math.pow(2, 1-eBias);                        // Denormalized:  <= mLen significand digits
+            }
+
+            if (abs*c >= 2) {
+                e++; c/=2;						// Rounding can increment the exponent
+            }
+
+            if (e+eBias >= eMax) {
+                // Overflow
+                m = 0;
+                e = eMax;
+            } else if (e+eBias >= 1) {
+                // Normalized - term order matters, as Math.pow(2, 52-e) and v*Math.pow(2, 52) can overflow
+                m = (abs*c-1)*Math.pow(2, mLen);
+                e = e + eBias;
+            } else {
+                // Denormalized - also catches the '0' case, somewhat by chance
+                m = abs*Math.pow(2, eBias-1)*Math.pow(2, mLen);
+                e = 0;
+            }
+        }
+
+        for (i = (pEndianness==Endianness.BIG_ENDIAN)?(pOp.opts.size-1):0, d=(pEndianness==Endianness.BIG_ENDIAN)?-1:1; mLen >= 8; pDestArr[pOffset+i]=m&0xff, i+=d, m/=256, mLen-=8);
+        for (e=(e<<mLen)|m, eLen+=mLen; eLen > 0; pDestArr[pOffset+i]=e&0xff, i+=d, e/=256, eLen-=8);
+        pDestArr[pOffset+i-d] |= s*128;
+    };
+
+}

package/src/common.ts

@@ -0,0 +1,25 @@
+/*
+ *
+ *     Reversense platform / dxc-struct :  Reversense is an automated reverse engineering and analysis platform
+ *     focused on security, privacy, quality, accessibility and safety assessment of software, including mobile app and firmware.
+ *     Copyright (C) 2026  Reversense SAS
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Affero General Public License as published
+ *     by the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     GNU Affero General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Affero General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+export enum Endianness {
+    LITTLE_ENDIAN,
+    BIG_ENDIAN
+}

package/src/error/MonitoredError.ts

@@ -0,0 +1,90 @@
+
+
+
+
+/*
+ *
+ *     Reversense platform / dxc-struct :  Reversense is an automated reverse engineering and analysis platform
+ *     focused on security, privacy, quality, accessibility and safety assessment of software, including mobile app and firmware.
+ *     Copyright (C) 2026  Reversense SAS
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Affero General Public License as published
+ *     by the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     GNU Affero General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Affero General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+/**
+ *
+ */
+export class MonitoredError extends Error {
+
+    static ERR_CODE_BASE = 1000;
+
+    static NEW_HOOK:((pErr:MonitoredError|null)=>void) = (()=>{});
+
+    /**
+     * Component name
+     *
+     * @field
+     * @type string
+     */
+    cmp:string;
+    code:number;
+    extra:any;
+
+    constructor( pCmp:string, pMsg:string, pCode = -1, pExtra:any = null) {
+        super(pMsg);
+        this.cmp = pCmp;
+        this.code = pCode;
+        this.extra = pExtra;
+    }
+
+    getCode():number {
+        return this.code;
+    }
+
+    getMessage():string {
+        return `[${this.cmp}][#${this.code}] ${this.message} `;
+    }
+
+    getExtra():any {
+        return this.extra;
+    }
+
+    toString():string {
+        return `[${this.cmp}] [#${this.code!=null ? this.code : "<null>"} ${this.message}`;
+    }
+
+    /**
+     * Called by children constructors, it help to implement
+     * extra action for every Exception thrown
+     *
+     * @method
+     */
+    protected _triggerNewHook(){
+        MonitoredError.NEW_HOOK.apply(null,[this]);
+    }
+
+    /**
+     *
+     * @param pIncludeExtra
+     */
+    toObject(pIncludeExtra=false):any {
+        return {
+            cmp: this.cmp,
+            code: this.code,
+            msg: this.message,
+            extra: pIncludeExtra ? this.extra : null
+        }
+    }
+}

package/src/error/RuntimeException.ts

@@ -0,0 +1,41 @@
+
+/*
+ *
+ *     Reversense platform / dxc-struct :  Reversense is an automated reverse engineering and analysis platform
+ *     focused on security, privacy, quality, accessibility and safety assessment of software, including mobile app and firmware.
+ *     Copyright (C) 2026  Reversense SAS
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Affero General Public License as published
+ *     by the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     GNU Affero General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Affero General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+import {MonitoredError} from "./MonitoredError.js";
+
+export class RuntimeException extends MonitoredError {
+
+    static WRITE_OOB = ()=>{
+        return new RuntimeException("Write Out-of-Bound",MonitoredError.ERR_CODE_BASE + 1) };
+
+    static READ_OOB = ()=>{
+        return new RuntimeException("Read Out-of-Bound",MonitoredError.ERR_CODE_BASE + 2) };
+
+    static UNKNOWN_FORMAT = (pToken:string)=>{
+        return new RuntimeException("Format is invalid. Following token is not recognized [token="+pToken+"]"
+            ,MonitoredError.ERR_CODE_BASE + 3) };
+
+
+    constructor( pMsg:string, pCode:number = null, pExtra:any = null) {
+        super('DXC-STRUCT', pMsg, pCode, pExtra);
+    }
+}