@cheatron/nthread 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cheatron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @cheatron/nthread
+
+**NThread** is a thread hijacking library for x64 Windows that seizes control of existing threads — without injecting shellcode, allocating remote memory, or using `CreateRemoteThread`.
+
+> Built on [@cheatron/native](https://github.com/Cheatron/cheatron-native). TypeScript port of the original [C/C++ NThread](https://github.com/woldann/NThread).
+
+> [!IMPORTANT]
+> **64-bit Windows only.** Requires Wine to develop/test on Linux.
+
+---
+
+## How It Works
+
+NThread reuses two tiny instruction sequences (gadgets) already present in loaded modules:
+
+| Gadget | Pattern | Purpose |
+|--------|---------|--------|
+| **Sleep** | `jmp .` (`EB FE`) | Parks the thread in an infinite loop |
+| **Pivot** | `push reg; ret` | Redirects `RIP` to the sleep gadget |
+
+Hijack sequence: suspend → capture context → redirect RIP through pivot → spin until RIP lands on sleep gadget. No shellcode, no remote allocation — just register writes.
+
+---
+
+## Features
+
+- **No code injection** — reuses gadgets in `ntdll`, `kernel32`, `kernelbase`, `msvcrt`
+- **No `WriteProcessMemory`** — memory ops are performed by hijacking the target thread to call its own `msvcrt` functions
+- **Auto-discovery** — scans modules lazily via `Module.scan()`
+- **Reversible** — saves full register context before hijacking; restores on `proxy.close()`
+- **CRT bridge** — resolves `msvcrt!malloc`, `calloc`, `memset`, `fwrite`, etc. and calls them *from inside the target thread*
+- **Write optimization** — `romem` tracks known region contents and lets `write()` skip unchanged bytes automatically
+- **Heap allocator** — `NThreadHeap` pre-allocates a single heap block in the target and sub-allocates from it, minimising round-trips
+
+---
+
+## Installation
+
+```bash
+bun add @cheatron/nthread
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { NThread, createReadOnlyMemory } from '@cheatron/nthread';
+
+const nthread = new NThread();
+
+// Hijack an existing thread by TID
+const [proxy, captured] = await nthread.inject(tid);
+
+// Call a function inside the target thread (x64 calling convention)
+const ptr = await proxy.call(crt.malloc, 1024n);
+
+// Write memory via hijacked memset calls
+await proxy.write(ptr, Buffer.from([0xDE, 0xAD, 0xBE, 0xEF]));
+
+// Allocate and write a wide string in one step
+const strPtr = await proxy.allocString('Hello, target!');
+
+// Read memory back
+const buf = await proxy.read(ptr, 4);
+
+// Restore original context and release
+await proxy.close();
+```
+
+---
+
+## Core Components
+
+### `NThread`
+
+Lightweight orchestrator — holds resolved gadget addresses and runs the hijack sequence.
+
+```typescript
+new NThread(processId?, sleepAddress?, pushretAddress?, regKey?)
+```
+
+| Method | Description |
+|--------|-------------|
+| `inject(thread)` | Hijack a thread (TID or `Thread`), returns `[ProxyThread, CapturedThread]` |
+| `threadCall(thread, target, args, timeout)` | Execute a function call on a captured thread |
+| `writeMemory(thread, dest, source)` | Write via decomposed `memset` calls; romem-aware |
+
+Overridable hooks (for subclasses):
+- `threadClose(proxy, captured, suicide?)` — called by `proxy.close()`
+- `threadAlloc(proxy, size, opts?)` — called by `proxy.alloc()`
+- `threadFree(proxy, ptr)` — called by `proxy.free()`
+
+### `NThreadHeap`
+
+Subclass of `NThread`. Pre-allocates a single heap block (`calloc`) in the target and sub-allocates from it. The heap doubles on full (up to `maxSize`); oversized requests fall back to `msvcrt!malloc`.
+
+```typescript
+new NThreadHeap(heapSize?, maxSize?, processId?, sleepAddress?, pushretAddress?, regKey?)
+// Defaults: heapSize = 65536, maxSize = 65536 * 8
+```
+
+All proxy allocations are **freed atomically on `proxy.close()`**.
+
+### `CapturedThread`
+
+Extends `Native.Thread`. Owns the hardware context cache, suspend tracking, and register manipulation for a single captured thread.
+
+| Method | Description |
+|--------|-------------|
+| `fetchContext()` / `applyContext()` | Sync hardware ↔ cache |
+| `getRIP()` / `setRIP(addr)` | RIP convenience accessors |
+| `wait(timeoutMs?)` | Poll until RIP == sleep address |
+| `release()` | Restore saved context without closing handle |
+| `close()` | `release()` → drain suspends → close handle |
+
+### `ProxyThread`
+
+High-level interface for a captured thread. Each operation is a replaceable delegate.
+
+```typescript
+new ProxyThread(close: CloseFn, process?: Native.Process)
+```
+
+| Method | Description |
+|--------|-------------|
+| `read(address, size)` | Read memory |
+| `write(address, data, size?)` | Write memory |
+| `call(address, ...args)` | Call a function |
+| `alloc(size, opts?)` | Allocate memory (`malloc`/`calloc`/realloc) |
+| `free(ptr)` | Free memory |
+| `allocString(str, encoding?, opts?)` | Alloc + write a string; null-terminated; default encoding `utf16le` |
+| `close(suicide?)` | Release the thread (or terminate with exit code) |
+| `setReader/setWriter/setCaller/setCloser/setAllocer/setFreer` | Replace delegates |
+
+### `globals.ts` — Gadget Registry
+
+Manages sleep and pushret gadget pools. Auto-discovery runs once lazily on first use, scanning `ntdll`, `kernel32`, `kernelbase`, `msvcrt`. Register priority: `Rbx → Rbp → Rdi → Rsi`.
+
+### `crt.ts` — CRT Bridge
+
+Resolves `msvcrt.dll` exports at load time (`malloc`, `calloc`, `free`, `memset`, `realloc`, `fopen`, `fread`, `fwrite`, `fflush`, `fclose`). All values are `NativePointer` — set as `RIP` on the hijacked thread.
+
+---
+
+## Read-Only Memory (`romem`)
+
+`romem` tracks a known-content region as a `(remote: NativePointer, local: Buffer)` pair. `proxy.write()` auto-detects overlaps and skips unchanged bytes.
+
+```typescript
+import { createReadOnlyMemory, unregisterReadOnlyMemory } from '@cheatron/nthread';
+
+const romem = await createReadOnlyMemory(proxy, 256); // calloc in target
+const data = Buffer.alloc(256);
+data.writeUInt32LE(0xDEADBEEF, 0);
+await proxy.write(romem.remote, data); // only changed bytes are written
+
+unregisterReadOnlyMemory(romem);
+```
+
+---
+
+## Development
+
+```bash
+bun install
+bun run build
+wine /path/to/bun.exe test
+```
+
+---
+
+## License
+
+MIT

package/dist/crt.d.ts

@@ -0,0 +1,24 @@
+import * as Native from '@cheatron/native';
+/**
+ * CRTFunctions: A collection of standard C Runtime functions resolved in the target process.
+ * These are essential for performing standard operations like memory allocation (malloc/free)
+ * and file I/O (fopen/fwrite) from native code within the hijacked thread.
+ */
+export interface CRTFunctions {
+    fopen: Native.NativePointer;
+    memset: Native.NativePointer;
+    malloc: Native.NativePointer;
+    calloc: Native.NativePointer;
+    realloc: Native.NativePointer;
+    fwrite: Native.NativePointer;
+    fflush: Native.NativePointer;
+    fclose: Native.NativePointer;
+    fread: Native.NativePointer;
+    free: Native.NativePointer;
+}
+/**
+ * Global CRT function pointers.
+ * These are initialized lazily or on import to be used globally by other components.
+ */
+export declare const crt: CRTFunctions;
+//# sourceMappingURL=crt.d.ts.map

package/dist/crt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crt.d.ts","sourceRoot":"","sources":["../src/crt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAG3C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC,aAAa,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC,aAAa,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC,aAAa,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC,aAAa,CAAC;CAC5B;AAYD;;;GAGG;AACH,eAAO,MAAM,GAAG,EAAE,YAWjB,CAAC"}

package/dist/crt.js

@@ -0,0 +1,28 @@
+import * as Native from '@cheatron/native';
+import { log } from './logger.js';
+/**
+ * Internal helper to resolve a function by name from the static `msvcrt.dll` module.
+ * This assumes `msvcrt.dll` is already loaded in the target process (common for Win32 apps).
+ */
+const get = (name) => {
+    const addr = Native.Module.crt.getProcAddress(name);
+    log.debug('CRT', `Resolved ${name}: ${addr}`);
+    return addr;
+};
+/**
+ * Global CRT function pointers.
+ * These are initialized lazily or on import to be used globally by other components.
+ */
+export const crt = {
+    fopen: get('fopen'),
+    memset: get('memset'),
+    malloc: get('malloc'),
+    calloc: get('calloc'),
+    realloc: get('realloc'),
+    fwrite: get('fwrite'),
+    fflush: get('fflush'),
+    fclose: get('fclose'),
+    fread: get('fread'),
+    free: get('free'),
+};
+//# sourceMappingURL=crt.js.map

package/dist/crt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crt.js","sourceRoot":"","sources":["../src/crt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAoBlC;;;GAGG;AACH,MAAM,GAAG,GAAG,CAAC,IAAY,EAAwB,EAAE;IACjD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IACpD,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,YAAY,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,GAAG,GAAiB;IAC/B,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC;IACnB,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC;IACrB,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC;IACrB,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC;IACrB,OAAO,EAAE,GAAG,CAAC,SAAS,CAAC;IACvB,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC;IACrB,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC;IACrB,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC;IACrB,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC;IACnB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;CAClB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,50 @@
+declare abstract class BaseError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class NThreadError extends BaseError {
+}
+export declare class NoSleepAddressError extends NThreadError {
+    constructor();
+}
+export declare class NoPushretAddressError extends NThreadError {
+    constructor();
+}
+export declare class InjectError extends NThreadError {
+}
+export declare class InjectTimeoutError extends InjectError {
+    readonly waitResult: number;
+    constructor(waitResult: number);
+}
+export declare class CallError extends NThreadError {
+    readonly target: bigint;
+    constructor(message: string, target: bigint);
+}
+export declare class CallNotInjectedError extends CallError {
+    constructor();
+}
+export declare class CallTooManyArgsError extends CallError {
+    readonly argCount: number;
+    constructor(argCount: number);
+}
+export declare class CallRipMismatchError extends CallError {
+    readonly currentRip: bigint;
+    readonly expectedRip: bigint;
+    constructor(target: bigint, currentRip: bigint, expectedRip: bigint);
+}
+export declare class CallTimeoutError extends CallError {
+    readonly waitResult: number;
+    constructor(target: bigint, waitResult: number);
+}
+export declare class CallThreadDiedError extends CallError {
+    constructor(target: bigint);
+}
+export declare class WriteError extends NThreadError {
+}
+export declare class GadgetError extends NThreadError {
+}
+export declare class GadgetScanError extends GadgetError {
+    readonly pattern: string;
+    constructor(pattern: string);
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,uBAAe,SAAU,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAID,qBAAa,YAAa,SAAQ,SAAS;CAAG;AAE9C,qBAAa,mBAAoB,SAAQ,YAAY;;CAIpD;AAED,qBAAa,qBAAsB,SAAQ,YAAY;;CAItD;AAED,qBAAa,WAAY,SAAQ,YAAY;CAAG;AAEhD,qBAAa,kBAAmB,SAAQ,WAAW;aACrB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAG/C;AAID,qBAAa,SAAU,SAAQ,YAAY;IACzC,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEnB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI5C;AAED,qBAAa,oBAAqB,SAAQ,SAAS;;CAIlD;AAED,qBAAa,oBAAqB,SAAQ,SAAS;IACjD,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,QAAQ,EAAE,MAAM;CAO7B;AAED,qBAAa,oBAAqB,SAAQ,SAAS;IACjD,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,WAAW,EAAE,MAAM,CAAC;gBAExB,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAQpE;AAED,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,SAAgB,UAAU,EAAE,MAAM,CAAC;gBAEvB,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAO/C;AAED,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,MAAM,EAAE,MAAM;CAM3B;AAID,qBAAa,UAAW,SAAQ,YAAY;CAAG;AAI/C,qBAAa,WAAY,SAAQ,YAAY;CAAG;AAEhD,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,SAAgB,OAAO,EAAE,MAAM,CAAC;gBAEpB,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors.js

@@ -0,0 +1,84 @@
+// ── Base ──────────────────────────────────────────────────────────────────────
+class BaseError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = this.constructor.name;
+    }
+}
+// ── NThread errors ────────────────────────────────────────────────────────────
+export class NThreadError extends BaseError {
+}
+export class NoSleepAddressError extends NThreadError {
+    constructor() {
+        super('No valid sleep address could be found or auto-discovered');
+    }
+}
+export class NoPushretAddressError extends NThreadError {
+    constructor() {
+        super('No valid pushret gadget could be found or auto-discovered');
+    }
+}
+export class InjectError extends NThreadError {
+}
+export class InjectTimeoutError extends InjectError {
+    waitResult;
+    constructor(waitResult) {
+        super(`Thread did not reach sleep address (wait result: ${waitResult})`);
+        this.waitResult = waitResult;
+    }
+}
+// ── Call errors ───────────────────────────────────────────────────────────────
+export class CallError extends NThreadError {
+    target;
+    constructor(message, target) {
+        super(message);
+        this.target = target;
+    }
+}
+export class CallNotInjectedError extends CallError {
+    constructor() {
+        super('Thread not injected. Call inject() first.', 0n);
+    }
+}
+export class CallTooManyArgsError extends CallError {
+    argCount;
+    constructor(argCount) {
+        super(`x64 calling convention supports max 4 register arguments (RCX, RDX, R8, R9), got ${argCount}`, 0n);
+        this.argCount = argCount;
+    }
+}
+export class CallRipMismatchError extends CallError {
+    currentRip;
+    expectedRip;
+    constructor(target, currentRip, expectedRip) {
+        super(`Thread RIP (0x${currentRip.toString(16)}) is not at sleep address (0x${expectedRip.toString(16)})`, target);
+        this.currentRip = currentRip;
+        this.expectedRip = expectedRip;
+    }
+}
+export class CallTimeoutError extends CallError {
+    waitResult;
+    constructor(target, waitResult) {
+        super(`Thread did not return to sleep address (wait result: ${waitResult})`, target);
+        this.waitResult = waitResult;
+    }
+}
+export class CallThreadDiedError extends CallError {
+    constructor(target) {
+        super('Thread died during call (e.g. ExitThread / noreturn function)', target);
+    }
+}
+// ── Write errors ─────────────────────────────────────────────────────────────────
+export class WriteError extends NThreadError {
+}
+// ── Gadget errors ─────────────────────────────────────────────────────────────
+export class GadgetError extends NThreadError {
+}
+export class GadgetScanError extends GadgetError {
+    pattern;
+    constructor(pattern) {
+        super(`Failed to scan for gadget pattern: ${pattern}`);
+        this.pattern = pattern;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,MAAe,SAAU,SAAQ,KAAK;IACpC,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IACpC,CAAC;CACF;AAED,iFAAiF;AAEjF,MAAM,OAAO,YAAa,SAAQ,SAAS;CAAG;AAE9C,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACnD;QACE,KAAK,CAAC,0DAA0D,CAAC,CAAC;IACpE,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,YAAY;IACrD;QACE,KAAK,CAAC,2DAA2D,CAAC,CAAC;IACrE,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,YAAY;CAAG;AAEhD,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IACrB;IAA5B,YAA4B,UAAkB;QAC5C,KAAK,CAAC,oDAAoD,UAAU,GAAG,CAAC,CAAC;QAD/C,eAAU,GAAV,UAAU,CAAQ;IAE9C,CAAC;CACF;AAED,iFAAiF;AAEjF,MAAM,OAAO,SAAU,SAAQ,YAAY;IACzB,MAAM,CAAS;IAE/B,YAAY,OAAe,EAAE,MAAc;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,SAAS;IACjD;QACE,KAAK,CAAC,2CAA2C,EAAE,EAAE,CAAC,CAAC;IACzD,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,SAAS;IACjC,QAAQ,CAAS;IAEjC,YAAY,QAAgB;QAC1B,KAAK,CACH,oFAAoF,QAAQ,EAAE,EAC9F,EAAE,CACH,CAAC;QACF,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,SAAS;IACjC,UAAU,CAAS;IACnB,WAAW,CAAS;IAEpC,YAAY,MAAc,EAAE,UAAkB,EAAE,WAAmB;QACjE,KAAK,CACH,iBAAiB,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,gCAAgC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EACnG,MAAM,CACP,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,SAAS;IAC7B,UAAU,CAAS;IAEnC,YAAY,MAAc,EAAE,UAAkB;QAC5C,KAAK,CACH,wDAAwD,UAAU,GAAG,EACrE,MAAM,CACP,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IAChD,YAAY,MAAc;QACxB,KAAK,CACH,+DAA+D,EAC/D,MAAM,CACP,CAAC;IACJ,CAAC;CACF;AAED,oFAAoF;AAEpF,MAAM,OAAO,UAAW,SAAQ,YAAY;CAAG;AAE/C,iFAAiF;AAEjF,MAAM,OAAO,WAAY,SAAQ,YAAY;CAAG;AAEhD,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAC9B,OAAO,CAAS;IAEhC,YAAY,OAAe;QACzB,KAAK,CAAC,sCAAsC,OAAO,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/globals.d.ts

@@ -0,0 +1,48 @@
+import * as Native from '@cheatron/native';
+/**
+ * GeneralPurposeRegs: Supported 64-bit general purpose registers for x64 hijacking.
+ */
+export type GeneralPurposeRegs = Extract<keyof Native.ThreadContext, 'Rax' | 'Rcx' | 'Rdx' | 'Rbx' | 'Rsp' | 'Rbp' | 'Rsi' | 'Rdi' | 'R8' | 'R9' | 'R10' | 'R11' | 'R12' | 'R13' | 'R14' | 'R15'>;
+/**
+ * Register priority sequence for hijacking.
+ * We prefer registers that are traditionally "callee-saved" or less likely to be
+ * actively holding critical data during a random suspension point.
+ */
+export declare const leastClobberedRegs: GeneralPurposeRegs[];
+/**
+ * Manually registers a sleep address (gadget) into the global pool.
+ * @param address The NativePointer to the 'jmp .' instruction.
+ */
+export declare function registerSleepAddress(address: Native.NativePointer): void;
+/**
+ * Retrieves a random sleep address from the pool.
+ * If the pool is empty, it triggers auto-discovery.
+ */
+export declare function getRandomSleepAddress(): Native.NativePointer | undefined;
+/**
+ * Manually registers a pushret address (gadget) into the global pool.
+ * @param address The NativePointer to the 'push reg; ret' sequence.
+ * @param regKey The register used in the 'push' instruction.
+ */
+export declare function registerPushretAddress(address: Native.NativePointer, regKey: GeneralPurposeRegs): void;
+/**
+ * Retrieves a random pushret address from the pool, prioritized by stability.
+ * @param regKey Optional filter to find a gadget for a specific register.
+ * @returns An object containing the pointer and the register it targets.
+ *
+ * Logic:
+ * 1. If regKey is specified, search only for that register.
+ * 2. If no regKey is specified, search through `leastClobberedRegs` in order
+ *    and return the first available gadget type found.
+ */
+export declare function getRandomPushretAddress(regKey?: GeneralPurposeRegs): {
+    address: Native.NativePointer;
+    regKey: GeneralPurposeRegs;
+} | undefined;
+/**
+ * Scans all loaded modules in the current process for useful hijacking gadgets.
+ * Uses Keystone to assemble the target instructions on-the-fly to ensure
+ * architecture-perfect pattern matching.
+ */
+export declare function autoDiscoverAddresses(): void;
+//# sourceMappingURL=globals.d.ts.map

package/dist/globals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../src/globals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAM3C;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,MAAM,MAAM,CAAC,aAAa,EACxB,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,IAAI,GACJ,IAAI,GACJ,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,CACR,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,kBAAkB,EAMlD,CAAC;AAWF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,aAAa,GAAG,IAAI,CAGxE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAAC,aAAa,GAAG,SAAS,CASxE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,CAAC,aAAa,EAC7B,MAAM,EAAE,kBAAkB,GACzB,IAAI,CAGN;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,CAAC,EAAE,kBAAkB,GAC1B;IAAE,OAAO,EAAE,MAAM,CAAC,aAAa,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAAG,SAAS,CA8B3E;AAKD;;;;GAIG;AACH,wBAAgB,qBAAqB,SAiDpC"}

package/dist/globals.js

@@ -0,0 +1,132 @@
+import * as Native from '@cheatron/native';
+import { log } from './logger.js';
+import { KeystoneX86 } from '@cheatron/keystone';
+const globalsLog = log.child('Globals');
+/**
+ * Register priority sequence for hijacking.
+ * We prefer registers that are traditionally "callee-saved" or less likely to be
+ * actively holding critical data during a random suspension point.
+ */
+export const leastClobberedRegs = [
+    'Rbx',
+    'Rbp',
+    'Rdi',
+    'Rsi', // Non-Volatile (stable frame pointers/iterators)
+    // "R12" - "R15" are also non-volatile but less common in simple gadgets
+];
+/** Internal pool of discovered 'jmp .' addresses */
+const sleepAddresses = [];
+/** Internal mapping of discovered 'push reg; ret' addresses to their respective registers */
+const pushretAddresses = new Map();
+/**
+ * Manually registers a sleep address (gadget) into the global pool.
+ * @param address The NativePointer to the 'jmp .' instruction.
+ */
+export function registerSleepAddress(address) {
+    sleepAddresses.push(address);
+    globalsLog.debug(`Registered sleepAddress: ${address}`);
+}
+/**
+ * Retrieves a random sleep address from the pool.
+ * If the pool is empty, it triggers auto-discovery.
+ */
+export function getRandomSleepAddress() {
+    if (sleepAddresses.length === 0) {
+        autoDiscoverAddresses();
+    }
+    if (sleepAddresses.length === 0)
+        return undefined;
+    const randomIndex = Math.floor(Math.random() * sleepAddresses.length);
+    return sleepAddresses[randomIndex];
+}
+/**
+ * Manually registers a pushret address (gadget) into the global pool.
+ * @param address The NativePointer to the 'push reg; ret' sequence.
+ * @param regKey The register used in the 'push' instruction.
+ */
+export function registerPushretAddress(address, regKey) {
+    pushretAddresses.set(address.address, { pointer: address, regKey });
+    globalsLog.debug(`Registered pushretAddress: ${address} (RegKey: ${regKey})`);
+}
+/**
+ * Retrieves a random pushret address from the pool, prioritized by stability.
+ * @param regKey Optional filter to find a gadget for a specific register.
+ * @returns An object containing the pointer and the register it targets.
+ *
+ * Logic:
+ * 1. If regKey is specified, search only for that register.
+ * 2. If no regKey is specified, search through `leastClobberedRegs` in order
+ *    and return the first available gadget type found.
+ */
+export function getRandomPushretAddress(regKey) {
+    if (pushretAddresses.size === 0) {
+        autoDiscoverAddresses();
+    }
+    if (pushretAddresses.size === 0)
+        return undefined;
+    let validEntries = Array.from(pushretAddresses.values());
+    if (regKey) {
+        validEntries = validEntries.filter((e) => e.regKey === regKey);
+    }
+    else {
+        // Step through priority list to find the "best" available gadget class
+        for (const bestReg of leastClobberedRegs) {
+            const bestEntries = validEntries.filter((e) => e.regKey === bestReg);
+            if (bestEntries.length > 0) {
+                validEntries = bestEntries;
+                break;
+            }
+        }
+    }
+    if (validEntries.length === 0)
+        return undefined;
+    const randomIndex = Math.floor(Math.random() * validEntries.length);
+    const selected = validEntries[randomIndex];
+    if (!selected)
+        return undefined;
+    return { address: selected.pointer, regKey: selected.regKey };
+}
+/** Flag to prevent redundant heavy scans */
+let isAutoDiscovered = false;
+/**
+ * Scans all loaded modules in the current process for useful hijacking gadgets.
+ * Uses Keystone to assemble the target instructions on-the-fly to ensure
+ * architecture-perfect pattern matching.
+ */
+export function autoDiscoverAddresses() {
+    if (isAutoDiscovered)
+        return;
+    globalsLog.info('Starting auto-discovery of global execution addresses via pattern scanning...');
+    // Search only in executable memory (RX or RWX)
+    const protect = Native.MemoryProtection.EXECUTE_READ |
+        Native.MemoryProtection.EXECUTE_READWRITE;
+    const assembler = new KeystoneX86();
+    // 1. Scan for Sleep Gadgets ('jmp .')
+    const sleepCode = assembler.asm('jmp .');
+    const sleepPattern = new Native.Pattern(sleepCode)
+        .noLimit()
+        .addProtect(protect);
+    const sleepRes = Native.Module.scan(sleepPattern);
+    for (const match of sleepRes.all()) {
+        registerSleepAddress(match.pointer);
+    }
+    // 2. Scan for PushRet Gadgets ('push reg; ret')
+    const retCode = assembler.asm('ret');
+    for (const regKey of leastClobberedRegs) {
+        // Compile 'push rax' etc.
+        const pushCode = assembler.asm('push ' + regKey.toString().toLowerCase());
+        // Pattern = [Push opcode(s)] + [Ret opcode]
+        const pushretCode = [...pushCode, ...retCode];
+        const pushretPattern = new Native.Pattern(pushretCode)
+            .noLimit()
+            .addProtect(protect);
+        // Perform process-wide cross-module scan
+        const pushretRes = Native.Module.scan(pushretPattern);
+        for (const match of pushretRes.all()) {
+            registerPushretAddress(match.pointer, regKey);
+        }
+    }
+    isAutoDiscovered = true;
+    globalsLog.info(`Auto-discovery complete. Found ${sleepAddresses.length} sleep gadgets and ${pushretAddresses.size} pushret gadgets.`);
+}
+//# sourceMappingURL=globals.js.map

package/dist/globals.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from './crt.js';
+export * from './errors.js';
+export * from './logger.js';
+export * from './thread/captured-thread.js';
+export * from './nthread.js';
+export * from './nthread-heap.js';
+export * from './globals.js';
+export * from './thread/proxy-thread.js';
+export * from './memory/romem.js';
+export * from './memory/heap.js';
+export * from './memory/alloc-options.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from './crt.js';
+export * from './errors.js';
+export * from './logger.js';
+export * from './thread/captured-thread.js';
+export * from './nthread.js';
+export * from './nthread-heap.js';
+export * from './globals.js';
+export * from './thread/proxy-thread.js';
+export * from './memory/romem.js';
+export * from './memory/heap.js';
+export * from './memory/alloc-options.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,2 @@
+export declare const log: import("@cheatron/log").LoggerHelpers;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,GAAG,uCAA6B,CAAC"}

package/dist/logger.js

@@ -0,0 +1,3 @@
+import { createLogHelper } from '@cheatron/log';
+export const log = createLogHelper('NThread');
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,CAAC,MAAM,GAAG,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC"}