@cheatron/native 1.1.0 → 1.2.1

package/dist/native-fn.js

@@ -0,0 +1,214 @@
+import { ffi, MsvcrtImpl as msvcrt, MemoryProtection, MemoryState, MemoryFreeType, } from '@cheatron/native-bindings';
+import { KeystoneX86 } from '@cheatron/keystone';
+import { log } from './logger';
+const nfLog = log.child('NativeFn');
+/** Registry for automatic cleanup of memory pages */
+const registry = new FinalizationRegistry((page) => {
+    if (page) {
+        // Lazy require to avoid circular dependencies
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { currentProcess } = require('./process');
+        // Free the allocated memory using currentProcess.free
+        try {
+            const success = currentProcess.memory.free(page, 0, MemoryFreeType.RELEASE);
+            if (success) {
+                nfLog.info('Garbage collection: cleaned up executable memory page');
+            }
+            else {
+                nfLog.error('Garbage collection: currentProcess.free returned false during cleanup');
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            nfLog.error(`Garbage collection: cleanup failed: ${message}`);
+        }
+    }
+});
+export const ALIGN = 16;
+/**
+ * Rounds a number up to the nearest multiple of 16.
+ */
+export function addressAlign16(n) {
+    return (n + ALIGN - 1) & ~(ALIGN - 1);
+}
+export const codeAlign16 = addressAlign16;
+export const stackAlign16 = addressAlign16;
+/**
+ * Dynamically creates callable native functions from assembly or bytecode.
+ *
+ * Functions are written into a single VirtualAlloc'd executable page and
+ * exposed as callable methods on the instance via koffi.
+ */
+export class NativeFunctionCreator {
+    page;
+    pageAddr;
+    offset = 0;
+    capacity;
+    ks;
+    functions = new Map();
+    constructor(capacity = 8192) {
+        this.capacity = capacity;
+        this.ks = new KeystoneX86();
+        // Lazy require to avoid circular dependencies
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { currentProcess } = require('./process');
+        // Allocate executable memory using currentProcess.alloc
+        this.page = currentProcess.memory.alloc(BigInt(capacity), null, MemoryState.COMMIT | MemoryState.RESERVE, MemoryProtection.EXECUTE_READWRITE);
+        if (!this.page) {
+            throw new Error('VirtualAlloc failed: could not allocate executable memory');
+        }
+        // Register for automatic cleanup. Use 'this' as the unregister token.
+        registry.register(this, this.page, this);
+        this.pageAddr = ffi.address(this.page);
+        nfLog.info(`Allocated ${capacity} bytes of executable memory at 0x${this.pageAddr.toString(16).toUpperCase()}`);
+    }
+    /**
+     * Add a native function from assembly source code.
+     * @param def Function definition { name: [returnType, [paramTypes...]] }
+     * @param asmSource x86-64 assembly instructions
+     * @returns Address of the function
+     */
+    add(def, asmSource) {
+        const name = Object.keys(def)[0];
+        if (!name) {
+            throw new Error('Invalid function definition: name is missing');
+        }
+        const sig = def[name];
+        if (!sig) {
+            throw new Error(`Invalid function definition: signature is missing for '${name}'`);
+        }
+        const funcAddr = this.pageAddr + BigInt(this.offset);
+        const bytes = this.ks.asm(asmSource, funcAddr);
+        return this._writeAndBind(name, sig, bytes);
+    }
+    /**
+     * Add a native function from raw bytecode.
+     * @param def Function definition { name: [returnType, [paramTypes...]] }
+     * @param bytes Raw machine code bytes
+     * @returns Address of the function
+     */
+    addBytes(def, bytes) {
+        const name = Object.keys(def)[0];
+        if (!name) {
+            throw new Error('Invalid function definition: name is missing');
+        }
+        const sig = def[name];
+        if (!sig) {
+            throw new Error(`Invalid function definition: signature is missing for '${name}'`);
+        }
+        return this._writeAndBind(name, sig, bytes);
+    }
+    /**
+     * Get the address of a registered function by name.
+     */
+    getAddress(name) {
+        return this.functions.get(name)?.address;
+    }
+    /**
+     * Get the callable function by name.
+     */
+    // eslint-disable-next-line no-unused-vars
+    getFunction(name) {
+        return this.functions.get(name)?.callable;
+    }
+    /**
+     * Get info about all registered functions.
+     */
+    list() {
+        return [...this.functions.values()];
+    }
+    /**
+     * Get remaining capacity in bytes.
+     */
+    get remaining() {
+        return this.capacity - this.offset;
+    }
+    /**
+     * Free the executable memory page.
+     */
+    destroy() {
+        if (this.page) {
+            // Unregister from finalizer as we are doing manual cleanup
+            registry.unregister(this);
+            // Lazy require to avoid circular dependencies
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { currentProcess } = require('./process');
+            // Perform the actual free using currentProcess.free
+            const success = currentProcess.memory.free(this.page, 0, MemoryFreeType.RELEASE);
+            if (success) {
+                nfLog.info('NativeFunctionCreator destroyed');
+            }
+            else {
+                nfLog.warn('currentProcess.free failed during NativeFunctionCreator destruction');
+            }
+            this.page = null;
+            this.functions.clear();
+        }
+    }
+    // ── Internal ──────────────────────────────────────────────
+    _writeAndBind(name, sig, bytes) {
+        if (this.functions.has(name)) {
+            throw new Error(`Function '${name}' already registered`);
+        }
+        const alignedSize = codeAlign16(bytes.length);
+        if (this.offset + alignedSize > this.capacity) {
+            throw new Error(`Not enough space: need ${alignedSize} bytes, ${this.remaining} remaining`);
+        }
+        const funcOffset = this.offset;
+        const funcAddr = this.pageAddr + BigInt(funcOffset);
+        // Write bytecode into executable page
+        const buf = Buffer.from(bytes);
+        msvcrt.memcpy(funcAddr, buf, BigInt(bytes.length));
+        nfLog.debug(`Written '${name}' (${bytes.length} bytes) at 0x${funcAddr.toString(16).toUpperCase()} [offset: ${funcOffset}]`);
+        // Advance offset (aligned)
+        this.offset += alignedSize;
+        // Create koffi prototype
+        const [retType, paramTypes] = sig;
+        const protoName = `__nf_${name}_${Date.now()}`;
+        const paramStr = paramTypes.map((t, i) => `${t} p${i}`).join(', ');
+        const protoStr = `${retType} ${protoName}(${paramStr})`;
+        const proto = ffi.proto(protoStr);
+        // Decode function pointer from base page + offset
+        // koffi.decode(ptr, type, offset) offsets from the base external pointer
+        const callable = ffi.decode(this.page, proto, funcOffset);
+        // Bind as method on this instance
+        Object.defineProperty(this, name, {
+            enumerable: true,
+            configurable: true,
+            value: callable,
+        });
+        // Track
+        const entry = {
+            name,
+            address: funcAddr,
+            size: bytes.length,
+            sig,
+            callable,
+        };
+        this.functions.set(name, entry);
+        return funcAddr;
+    }
+}
+/**
+ * Global shared NativeFunctionCreator instance.
+ * Lazy initialized to prevent circular dependency issues during module load.
+ */
+let _nativeFn;
+export const nativeFn = new Proxy({}, {
+    get(_target, prop) {
+        if (!_nativeFn) {
+            _nativeFn = new NativeFunctionCreator();
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const val = _nativeFn[prop];
+        // Don't bind non-functions or constructor
+        if (typeof val === 'function' && prop !== 'constructor') {
+            return val.bind(_nativeFn);
+        }
+        return val;
+    },
+    getPrototypeOf() {
+        return NativeFunctionCreator.prototype;
+    },
+});
+//# sourceMappingURL=native-fn.js.map

package/dist/native-fn.js.map

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

package/dist/pattern.d.ts

@@ -0,0 +1,36 @@
+import { MemoryProtection } from '@cheatron/win32-ext';
+/**
+ * Default protection mask: all readable memory regions.
+ */
+export declare const DEFAULT_PROTECT: number;
+/**
+ * Pure data representation of a memory signature.
+ * Defines the bytes, mask, limits, and memory protection preferences.
+ */
+export declare class Pattern {
+    bytes: Buffer;
+    mask: string;
+    private _limit;
+    protect: number;
+    constructor(signature: string);
+    get length(): number;
+    get maxResults(): number;
+    get hasLimit(): boolean;
+    /**
+     * Sets a specific scan limit.
+     */
+    limit(n: number): this;
+    /**
+     * Removes any limits (scan the whole memory for matches).
+     */
+    noLimit(): this;
+    /**
+     * Restricts scan to segments matching the given protection mask.
+     */
+    addProtect(flag: number | MemoryProtection): this;
+    /**
+     * Automatically applies typical readable/executable filters.
+     */
+    defaultProtect(): this;
+}
+//# sourceMappingURL=pattern.d.ts.map

package/dist/pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern.d.ts","sourceRoot":"","sources":["../src/pattern.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAKvD;;GAEG;AACH,eAAO,MAAM,eAAe,QAIQ,CAAC;AAErC;;;GAGG;AACH,qBAAa,OAAO;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,MAAM,CAAa;IACpB,OAAO,EAAE,MAAM,CAAK;gBAEf,SAAS,EAAE,MAAM;IAsB7B,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;OAEG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKtB;;OAEG;IACH,OAAO,IAAI,IAAI;IAKf;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAKjD;;OAEG;IACH,cAAc,IAAI,IAAI;CAIvB"}

package/dist/pattern.js

@@ -0,0 +1,79 @@
+import { MemoryProtection } from '@cheatron/win32-ext';
+import { log } from './logger';
+const scanLog = log.child('Scanner');
+/**
+ * Default protection mask: all readable memory regions.
+ */
+export const DEFAULT_PROTECT = MemoryProtection.READONLY |
+    MemoryProtection.READWRITE |
+    MemoryProtection.EXECUTE_READ |
+    MemoryProtection.EXECUTE_READWRITE;
+/**
+ * Pure data representation of a memory signature.
+ * Defines the bytes, mask, limits, and memory protection preferences.
+ */
+export class Pattern {
+    bytes;
+    mask;
+    _limit = 1; // Default to 1 result
+    protect = 0;
+    constructor(signature) {
+        const parts = signature.split(/\s+/).filter(Boolean);
+        const bytes = [];
+        let mask = '';
+        for (const part of parts) {
+            if (part === '??' || part === '?') {
+                bytes.push(0);
+                mask += '?';
+            }
+            else {
+                const byte = parseInt(part, 16);
+                if (isNaN(byte))
+                    throw new Error(`Invalid byte in signature: ${part}`);
+                bytes.push(byte);
+                mask += 'x';
+            }
+        }
+        this.bytes = Buffer.from(bytes);
+        this.mask = mask;
+        scanLog.debug(`Parsed pattern: ${signature} -> ${mask}`);
+    }
+    get length() {
+        return this.bytes.length;
+    }
+    get maxResults() {
+        return this._limit;
+    }
+    get hasLimit() {
+        return this._limit > 0;
+    }
+    /**
+     * Sets a specific scan limit.
+     */
+    limit(n) {
+        this._limit = n;
+        return this;
+    }
+    /**
+     * Removes any limits (scan the whole memory for matches).
+     */
+    noLimit() {
+        this._limit = 0;
+        return this;
+    }
+    /**
+     * Restricts scan to segments matching the given protection mask.
+     */
+    addProtect(flag) {
+        this.protect |= flag;
+        return this;
+    }
+    /**
+     * Automatically applies typical readable/executable filters.
+     */
+    defaultProtect() {
+        this.protect = DEFAULT_PROTECT;
+        return this;
+    }
+}
+//# sourceMappingURL=pattern.js.map

package/dist/pattern.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern.js","sourceRoot":"","sources":["../src/pattern.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,gBAAgB,CAAC,QAAQ;IACzB,gBAAgB,CAAC,SAAS;IAC1B,gBAAgB,CAAC,YAAY;IAC7B,gBAAgB,CAAC,iBAAiB,CAAC;AAErC;;;GAGG;AACH,MAAM,OAAO,OAAO;IACX,KAAK,CAAS;IACd,IAAI,CAAS;IACZ,MAAM,GAAW,CAAC,CAAC,CAAC,sBAAsB;IAC3C,OAAO,GAAW,CAAC,CAAC;IAE3B,YAAY,SAAiB;QAC3B,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,IAAI,GAAG,EAAE,CAAC;QAEd,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;gBAClC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACd,IAAI,IAAI,GAAG,CAAC;YACd,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAChC,IAAI,KAAK,CAAC,IAAI,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,EAAE,CAAC,CAAC;gBACvE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACjB,IAAI,IAAI,GAAG,CAAC;YACd,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,OAAO,CAAC,KAAK,CAAC,mBAAmB,SAAS,OAAO,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,CAAS;QACb,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,IAA+B;QACxC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,IAAI,CAAC,OAAO,GAAG,eAAe,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/process.d.ts

@@ -0,0 +1,104 @@
+import { Thread } from './thread';
+import { ThreadCreationFlags, MemoryFreeType, type SecurityAttributes, type MemoryBasicInformation, type HANDLE, type LPVOID, type SIZE_T } from '@cheatron/native-bindings';
+import { Handle } from './handle';
+import { Pattern } from './pattern';
+import { ScanResult } from './scan-result';
+/**
+ * Represents a process handle
+ */
+export declare class Process extends Handle {
+    protected _pid: number;
+    readonly memory: ProcessMemory;
+    constructor(handle: HANDLE, pid?: number, autoClose?: boolean);
+    static open(pid: number, access?: number): Process;
+    createThread(startAddress: LPVOID, parameter?: LPVOID | null, stackSize?: SIZE_T, flags?: ThreadCreationFlags | number, attributes?: SecurityAttributes | LPVOID | null): Thread;
+    /**
+     * Finds pattern matches in a specific memory range.
+     * Configure limit on the Pattern: `.limit(1)` for first match only.
+     */
+    private findPatternInRangeGenerator;
+    findPatternInRange(signature: string | Pattern, start: bigint, size: number, module?: import('./module').Module): ScanResult;
+    /**
+     * Finds pattern matches in all committed readable memory of the process.
+     * Configure limit and protect filter on the Pattern object.
+     */
+    private findPatternGenerator;
+    findPattern(signature: string | Pattern): ScanResult;
+    /**
+     * Finds pattern matches across specified modules (default: all static modules).
+     * Each entry in the result is tagged with its source module.
+     * Configure limit and protect filter on the Pattern object.
+     */
+    private findPatternFromModulesGenerator;
+    findPatternFromModules(signature: string | Pattern, moduleNames?: string[]): ScanResult;
+    static current(): CurrentProcess;
+    get pid(): number;
+}
+/**
+ * Represents the current process (singleton)
+ */
+export declare class CurrentProcess extends Process {
+    readonly memory: CurrentProcessMemory;
+    constructor();
+    createThread(startAddress: LPVOID, parameter?: LPVOID | null, stackSize?: SIZE_T, flags?: ThreadCreationFlags | number, attributes?: SecurityAttributes | LPVOID | null): Thread;
+    close(): void;
+}
+export declare const currentProcess: CurrentProcess;
+/**
+ * Manages memory operations for a given process handle.
+ */
+export declare class ProcessMemory {
+    readonly process: Process;
+    constructor(process: Process);
+    read(address: LPVOID, size: number): Buffer;
+    readMemory: (address: LPVOID, size: number) => Buffer;
+    write(address: LPVOID, buffer: Buffer): void;
+    writeMemory: (address: LPVOID, buffer: Buffer) => void;
+    readInt8(address: LPVOID): number;
+    writeInt8(address: LPVOID, value: number): void;
+    readUInt8(address: LPVOID): number;
+    writeUInt8(address: LPVOID, value: number): void;
+    readInt16(address: LPVOID): number;
+    writeInt16(address: LPVOID, value: number): void;
+    readUInt16(address: LPVOID): number;
+    writeUInt16(address: LPVOID, value: number): void;
+    readInt32(address: LPVOID): number;
+    writeInt32(address: LPVOID, value: number): void;
+    readUInt32(address: LPVOID): number;
+    writeUInt32(address: LPVOID, value: number): void;
+    readInt64(address: LPVOID): bigint;
+    writeInt64(address: LPVOID, value: bigint): void;
+    readUInt64(address: LPVOID): bigint;
+    writeUInt64(address: LPVOID, value: bigint): void;
+    readFloat(address: LPVOID): number;
+    writeFloat(address: LPVOID, value: number): void;
+    readDouble(address: LPVOID): number;
+    writeDouble(address: LPVOID, value: number): void;
+    readString(address: LPVOID, length: number, encoding?: BufferEncoding): string;
+    writeString(address: LPVOID, value: string, encoding?: BufferEncoding): void;
+    query(address: LPVOID): MemoryBasicInformation;
+    virtualQuery: (address: LPVOID) => MemoryBasicInformation;
+    /**
+     * Allocates memory in the process.
+     */
+    alloc(size: SIZE_T, address?: LPVOID | null, allocationType?: number, protection?: number): LPVOID;
+    /**
+     * Frees memory in the process.
+     */
+    free(address: LPVOID, size?: SIZE_T, freeType?: MemoryFreeType | number): boolean;
+    /**
+     * Changes the memory protection of a region of memory.
+     */
+    protect(address: LPVOID, size: SIZE_T, newProtect: number): number | null;
+}
+/**
+ * Optimizes memory operations natively for the current running process.
+ */
+export declare class CurrentProcessMemory extends ProcessMemory {
+    alloc(size: SIZE_T, address?: LPVOID | null, allocationType?: number, protection?: number): LPVOID;
+    free(address: LPVOID, size?: SIZE_T, freeType?: MemoryFreeType | number): boolean;
+    protect(address: LPVOID, size: SIZE_T | number, newProtect: number): number | null;
+    query(address: LPVOID): MemoryBasicInformation;
+    virtualQuery: (address: LPVOID) => MemoryBasicInformation;
+}
+//# sourceMappingURL=process.d.ts.map

package/dist/process.d.ts.map

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