rea-agents 0.2.1

package/dist/domain/binaryTarget.js

@@ -0,0 +1,321 @@
+import { constants } from "node:fs";
+import { createReadStream } from "node:fs";
+import { createHash } from "node:crypto";
+import { access, open, readFile, realpath, stat, } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { BinaryTargetError } from "./errors.js";
+import { err, ok } from "./result.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Resolve and classify a readable local target before Hopper is launched.
+ * FAT Mach-O inputs select only a host-compatible architecture so setup remains
+ * non-interactive; unsupported or ambiguous inputs are returned as typed errors.
+ */
+export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitecture = process.arch, targetKind) => {
+    const candidate = isAbsolute(input) ? input : resolve(cwd, input);
+    try {
+        await access(candidate, constants.R_OK);
+        const canonical = await realpath(candidate);
+        const resolved = await resolveAppBundle(canonical);
+        if (!resolved.ok)
+            return err(resolved.error);
+        const path = resolved.value;
+        if (!(await stat(path)).isFile())
+            return err(new BinaryTargetError(path, "target is not a regular file"));
+        if (targetKind === "database" ||
+            (targetKind === undefined && path.toLowerCase().endsWith(".hop")))
+            return ok({
+                path,
+                sha256: await sha256File(path),
+                kind: "database",
+                format: "hopper",
+                loaderArgs: [],
+            });
+        const handle = await open(path, "r");
+        let detected;
+        try {
+            detected = await readExecutableMetadata(handle, hostArchitecture);
+        }
+        finally {
+            await handle.close();
+        }
+        if (!detected.ok)
+            return err(new BinaryTargetError(path, detected.error));
+        return ok({
+            path,
+            sha256: await sha256File(path),
+            kind: "executable",
+            ...detected.value,
+        });
+    }
+    catch (cause) {
+        return err(new BinaryTargetError(candidate, "path is not readable", { cause }));
+    }
+};
+const sha256File = async (path) => {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+};
+const resolveAppBundle = async (path) => {
+    const metadata = await stat(path);
+    if (!metadata.isDirectory())
+        return ok(path);
+    if (extname(path).toLowerCase() !== ".app")
+        return err(new BinaryTargetError(path, "target is not an app or file"));
+    const plistPath = join(path, "Contents", "Info.plist");
+    let name;
+    try {
+        const plist = await readFile(plistPath);
+        name =
+            plist.subarray(0, 6).toString("ascii") === "bplist"
+                ? await readBinaryPlistExecutable(plistPath)
+                : parseXmlPlistExecutable(plist.toString("utf8"));
+    }
+    catch (cause) {
+        return err(new BinaryTargetError(path, "app has no readable CFBundleExecutable", {
+            cause,
+        }));
+    }
+    if (!isSafeExecutableName(name))
+        return err(new BinaryTargetError(path, "app has an unsafe CFBundleExecutable"));
+    const programs = join(path, "Contents", "MacOS");
+    const executable = join(programs, name);
+    try {
+        const [canonicalPrograms, canonicalExecutable] = await Promise.all([
+            realpath(programs),
+            realpath(executable),
+        ]);
+        const location = relative(canonicalPrograms, canonicalExecutable);
+        if (location === ".." ||
+            location.startsWith(`..${sep}`) ||
+            isAbsolute(location))
+            return err(new BinaryTargetError(path, "app program file leaves Contents/MacOS"));
+        return ok(canonicalExecutable);
+    }
+    catch (cause) {
+        return err(new BinaryTargetError(path, "app program file is missing", { cause }));
+    }
+};
+const parseXmlPlistExecutable = (plist) => {
+    const match = /<key>\s*CFBundleExecutable\s*<\/key>\s*<string>([^<]+)<\/string>/u.exec(plist);
+    if (match?.[1] === undefined)
+        throw new Error("CFBundleExecutable is missing");
+    return decodeXml(match[1].trim());
+};
+const readBinaryPlistExecutable = async (plistPath) => (await execFileAsync("/usr/bin/plutil", [
+    "-extract",
+    "CFBundleExecutable",
+    "raw",
+    "-o",
+    "-",
+    plistPath,
+])).stdout.trim();
+const isSafeExecutableName = (name) => name.length > 0 &&
+    name !== "." &&
+    name !== ".." &&
+    !name.includes("\0") &&
+    !/[/\\]/u.test(name);
+const decodeXml = (value) => value
+    .replaceAll("&amp;", "&")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&quot;", '"')
+    .replaceAll("&apos;", "'");
+const readExecutableMetadata = async (handle, hostArchitecture) => {
+    const prefix = Buffer.alloc(4096);
+    const prefixRead = await handle.read(prefix, 0, prefix.length, 0);
+    const bytes = prefix.subarray(0, prefixRead.bytesRead);
+    if (bytes.length >= 64 && bytes[0] === 0x4d && bytes[1] === 0x5a) {
+        const offset = bytes.readUInt32LE(0x3c);
+        if (offset > bytes.length - 6) {
+            const record = Buffer.alloc(6);
+            const recordRead = await handle.read(record, 0, record.length, offset);
+            return recordRead.bytesRead === record.length
+                ? parsePeRecord(record)
+                : err("invalid or truncated PE header");
+        }
+    }
+    if (bytes.length >= 8) {
+        const magic = bytes.readUInt32BE(0);
+        if ([0xcafebabf, 0xbfbafeca].includes(magic)) {
+            const little = magic === 0xbfbafeca;
+            const count = little ? bytes.readUInt32LE(4) : bytes.readUInt32BE(4);
+            const required = 8 + count * 32;
+            if (count <= 128 && required > bytes.length) {
+                const header = Buffer.alloc(required);
+                const headerRead = await handle.read(header, 0, header.length, 0);
+                return parseExecutableHeader(header.subarray(0, headerRead.bytesRead), hostArchitecture);
+            }
+        }
+    }
+    return parseExecutableHeader(bytes, hostArchitecture);
+};
+/**
+ * Parse supported executable headers without I/O and derive explicit Hopper
+ * loader arguments. The caller must supply the host architecture used for FAT
+ * Mach-O slice selection.
+ */
+export const parseExecutableHeader = (bytes, hostArchitecture) => {
+    if (bytes.length >= 4 &&
+        bytes.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))
+        return parseElf(bytes);
+    if (bytes.length >= 2 && bytes[0] === 0x4d && bytes[1] === 0x5a)
+        return parsePe(bytes);
+    if (bytes.length < 8)
+        return err("truncated or unsupported binary header");
+    const magic = bytes.readUInt32BE(0);
+    if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic))
+        return parseThinMachO(bytes, magic);
+    if ([0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
+        return parseFatMachO(bytes, magic, hostArchitecture);
+    return err("unsupported binary format");
+};
+const parseThinMachO = (bytes, magic) => {
+    if (bytes.length < 8)
+        return err("truncated Mach-O header");
+    const little = magic === 0xcefaedfe || magic === 0xcffaedfe;
+    const architecture = machArchitecture(little ? bytes.readUInt32LE(4) : bytes.readUInt32BE(4));
+    if (architecture === undefined)
+        return err("unsupported Mach-O architecture");
+    return ok({
+        format: "mach-o",
+        architecture,
+        availableArchitectures: [architecture],
+        loaderArgs: ["-l", "Mach-O", hopperArchitectureFlag(architecture)],
+    });
+};
+const parseFatMachO = (bytes, magic, host) => {
+    const little = magic === 0xbebafeca || magic === 0xbfbafeca;
+    const is64 = magic === 0xcafebabf || magic === 0xbfbafeca;
+    if (bytes.length < 8)
+        return err("truncated FAT header");
+    const read = (offset) => little ? bytes.readUInt32LE(offset) : bytes.readUInt32BE(offset);
+    const count = read(4);
+    const entrySize = is64 ? 32 : 20;
+    if (count === 0 || count > 128 || bytes.length < 8 + count * entrySize)
+        return err("truncated or invalid FAT architecture table");
+    const architectures = [];
+    for (let index = 0; index < count; index += 1) {
+        const architecture = machArchitecture(read(8 + index * entrySize));
+        if (architecture !== undefined && !architectures.includes(architecture))
+            architectures.push(architecture);
+    }
+    const preferred = host === "arm64"
+        ? "arm64"
+        : host === "x64"
+            ? "x86_64"
+            : host === "ia32"
+                ? "x86"
+                : host === "arm"
+                    ? "arm"
+                    : undefined;
+    if (preferred === undefined || !architectures.includes(preferred))
+        return err(`FAT binary has no host-compatible ${host} architecture`);
+    return ok({
+        format: "mach-o",
+        architecture: preferred,
+        availableArchitectures: architectures,
+        loaderArgs: [
+            "-l",
+            "FAT",
+            hopperArchitectureFlag(preferred),
+            "-l",
+            "Mach-O",
+        ],
+    });
+};
+const parseElf = (bytes) => {
+    if (bytes.length < 20)
+        return err("truncated ELF header");
+    if (bytes[4] !== 1 && bytes[4] !== 2)
+        return err("unsupported ELF class");
+    const little = bytes[5] === 1;
+    if (!little && bytes[5] !== 2)
+        return err("unsupported ELF endianness");
+    const machine = little ? bytes.readUInt16LE(18) : bytes.readUInt16BE(18);
+    const architecture = elfArchitecture(machine);
+    if (architecture === undefined)
+        return err("unsupported ELF architecture");
+    return ok({
+        format: "elf",
+        architecture,
+        availableArchitectures: [architecture],
+        loaderArgs: ["-l", "ELF", hopperArchitectureFlag(architecture)],
+    });
+};
+const parsePe = (bytes) => {
+    if (bytes.length < 64)
+        return err("truncated PE DOS header");
+    const offset = bytes.readUInt32LE(0x3c);
+    if (offset > bytes.length - 6)
+        return err("invalid or truncated PE header");
+    return parsePeRecord(bytes.subarray(offset, offset + 6));
+};
+const parsePeRecord = (record) => {
+    if (record.length < 6 || record.toString("binary", 0, 4) !== "PE\u0000\u0000")
+        return err("invalid or truncated PE header");
+    const architecture = peArchitecture(record.readUInt16LE(4));
+    if (architecture === undefined)
+        return err("unsupported PE architecture");
+    return ok({
+        format: "pe",
+        architecture,
+        availableArchitectures: [architecture],
+        loaderArgs: ["-l", "WinPE", hopperArchitectureFlag(architecture)],
+    });
+};
+const machArchitecture = (cpu) => {
+    switch (cpu) {
+        case 7:
+            return "x86";
+        case 0x01000007:
+            return "x86_64";
+        case 12:
+            return "arm";
+        case 0x0100000c:
+            return "arm64";
+    }
+    return undefined;
+};
+const elfArchitecture = (machine) => {
+    switch (machine) {
+        case 3:
+            return "x86";
+        case 62:
+            return "x86_64";
+        case 40:
+            return "arm";
+        case 183:
+            return "arm64";
+    }
+    return undefined;
+};
+const peArchitecture = (machine) => {
+    switch (machine) {
+        case 0x14c:
+            return "x86";
+        case 0x8664:
+            return "x86_64";
+        case 0x1c0:
+            return "arm";
+        case 0xaa64:
+            return "arm64";
+    }
+    return undefined;
+};
+const hopperArchitectureFlag = (architecture) => {
+    switch (architecture) {
+        case "x86":
+            return "--intel-32";
+        case "x86_64":
+            return "--intel-64";
+        case "arm":
+            return "--armv7";
+        case "arm64":
+            return "--aarch64";
+    }
+};

package/dist/domain/errors.js

@@ -0,0 +1,81 @@
+/** Base class for expected analysis, provider, and session failures. */
+export class AnalysisError extends Error {
+}
+/** Base class for failures produced specifically by the Hopper provider. */
+export class HopperError extends AnalysisError {
+}
+/** Provider-neutral invalid analysis input or output at an application boundary. */
+export class AnalysisProtocolError extends AnalysisError {
+    _tag = "AnalysisProtocolError";
+}
+/** An evidence bundle or bounded session ledger rejected caller-controlled data. */
+export class EvidenceLedgerError extends AnalysisError {
+    _tag = "EvidenceLedgerError";
+}
+/** Hopper did not respond within the configured operation deadline. */
+export class HopperTimeoutError extends HopperError {
+    timeoutMs;
+    _tag = "HopperTimeoutError";
+    constructor(timeoutMs) {
+        super(`Hopper did not respond within ${String(timeoutMs)}ms`);
+        this.timeoutMs = timeoutMs;
+    }
+}
+/** The caller cancelled a Hopper operation before it completed. */
+export class HopperCancelledError extends HopperError {
+    _tag = "HopperCancelledError";
+    constructor() {
+        super("Hopper operation was cancelled");
+    }
+}
+/** Hopper returned bytes or JSON that do not satisfy the NDJSON RPC contract. */
+export class HopperProtocolError extends HopperError {
+    _tag = "HopperProtocolError";
+}
+/** Hopper's JSON-RPC endpoint returned an expected remote error response. */
+export class HopperRemoteError extends HopperError {
+    code;
+    safeMessage;
+    _tag = "HopperRemoteError";
+    constructor(code, safeMessage) {
+        super(`Hopper request failed (${String(code)}): ${safeMessage}`);
+        this.code = code;
+        this.safeMessage = safeMessage;
+    }
+}
+/** The owned Hopper bridge stopped before its client was closed. */
+export class HopperProcessError extends HopperError {
+    exitCode;
+    _tag = "HopperProcessError";
+    constructor(exitCode) {
+        super(`Hopper bridge stopped unexpectedly with code ${String(exitCode)}`);
+        this.exitCode = exitCode;
+    }
+}
+/** Hopper or the repository bridge could not be started. */
+export class HopperStartError extends HopperError {
+    _tag = "HopperStartError";
+    constructor(options) {
+        super("Hopper application bridge could not be started", options);
+    }
+}
+/** Runtime configuration could not be parsed safely. */
+export class ConfigurationError extends AnalysisError {
+    _tag = "ConfigurationError";
+}
+/** No app or binary session exists for an analysis request. */
+export class NoBinaryOpenError extends AnalysisError {
+    _tag = "NoBinaryOpenError";
+    constructor() {
+        super("No app is open. Ask the user which app to investigate, then call open_binary with its local path.");
+    }
+}
+/** A supplied target path could not be safely opened as a supported app or binary. */
+export class BinaryTargetError extends AnalysisError {
+    path;
+    _tag = "BinaryTargetError";
+    constructor(path, reason, options) {
+        super(`Cannot open app: ${reason}: ${path}`, options);
+        this.path = path;
+    }
+}

package/dist/domain/evidence.js

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { jsonValueSchema } from "./jsonValue.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const providerSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    version: z.string().nullable(),
+});
+const subjectSchema = z.object({
+    name: z.string().min(1),
+    digest: z.object({ sha256: digestSchema }),
+    format: z.enum(["hopper", "mach-o", "elf", "pe"]),
+    architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
+    local_path: z.string(),
+});
+const locationSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("address"), address: z.string().min(1) }),
+    z.object({
+        kind: z.literal("address-range"),
+        start: z.string().min(1),
+        end: z.string().min(1),
+    }),
+    z.object({ kind: z.literal("artifact-path"), path: z.string().min(1) }),
+]);
+const evidenceAuthoritySchema = z.enum([
+    "shipped-artifact",
+    "controlled-replay",
+    "historical-reference",
+    "external-service",
+    "analyst-inference",
+]);
+const executionEnvironmentSchema = z.object({
+    id: z.string().min(1),
+    platform: z.string().min(1),
+    architecture: z.string().min(1),
+    isolation: z.enum(["none", "process", "container", "virtual-machine"]),
+});
+/** Strict, provider-neutral record for one successful public observation. */
+export const evidenceSchema = z.object({
+    schema_version: z.literal(2),
+    evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
+    subject: subjectSchema.nullable(),
+    provider: providerSchema,
+    predicate_type: z.string().min(1),
+    operation: z.string().min(1),
+    parameters: z.record(z.string(), jsonValueSchema),
+    result: jsonValueSchema,
+    raw_payload_sha256: digestSchema.nullable(),
+    confidence: z.enum(["observed", "derived", "inferred"]),
+    authority: evidenceAuthoritySchema,
+    environment: executionEnvironmentSchema.nullable(),
+    limitations: z.array(z.string()),
+    locations: z.array(locationSchema),
+    evidence_links: z.array(z.string().regex(/^ev_[a-f0-9]{64}$/u)),
+});
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+/** Serialize JSON according to RFC 8785 JSON Canonicalization Scheme. */
+const canonicalJson = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("RFC 8785 canonicalization rejected a JSON value");
+    return serialized;
+};
+const semanticProjection = (evidence) => ({
+    schema_version: evidence.schema_version,
+    subject: evidence.subject === null
+        ? null
+        : {
+            digest: evidence.subject.digest,
+            format: evidence.subject.format,
+            architecture: evidence.subject.architecture,
+        },
+    provider: evidence.provider,
+    predicate_type: evidence.predicate_type,
+    operation: evidence.operation,
+    parameters: evidence.parameters,
+    result: evidence.result,
+    confidence: evidence.confidence,
+    authority: evidence.authority,
+    environment: evidence.environment,
+    limitations: evidence.limitations,
+    locations: evidence.locations,
+    evidence_links: evidence.evidence_links,
+});
+/** Recompute the semantic identifier, excluding paths and raw payload bytes. */
+const computeEvidenceId = (evidence) => `ev_${sha256(canonicalJson(semanticProjection(evidence)))}`;
+/** Parse evidence and reject a syntactically valid but tampered semantic ID. */
+export const parseEvidence = (input) => {
+    const evidence = evidenceSchema.parse(input);
+    const { evidence_id: evidenceId, ...withoutId } = evidence;
+    if (computeEvidenceId(withoutId) !== evidenceId)
+        throw new TypeError("Evidence semantic identifier does not match its record");
+    return evidence;
+};
+/** Build deterministic Evidence v2 from an immutable artifact subject. */
+export const createEvidence = (target, provider, observation) => {
+    const subject = target === undefined
+        ? null
+        : {
+            name: target.path.split("/").at(-1) ?? target.path,
+            digest: { sha256: target.sha256 },
+            format: target.format,
+            architecture: target.architecture ?? null,
+            local_path: target.path,
+        };
+    const semantic = {
+        schema_version: 2,
+        subject: subject === null
+            ? null
+            : {
+                digest: subject.digest,
+                format: subject.format,
+                architecture: subject.architecture,
+            },
+        provider: {
+            id: provider.id,
+            name: provider.name,
+            version: provider.version,
+        },
+        predicate_type: observation.predicateType ?? "rea.analysis/v2",
+        operation: observation.operation,
+        parameters: observation.parameters,
+        result: observation.result,
+        confidence: observation.confidence ?? "observed",
+        authority: observation.authority ?? "shipped-artifact",
+        environment: observation.environment ?? null,
+        limitations: [
+            ...(target === undefined
+                ? ["Artifact identity is unavailable for this observation."]
+                : []),
+            ...(observation.limitations ?? []),
+        ],
+        locations: [...(observation.locations ?? [])],
+        evidence_links: [...(observation.evidenceLinks ?? [])],
+    };
+    return evidenceSchema.parse({
+        ...semantic,
+        evidence_id: `ev_${sha256(canonicalJson(semantic))}`,
+        subject,
+        raw_payload_sha256: observation.redactedRawPayload === undefined
+            ? null
+            : sha256(canonicalJson(observation.redactedRawPayload)),
+    });
+};

package/dist/domain/evidenceBundle.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { evidenceSchema } from "./evidence.js";
+export const evidenceBundleSchema = z.object({
+    bundle_version: z.literal(1),
+    records: z.array(evidenceSchema),
+});
+/** Project records into a deterministic bundle whose order has no semantics. */
+export const createEvidenceBundle = (records) => ({
+    bundle_version: 1,
+    records: [...records].sort((left, right) => left.evidence_id.localeCompare(right.evidence_id)),
+});