reverseport 0.0.0-stage → 1.2.0

package/dist/domain/native/recordedCrash.js

@@ -0,0 +1,263 @@
+import { z } from "zod";
+import { localPathStringSchema } from "../localPath.js";
+import { CANONICAL_BASE64_PATTERN } from "../stringPatterns.js";
+import { recordedNoteCoverageIssues } from "./recordedCrashNoteCoverage.js";
+const hex = z.string().regex(/^0x(?:0|[1-9a-f][0-9a-f]{0,15})$/);
+const index = z.number().int().nonnegative();
+const signed32 = z.number().int().min(-2147483648).max(2147483647);
+const base64 = z.string().regex(CANONICAL_BASE64_PATTERN);
+const range = z.strictObject({ offset: hex, bytes: hex });
+const diagnostics = z.strictObject({
+    stdout: z.string(),
+    stderr: z.string(),
+    truncated: z.boolean(),
+});
+// Exact b"CORE\0"; a lossy display label cannot establish the Linux note ABI.
+const LINUX_CORE_OWNER_BASE64 = "Q09SRQA=";
+/** Complete register identities in the supported Linux amd64 PRSTATUS ABI order. */
+export const RECORDED_LINUX_AMD64_REGISTERS = [
+    "r15",
+    "r14",
+    "r13",
+    "r12",
+    "rbp",
+    "rbx",
+    "r11",
+    "r10",
+    "r9",
+    "r8",
+    "rax",
+    "rcx",
+    "rdx",
+    "rsi",
+    "rdi",
+    "orig_rax",
+    "rip",
+    "cs",
+    "eflags",
+    "rsp",
+    "ss",
+    "fs_base",
+    "gs_base",
+    "ds",
+    "es",
+    "fs",
+    "gs",
+];
+const supportedRegisters = new Set(RECORDED_LINUX_AMD64_REGISTERS);
+/** Select an explicit recording and optionally request debugger-derived mapping context. */
+export const inspectRecordedCrashInputSchema = z.strictObject({
+    path: localPathStringSchema.describe("Absolute filesystem path to a supplied Linux ELF core"),
+    include_debugger_context: z
+        .boolean()
+        .default(false)
+        .describe("Add core-only mapping candidates through caller-supplied GDB/pwndbg"),
+});
+/** Debugger map candidates preserve reported flags; zero does not establish absent permissions. */
+export const recordedCrashDebuggerSchema = z.discriminatedUnion("status", [
+    z.strictObject({ status: z.literal("not-requested") }),
+    z.strictObject({
+        status: z.literal("available"),
+        gdb_version: z.string().min(1),
+        pwndbg_version: z.string().min(1),
+        connection: z.literal("core"),
+        executable: z.null(),
+        historical_pid: signed32,
+        reported_limits: z.strictObject({
+            address_space_bytes: index,
+            cpu_seconds: index,
+            file_size_bytes: index,
+        }),
+        maps: z.array(z.strictObject({
+            start: hex,
+            end: hex,
+            offset: hex,
+            reported_flags: index,
+            permissions: z
+                .strictObject({
+                read: z.boolean(),
+                write: z.boolean(),
+                execute: z.boolean(),
+            })
+                .nullable(),
+            pathname_display: z.string(),
+            current_file_identity: z.literal("unknown"),
+        })),
+        confidence: z.literal("derived"),
+        completeness: z.literal("unknown"),
+        diagnostics,
+    }),
+]);
+/** Portable recorded observations; registers and source coordinates remain lossless. */
+const recordedCrashObjectSchema = z.strictObject({
+    artifact: z.strictObject({
+        path: z.string().min(1),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        bytes: index,
+    }),
+    format: z.literal("elf-core"),
+    architecture: z.literal("x86_64-little-endian"),
+    target_execution: z.literal("not-performed"),
+    live_process_identity: z.literal("unknown"),
+    segments: z.array(z.strictObject({
+        index,
+        type: z.union([z.string(), index]),
+        header_location: range,
+        offset: hex,
+        file_size: hex,
+        memory_size: hex,
+        virtual_address: hex,
+        physical_address: hex,
+        alignment: hex,
+        flags: hex,
+        file_backing: z.enum(["file", "none"]),
+    })),
+    notes: z.array(z.strictObject({
+        index,
+        segment_index: index,
+        type: z.union([z.string(), index]),
+        location: range,
+        owner_location: range,
+        owner_bytes_base64: base64,
+        owner_display: z.string().nullable(),
+        descriptor_location: range,
+        descriptor_bytes_base64: base64,
+    })),
+    note_padding: z.array(z.strictObject({
+        segment_index: index,
+        location: range,
+        bytes_base64: base64,
+    })),
+    threads: z.array(z.strictObject({
+        note_index: index,
+        historical_pid: signed32,
+        recorded_current_signal: z.number().int().min(-32768).max(32767),
+        registers: z.array(z.strictObject({
+            name: z.string().min(1),
+            value: hex,
+            location: range,
+        })),
+    })),
+    signals: z.array(z.strictObject({
+        note_index: index,
+        number: signed32,
+        code: signed32,
+        errno: signed32,
+        fault_address: hex.nullable(),
+        fault_address_meaning: z.enum(["recorded-sigsegv-address", "unknown"]),
+        thread_association: z.literal("unknown"),
+    })),
+    debugger: recordedCrashDebuggerSchema,
+    note_interpretation_completeness: z.literal("unknown"),
+    decoder_diagnostics: diagnostics,
+    diagnostics,
+    limitations: z.array(z.string()),
+});
+/** Provider payload excludes identity and diagnostics bound by the owned snapshot boundary. */
+export const recordedCrashPayloadSchema = recordedCrashObjectSchema.omit({
+    artifact: true,
+    diagnostics: true,
+    debugger: true,
+    decoder_diagnostics: true,
+});
+/** Validate the next consumer's file ranges, note links and register representations. */
+export const recordedCrashSchema = recordedCrashObjectSchema.superRefine((value, context) => {
+    const fail = (message) => context.addIssue({ code: "custom", message });
+    const within = (item, start = 0n, end = BigInt(value.artifact.bytes)) => {
+        const offset = BigInt(item.offset);
+        const bytes = BigInt(item.bytes);
+        return offset >= start && offset <= end && bytes <= end - offset;
+    };
+    for (const issue of recordedNoteCoverageIssues(value.segments, value.notes, value.note_padding))
+        fail(issue);
+    for (const [position, segment] of value.segments.entries()) {
+        if (position !== segment.index || !within(segment.header_location))
+            fail("Invalid original segment identity or header range.");
+        if (segment.file_backing === "file" &&
+            !within({ offset: segment.offset, bytes: segment.file_size }))
+            fail("Recorded segment exceeds artifact bytes.");
+        if (segment.type === "PT_LOAD" &&
+            BigInt(segment.file_size) > BigInt(segment.memory_size))
+            fail("Recorded PT_LOAD file size exceeds memory size.");
+    }
+    for (const [position, note] of value.notes.entries()) {
+        const segment = value.segments[note.segment_index];
+        if (position !== note.index || segment?.type !== "PT_NOTE") {
+            fail("Invalid original note identity or segment reference.");
+            continue;
+        }
+        const decodedLength = (raw) => BigInt((raw.length / 4) * 3 -
+            (raw.endsWith("==") ? 2 : raw.endsWith("=") ? 1 : 0));
+        if (decodedLength(note.owner_bytes_base64) !==
+            BigInt(note.owner_location.bytes) ||
+            decodedLength(note.descriptor_bytes_base64) !==
+                BigInt(note.descriptor_location.bytes))
+            fail("Raw note lengths differ from their source ranges.");
+        const start = BigInt(segment.offset);
+        const end = start + BigInt(segment.file_size);
+        if (!within(note.location, start, end) ||
+            !within(note.owner_location, BigInt(note.location.offset), BigInt(note.location.offset) + BigInt(note.location.bytes)) ||
+            !within(note.descriptor_location, BigInt(note.location.offset), BigInt(note.location.offset) + BigInt(note.location.bytes)))
+            fail("Note source ranges exceed their recorded segment.");
+    }
+    for (const padding of value.note_padding) {
+        const segment = value.segments[padding.segment_index];
+        if (segment?.type !== "PT_NOTE" ||
+            !within(padding.location, BigInt(segment.offset), BigInt(segment.offset) + BigInt(segment.file_size)))
+            fail("Invalid recorded note padding range.");
+    }
+    for (const [kind, rows] of [
+        ["NT_PRSTATUS", value.threads],
+        ["NT_SIGINFO", value.signals],
+    ]) {
+        const matchingNotes = value.notes.filter((note) => note.type === kind &&
+            note.owner_bytes_base64 === LINUX_CORE_OWNER_BASE64);
+        if (rows.length !== matchingNotes.length ||
+            new Set(rows.map(({ note_index }) => note_index)).size !== rows.length)
+            fail("Each supported raw note requires exactly one corresponding interpretation.");
+    }
+    for (const thread of value.threads) {
+        const note = value.notes[thread.note_index];
+        if (note?.type !== "NT_PRSTATUS" ||
+            note.owner_display !== "CORE" ||
+            note.owner_bytes_base64 !== LINUX_CORE_OWNER_BASE64) {
+            fail("Thread references a different note kind.");
+            continue;
+        }
+        if (thread.registers.length !== RECORDED_LINUX_AMD64_REGISTERS.length ||
+            !thread.registers.every(({ name }) => supportedRegisters.has(name)) ||
+            new Set(thread.registers.map(({ name }) => name)).size !==
+                thread.registers.length)
+            fail("Each recorded thread requires every supported register exactly once.");
+        for (const register of thread.registers)
+            if (BigInt(register.location.bytes) !== 8n ||
+                !within(register.location, BigInt(note.descriptor_location.offset), BigInt(note.descriptor_location.offset) +
+                    BigInt(note.descriptor_location.bytes)))
+                fail("Register source exceeds its descriptor.");
+    }
+    for (const signal of value.signals) {
+        if (value.notes[signal.note_index]?.type !== "NT_SIGINFO" ||
+            value.notes[signal.note_index]?.owner_display !== "CORE" ||
+            value.notes[signal.note_index]?.owner_bytes_base64 !==
+                LINUX_CORE_OWNER_BASE64)
+            fail("Signal references a different note kind.");
+        const known = signal.number === 11 && (signal.code === 1 || signal.code === 2);
+        if (known !== (signal.fault_address !== null) ||
+            (signal.fault_address !== null) !==
+                (signal.fault_address_meaning === "recorded-sigsegv-address"))
+            fail("Signal union meaning does not match recorded SIGSEGV code.");
+    }
+    if (value.debugger.status === "available")
+        for (const map of value.debugger.maps) {
+            if (BigInt(map.end) < BigInt(map.start))
+                fail("Debugger mapping end precedes its start.");
+            if (map.permissions !== null &&
+                (map.permissions.read !== Boolean(map.reported_flags & 4) ||
+                    map.permissions.write !== Boolean(map.reported_flags & 2) ||
+                    map.permissions.execute !== Boolean(map.reported_flags & 1)))
+                fail("Mapping permissions differ from reported flags.");
+            if ((map.reported_flags === 0 || map.reported_flags > 7) !==
+                (map.permissions === null))
+                fail("Unreported or unfamiliar map flags require unknown permissions.");
+        }
+});

package/dist/domain/native/recordedCrashNoteCoverage.js

@@ -0,0 +1,73 @@
+const align = (size) => ((size + 3n) / 4n) * 4n;
+const layoutMatches = (note) => {
+    const start = BigInt(note.location.offset);
+    const owner = BigInt(note.owner_location.bytes);
+    const descriptor = BigInt(note.descriptor_location.bytes);
+    return (BigInt(note.owner_location.offset) === start + 12n &&
+        BigInt(note.descriptor_location.offset) === start + 12n + align(owner) &&
+        BigInt(note.location.bytes) === 12n + align(owner) + align(descriptor));
+};
+const paddingMatches = (item, segment) => {
+    const bytes = BigInt(item.location.bytes);
+    const decodedLength = (item.bytes_base64.length / 4) * 3 -
+        (item.bytes_base64.endsWith("==")
+            ? 2
+            : item.bytes_base64.endsWith("=")
+                ? 1
+                : 0);
+    return (bytes > 0n &&
+        bytes < 12n &&
+        BigInt(decodedLength) === bytes &&
+        /^A*={0,2}$/.test(item.bytes_base64) &&
+        segment !== undefined &&
+        BigInt(item.location.offset) + bytes ===
+            BigInt(segment.offset) + BigInt(segment.file_size));
+};
+/** Require exact aligned note layouts and one complete, nonoverlapping physical coverage. */
+export function recordedNoteCoverageIssues(segments, notes, padding) {
+    const issues = [];
+    const bySegment = new Map();
+    const all = [];
+    const add = (segment, range) => {
+        const ranges = bySegment.get(segment) ?? [];
+        ranges.push(range);
+        bySegment.set(segment, ranges);
+        all.push(range);
+    };
+    for (const note of notes) {
+        if (!layoutMatches(note))
+            issues.push("Recorded note layout differs from its aligned header/owner/descriptor ranges.");
+        add(note.segment_index, note.location);
+    }
+    for (const item of padding) {
+        if (!paddingMatches(item, segments[item.segment_index]))
+            issues.push("Recorded note padding must be a short zero-filled segment tail.");
+        add(item.segment_index, item.location);
+    }
+    const compare = (left, right) => BigInt(left.offset) < BigInt(right.offset)
+        ? -1
+        : BigInt(left.offset) > BigInt(right.offset)
+            ? 1
+            : 0;
+    let end = 0n;
+    for (const range of all.sort(compare)) {
+        const start = BigInt(range.offset);
+        if (start < end)
+            issues.push("Physical recorded note/padding ranges overlap or repeat.");
+        if (start + BigInt(range.bytes) > end)
+            end = start + BigInt(range.bytes);
+    }
+    for (const segment of segments) {
+        if (segment.type !== "PT_NOTE")
+            continue;
+        let cursor = BigInt(segment.offset);
+        for (const range of (bySegment.get(segment.index) ?? []).sort(compare)) {
+            if (BigInt(range.offset) !== cursor)
+                issues.push("Recorded note/padding ranges leave a gap or overlap in their segment.");
+            cursor = BigInt(range.offset) + BigInt(range.bytes);
+        }
+        if (cursor !== BigInt(segment.offset) + BigInt(segment.file_size))
+            issues.push("Recorded note/padding ranges do not completely cover their segment.");
+    }
+    return issues;
+}

package/dist/domain/nativeConvention.js

@@ -0,0 +1,33 @@
+/** Path-segment conventions. These are inferences, not observations of runtime behavior. */
+const foldSegment = (segment) => segment.toLocaleLowerCase("en-US");
+const REACT_NATIVE_SEGMENTS = new Set([
+    "react.framework",
+    "reactnative.framework",
+    "libreactnative.so",
+    "libreactnativejni.so",
+    "libhermes_executor.so",
+    "libhermes.so",
+    "hermes.framework",
+]);
+const FLUTTER_SEGMENTS = new Set(["libflutter.so", "flutter.framework"]);
+const UNITY_SEGMENTS = new Set(["libunity.so", "unityframework.framework"]);
+/**
+ * A runtime family named by one filename or directory segment.
+ * Only recognized complete library and framework names establish a convention.
+ */
+export const nativeRuntimeConvention = (path) => {
+    for (const segment of path.split("/")) {
+        const folded = foldSegment(segment);
+        if (REACT_NATIVE_SEGMENTS.has(folded))
+            return "react-native";
+        if (FLUTTER_SEGMENTS.has(folded))
+            return "flutter";
+        if (UNITY_SEGMENTS.has(folded))
+            return "unity";
+    }
+    return null;
+};
+/** Swift runtime libraries are `libswift*.dylib` segments, not every dynamic library. */
+export const isSwiftRuntimeLibrary = (path) => path
+    .split("/")
+    .some((segment) => /^libswift.+\.dylib$/u.test(foldSegment(segment)));

package/dist/domain/offsetDateTime.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/**
+ * ISO-8601 date-time that requires an explicit UTC offset.
+ *
+ * `z.string().datetime({ offset: true })` emits Zod's offset class as `[+-]`.
+ * Annex B and `u` mode accept that, but ECMA-262 `v` mode rejects the
+ * unescaped `-`, so any tool whose schema carries the pattern is unusable for a
+ * client that compiles advertised patterns — schema compilation happens before
+ * arguments are supplied, so the whole tools request fails rather than one call.
+ *
+ * The accepted set is identical to the Zod validator; only the offset class
+ * escapes `-`, as `\x2d`, because an escaped `-` inside a character class is
+ * removed by `oxlint --fix` as a useless escape.
+ */
+export const offsetDateTimeSchema = z
+    .string()
+    .regex(/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|(?:[+\x2d](?:[01]\d|2[0-3]):[0-5]\d)))$/u, "Use an ISO-8601 date-time with an explicit UTC offset");

package/dist/domain/peMachine.js

@@ -0,0 +1,36 @@
+const architectureForMachine = (machine) => {
+    switch (machine) {
+        case 0x014c:
+            return "x86";
+        case 0x8664:
+            return "x86_64";
+        case 0x01c0:
+        case 0x01c2:
+        case 0x01c4:
+            return "arm";
+        case 0xaa64:
+            return "arm64";
+    }
+    return undefined;
+};
+/**
+ * ReadyToRun images compiled for a non-Windows OS store the COFF machine XORed
+ * with IMAGE_FILE_MACHINE_NATIVE_OS_OVERRIDE (dotnet/runtime
+ * src/coreclr/inc/pedecoder.h): Apple, FreeBSD, OpenBSD, Linux, NetBSD, SunOS.
+ */
+const NATIVE_OS_OVERRIDES = [0x4644, 0xadc4, 0xadc5, 0x7b79, 0x1993, 0x1992];
+/**
+ * Decode a COFF machine. Only managed images carry an OS override, so callers
+ * must reject `nativeOsOverride` when the image has no CLI header.
+ */
+export const decodePeMachine = (machine) => {
+    const direct = architectureForMachine(machine);
+    if (direct !== undefined)
+        return { architecture: direct, nativeOsOverride: false };
+    for (const override of NATIVE_OS_OVERRIDES) {
+        const architecture = architectureForMachine(machine ^ override);
+        if (architecture !== undefined)
+            return { architecture, nativeOsOverride: true };
+    }
+    return undefined;
+};