@cheatron/nthread 1.0.0

package/dist/nthread-heap.d.ts

@@ -0,0 +1,65 @@
+import * as Native from '@cheatron/native';
+import { NThread } from './nthread.js';
+import type { CapturedThread } from './thread/captured-thread.js';
+import type { ProxyThread } from './thread/proxy-thread.js';
+import type { GeneralPurposeRegs } from './globals.js';
+import type { AllocOptions } from './memory/alloc-options.js';
+/** Default initial heap block size (bytes). */
+export declare const DEFAULT_NTHREAD_HEAP_SIZE = 65536;
+/** Default maximum heap size — heap doubles up to this limit before falling back to super. */
+export declare const DEFAULT_NTHREAD_HEAP_MAX_SIZE: number;
+/**
+ * NThreadHeap extends {@link NThread} with a single growing heap per injection.
+ *
+ * On first allocation a {@link Heap} of `heapSize` bytes is created in the
+ * target process via `calloc`. When it fills up the heap is **doubled** (up to
+ * `maxSize`) — the old block is kept resident so its existing allocations can
+ * still be freed, but new allocations come from the freshly grown block.
+ *
+ * When even a `maxSize`-sized block cannot satisfy a request (or `maxSize` is
+ * already reached), `super.threadAlloc()` is called — the base {@link NThread}
+ * allocator, which uses `msvcrt!malloc` / `calloc` / `realloc`.
+ *
+ * ### Lifecycle
+ * - `proxy.close()` destroys the active heap **and** all previous blocks, then
+ *   restores the thread context via `super.threadClose()`.
+ *
+ * ### When to prefer NThreadHeap over NThread
+ * - Many small allocations: one `calloc` round-trip per block instead of per alloc
+ * - Readonly data: zone-typed allocs benefit from romem snapshot-skip writes
+ * - Predictable lifetime: all heap memory freed atomically on `proxy.close()`
+ *
+ * @example
+ * ```typescript
+ * const nt = new NThreadHeap(65536, 524288); // initial 64 KiB, max 512 KiB
+ * const [proxy] = await nt.inject(tid);
+ *
+ * const ptr = await proxy.alloc(64, { readonly: true, fill: 0 });
+ * await proxy.write(ptr, myBuffer);
+ *
+ * await proxy.close(); // destroys all heap blocks, restores thread
+ * ```
+ */
+export declare class NThreadHeap extends NThread {
+    /** Initial heap block size (bytes). */
+    readonly heapSize: number;
+    /** Maximum heap block size (bytes). Exceeded → super.threadAlloc(). */
+    readonly maxSize: number;
+    private state;
+    constructor(heapSize?: number, maxSize?: number, processId?: number, sleepAddress?: Native.NativePointer, pushretAddress?: Native.NativePointer, regKey?: GeneralPurposeRegs);
+    protected threadClose(proxy: ProxyThread, captured: CapturedThread, suicide?: number): Promise<void>;
+    protected threadAlloc(proxy: ProxyThread, size: number, opts?: AllocOptions): Promise<Native.NativePointer>;
+    protected threadFree(proxy: ProxyThread, ptr: Native.NativePointer): Promise<void>;
+    private getState;
+    /**
+     * Tries to allocate from the active heap. Grows the heap if full (up to
+     * `maxSize`). Returns `null` when the request must be served by super.
+     */
+    private allocFromHeap;
+    /** Silent wrapper around `Heap.alloc` / `Heap.allocReadonly`. Returns `null` on failure. */
+    private tryAlloc;
+    /** Computes readonly zone size for a new heap block. */
+    private calcRoSize;
+    private reallocInternal;
+}
+//# sourceMappingURL=nthread-heap.d.ts.map

package/dist/nthread-heap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nthread-heap.d.ts","sourceRoot":"","sources":["../src/nthread-heap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,+CAA+C;AAC/C,eAAO,MAAM,yBAAyB,QAAQ,CAAC;AAE/C,8FAA8F;AAC9F,eAAO,MAAM,6BAA6B,QAAgC,CAAC;AAc3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,WAAY,SAAQ,OAAO;IACtC,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,OAAO,CAAC,KAAK,CAAsC;gBAGjD,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,CAAC,aAAa,EACnC,cAAc,CAAC,EAAE,MAAM,CAAC,aAAa,EACrC,MAAM,CAAC,EAAE,kBAAkB;cAWJ,WAAW,CAClC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;cAYS,WAAW,CAClC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,YAAY,GAClB,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC;cAoBP,UAAU,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,MAAM,CAAC,aAAa,GACxB,OAAO,CAAC,IAAI,CAAC;IAiBhB,OAAO,CAAC,QAAQ;IAShB;;;OAGG;YACW,aAAa;IA4C3B,4FAA4F;IAC5F,OAAO,CAAC,QAAQ;IAQhB,wDAAwD;IACxD,OAAO,CAAC,UAAU;YAIJ,eAAe;CA0D9B"}

package/dist/nthread-heap.js

@@ -0,0 +1,193 @@
+import * as Native from '@cheatron/native';
+import { NThread } from './nthread.js';
+import { Heap } from './memory/heap.js';
+/** Default initial heap block size (bytes). */
+export const DEFAULT_NTHREAD_HEAP_SIZE = 65536;
+/** Default maximum heap size — heap doubles up to this limit before falling back to super. */
+export const DEFAULT_NTHREAD_HEAP_MAX_SIZE = DEFAULT_NTHREAD_HEAP_SIZE * 8; // 512 KiB
+/**
+ * NThreadHeap extends {@link NThread} with a single growing heap per injection.
+ *
+ * On first allocation a {@link Heap} of `heapSize` bytes is created in the
+ * target process via `calloc`. When it fills up the heap is **doubled** (up to
+ * `maxSize`) — the old block is kept resident so its existing allocations can
+ * still be freed, but new allocations come from the freshly grown block.
+ *
+ * When even a `maxSize`-sized block cannot satisfy a request (or `maxSize` is
+ * already reached), `super.threadAlloc()` is called — the base {@link NThread}
+ * allocator, which uses `msvcrt!malloc` / `calloc` / `realloc`.
+ *
+ * ### Lifecycle
+ * - `proxy.close()` destroys the active heap **and** all previous blocks, then
+ *   restores the thread context via `super.threadClose()`.
+ *
+ * ### When to prefer NThreadHeap over NThread
+ * - Many small allocations: one `calloc` round-trip per block instead of per alloc
+ * - Readonly data: zone-typed allocs benefit from romem snapshot-skip writes
+ * - Predictable lifetime: all heap memory freed atomically on `proxy.close()`
+ *
+ * @example
+ * ```typescript
+ * const nt = new NThreadHeap(65536, 524288); // initial 64 KiB, max 512 KiB
+ * const [proxy] = await nt.inject(tid);
+ *
+ * const ptr = await proxy.alloc(64, { readonly: true, fill: 0 });
+ * await proxy.write(ptr, myBuffer);
+ *
+ * await proxy.close(); // destroys all heap blocks, restores thread
+ * ```
+ */
+export class NThreadHeap extends NThread {
+    /** Initial heap block size (bytes). */
+    heapSize;
+    /** Maximum heap block size (bytes). Exceeded → super.threadAlloc(). */
+    maxSize;
+    state = new Map();
+    constructor(heapSize, maxSize, processId, sleepAddress, pushretAddress, regKey) {
+        super(processId, sleepAddress, pushretAddress, regKey);
+        this.heapSize = heapSize ?? DEFAULT_NTHREAD_HEAP_SIZE;
+        this.maxSize = maxSize ?? DEFAULT_NTHREAD_HEAP_MAX_SIZE;
+    }
+    // ---------------------------------------------------------------------------
+    // Overrides
+    // ---------------------------------------------------------------------------
+    async threadClose(proxy, captured, suicide) {
+        const s = this.state.get(proxy);
+        if (s) {
+            const allHeaps = s.heap ? [...s.prevHeaps, s.heap] : s.prevHeaps;
+            for (const heap of allHeaps) {
+                await heap.destroy(proxy);
+            }
+            this.state.delete(proxy);
+        }
+        await super.threadClose(proxy, captured, suicide);
+    }
+    async threadAlloc(proxy, size, opts) {
+        if (opts?.address) {
+            return this.reallocInternal(proxy, opts.address, size, opts);
+        }
+        const ro = opts?.readonly ?? false;
+        const ptr = await this.allocFromHeap(proxy, size, ro);
+        // ptr === null → heap can't serve it; fall back to super (NThread/malloc)
+        if (ptr === null) {
+            return super.threadAlloc(proxy, size, opts);
+        }
+        if (opts?.fill !== undefined) {
+            await proxy.write(ptr, Buffer.alloc(size, opts.fill & 0xff));
+        }
+        return ptr;
+    }
+    async threadFree(proxy, ptr) {
+        const s = this.state.get(proxy);
+        const entry = s?.allocations.get(ptr.address);
+        s?.allocations.delete(ptr.address);
+        // Unknown or super-backed → delegate to NThread base (crt.free)
+        if (!entry || entry === 'super') {
+            return super.threadFree(proxy, ptr);
+        }
+        entry.heap.free(entry.alloc);
+    }
+    // ---------------------------------------------------------------------------
+    // Internal helpers
+    // ---------------------------------------------------------------------------
+    getState(proxy) {
+        let s = this.state.get(proxy);
+        if (!s) {
+            s = { heap: null, prevHeaps: [], allocations: new Map() };
+            this.state.set(proxy, s);
+        }
+        return s;
+    }
+    /**
+     * Tries to allocate from the active heap. Grows the heap if full (up to
+     * `maxSize`). Returns `null` when the request must be served by super.
+     */
+    async allocFromHeap(proxy, size, ro) {
+        const s = this.getState(proxy);
+        if (s.heap) {
+            // Try current active heap
+            const result = this.tryAlloc(s.heap, size, ro);
+            if (result) {
+                s.allocations.set(result.remote.address, {
+                    alloc: result,
+                    heap: s.heap,
+                });
+                return result.remote;
+            }
+            // Full — can we grow?
+            if (s.heap.totalSize >= this.maxSize)
+                return null; // at ceiling
+            const newSize = Math.min(s.heap.totalSize * 2, this.maxSize);
+            if (size > newSize)
+                return null; // request too big for any heap block
+            s.prevHeaps.push(s.heap);
+            s.heap = await Heap.create(proxy, newSize, this.calcRoSize(newSize, ro));
+        }
+        else {
+            // First alloc — create the initial heap
+            if (size > this.maxSize)
+                return null;
+            const initSize = Math.max(Math.min(this.heapSize, this.maxSize), size);
+            s.heap = await Heap.create(proxy, initSize, this.calcRoSize(initSize, ro));
+        }
+        const result = this.tryAlloc(s.heap, size, ro);
+        if (!result)
+            return null; // shouldn't happen
+        s.allocations.set(result.remote.address, { alloc: result, heap: s.heap });
+        return result.remote;
+    }
+    /** Silent wrapper around `Heap.alloc` / `Heap.allocReadonly`. Returns `null` on failure. */
+    tryAlloc(heap, size, ro) {
+        try {
+            return ro ? heap.allocReadonly(size) : heap.alloc(size);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Computes readonly zone size for a new heap block. */
+    calcRoSize(totalSize, ro) {
+        return ro ? Math.floor((totalSize * 3) / 4) : Math.floor(totalSize / 4);
+    }
+    async reallocInternal(proxy, address, newSize, opts) {
+        const s = this.getState(proxy);
+        const entry = s.allocations.get(address.address);
+        if (!entry || entry === 'super') {
+            // Delegate entirely to NThread base (CRT realloc path)
+            if (entry === 'super')
+                s.allocations.delete(address.address);
+            const newPtr = await super.threadAlloc(proxy, newSize, opts);
+            s.allocations.set(newPtr.address, 'super');
+            return newPtr;
+        }
+        // Detect old zone: address < base + roSize → was readonly
+        const oldRo = entry.alloc.remote.address <
+            entry.heap.base.address + BigInt(entry.heap.roSize);
+        // Preserve old zone unless caller explicitly requests a change
+        const ro = opts?.readonly ?? oldRo;
+        // Allocate new block (heap if possible, otherwise super/CRT — but NOT realloc on old address)
+        const newRaw = await this.allocFromHeap(proxy, newSize, ro);
+        const newPtr = newRaw ??
+            (await super.threadAlloc(proxy, newSize, {
+                ...opts,
+                address: undefined,
+            }));
+        if (!newRaw)
+            s.allocations.set(newPtr.address, 'super');
+        // Copy old content
+        const copyLen = Math.min(entry.alloc.size, newSize);
+        if (copyLen > 0) {
+            const oldData = await proxy.read(address, copyLen);
+            await proxy.write(newPtr, oldData);
+        }
+        // Fill newly added bytes when growing
+        if (newSize > copyLen && opts?.fill !== undefined) {
+            const fillPtr = new Native.NativePointer(newPtr.address + BigInt(copyLen));
+            await proxy.write(fillPtr, Buffer.alloc(newSize - copyLen, opts.fill & 0xff));
+        }
+        entry.heap.free(entry.alloc);
+        s.allocations.delete(address.address);
+        return newPtr;
+    }
+}
+//# sourceMappingURL=nthread-heap.js.map

package/dist/nthread-heap.js.map

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

package/dist/nthread.d.ts

@@ -0,0 +1,146 @@
+import * as Native from '@cheatron/native';
+import { type GeneralPurposeRegs } from './globals.js';
+import { ProxyThread } from './thread/proxy-thread.js';
+import { CapturedThread } from './thread/captured-thread.js';
+import type { AllocOptions } from './memory/alloc-options.js';
+export { STACK_ADD } from './thread/captured-thread.js';
+/**
+ * Register-compatible argument type.
+ * All values are ultimately converted to bigint for register assignment (RCX, RDX, R8, R9).
+ * Accepts NativePointer (→ .address) and number (→ BigInt()) for convenience.
+ */
+export type Arg = bigint | number | Native.NativePointer;
+/**
+ * NThread: Orchestrates non-invasive thread hijacking.
+ *
+ * It works by suspending a target thread, redirecting its Rip to a 'pushreg/ret' gadget,
+ * setting a 'sleep' address as the target, and waiting for the thread to 'land'
+ * at said sleep address. Once landed, the thread is effectively seized without
+ * stopping the underlying process or requiring complex debugging APIs.
+ *
+ * The actual thread state (context cache, suspend tracking, proxy) is managed by
+ * the contained CapturedThread instance, created during inject().
+ */
+export declare class NThread {
+    /** Optional process ID for diagnostics and logging */
+    processId?: number;
+    /** Address of an infinite loop gadget ('jmp .') used to hold the thread */
+    sleepAddress: Native.NativePointer;
+    /** Address of a pivot gadget ('push reg; ret') used to redirect execution */
+    pushretAddress: Native.NativePointer;
+    /** The register key (e.g., 'Rbx') used for the pushret pivot */
+    regKey: GeneralPurposeRegs;
+    /**
+     * Creates an NThread instance and prepares redirect gadgets.
+     * @param processId Optional process ID for diagnostics and logging.
+     * @param sleepAddress Optional explicit sleep gadget.
+     * @param pushretAddress Optional explicit pushret gadget.
+     * @param regKey Optional register preference for the pushret gadget.
+     */
+    constructor(processId?: number, sleepAddress?: Native.NativePointer, pushretAddress?: Native.NativePointer, regKey?: GeneralPurposeRegs);
+    /**
+     * Executes the hijacking flow:
+     * 1. Create a CapturedThread from the given thread parameter.
+     * 2. Suspend the thread.
+     * 3. Capture and save current register state.
+     * 4. Redirect Rip to PushRet gadget.
+     * 5. Point the chosen register (RegKey) to the Sleep gadget.
+     * 6. Adjust stack (Rsp) to a safe scratch area.
+     * 7. Resume and wait for the thread to 'trap' itself in the loop.
+     *
+     * @param thread Thread object or Thread ID to hijack.
+     */
+    inject(thread: Native.Thread | number): Promise<[ProxyThread, CapturedThread]>;
+    /** Writes data to the target process; dispatches NativePointer vs Buffer. */
+    private threadWrite;
+    /**
+     * Hook: called to release the proxy and captured thread.
+     * Subclasses can override to perform cleanup (e.g. destroy a heap pool)
+     * before closing. Default: terminate (if suicide) then close the handle.
+     */
+    protected threadClose(_proxy: ProxyThread, captured: CapturedThread, suicide?: number): Promise<void>;
+    /**
+     * Hook: allocates memory in the target process.
+     * Default: `malloc` / `calloc` / `malloc+memset` depending on `opts.fill`;
+     * delegates to `msvcrt!realloc` when `opts.address` is provided.
+     * Subclasses can override to use a pre-allocated heap instead.
+     */
+    protected threadAlloc(proxy: ProxyThread, size: number, opts?: AllocOptions): Promise<Native.NativePointer>;
+    /**
+     * Hook: frees a pointer in the target process.
+     * Default: `msvcrt!free`.
+     * Subclasses can override to return the block to a managed heap instead.
+     */
+    protected threadFree(proxy: ProxyThread, ptr: Native.NativePointer): Promise<void>;
+    /**
+     * Allocates memory for a string and writes it into the remote process via the captured thread.
+     * Null-terminates automatically.
+     *
+     * @param proxy The proxy for the captured thread.
+     * @param str String to encode and write.
+     * @param encoding Buffer encoding — defaults to `'utf16le'` (Windows wide string).
+     * @param opts Optional alloc options forwarded to `proxy.alloc()`.
+     */
+    allocString(proxy: ProxyThread, str: string, encoding?: BufferEncoding, opts?: AllocOptions): Promise<Native.NativePointer>;
+    /**
+     * Executes a function call on a captured thread using the Windows x64 calling convention.
+     * The thread must be parked at the sleep address (after inject()).
+     *
+     * Supports up to 4 parameters mapped to RCX, RDX, R8, R9.
+     * Returns the value from RAX after the function completes.
+     *
+     * @param thread The captured thread to execute on.
+     * @param target Address of the function to call.
+     * @param args Up to 4 arguments (RCX, RDX, R8, R9).
+     * @param timeoutMs Timeout in ms for waiting on the function return (default: 5000).
+     * @returns RAX value as NativePointer.
+     */
+    threadCall(thread: CapturedThread, target: Native.NativePointer | bigint, args?: Arg[], timeoutMs?: number): Promise<Native.NativePointer>;
+    /**
+     * Writes arbitrary data to the target process memory using hijacked memset calls.
+     * Decomposes the source buffer into runs of equal bytes and issues one
+     * `msvcrt!memset(dest + offset, value, runLength)` call per run.
+     *
+     * If the write range overlaps a registered read-only memory region, the
+     * overlapping portion is routed through writeMemorySafeBuffer (skips unchanged
+     * bytes) and the non-overlapping parts are written normally via recursive calls.
+     *
+     * @param dest Target address to write to.
+     * @param source The data to write.
+     */
+    writeMemory(proxy: ProxyThread, dest: Native.NativePointer | bigint, source: Buffer | Uint8Array): Promise<number>;
+    /**
+     * Writes data from a NativePointer source to the target process memory
+     * using hijacked memset calls. Reads the source pointer byte-by-byte into
+     * a local buffer first, then delegates to the standard decomposed memset.
+     *
+     * Does NOT check read-only memory regions — this is intended for writing
+     * data we don't already know the contents of.
+     *
+     * @param thread The captured thread to execute on.
+     * @param dest Target address to write to.
+     * @param source Source pointer to read from (in our process).
+     * @param size Number of bytes to write.
+     */
+    writeMemoryWithPointer(proxy: ProxyThread, dest: Native.NativePointer | bigint, source: Native.NativePointer, size: number): Promise<number>;
+    /**
+     * Safe write dispatcher: routes to the optimized variant based on `lastDest` type.
+     *
+     * @param dest Target address to write to.
+     * @param source The data to write.
+     * @param lastDest Either a snapshot Buffer of the previous state, or a single byte value
+     *                 representing a uniform fill (e.g. 0 means the region is all zeroes).
+     */
+    writeMemorySafe(proxy: ProxyThread, dest: Native.NativePointer, source: Buffer, lastDest: Buffer | number): Promise<number>;
+    /**
+     * Safe write against a uniform fill value.
+     * Skips bytes that already equal `fillByte`.
+     */
+    private writeMemorySafeUniform;
+    /**
+     * Safe write against a snapshot Buffer.
+     * Skips bytes that match the corresponding byte in `last`.
+     */
+    private writeMemorySafeBuffer;
+}
+//# sourceMappingURL=nthread.d.ts.map

package/dist/nthread.d.ts.map

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