rea-agents 2.3.0 → 2.5.0

package/dist/domain/browserScenarioValues.js

@@ -0,0 +1,372 @@
+import { z } from "zod";
+import { browserAllowedOriginsSchema, browserEndpointSchema, browserOriginSchema, } from "./browserObservation.js";
+export const BROWSER_SCENARIO_LIMITS = {
+    actions: 128,
+    secrets: 64,
+    storageEntries: 512,
+    replayRoutes: 256,
+    durationMs: 300_000,
+    actionTimeoutMs: 60_000,
+};
+export const scenarioIdentifierSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9._-]{0,63}$/u);
+const absoluteExecutablePathSchema = z
+    .string()
+    .min(1)
+    .max(4_096)
+    .refine((value) => value.startsWith("/") ||
+    /^[A-Za-z]:[\\/]/u.test(value) ||
+    value.startsWith("\\\\"), "Expected an absolute browser executable path");
+const browserScenarioBaseUrlSchema = z
+    .string()
+    .min(1)
+    .max(65_536)
+    .transform((value, context) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        context.addIssue({ code: "custom", message: "Invalid browser URL" });
+        return z.NEVER;
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:") ||
+        url.username !== "" ||
+        url.password !== "" ||
+        url.search !== "" ||
+        url.hash !== "") {
+        context.addIssue({
+            code: "custom",
+            message: "Browser URLs must be HTTP(S), omit credentials, and declare query values separately",
+        });
+        return z.NEVER;
+    }
+    return url.toString();
+});
+export const browserScenarioValueSchema = z.discriminatedUnion("source", [
+    z.strictObject({
+        source: z.literal("literal"),
+        value: z.string().max(65_536),
+        classification: z.literal("public"),
+    }),
+    z.strictObject({
+        source: z.literal("secret"),
+        secret_id: scenarioIdentifierSchema,
+    }),
+]);
+const queryEntrySchema = z.strictObject({
+    name: z.string().min(1).max(256),
+    value: browserScenarioValueSchema,
+});
+/** URL whose values remain explicit public literals or declared secret references. */
+export const browserScenarioUrlSchema = z.strictObject({
+    url: browserScenarioBaseUrlSchema,
+    query: z.array(queryEntrySchema).max(64).default([]),
+});
+export const browserScenarioBrowserSchema = z.discriminatedUnion("mode", [
+    z.strictObject({
+        mode: z.literal("launch"),
+        executable_path: absoluteExecutablePathSchema,
+        headless: z.literal(true),
+        user_data: z.literal("temporary-owned"),
+        cleanup: z.literal("close-and-delete-profile"),
+    }),
+    z.strictObject({
+        mode: z.literal("connect"),
+        cdp_endpoint: browserEndpointSchema,
+        target_id: z.string().trim().min(1).max(256),
+        ownership: z.literal("external"),
+        cleanup: z.literal("disconnect-only"),
+    }),
+]);
+export const browserScenarioEnvironmentSchema = z.strictObject({
+    viewport: z.strictObject({
+        width: z.number().int().min(320).max(7_680),
+        height: z.number().int().min(240).max(4_320),
+        device_scale_factor: z.number().min(0.5).max(4).default(1),
+    }),
+    locale: z
+        .string()
+        .min(2)
+        .max(64)
+        .regex(/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/u),
+    timezone: z
+        .string()
+        .min(1)
+        .max(128)
+        .regex(/^[A-Za-z0-9_+-]+(?:\/[A-Za-z0-9_+-]+)*$/u),
+    color_scheme: z.enum(["light", "dark", "no-preference"]),
+    reduced_motion: z.enum(["reduce", "no-preference"]),
+    service_workers: z.literal("block"),
+});
+const locatorSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("test_id"),
+        value: z.string().min(1).max(512),
+    }),
+    z.strictObject({
+        kind: z.literal("role"),
+        role: z.enum([
+            "button",
+            "checkbox",
+            "combobox",
+            "dialog",
+            "link",
+            "listbox",
+            "menuitem",
+            "option",
+            "radio",
+            "slider",
+            "spinbutton",
+            "switch",
+            "tab",
+            "textbox",
+        ]),
+        name: z.string().min(1).max(1_024),
+        exact: z.literal(true),
+    }),
+    z.strictObject({
+        kind: z.literal("css"),
+        selector: z.string().min(1).max(4_096),
+        approved: z.literal(true),
+    }),
+]);
+const stepBase = {
+    step_id: scenarioIdentifierSchema,
+    timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .max(BROWSER_SCENARIO_LIMITS.actionTimeoutMs)
+        .optional(),
+};
+export const browserScenarioActionSchema = z.discriminatedUnion("action", [
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("goto"),
+        destination: browserScenarioUrlSchema,
+        wait_until: z.enum(["commit", "domcontentloaded", "load"]),
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("click"),
+        locator: locatorSchema,
+        button: z.enum(["left", "middle", "right"]).default("left"),
+        click_count: z.number().int().min(1).max(3).default(1),
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("fill"),
+        locator: locatorSchema,
+        value: browserScenarioValueSchema,
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("press"),
+        locator: locatorSchema,
+        key: z.string().min(1).max(64),
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("select_option"),
+        locator: locatorSchema,
+        value: browserScenarioValueSchema,
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.enum(["check", "uncheck"]),
+        locator: locatorSchema,
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("wait_for"),
+        locator: locatorSchema,
+        state: z.enum(["attached", "detached", "visible", "hidden"]),
+    }),
+    z.strictObject({
+        step_id: scenarioIdentifierSchema,
+        action: z.literal("wait_for_timeout"),
+        duration_ms: z
+            .number()
+            .int()
+            .min(1)
+            .max(BROWSER_SCENARIO_LIMITS.actionTimeoutMs),
+    }),
+]);
+const storageEntrySchema = z.strictObject({
+    name: z.string().min(1).max(1_024),
+    value: browserScenarioValueSchema,
+});
+export const browserScenarioStorageSchema = z.strictObject({
+    cookies: z
+        .array(z.strictObject({
+        name: z.string().min(1).max(1_024),
+        value: browserScenarioValueSchema,
+        destination: browserScenarioUrlSchema,
+        http_only: z.boolean(),
+        secure: z.boolean(),
+        same_site: z.enum(["Strict", "Lax", "None"]),
+    }))
+        .max(128)
+        .default([]),
+    local_storage: z
+        .array(z.strictObject({
+        origin: browserOriginSchema,
+        entries: z.array(storageEntrySchema).max(128),
+    }))
+        .max(32)
+        .default([]),
+    session_storage: z
+        .array(z.strictObject({
+        origin: browserOriginSchema,
+        entries: z.array(storageEntrySchema).max(128),
+    }))
+        .max(32)
+        .default([]),
+});
+const headerNameSchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u)
+    .transform((value) => value.toLowerCase());
+const replayHeaderSchema = z.strictObject({
+    name: headerNameSchema,
+    value: browserScenarioValueSchema,
+});
+const replayResponseSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("response"),
+        status: z.number().int().min(100).max(599),
+        headers: z.array(replayHeaderSchema).max(64).default([]),
+        body: browserScenarioValueSchema.optional(),
+    }),
+    z.strictObject({
+        kind: z.literal("redirect"),
+        status: z.union([
+            z.literal(301),
+            z.literal(302),
+            z.literal(303),
+            z.literal(307),
+            z.literal(308),
+        ]),
+        destination: browserScenarioUrlSchema,
+    }),
+]);
+const replayRouteSchema = z.strictObject({
+    route_id: scenarioIdentifierSchema,
+    method: z.enum(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]),
+    request: browserScenarioUrlSchema,
+    response: replayResponseSchema,
+});
+export const browserScenarioRequestReplaySchema = z.discriminatedUnion("mode", [
+    z.strictObject({ mode: z.literal("disabled") }),
+    z.strictObject({
+        mode: z.literal("exact"),
+        unmatched: z.enum(["abort", "passthrough-approved-origins"]),
+        routes: z
+            .array(replayRouteSchema)
+            .min(1)
+            .max(BROWSER_SCENARIO_LIMITS.replayRoutes),
+    }),
+]);
+export const browserScenarioSecretSchema = z.strictObject({
+    secret_id: scenarioIdentifierSchema,
+    environment_variable: z.string().regex(/^[A-Z_][A-Z0-9_]{0,127}$/u),
+    purpose: z.enum(["input", "storage", "request-replay"]),
+    redaction: z.literal("replace-with-secret-reference"),
+});
+const REQUIRED_REDACTED_HEADERS = [
+    "authorization",
+    "cookie",
+    "proxy-authorization",
+    "set-cookie",
+];
+const normalizedNames = (maximum) => z
+    .array(z
+    .string()
+    .trim()
+    .min(1)
+    .max(256)
+    .transform((value) => value.toLowerCase()))
+    .max(maximum)
+    .transform((values) => [...new Set(values)].sort());
+export const browserScenarioRedactionSchema = z
+    .strictObject({
+    secret_values: z.literal("replace-with-secret-reference"),
+    query_parameter_names: normalizedNames(128).default([]),
+    header_names: normalizedNames(128).default([...REQUIRED_REDACTED_HEADERS]),
+})
+    .superRefine(({ header_names: names }, context) => {
+    for (const required of REQUIRED_REDACTED_HEADERS)
+        if (!names.includes(required))
+            context.addIssue({
+                code: "custom",
+                path: ["header_names"],
+                message: `Required credential header ${required} must be redacted`,
+            });
+});
+const snapshotKindSchema = z.enum([
+    "screenshot",
+    "dom",
+    "accessibility",
+    "url",
+    "history",
+    "storage",
+]);
+export const browserScenarioCaptureSchema = z.strictObject({
+    after_each_step: z.array(snapshotKindSchema).max(6),
+    at_end: z.array(snapshotKindSchema).max(6),
+    events: z.array(z.enum([
+        "console",
+        "page-errors",
+        "network",
+        "websockets",
+        "frames",
+        "workers",
+        "popups",
+        "downloads",
+    ])),
+});
+export const browserScenarioCaptureLimitsSchema = z.strictObject({
+    max_duration_ms: z
+        .number()
+        .int()
+        .min(100)
+        .max(BROWSER_SCENARIO_LIMITS.durationMs),
+    action_timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .max(BROWSER_SCENARIO_LIMITS.actionTimeoutMs),
+    navigation_timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .max(BROWSER_SCENARIO_LIMITS.actionTimeoutMs),
+    max_events: z.number().int().min(1).max(100_000),
+    max_frames: z.number().int().min(1).max(1_000),
+    max_workers: z.number().int().min(0).max(1_000),
+    max_popups: z.number().int().min(0).max(100),
+    max_websockets: z.number().int().min(0).max(10_000),
+    max_dom_nodes: z.number().int().min(1).max(100_000),
+    max_accessibility_nodes: z.number().int().min(1).max(100_000),
+    max_screenshots: z.number().int().min(0).max(256),
+    max_screenshot_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(8 * 1_024 * 1_024),
+    max_storage_entries: z
+        .number()
+        .int()
+        .min(0)
+        .max(BROWSER_SCENARIO_LIMITS.storageEntries),
+    max_total_metadata_bytes: z
+        .number()
+        .int()
+        .min(1_024)
+        .max(64 * 1_024 * 1_024),
+});
+export const browserScenarioAllowedOriginsSchema = browserAllowedOriginsSchema;

package/dist/domain/evidence.js

@@ -22,6 +22,8 @@ const subjectSchema = z.object({
         "zip",
         "ipa",
         "apk",
+        "msix",
+        "appx",
         "asar",
         "dmg",
         "pkg",

package/dist/domain/hopperValues.js

@@ -114,6 +114,16 @@ const boundedSchema = (item) => z
         });
     }
 });
+/** Provider-neutral bounded raw-instruction window for one analyzed function. */
+export const functionInstructionWindowSchema = z
+    .object({
+    procedure: procedureIdentitySchema,
+    instructions: boundedSchema(z.string()),
+    instructions_scanned: z.number().int().min(0),
+    instruction_scan_truncated: z.boolean(),
+    limitations: z.array(z.string()),
+})
+    .strict();
 const availableReferenceKindSchema = z
     .object({
     available: z.literal(true),

package/dist/domain/javascriptRuntimeObservation.js

@@ -0,0 +1,170 @@
+import { isAbsolute, resolve } from "node:path";
+import { z } from "zod";
+import { browserEndpointSchema, browserOriginSchema, } from "./browserObservation.js";
+const boundedTextSchema = z.string().min(1).max(4_096);
+const runtimeFileRootsSchema = z
+    .array(z
+    .string()
+    .min(1)
+    .max(16_384)
+    .refine(isAbsolute, "Runtime file roots must be absolute paths")
+    .overwrite(resolve))
+    .max(32)
+    .overwrite((roots) => [...new Set(roots)].sort())
+    .default([]);
+const runtimeOriginsSchema = z
+    .array(browserOriginSchema)
+    .max(32)
+    .overwrite((origins) => [...new Set(origins)].sort())
+    .default([]);
+const approvedRuntimeScope = {
+    inspector_endpoint: browserEndpointSchema,
+    allowed_file_roots: runtimeFileRootsSchema,
+    allowed_origins: runtimeOriginsSchema,
+    approved: z.literal(true),
+};
+const requireRuntimeScope = (input, context) => {
+    if (input.allowed_file_roots.length === 0 &&
+        input.allowed_origins.length === 0)
+        context.addIssue({
+            code: "custom",
+            path: ["allowed_file_roots"],
+            message: "At least one exact file root or HTTP(S) origin is required",
+        });
+};
+/** Input for listing approved Node/Electron V8 Inspector targets. */
+export const listJavaScriptRuntimeTargetsInputSchema = z
+    .strictObject({
+    ...approvedRuntimeScope,
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(200).default(100),
+})
+    .superRefine(requireRuntimeScope);
+export const javascriptRuntimeKindSchema = z.enum([
+    "node",
+    "electron-main",
+    "electron-preload",
+    "electron-renderer",
+]);
+export const javascriptRuntimeObservationLimitsSchema = z.strictObject({
+    max_events: z.number().int().min(1).max(50_000).default(10_000),
+    max_scripts: z.number().int().min(1).max(10_000).default(2_000),
+    max_execution_contexts: z.number().int().min(1).max(5_000).default(1_000),
+    max_location_bytes: z.number().int().min(64).max(65_536).default(16_384),
+    max_total_metadata_bytes: z
+        .number()
+        .int()
+        .min(1_024)
+        .max(32 * 1_024 * 1_024)
+        .default(4 * 1_024 * 1_024),
+});
+/** Input for one bounded, attach-only V8 Inspector observation. */
+export const observeJavaScriptRuntimeInputSchema = z
+    .strictObject({
+    ...approvedRuntimeScope,
+    target_id: z.string().trim().min(1).max(256),
+    runtime_kind: javascriptRuntimeKindSchema,
+    observation_ms: z.number().int().min(0).max(10_000).default(100),
+    limits: javascriptRuntimeObservationLimitsSchema.default({
+        max_events: 10_000,
+        max_scripts: 2_000,
+        max_execution_contexts: 1_000,
+        max_location_bytes: 16_384,
+        max_total_metadata_bytes: 4 * 1_024 * 1_024,
+    }),
+})
+    .superRefine(requireRuntimeScope);
+export const javascriptRuntimeVersionSchema = z.strictObject({
+    product: z.string().min(1).max(1_024),
+    protocol_version: z.string().min(1).max(100),
+    v8_version: z.string().max(1_024).nullable(),
+});
+export const javascriptRuntimeLocationSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("file"),
+        file_path: z.string().min(1).max(16_384),
+    }),
+    z.strictObject({
+        kind: z.literal("url"),
+        origin: z.string().min(1).max(2_048),
+        sanitized_url: z.string().min(1).max(65_536),
+    }),
+    z.strictObject({
+        kind: z.literal("builtin"),
+        specifier: z.string().min(1).max(4_096),
+    }),
+]);
+const javascriptRuntimeTargetSchema = z.strictObject({
+    target_id: z.string().min(1).max(256),
+    protocol_type: z.string().min(1).max(100),
+    attached: z.boolean(),
+    location: javascriptRuntimeLocationSchema,
+});
+/** Root/origin-filtered V8 Inspector target inventory. */
+export const javascriptRuntimeTargetListSchema = z.strictObject({
+    schema_version: z.literal(1),
+    runtime: javascriptRuntimeVersionSchema,
+    targets: z.strictObject({
+        items: z.array(javascriptRuntimeTargetSchema),
+        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.strictObject({
+        outside_file_roots: z.number().int().min(0),
+        outside_origins: z.number().int().min(0),
+        unsupported_location: z.number().int().min(0),
+        unconnectable: z.number().int().min(0),
+    }),
+    limitations: z.array(boundedTextSchema).max(100),
+});
+const javascriptRuntimeScriptSchema = z.strictObject({
+    script_key: z.string().regex(/^v8_script_[a-f0-9]{64}$/u),
+    location: javascriptRuntimeLocationSchema,
+    execution_context_key: z.string().max(64).nullable(),
+    cdp_hash: z.string().max(512).nullable(),
+    length: z.number().int().min(0),
+    is_module: z.boolean(),
+    status: z.literal("observed-loaded"),
+});
+const javascriptRuntimeContextSchema = z.strictObject({
+    context_key: z.string().min(1).max(64),
+    state: z.enum(["created", "destroyed", "cleared"]),
+    name: z.string().max(1_024).nullable(),
+    origin: z.string().max(4_096).nullable(),
+});
+/** Deterministic passive script/context snapshot from one bounded window. */
+export const javascriptRuntimeObservationSchema = z.strictObject({
+    schema_version: z.literal(1),
+    runtime: javascriptRuntimeVersionSchema,
+    target: javascriptRuntimeTargetSchema.extend({
+        runtime_kind: javascriptRuntimeKindSchema,
+        runtime_kind_authority: z.literal("caller-declared-unverified"),
+    }),
+    capture: z.strictObject({
+        observation_ms: z.number().int().min(0),
+        events_observed: z.number().int().min(0),
+        events_retained: z.number().int().min(0),
+        events_dropped: z.number().int().min(0),
+        metadata_bytes_retained: z.number().int().min(0),
+        truncated: z.boolean(),
+        truncation_reasons: z.array(boundedTextSchema).max(20),
+    }),
+    scripts: z.strictObject({
+        items: z.array(javascriptRuntimeScriptSchema),
+        observed_total: z.number().int().min(0),
+        excluded: z.strictObject({
+            outside_file_roots: z.number().int().min(0),
+            outside_origins: z.number().int().min(0),
+            unsupported_location: z.number().int().min(0),
+            invalid_protocol_value: z.number().int().min(0),
+        }),
+    }),
+    execution_contexts: z.array(javascriptRuntimeContextSchema),
+    directly_observed: z.array(boundedTextSchema).max(20),
+    unavailable_without_instrumentation: z.array(boundedTextSchema).max(20),
+    unknowns: z.array(boundedTextSchema).max(100),
+    limitations: z.array(boundedTextSchema).max(100),
+});