wowdump 0.2.1 → 0.3.2

package/dist/reader/broker.js

@@ -0,0 +1,475 @@
+import { createInterface } from "node:readline";
+import { stdin, stdout } from "node:process";
+export const DEFAULT_IDLE_TIMEOUT_MS = 20 * 60 * 1000;
+export const DEFAULT_RIGHTS = Object.freeze([
+    "PROCESS_QUERY_INFORMATION",
+    "PROCESS_VM_READ"
+]);
+function hexAddress(value) {
+    const normalized = value.trim();
+    if (!/^0x[0-9a-f]+$/i.test(normalized)) {
+        throw new ReaderProtocolError("INVALID_ADDRESS", "address must be a hexadecimal 0x-prefixed string");
+    }
+    const address = BigInt(normalized);
+    if (address < 0n || address > 0xffffffffffffffffn) {
+        throw new ReaderProtocolError("INVALID_ADDRESS", "address is outside the 64-bit range");
+    }
+    return address;
+}
+function boundedSize(value, name, maximum = 16 * 1024 * 1024) {
+    const size = Number(value);
+    if (!Number.isSafeInteger(size) || size <= 0 || size > maximum) {
+        throw new ReaderProtocolError("INVALID_SIZE", `${name} must be an integer between 1 and ${maximum}`);
+    }
+    return size;
+}
+function boundedPid(value) {
+    const pid = Number(value);
+    if (!Number.isSafeInteger(pid) || pid <= 0 || pid > 0x7fffffff) {
+        throw new ReaderProtocolError("INVALID_PID", "pid must be a positive Windows process id");
+    }
+    return pid;
+}
+function toHex(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}
+function bytesFromResult(result) {
+    if (!result || !(result.bytes instanceof Uint8Array)) {
+        throw new ReaderProtocolError("NATIVE_RESULT", "native reader returned no byte buffer");
+    }
+    const bytesRead = result.bytesRead === undefined ? result.bytes.byteLength : Number(result.bytesRead);
+    if (!Number.isSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > result.bytes.byteLength) {
+        throw new ReaderProtocolError("NATIVE_RESULT", "native reader returned an invalid bytesRead value");
+    }
+    return { bytes: result.bytes.subarray(0, bytesRead), bytesRead };
+}
+export class ReaderProtocolError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "ReaderProtocolError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Placeholder backend used until the platform adapter is installed.  Keeping
+ * this explicit makes an unavailable native layer observable to the caller.
+ */
+export class UnavailableNativeReader {
+    diagnostic() {
+        throw new ReaderProtocolError("NATIVE_BACKEND_UNAVAILABLE", "Windows native reader backend is not installed", {
+            platform: process.platform,
+            requestedRights: [...DEFAULT_RIGHTS],
+            elevation: this.elevationStatus()
+        });
+    }
+    openProcess(_pid, _rights) {
+        return Promise.reject(this.diagnostic());
+    }
+    readProcessMemory(_handle, _address, _size) {
+        return Promise.reject(this.diagnostic());
+    }
+    elevationStatus() {
+        return {
+            isWindows: process.platform === "win32",
+            elevated: false,
+            state: "unknown",
+            reason: "native elevation probe is not installed"
+        };
+    }
+}
+export class ReaderBroker {
+    idleTimeoutMs;
+    backend;
+    now;
+    onShutdown;
+    runFrida;
+    handles = new Map();
+    watches = new Map();
+    idleTimer;
+    watchCounter = 0;
+    stopped = false;
+    constructor(options = {}) {
+        this.backend = options.backend ?? new UnavailableNativeReader();
+        this.idleTimeoutMs = Math.max(1, Math.floor(options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS));
+        this.now = options.now ?? Date.now;
+        this.onShutdown = options.onShutdown;
+        this.runFrida = options.runFrida;
+        this.armIdleTimer();
+    }
+    get isStopped() {
+        return this.stopped;
+    }
+    get activeHandleCount() {
+        return this.handles.size;
+    }
+    get activeWatchCount() {
+        return [...this.watches.values()].filter(watch => !watch.stopped).length;
+    }
+    /** Handle one already-decoded request. Suitable for a CLI client or tests. */
+    async handle(request) {
+        const command = typeof request?.command === "string" ? request.command : "unknown";
+        const base = { id: request?.id, ok: true, command, timestamp: this.now() };
+        if (this.stopped) {
+            return { ...base, ok: false, error: { code: "BROKER_STOPPED", message: "reader broker is stopped" } };
+        }
+        try {
+            const result = await this.dispatch(request);
+            this.armIdleTimer();
+            return { ...base, ...result, ok: true };
+        }
+        catch (error) {
+            this.armIdleTimer();
+            return { ...base, ok: false, error: serializeError(error, this.backend) };
+        }
+    }
+    async shutdown(reason = "request") {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        for (const watch of this.watches.values())
+            watch.stopped = true;
+        this.watches.clear();
+        const handles = [...this.handles.values()];
+        this.handles.clear();
+        for (const handle of handles) {
+            await Promise.resolve(handle.close()).catch(() => undefined);
+        }
+        await Promise.resolve(this.backend.close?.()).catch(() => undefined);
+        await Promise.resolve(this.onShutdown?.(reason)).catch(() => undefined);
+    }
+    armIdleTimer() {
+        if (this.stopped)
+            return;
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => {
+            void this.shutdown("idle");
+        }, this.idleTimeoutMs);
+        // A broker should not keep an otherwise idle CLI event loop alive in tests.
+        this.idleTimer.unref?.();
+    }
+    async dispatch(request) {
+        switch (request.command) {
+            case "status":
+                return {
+                    pid: process.pid,
+                    idleTimeoutMs: this.idleTimeoutMs,
+                    activeHandles: this.handles.size,
+                    activeWatches: this.activeWatchCount,
+                    elevation: await Promise.resolve(this.backend.elevationStatus?.() ?? { state: "unknown" })
+                };
+            case "frida":
+                if (!this.runFrida)
+                    throw new ReaderProtocolError("FRIDA_NOT_CONFIGURED", "elevated Frida runner is not configured");
+                return this.runFrida(request);
+            case "modules":
+                return this.modules(request);
+            case "open":
+                return this.open(request);
+            case "close":
+                return this.close(request);
+            case "read":
+                return this.read(request);
+            case "watch.start":
+                return this.watchStart(request);
+            case "watch.poll":
+                return this.watchPoll(request);
+            case "watch.stop":
+                return this.watchStop(request);
+            case "shutdown":
+                await this.shutdown("request");
+                return { stopped: true };
+            default:
+                throw new ReaderProtocolError("UNKNOWN_COMMAND", `unsupported reader command: ${String(request?.command)}`);
+        }
+    }
+    async getHandle(pid, requested) {
+        const existing = this.handles.get(pid);
+        if (existing && (!requested || requested === existing.id))
+            return existing;
+        if (requested && existing?.id !== requested) {
+            throw new ReaderProtocolError("HANDLE_MISMATCH", `handle ${requested} is not open for pid ${pid}`);
+        }
+        const handle = await this.backend.openProcess(pid, DEFAULT_RIGHTS);
+        this.handles.set(pid, handle);
+        return handle;
+    }
+    async open(request) {
+        const pid = boundedPid(request.pid);
+        const rights = request.rights?.length ? [...request.rights] : [...DEFAULT_RIGHTS];
+        const handle = await this.backend.openProcess(pid, rights);
+        const previous = this.handles.get(pid);
+        if (previous && previous !== handle)
+            await Promise.resolve(previous.close()).catch(() => undefined);
+        this.handles.set(pid, handle);
+        return { pid, handle: handle.id, rights };
+    }
+    async close(request) {
+        const pid = request.pid === undefined ? undefined : boundedPid(request.pid);
+        const handle = pid === undefined
+            ? [...this.handles.values()].find(candidate => candidate.id === request.handle)
+            : this.handles.get(pid);
+        if (!handle)
+            return { closed: false, pid, handle: request.handle };
+        await Promise.resolve(handle.close());
+        if (pid !== undefined)
+            this.handles.delete(pid);
+        else
+            for (const [key, candidate] of this.handles)
+                if (candidate === handle)
+                    this.handles.delete(key);
+        for (const watch of this.watches.values()) {
+            if (watch.handle === handle)
+                watch.stopped = true;
+        }
+        return { closed: true, pid, handle: handle.id };
+    }
+    async read(request) {
+        const pid = boundedPid(request.pid);
+        const address = hexAddress(request.address);
+        const size = boundedSize(request.size, "size");
+        const handle = await this.getHandle(pid, request.handle);
+        const startedAt = this.now();
+        const native = bytesFromResult(await this.backend.readProcessMemory(handle, address, size));
+        return {
+            pid,
+            handle: handle.id,
+            address: `0x${address.toString(16)}`,
+            requestedSize: size,
+            bytesRead: native.bytesRead,
+            dataHex: toHex(native.bytes),
+            complete: native.bytesRead === size,
+            startedAt,
+            finishedAt: this.now()
+        };
+    }
+    async modules(request) {
+        const pid = boundedPid(request.pid);
+        if (!this.backend.enumerateModules) {
+            throw new ReaderProtocolError("MODULE_ENUM_UNAVAILABLE", "native module enumeration is not installed");
+        }
+        return { pid, modules: await this.backend.enumerateModules(pid) };
+    }
+    async watchStart(request) {
+        const pid = boundedPid(request.pid);
+        const address = hexAddress(request.address);
+        const size = boundedSize(request.size, "size", 1024 * 1024);
+        const intervalMs = Math.min(60 * 60 * 1000, Math.max(10, Math.floor(Number(request.intervalMs ?? 1000))));
+        const maxSamples = Math.min(100000, Math.max(1, Math.floor(Number(request.maxSamples ?? 0) || 100000)));
+        const handle = await this.getHandle(pid, request.handle);
+        const id = `watch-${++this.watchCounter}`;
+        this.watches.set(id, {
+            id,
+            pid,
+            address,
+            size,
+            intervalMs,
+            changeOnly: request.changeOnly === true,
+            maxSamples,
+            handle,
+            sequence: 0,
+            nextDue: this.now(),
+            stopped: false
+        });
+        return { watchId: id, pid, handle: handle.id, address: `0x${address.toString(16)}`, size, intervalMs, changeOnly: request.changeOnly === true, maxSamples };
+    }
+    async watchPoll(request) {
+        if (!request.watchId || typeof request.watchId !== "string")
+            throw new ReaderProtocolError("INVALID_WATCH", "watchId is required");
+        const watch = this.watches.get(request.watchId);
+        if (!watch || watch.stopped)
+            return { watchId: request.watchId, stopped: true, events: [] };
+        const now = this.now();
+        if (now < watch.nextDue)
+            return { watchId: watch.id, stopped: false, events: [], nextDue: watch.nextDue };
+        watch.nextDue = now + watch.intervalMs;
+        if (watch.sequence >= watch.maxSamples) {
+            watch.stopped = true;
+            return { watchId: watch.id, stopped: true, reason: "max_samples", events: [] };
+        }
+        if (this.backend.isProcessAlive && !(await this.backend.isProcessAlive(watch.pid))) {
+            watch.stopped = true;
+            return { watchId: watch.id, stopped: true, reason: "target_exited", events: [{ type: "target_exited", pid: watch.pid, sequence: watch.sequence + 1, timestamp: now }] };
+        }
+        try {
+            const native = bytesFromResult(await this.backend.readProcessMemory(watch.handle, watch.address, watch.size));
+            const changed = !watch.lastBytes || !equalBytes(watch.lastBytes, native.bytes);
+            watch.sequence += 1;
+            const event = {
+                type: changed ? "snapshot" : "unchanged",
+                watchId: watch.id,
+                pid: watch.pid,
+                sequence: watch.sequence,
+                timestamp: this.now(),
+                address: `0x${watch.address.toString(16)}`,
+                requestedSize: watch.size,
+                bytesRead: native.bytesRead,
+                complete: native.bytesRead === watch.size,
+                dataHex: toHex(native.bytes),
+                changed
+            };
+            const previous = watch.lastBytes;
+            watch.lastBytes = new Uint8Array(native.bytes);
+            if (watch.changeOnly && !changed)
+                return { watchId: watch.id, stopped: false, events: [], sequence: watch.sequence };
+            return { watchId: watch.id, stopped: false, events: [event], previousHex: previous ? toHex(previous) : undefined, sequence: watch.sequence };
+        }
+        catch (error) {
+            watch.stopped = true;
+            return { watchId: watch.id, stopped: true, reason: "reader_error", events: [{ type: "reader_error", watchId: watch.id, pid: watch.pid, sequence: watch.sequence + 1, timestamp: this.now(), error: serializeError(error, this.backend) }] };
+        }
+    }
+    async watchStop(request) {
+        if (!request.watchId || typeof request.watchId !== "string")
+            throw new ReaderProtocolError("INVALID_WATCH", "watchId is required");
+        const watch = this.watches.get(request.watchId);
+        if (!watch)
+            return { watchId: request.watchId, stopped: false };
+        watch.stopped = true;
+        this.watches.delete(request.watchId);
+        return { watchId: request.watchId, stopped: true, sequence: watch.sequence };
+    }
+}
+function equalBytes(left, right) {
+    if (left.byteLength !== right.byteLength)
+        return false;
+    for (let index = 0; index < left.byteLength; index += 1)
+        if (left[index] !== right[index])
+            return false;
+    return true;
+}
+function serializeError(error, backend) {
+    if (error instanceof ReaderProtocolError) {
+        return { code: error.code, message: error.message, ...(error.details ? { details: error.details } : {}) };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        code: "READER_ERROR",
+        message,
+        elevation: backend.elevationStatus ? backend.elevationStatus() : { state: "unknown" }
+    };
+}
+/** Start a JSONL broker process over stdio. */
+export function serveReaderBroker(options = {}) {
+    const broker = new ReaderBroker({ ...options, attachStdio: false });
+    if (options.attachStdio !== false) {
+        const input = options.input ?? stdin;
+        const output = options.output ?? stdout;
+        const rl = createInterface({ input, crlfDelay: Infinity });
+        // Preserve JSONL request order so open/read/close sequences cannot race.
+        let pending = Promise.resolve();
+        rl.on("line", line => {
+            pending = pending.then(async () => {
+                if (!line.trim())
+                    return;
+                let request;
+                try {
+                    request = JSON.parse(line);
+                }
+                catch (error) {
+                    const response = {
+                        ok: false,
+                        command: "parse",
+                        timestamp: Date.now(),
+                        error: { code: "INVALID_JSON", message: error instanceof Error ? error.message : String(error) }
+                    };
+                    output.write(`${JSON.stringify(response)}\n`);
+                    return;
+                }
+                const response = await broker.handle(request);
+                output.write(`${JSON.stringify(response)}\n`);
+                if (request.command === "shutdown")
+                    rl.close();
+            });
+        });
+        const close = () => { void broker.shutdown("request"); };
+        input.once("close", close);
+        input.once("error", close);
+    }
+    return broker;
+}
+/** Small typed client used by the CLI; transport owns process/UAC reuse. */
+export class ReaderClient {
+    transport;
+    requestTimeoutMs;
+    counter = 0;
+    constructor(options) {
+        this.transport = options.transport;
+        this.requestTimeoutMs = Math.max(1, Math.floor(options.requestTimeoutMs ?? 30_000));
+    }
+    async request(request) {
+        const id = request.id ?? `req-${++this.counter}`;
+        const line = await withTimeout(this.transport.request(JSON.stringify({ ...request, id })), this.requestTimeoutMs);
+        const response = JSON.parse(line);
+        if (!response || typeof response !== "object" || typeof response.ok !== "boolean") {
+            throw new ReaderProtocolError("INVALID_RESPONSE", "reader broker returned an invalid JSONL response");
+        }
+        return response;
+    }
+    close() {
+        return Promise.resolve(this.transport.close?.());
+    }
+}
+function withTimeout(promise, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new ReaderProtocolError("REQUEST_TIMEOUT", `reader request timed out after ${timeoutMs}ms`)), timeoutMs);
+        timer.unref?.();
+        promise.then(value => { clearTimeout(timer); resolve(value); }, error => { clearTimeout(timer); reject(error); });
+    });
+}
+export function createElevatedLaunchSpec(file, args = []) {
+    if (!file.trim())
+        throw new TypeError("elevated broker file must be non-empty");
+    return Object.freeze({ file, args: [...args], verb: "runas", windowsHide: false });
+}
+/** Reuse one broker client and invoke the launcher only after the first miss. */
+export class ReaderBrokerPool {
+    client;
+    launching;
+    launcher;
+    launchSpec;
+    requestTimeoutMs;
+    constructor(launcher, launchSpec, requestTimeoutMs) {
+        this.launcher = launcher;
+        this.launchSpec = launchSpec;
+        this.requestTimeoutMs = requestTimeoutMs;
+    }
+    async request(request) {
+        const client = await this.getClient();
+        try {
+            return await client.request(request);
+        }
+        catch (error) {
+            // A dead broker is discarded; the next request gets a fresh UAC launch.
+            this.client = undefined;
+            throw error;
+        }
+    }
+    async close() {
+        const client = this.client;
+        this.client = undefined;
+        await client?.close();
+    }
+    async getClient() {
+        if (this.client)
+            return this.client;
+        if (!this.launching) {
+            this.launching = this.launcher.launch(this.launchSpec).then(result => {
+                this.client = new ReaderClient({ transport: result.transport, requestTimeoutMs: this.requestTimeoutMs });
+                return this.client;
+            }).catch(error => {
+                throw new ReaderProtocolError("ELEVATION_FAILED", error instanceof Error ? error.message : String(error), {
+                    verb: this.launchSpec.verb,
+                    requestedRights: [...DEFAULT_RIGHTS],
+                    elevation: "launch rejected or cancelled"
+                });
+            }).finally(() => { this.launching = undefined; });
+        }
+        return this.launching;
+    }
+}

package/dist/reader/client.js

@@ -0,0 +1 @@
+export { ReaderClient, ReaderBrokerPool, ReaderProtocolError, createElevatedLaunchSpec } from "./broker.js";

package/dist/reader/launcher.js

@@ -0,0 +1,219 @@
+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 "./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(() => {
+            const error = new Error(`reader broker request timed out after ${timeoutMs}ms`);
+            error.code = "BROKER_REQUEST_TIMEOUT";
+            finish(error);
+        }, 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) {
+            const requestTimeout = invocation.command === "frida"
+                ? Math.max(this.options.requestTimeoutMs ?? 30_000, Math.min(600_000, Number(invocation.payload.timeoutMs ?? 120_000) + 10_000))
+                : this.options.requestTimeoutMs ?? 30_000;
+            try {
+                return await requestPipe(existing, request, requestTimeout);
+            }
+            catch (error) {
+                const code = error.code;
+                // A long-running Frida request is not evidence that the broker died.
+                // Keep its metadata so the next command reuses the elevated process.
+                if (code === "BROKER_REQUEST_TIMEOUT")
+                    throw error;
+                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);
+        }
+    }
+}