rea-agents 2.0.0 → 2.2.0

package/dist/domain/binaryTarget.js

@@ -1,5 +1,4 @@
 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";
@@ -22,43 +21,42 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
         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,
-                sourcePath: canonical,
-                sha256: await sha256File(path),
-                kind: "database",
-                format: "analysis-database",
-            });
         const handle = await open(path, "r");
-        let detected;
         try {
+            if (!(await handle.stat()).isFile())
+                return err(new BinaryTargetError(path, "target is not a regular file"));
+            if (targetKind === "database" ||
+                (targetKind === undefined && path.toLowerCase().endsWith(".hop")))
+                return ok({
+                    path,
+                    sourcePath: canonical,
+                    sha256: await sha256Handle(handle),
+                    kind: "database",
+                    format: "analysis-database",
+                });
             const artifactFormat = await detectArtifactFormat(path, handle);
             if (artifactFormat !== undefined)
                 return ok({
                     path,
                     sourcePath: canonical,
-                    sha256: await sha256File(path),
+                    sha256: await sha256Handle(handle),
                     kind: isArchiveFormat(artifactFormat) ? "archive" : "artifact",
                     format: artifactFormat,
                 });
-            detected = await readExecutableMetadata(handle, hostArchitecture);
+            const detected = await readExecutableMetadata(handle, hostArchitecture);
+            if (!detected.ok)
+                return err(new BinaryTargetError(path, detected.error));
+            return ok({
+                path,
+                sourcePath: canonical,
+                sha256: await sha256Handle(handle),
+                kind: "executable",
+                ...detected.value,
+            });
         }
         finally {
             await handle.close();
         }
-        if (!detected.ok)
-            return err(new BinaryTargetError(path, detected.error));
-        return ok({
-            path,
-            sourcePath: canonical,
-            sha256: await sha256File(path),
-            kind: "executable",
-            ...detected.value,
-        });
     }
     catch (cause) {
         return err(new BinaryTargetError(candidate, "path is not readable", { cause }));
@@ -107,10 +105,17 @@ const namedArtifactFormat = (lowerPath) => {
     return /\.(?:m?js|cjs)$/u.test(lowerPath) ? "javascript" : undefined;
 };
 const isArchiveFormat = (format) => ["zip", "ipa", "apk", "asar", "dmg", "pkg"].includes(format);
-const sha256File = async (path) => {
+const sha256Handle = async (handle) => {
     const hash = createHash("sha256");
-    for await (const chunk of createReadStream(path))
-        hash.update(chunk);
+    const chunk = Buffer.allocUnsafe(64 * 1024);
+    let position = 0;
+    while (true) {
+        const observed = await handle.read(chunk, 0, chunk.length, position);
+        if (observed.bytesRead === 0)
+            break;
+        hash.update(chunk.subarray(0, observed.bytesRead));
+        position += observed.bytesRead;
+    }
     return hash.digest("hex");
 };
 const resolveAppBundle = async (path) => {
@@ -184,13 +189,7 @@ const readExecutableMetadata = async (handle, hostArchitecture) => {
     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");
-        }
+        return readPeMetadata(handle, offset);
     }
     if (bytes.length >= 8) {
         const magic = bytes.readUInt32BE(0);
@@ -207,6 +206,20 @@ const readExecutableMetadata = async (handle, hostArchitecture) => {
     }
     return parseExecutableHeader(bytes, hostArchitecture);
 };
+const readPeMetadata = async (handle, offset) => {
+    const fileHeader = Buffer.alloc(24);
+    const fileHeaderRead = await handle.read(fileHeader, 0, fileHeader.length, offset);
+    if (fileHeaderRead.bytesRead !== fileHeader.length)
+        return err("invalid or truncated PE header");
+    const optionalHeaderSize = fileHeader.readUInt16LE(20);
+    if (optionalHeaderSize > 4096)
+        return err("invalid PE optional header size");
+    const record = Buffer.alloc(24 + optionalHeaderSize);
+    const recordRead = await handle.read(record, 0, record.length, offset);
+    return recordRead.bytesRead === record.length
+        ? parsePeRecord(record)
+        : err("invalid or truncated PE header");
+};
 /**
  * Parse supported executable headers without I/O. The caller supplies the host
  * architecture used for deterministic FAT Mach-O slice selection.
@@ -294,22 +307,59 @@ const parsePe = (bytes) => {
     if (bytes.length < 64)
         return err("truncated PE DOS header");
     const offset = bytes.readUInt32LE(0x3c);
-    if (offset > bytes.length - 6)
+    if (offset > bytes.length - 24)
         return err("invalid or truncated PE header");
-    return parsePeRecord(bytes.subarray(offset, offset + 6));
+    return parsePeRecord(bytes.subarray(offset));
 };
 const parsePeRecord = (record) => {
-    if (record.length < 6 || record.toString("binary", 0, 4) !== "PE\u0000\u0000")
+    if (record.length < 24 ||
+        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");
+    const optionalHeaderSize = record.readUInt16LE(20);
+    if (optionalHeaderSize > 4096 || record.length < 24 + optionalHeaderSize)
+        return err("invalid or truncated PE optional header");
+    const optionalHeader = record.subarray(24, 24 + optionalHeaderSize);
+    const managed = peManagedStatus(optionalHeader, architecture);
+    if (!managed.ok)
+        return managed;
+    const characteristics = record.readUInt16LE(22);
     return ok({
         format: "pe",
         architecture,
         availableArchitectures: [architecture],
+        executableRole: (characteristics & 0x0002) === 0
+            ? "non-executable"
+            : (characteristics & 0x2000) === 0
+                ? "application"
+                : "shared-library",
+        managed: managed.value,
     });
 };
+const peManagedStatus = (optionalHeader, architecture) => {
+    if (optionalHeader.length < 2)
+        return err("truncated PE optional header");
+    const magic = optionalHeader.readUInt16LE(0);
+    const expectedMagic = architecture === "x86_64" || architecture === "arm64" ? 0x20b : 0x10b;
+    if (magic !== expectedMagic)
+        return err("PE optional-header magic does not match its architecture");
+    const directoryOffset = magic === 0x20b ? 112 : 96;
+    const directoryCountOffset = directoryOffset - 4;
+    if (optionalHeader.length < directoryCountOffset + 4)
+        return err("truncated PE optional header");
+    const directoryCount = optionalHeader.readUInt32LE(directoryCountOffset);
+    const requiredBytes = directoryOffset + directoryCount * 8;
+    if (!Number.isSafeInteger(requiredBytes) ||
+        requiredBytes > optionalHeader.length)
+        return err("truncated PE data-directory table");
+    if (directoryCount <= 14)
+        return ok(false);
+    const cliDirectory = directoryOffset + 14 * 8;
+    return ok(optionalHeader.readUInt32LE(cliDirectory) !== 0 ||
+        optionalHeader.readUInt32LE(cliDirectory + 4) !== 0);
+};
 const machArchitecture = (cpu) => {
     switch (cpu) {
         case 7:

package/dist/domain/boundedCartesianProjection.js

@@ -0,0 +1,15 @@
+/** Project a Cartesian product without materializing values beyond the output limit. */
+export const projectBoundedCartesian = (left, right, maximum, project) => {
+    const values = [];
+    for (const leftValue of left) {
+        for (const rightValue of right) {
+            if (values.length === maximum)
+                return {
+                    values,
+                    omitted: left.length * right.length - values.length,
+                };
+            values.push(project(leftValue, rightValue));
+        }
+    }
+    return { values, omitted: 0 };
+};

package/dist/domain/browserObservation.js

@@ -1,7 +1,5 @@
 import { z } from "zod";
-import { browserCompletenessSchema } from "./browserCompleteness.js";
-import { webTextArtifactSchema } from "./webContentArtifact.js";
-import { jsonShapeSchema } from "./jsonShape.js";
+export { browserTargetListSchema, webPageInspectionSchema, } from "./browserObservationSchemas.js";
 const parseExactOrigin = (value) => {
     let url;
     try {
@@ -306,285 +304,3 @@ export const sanitizeBrowserUrl = (value) => {
         redacted: wasTruncated || hadCredentials || hadFragment || names.length > 0,
     };
 };
-const browserVersionSchema = z.object({
-    product: z.string(),
-    protocol_version: z.string(),
-    revision: z.string(),
-    user_agent: z.string(),
-    js_version: z.string(),
-});
-const browserTargetSchema = z.object({
-    target_id: z.string(),
-    type: z.string(),
-    title: z.string(),
-    url: z.string(),
-    origin: z.string(),
-    attached: z.boolean(),
-});
-/** Bounded and policy-filtered browser target discovery result. */
-export const browserTargetListSchema = z.object({
-    schema_version: z.literal(1),
-    browser: browserVersionSchema,
-    targets: z.object({
-        items: z.array(browserTargetSchema),
-        offset: z.number().int().min(0),
-        limit: z.number().int().min(1),
-        total: z.number().int().min(0),
-        next_offset: z.number().int().min(0).nullable(),
-        has_more: z.boolean(),
-    }),
-    excluded: z.object({
-        disallowed_origin: z.number().int().min(0),
-        unsupported_url: z.number().int().min(0),
-        non_page: z.number().int().min(0),
-    }),
-    limitations: z.array(z.string()),
-});
-const browserFrameSchema = z.object({
-    frame_id: z.string(),
-    parent_frame_id: z.string().nullable(),
-    url: z.string(),
-    origin: z.string().nullable(),
-});
-const browserDomNodeSchema = z.object({
-    index: z.number().int().min(0),
-    parent_index: z.number().int().min(-1),
-    node_type: z.number().int().min(0),
-    node_name: z.string(),
-    node_value_length: z.number().int().min(0),
-    attribute_names: z.array(z.string()),
-});
-const browserAxNodeSchema = z.object({
-    node_id: z.string(),
-    parent_id: z.string().nullable(),
-    role: z.string().nullable(),
-    name: z.string().nullable(),
-    description: z.string().nullable(),
-    ignored: z.boolean(),
-});
-const browserScriptSourceSchema = z.discriminatedUnion("included", [
-    z.object({ included: z.literal(false), reason: z.string() }),
-    z.object({
-        included: z.literal(true),
-        artifact: webTextArtifactSchema,
-    }),
-]);
-const browserResourceReconciliationSchema = z.discriminatedUnion("status", [
-    z.object({ status: z.literal("exact"), resource_key: z.string() }),
-    z.object({
-        status: z.literal("ambiguous"),
-        candidate_resource_keys: z.array(z.string()),
-    }),
-    z.object({
-        status: z.literal("unmatched"),
-        reason: z.literal("no_exact_sanitized_url"),
-    }),
-]);
-const browserScriptSchema = z.object({
-    script_key: z.string().regex(/^scr_[a-f0-9]{64}(?:_[0-9]+)?$/u),
-    frame_id: z.string().nullable().default(null),
-    url: z.string(),
-    origin: z.string().nullable(),
-    cdp_hash: z.string(),
-    length: z.number().int().min(0),
-    is_module: z.boolean(),
-    language: z.string().nullable(),
-    source_map_url: z.string().nullable(),
-    resource_reconciliation: browserResourceReconciliationSchema,
-    source: browserScriptSourceSchema,
-});
-const browserResourceSchema = z.object({
-    resource_key: z.string().regex(/^res_[a-f0-9]{64}$/u),
-    url: z.string(),
-    origin: z.string().nullable(),
-    type: z.string(),
-    mime_type: z.string(),
-    content_size: z.number().min(0).nullable(),
-});
-const browserNetworkRequestSchema = z.object({
-    request_id: z.string(),
-    url: z.string(),
-    origin: z.string().nullable(),
-    method: z.string(),
-    resource_type: z.string().nullable(),
-    status: z.number().nullable(),
-    mime_type: z.string().nullable(),
-    encoded_data_length: z.number().min(0).nullable(),
-    initiator: z.object({
-        type: z.string(),
-        url: z.string().nullable(),
-        line: z.number().int().min(0).nullable(),
-        column: z.number().int().min(0).nullable(),
-    }),
-    body_shapes: z.object({
-        status: z.enum([
-            "not_approved",
-            "included",
-            "partial",
-            "unavailable",
-            "truncated",
-        ]),
-        request: jsonShapeSchema.nullable(),
-        response: jsonShapeSchema.nullable(),
-    }),
-});
-const browserConsoleEventSchema = z.object({
-    type: z.string(),
-    timestamp: z.number(),
-    argument_types: z.array(z.string()),
-    url: z.string().nullable(),
-    line: z.number().int().min(0).nullable(),
-    column: z.number().int().min(0).nullable(),
-    text_capture: z.object({
-        status: z.enum(["not_approved", "included", "truncated"]),
-        values: z.array(z.object({
-            argument_index: z.number().int().min(0),
-            type: z.string(),
-            text: z.string(),
-        })),
-        retained_bytes: z.number().int().min(0),
-        truncated_values: z.number().int().min(0),
-    }),
-});
-const browserWebSocketEventSchema = z.object({
-    request_id: z.string(),
-    direction: z.enum(["sent", "received"]),
-    opcode: z.number().int().min(0),
-    payload_bytes: z.number().int().min(0),
-    payload_shape: z
-        .object({
-        format: z.enum(["json", "text", "binary"]),
-        json_shape: jsonShapeSchema.nullable(),
-        truncated: z.boolean(),
-    })
-        .nullable(),
-});
-const browserWorkerSchema = z.object({
-    target_id: z.string(),
-    type: z.string(),
-    url: z.string(),
-    origin: z.string().nullable(),
-    attached: z.boolean(),
-    opener_target_id: z.string().nullable().default(null),
-    parent_frame_id: z.string().nullable().default(null),
-});
-const browserCspSourceSchema = z.object({
-    kind: z.enum([
-        "keyword",
-        "scheme",
-        "approved_origin",
-        "external_origin",
-        "other",
-    ]),
-    value: z.string().nullable(),
-});
-const browserLinkMetadataSchema = z.object({
-    href: z.string().nullable(),
-    destination_scope: z.enum(["approved", "outside_policy", "unsupported"]),
-    rel: z.array(z.string()),
-    as: z.string().nullable(),
-    type: z.string().nullable(),
-    crossorigin: z.string().nullable(),
-});
-const browserAgentHintSchema = z.object({
-    mechanism: z.enum([
-        "link_rel",
-        "dom_link_rel",
-        "well_known_resource",
-        "response_header",
-    ]),
-    declaration: z.string(),
-    url: z.string().nullable(),
-    trust: z.literal("page-declared-untrusted"),
-});
-const browserSafeMetadataSchema = z.object({
-    responses: z.array(z.object({
-        request_id: z.string(),
-        url: z.string(),
-        mime_type: z.string().nullable(),
-        content_length: z.number().int().min(0).nullable(),
-        content_encoding: z.string().nullable(),
-        csp: z.object({
-            directives: z.array(z.object({
-                name: z.string(),
-                sources: z.array(browserCspSourceSchema),
-            })),
-            nonce_count: z.number().int().min(0),
-            hash_count: z.number().int().min(0),
-        }),
-        links: z.array(browserLinkMetadataSchema),
-        policies: z.object({
-            coop: z.string().nullable(),
-            coep: z.string().nullable(),
-            corp: z.string().nullable(),
-            referrer_policy: z.string().nullable(),
-            x_content_type_options: z.string().nullable(),
-            permissions_policy_features: z.array(z.string()),
-        }),
-    })),
-    dom_urls: z.array(z.object({
-        node_index: z.number().int().min(0),
-        attribute: z.enum(["href", "src", "action", "formaction", "poster"]),
-        url: z.string().nullable(),
-        destination_scope: z.enum(["approved", "outside_policy", "unsupported"]),
-    })),
-    agent_hints: z.array(browserAgentHintSchema),
-    excluded_dom_urls: z.number().int().min(0),
-    headers_allowlisted: z.literal(true),
-});
-/** Provider-neutral normalized result for one passive web-page observation. */
-export const webPageInspectionSchema = z.object({
-    schema_version: z.literal(2),
-    browser: browserVersionSchema,
-    target: browserTargetSchema,
-    capture_window: z.object({
-        started_at: z.iso.datetime(),
-        ended_at: z.iso.datetime(),
-        observation_ms: z.number().int().min(0),
-    }),
-    completeness: browserCompletenessSchema,
-    frames: z.array(browserFrameSchema),
-    dom: z.object({
-        total_nodes: z.number().int().min(0),
-        nodes: z.array(browserDomNodeSchema),
-    }),
-    accessibility: z.object({
-        total_nodes: z.number().int().min(0),
-        text_capture: z.object({
-            status: z.enum(["not_approved", "included", "truncated", "unavailable"]),
-            retained_bytes: z.number().int().min(0),
-            excluded_fields: z.number().int().min(0),
-            truncated_fields: z.number().int().min(0),
-        }),
-        nodes: z.array(browserAxNodeSchema),
-    }),
-    scripts: z.object({
-        total: z.number().int().min(0),
-        items: z.array(browserScriptSchema),
-    }),
-    resources: z.array(browserResourceSchema),
-    network: z.object({
-        requests: z.array(browserNetworkRequestSchema),
-        websocket_events: z.array(browserWebSocketEventSchema),
-        coverage_started_at: z.iso.datetime(),
-        prior_activity_available: z.literal(false),
-    }),
-    console: z.object({
-        events: z.array(browserConsoleEventSchema),
-        coverage_started_at: z.iso.datetime(),
-        prior_activity_available: z.literal(false),
-    }),
-    workers: z.array(browserWorkerSchema),
-    metadata: browserSafeMetadataSchema,
-    storage: z.object({
-        origin: z.string(),
-        usage_bytes: z.number().min(0).nullable(),
-        quota_bytes: z.number().min(0).nullable(),
-        local_storage_keys: z.array(z.string()),
-        session_storage_keys: z.array(z.string()),
-        indexed_db_names: z.array(z.string()),
-        cache_names: z.array(z.string()),
-        values_redacted: z.literal(true),
-    }),
-    limitations: z.array(z.string()),
-});