reverseport 0.0.0-stage → 1.2.0

package/dist/domain/propertyListKeys.js

@@ -0,0 +1,107 @@
+import { DOMParser, normalizeLineEndings } from "@xmldom/xmldom";
+import { parse } from "plist";
+/** The dictionary key REA results cannot carry: validation strips it. */
+const PROTOTYPE_KEY = "__proto__";
+/** Limitation for results whose source plist held `__proto__` entries. */
+export const omittedPrototypeKeysLimitation = (count) => count === null
+    ? "Dictionary entries keyed __proto__ were omitted because REA results cannot represent that key."
+    : `${String(count)} dictionary ${count === 1 ? "entry" : "entries"} keyed __proto__ ${count === 1 ? "was" : "were"} omitted because REA results cannot represent that key.`;
+const withoutKey = (value, key) => {
+    let omitted = 0;
+    const strip = (item) => {
+        if (Array.isArray(item))
+            return item.map(strip);
+        if (item === null ||
+            typeof item !== "object" ||
+            item instanceof Date ||
+            item instanceof Uint8Array)
+            return item;
+        return Object.fromEntries(Object.entries(item).flatMap(([name, entry]) => {
+            if (name !== key)
+                return [[name, strip(entry)]];
+            omitted += 1;
+            return [];
+        }));
+    };
+    const stripped = strip(value);
+    return { value: stripped, omittedPrototypeKeys: omitted };
+};
+/** Remove own `__proto__` entries, such as JSON.parse creates, and count them. */
+export const omitPrototypeKeys = (value) => withoutKey(value, PROTOTYPE_KEY);
+const XML_ENTITIES = {
+    amp: "&",
+    apos: "'",
+    gt: ">",
+    lt: "<",
+    quot: '"',
+};
+/**
+ * Expand XML character and predefined entity references. A reference beyond
+ * Unicode stays as written: comments and CDATA may hold such text literally,
+ * and the XML decoder rejects it anywhere else.
+ */
+export const decodeXmlText = (text) => text.replace(/&(?:#x([\da-f]+)|#(\d+)|([a-z]+));/giu, (entity, hex, decimal, name) => {
+    const codePoint = hex !== undefined
+        ? parseInt(hex, 16)
+        : decimal !== undefined
+            ? parseInt(decimal, 10)
+            : undefined;
+    if (codePoint !== undefined)
+        return codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : entity;
+    return (name === undefined ? undefined : XML_ENTITIES[name]) ?? entity;
+});
+/**
+ * Decode an XML plist whose dictionaries may use the legal key `__proto__`,
+ * which the `plist` decoder rejects outright. Those entries are omitted and
+ * counted so callers can report them instead of failing the whole document.
+ */
+export const parseXmlPropertyList = (text) => {
+    // Preserve the pinned decoder's existing OpenStep autodetection, also used
+    // by app Info.plist resolution. Only XML needs the key-element substitution.
+    const first = text.trimStart()[0];
+    if (first === "{" || first === "(")
+        return omitPrototypeKeys(parse(text));
+    const { substituted, placeholder } = substitutePrototypeKeys(normalizeLineEndings(text));
+    return withoutKey(parse(substituted), placeholder);
+};
+/** Locate keys with the same XML parser and first-child semantics as plist. */
+const substitutePrototypeKeys = (text) => {
+    // Normalize only the literal line endings the pinned decoder normalizes.
+    // Preserve character references in the source: serializing a DOM would turn
+    // e.g. an encoded carriage return into a literal newline on the second parse.
+    const document = new DOMParser().parseFromString(text, "text/xml");
+    const keys = Array.from(document.getElementsByTagName("key"));
+    const decodedKeys = new Set(keys.map((key) => key.firstChild?.nodeValue));
+    let placeholder = "__rea_prototype_key__";
+    while (decodedKeys.has(placeholder))
+        placeholder = `_${placeholder}`;
+    const omitted = keys
+        .map((key) => key.firstChild)
+        .filter((node) => node?.nodeValue === PROTOTYPE_KEY);
+    if (omitted.length === 0)
+        return { substituted: text, placeholder };
+    // xmldom uses one-based locators in document order. Scan forward only to
+    // needed lines instead of retaining an offset for every source newline.
+    let line = 1;
+    let lineStart = 0;
+    const parts = [];
+    let cursor = 0;
+    for (const node of omitted) {
+        const nodeLine = node?.lineNumber;
+        const column = node?.columnNumber;
+        if (nodeLine === undefined || column === undefined)
+            throw new TypeError("XML plist key has no source location");
+        while (line < nodeLine) {
+            const newline = text.indexOf("\n", lineStart);
+            if (newline === -1)
+                throw new TypeError("XML plist key has an invalid source location");
+            lineStart = newline + 1;
+            line += 1;
+        }
+        const offset = lineStart + column - 1;
+        parts.push(text.slice(cursor, offset), `<![CDATA[${placeholder}]]>`);
+        cursor = offset;
+    }
+    parts.push(text.slice(cursor));
+    return { substituted: parts.join(""), placeholder };
+};

package/dist/domain/propertyListXmlText.js

@@ -0,0 +1,19 @@
+/** Decode BOM-aware XML plist text with fatal byte validation. */
+export const decodeXmlPlistText = (bytes) => {
+    const encoding = bytes[0] === 0xff && bytes[1] === 0xfe
+        ? "utf-16le"
+        : bytes[0] === 0xfe && bytes[1] === 0xff
+            ? "utf-16be"
+            : "utf-8";
+    const text = new TextDecoder(encoding, { fatal: true }).decode(bytes);
+    const declaration = /^<\?xml\s[^?]*\bencoding\s*=\s*["']([^"']+)["']/u.exec(text)?.[1];
+    const declared = declaration?.toLowerCase();
+    if (declared !== undefined &&
+        !["utf-8", "utf-16", "utf-16le", "utf-16be"].includes(declared))
+        throw new TypeError(`Unsupported XML encoding declaration: ${declaration}. Supported encodings are UTF-8 and BOM-marked UTF-16 in either byte order.`);
+    if (declared !== undefined &&
+        declared !== encoding &&
+        !(encoding !== "utf-8" && declared === "utf-16"))
+        throw new TypeError("XML encoding declaration disagrees with its bytes");
+    return text;
+};

package/dist/domain/providerAdapterError.js

@@ -0,0 +1,19 @@
+import { AnalysisError, } from "./analysisErrorBase.js";
+/** A provider adapter failed outside its more precise typed variants. */
+export class ProviderAdapterError extends AnalysisError {
+    providerId;
+    operation;
+    _tag = "ProviderAdapterError";
+    userMessage;
+    diagnostics;
+    constructor(providerId, operation, options = {}) {
+        super(`Provider ${providerId} adapter failed during ${operation}`, options);
+        this.providerId = providerId;
+        this.operation = operation;
+        this.userMessage = options.userMessage;
+        this.diagnostics =
+            options.diagnostics === undefined
+                ? undefined
+                : structuredClone(options.diagnostics);
+    }
+}

package/dist/domain/providerCleanupError.js

@@ -0,0 +1,18 @@
+import { ProviderAdapterError } from "./providerAdapterError.js";
+/** Provider resources could not be proven closed after bounded cleanup. */
+export class ProviderCleanupError extends ProviderAdapterError {
+    cleanupIncomplete = true;
+    cleanupResources;
+    userMessage = "Provider cleanup could not be fully confirmed. Review the reported local resources before opening another target.";
+    constructor(providerId, resources, diagnostics, 
+    /** Identify the operation owning these resources; binary callers retain their default. */
+    options) {
+        const { operation = "close_binary", partialObservation, ...errorOptions } = options ?? {};
+        super(providerId, operation, {
+            ...errorOptions,
+            ...(partialObservation === undefined ? {} : { partialObservation }),
+            diagnostics,
+        });
+        this.cleanupResources = [...resources];
+    }
+}

package/dist/domain/providerConfigurationRefusal.js

@@ -0,0 +1,12 @@
+import { AnalysisCapabilityUnavailableError } from "./analysisErrorCore.js";
+/** Convert a provider's host configuration failure into actionable refusal evidence. */
+export const providerConfigurationRefusal = (providerId, operation, failure) => {
+    const remediation = failure.diagnostics?.remediation;
+    const reason = typeof remediation === "string"
+        ? `${failure.message}. ${remediation}.`
+        : `${failure.message}.`;
+    return new AnalysisCapabilityUnavailableError(providerId, operation, reason, {
+        cause: failure,
+        userMessage: reason,
+    });
+};

package/dist/domain/providerOperationHealth.js

@@ -0,0 +1,54 @@
+/** Caller-visible operational state for one provider bridge. */
+export const PROVIDER_OPERATION_STATES = [
+    "idle",
+    "busy",
+    "exited",
+    "unreachable",
+    "not_started",
+    "unknown",
+];
+/** What the caller should do next for this provider state. */
+export const PROVIDER_RETRY_ACTIONS = [
+    "retry",
+    "wait",
+    "restart_provider",
+    "unknown",
+];
+/** Stage that was in progress when the provider operation failed. */
+export const PROVIDER_FAILURE_STAGES = [
+    "launch",
+    "connection",
+    "analysis",
+    "decompilation",
+    "unknown",
+];
+/**
+ * Choose a recovery action from the observed state.
+ * Startup failures keep their existing install or configuration guidance.
+ */
+export const providerRetryAction = (state, startupFailure = false) => {
+    if (state === "idle")
+        return null;
+    if (startupFailure && state === "exited")
+        return "retry";
+    switch (state) {
+        case "busy":
+            return "wait";
+        case "exited":
+        case "unreachable":
+            return "restart_provider";
+        case "not_started":
+            return "retry";
+        case "unknown":
+            return "unknown";
+    }
+};
+/** Use one stage when every retained request agrees, otherwise unknown. */
+export const sharedProviderFailureStage = (requests) => {
+    const first = requests[0]?.stage;
+    if (first === undefined)
+        return null;
+    return requests.every((request) => request.stage === first)
+        ? first
+        : "unknown";
+};

package/dist/domain/providerSelectionError.js

@@ -0,0 +1,46 @@
+import { AnalysisError, } from "./analysisErrorBase.js";
+/** No configured provider can satisfy a requested operation or target binding. */
+export class ProviderSelectionError extends AnalysisError {
+    _tag = "ProviderSelectionError";
+    operation;
+    reason;
+    requestedProviderId;
+    candidateIds;
+    rejections;
+    userMessage;
+    constructor(options) {
+        const operation = options.operation ?? "open_binary";
+        super(providerSelectionDiagnostic(options), options.capturedOutput === undefined
+            ? undefined
+            : { capturedOutput: options.capturedOutput });
+        this.operation = operation;
+        this.reason = options.reason;
+        this.requestedProviderId = options.requestedProviderId;
+        this.candidateIds = [...options.candidateIds];
+        this.rejections = [...(options.rejections ?? [])].map((rejection) => ({
+            ...rejection,
+            diagnostics: structuredClone(rejection.diagnostics),
+        }));
+        this.userMessage = providerSelectionUserMessage(options);
+    }
+}
+const providerSelectionDiagnostic = (options) => {
+    const candidates = options.candidateIds.length === 0
+        ? "none"
+        : options.candidateIds.join(", ");
+    return `Analysis provider selection failed (${options.reason}) for ${options.requestedProviderId}; candidates: ${candidates}`;
+};
+const providerSelectionUserMessage = (options) => {
+    switch (options.reason) {
+        case "ambiguous":
+            return "Multiple analysis providers support this target. Choose one with provider_id, --provider, or REA_ANALYSIS_PROVIDER.";
+        case "unknown_provider":
+            return `The requested analysis provider is unknown. Choose one of: ${options.candidateIds.join(", ") || "no configured providers"}.`;
+        case "provider_unavailable":
+            return "The selected analysis provider is unavailable. Review the reported local diagnostics or run `reverseport doctor`, then retry.";
+        case "target_unsupported":
+            return "The selected analysis provider does not support this target. Choose another provider or open a supported extracted binary.";
+        case "invalid_options":
+            return "The analysis provider selection or open options are invalid. Correct them and try again.";
+    }
+};

package/dist/domain/rawBinary.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { err, ok } from "./result.js";
+/** Caller-visible CPU families admitted for headerless raw binaries. */
+export const BINARY_ARCHITECTURES = [
+    "x86",
+    "x86_64",
+    "arm",
+    "arm64",
+];
+/** Provider-neutral CPU family for a caller-supplied raw-binary load. */
+export const binaryArchitectureSchema = z.enum(BINARY_ARCHITECTURES);
+const RAW_BINARY_ENTRY_POINT = /^0x[0-9A-Fa-f]{1,16}$/u;
+/** Hexadecimal load and entry address; file offset 0 is mapped here. */
+export const rawBinaryEntryPointSchema = z
+    .string()
+    .regex(RAW_BINARY_ENTRY_POINT, {
+    message: "entry_point must be a hexadecimal address of the form 0x…",
+});
+/** Parse a caller-supplied hex entry while preserving the source spelling. */
+export const parseRawBinaryEntryPoint = (value) => {
+    if (!RAW_BINARY_ENTRY_POINT.test(value))
+        return err("entry_point must be a hexadecimal address of the form 0x…");
+    const parsed = BigInt(value);
+    return ok({
+        source: value,
+        canonical: `0x${parsed.toString(16)}`,
+        value: parsed,
+    });
+};
+/** Reject empty or non-integral file extents for a headerless image. */
+export const validateRawBinaryLength = (length) => Number.isSafeInteger(length) && length >= 1
+    ? ok(null)
+    : err("raw-binary requires at least one file byte");
+const addressWidth = (architecture) => architecture === "x86" || architecture === "arm"
+    ? 0xffffffffn
+    : 0xffffffffffffffffn;
+/** Validate architecture, entry, and that the mapped image fits the CPU width. */
+export const admitRawBinary = (input) => {
+    const architecture = binaryArchitectureSchema.safeParse(input.architecture);
+    if (!architecture.success)
+        return err({
+            reason: "raw-binary format requires architecture (x86, x86_64, arm, or arm64)",
+            constraint: "load_selection_rejected",
+        });
+    if (typeof input.entryPoint !== "string")
+        return err({
+            reason: "raw-binary format requires entry_point as a hexadecimal address of the form 0x…",
+            constraint: "load_selection_rejected",
+        });
+    const entry = parseRawBinaryEntryPoint(input.entryPoint);
+    if (!entry.ok)
+        return err({
+            reason: entry.error,
+            constraint: "load_selection_rejected",
+        });
+    if ((architecture.data === "arm" || architecture.data === "arm64") &&
+        entry.value.value % 4n !== 0n)
+        return err({
+            reason: `raw-binary ${architecture.data} entry_point ${entry.value.canonical} must be 4-byte aligned`,
+            constraint: "load_selection_rejected",
+        });
+    const length = validateRawBinaryLength(input.fileBytes);
+    if (!length.ok)
+        return err({
+            reason: length.error,
+            constraint: "file_format_rejected",
+        });
+    const last = entry.value.value + BigInt(input.fileBytes) - 1n;
+    const max = addressWidth(architecture.data);
+    if (entry.value.value > max || last > max)
+        return err({
+            reason: `raw-binary mapping from ${entry.value.canonical} must fit in the ${architecture.data} address width`,
+            constraint: "load_selection_rejected",
+        });
+    return ok({
+        architecture: architecture.data,
+        entryPoint: entry.value.canonical,
+        entryPointSource: entry.value.source,
+    });
+};
+/** Describe the format/architecture/entry pairing without performing I/O. */
+export const rawBinarySelectionError = (input) => {
+    const hasArchitecture = input.architecture !== undefined;
+    const hasEntry = input.entryPoint !== undefined;
+    if (input.format === "raw-binary") {
+        if (!hasArchitecture || !hasEntry)
+            return "format=raw-binary requires architecture and entry_point";
+        return undefined;
+    }
+    if (hasArchitecture || hasEntry)
+        return "architecture and entry_point apply only with format=raw-binary";
+    return undefined;
+};