wowdump 0.2.0 → 0.3.1

package/dist/windows-launcher.js

@@ -0,0 +1,207 @@
+import { randomBytes } from "node:crypto";
+import { createConnection } from "node:net";
+import { mkdir, open, readFile, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import koffi from "koffi";
+import { ReaderProtocolError } from "./reader-broker.js";
+function quoteWindowsArgument(value) {
+    if (value.length > 0 && !/[\s"]/u.test(value))
+        return value;
+    let result = '"';
+    let slashes = 0;
+    for (const character of value) {
+        if (character === "\\") {
+            slashes += 1;
+            continue;
+        }
+        if (character === '"') {
+            result += "\\".repeat(slashes * 2 + 1) + '"';
+            slashes = 0;
+            continue;
+        }
+        result += "\\".repeat(slashes) + character;
+        slashes = 0;
+    }
+    return result + "\\".repeat(slashes * 2) + '"';
+}
+export function buildWindowsCommandLine(args) {
+    return args.map(quoteWindowsArgument).join(" ");
+}
+export function shellExecuteRunAs(file, args, cwd) {
+    if (process.platform !== "win32")
+        throw new Error("ShellExecuteEx runas is only available on Windows");
+    const shell32 = koffi.load("shell32.dll");
+    const kernel32 = koffi.load("kernel32.dll");
+    const SHELLEXECUTEINFOW = koffi.struct("WOWDUMP_SHELLEXECUTEINFOW", {
+        cbSize: "uint32_t",
+        fMask: "uint32_t",
+        hwnd: "void *",
+        lpVerb: "str16",
+        lpFile: "str16",
+        lpParameters: "str16",
+        lpDirectory: "str16",
+        nShow: "int32_t",
+        hInstApp: "void *",
+        lpIDList: "void *",
+        lpClass: "str16",
+        hkeyClass: "void *",
+        dwHotKey: "uint32_t",
+        hIcon: "void *",
+        hProcess: "void *"
+    });
+    const ShellExecuteExW = shell32.func("bool __stdcall ShellExecuteExW(_Inout_ WOWDUMP_SHELLEXECUTEINFOW *info)");
+    const GetLastError = kernel32.func("uint32_t __stdcall GetLastError()");
+    const info = {
+        cbSize: koffi.sizeof(SHELLEXECUTEINFOW),
+        fMask: 0,
+        hwnd: null,
+        lpVerb: "runas",
+        lpFile: resolve(file),
+        lpParameters: buildWindowsCommandLine(args),
+        lpDirectory: resolve(cwd),
+        nShow: 0,
+        hInstApp: null,
+        lpIDList: null,
+        lpClass: null,
+        hkeyClass: null,
+        dwHotKey: 0,
+        hIcon: null,
+        hProcess: null
+    };
+    if (!ShellExecuteExW(info)) {
+        const win32 = Number(GetLastError());
+        const error = new Error(`ShellExecuteExW(runas) failed with Win32 error ${win32}`);
+        error.win32 = win32;
+        throw error;
+    }
+}
+function invocationRequest(invocation) {
+    return { command: invocation.command, ...invocation.payload };
+}
+function requestPipe(metadata, request, timeoutMs) {
+    return new Promise((resolveResult, reject) => {
+        const socket = createConnection({ host: metadata.host, port: metadata.port });
+        let buffer = "";
+        let settled = false;
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            if (error)
+                reject(error);
+            else
+                resolveResult(value);
+        };
+        const timer = setTimeout(() => finish(new Error(`reader broker request timed out after ${timeoutMs}ms`)), timeoutMs);
+        socket.setEncoding("utf8");
+        socket.once("connect", () => socket.write(`${JSON.stringify({ token: metadata.token, request })}\n`));
+        socket.on("data", chunk => {
+            buffer += chunk;
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            try {
+                finish(undefined, JSON.parse(buffer.slice(0, newline)));
+            }
+            catch (error) {
+                finish(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        socket.once("error", error => finish(error));
+        socket.once("end", () => { if (!settled)
+            finish(new Error("reader broker closed without a response")); });
+    });
+}
+async function pause(milliseconds) {
+    await new Promise(resolvePause => setTimeout(resolvePause, milliseconds));
+}
+export class WindowsBrokerManager {
+    metadataFile;
+    options;
+    constructor(options) {
+        this.options = { ...options, home: resolve(options.home), readerEntry: resolve(options.readerEntry) };
+        this.metadataFile = join(this.options.home, "runtime", "reader-broker.json");
+    }
+    async request(invocation) {
+        const request = invocationRequest(invocation);
+        const existing = await this.readMetadata();
+        if (existing) {
+            try {
+                return await requestPipe(existing, request, this.options.requestTimeoutMs ?? 30_000);
+            }
+            catch {
+                await rm(this.metadataFile, { force: true }).catch(() => undefined);
+            }
+        }
+        const metadata = await this.launchBroker();
+        return requestPipe(metadata, request, this.options.requestTimeoutMs ?? 30_000);
+    }
+    async readMetadata() {
+        try {
+            const value = JSON.parse(await readFile(this.metadataFile, "utf8"));
+            return value?.schema === "wowdump.reader-broker.v1"
+                && value.host === "127.0.0.1"
+                && Number.isSafeInteger(value.port)
+                && value.port > 0
+                && value.port <= 65535
+                && typeof value.token === "string"
+                ? value
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async launchBroker() {
+        await mkdir(dirname(this.metadataFile), { recursive: true });
+        const lockFile = `${this.metadataFile}.lock`;
+        let lock;
+        try {
+            lock = await open(lockFile, "wx", 0o600);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const deadline = Date.now() + (this.options.launchTimeoutMs ?? 30_000);
+            while (Date.now() < deadline) {
+                const metadata = await this.readMetadata();
+                if (metadata)
+                    return metadata;
+                await pause(100);
+            }
+            await rm(lockFile, { force: true }).catch(() => undefined);
+            return this.launchBroker();
+        }
+        const token = randomBytes(32).toString("hex");
+        const args = [this.options.readerEntry, "--listen", "127.0.0.1", "--port", "0", "--token", token, "--metadata", this.metadataFile];
+        const launch = this.options.launch ?? shellExecuteRunAs;
+        try {
+            try {
+                launch(this.options.nodeExecutable ?? process.execPath, args, dirname(this.options.readerEntry));
+            }
+            catch (error) {
+                const native = error;
+                throw new ReaderProtocolError("ELEVATION_FAILED", native.message, {
+                    verb: "runas",
+                    win32: native.win32 ?? null,
+                    requestedRights: ["PROCESS_QUERY_INFORMATION", "PROCESS_VM_READ"],
+                    readerEntry: this.options.readerEntry
+                });
+            }
+            const deadline = Date.now() + (this.options.launchTimeoutMs ?? 30_000);
+            while (Date.now() < deadline) {
+                const metadata = await this.readMetadata();
+                if (metadata?.token === token)
+                    return metadata;
+                await pause(100);
+            }
+            throw new Error(`elevated reader broker did not become ready within ${this.options.launchTimeoutMs ?? 30_000}ms`);
+        }
+        finally {
+            await lock.close().catch(() => undefined);
+            await rm(lockFile, { force: true }).catch(() => undefined);
+        }
+    }
+}

package/dist/windows-reader.js

@@ -0,0 +1,102 @@
+import koffi from "koffi";
+const PROCESS_QUERY_INFORMATION = 0x0400;
+const PROCESS_VM_READ = 0x0010;
+const HANDLE = koffi.pointer("WOWDUMP_HANDLE", koffi.opaque());
+const SIZE_T = process.arch === "x64" ? "uint64_t" : "uint32_t";
+const kernel32 = koffi.load("kernel32.dll");
+const shell32 = koffi.load("shell32.dll");
+const OpenProcess = kernel32.func("OpenProcess", HANDLE, ["uint32_t", "bool", "uint32_t"]);
+const ReadProcessMemory = kernel32.func("ReadProcessMemory", "bool", [HANDLE, "uint64_t", koffi.pointer("uint8_t"), SIZE_T, koffi.out(koffi.pointer(SIZE_T))]);
+const VirtualQueryEx = kernel32.func("VirtualQueryEx", SIZE_T, [HANDLE, "uint64_t", koffi.pointer("uint8_t"), SIZE_T]);
+const CloseHandle = kernel32.func("CloseHandle", "bool", [HANDLE]);
+const GetLastError = kernel32.func("GetLastError", "uint32_t", []);
+const IsUserAnAdmin = shell32.func("IsUserAnAdmin", "bool", []);
+function addressOf(handle) {
+    return `0x${koffi.address(handle).toString(16)}`;
+}
+function win32Error(operation) {
+    const win32 = Number(GetLastError());
+    const error = new Error(`${operation} failed with Win32 error ${win32}`);
+    error.code = "WIN32_ERROR";
+    error.win32 = win32;
+    return error;
+}
+class WindowsHandle {
+    raw;
+    pid;
+    id;
+    constructor(raw, pid) {
+        this.raw = raw;
+        this.pid = pid;
+        this.id = addressOf(raw);
+    }
+    close() {
+        if (this.raw !== null) {
+            CloseHandle(this.raw);
+            this.raw = null;
+        }
+    }
+}
+export class WindowsNativeReader {
+    async openProcess(pid, rights) {
+        const requested = rights.reduce((mask, right) => {
+            if (right === "PROCESS_QUERY_INFORMATION")
+                return mask | PROCESS_QUERY_INFORMATION;
+            if (right === "PROCESS_VM_READ")
+                return mask | PROCESS_VM_READ;
+            return mask;
+        }, 0);
+        const handle = OpenProcess(requested || PROCESS_QUERY_INFORMATION | PROCESS_VM_READ, false, pid);
+        if (!handle)
+            throw win32Error(`OpenProcess(${pid})`);
+        return new WindowsHandle(handle, pid);
+    }
+    async readProcessMemory(handle, address, size) {
+        const native = handle;
+        const bytes = Buffer.allocUnsafe(size);
+        const read = [0n];
+        const ok = ReadProcessMemory(native.raw, address, bytes, size, read);
+        const bytesRead = Number(read[0]);
+        if (!ok && bytesRead === 0)
+            throw win32Error(`ReadProcessMemory(${native.id}, ${`0x${address.toString(16)}`})`);
+        return { bytes: bytes.subarray(0, bytesRead), bytesRead };
+    }
+    async virtualQueryEx(handle, address) {
+        const native = handle;
+        const buffer = Buffer.alloc(48);
+        const result = Number(VirtualQueryEx(native.raw, address, buffer, buffer.length));
+        if (result === 0)
+            throw win32Error(`VirtualQueryEx(${native.id})`);
+        return {
+            baseAddress: `0x${buffer.readBigUInt64LE(0).toString(16)}`,
+            allocationBase: `0x${buffer.readBigUInt64LE(8).toString(16)}`,
+            allocationProtect: buffer.readUInt32LE(16),
+            regionSize: buffer.readBigUInt64LE(24).toString(),
+            state: buffer.readUInt32LE(32),
+            protect: buffer.readUInt32LE(36),
+            type: buffer.readUInt32LE(40),
+            bytesReturned: result
+        };
+    }
+    async isProcessAlive(pid) {
+        try {
+            const handle = await this.openProcess(pid, ["PROCESS_QUERY_INFORMATION"]);
+            handle.close();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    elevationStatus() {
+        return {
+            elevated: Boolean(IsUserAnAdmin()),
+            processArchitecture: process.arch,
+            backend: "koffi/kernel32",
+            requestedRights: ["PROCESS_QUERY_INFORMATION", "PROCESS_VM_READ"]
+        };
+    }
+}
+export function createWindowsNativeReader() {
+    return new WindowsNativeReader();
+}