wowdump 0.0.0 → 0.2.1

package/dist/broker-main.js

@@ -0,0 +1,291 @@
+import { resolve, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { BrokerCore } from "./broker-core.js";
+import { BrokerServer, FileBrokerArtifactStore, FileBrokerSingletonGuard } from "./broker-server.js";
+import { BrokerFridaRuntime } from "./broker-runtime.js";
+import { FridaCommandRuntime } from "./frida-runtime.js";
+import { canonicalArtifactRoot, sidHash } from "./broker-protocol.js";
+import { isWindowsProcessElevated } from "./broker-client.js";
+import { discoverInstalls } from "./discovery.js";
+import { listWowProcesses } from "./processes.js";
+import { FocusAnalysisService } from "./focus-service.js";
+import { AnalysisProcessLog } from "./analysis-process-log.js";
+process.title = "wowdump-broker";
+if (process.env.NODE_ENV === "test" && process.env.WOW_BROKER_LIFECYCLE_NORMALIZE_FIXTURE) {
+    const fixture = JSON.parse(process.env.WOW_BROKER_LIFECYCLE_NORMALIZE_FIXTURE);
+    const event = fixture.event && typeof fixture.event === "object" && !Array.isArray(fixture.event) ? fixture.event : {};
+    const seq = Number.isSafeInteger(fixture.seq) ? Number(fixture.seq) : 1;
+    const fixtureInstanceId = typeof fixture.instanceId === "string" ? fixture.instanceId : "fixture-instance";
+    const timestamp = typeof fixture.timestamp === "string" ? fixture.timestamp : new Date().toISOString();
+    process.stdout.write(`${JSON.stringify(normalizeLifecycleEvent(event, seq, fixtureInstanceId, timestamp))}\n`);
+    process.exit(0);
+}
+const configuredPipeName = argument("--pipe") ?? process.env.WOW_BROKER_PIPE;
+if (!configuredPipeName)
+    throw new Error("Broker pipe name is required");
+const pipeName = configuredPipeName;
+const sid = process.env.WOW_BROKER_SID ?? process.env.USERNAME ?? "default";
+const currentSidHash = argument("--sid-hash") ?? process.env.WOW_BROKER_SID_HASH ?? sidHash(sid);
+if (!/^[a-f0-9]{24}$/i.test(currentSidHash))
+    throw new Error("Broker SID hash is invalid");
+const bootstrapNonce = argument("--bootstrap-nonce") ?? process.env.WOW_BROKER_BOOTSTRAP_NONCE ?? randomUUID();
+const instanceId = randomUUID();
+const artifactDir = canonicalArtifactRoot(argument("--artifact-root") ?? process.env.WOW_BROKER_ARTIFACT_ROOT ?? process.env.WOWDUMP_RUNTIME_DIR ?? join(process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local"), "wowdump"));
+const profileRoot = resolve(process.env.WOWDUMP_PROFILE_DIR ?? artifactDir);
+const gameRoots = (process.env.WOWDUMP_GAME_ROOTS ?? process.env.WOW_ROOT ?? "")
+    .split(";").map(value => value.trim()).filter(Boolean);
+const executor = new FridaCommandRuntime({ artifactDir });
+const processLog = new AnalysisProcessLog(artifactDir);
+const focusService = new FocusAnalysisService({ executor, runtimeRoot: artifactDir, profileRoot, deferAttachmentDetach: true, lifecycle: event => appendLifecycle(event) });
+const readyIdentity = { instanceId, protocolVersion: "2026-07-28", sidHash: currentSidHash, elevated: await isWindowsProcessElevated(), pipeName, bootstrapNonce, artifactRoot: artifactDir };
+const processResolver = async (pid) => {
+    try {
+        const installs = gameRoots.flatMap(gameRoot => discoverInstalls(gameRoot));
+        const process = (await listWowProcesses(installs)).find(item => item.pid === pid);
+        return process ? {
+            pid: process.pid,
+            name: "Wow.exe",
+            executable: process.executable,
+            processStartTime: process.startTime,
+            buildKey: process.install.build.buildKey
+        } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const runtime = new BrokerFridaRuntime(executor, readyIdentity, undefined, join(artifactDir, "broker-evidence"), processResolver, focusService);
+let server;
+let core;
+let closing;
+async function start() {
+    core = new BrokerCore({
+        runtime,
+        ledgerPath: join(artifactDir, "frida-broker-request-ledger.jsonl"),
+        idleTimeoutMs: numericEnvironment("WOWDUMP_BROKER_IDLE_MS", 20 * 60 * 1000),
+        lifecycle: event => appendLifecycle(event),
+        closeServer: () => server?.closeServer(),
+        releaseSingleton: () => server?.releaseGuard()
+    });
+    const artifactStore = new FileBrokerArtifactStore(join(artifactDir, "broker-artifacts"));
+    const guard = new FileBrokerSingletonGuard(join(homedir(), `.wowdump-frida-${currentSidHash}.lock`), pipeName);
+    server = new BrokerServer({ pipeName, core, guard, artifactStore });
+    await server.listen();
+}
+async function stop(reason) {
+    if (closing)
+        return closing;
+    closing = (async () => {
+        if (core)
+            await core.shutdown(reason).catch(() => undefined);
+        else
+            await server?.close().catch(() => undefined);
+    })();
+    return closing;
+}
+process.once("SIGINT", () => void stop("signal"));
+process.once("SIGTERM", () => void stop("signal"));
+process.once("uncaughtException", error => {
+    console.error("broker:", error);
+    void stop("broker_fatal").finally(() => process.exit(1));
+});
+process.once("unhandledRejection", error => {
+    console.error("broker:", error);
+    void stop("broker_fatal").finally(() => process.exit(1));
+});
+try {
+    await start();
+}
+catch (error) {
+    await writeStartupFailure(error).catch(() => undefined);
+    throw error;
+}
+function argument(name) {
+    const index = process.argv.indexOf(name);
+    return index >= 0 ? process.argv[index + 1] : undefined;
+}
+function numericEnvironment(name, fallback) {
+    const value = Number(process.env[name]);
+    return Number.isSafeInteger(value) && value >= 0 ? value : fallback;
+}
+async function writeStartupFailure(error) {
+    await mkdir(artifactDir, { recursive: true });
+    const safeNonce = bootstrapNonce.replace(/[^A-Za-z0-9_.-]/g, "_").slice(0, 128);
+    const path = join(artifactDir, `broker-startup-failure-${safeNonce}.json`);
+    const temporary = `${path}.${process.pid}.tmp`;
+    const protocolError = error;
+    const report = {
+        schema: "wow.broker-startup-failure.v1",
+        timestamp: new Date().toISOString(),
+        pid: process.pid,
+        pipeName,
+        sidHash: currentSidHash,
+        artifactRoot: artifactDir,
+        bootstrapNonce,
+        elevated: await isWindowsProcessElevated().catch(() => false),
+        error: {
+            name: error instanceof Error ? error.name : "Error",
+            code: typeof protocolError?.code === "string" ? protocolError.code : null,
+            message: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack ?? null : null,
+            nextAction: typeof protocolError?.nextAction === "string" ? protocolError.nextAction : null
+        }
+    };
+    await writeFile(temporary, `${JSON.stringify(report, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(temporary, path);
+}
+let lifecycleSeq = 0;
+let lifecycleLoaded = false;
+let lifecycleTail = Promise.resolve();
+function appendLifecycle(event) {
+    const operation = lifecycleTail.then(() => appendLifecycleOwned(event));
+    lifecycleTail = operation.catch(() => undefined);
+    return operation;
+}
+async function appendLifecycleOwned(event) {
+    await mkdir(artifactDir, { recursive: true });
+    if (!lifecycleLoaded) {
+        lifecycleLoaded = true;
+        try {
+            const text = await readFile(join(artifactDir, "frida-broker-lifecycle.jsonl"), "utf8");
+            for (const line of text.split(/\r?\n/)) {
+                if (!line)
+                    continue;
+                try {
+                    const parsed = JSON.parse(line);
+                    if (Number.isSafeInteger(parsed.seq))
+                        lifecycleSeq = Math.max(lifecycleSeq, Number(parsed.seq));
+                }
+                catch { /* preserve malformed history; the process log remains append-only */ }
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    const normalized = normalizeLifecycleEvent(event, ++lifecycleSeq, instanceId);
+    const lifecycleFile = join(artifactDir, "frida-broker-lifecycle.jsonl");
+    const lifecycleHandle = await open(lifecycleFile, "a", 0o600);
+    try {
+        await lifecycleHandle.write(JSON.stringify(normalized) + "\n", null, "utf8");
+        await lifecycleHandle.sync();
+    }
+    finally {
+        await lifecycleHandle.close();
+    }
+    const value = normalized;
+    const operation = typeof value.operation === "string" ? value.operation : null;
+    const focusOperation = operation?.startsWith("wow_focus_") || operation?.startsWith("wow_watch_") || operation === "wow_session_checkpoint";
+    const result = lifecycleResultProjection(value);
+    const sessionId = textValue(value.sessionId) ?? textValue(result.sessionId);
+    const resourceId = textValue(value.resourceId) ?? textValue(result.resourceId);
+    const pid = Number.isSafeInteger(value.pid) ? Number(value.pid) : null;
+    await processLog.append({
+        buildKey: typeof value.buildKey === "string" ? value.buildKey : null,
+        phase: focusOperation ? (operation?.startsWith("wow_watch_") ? "data-root" : "lua-trace") : "verify",
+        action: focusOperation ? `${operation}_${String(value.action ?? "lifecycle")}` : `broker_${String(value.action ?? "lifecycle")}`,
+        tool: "frida-mcp",
+        command: operation,
+        status: typeof value.status === "string" ? value.status : "partial",
+        target: {
+            name: sessionId ?? "Wow.exe",
+            kind: sessionId ? "focused_session" : "module",
+            pid,
+            sessionId: sessionId ?? null,
+            resourceId: resourceId ?? null,
+            va: null,
+            rva: null,
+            imageBase: "0x140000000",
+            moduleBase: null,
+            runtimeAddress: null
+        },
+        result: {
+            ...result,
+            requestId: textValue(value.requestId) ?? textValue(result.requestId) ?? null,
+            clientId: textValue(value.clientId) ?? textValue(result.clientId) ?? null,
+            sessionId: sessionId ?? null,
+            resourceId: resourceId ?? null,
+            pid,
+            buildKey: typeof value.buildKey === "string" ? value.buildKey : null
+        },
+        error: value.error ?? null,
+        nextAction: typeof value.nextAction === "string" ? value.nextAction : null
+    });
+}
+export function normalizeLifecycleEvent(event, seq, writerInstanceId, timestamp = new Date().toISOString()) {
+    const value = event;
+    const result = value.result && typeof value.result === "object" && !Array.isArray(value.result)
+        ? value.result
+        : {};
+    const durationCandidate = typeof value.durationMs === "number" ? value.durationMs : value.duration;
+    const durationMs = typeof durationCandidate === "number" && Number.isFinite(durationCandidate) && durationCandidate >= 0
+        ? durationCandidate
+        : 0;
+    const dropSummary = objectValue(value.dropSummary) ?? objectValue(result.dropSummary) ?? {
+        droppedEventCount: nonNegativeNumber(value.droppedEventCount) ?? nonNegativeNumber(result.droppedEventCount) ?? 0,
+        droppedByteCount: nonNegativeNumber(value.droppedByteCount) ?? nonNegativeNumber(result.droppedByteCount) ?? 0,
+        overflowCount: nonNegativeNumber(value.overflowCount) ?? nonNegativeNumber(result.overflowCount) ?? 0
+    };
+    const cleanupSummary = objectValue(value.cleanupSummary) ?? objectValue(result.cleanupSummary) ?? {
+        cleanupAttempted: booleanValue(value.cleanupAttempted) ?? booleanValue(result.cleanupAttempted) ?? false,
+        fullyReleased: booleanValue(value.fullyReleased) ?? booleanValue(result.fullyReleased) ?? null,
+        cleanupStatus: objectValue(value.cleanupStatus) ?? objectValue(result.cleanupStatus) ?? null,
+        residualResourceIds: arrayValue(value.residualResourceIds) ?? arrayValue(result.residualResourceIds) ?? [],
+        residualSessionId: textValue(value.residualSessionId) ?? textValue(result.residualSessionId) ?? null
+    };
+    const error = Object.hasOwn(value, "error") ? value.error : null;
+    return {
+        ...value,
+        timestamp: textValue(value.timestamp) ?? timestamp,
+        seq,
+        instanceId: writerInstanceId,
+        clientId: textValue(value.clientId) ?? textValue(result.clientId) ?? null,
+        requestId: textValue(value.requestId) ?? textValue(result.requestId) ?? null,
+        resourceId: textValue(value.resourceId) ?? textValue(result.resourceId) ?? null,
+        sessionId: textValue(value.sessionId) ?? textValue(result.sessionId) ?? null,
+        operation: textValue(value.operation) ?? textValue(value.action) ?? "broker_lifecycle",
+        pid: Number.isSafeInteger(value.pid) ? Number(value.pid) : Number.isSafeInteger(result.pid) ? Number(result.pid) : null,
+        buildKey: textValue(value.buildKey) ?? textValue(result.buildKey) ?? null,
+        duration: durationMs,
+        durationMs,
+        result: Object.hasOwn(value, "result") ? value.result : null,
+        status: textValue(value.status) ?? (error === null || error === undefined ? "partial" : "failed"),
+        dropSummary,
+        cleanupSummary,
+        error: error ?? null,
+        nextAction: textValue(value.nextAction) ?? null
+    };
+}
+function lifecycleResultProjection(value) {
+    const source = value.result && typeof value.result === "object" && !Array.isArray(value.result)
+        ? value.result
+        : {};
+    const projected = {};
+    for (const key of [
+        "requestId", "clientId", "sessionId", "resourceId", "pid", "buildKey",
+        "cleanupAttempted", "fullyReleased", "alreadyReleased", "cleanupStatus",
+        "residualSessionId", "residualResourceIds", "attachmentDetachStatus",
+        "seq", "eventKind", "diff", "reason", "cleanupSteps"
+    ])
+        if (Object.hasOwn(source, key))
+            projected[key] = source[key];
+    return projected;
+}
+function textValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function arrayValue(value) {
+    return Array.isArray(value) ? value : undefined;
+}
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function nonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}

package/dist/broker-protocol.js

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+export const BROKER_PROTOCOL_VERSION = "2026-07-28";
+export const BROKER_SCHEMA_VERSION = 1;
+export const BROKER_MAX_FRAME_BYTES = 4 * 1024 * 1024;
+export const BROKER_MAX_INLINE_BYTES = 1024 * 1024;
+export const BROKER_DEFAULT_TIMEOUT_MS = 30_000;
+export function canonicalArtifactRoot(value) {
+    if (typeof value !== "string" || !value.trim())
+        throw new BrokerProtocolError("BROKER_ARTIFACT_ROOT_MISMATCH", "artifactRoot must be a non-empty absolute path");
+    return resolve(value);
+}
+export const BROKER_ERROR_CODES = [
+    "BROKER_STOPPED", "BOOTSTRAP_LOCK_BUSY", "BOOTSTRAP_TIMEOUT",
+    "BROKER_EXECUTABLE_INVALID", "BOOTSTRAP_SPAWN_FAILED", "UAC_CANCELLED",
+    "UAC_FAILED", "READY_IDENTITY_MISMATCH", "ACL_MISMATCH", "STALE_LOCK_UNSAFE",
+    "FRAME_INVALID", "FRAME_TOO_LARGE", "PROTOCOL_VERSION_MISMATCH", "REQUEST_TIMEOUT",
+    "REQUEST_CANCELLED", "REQUEST_NOT_FOUND", "REQUEST_ID_REPLAYED", "PID_REQUIRED",
+    "PID_NOT_WOW", "PID_BUILD_MISMATCH", "PID_REUSED", "MODULE_NOT_FOUND",
+    "SELECTOR_EMPTY", "SELECTOR_INVALID", "TARGETS_OVER_LIMIT", "RESOURCE_NOT_FOUND",
+    "RESOURCE_NOT_OWNER", "RESOURCE_ALREADY_RELEASED", "RESOURCE_REF_UNDERFLOW",
+    "SESSION_TARGET_MISMATCH", "CAPTURE_FATAL", "ATTACHMENT_FATAL", "BROKER_FATAL",
+    "CLEANUP_TIMEOUT", "ARTIFACT_MANIFEST_CONFLICT", "ARTIFACT_VERIFY_FAILED",
+    "MUTATION_PLAN_REQUIRED", "MUTATION_CONFIRMATION_REQUIRED", "MUTATION_EXPECTED_EFFECT_REQUIRED",
+    "MUTATION_ROLLBACK_REQUIRED", "MUTATION_ROLLBACK_INVALID", "MUTATION_IRREVERSIBLE_CONFIRMATION_REQUIRED",
+    "MUTATION_EVIDENCE_PLAN_REQUIRED", "MUTATION_AUDIT_REQUIRED", "MUTATION_CONFIRMATION_EXPIRED",
+    "MUTATION_CONFIRMATION_REPLAYED", "MUTATION_TARGET_MISMATCH", "MUTATION_EVIDENCE_MISMATCH",
+    "MUTATION_BEFORE_EVIDENCE_FAILED", "MUTATION_EXECUTION_FAILED", "MUTATION_AFTER_EVIDENCE_FAILED",
+    "MUTATION_ROLLBACK_UNAVAILABLE", "MUTATION_ROLLBACK_FAILED", "MUTATION_OUTCOME_UNKNOWN",
+    "SPAWN_CONTRACT_REQUIRED", "SPAWN_PID_MUST_BE_NULL", "SPAWN_BUILD_MISMATCH",
+    "HOST_CALL_BUILD_KEY_REQUIRED", "HOST_CALL_NOT_ALLOWLISTED", "HOST_CALL_SCHEMA_MISMATCH",
+    "BROKER_ARTIFACT_ROOT_MISMATCH"
+];
+export class BrokerProtocolError extends Error {
+    code;
+    nextAction;
+    constructor(code, message, nextAction = "Inspect Broker status and retry with a valid request.") {
+        super(message);
+        this.code = code;
+        this.nextAction = nextAction;
+        this.name = "BrokerProtocolError";
+    }
+}
+export function sidHash(sid) {
+    return createHash("sha256").update(sid, "utf8").digest("hex").slice(0, 24);
+}
+export function pipeNameForSid(sid) {
+    return `\\\\.\\pipe\\wowdump-frida-${sidHash(sid)}`;
+}
+export function canonicalPayloadHash(request) {
+    return createHash("sha256").update(stableJson({
+        clientId: request.clientId,
+        operation: request.operation,
+        pid: request.pid,
+        buildKey: request.buildKey,
+        payload: request.payload
+    })).digest("hex");
+}
+export function validateRequest(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail("FRAME_INVALID", "request must be an object");
+    const request = value;
+    if (request.schemaVersion !== BROKER_SCHEMA_VERSION || request.protocolVersion !== BROKER_PROTOCOL_VERSION) {
+        fail("PROTOCOL_VERSION_MISMATCH", "unsupported Broker schema or protocol version");
+    }
+    for (const key of ["requestId", "clientId", "operation"]) {
+        if (typeof request[key] !== "string" || !request[key].trim())
+            fail("FRAME_INVALID", `${key} must be a non-empty string`);
+    }
+    if (request.pid !== null && (!Number.isSafeInteger(request.pid) || request.pid <= 0))
+        fail("FRAME_INVALID", "pid must be null or a positive integer");
+    if (request.buildKey !== null && typeof request.buildKey !== "string")
+        fail("FRAME_INVALID", "buildKey must be null or a string");
+    if (!request.payload || typeof request.payload !== "object" || Array.isArray(request.payload))
+        fail("FRAME_INVALID", "payload must be an object");
+    return request;
+}
+export function encodeFrame(value) {
+    const body = Buffer.from(JSON.stringify(value), "utf8");
+    if (body.length > BROKER_MAX_FRAME_BYTES)
+        fail("FRAME_TOO_LARGE", `frame exceeds ${BROKER_MAX_FRAME_BYTES} bytes`);
+    const frame = Buffer.allocUnsafe(body.length + 4);
+    frame.writeUInt32LE(body.length, 0);
+    body.copy(frame, 4);
+    return frame;
+}
+export class FrameDecoder {
+    buffered = Buffer.alloc(0);
+    push(chunk) {
+        this.buffered = Buffer.concat([this.buffered, chunk]);
+        const values = [];
+        while (this.buffered.length >= 4) {
+            const length = this.buffered.readUInt32LE(0);
+            if (length > BROKER_MAX_FRAME_BYTES)
+                fail("FRAME_TOO_LARGE", `frame exceeds ${BROKER_MAX_FRAME_BYTES} bytes`);
+            if (this.buffered.length < length + 4)
+                break;
+            const body = this.buffered.subarray(4, length + 4);
+            this.buffered = this.buffered.subarray(length + 4);
+            try {
+                values.push(JSON.parse(body.toString("utf8")));
+            }
+            catch {
+                fail("FRAME_INVALID", "frame body is not valid JSON");
+            }
+        }
+        return values;
+    }
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`).join(",")}}`;
+    return JSON.stringify(value);
+}
+function fail(code, message) {
+    throw new BrokerProtocolError(code, message);
+}