wowdump 0.3.2 → 0.3.4

package/dist/cli.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { existsSync, realpathSync, readFileSync } from "node:fs";
-import { readFile, readdir } from "node:fs/promises";
+import { mkdir, open, readFile, readdir, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Command } from "commander";
 import { WindowsBrokerManager } from "./reader/launcher.js";
-import { initializeWowdumpHome, bootstrapToolchain, resolveToolchain, resolveWowdumpHome } from "./toolchain.js";
-import { runDisassembly } from "./analysis/disassemble.js";
+import { initializeWowdumpHome, bootstrapToolchain, resolveToolchain } from "./toolchain.js";
+import { buildPaths, databaseStatus, ensureBuild, findReusableDump, readBuild, resolveWowdumpHome, safeBuildKey, sha256File } from "./core/build-store.js";
 import { RUNTIME_EXPORT_SCRIPT } from "./analysis/runtime-script.js";
 import { ProfileEngine } from "./core/profile-engine.js";
 import { ReaderProfileAdapter } from "./adapters/reader.js";
@@ -85,6 +86,64 @@ async function discoverWowTargets(selectedPid, elevatedModules) {
     }
     return targets;
 }
+async function preferredImageBase(file) {
+    let handle;
+    try {
+        handle = await open(file, "r");
+        const header = Buffer.alloc(64 * 1024);
+        await handle.read(header, 0, header.length, 0);
+        if (header.length < 0x40 || header.readUInt16LE(0) !== 0x5a4d)
+            return null;
+        const peOffset = header.readUInt32LE(0x3c);
+        if (peOffset + 0x58 > header.length || header.readUInt32LE(peOffset) !== 0x00004550)
+            return null;
+        const optional = peOffset + 24;
+        const magic = header.readUInt16LE(optional);
+        if (magic === 0x20b)
+            return `0x${header.readBigUInt64LE(optional + 24).toString(16)}`;
+        if (magic === 0x10b)
+            return `0x${BigInt(header.readUInt32LE(optional + 28)).toString(16)}`;
+        return null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (handle)
+            await handle.close().catch(() => undefined);
+    }
+}
+async function persistDiscoveredBuilds(home, targets) {
+    for (const target of targets) {
+        const path = typeof target.path === "string" ? target.path : null;
+        const buildKey = typeof target.buildKey === "string" ? target.buildKey : null;
+        if (!path || !buildKey)
+            continue;
+        try {
+            const executableSha256 = await sha256File(path);
+            const imageBase = await preferredImageBase(path);
+            const result = await ensureBuild(home, {
+                buildKey: safeBuildKey(buildKey),
+                executablePath: path,
+                executableSha256,
+                preferredImageBase: imageBase,
+                moduleSize: Number.isSafeInteger(Number(target.moduleSize)) ? Number(target.moduleSize) : null
+            });
+            target.executableSha256 = executableSha256;
+            target.preferredImageBase = imageBase;
+            target.database = {
+                directory: buildPaths(home, buildKey).database,
+                path: buildPaths(home, buildKey).databaseFile,
+                status: result.database.status,
+                reused: result.reused
+            };
+        }
+        catch (error) {
+            target.diagnostics = { ...(target.diagnostics && typeof target.diagnostics === "object" ? target.diagnostics : {}), buildStore: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    return targets;
+}
 function packageVersion() {
     const override = process.env.WOWDUMP_VERSION?.trim();
     if (override)
@@ -248,7 +307,7 @@ function selected(source, keys) {
 function requireRuntimeConfirmation(options) {
     if (options.confirm === true)
         return;
-    throw new CliError("CONFIRMATION_REQUIRED", "runtime export requires --confirm", {
+    throw new CliError("CONFIRMATION_REQUIRED", "runtime analysis requires --confirm", {
         pid: options.pid,
         buildKey: options.build,
         operation: "runtime",
@@ -259,6 +318,37 @@ function requireRuntimeConfirmation(options) {
         cleanupDeadlineMs: options.cleanupDeadlineMs
     });
 }
+function profileDirectoryFor(home, buildKey) {
+    if (!buildKey)
+        throw new CliError("BUILD_REQUIRED", "a build key is required to resolve the profile directory");
+    return buildPaths(home, safeBuildDirectory(buildKey)).profile;
+}
+async function validateProfileIdentity(home, buildKey, profile, file) {
+    if (!buildKey)
+        return;
+    if (typeof profile.buildKey === "string" && profile.buildKey !== buildKey) {
+        throw new CliError("BUILD_MISMATCH", `profile build ${profile.buildKey} does not match ${buildKey}`, { profileFile: file });
+    }
+    const build = await readBuild(home, buildKey);
+    if (!build)
+        return;
+    const profileHash = typeof profile.executableSha256 === "string"
+        ? profile.executableSha256
+        : profile.executable && typeof profile.executable === "object" && !Array.isArray(profile.executable)
+            ? String(profile.executable.sha256 ?? "")
+            : "";
+    if (profileHash && profileHash !== build.executableSha256) {
+        throw new CliError("EXECUTABLE_MISMATCH", "profile executable hash does not match the selected build", { expected: build.executableSha256, actual: profileHash, profileFile: file });
+    }
+}
+function safeBuildDirectory(buildKey) {
+    try {
+        return safeBuildKey(buildKey);
+    }
+    catch {
+        throw new CliError("ARGUMENT_INVALID", "build key contains unsupported path characters");
+    }
+}
 export function createWowdumpCli(dependencies = {}) {
     const io = dependencies.io ?? { stdout: process.stdout, stderr: process.stderr };
     const env = dependencies.env ?? process.env;
@@ -288,7 +378,7 @@ export function createWowdumpCli(dependencies = {}) {
         .option("--pid <pid>", "select one process ID")
         .action(async (options) => {
         const selectedPid = options.pid ? positiveInteger(options.pid, "pid") : undefined;
-        const targets = await discoverWowTargets(selectedPid, async (pid) => broker({ command: "modules", payload: { pid } }));
+        const targets = await persistDiscoveredBuilds(home, await discoverWowTargets(selectedPid, async (pid) => broker({ command: "modules", payload: { pid } })));
         if (selectedPid !== undefined && targets.length === 0)
             throw new CliError("TARGET_NOT_FOUND", `Wow.exe process ${selectedPid} was not found`);
         writeJson(io, {
@@ -299,6 +389,14 @@ export function createWowdumpCli(dependencies = {}) {
             targets
         });
     });
+    program.command("database")
+        .description("Show the persistent static database state for a build")
+        .command("status")
+        .description("Show database path, lock and freshness")
+        .requiredOption("--build <buildKey>", "build key")
+        .action(async (options) => {
+        writeJson(io, { ...await databaseStatus(home, options.build), command: "database.status" });
+    });
     program.command("target")
         .description("Show target, reader broker, profile, monitor, and Frida state")
         .option("--pid <pid>", "target process ID")
@@ -314,9 +412,10 @@ export function createWowdumpCli(dependencies = {}) {
     program.command("profiles")
         .description("List profiles or describe one profile")
         .argument("[id-or-file]", "profile ID or absolute JSON file")
-        .option("--directory <path>", "profile directory", join(home, "profiles"))
+        .option("--build <buildKey>", "build key used for the default profile directory")
+        .option("--directory <path>", "profile directory")
         .action(async (idOrFile, options) => {
-        const directory = resolve(options.directory);
+        const directory = resolve(options.directory ?? profileDirectoryFor(home, options.build));
         if (idOrFile) {
             const file = profileFile(directory, idOrFile);
             const profile = jsonRecord(await readFile(file, "utf8"), file);
@@ -347,13 +446,27 @@ export function createWowdumpCli(dependencies = {}) {
             ...(options.size ? { size: positiveInteger(options.size, "size") } : {})
         };
         const pid = positiveInteger(String(payload.pid ?? options.pid), "pid");
-        const profileId = typeof payload.profileId === "string" ? payload.profileId : (typeof options.profile === "string" ? options.profile : undefined);
+        let profileId = typeof payload.profileId === "string" ? payload.profileId : (typeof options.profile === "string" ? options.profile : undefined);
+        const requestedBuild = typeof payload.buildKey === "string" ? payload.buildKey : (typeof options.build === "string" ? options.build : undefined);
+        if (!profileId && payload.address === undefined && requestedBuild) {
+            const available = await listProfileFiles(profileDirectoryFor(home, requestedBuild));
+            if (available.length === 1)
+                profileId = basename(available[0], extname(available[0]));
+            else if (available.length === 0)
+                throw new CliError("PROFILE_NOT_FOUND", `no profile exists for build ${requestedBuild}`, { directory: profileDirectoryFor(home, requestedBuild) });
+            else
+                throw new CliError("PROFILE_SELECTION_REQUIRED", `more than one profile exists for build ${requestedBuild}`, { profiles: available });
+        }
         if (profileId && payload.address === undefined) {
-            const profileFilePath = profileFile(join(home, "profiles"), profileId);
+            const buildKey = requestedBuild;
+            const profileFilePath = profileFile(isAbsolute(profileId) ? dirname(profileId) : profileDirectoryFor(home, buildKey), profileId);
             const profile = jsonRecord(await readFile(profileFilePath, "utf8"), profileFilePath);
+            await validateProfileIdentity(home, buildKey, profile, profileFilePath);
+            const buildRecord = buildKey ? await readBuild(home, buildKey) : null;
             const result = await profileEngine.read({
                 pid,
-                buildKey: typeof payload.buildKey === "string" ? payload.buildKey : undefined,
+                buildKey,
+                ...(buildRecord?.executableSha256 ? { executableSha256: buildRecord.executableSha256 } : {}),
                 profile,
                 fields: Array.isArray(payload.fields) ? payload.fields.map(String) : undefined
             }, profileAdapter);
@@ -401,34 +514,23 @@ export function createWowdumpCli(dependencies = {}) {
         .description("Stop a monitor and release its resources")
         .requiredOption("--id <watchId>", "monitor ID")
         .action(async (options) => writeJson(io, await broker({ command: "watch.stop", payload: { watchId: options.id } })));
-    const analyze = program.command("analyze").description("Run Frida evidence export and runtime-guided disassembly");
-    analyze.command("disassemble")
-        .description("Decode Frida text evidence and produce a Reader profile")
-        .requiredOption("--exe <path>", "path to Wow.exe")
-        .requiredOption("--build <buildKey>", "build key")
-        .requiredOption("--runtime-export <file>", "Frida runtime text JSON")
-        .option("--ida-evidence <file>", "JSON produced by an IDA Pro MCP analysis")
-        .option("--output <file>", "profile output JSON")
-        .option("--max-instructions <count>", "maximum decoded instructions", "256")
-        .option("--dry-run", "validate inputs without writing a profile")
-        .action(async (options) => writeJson(io, await runDisassembly({
-        exe: options.exe,
-        buildKey: options.build,
-        runtimeExport: options.runtimeExport,
-        ...(options.idaEvidence ? { idaEvidence: options.idaEvidence } : {}),
-        ...(options.output ? { output: options.output } : {}),
-        maxInstructions: positiveInteger(options.maxInstructions, "max-instructions"),
-        dryRun: options.dryRun === true
-    })));
+    const analyze = program.command("analyze").description("Run Frida evidence export and bounded runtime operations");
     analyze.command("runtime")
-        .description("Read runtime evidence through the elevated Frida broker")
+        .description("Dump runtime PE sections or verify profile candidates through the elevated Frida broker")
         .requiredOption("--pid <pid>", "target process ID")
         .requiredOption("--build <buildKey>", "build key")
         .option("--build-key <buildKey>", "alias for --build")
-        .option("--kind <kind>", "text or providers", "providers")
+        .option("--kind <kind>", "dump or verify", "dump")
         .option("--worker <path>", "Frida worker entry")
-        .option("--profile <path>", "existing reader profile containing candidate RVAs")
-        .option("--max-hooks <count>", "maximum hooks", "1")
+        .option("--profile <path>", "reader profile containing candidate RVAs (verify only)")
+        .option("--output-dir <path>", "directory for dump manifest and section binaries")
+        .option("--sections <names...>", "sections to dump (default: .text .rdata .pdata)")
+        .option("--no-progress", "disable dump progress on stderr")
+        .option("--max-section-bytes <bytes>", "per-section dump limit", "134217728")
+        .option("--max-total-bytes <bytes>", "total dump limit", "268435456")
+        .option("--chunk-size <bytes>", "dump chunk size", "1048576")
+        .option("--max-verify-bytes <bytes>", "maximum bytes read per candidate", "256")
+        .option("--max-hooks <count>", "reserved compatibility limit", "1")
         .option("--duration-ms <ms>", "maximum duration", "5000")
         .option("--max-events <count>", "maximum events", "100")
         .option("--cleanup-deadline-ms <ms>", "cleanup deadline", "2000")
@@ -442,40 +544,93 @@ export function createWowdumpCli(dependencies = {}) {
             durationMs: positiveInteger(options.durationMs, "duration-ms"),
             maxEvents: positiveInteger(options.maxEvents, "max-events"),
             cleanupDeadlineMs: positiveInteger(options.cleanupDeadlineMs, "cleanup-deadline-ms"),
+            maxSectionBytes: positiveInteger(options.maxSectionBytes, "max-section-bytes"),
+            maxTotalBytes: positiveInteger(options.maxTotalBytes, "max-total-bytes"),
+            chunkSize: positiveInteger(options.chunkSize, "chunk-size"),
+            maxVerifyBytes: positiveInteger(options.maxVerifyBytes, "max-verify-bytes"),
             confirm: options.confirm === true
         };
-        if (!["text", "providers"].includes(normalized.kind))
-            throw new CliError("ARGUMENT_INVALID", "kind must be text or providers");
+        if (!["dump", "verify"].includes(normalized.kind))
+            throw new CliError("ARGUMENT_INVALID", "kind must be dump or verify");
         requireRuntimeConfirmation(normalized);
+        if (normalized.kind === "verify" && !options.profile)
+            throw new CliError("PROFILE_REQUIRED", "verify requires --profile <file>");
         const worker = resolve(options.worker ?? env.WOWDUMP_FRIDA_WORKER ?? join(packageDist, "frida-worker.js"));
         if (!existsSync(worker))
             throw new CliError("FRIDA_WORKER_NOT_FOUND", `Frida worker was not found: ${worker}`);
         const profile = options.profile
             ? jsonRecord(await readFile(resolve(options.profile), "utf8"), options.profile)
             : undefined;
+        const buildRecord = await readBuild(home, normalized.build);
+        if (profile)
+            await validateProfileIdentity(home, normalized.build, profile, resolve(options.profile));
+        const sections = Array.isArray(options.sections) && options.sections.length > 0
+            ? options.sections.map((value) => String(value).toLowerCase())
+            : [".text", ".rdata", ".pdata"];
+        if (normalized.kind === "dump") {
+            const reusable = buildRecord?.executableSha256
+                ? await findReusableDump(home, normalized.build, {
+                    executableSha256: buildRecord.executableSha256,
+                    sections,
+                    maxSectionBytes: normalized.maxSectionBytes,
+                    maxTotalBytes: normalized.maxTotalBytes,
+                    chunkSize: normalized.chunkSize
+                })
+                : null;
+            if (reusable) {
+                writeJson(io, { ok: true, command: "analyze.runtime.dump", reused: true, manifestFile: String(reusable.manifestFile ?? ""), manifest: reusable });
+                return;
+            }
+        }
+        const sessionId = randomUUID();
+        const sessionDirectory = options.outputDir
+            ? resolve(options.outputDir, "..")
+            : join(buildPaths(home, normalized.build).runtime, sessionId);
+        const outputDirectory = resolve(options.outputDir ?? join(sessionDirectory, "dump"));
+        await mkdir(sessionDirectory, { recursive: true });
+        await writeFile(join(sessionDirectory, "target.json"), `${JSON.stringify({ schema: "wowdump.runtime-target.v1", pid: normalized.pid, buildKey: normalized.build, executableSha256: buildRecord?.executableSha256 ?? null, sessionId, createdAt: new Date().toISOString() }, null, 2)}\n`, "utf8");
         const request = {
-            command: "dynamic-script",
+            command: normalized.kind === "dump" ? "runtime-dump" : "dynamic-script",
             pid: normalized.pid,
             build: normalized.build,
             source: RUNTIME_EXPORT_SCRIPT,
             exportName: "collect",
+            ...(normalized.kind === "dump" ? { outputDir: outputDirectory, progress: options.progress !== false, executableSha256: buildRecord?.executableSha256 ?? null, preferredImageBase: buildRecord?.preferredImageBase ?? null, moduleSize: buildRecord?.moduleSize ?? null, dumpParameters: { executableSha256: buildRecord?.executableSha256 ?? null, sections, maxSectionBytes: normalized.maxSectionBytes, maxTotalBytes: normalized.maxTotalBytes, chunkSize: normalized.chunkSize } } : {}),
             args: {
                 kind: normalized.kind,
                 maxHooks: normalized.maxHooks,
                 durationMs: normalized.durationMs,
                 maxEvents: normalized.maxEvents,
                 cleanupDeadlineMs: normalized.cleanupDeadlineMs,
+                maxSectionBytes: normalized.maxSectionBytes,
+                maxTotalBytes: normalized.maxTotalBytes,
+                chunkSize: normalized.chunkSize,
+                maxVerifyBytes: normalized.maxVerifyBytes,
+                ...(normalized.kind === "dump" ? { sections } : {}),
                 ...(profile ? { profile } : {})
             },
             callArgs: [],
             durationMs: normalized.durationMs
         };
         const result = await sidecar(process.execPath, [worker], `${JSON.stringify(request)}\n`);
+        if (result.stderr && options.progress !== false)
+            io.stderr.write(result.stderr);
         if (result.exitCode !== 0)
             throw new CliError("FRIDA_WORKER_FAILED", result.stderr.trim() || `Frida worker exited with ${result.exitCode}`);
         const line = result.stdout.split(/\r?\n/).find(value => value.trim());
         const value = line ? jsonRecord(line, "runtime result") : { ok: true, stdout: result.stdout };
-        writeJson(io, { ...value, command: "analyze.runtime" });
+        if (normalized.kind === "dump" && value.ok === true) {
+            if (typeof value.manifestFile === "string") {
+                await writeFile(join(sessionDirectory, "dynamic.json"), `${JSON.stringify(value.manifest ?? value, null, 2)}\n`, "utf8").catch(() => undefined);
+                writeJson(io, { ...value, command: "analyze.runtime.dump", sessionDirectory });
+            }
+            else
+                throw new CliError("RUNTIME_DUMP_INVALID", "runtime dump worker returned no manifest");
+        }
+        else {
+            await writeFile(join(sessionDirectory, "verify.json"), `${JSON.stringify(value, null, 2)}\n`, "utf8").catch(() => undefined);
+            writeJson(io, { ...value, command: "analyze.runtime.verify" });
+        }
     });
     analyze.command("dynamic")
         .description("Run a caller-supplied GumJS script through Frida")
@@ -507,11 +662,17 @@ export function createWowdumpCli(dependencies = {}) {
         if (!existsSync(worker))
             throw new CliError("FRIDA_WORKER_NOT_FOUND", `Frida worker was not found: ${worker}`);
         const request = { command: "dynamic-script", ...selected(normalized, ["pid", "build", "script", "exportName", "args", "callArgs", "durationMs"]) };
+        const sessionId = randomUUID();
+        const sessionDirectory = join(buildPaths(home, normalized.build).runtime, sessionId);
+        await mkdir(sessionDirectory, { recursive: true });
+        await writeFile(join(sessionDirectory, "target.json"), `${JSON.stringify({ schema: "wowdump.runtime-target.v1", pid: normalized.pid, buildKey: normalized.build, sessionId, createdAt: new Date().toISOString() }, null, 2)}\n`, "utf8");
         const result = await sidecar(process.execPath, [worker], `${JSON.stringify(request)}\n`);
         if (result.exitCode !== 0)
             throw new CliError("FRIDA_WORKER_FAILED", result.stderr.trim() || `Frida worker exited with ${result.exitCode}`);
         const line = result.stdout.split(/\r?\n/).find(value => value.trim());
-        writeJson(io, line ? JSON.parse(line) : { ok: true, command: "analyze.dynamic", stdout: result.stdout });
+        const value = line ? JSON.parse(line) : { ok: true, command: "analyze.dynamic", stdout: result.stdout };
+        await writeFile(join(sessionDirectory, "dynamic.json"), `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        writeJson(io, { ...value, command: "analyze.dynamic", sessionDirectory });
     });
     program.command("init")
         .description("Initialize WOWDUMP_HOME without overwriting existing files")

package/dist/core/build-store.js

@@ -0,0 +1,166 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, normalize, resolve } from "node:path";
+export function resolveWowdumpHome(env = process.env, userHome = homedir()) {
+    return normalize(resolve(env.WOWDUMP_HOME || join(userHome, ".wowdump")));
+}
+export function safeBuildKey(buildKey) {
+    const value = buildKey.trim();
+    if (!value || value === "." || value === ".." || !/^[A-Za-z0-9_.@-]+$/.test(value))
+        throw new Error("build key contains unsupported path characters");
+    return value;
+}
+export function buildDirectory(home, buildKey) {
+    return join(resolve(home), safeBuildKey(buildKey));
+}
+export function buildPaths(home, buildKey) {
+    const build = buildDirectory(home, buildKey);
+    const database = join(build, "database");
+    return {
+        root: resolve(home),
+        build,
+        database,
+        databaseFile: join(database, "database.json"),
+        databaseLock: join(database, "database.lock"),
+        ida: join(database, "ida"),
+        profile: join(build, "profile"),
+        runtime: join(build, "runtime")
+    };
+}
+export async function sha256File(file) {
+    return new Promise((resolveHash, reject) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(file);
+        stream.on("data", chunk => hash.update(chunk));
+        stream.once("error", reject);
+        stream.once("end", () => resolveHash(hash.digest("hex")));
+    });
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function writeJson(file, value) {
+    await mkdir(resolve(file, ".."), { recursive: true });
+    await writeFile(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+export async function readBuild(home, buildKey) {
+    return readJson(join(buildDirectory(home, buildKey), "build.json"));
+}
+export async function readDatabase(home, buildKey) {
+    return readJson(buildPaths(home, buildKey).databaseFile);
+}
+async function ensureBuildUnlocked(home, input) {
+    const paths = buildPaths(home, input.buildKey);
+    await mkdir(paths.profile, { recursive: true });
+    await mkdir(paths.ida, { recursive: true });
+    await mkdir(paths.runtime, { recursive: true });
+    const now = new Date().toISOString();
+    const oldBuild = await readJson(join(paths.build, "build.json"));
+    const oldDatabase = await readJson(paths.databaseFile);
+    const sameIdentity = Boolean(oldBuild && oldDatabase
+        && oldBuild.executableSha256 === input.executableSha256
+        && oldBuild.preferredImageBase === input.preferredImageBase
+        && oldBuild.moduleSize === input.moduleSize
+        && oldDatabase.executableSha256 === input.executableSha256
+        && oldDatabase.preferredImageBase === input.preferredImageBase
+        && oldDatabase.moduleSize === input.moduleSize);
+    const build = {
+        schema: "wowdump.build.v1",
+        ...input,
+        createdAt: oldBuild?.createdAt ?? now,
+        updatedAt: now
+    };
+    const database = {
+        schema: "wowdump.database.v1",
+        buildKey: input.buildKey,
+        executableSha256: input.executableSha256,
+        preferredImageBase: input.preferredImageBase,
+        moduleSize: input.moduleSize,
+        idaDatabase: join(paths.ida, "Wow.i64"),
+        idaVersion: oldDatabase?.idaVersion ?? null,
+        status: sameIdentity ? (oldDatabase?.status ?? "creating") : oldDatabase ? "stale" : "creating",
+        createdAt: oldDatabase?.createdAt ?? now,
+        updatedAt: now,
+        lastAnalysisAt: oldDatabase?.lastAnalysisAt ?? null
+    };
+    await writeJson(join(paths.build, "build.json"), build);
+    await writeJson(paths.databaseFile, database);
+    return { build, database, reused: sameIdentity && database.status === "ready" };
+}
+export async function ensureBuild(home, input) {
+    const release = await acquireDatabaseLock(home, input.buildKey);
+    try {
+        return await ensureBuildUnlocked(home, input);
+    }
+    finally {
+        await release();
+    }
+}
+export async function markDatabaseReady(home, buildKey, patch = {}) {
+    const current = await readDatabase(home, buildKey);
+    if (!current)
+        throw new Error(`database for ${buildKey} does not exist`);
+    const database = { ...current, ...patch, status: "ready", updatedAt: new Date().toISOString(), lastAnalysisAt: new Date().toISOString() };
+    await writeJson(buildPaths(home, buildKey).databaseFile, database);
+    return database;
+}
+export async function acquireDatabaseLock(home, buildKey) {
+    const paths = buildPaths(home, buildKey);
+    await mkdir(paths.database, { recursive: true });
+    let handle;
+    try {
+        handle = await open(paths.databaseLock, "wx");
+    }
+    catch (error) {
+        throw new Error(`database is locked: ${paths.databaseLock}`, { cause: error });
+    }
+    await handle.writeFile(`${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`, "utf8");
+    return async () => {
+        await handle.close().catch(() => undefined);
+        await rm(paths.databaseLock, { force: true }).catch(() => undefined);
+    };
+}
+export async function databaseStatus(home, buildKey) {
+    const paths = buildPaths(home, buildKey);
+    const [build, loadedDatabase, lock] = await Promise.all([
+        readJson(join(paths.build, "build.json")),
+        readJson(paths.databaseFile),
+        stat(paths.databaseLock).then(() => true).catch(() => false)
+    ]);
+    let database = loadedDatabase;
+    if (database && database.status === "creating" && await stat(database.idaDatabase).then(() => true).catch(() => false)) {
+        database = { ...database, status: "ready", updatedAt: new Date().toISOString(), lastAnalysisAt: database.lastAnalysisAt ?? new Date().toISOString() };
+        if (!lock)
+            await writeJson(paths.databaseFile, database);
+    }
+    return { ok: true, buildKey: safeBuildKey(buildKey), buildDirectory: paths.build, databasePath: paths.databaseFile, exists: Boolean(database), locked: lock, build, database };
+}
+export async function findReusableDump(home, buildKey, criteria) {
+    const runtime = buildPaths(home, buildKey).runtime;
+    let sessions;
+    try {
+        sessions = await readdir(runtime, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    for (const session of sessions.filter(item => item.isDirectory())) {
+        const manifestFile = join(runtime, session.name, "dump", "manifest.json");
+        const manifest = await readJson(manifestFile);
+        if (!manifest || typeof manifest.moduleBase !== "string" || JSON.stringify(manifest.dumpParameters ?? null) !== JSON.stringify(criteria))
+            continue;
+        return { ...manifest, manifestFile };
+    }
+    return null;
+}

package/dist/core/profile-engine.js

@@ -143,6 +143,15 @@ export class ProfileEngine {
         if (request.buildKey && request.buildKey !== buildKey) {
             throw new ProfileEngineError("BUILD_MISMATCH", `profile build ${buildKey} does not match ${request.buildKey}`);
         }
+        if (request.executableSha256) {
+            const executable = profile.executable && typeof profile.executable === "object" && !Array.isArray(profile.executable)
+                ? profile.executable
+                : undefined;
+            const profileHash = typeof profile.executableSha256 === "string" ? profile.executableSha256 : String(executable?.sha256 ?? "");
+            if (profileHash && profileHash !== request.executableSha256) {
+                throw new ProfileEngineError("EXECUTABLE_MISMATCH", "profile executable hash does not match the target build", { expected: request.executableSha256, actual: profileHash });
+            }
+        }
         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 });

package/dist/frida-worker.js

@@ -1,6 +1,8 @@
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
 import { FridaCommandRuntime } from "./analysis/frida-runtime.js";
+import { RuntimeDumpWriter } from "./analysis/runtime-dump.js";
+import { isAbsolute, resolve } from "node:path";
 function record(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
@@ -15,7 +17,7 @@ function positive(value, name) {
  * GumJS source; this process only attaches, loads, calls, and cleans it up.
  */
 async function run(input) {
-    if (input.command !== "dynamic-script")
+    if (input.command !== "dynamic-script" && input.command !== "runtime-dump")
         throw new Error("unsupported worker command");
     const pid = positive(input.pid, "pid");
     const buildKey = String(input.build ?? input.buildKey ?? "").trim();
@@ -29,24 +31,74 @@ async function run(input) {
     const runtime = new FridaCommandRuntime({ artifactDir: process.env.WOW_ANALYZE_DIR });
     let sessionId;
     let loaded = false;
+    const isDump = input.command === "runtime-dump";
+    const outputDirectory = isDump ? resolve(String(input.outputDir ?? "")) : undefined;
+    const outputDirectoryInput = isDump ? String(input.outputDir ?? "") : "";
+    const writer = isDump ? new RuntimeDumpWriter({
+        outputDirectory: outputDirectory,
+        buildKey,
+        pid,
+        executableSha256: typeof input.executableSha256 === "string" ? input.executableSha256 : null,
+        preferredImageBase: typeof input.preferredImageBase === "string" ? input.preferredImageBase : null,
+        moduleSize: Number.isSafeInteger(Number(input.moduleSize)) ? Number(input.moduleSize) : null,
+        dumpParameters: input.dumpParameters && typeof input.dumpParameters === "object" ? input.dumpParameters : undefined
+    }) : undefined;
+    let finalized = false;
     try {
+        if (isDump) {
+            if (!outputDirectoryInput || !isAbsolute(outputDirectoryInput))
+                throw new Error("runtime dump outputDir must be an absolute path");
+            await writer.initialize();
+        }
         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;
+        const scriptSource = `globalThis.__WOWDUMP_INPUT__ = Object.freeze(${JSON.stringify(input.args ?? {})});\n${source}`;
+        let value;
+        let messages = [];
+        if (isDump) {
+            await writeFile(resolve(outputDirectory, "..", "target.json"), `${JSON.stringify({ schema: "wowdump.runtime-target.v1", pid, buildKey, module, executableSha256: input.executableSha256 ?? null, createdAt: new Date().toISOString() }, null, 2)}\n`, "utf8").catch(() => undefined);
+            let progressBytes = 0;
+            const streamed = await runtime.streamScriptCall({
+                operation: "script_load",
+                sessionId,
+                pid,
+                buildKey,
+                source: scriptSource,
+                exportName: typeof input.exportName === "string" ? input.exportName : "collect"
+            }, undefined, async (message, data) => {
+                const envelope = message && typeof message === "object" ? message : {};
+                if (envelope.type !== "send" || !data)
+                    return;
+                const payload = envelope.payload && typeof envelope.payload === "object" ? envelope.payload : {};
+                if (payload.type !== "wowdump.dump.chunk")
+                    return;
+                await writer.writeChunk(payload, data);
+                progressBytes += data.byteLength;
+                if (input.progress !== false)
+                    process.stderr.write(`wowdump dump ${progressBytes} bytes\\n`);
+            });
+            value = streamed.value;
+            const result = value && typeof value === "object" ? value : {};
+            if (result.ok !== true)
+                throw new Error(String(result.error ?? "runtime dump failed"));
+            const persisted = await writer.finalize({ ...result, module: module ?? result.module });
+            finalized = true;
+            await writeFile(resolve(outputDirectory, "..", "dynamic.json"), `${JSON.stringify({ ...result, manifestFile: persisted.manifestFile, generatedAt: new Date().toISOString() }, null, 2)}\n`, "utf8").catch(() => undefined);
+            return { ok: true, command: "analyze.runtime.dump", pid, buildKey, manifestFile: persisted.manifestFile, outputDirectory, manifest: persisted.manifest, sections: persisted.sections };
+        }
         await runtime.execute({
             operation: "script_load",
             sessionId,
             pid,
             buildKey,
-            source: `globalThis.__WOWDUMP_INPUT__ = Object.freeze(${JSON.stringify(input.args ?? {})});\n${source}`,
+            source: scriptSource,
             scriptId: "dynamic"
         });
         loaded = true;
-        let value;
-        let messages = [];
         if (typeof input.exportName === "string" && input.exportName.trim()) {
             const called = await runtime.execute({
                 operation: "script_call",
@@ -79,6 +131,8 @@ async function run(input) {
     finally {
         if (sessionId && loaded)
             await runtime.execute({ operation: "script_unload", sessionId, scriptId: "dynamic" }).catch(() => undefined);
+        if (isDump && writer && !finalized)
+            await writer.abort().catch(() => undefined);
         await runtime.close();
     }
 }