@jshookmcp/jshook 0.2.6 → 0.2.8

package/dist/StructureAnalyzer-D4GkMduU.mjs

@@ -0,0 +1,426 @@
+import { An as STRUCT_RTTI_MAX_STRING_LEN, jn as STRUCT_VTABLE_MAX_FUNCTIONS, kn as STRUCT_ANALYZE_DEFAULT_SIZE } from "./constants-CCvsN80K.mjs";
+import { t as nativeMemoryManager } from "./NativeMemoryManager.impl-CB6gJ0NM.mjs";
+import { t as createPlatformProvider } from "./factory-CibqTNC8.mjs";
+//#region src/native/StructureAnalyzer.ts
+/**
+* Structure Analyzer — heuristic memory structure inference.
+*
+* Analyzes memory at a given address to infer field types, detect vtables,
+* parse RTTI, and export C-style struct definitions.
+*
+* Uses PlatformMemoryAPI for cross-platform memory operations.
+*
+* @module StructureAnalyzer
+*/
+var StructureAnalyzer = class {
+	_provider = null;
+	get provider() {
+		if (!this._provider) this._provider = createPlatformProvider();
+		return this._provider;
+	}
+	/**
+	* Infer the structure layout at a given address.
+	*/
+	async analyzeStructure(pid, address, options) {
+		const size = options?.size ?? STRUCT_ANALYZE_DEFAULT_SIZE;
+		const baseAddr = BigInt(address.startsWith("0x") ? address : `0x${address}`);
+		const handle = this.provider.openProcess(pid, false);
+		try {
+			const buf = this.provider.readMemory(handle, baseAddr, size).data;
+			const fields = [];
+			let offset = 0;
+			while (offset < size) {
+				const remaining = size - offset;
+				if (remaining < 1) break;
+				const classification = this.classifyValue(buf, handle, baseAddr, offset, remaining);
+				fields.push({
+					offset,
+					size: classification.size,
+					type: classification.type,
+					name: `field_0x${offset.toString(16).padStart(2, "0").toUpperCase()}`,
+					value: classification.value,
+					confidence: classification.confidence,
+					notes: classification.notes
+				});
+				offset += classification.size;
+			}
+			let vtableAddress;
+			let className;
+			let baseClasses;
+			if (fields.length > 0 && fields[0].type === "vtable_ptr") {
+				vtableAddress = fields[0].value;
+				if (options?.parseRtti !== false && vtableAddress) try {
+					const rtti = await this.parseRtti(pid, vtableAddress, handle);
+					if (rtti) {
+						className = rtti.className;
+						baseClasses = rtti.baseClasses;
+					}
+				} catch {}
+			}
+			return {
+				baseAddress: `0x${baseAddr.toString(16).toUpperCase()}`,
+				totalSize: size,
+				fields,
+				vtableAddress,
+				className,
+				baseClasses,
+				timestamp: Date.now()
+			};
+		} finally {
+			this.provider.closeProcess(handle);
+		}
+	}
+	/**
+	* Parse vtable at given address.
+	* A vtable is an array of function pointers in executable memory.
+	*/
+	async parseVtable(pid, vtableAddress) {
+		const vtableAddr = BigInt(vtableAddress.startsWith("0x") ? vtableAddress : `0x${vtableAddress}`);
+		const handle = this.provider.openProcess(pid, false);
+		try {
+			const functions = [];
+			const modules = await this.getModuleEntries(pid);
+			for (let i = 0; i < STRUCT_VTABLE_MAX_FUNCTIONS; i++) {
+				const ptrAddr = vtableAddr + BigInt(i * 8);
+				let funcPtr;
+				try {
+					funcPtr = this.provider.readMemory(handle, ptrAddr, 8).data.readBigUInt64LE(0);
+				} catch {
+					break;
+				}
+				if (!this.isValidExecutablePointer(handle, funcPtr)) break;
+				const modInfo = this.resolveToModule(funcPtr, modules);
+				functions.push({
+					index: i,
+					address: `0x${funcPtr.toString(16).toUpperCase()}`,
+					module: modInfo?.module,
+					moduleOffset: modInfo?.offset
+				});
+			}
+			let rttiName;
+			let baseClassList;
+			try {
+				const rtti = await this.parseRtti(pid, vtableAddress, handle);
+				if (rtti) {
+					rttiName = rtti.className;
+					baseClassList = rtti.baseClasses;
+				}
+			} catch {}
+			return {
+				address: `0x${vtableAddr.toString(16).toUpperCase()}`,
+				functionCount: functions.length,
+				functions,
+				rttiName,
+				baseClasses: baseClassList
+			};
+		} finally {
+			this.provider.closeProcess(handle);
+		}
+	}
+	/**
+	* Parse RTTI Complete Object Locator (MSVC x64 layout).
+	*
+	* vtable[-1] → RTTI COL:
+	*   +0x00: signature (1 for x64)
+	*   +0x04: offset
+	*   +0x08: cdOffset
+	*   +0x0C: typeDescriptorRVA
+	*   +0x10: classDescriptorRVA
+	*   +0x14: objectLocatorRVA
+	*
+	* TypeDescriptor (at moduleBase + typeDescriptorRVA):
+	*   +0x00: pVFTable (pointer)
+	*   +0x08: spare (pointer)
+	*   +0x10: name (null-terminated mangled string)
+	*/
+	async parseRtti(pid, vtableAddress, existingHandle) {
+		const vtableAddr = BigInt(vtableAddress.startsWith("0x") ? vtableAddress : `0x${vtableAddress}`);
+		const ownHandle = !existingHandle;
+		const handle = existingHandle ?? this.provider.openProcess(pid, false);
+		try {
+			const colAddr = this.provider.readMemory(handle, vtableAddr - 8n, 8).data.readBigUInt64LE(0);
+			if (!this.isValidReadablePointer(handle, colAddr)) return null;
+			const colBuf = this.provider.readMemory(handle, colAddr, 24).data;
+			if (colBuf.readUInt32LE(0) !== 1) return null;
+			const typeDescRVA = colBuf.readUInt32LE(12);
+			const classDescRVA = colBuf.readUInt32LE(16);
+			const objectLocRVA = colBuf.readUInt32LE(20);
+			const moduleBase = colAddr - BigInt(objectLocRVA);
+			const typeDescAddr = moduleBase + BigInt(typeDescRVA);
+			const className = this.readCString(handle, typeDescAddr + 16n, STRUCT_RTTI_MAX_STRING_LEN);
+			if (!className) return null;
+			const demangled = this.demangleMsvcName(className);
+			const baseClasses = [];
+			try {
+				const classDescAddr = moduleBase + BigInt(classDescRVA);
+				const classDescBuf = this.provider.readMemory(handle, classDescAddr, 16).data;
+				const numBaseClasses = classDescBuf.readUInt32LE(8);
+				const baseClassArrayRVA = classDescBuf.readUInt32LE(12);
+				if (numBaseClasses > 0 && numBaseClasses < 20) {
+					const baseArrayAddr = moduleBase + BigInt(baseClassArrayRVA);
+					const baseArrayBuf = this.provider.readMemory(handle, baseArrayAddr, numBaseClasses * 4).data;
+					for (let i = 1; i < numBaseClasses; i++) {
+						const baseDescRVA = baseArrayBuf.readUInt32LE(i * 4);
+						const baseDescAddr = moduleBase + BigInt(baseDescRVA);
+						try {
+							const baseTypeDescRVA = this.provider.readMemory(handle, baseDescAddr, 8).data.readUInt32LE(0);
+							const baseTypeDescAddr = moduleBase + BigInt(baseTypeDescRVA);
+							const baseName = this.readCString(handle, baseTypeDescAddr + 16n, STRUCT_RTTI_MAX_STRING_LEN);
+							if (baseName) baseClasses.push(this.demangleMsvcName(baseName));
+						} catch {
+							break;
+						}
+					}
+				}
+			} catch {}
+			return {
+				className: demangled,
+				baseClasses
+			};
+		} catch {
+			return null;
+		} finally {
+			if (ownHandle) this.provider.closeProcess(handle);
+		}
+	}
+	/**
+	* Export an inferred struct as C-style definition.
+	*/
+	exportToCStruct(structure, name) {
+		const structName = name ?? structure.className ?? "UnknownStruct";
+		const lines = [];
+		lines.push(`struct ${structName} { // size: 0x${structure.totalSize.toString(16).toUpperCase()} (${structure.totalSize} bytes)`);
+		for (const field of structure.fields) {
+			const cType = this.fieldTypeToCType(field.type, field.size);
+			const offsetStr = `0x${field.offset.toString(16).padStart(2, "0").toUpperCase()}`;
+			const comment = field.notes ? `// +${offsetStr} ${field.notes}` : `// +${offsetStr} = ${field.value}`;
+			if (field.type === "padding") lines.push(`    uint8_t _pad_${field.offset.toString(16)}[${field.size}]; ${comment}`);
+			else lines.push(`    ${cType} ${field.name}; ${comment}`);
+		}
+		lines.push("};");
+		return {
+			name: structName,
+			definition: lines.join("\n"),
+			size: structure.totalSize,
+			fieldCount: structure.fields.filter((f) => f.type !== "padding").length
+		};
+	}
+	/**
+	* Compare two structure instances to find differing vs constant fields.
+	*/
+	async compareInstances(pid, address1, address2, size) {
+		const analysisSize = size ?? STRUCT_ANALYZE_DEFAULT_SIZE;
+		const [struct1, struct2] = await Promise.all([this.analyzeStructure(pid, address1, {
+			size: analysisSize,
+			parseRtti: false
+		}), this.analyzeStructure(pid, address2, {
+			size: analysisSize,
+			parseRtti: false
+		})]);
+		const matching = [];
+		const differing = [];
+		const fieldMap2 = new Map(struct2.fields.map((f) => [f.offset, f]));
+		for (const f1 of struct1.fields) {
+			const f2 = fieldMap2.get(f1.offset);
+			if (!f2) continue;
+			if (f1.value === f2.value && f1.type === f2.type) matching.push(f1);
+			else differing.push({
+				offset: f1.offset,
+				value1: f1.value,
+				value2: f2.value,
+				type: f1.type
+			});
+		}
+		return {
+			matching,
+			differing
+		};
+	}
+	/**
+	* Classify the value at a given offset in the buffer.
+	*/
+	classifyValue(buf, handle, _baseAddr, offset, remaining) {
+		if (remaining >= 8) {
+			const val64 = buf.readBigUInt64LE(offset);
+			if (offset === 0 && val64 !== 0n) {
+				if (this.isValidExecutablePointer(handle, val64)) try {
+					const firstFunc = this.provider.readMemory(handle, val64, 16).data.readBigUInt64LE(0);
+					if (this.isValidExecutablePointer(handle, firstFunc)) return {
+						type: "vtable_ptr",
+						size: 8,
+						value: `0x${val64.toString(16).toUpperCase()}`,
+						confidence: .9,
+						notes: "likely vtable pointer (points to array of executable pointers)"
+					};
+				} catch {}
+			}
+			if (val64 !== 0n && val64 > 65536n && val64 < 140737488355327n) {
+				if (this.isValidReadablePointer(handle, val64)) {
+					const str = this.readCString(handle, val64, 64);
+					if (str && str.length >= 2) return {
+						type: "string_ptr",
+						size: 8,
+						value: `0x${val64.toString(16).toUpperCase()} → "${str.slice(0, 32)}${str.length > 32 ? "..." : ""}"`,
+						confidence: .75,
+						notes: `string pointer: "${str.slice(0, 64)}"`
+					};
+					return {
+						type: "pointer",
+						size: 8,
+						value: `0x${val64.toString(16).toUpperCase()}`,
+						confidence: .7,
+						notes: "valid pointer to readable memory"
+					};
+				}
+			}
+		}
+		if (remaining >= 4) {
+			const val32u = buf.readUInt32LE(offset);
+			const val32s = buf.readInt32LE(offset);
+			const valFloat = buf.readFloatLE(offset);
+			if (val32u === 0 && remaining >= 8 && buf.readUInt32LE(offset + 4) === 0) {
+				let zeroLen = 0;
+				for (let i = offset; i < buf.length && buf[i] === 0; i++) zeroLen++;
+				const alignedPad = Math.min(zeroLen, remaining) & -8;
+				return {
+					type: "padding",
+					size: alignedPad,
+					value: `0x${"00".repeat(Math.min(alignedPad, 8))}`,
+					confidence: .6
+				};
+			}
+			if (val32u === 0) return {
+				type: "int32",
+				size: 4,
+				value: "0",
+				confidence: .4,
+				notes: "zero value — could be int, bool, or padding"
+			};
+			if (val32u === 1) return {
+				type: "bool",
+				size: 4,
+				value: "true",
+				confidence: .5,
+				notes: "value is 1 — could be boolean"
+			};
+			if (isFinite(valFloat) && !isNaN(valFloat) && Math.abs(valFloat) > 1e-10 && Math.abs(valFloat) < 1e8) {
+				const intLooksReasonable = val32u > 0 && val32u < 1e5;
+				const floatHasDecimals = Math.abs(valFloat - Math.round(valFloat)) > .001;
+				if (floatHasDecimals || !intLooksReasonable && Math.abs(valFloat) < 1e4) return {
+					type: "float",
+					size: 4,
+					value: valFloat.toFixed(6),
+					confidence: floatHasDecimals ? .8 : .5,
+					notes: floatHasDecimals ? "IEEE 754 float with fractional part" : "could be float or int"
+				};
+			}
+			if (val32u < 2147483648) return {
+				type: "int32",
+				size: 4,
+				value: val32s.toString(),
+				confidence: .6
+			};
+			return {
+				type: "uint32",
+				size: 4,
+				value: val32u.toString(),
+				confidence: .5
+			};
+		}
+		if (remaining >= 2) return {
+			type: "uint16",
+			size: 2,
+			value: buf.readUInt16LE(offset).toString(),
+			confidence: .4
+		};
+		return {
+			type: "uint8",
+			size: 1,
+			value: buf.readUInt8(offset).toString(),
+			confidence: .3
+		};
+	}
+	isValidReadablePointer(handle, address) {
+		try {
+			const regionInfo = this.provider.queryRegion(handle, address);
+			if (!regionInfo) return false;
+			return regionInfo.isReadable;
+		} catch {
+			return false;
+		}
+	}
+	isValidExecutablePointer(handle, address) {
+		try {
+			const regionInfo = this.provider.queryRegion(handle, address);
+			if (!regionInfo) return false;
+			return regionInfo.isReadable && regionInfo.isExecutable;
+		} catch {
+			return false;
+		}
+	}
+	readCString(handle, address, maxLen) {
+		try {
+			const buf = this.provider.readMemory(handle, address, maxLen).data;
+			const nullIdx = buf.indexOf(0);
+			if (nullIdx < 0) return null;
+			const str = buf.subarray(0, nullIdx).toString("ascii");
+			if (/^[\x20-\x7E]+$/.test(str) && str.length >= 1) return str;
+			return null;
+		} catch {
+			return null;
+		}
+	}
+	demangleMsvcName(name) {
+		const match = name.match(/\.?\?A[VU](.+?)@@/);
+		if (match) return match[1];
+		const enumMatch = name.match(/\.?\?AW4(.+?)@@/);
+		if (enumMatch) return enumMatch[1];
+		return name.replace(/^\./, "").replace(/@@$/, "");
+	}
+	fieldTypeToCType(type, size) {
+		switch (type) {
+			case "int8": return "int8_t";
+			case "uint8": return "uint8_t";
+			case "int16": return "int16_t";
+			case "uint16": return "uint16_t";
+			case "int32": return "int32_t";
+			case "uint32": return "uint32_t";
+			case "int64": return "int64_t";
+			case "uint64": return "uint64_t";
+			case "float": return "float";
+			case "double": return "double";
+			case "pointer": return "void*";
+			case "vtable_ptr": return "void**";
+			case "string_ptr": return "char*";
+			case "bool": return "bool";
+			case "padding": return `uint8_t[${size}]`;
+			case "unknown": return `uint8_t[${size}]`;
+			default: return `uint8_t[${size}]`;
+		}
+	}
+	async getModuleEntries(pid) {
+		const modules = /* @__PURE__ */ new Map();
+		try {
+			const result = await nativeMemoryManager.enumerateModules(pid);
+			if (result.success && result.modules) for (const mod of result.modules) {
+				const base = BigInt(mod.baseAddress.startsWith("0x") ? mod.baseAddress : `0x${mod.baseAddress}`);
+				modules.set(mod.name.toLowerCase(), {
+					name: mod.name,
+					base,
+					size: mod.size
+				});
+			}
+		} catch {}
+		return modules;
+	}
+	resolveToModule(address, moduleMap) {
+		for (const entry of moduleMap.values()) if (address >= entry.base && address < entry.base + BigInt(entry.size)) return {
+			module: entry.name,
+			offset: Number(address - entry.base)
+		};
+		return null;
+	}
+};
+const structureAnalyzer = new StructureAnalyzer();
+//#endregion
+export { StructureAnalyzer, structureAnalyzer };