@cheatron/nthread 1.0.0

package/dist/thread/captured-thread.js

@@ -0,0 +1,167 @@
+import * as Native from '@cheatron/native';
+export const STACK_ADD = -8192n;
+/**
+ * CapturedThread: A specialized Thread wrapper that manages the low-level state
+ * of a captured thread, including context caching, suspend/resume tracking,
+ * and register manipulation.
+ *
+ * It extends Native.Thread. A ProxyThread holds the reference back to this instance.
+ */
+export class CapturedThread extends Native.Thread {
+    /** Count of active suspensions to ensure balanced resume calls on close */
+    suspendCount = 0;
+    /** The register context captured immediately before hijacking */
+    savedContext;
+    /** The current live or modified context of the thread */
+    latestContext;
+    /** Pre-computed RSP value used for call() — set once during inject() */
+    callRsp = 0n;
+    /** Address of an infinite loop gadget ('jmp .') used to hold the thread */
+    sleepAddress;
+    /** The register key (e.g., 'Rbx') used for the pushret pivot */
+    regKey;
+    /**
+     * Creates a CapturedThread instance.
+     * @param thread Thread object or Thread ID to attach to.
+     * @param regKey The register key used for the pushret pivot.
+     * @param sleepAddress The sleep gadget address for parking the thread.
+     * @param processId Optional process ID for diagnostics and logging.
+     */
+    constructor(thread, regKey, sleepAddress, processId) {
+        let threadObject;
+        if (thread instanceof Native.Thread) {
+            threadObject = thread;
+        }
+        else {
+            threadObject = Native.Thread.open(thread, processId);
+        }
+        const rawHandle = threadObject.rawHandle;
+        // Unregister original so CapturedThread owns the lifecycle via super()
+        Native.handleRegistry.unregister(threadObject);
+        super(rawHandle, threadObject.tid, true);
+        this.regKey = regKey;
+        this.sleepAddress = sleepAddress;
+    }
+    /** Calculates a new stack pointer offset from the current RSP */
+    calcStackBegin(baseRsp = BigInt(this.getContext().Rsp)) {
+        return Native.stackAlign16(baseRsp + STACK_ADD);
+    }
+    /** Gets the value of the pivot register */
+    getTargetReg() {
+        return this.getContext()[this.regKey];
+    }
+    /** Sets the value of the pivot register */
+    setTargetReg(reg) {
+        const ctx = this.getContext();
+        ctx[this.regKey] = reg;
+        this.setContext(ctx);
+    }
+    /** Helper to get RSP */
+    getRSP() {
+        return this.getContext().Rsp;
+    }
+    /** Helper to set RSP */
+    setRSP(rsp) {
+        const ctx = this.getContext();
+        ctx.Rsp = rsp;
+        this.setContext(ctx);
+    }
+    /** Helper to get RIP */
+    getRIP() {
+        return this.getContext().Rip;
+    }
+    /** Helper to set RIP */
+    setRIP(rip) {
+        const ctx = this.getContext();
+        ctx.Rip = rip;
+        this.setContext(ctx);
+    }
+    /** Returns the last fetched/modified context cache */
+    getContext() {
+        if (!this.latestContext) {
+            this.fetchContext();
+        }
+        return this.latestContext;
+    }
+    /** Updates the context cache (does not apply to hardware yet) */
+    setContext(ctx) {
+        this.latestContext = ctx;
+    }
+    /** Explicitly fetches context from the hardware into the cache */
+    fetchContext() {
+        this.latestContext = super.getContext();
+    }
+    /** Explicitly applies the cached context to the hardware */
+    applyContext() {
+        super.setContext(this.latestContext);
+    }
+    /** Suspends the thread and increments internal counter */
+    suspend() {
+        const result = super.suspend();
+        if (result) {
+            this.suspendCount++;
+        }
+        return result;
+    }
+    /** Resumes the thread and decrements internal counter */
+    resume() {
+        const result = super.resume();
+        if (result) {
+            this.suspendCount--;
+        }
+        return result;
+    }
+    /** Restores the saved context and resumes the thread (without closing the handle) */
+    release() {
+        this.suspend();
+        this.setContext(this.savedContext);
+        this.applyContext();
+        this.resume();
+    }
+    /** Closes the handle and ensures the thread is resumed if it was suspended by us */
+    close() {
+        try {
+            this.release();
+        }
+        catch {
+            // Thread may already be dead (e.g. ExitThread was called) — ignore
+        }
+        for (let i = 0; i < this.suspendCount; i++) {
+            try {
+                super.resume();
+            }
+            catch {
+                break;
+            }
+        }
+        this.suspendCount = 0;
+        super.close();
+    }
+    /**
+     * Custom wait that polls the thread's RIP to see if it landed at the sleepAddress.
+     * If the thread dies or crashes during wait, it returns FAILED.
+     */
+    async wait(timeoutMs = Native.INFINITE) {
+        let count = 0;
+        while (count < timeoutMs) {
+            try {
+                this.fetchContext();
+                const rip = this.getContext().Rip;
+                if (BigInt(rip) === this.sleepAddress.valueOf()) {
+                    return Native.WaitReturn.OBJECT_0;
+                }
+            }
+            catch (_) {
+                const res = await super.wait(0);
+                if (res === Native.WaitReturn.OBJECT_0) {
+                    return Native.WaitReturn.FAILED;
+                }
+                return res;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 1));
+            count++;
+        }
+        return Native.WaitReturn.TIMEOUT;
+    }
+}
+//# sourceMappingURL=captured-thread.js.map

package/dist/thread/captured-thread.js.map

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

package/dist/thread/proxy-thread.d.ts

@@ -0,0 +1,92 @@
+import * as Native from '@cheatron/native';
+import type { Arg } from '../nthread.js';
+import type { AllocOptions } from '../memory/alloc-options.js';
+/**
+ * Type signatures for proxy operations.
+ * Each receives the ProxyThread instance as the first argument for context.
+ */
+export type ReadMemoryFn = (proxy: ProxyThread, address: Native.NativePointer, size: number) => Promise<Buffer>;
+export type WriteMemoryFn = (proxy: ProxyThread, address: Native.NativePointer, data: Buffer | Native.NativePointer, size?: number) => Promise<number>;
+export type CallFn = (proxy: ProxyThread, address: Native.NativePointer, ...args: Arg[]) => Promise<Native.NativePointer>;
+export type CloseFn = (proxy: ProxyThread, suicide?: number) => Promise<void>;
+export type AllocFn = (proxy: ProxyThread, size: number, opts?: AllocOptions) => Promise<Native.NativePointer>;
+export type FreeFn = (proxy: ProxyThread, ptr: Native.NativePointer) => Promise<void>;
+/** Signature for a bound function on ProxyThread (e.g. proxy.malloc, proxy.memset) */
+export type BoundCallFn = (...args: Arg[]) => Promise<Native.NativePointer>;
+/**
+ * ProxyThread provides a high-level, extensible interface for interacting with a captured thread.
+ * Each operation (read, write, call) can be independently replaced via setter methods.
+ */
+export declare class ProxyThread {
+    /** `msvcrt!fopen(path, mode)` */
+    fopen: (path: Arg, mode: Arg) => Promise<Native.NativePointer>;
+    /** `msvcrt!memset(dest, value, count)` */
+    memset: (dest: Arg, value: Arg, count: Arg) => Promise<Native.NativePointer>;
+    /** `msvcrt!malloc(size)` */
+    malloc: (size: Arg) => Promise<Native.NativePointer>;
+    /** `msvcrt!calloc(count, size)` */
+    calloc: (count: Arg, size: Arg) => Promise<Native.NativePointer>;
+    /** `msvcrt!fwrite(buffer, size, count, stream)` */
+    fwrite: (buffer: Arg, size: Arg, count: Arg, stream: Arg) => Promise<Native.NativePointer>;
+    /** `msvcrt!fflush(stream)` */
+    fflush: (stream: Arg) => Promise<Native.NativePointer>;
+    /** `msvcrt!fclose(stream)` */
+    fclose: (stream: Arg) => Promise<Native.NativePointer>;
+    /** `msvcrt!fread(buffer, size, count, stream)` */
+    fread: (buffer: Arg, size: Arg, count: Arg, stream: Arg) => Promise<Native.NativePointer>;
+    /** `msvcrt!realloc(ptr, size)` */
+    realloc: (ptr: Arg, size: Arg) => Promise<Native.NativePointer>;
+    private _read;
+    private _write;
+    private _call;
+    private _close;
+    private _alloc;
+    private _free;
+    constructor(close: CloseFn, process?: Native.Process);
+    /**
+     * Binds a named function onto this proxy instance.
+     * The bound function delegates to `this.call(address, ...args)`.
+     *
+     * @param name Function name — becomes a property on the proxy (e.g. 'malloc').
+     * @param address Target function address in the remote process.
+     */
+    bind(name: string, address: Native.NativePointer): void;
+    /** Sets the read memory strategy */
+    setReader(fn: ReadMemoryFn): void;
+    /** Sets the write memory strategy */
+    setWriter(fn: WriteMemoryFn): void;
+    /** Sets the call strategy */
+    setCaller(fn: CallFn): void;
+    /** Sets the close strategy */
+    setCloser(fn: CloseFn): void;
+    /** Sets the alloc strategy */
+    setAllocer(fn: AllocFn): void;
+    /** Sets the free strategy */
+    setFreer(fn: FreeFn): void;
+    /** Reads memory from the remote process */
+    read(address: Native.NativePointer, size: number): Promise<Buffer>;
+    /** Writes memory into the remote process */
+    write(address: Native.NativePointer, data: Buffer | Native.NativePointer, size?: number): Promise<number>;
+    /** Calls a function, passing this proxy as context */
+    call(address: Native.NativePointer, ...args: Arg[]): Promise<Native.NativePointer>;
+    /**
+     * Restores the thread to its original state and releases it.
+     * @param suicide If provided, terminates the thread with this exit code instead of resuming it.
+     */
+    close(suicide?: number): Promise<void>;
+    /**
+     * Allocates memory in the remote process.
+     *
+     * - `opts.fill` undefined         → `malloc(size)`
+     * - `opts.fill === 0`              → `calloc(1, size)` (zero-initialized)
+     * - `opts.fill > 0`                → `malloc(size)` + `memset(ptr, fill, size)`
+     * - `opts.type`                    → zone hint for HeapPool (READONLY / READWRITE)
+     * - `opts.address`                 → realloc mode: resize existing allocation
+     */
+    alloc(size: number, opts?: AllocOptions): Promise<Native.NativePointer>;
+    /**
+     * Frees a previously allocated remote pointer.
+     */
+    free(ptr: Native.NativePointer): Promise<void>;
+}
+//# sourceMappingURL=proxy-thread.d.ts.map

package/dist/thread/proxy-thread.d.ts.map

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

package/dist/thread/proxy-thread.js

@@ -0,0 +1,154 @@
+import * as Native from '@cheatron/native';
+import { crt } from '../crt.js';
+/**
+ * ProxyThread provides a high-level, extensible interface for interacting with a captured thread.
+ * Each operation (read, write, call) can be independently replaced via setter methods.
+ */
+export class ProxyThread {
+    // Note: `free` is a first-class delegate method below — not a CRT auto-binding.
+    _read;
+    _write;
+    _call;
+    _close;
+    _alloc;
+    _free;
+    constructor(close, process) {
+        this._close = close;
+        this._read = async (_proxy, address, size) => {
+            if (!process)
+                throw new Error('read not configured and no Process provided.');
+            return process.memory.read(address, size);
+        };
+        this._write = async (_proxy, address, data, size) => {
+            if (!process)
+                throw new Error('write not configured and no Process provided.');
+            if (data instanceof Native.NativePointer) {
+                if (size) {
+                    const written = process.memory.writeWithPointer(address, data, size);
+                    if (written != size) {
+                        throw new Error('Failed to write memory.');
+                    }
+                    return written;
+                }
+                else {
+                    throw new Error('Size must be specified when writing a pointer.');
+                }
+            }
+            else {
+                const writeSize = size ?? data.length;
+                const written = process.memory.write(address, data, writeSize);
+                if (written != writeSize) {
+                    throw new Error('Failed to write memory.');
+                }
+                return written;
+            }
+        };
+        this._call = async (_proxy, _address, ..._args) => {
+            throw new Error('call not configured.');
+        };
+        // Default alloc: malloc / calloc / malloc+memset depending on opts.fill
+        this._alloc = async (_proxy, size, opts) => {
+            if (opts?.address) {
+                // Basic realloc via CRT
+                const ptr = await this.realloc(opts.address.address, BigInt(size));
+                if (ptr.address === 0n)
+                    throw new Error(`realloc(0x${opts.address.address.toString(16)}, ${size}) returned NULL`);
+                return ptr;
+            }
+            const fill = opts?.fill;
+            if (fill === undefined) {
+                return this.malloc(BigInt(size));
+            }
+            else if (fill === 0) {
+                return this.calloc(1n, BigInt(size));
+            }
+            else {
+                const ptr = await this.malloc(BigInt(size));
+                await this.memset(ptr.address, BigInt(fill & 0xff), BigInt(size));
+                return ptr;
+            }
+        };
+        // Default free: delegates to msvcrt!free via the call chain
+        this._free = async (_proxy, ptr) => {
+            await this.call(crt.free, ptr.address);
+        };
+        // Auto-bind all CRT functions except 'free' (free is a first-class delegate method)
+        for (const [name, address] of Object.entries(crt)) {
+            if (name !== 'free')
+                this.bind(name, address);
+        }
+    }
+    /**
+     * Binds a named function onto this proxy instance.
+     * The bound function delegates to `this.call(address, ...args)`.
+     *
+     * @param name Function name — becomes a property on the proxy (e.g. 'malloc').
+     * @param address Target function address in the remote process.
+     */
+    bind(name, address) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this[name] = (...args) => this.call(address, ...args);
+    }
+    /** Sets the read memory strategy */
+    setReader(fn) {
+        this._read = fn;
+    }
+    /** Sets the write memory strategy */
+    setWriter(fn) {
+        this._write = fn;
+    }
+    /** Sets the call strategy */
+    setCaller(fn) {
+        this._call = fn;
+    }
+    /** Sets the close strategy */
+    setCloser(fn) {
+        this._close = fn;
+    }
+    /** Sets the alloc strategy */
+    setAllocer(fn) {
+        this._alloc = fn;
+    }
+    /** Sets the free strategy */
+    setFreer(fn) {
+        this._free = fn;
+    }
+    /** Reads memory from the remote process */
+    read(address, size) {
+        return this._read(this, address, size);
+    }
+    /** Writes memory into the remote process */
+    write(address, data, size) {
+        return this._write(this, address, data, size);
+    }
+    /** Calls a function, passing this proxy as context */
+    async call(address, ...args) {
+        return this._call(this, address, ...args);
+    }
+    /**
+     * Restores the thread to its original state and releases it.
+     * @param suicide If provided, terminates the thread with this exit code instead of resuming it.
+     */
+    close(suicide) {
+        return this._close(this, suicide);
+    }
+    /**
+     * Allocates memory in the remote process.
+     *
+     * - `opts.fill` undefined         → `malloc(size)`
+     * - `opts.fill === 0`              → `calloc(1, size)` (zero-initialized)
+     * - `opts.fill > 0`                → `malloc(size)` + `memset(ptr, fill, size)`
+     * - `opts.type`                    → zone hint for HeapPool (READONLY / READWRITE)
+     * - `opts.address`                 → realloc mode: resize existing allocation
+     */
+    alloc(size, opts) {
+        return this._alloc(this, size, opts);
+    }
+    /**
+     * Frees a previously allocated remote pointer.
+     */
+    free(ptr) {
+        return this._free(this, ptr);
+    }
+}
+//# sourceMappingURL=proxy-thread.js.map

package/dist/thread/proxy-thread.js.map

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@cheatron/nthread",
+  "version": "1.0.0",
+  "description": "Non-invasive x64 Windows thread hijacking library — seize control of existing threads without shellcode, remote allocation, or CreateRemoteThread.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "thread-hijacking",
+    "windows",
+    "x64",
+    "game-hacking",
+    "cheat",
+    "native",
+    "process-injection",
+    "rop-gadget",
+    "memset",
+    "msvcrt"
+  ],
+  "author": "Cheatron",
+  "homepage": "https://github.com/Cheatron/cheatron-nthread#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cheatron/cheatron-nthread.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Cheatron/cheatron-nthread/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "lint": "eslint \"{src,tests}/**/*.ts\" --cache",
+    "lint:fix": "eslint \"{src,tests}/**/*.ts\" --fix",
+    "format": "prettier --write \"{src,tests}/**/*.ts\"",
+    "format:check": "prettier --check \"{src,tests}/**/*.ts\""
+  },
+  "dependencies": {
+    "@cheatron/keystone": "^1.0.1",
+    "@cheatron/native": "^1.2.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/bun": "latest",
+    "eslint": "^10.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.3.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0"
+  }
+}