wowdump 0.2.1 → 0.3.2

package/dist/core/profile-engine.js

@@ -0,0 +1,238 @@
+export class ProfileEngineError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "ProfileEngineError";
+        this.code = code;
+        this.details = details;
+    }
+}
+const SCALAR_SIZES = {
+    u8: 1, i8: 1, u16: 2, i16: 2, u32: 4, i32: 4,
+    u64: 8, i64: 8, f32: 4, f64: 8, pointer: 8,
+    bytes: undefined, utf8: undefined, utf16: undefined
+};
+function record(value, name) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ProfileEngineError("PROFILE_INVALID", `${name} must be an object`);
+    }
+    return value;
+}
+function hex(value, name) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0)
+        return BigInt(value);
+    if (typeof value !== "string" || !/^0x[0-9a-f]+$/i.test(value.trim())) {
+        throw new ProfileEngineError("PROFILE_INVALID", `${name} must be a 0x-prefixed hexadecimal value`);
+    }
+    return BigInt(value);
+}
+function hexText(value) {
+    return `0x${value.toString(16)}`;
+}
+function integer(value, name, maximum = 16 * 1024 * 1024) {
+    const result = typeof value === "number" ? value : Number(value);
+    if (!Number.isSafeInteger(result) || result < 0 || result > maximum) {
+        throw new ProfileEngineError("PROFILE_INVALID", `${name} must be an integer between 0 and ${maximum}`);
+    }
+    return result;
+}
+function scalarType(value, name) {
+    if (typeof value !== "string" || !(value in SCALAR_SIZES)) {
+        throw new ProfileEngineError("PROFILE_INVALID", `${name} has an unsupported scalar type`);
+    }
+    return value;
+}
+function layoutOf(field) {
+    const layout = field.layout;
+    if (layout === undefined)
+        return { kind: "scalar", type: field.type ?? "pointer" };
+    return record(layout, "field.layout");
+}
+function layoutSize(layout) {
+    const kind = String(layout.kind ?? "scalar");
+    if (kind === "scalar") {
+        const type = scalarType(layout.type, "layout.type");
+        const size = SCALAR_SIZES[type];
+        if (size === undefined)
+            return integer(layout.size, "layout.size", 16 * 1024 * 1024);
+        return size;
+    }
+    if (kind === "struct") {
+        let size = layout.size === undefined ? 0 : integer(layout.size, "struct.size");
+        const fields = record(layout.fields ?? {}, "struct.fields");
+        for (const value of Object.values(fields)) {
+            const field = record(value, "struct field");
+            const offset = integer(hex(field.offset, "field.offset"), "field.offset");
+            size = Math.max(size, offset + layoutSize(field.layout ? record(field.layout, "field.layout") : field));
+        }
+        return size;
+    }
+    if (kind === "array") {
+        const item = record(layout.item, "array.item");
+        const stride = integer(layout.stride ?? layoutSize(item), "array.stride");
+        const count = layout.count;
+        if (typeof count === "number" || typeof count === "string")
+            return stride * integer(count, "array.count", 100000);
+        return stride * integer(layout.maxItems, "array.maxItems", 100000);
+    }
+    if (kind === "linked_list") {
+        const item = record(layout.item, "linked_list.item");
+        return Math.max(layoutSize(item), integer(hex(layout.nextOffset ?? "0x8", "nextOffset"), "nextOffset") + 8);
+    }
+    throw new ProfileEngineError("PROFILE_INVALID", `unsupported layout kind ${kind}`);
+}
+function decodeScalar(type, bytes) {
+    switch (type) {
+        case "u8": return bytes.readUInt8(0);
+        case "i8": return bytes.readInt8(0);
+        case "u16": return bytes.readUInt16LE(0);
+        case "i16": return bytes.readInt16LE(0);
+        case "u32": return bytes.readUInt32LE(0);
+        case "i32": return bytes.readInt32LE(0);
+        case "u64": return hexText(bytes.readBigUInt64LE(0));
+        case "i64": return bytes.readBigInt64LE(0).toString();
+        case "f32": return bytes.readFloatLE(0);
+        case "f64": return bytes.readDoubleLE(0);
+        case "pointer": return hexText(bytes.readBigUInt64LE(0));
+        case "bytes": return bytes.toString("hex");
+        case "utf8": return bytes.toString("utf8").replace(/\0.*$/s, "");
+        case "utf16": return bytes.toString("utf16le").replace(/\0.*$/s, "");
+    }
+}
+function decodeInline(layout, bytes, base = 0) {
+    const kind = String(layout.kind ?? "scalar");
+    if (kind === "scalar") {
+        const type = scalarType(layout.type, "layout.type");
+        const size = SCALAR_SIZES[type] ?? integer(layout.size, "layout.size");
+        return decodeScalar(type, bytes.subarray(base, base + size));
+    }
+    if (kind === "struct") {
+        const result = {};
+        const fields = record(layout.fields ?? {}, "struct.fields");
+        for (const [name, value] of Object.entries(fields)) {
+            const field = record(value, `struct field ${name}`);
+            const offset = integer(hex(field.offset, `${name}.offset`), `${name}.offset`);
+            result[name] = decodeInline(field.layout ? record(field.layout, `${name}.layout`) : field, bytes, base + offset);
+        }
+        return result;
+    }
+    if (kind === "array") {
+        const item = record(layout.item, "array.item");
+        const stride = integer(layout.stride ?? layoutSize(item), "array.stride");
+        const count = integer(layout.count ?? layout.maxItems, "array.count", 100000);
+        return Array.from({ length: count }, (_, index) => decodeInline(item, bytes, base + index * stride));
+    }
+    throw new ProfileEngineError("PROFILE_INVALID", `inline layout ${kind} is not supported`);
+}
+function profileId(profile) {
+    return typeof profile.id === "string" && profile.id ? profile.id : String(profile.buildKey ?? "profile");
+}
+function rootSpec(value, name) {
+    const root = record(value, `${name}.root`);
+    if (root.rva === undefined && root.address === undefined)
+        throw new ProfileEngineError("PROFILE_INVALID", `${name}.root requires rva or address`);
+    return root;
+}
+export class ProfileEngine {
+    async read(request, adapter) {
+        const profile = record(request.profile, "profile");
+        const buildKey = String(profile.buildKey ?? "");
+        if (!buildKey)
+            throw new ProfileEngineError("PROFILE_INVALID", "profile.buildKey is required");
+        if (request.buildKey && request.buildKey !== buildKey) {
+            throw new ProfileEngineError("BUILD_MISMATCH", `profile build ${buildKey} does not match ${request.buildKey}`);
+        }
+        const status = String(profile.readerStatus ?? profile.status ?? (profile.confidence === "reader_ready" ? "reader_ready" : ""));
+        if (status !== "reader_ready")
+            throw new ProfileEngineError("PROFILE_NOT_READY", "profile is not reader_ready", { status });
+        const modules = await adapter.modules(request.pid);
+        const moduleSpec = profile.module && typeof profile.module === "object" ? record(profile.module, "profile.module") : {};
+        const moduleName = String(moduleSpec.name ?? profile.moduleName ?? "Wow.exe");
+        const module = modules.find(item => item.name.toLowerCase() === moduleName.toLowerCase());
+        if (!module)
+            throw new ProfileEngineError("MODULE_NOT_FOUND", `${moduleName} was not found`, { modules: modules.map(item => item.name) });
+        const definitions = record(profile.fields ?? profile.readers, "profile.fields");
+        const names = request.fields?.length ? [...request.fields] : Object.keys(definitions);
+        const fields = {};
+        const reads = [];
+        for (const name of names) {
+            const definition = record(definitions[name], `field ${name}`);
+            fields[name] = await this.readField(request.pid, hex(module.base, "module.base"), name, definition, adapter, reads);
+        }
+        return { ok: true, command: "profile.read", pid: request.pid, buildKey, profileId: profileId(profile), module, fields, reads };
+    }
+    async readField(pid, moduleBase, fieldName, definition, adapter, reads) {
+        let address = definition.root === undefined ? moduleBase : await this.resolveRoot(pid, moduleBase, rootSpec(definition.root, fieldName), adapter, fieldName, reads);
+        const chainValue = definition.pointerChain ?? definition.chain;
+        const chain = Array.isArray(chainValue) ? chainValue : [];
+        for (const value of chain) {
+            const step = record(value, `${fieldName}.pointerChain`);
+            address += hex(step.offset ?? "0x0", `${fieldName}.pointerChain.offset`);
+            if (step.dereference === false)
+                continue;
+            const pointer = await this.readBytes(pid, address, 8, fieldName, adapter, reads);
+            address = BigInt(`0x${pointer.toString("hex").match(/../g).reverse().join("")}`);
+            const mask = step.mask === undefined ? 0n : hex(step.mask, `${fieldName}.pointerChain.mask`);
+            if (mask)
+                address &= mask;
+            if (address === 0n)
+                throw new ProfileEngineError("NULL_POINTER", `${fieldName} resolved to a null pointer`);
+        }
+        return this.readLayout(pid, address, layoutOf(definition), fieldName, adapter, reads);
+    }
+    async resolveRoot(pid, moduleBase, root, adapter, field, reads) {
+        let address = root.address === undefined ? moduleBase + hex(root.rva, `${field}.root.rva`) : hex(root.address, `${field}.root.address`);
+        if (root.dereference === true) {
+            const bytes = await this.readBytes(pid, address, 8, field, adapter, reads);
+            address = BigInt(`0x${bytes.toString("hex").match(/../g).reverse().join("")}`);
+        }
+        return address;
+    }
+    async readLayout(pid, address, layout, field, adapter, reads) {
+        const kind = String(layout.kind ?? "scalar");
+        if (kind === "linked_list") {
+            const item = record(layout.item, `${field}.item`);
+            const nextOffset = integer(hex(layout.nextOffset ?? "0x8", `${field}.nextOffset`), `${field}.nextOffset`);
+            const itemSize = Math.max(layoutSize(item), nextOffset + 8);
+            const maxItems = integer(layout.maxItems ?? 64, `${field}.maxItems`, 100000);
+            const values = [];
+            const seen = new Set();
+            while (address !== 0n && values.length < maxItems) {
+                const key = hexText(address);
+                if (seen.has(key))
+                    throw new ProfileEngineError("POINTER_CYCLE", `${field} linked list contains a cycle`, { address: key });
+                seen.add(key);
+                if (layout.stopOnTagged !== false && (address & 1n) !== 0n)
+                    break;
+                const bytes = await this.readBytes(pid, address, itemSize, field, adapter, reads);
+                values.push(decodeInline(item, bytes));
+                const nextBytes = bytes.subarray(nextOffset, nextOffset + 8);
+                address = nextBytes.length < 8 ? 0n : BigInt(`0x${nextBytes.toString("hex").match(/../g).reverse().join("")}`);
+            }
+            return values;
+        }
+        const size = layout.kind === "scalar" && layout.type && SCALAR_SIZES[scalarType(layout.type, `${field}.type`)] === undefined
+            ? integer(layout.size, `${field}.size`)
+            : layoutSize(layout);
+        const bytes = await this.readBytes(pid, address, size, field, adapter, reads);
+        if (kind === "array" && layout.count === undefined && layout.maxItems !== undefined) {
+            const item = record(layout.item, `${field}.item`);
+            const stride = integer(layout.stride ?? layoutSize(item), `${field}.stride`);
+            const count = integer(layout.maxItems, `${field}.maxItems`, 100000);
+            return Array.from({ length: count }, (_, index) => decodeInline(item, bytes, index * stride));
+        }
+        return decodeInline(layout, bytes);
+    }
+    async readBytes(pid, address, size, field, adapter, reads) {
+        const result = await adapter.read(pid, hexText(address), size);
+        if (!result.ok || typeof result.dataHex !== "string")
+            throw new ProfileEngineError("READ_FAILED", `${field} read failed`, { address: hexText(address), size, error: result.error ?? null });
+        const bytesRead = Number(result.bytesRead ?? result.dataHex.length / 2);
+        const bytes = Buffer.from(result.dataHex, "hex");
+        reads.push({ field, address: hexText(address), size, bytesRead, dataHex: result.dataHex, complete: result.complete === true && bytesRead === size });
+        if (bytesRead !== size || bytes.length < size)
+            throw new ProfileEngineError("PARTIAL_READ", `${field} read was incomplete`, { address: hexText(address), size, bytesRead });
+        return bytes.subarray(0, size);
+    }
+}

package/dist/frida-worker.js

@@ -0,0 +1,99 @@
+import { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { FridaCommandRuntime } from "./analysis/frida-runtime.js";
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function positive(value, name) {
+    const number = Number(value);
+    if (!Number.isSafeInteger(number) || number < 1)
+        throw new Error(`${name} must be a positive integer`);
+    return number;
+}
+/**
+ * Elevated Frida execution boundary. Analysis belongs to the caller-supplied
+ * GumJS source; this process only attaches, loads, calls, and cleans it up.
+ */
+async function run(input) {
+    if (input.command !== "dynamic-script")
+        throw new Error("unsupported worker command");
+    const pid = positive(input.pid, "pid");
+    const buildKey = String(input.build ?? input.buildKey ?? "").trim();
+    if (!buildKey)
+        throw new Error("build is required");
+    const source = typeof input.source === "string"
+        ? input.source
+        : typeof input.script === "string" ? await readFile(input.script, "utf8") : "";
+    if (!source.trim())
+        throw new Error("script or source is required");
+    const runtime = new FridaCommandRuntime({ artifactDir: process.env.WOW_ANALYZE_DIR });
+    let sessionId;
+    let loaded = false;
+    try {
+        const attached = await runtime.execute({ operation: "attach", pid, buildKey, allowUnmatched: true });
+        sessionId = String(attached.sessionId);
+        const modules = await runtime.execute({ operation: "modules", sessionId, pid, buildKey });
+        const module = Array.isArray(modules.modules)
+            ? modules.modules.find(item => String(item.name ?? "").toLowerCase() === "wow.exe")
+            : undefined;
+        await runtime.execute({
+            operation: "script_load",
+            sessionId,
+            pid,
+            buildKey,
+            source: `globalThis.__WOWDUMP_INPUT__ = Object.freeze(${JSON.stringify(input.args ?? {})});\n${source}`,
+            scriptId: "dynamic"
+        });
+        loaded = true;
+        let value;
+        let messages = [];
+        if (typeof input.exportName === "string" && input.exportName.trim()) {
+            const called = await runtime.execute({
+                operation: "script_call",
+                sessionId,
+                scriptId: "dynamic",
+                exportName: input.exportName,
+                args: Array.isArray(input.callArgs) ? input.callArgs : []
+            });
+            value = called.value;
+            messages = Array.isArray(called.messages) ? called.messages : [];
+        }
+        const durationMs = Math.min(120_000, positive(input.durationMs ?? 100, "duration-ms"));
+        if (value === undefined)
+            await new Promise(resolve => setTimeout(resolve, durationMs));
+        return {
+            ok: true,
+            command: "analyze.dynamic",
+            pid,
+            buildKey,
+            module: module && typeof module.base === "string"
+                ? { name: module.name, moduleBase: module.base, moduleSize: module.size ?? null }
+                : null,
+            exportName: typeof input.exportName === "string" ? input.exportName : null,
+            value,
+            messages,
+            script: typeof input.script === "string" ? input.script : "<inline>",
+            evidence: [{ kind: "frida-gumjs", source: "frida", moduleBase: module?.base ?? null }]
+        };
+    }
+    finally {
+        if (sessionId && loaded)
+            await runtime.execute({ operation: "script_unload", sessionId, scriptId: "dynamic" }).catch(() => undefined);
+        await runtime.close();
+    }
+}
+const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
+let failed = false;
+for await (const line of input) {
+    if (!line.trim())
+        continue;
+    try {
+        process.stdout.write(`${JSON.stringify(await run(record(JSON.parse(line))))}\n`);
+    }
+    catch (error) {
+        failed = true;
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+if (failed)
+    process.exitCode = 1;