wowdump 0.3.1 → 0.3.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Follen
-
-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.
+MIT License
+
+Copyright (c) 2026 Follen
+
+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

@@ -1,70 +1,38 @@
 # wowdump
 
-Node/TypeScript WoW native-memory analysis framework. The normal entry point is
-the `wowdump` CLI; MCP and Frida remain optional integration paths.
+WoW 原生内存分析 CLI。用 Frida 运行时证据和 IDA Pro/iced-x86 局部反汇编定位字段，生成可复核的 Reader profile。
 
-## Run
+## 安装
 
 ```powershell
-npm install
-npm run build
-$env:WOWDUMP_HOME='C:\Users\follen\.wowdump'
-wowdump --help
+npm install --global wowdump
 wowdump init
-$env:WOW_ROOT='D:\Game\World of Warcraft'
-npm run discover
-npm run dry-run
-npm start
 ```
 
-`npm install` initializes `WOWDUMP_HOME`, installs the `wowdump` Skill and its
-`commands.md` reference under `%USERPROFILE%\.agents\skills\wowdump`, and detects
-an existing Java/Ghidra installation. If either tool is missing, the postinstall
-bootstrap prepares a pinned copy under `%WOWDUMP_HOME%\toolchains` (set
-`WOWDUMP_SKIP_TOOLCHAIN_DOWNLOAD=1` to skip downloads and configure paths
-manually). Use `WOWDUMP_SKILL_HOME` to choose another Skill root.
-
-## Analysis CLI
+安装脚本会初始化 `~/.wowdump`，并把 Skill 与 references 参考文档安装到 `~/.agents/skills/wowdump`。反汇编保底使用 npm 内置的 `iced-x86`。
 
-Static analysis is the default analysis path and runs Ghidra Headless against a
-disk executable. It does not attach to a running game or require elevation:
+## 基本流程
 
 ```powershell
-wowdump analyze static --exe "D:\Game\World of Warcraft\_retail_\Wow.exe" `
-  --build "retail@12.1.0.69587" --output "$env:USERPROFILE\.wowdump\profiles\69587\profile.json"
-```
+# 1. 导出运行时模块或 provider
+wowdump analyze runtime --pid 1234 --build "retail@VERSION" --kind text --duration-ms 5000 --max-events 100 --confirm > runtime.json
 
-Runtime export is a separate, explicitly confirmed Frida-worker operation:
-
-```powershell
-wowdump analyze runtime-export --pid 1234 --build "retail@VERSION" `
-  --static-profile .wowdump\profiles\static.json --kind providers --confirm
-wowdump analyze verify --static-profile .wowdump\profiles\static.json `
-  --runtime-export .wowdump\runtime\export.json
-```
-
-The static profile supplies candidate RVAs. The runtime export records the live
-module base and `runtimeAddress = moduleBase + rva`; after verification, persist
-only the passing records in a `reader_ready` profile and use the reader for
-subsequent polling.
+# 2. 通过 IDA Pro MCP（若可用）或 iced-x86 局部反汇编生成 profile
+wowdump analyze disassemble --exe "C:\Games\World of Warcraft\_retail_\Wow.exe" --build "retail@VERSION" --runtime-export "$HOME\.wowdump\runtime\<session-id>\text.json" --output "$HOME\.wowdump\runtime\<session-id>\candidate.profile.json"
 
-The CLI also exposes `target`, `profiles`, `memory read`, and `memory watch`.
-Those commands use an isolated reader broker. The broker performs one elevated
-launch through Node's `ShellExecuteExW(..., "runas", ...)`, then listens only on
-`127.0.0.1` behind a random 256-bit token. Later CLI processes reuse the same
-broker and monitor state until 20 minutes of idle time elapse. No PowerShell
-script or native reader command is a user entry point.
+# 3. 用户确认后，把 profile 保存到当前 build 的 profile 目录，再读取
+wowdump memory read --pid 1234 --profile "$HOME\.wowdump\retail@VERSION\profile\player-state.json" --field playerAuras
+```
 
-The root `.build.info` is read from the parent game directory and associated with
-each `_retail_`, `_beta_`, `_classic_`, and other directory containing `Wow.exe`.
-The collector polls `Wow.exe` processes, matches each executable path to its
-install, and creates one Frida session per PID.
+Windows reader 首次使用时由 Node 请求 UAC 启动 broker，后续调用复用同一 broker，空闲 20 分钟后退出。Frida 运行时导出需要显式 `--confirm`；高开销 Stalker 默认关闭。
 
-`npm run dry-run` performs one process scan and prints a JSON report without
-loading the Frida session or writing `errors.jsonl`. Each discovered install and
-live process includes its `flavor`, `buildKey`, and `adapterStatus`. Builds with
-no verified adapter are reported as `unsupported` with an `adapterReason`.
+当前 build 的持久化 profile 放在 `~/.wowdump/<buildKey>/profile/`；动态导出、静态候选和验证报告放在 runtime 会话临时目录。完整字段和 JSON 约定见 `~/.agents/skills/wowdump/references/commands.md`、`references/request-schema.md` 与 `references/profiles.md`；短时 Hook 示例见 `~/.agents/skills/wowdump/scripts/dynamic-session.js`。
 
-Run the regression suite with `npm test`. It covers build-info discovery,
-adapter lookup, dry-run formatting, and CIM process-row parsing.
+## 开发验证
 
+```powershell
+npm run typecheck
+npm run build
+npm test
+npm pack --dry-run
+```

package/dist/adapters/reader.js

@@ -0,0 +1,33 @@
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+/** Adapts the elevated reader broker to ProfileEngine's minimal memory API. */
+export class ReaderProfileAdapter {
+    invoke;
+    constructor(invoke) {
+        this.invoke = invoke;
+    }
+    async modules(pid) {
+        const response = record(await this.invoke({ command: "modules", payload: { pid } }));
+        if (response.ok !== true)
+            throw new Error(String(record(response.error).message ?? "module enumeration failed"));
+        const values = Array.isArray(response.modules) ? response.modules : [];
+        return values.filter(value => value && typeof value === "object").map(value => {
+            const item = value;
+            return { name: String(item.name ?? ""), base: String(item.base ?? "0x0"), ...(item.size !== undefined ? { size: Number(item.size) } : {}), ...(item.path !== undefined ? { path: String(item.path) } : {}) };
+        });
+    }
+    async read(pid, address, size) {
+        const response = record(await this.invoke({ command: "read", payload: { pid, address, size } }));
+        const error = response.error;
+        return {
+            ok: response.ok === true,
+            address: typeof response.address === "string" ? response.address : address,
+            requestedSize: Number(response.requestedSize ?? size),
+            bytesRead: Number(response.bytesRead ?? 0),
+            dataHex: typeof response.dataHex === "string" ? response.dataHex : undefined,
+            complete: response.complete === true,
+            ...(error !== undefined ? { error } : {})
+        };
+    }
+}

package/dist/analysis/disassemble.js

@@ -0,0 +1,77 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { resolve } from "node:path";
+import { Decoder, DecoderOptions, Formatter, FormatterSyntax } from "iced-x86";
+import { inspectPeSections, sha256File } from "../toolchain.js";
+function record(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : {}; }
+function array(value) { return Array.isArray(value) ? value.filter(item => item && typeof item === "object" && !Array.isArray(item)) : []; }
+function hex(value) { if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0)
+    return BigInt(value); if (typeof value === "string" && /^0x[0-9a-f]+$/i.test(value.trim()))
+    return BigInt(value); return undefined; }
+function hexText(value) { return `0x${value.toString(16)}`; }
+function moduleInfo(runtime) { const module = record(runtime.module); const base = hex(module.moduleBase ?? module.base ?? runtime.moduleBase) ?? 0n; const size = Number(module.moduleSize ?? module.size ?? runtime.moduleSize ?? 0); return { base, size: Number.isFinite(size) ? size : 0, name: String(module.name ?? "Wow.exe") }; }
+function sampleBytes(item) { const value = item.bytesHex ?? item.dataHex; if (typeof value !== "string" || !/^[0-9a-f]*$/i.test(value) || value.length % 2 !== 0)
+    return undefined; return Buffer.from(value, "hex"); }
+function sampleRva(item) { return hex(item.rva) ?? (hex(item.address) !== undefined ? hex(item.address) : undefined); }
+function decodeSamples(runtime, maxInstructions) {
+    const info = moduleInfo(runtime);
+    const samples = [...array(runtime.samples), ...array(runtime.records)];
+    const formatter = new Formatter(FormatterSyntax.Masm);
+    const output = [];
+    let remaining = maxInstructions;
+    for (const sample of samples) {
+        if (remaining <= 0)
+            break;
+        const bytes = sampleBytes(sample);
+        const raw = sampleRva(sample);
+        if (!bytes || raw === undefined)
+            continue;
+        const rva = raw >= info.base && info.base > 0n ? raw - info.base : raw;
+        const ip = info.base + rva;
+        const decoder = new Decoder(64, bytes, DecoderOptions.None);
+        decoder.ip = ip;
+        const instructions = [];
+        while (remaining > 0 && decoder.canDecode) {
+            const instruction = decoder.decode();
+            if (instruction.code === 0)
+                break;
+            instructions.push(formatter.format(instruction));
+            remaining--;
+        }
+        output.push({ rva: hexText(rva), address: hexText(ip), bytesHex: bytes.toString("hex"), instructions, source: "frida-text" });
+    }
+    return output;
+}
+function fieldCandidates(runtime, ida) {
+    const candidates = {};
+    const source = { ...record(runtime.fields), ...record(ida.fields) };
+    for (const [name, value] of Object.entries(source)) {
+        const item = record(value);
+        const rva = item.rva ?? record(item.root).rva;
+        const type = item.type ?? (record(item.layout).type);
+        const layout = item.layout;
+        if (rva !== undefined && (typeof type === "string" || (layout && typeof layout === "object" && !Array.isArray(layout))))
+            candidates[name] = { ...item, root: item.root ?? { rva }, ...(type ? { type } : {}), evidence: [...array(item.evidence), { source: ida && Object.keys(ida).length ? "ida-pro-mcp" : "iced-x86", kind: "runtime-guided" }] };
+    }
+    return candidates;
+}
+export async function runDisassembly(options) {
+    const executable = resolve(options.exe);
+    await access(executable, constants.R_OK);
+    if (!options.buildKey?.trim())
+        throw new Error("buildKey is required");
+    const runtime = record(JSON.parse(await readFile(resolve(options.runtimeExport), "utf8")));
+    const ida = options.idaEvidence ? record(JSON.parse(await readFile(resolve(options.idaEvidence), "utf8"))) : {};
+    const info = moduleInfo(runtime);
+    const decoded = decodeSamples(runtime, Math.min(Math.max(options.maxInstructions ?? 256, 1), 10_000));
+    const sections = inspectPeSections(await readFile(executable));
+    const fields = fieldCandidates(runtime, ida);
+    const ready = Object.keys(fields).length > 0 && Object.values(fields).every(field => { const value = record(field); return value.root !== undefined && (value.type !== undefined || value.layout !== undefined); });
+    const outputFile = resolve(options.output ?? `${executable}.${options.buildKey.replace(/[^A-Za-z0-9_.@-]+/g, "-")}.profile.json`);
+    const profile = { schema: "wowdump.profile.v1", id: `${options.buildKey}-runtime`, buildKey: options.buildKey, readerStatus: ready ? "reader_ready" : "candidate", confidence: ready ? "confirmed" : "candidate", module: { name: info.name, rvaBase: "0x0" }, executable: { path: executable, sha256: await sha256File(executable) }, sections, fields, evidence: [{ source: "frida", kind: "runtime-text", samples: decoded.length }, { source: options.idaEvidence ? "ida-pro-mcp" : "iced-x86", kind: "disassembly", instructions: decoded.length }], analysis: { engine: options.idaEvidence ? "ida-pro-mcp+iced-x86" : "iced-x86", generatedAt: new Date().toISOString() } };
+    const disassembly = { module: { name: info.name, moduleBase: hexText(info.base), moduleSize: info.size }, sections, instructions: decoded, idaEvidence: options.idaEvidence ?? null };
+    if (!options.dryRun)
+        await writeFile(outputFile, `${JSON.stringify(profile, null, 2)}\n`, "utf8");
+    return { ok: true, command: "analyze.disassemble", engine: options.idaEvidence ? "ida-pro-mcp" : "iced-x86", buildKey: options.buildKey, executable, outputFile, profile, disassembly };
+}

package/dist/{frida-runtime.js → analysis/frida-runtime.js}

@@ -9,54 +9,54 @@ const DEFAULT_SCRIPT_TIMEOUT_MS = 150;
  * `script_load` still accept native GumJS, so a new WoW build can use any
  * Frida API without requiring a host release for every new command.
  */
-const BRIDGE_SOURCE = String.raw `
-function __wowBytes(value) {
-  return value == null ? [] : Array.from(new Uint8Array(value));
-}
-function __wowModule(value) {
-  return { name: value.name, base: value.base.toString(), size: value.size, path: value.path };
-}
-function __wowExport(value) {
-  return { type: value.type, name: value.name, address: value.address.toString(), moduleName: value.moduleName };
-}
-function __wowRange(value) {
-  return { base: value.base.toString(), size: value.size, protection: value.protection, file: value.file ?? null };
-}
-rpc.exports = {
-  enumerateModules() {
-    return Process.enumerateModules().map(__wowModule);
-  },
-  enumerateExports(moduleName) {
-    const module = Process.getModuleByName(moduleName);
-    return module.enumerateExports().map(__wowExport);
-  },
-  enumerateRanges(protection, coalesce) {
-    try {
-      return Process.enumerateRanges({ protection: protection || "r--", coalesce: Boolean(coalesce) }).map(__wowRange);
-    } catch (_) {
-      return Process.enumerateRanges(protection || "r--").map(__wowRange);
-    }
-  },
-  readMemory(address, size) {
-    return __wowBytes(ptr(address).readByteArray(size));
-  },
-  writeMemory(address, bytes) {
-    const target = ptr(address);
-    const input = Uint8Array.from(bytes || []);
-    const before = __wowBytes(target.readByteArray(input.byteLength));
-    target.writeByteArray(input.buffer);
-    return { before, after: Array.from(input), address: target.toString(), size: input.byteLength };
-  },
-  protectMemory(address, size, protection) {
-    const changed = Memory.protect(ptr(address), size, protection);
-    return { address: ptr(address).toString(), size, protection, changed };
-  },
-  scanMemory(address, size, pattern) {
-    return Memory.scanSync(ptr(address), size, pattern).map(match => ({
-      address: match.address.toString(), size: match.size
-    }));
-  }
-};
+const BRIDGE_SOURCE = String.raw `
+function __wowBytes(value) {
+  return value == null ? [] : Array.from(new Uint8Array(value));
+}
+function __wowModule(value) {
+  return { name: value.name, base: value.base.toString(), size: value.size, path: value.path };
+}
+function __wowExport(value) {
+  return { type: value.type, name: value.name, address: value.address.toString(), moduleName: value.moduleName };
+}
+function __wowRange(value) {
+  return { base: value.base.toString(), size: value.size, protection: value.protection, file: value.file ?? null };
+}
+rpc.exports = {
+  enumerateModules() {
+    return Process.enumerateModules().map(__wowModule);
+  },
+  enumerateExports(moduleName) {
+    const module = Process.getModuleByName(moduleName);
+    return module.enumerateExports().map(__wowExport);
+  },
+  enumerateRanges(protection, coalesce) {
+    try {
+      return Process.enumerateRanges({ protection: protection || "r--", coalesce: Boolean(coalesce) }).map(__wowRange);
+    } catch (_) {
+      return Process.enumerateRanges(protection || "r--").map(__wowRange);
+    }
+  },
+  readMemory(address, size) {
+    return __wowBytes(ptr(address).readByteArray(size));
+  },
+  writeMemory(address, bytes) {
+    const target = ptr(address);
+    const input = Uint8Array.from(bytes || []);
+    const before = __wowBytes(target.readByteArray(input.byteLength));
+    target.writeByteArray(input.buffer);
+    return { before, after: Array.from(input), address: target.toString(), size: input.byteLength };
+  },
+  protectMemory(address, size, protection) {
+    const changed = Memory.protect(ptr(address), size, protection);
+    return { address: ptr(address).toString(), size, protection, changed };
+  },
+  scanMemory(address, size, pattern) {
+    return Memory.scanSync(ptr(address), size, pattern).map(match => ({
+      address: match.address.toString(), size: match.size
+    }));
+  }
+};
 `;
 function asRecord(value) {
     return value && typeof value === "object" ? value : {};

package/dist/analysis/runtime-script.js

@@ -0,0 +1,36 @@
+/** Built-in bounded sampler used by `analyze runtime`; dynamic stays caller-owned. */
+export const RUNTIME_EXPORT_SCRIPT = String.raw `
+"use strict";
+const input = globalThis.__WOWDUMP_INPUT__ || {};
+const moduleName = typeof input.module === "string" && input.module ? input.module : "Wow.exe";
+const module = Process.findModuleByName(moduleName);
+const limit = Math.min(Math.max(Number(input.maxEvents || 16), 1), 256);
+const sampleBytes = Math.min(Math.max(Number(input.sampleBytes || 64), 1), 256);
+function bytes(address, size) { const value = address.readByteArray(size); return value ? Array.from(new Uint8Array(value), byte => byte.toString(16).padStart(2, "0")).join("") : ""; }
+function collect() {
+  if (!module) return { ok: false, module: { name: moduleName }, records: [], evidence: [{ source: "frida", kind: "module-missing" }] };
+  if (input.kind === "text") {
+    const ranges = Process.enumerateRanges("r-x").filter(range => range.base.compare(module.base) >= 0 && range.base.compare(module.base.add(module.size)) < 0);
+    const textRanges = ranges.map(range => ({ base: range.base.toString(), rva: range.base.sub(module.base).toString(), size: range.size, protection: range.protection }));
+    const records = [];
+    for (const range of ranges) {
+      if (records.length >= limit) break;
+      const rva = range.base.sub(module.base);
+      const offset = rva.isNull() && range.size > 0x1000 ? 0x1000 : 0;
+      const address = range.base.add(offset);
+      records.push({ address: address.toString(), rva: address.sub(module.base).toString(), size: Math.min(sampleBytes, range.size - offset), bytesHex: bytes(address, Math.min(sampleBytes, range.size - offset)) });
+    }
+    return { ok: true, kind: "text", module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size }, textRanges, samples: records, records, evidence: [{ source: "frida", kind: "frida-runtime-text", samples: records.length }] };
+  }
+  const profile = input.profile && typeof input.profile === "object" ? input.profile : {};
+  const candidates = Array.isArray(profile.providers) ? profile.providers : [];
+  const records = [];
+  for (const candidate of candidates.slice(0, limit)) {
+    if (!candidate || typeof candidate.rva !== "string") continue;
+    const address = module.base.add(ptr(candidate.rva));
+    records.push({ name: candidate.name || "candidate", rva: candidate.rva, runtimeAddress: address.toString(), bytesHex: bytes(address, Math.min(Number(candidate.size || 16), 256)), source: "frida" });
+  }
+  return { ok: true, module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size }, records, evidence: [{ source: "frida", kind: "frida-runtime-read", count: records.length }] };
+}
+rpc.exports = { collect };
+`;