reverseport 0.0.0-stage → 1.2.0

package/dist/ghidra/GhidraPspExtension.js

@@ -0,0 +1,144 @@
+import { createHash } from "node:crypto";
+import { lstat, opendir, realpath } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { z } from "zod";
+import { openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+/** Installed processor code and data, distinct from REA's analysis-extension ABI. */
+export const ghidraPspExtensionSchema = z.strictObject({
+    id: z.literal("ghidra-allegrex"),
+    root: z.string().refine(isAbsolute),
+    ghidra_version: z.string().min(1),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+});
+// Resource bounds for scanning a caller-installed extension, not target limits.
+const MAX_ENTRIES = 1024;
+const MAX_BYTES = 64 * 1024 * 1024;
+const MAX_DEPTH = 16;
+const REQUIRED = [
+    "Module.manifest",
+    "extension.properties",
+    "data/languages/allegrex.ldefs",
+    "data/languages/allegrex.sla",
+    "data/languages/allegrex.pspec",
+    "data/languages/allegrex.cspec",
+];
+/** Read-only fingerprint of all installed files; no home scanning or installation. */
+export const inspectGhidraPspExtension = async (root, ghidraVersion, signal) => {
+    signal?.throwIfAborted();
+    if (!isAbsolute(root) || (await realpath(root)) !== root)
+        throw new Error("The installed Allegrex directory must be a canonical non-symlink path.");
+    const files = [];
+    let entries = 1; // The root itself consumes one inventory entry.
+    const visit = async (relative, depth) => {
+        signal?.throwIfAborted();
+        if (depth > MAX_DEPTH)
+            throw new Error("Allegrex extension directory nesting exceeds the inspection limit.");
+        const path = join(root, relative);
+        const metadata = await lstat(path);
+        if (metadata.isDirectory()) {
+            const children = [];
+            for await (const child of await opendir(path)) {
+                signal?.throwIfAborted();
+                if (++entries > MAX_ENTRIES)
+                    throw new Error("Allegrex extension inventory exceeds the inspection limit.");
+                children.push(child.name);
+            }
+            children.sort();
+            for (const child of children)
+                await visit(relative === "" ? child : `${relative}/${child}`, depth + 1);
+        }
+        else if (metadata.isFile()) {
+            files.push(relative);
+        }
+        else
+            throw new Error(`Allegrex extension entries must be regular files or directories: ${relative}`);
+    };
+    await visit("", 0);
+    for (const required of REQUIRED)
+        if (!files.includes(required))
+            throw new Error(`Missing installed Allegrex component: ${required}`);
+    if (!files.some((path) => path.startsWith("lib/") && path.endsWith(".jar")))
+        throw new Error("The installed Allegrex extension has no loader JAR.");
+    const hash = createHash("sha256");
+    let bytesRead = 0;
+    let properties = "";
+    for (const relative of files) {
+        signal?.throwIfAborted();
+        const path = join(root, relative);
+        const handle = await openRegularFile(path, { symlinks: "reject", signal });
+        try {
+            const before = await handle.stat();
+            if (!Number.isSafeInteger(before.size) ||
+                before.size > MAX_BYTES - bytesRead)
+                throw new Error("Allegrex extension bytes exceed the inspection limit.");
+            if (relative === "extension.properties" && before.size > 65536)
+                throw new Error("Allegrex extension properties exceed the inspection limit.");
+            hash.update(JSON.stringify([relative, before.size]));
+            const buffer = Buffer.alloc(Math.min(65536, before.size + 1));
+            let offset = 0;
+            const chunks = [];
+            while (offset < before.size) {
+                signal?.throwIfAborted();
+                const read = await handle.read(buffer, 0, Math.min(buffer.length, before.size - offset), offset);
+                if (read.bytesRead === 0)
+                    throw new Error(`Truncated Allegrex component: ${relative}`);
+                const chunk = buffer.subarray(0, read.bytesRead);
+                hash.update(chunk);
+                if (relative === "extension.properties")
+                    chunks.push(Buffer.from(chunk));
+                offset += read.bytesRead;
+            }
+            if (!sameRegularFileState(before, await handle.stat()) ||
+                !sameRegularFileState(before, await lstat(path)))
+                throw new Error(`Allegrex component changed during inspection: ${relative}`);
+            bytesRead += before.size;
+            if (relative === "extension.properties")
+                properties = Buffer.concat(chunks).toString("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    // Ghidra's extension.properties version is the compatible Ghidra version,
+    // not the extension release (e.g. v21.4); content identity supplies the latter.
+    const property = (name) => {
+        const values = properties.split(/\r?\n/u).flatMap((line) => {
+            const match = /^\s*([A-Za-z][A-Za-z0-9]*)\s*=\s*(.*?)\s*$/u.exec(line);
+            return match?.[1] === name ? [match[2] ?? ""] : [];
+        });
+        if (values.length !== 1)
+            throw new Error(`Allegrex extension must declare exactly one ${name}.`);
+        return values[0] ?? "";
+    };
+    if (property("name") !== "ghidra-allegrex" ||
+        property("version") !== ghidraVersion)
+        throw new Error(`Allegrex extension metadata does not match the selected Ghidra ${ghidraVersion}; install or rebuild a compatible extension.`);
+    signal?.throwIfAborted();
+    return {
+        id: "ghidra-allegrex",
+        root,
+        ghidra_version: ghidraVersion,
+        sha256: hash.digest("hex"),
+    };
+};
+/** Resolve prerequisites before opening or admitting cached PSP analysis. */
+export const resolveGhidraPspExtension = async (installation, signal) => {
+    if (signal?.aborted)
+        return err(new AnalysisCancelledError("resolve_analysis_profile"));
+    try {
+        if (installation.status !== "available" ||
+            installation.platform !== "linux" ||
+            installation.architecture !== "x64")
+            throw new Error("The initial PSP profile requires a supported Linux x64 Ghidra installation.");
+        const root = join(await realpath(installation.installDir), "Ghidra", "Extensions", "ghidra-allegrex");
+        return ok(await inspectGhidraPspExtension(root, installation.providerVersion, signal));
+    }
+    catch (cause) {
+        if (signal?.aborted)
+            return err(new AnalysisCancelledError("resolve_analysis_profile"));
+        const reason = `PSP_EXTENSION_UNAVAILABLE: ${cause instanceof Error ? cause.message : String(cause)} Use a compatible caller-installed ghidra-allegrex under GHIDRA_INSTALL_DIR/Ghidra/Extensions; REA does not install it.`;
+        return err(new AnalysisCapabilityUnavailableError("ghidra", "resolve_analysis_profile", reason, { cause, userMessage: reason }));
+    }
+};

package/dist/ghidra/GhidraPspProfile.js

@@ -0,0 +1,50 @@
+import { ghidraMipsUnsupportedReason } from "./GhidraMipsProfile.js";
+/** Allegrex's ELF machine declaration, not a filename or inferred instruction. */
+export const isGhidraPspTarget = (target) => target.kind === "executable" &&
+    target.format === "elf" &&
+    target.architecture === "mips" &&
+    target.mips !== undefined &&
+    (target.mips.flags & 0x00ff0000) === 0x00a20000;
+/** PSP has its own verified interpretation; generic MIPS rules remain unchanged. */
+export const ghidraProcessorUnsupportedReason = (target) => {
+    if (target.kind !== "executable" ||
+        target.architecture !== "mips" ||
+        !isGhidraPspTarget(target))
+        return ghidraMipsUnsupportedReason(target);
+    const metadata = target.mips;
+    if (metadata === undefined)
+        return "PSP analysis requires ELF metadata.";
+    if (metadata.elfClass !== 32 || metadata.byteOrder !== "little")
+        return "The PSP Allegrex profile requires little-endian ELF32.";
+    if (metadata.type !== 2)
+        return "The PSP Allegrex profile supports static ET_EXEC only; PRX, shared and relocatable images require separate verification.";
+    // PSPSDK emits MIPS-II / Allegrex / EABI32 with NOREORDER. Do not accept
+    // unknown producer flags or treat this as proof of instruction semantics.
+    if (metadata.flags !== 0x10a23001)
+        return "The PSP Allegrex profile requires the verified PSPSDK ELF declaration 0x10a23001; other ISA/ABI/ASE flags are not inferred.";
+    const abi = metadata.abiFlags;
+    if (abi === undefined || abi === null)
+        return "The PSP Allegrex profile requires an inspected separate MIPS ABI flags record; missing declarations are not inferred.";
+    // PSPDEV v20261001: GNU readelf 2.44 and the 24-byte record agree on
+    // MIPS II, 32-bit registers, single-precision hard float and flags1=1.
+    // This is a bounded producer declaration, not a claim about VFPU semantics.
+    if (abi.version !== 0 ||
+        abi.isaLevel !== 2 ||
+        abi.isaRevision !== 0 ||
+        abi.gprSize !== 1 ||
+        abi.cpr1Size !== 1 ||
+        abi.cpr2Size !== 0 ||
+        abi.fpAbi !== 2 ||
+        abi.isaExtension !== 0 ||
+        abi.ases !== 0 ||
+        abi.flags1 !== 1 ||
+        abi.flags2 !== 0)
+        return "The separate MIPS ABI flags record does not match the verified PSP MIPS-II/32-bit/single-float declaration; other versions, register modes and extension flags require separate verification.";
+    return null;
+};
+/** Propagated with every PSP observation, including successful decompilation. */
+export const GHIDRA_PSP_LIMITATIONS = [
+    "PSP/Allegrex analysis uses the caller-installed ghidra-allegrex extension. ELF declarations and selected instruction checks are not proof of runtime semantics.",
+    "ghidra-allegrex does not model VFPU prefix effects completely in decompiled output. Verify vector behavior independently; pseudocode is not an execution oracle.",
+    "This PSP profile covers static ELF32 ET_EXEC only. PRX relocations, PBP/ISO containers, live overlays and PSP emulation are outside this verified lane.",
+];

package/dist/ghidra/GhidraRawBinaryLanguage.js

@@ -0,0 +1,18 @@
+/**
+ * Map the four caller-visible CPU families to little-endian generic Ghidra
+ * languages with a supported generic compiler specification. These are
+ * analysis conventions, not evidence of the target's original compiler.
+ * Big-endian, Thumb-only, and Cortex-M variants are out of scope.
+ */
+export const ghidraRawBinaryLanguage = (architecture) => {
+    switch (architecture) {
+        case "x86":
+            return { languageId: "x86:LE:32:default", compilerSpecId: "gcc" };
+        case "x86_64":
+            return { languageId: "x86:LE:64:default", compilerSpecId: "gcc" };
+        case "arm":
+            return { languageId: "ARM:LE:32:v7", compilerSpecId: "default" };
+        case "arm64":
+            return { languageId: "AARCH64:LE:64:v8A", compilerSpecId: "default" };
+    }
+};

package/dist/ghidra/GhidraRequestQueue.js

@@ -0,0 +1,115 @@
+import { err } from "../domain/result.js";
+/** FIFO that admits one Ghidra Program request at a time. */
+export class GhidraRequestQueue {
+    execute;
+    failure;
+    onActiveCancellation;
+    #queue = [];
+    #active = false;
+    #closedFailure;
+    constructor(execute, failure, onActiveCancellation) {
+        this.execute = execute;
+        this.failure = failure;
+        this.onActiveCancellation = onActiveCancellation;
+    }
+    /** Queue one request until it completes, is cancelled, or the session closes. */
+    run(method, parameters, options) {
+        if (this.#closedFailure !== undefined)
+            return Promise.resolve(err(this.#closedFailure));
+        if (options.signal?.aborted === true)
+            return Promise.resolve(err(this.failure("cancelled", "Ghidra request was cancelled")));
+        return new Promise((resolve) => {
+            let entry;
+            const onAbort = options.signal === undefined
+                ? undefined
+                : () => this.#rejectQueued(entry, err(this.failure("cancelled", "Ghidra request was cancelled")));
+            entry = {
+                method,
+                parameters,
+                signal: options.signal,
+                resolve,
+                onAbort,
+            };
+            this.#queue.push(entry);
+            if (onAbort !== undefined)
+                options.signal?.addEventListener("abort", onAbort, { once: true });
+            this.#drain();
+        });
+    }
+    /** Fail requests that have not crossed the socket during session cleanup. */
+    failQueued(failure) {
+        this.#closedFailure = failure;
+        for (const entry of this.#queue.splice(0)) {
+            this.#release(entry);
+            entry.resolve(err(failure));
+        }
+    }
+    /** Admit requests after the owning client completes a new session startup. */
+    reopen() {
+        this.#closedFailure = undefined;
+    }
+    #drain() {
+        if (this.#active)
+            return;
+        const entry = this.#queue.shift();
+        if (entry === undefined)
+            return;
+        this.#release(entry);
+        if (entry.signal?.aborted === true) {
+            entry.resolve(err(this.failure("cancelled", "Ghidra request was cancelled")));
+            this.#drain();
+            return;
+        }
+        this.#active = true;
+        let executionSettled = false;
+        let activeCancellation;
+        const onAbort = entry.signal === undefined
+            ? undefined
+            : () => {
+                if (executionSettled)
+                    return;
+                this.failQueued(this.failure("process", "Ghidra session closed after active request cancellation"));
+                activeCancellation = this.onActiveCancellation();
+            };
+        if (onAbort !== undefined)
+            entry.signal?.addEventListener("abort", onAbort, { once: true });
+        void this.execute(entry.method, entry.parameters, entry.signal === undefined ? {} : { signal: entry.signal })
+            .then(async (result) => {
+            if (activeCancellation !== undefined) {
+                try {
+                    await activeCancellation;
+                }
+                catch (cause) {
+                    result = err(this.failure("process", cause instanceof Error
+                        ? `Ghidra cleanup after cancellation failed: ${cause.message}`
+                        : "Ghidra cleanup after cancellation failed", cause));
+                }
+            }
+            executionSettled = true;
+            entry.resolve(result);
+        })
+            .catch((cause) => {
+            executionSettled = true;
+            entry.resolve(err(this.failure("protocol", "Ghidra serial request execution rejected unexpectedly", cause)));
+        })
+            .finally(() => {
+            if (entry.signal !== undefined && onAbort !== undefined)
+                entry.signal.removeEventListener("abort", onAbort);
+            this.#active = false;
+            if (this.#closedFailure === undefined)
+                this.#drain();
+        });
+    }
+    #rejectQueued(entry, result) {
+        const index = this.#queue.indexOf(entry);
+        if (index < 0)
+            return;
+        this.#queue.splice(index, 1);
+        this.#release(entry);
+        entry.resolve(result);
+    }
+    #release(entry) {
+        if (entry.signal !== undefined && entry.onAbort !== undefined)
+            entry.signal.removeEventListener("abort", entry.onAbort);
+    }
+}

package/dist/ghidra/GhidraResponseBuffer.js

@@ -0,0 +1,31 @@
+/** Splits fragmented UTF-8 socket data into response lines. */
+export class GhidraResponseBuffer {
+    #options;
+    #buffer = "";
+    #fragments = [];
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Consume one decoded socket chunk. */
+    push(chunk) {
+        this.#fragments.push(chunk);
+        if (!chunk.includes("\n"))
+            return;
+        this.#buffer += this.#fragments.join("");
+        this.#fragments = [];
+        let newline = this.#buffer.indexOf("\n");
+        while (newline >= 0) {
+            const encodedLine = this.#buffer.slice(0, newline);
+            this.#buffer = this.#buffer.slice(newline + 1);
+            const line = encodedLine.trim();
+            if (line.length > 0)
+                this.#options.onLine(line);
+            newline = this.#buffer.indexOf("\n");
+        }
+    }
+    /** Drop any incomplete line when a session closes. */
+    reset() {
+        this.#buffer = "";
+        this.#fragments = [];
+    }
+}

package/dist/ghidra/GhidraResponseRouter.js

@@ -0,0 +1,24 @@
+import { err } from "../domain/result.js";
+import { ghidraResponseResult, parseGhidraResponseLine } from "./protocol.js";
+/** Routes validated response IDs without giving the wire protocol client state. */
+export class GhidraResponseRouter {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Parse and settle one complete response line. */
+    route(line) {
+        const parsed = parseGhidraResponseLine(line);
+        if (!parsed.ok) {
+            this.#options.protocolFailure(parsed.error.message, parsed.error);
+            return;
+        }
+        if (!this.#options.pending.has(parsed.value.id)) {
+            if (parsed.value.id >= this.#options.nextId())
+                this.#options.protocolFailure("Ghidra returned an unknown response id");
+            return;
+        }
+        const result = ghidraResponseResult(parsed.value);
+        this.#options.pending.settle(parsed.value.id, result.ok ? result : err(this.#options.remoteFailure(result.error)));
+    }
+}

package/dist/ghidra/GhidraSessionError.js

@@ -0,0 +1,180 @@
+import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";
+import { boundedUtf8Text } from "../process/boundedUtf8Text.js";
+import { GhidraLaunchError } from "./GhidraLauncher.js";
+const MAX_CAUSE_DEPTH = 3;
+const MAX_CAUSE_MESSAGE_BYTES = 2 * 1024;
+const MAX_CAUSE_FIELD_BYTES = 1024;
+const MAX_COMPILER_STDERR_BYTES = 8 * 1024;
+const MAX_LAUNCH_COMMAND_OUTPUT_BYTES = 8 * 1024;
+/** Provider-owned failure with bounded, token-redacted local diagnostics. */
+export class GhidraSessionError extends Error {
+    kind;
+    diagnostics;
+    timeoutMs;
+    remoteCode;
+    cleanupFailure;
+    constructor(kind, message, diagnostics = {}, options = {}) {
+        super(message, options);
+        this.kind = kind;
+        this.name = "GhidraSessionError";
+        this.diagnostics = structuredClone(diagnostics);
+        this.timeoutMs = options.timeoutMs;
+        this.remoteCode = options.remoteCode;
+        this.cleanupFailure = options.cleanupFailure;
+    }
+}
+/** Build a session failure while preserving bounded remote failure metadata. */
+const createGhidraSessionError = (failure) => new GhidraSessionError(failure.kind, failure.message, {
+    ...failure.diagnostics,
+    failure_kind: failure.kind,
+    failure_message: failure.message,
+    ...(failure.remoteCode === undefined
+        ? {}
+        : {
+            remote_code: failure.redact(failure.remoteCode),
+            remote_message: failure.message,
+        }),
+}, {
+    ...(failure.cause === undefined ? {} : { cause: failure.cause }),
+    ...(failure.timeoutMs === undefined
+        ? {}
+        : { timeoutMs: failure.timeoutMs }),
+    ...(failure.remoteCode === undefined
+        ? {}
+        : { remoteCode: failure.remoteCode }),
+});
+/** Bind session-failure construction to a live, token-redacted diagnostic view. */
+export const bindGhidraSessionFailure = (diagnostics, redact = (value) => value) => (kind, message, cause, options = {}) => createGhidraSessionError({
+    kind,
+    message: redact(message),
+    diagnostics: {
+        ...diagnostics(),
+        ...(cause === undefined
+            ? {}
+            : { failure_cause: describeCause(cause, redact) }),
+    },
+    redact,
+    ...(cause === undefined ? {} : { cause }),
+    ...options,
+});
+const describeCause = (cause, redact, depth = 0) => {
+    if (cause instanceof Error) {
+        return describeErrorCause(cause, redact, depth);
+    }
+    if (typeof cause === "string") {
+        const message = boundedUtf8Text(redact(cause), MAX_CAUSE_MESSAGE_BYTES);
+        return {
+            type: "string",
+            message: message.text,
+            ...(message.truncated ? { message_truncated: true } : {}),
+        };
+    }
+    if (cause === null || typeof cause === "boolean")
+        return { type: cause === null ? "null" : "boolean", value: cause };
+    if (typeof cause === "number" && Number.isFinite(cause))
+        return { type: "number", value: cause };
+    return { type: typeof cause };
+};
+const describeErrorCause = (cause, redact, depth) => {
+    const message = boundedUtf8Text(redact(cause.message), MAX_CAUSE_MESSAGE_BYTES);
+    const name = boundedUtf8Text(redact(cause.name), MAX_CAUSE_FIELD_BYTES);
+    return {
+        name: name.text,
+        ...(name.truncated ? { name_truncated: true } : {}),
+        message: message.text,
+        ...(message.truncated ? { message_truncated: true } : {}),
+        ...causeCode(cause, redact),
+        ...causeSignal(cause, redact),
+        ...causeCompilerOutcome(cause, redact),
+        ...causeLaunchOutcome(cause, redact),
+        ...nestedErrorCause(cause, redact, depth),
+    };
+};
+const causeCode = (cause, redact) => {
+    const code = "code" in cause ? cause.code : undefined;
+    if (typeof code === "string") {
+        const bounded = boundedUtf8Text(redact(code), MAX_CAUSE_FIELD_BYTES);
+        return {
+            code: bounded.text,
+            ...(bounded.truncated ? { code_truncated: true } : {}),
+        };
+    }
+    if (typeof code === "number" && Number.isFinite(code))
+        return { code };
+    return {};
+};
+const causeSignal = (cause, redact) => {
+    const signal = "signal" in cause ? cause.signal : undefined;
+    if (typeof signal === "string") {
+        const bounded = boundedUtf8Text(redact(signal), MAX_CAUSE_FIELD_BYTES);
+        return {
+            signal: bounded.text,
+            ...(bounded.truncated ? { signal_truncated: true } : {}),
+        };
+    }
+    if (signal === null)
+        return { signal: null };
+    return {};
+};
+const causeCompilerOutcome = (cause, redact) => {
+    if (!(cause instanceof DarwinProcessOwnershipInspectionError))
+        return {};
+    const outcome = cause.compilerOutcome;
+    if (outcome === undefined)
+        return {};
+    const stderr = boundedUtf8Text(redact(outcome.stderr), MAX_COMPILER_STDERR_BYTES);
+    const code = boundedCompilerField(outcome.code, redact);
+    const signal = boundedCompilerField(outcome.signal, redact);
+    return {
+        compiler_outcome: {
+            ...outcome,
+            code: code.value,
+            signal: signal.value,
+            stderr: stderr.text,
+            stderrTruncated: outcome.stderrTruncated || stderr.truncated,
+            ...(code.truncated ? { codeTruncated: true } : {}),
+            ...(signal.truncated ? { signalTruncated: true } : {}),
+        },
+    };
+};
+const boundedCompilerField = (value, redact) => {
+    if (typeof value !== "string")
+        return { value, truncated: false };
+    const bounded = boundedUtf8Text(redact(value), MAX_CAUSE_FIELD_BYTES);
+    return { value: bounded.text, truncated: bounded.truncated };
+};
+/** Retain a launch failure's launcher command outcome in its cause envelope. */
+const causeLaunchOutcome = (cause, redact) => {
+    if (!(cause instanceof GhidraLaunchError))
+        return {};
+    const output = cause.capturedOutput;
+    if (output === undefined)
+        return {};
+    const stdout = boundedUtf8Text(redact(output.stdout), MAX_LAUNCH_COMMAND_OUTPUT_BYTES);
+    const stderr = boundedUtf8Text(redact(output.stderr), MAX_LAUNCH_COMMAND_OUTPUT_BYTES);
+    const truncated = output.truncated || stdout.truncated || stderr.truncated;
+    return {
+        launch_outcome: {
+            stdout: stdout.text,
+            stderr: stderr.text,
+            truncated,
+            ...(truncated
+                ? {
+                    stdout_bytes: Buffer.byteLength(output.stdout),
+                    stderr_bytes: Buffer.byteLength(output.stderr),
+                }
+                : {}),
+            ...(output.exit_code === undefined
+                ? {}
+                : { exit_code: output.exit_code }),
+            ...(output.signal === undefined ? {} : { signal: output.signal }),
+        },
+    };
+};
+const nestedErrorCause = (cause, redact, depth) => {
+    if (!("cause" in cause))
+        return {};
+    if (depth >= MAX_CAUSE_DEPTH)
+        return { cause_truncated: true };
+    return { cause: describeCause(cause.cause, redact, depth + 1) };
+};

package/dist/ghidra/GhidraSessionRoot.js

@@ -0,0 +1,39 @@
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+/** Session roots may not contain a dot-prefixed path element. */
+const hasDotPrefixElement = (directory) => resolve(directory)
+    .split(sep)
+    .some((element) => element.startsWith("."));
+/** Nearest ancestor of `directory`, inclusive, that has no dot-prefixed element. */
+const nearestSafeAncestor = (directory) => {
+    let current = resolve(directory);
+    for (;;) {
+        if (!hasDotPrefixElement(current))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+};
+/**
+ * Select a session root usable as the parent of a Ghidra project path.
+ *
+ * Ghidra validates every project path element with `NamingUtilities.checkName`
+ * and aborts the headless analyzer on any element that starts with `.`, so an
+ * inherited `TMPDIR` such as `~/.cache/<tool>` fails every Ghidra operation
+ * with a generic analysis failure. Prefer the inherited base when it is usable,
+ * then a dot-free platform temp directory, then the nearest dot-free ancestor.
+ */
+export const ghidraSessionRoot = (options = {}) => {
+    const base = resolve(options.base ?? tmpdir());
+    if (!hasDotPrefixElement(base))
+        return base;
+    const platform = options.platform ?? process.platform;
+    const fallback = options.fallback ?? (platform === "win32" ? undefined : "/tmp");
+    if (fallback !== undefined &&
+        isAbsolute(fallback) &&
+        !hasDotPrefixElement(fallback))
+        return resolve(fallback);
+    return nearestSafeAncestor(base) ?? base;
+};