reverseport 0.0.0-stage → 1.2.0

package/dist/domain/browserObservationSchemas.js

@@ -0,0 +1,327 @@
+import { z } from "zod";
+import { browserCompletenessSchema } from "./browserCompleteness.js";
+import { webTextArtifactSchema } from "./webContentArtifact.js";
+import { jsonShapeSchema } from "./jsonShape.js";
+import { prefixedDigestSchema } from "./../domain/digests.js";
+/** Shared CDP/browser version identity carried on observation Evidence. */
+export 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()
+        .nullable()
+        .describe("Discovery-reported debugger attachment state; null means unknown"),
+});
+/** Complete policy-filtered browser target discovery result. */
+export const browserTargetListSchema = z.object({
+    browser: browserVersionSchema,
+    targets: z.array(browserTargetSchema),
+    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(),
+    states: z
+        .array(z.object({
+        name: z.string(),
+        value: z.union([z.boolean(), z.number(), z.string()]),
+    }))
+        .default([]),
+});
+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()
+        .nullable()
+        .describe("Producer-reported script hash; null when unavailable."),
+    length: z
+        .number()
+        .int()
+        .min(0)
+        .nullable()
+        .describe("Producer-reported script length; null when unavailable."),
+    is_module: z
+        .boolean()
+        .nullable()
+        .describe("Producer-reported module classification; null when unavailable."),
+    language: z.string().nullable(),
+    source_map_url: z.string().nullable(),
+    resource_reconciliation: browserResourceReconciliationSchema,
+    source: browserScriptSourceSchema,
+});
+const browserResourceSchema = z.object({
+    resource_key: prefixedDigestSchema("res"),
+    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(),
+    redirects: z
+        .array(z.object({
+        url: z.string(),
+        response_url: z.string(),
+        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(),
+        request_timestamp: z.number().nullable(),
+        redirect_event_timestamp: z.number().nullable(),
+    }))
+        .optional(),
+    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"]),
+        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"]),
+        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),
+    }),
+});
+const browserWebSocketFrameSchema = z.object({
+    direction: z.enum(["sent", "received"]),
+    opcode: z.number().int().min(0),
+    payload_bytes: z.number().int().min(0).nullable(),
+    payload_shape: z
+        .object({
+        format: z.enum(["json", "text", "binary"]),
+        json_shape: jsonShapeSchema.nullable(),
+    })
+        .nullable(),
+});
+const browserWebSocketConnectionSchema = z.object({
+    request_id: z.string(),
+    url: z.string(),
+    events: z.array(browserWebSocketFrameSchema),
+});
+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({
+    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", "unavailable"]),
+            retained_bytes: z.number().int().min(0),
+            excluded_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_connections: z.array(browserWebSocketConnectionSchema),
+        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()),
+        content_fingerprints: z
+            .array(z.object({
+            scope: z.enum([
+                "cookie",
+                "local_storage",
+                "session_storage",
+                "indexed_db_schema",
+                "indexed_db_record",
+                "cache_entry",
+            ]),
+            identity_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+            value_sha256: z
+                .string()
+                .regex(/^[a-f0-9]{64}$/u)
+                .nullable(),
+            complete: z.boolean(),
+        }))
+            .default([]),
+        fingerprint_algorithm: z.literal("sha256").default("sha256"),
+        fingerprints_complete: z.boolean().default(false),
+        values_redacted: z.literal(true),
+    }),
+    limitations: z.array(z.string()),
+});

package/dist/domain/browserScenario.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { browserScenarioActionSchema, browserScenarioBrowserSchema, browserScenarioCaptureSchema, browserScenarioEnvironmentSchema, browserScenarioSecretSchema, browserScenarioStorageSchema, browserScenarioUrlSchema, } from "./browserScenarioValues.js";
+export const browserScenarioInputSchema = z.strictObject({
+    browser: browserScenarioBrowserSchema.describe("Required launch/connect selection. Launch uses the selected executable and an owned temporary profile; connect uses one loopback CDP endpoint and target."),
+    start_url: browserScenarioUrlSchema.describe("Required initial HTTP(S) URL. Query values must be declared separately as public literals or secret references."),
+    environment: browserScenarioEnvironmentSchema,
+    actions: z
+        .array(browserScenarioActionSchema)
+        .min(1)
+        .describe("Required sequence of explicit browser actions."),
+    storage: browserScenarioStorageSchema,
+    secrets: z
+        .array(browserScenarioSecretSchema)
+        .default([])
+        .describe("Optional environment-variable references for values used in actions, URLs, storage, or replay, and for redacting matching observed text. Secret values are never supplied inline."),
+    capture: browserScenarioCaptureSchema,
+});
+const addIssue = (context, path, message) => context.addIssue({ code: "custom", path, message });
+const assertUnique = (values, path, label, context) => {
+    if (new Set(values).size !== values.length)
+        addIssue(context, path, `${label} must be unique`);
+};
+const secretReferencesInValue = (value) => (value?.source === "secret" ? [value.secret_id] : []);
+const destinationSecretReferences = (destination) => destination.query.flatMap(({ value }) => secretReferencesInValue(value));
+const actionSecretReferences = (action) => {
+    if (action.action === "fill" || action.action === "select_option")
+        return secretReferencesInValue(action.value);
+    if (action.action === "goto")
+        return destinationSecretReferences(action.destination);
+    return [];
+};
+const validateStorage = (scenario) => {
+    const references = [];
+    scenario.storage.cookies.forEach((cookie) => {
+        references.push(...secretReferencesInValue(cookie.value));
+        references.push(...destinationSecretReferences(cookie.destination));
+    });
+    for (const collection of ["local_storage", "session_storage"])
+        scenario.storage[collection].forEach((storage) => {
+            for (const entry of storage.entries)
+                references.push(...secretReferencesInValue(entry.value));
+        });
+    return references;
+};
+const validateSecretReferences = (scenario, references, context) => {
+    const declared = new Set(scenario.secrets.map(({ secret_id: id }) => id));
+    for (const reference of references)
+        if (!declared.has(reference))
+            addIssue(context, ["secrets"], `Secret reference ${reference} is not declared`);
+};
+const validateBrowserScenario = (scenario, context) => {
+    assertUnique(scenario.actions.map(({ step_id: id }) => id), ["actions"], "Action step IDs", context);
+    assertUnique(scenario.secrets.map(({ secret_id: id }) => id), ["secrets"], "Secret IDs", context);
+    assertUnique(scenario.secrets.map(({ environment_variable: name }) => name), ["secrets"], "Secret environment variables", context);
+    const references = scenario.actions.flatMap(actionSecretReferences);
+    references.push(...destinationSecretReferences(scenario.start_url));
+    references.push(...validateStorage(scenario));
+    validateSecretReferences(scenario, references, context);
+};
+/** Strict provider-neutral contract for one controlled browser scenario. */
+export const browserScenarioSchema = browserScenarioInputSchema.superRefine(validateBrowserScenario);

package/dist/domain/browserScenarioCapture.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { browserNetworkContentSelectionValuesSchema } from "./browserNetworkEvidence.js";
+import { browserScenarioCompletenessSchema, browserScenarioEventSchema, browserScenarioStepSchema, } from "./browserScenarioCaptureValues.js";
+/** Step-indexed browser scenario observation. */
+export const browserScenarioCaptureSchema = z
+    .strictObject({
+    browser: z.strictObject({
+        mode: z.enum(["launch", "connect"]),
+        process_ownership: z.enum(["provider-owned", "external"]),
+        cleanup: z.enum(["terminated-owned-process", "disconnected-external"]),
+        product: z.string().min(1),
+        version: z.string().min(1),
+    }),
+    scenario: z.strictObject({
+        start_origin: z.string().min(1),
+        action_count: z.number().int().min(1),
+        secret_references: z.array(z.string().min(1)),
+        network_content: browserNetworkContentSelectionValuesSchema,
+    }),
+    duration_ms: z.number().int().min(0),
+    steps: z.array(browserScenarioStepSchema).min(1),
+    events: z.strictObject({
+        retained: z.number().int().min(0),
+        dropped: z.number().int().min(0),
+        items: z.array(browserScenarioEventSchema),
+    }),
+    completeness: browserScenarioCompletenessSchema,
+    limitations: z.array(z.string().min(1)),
+})
+    .superRefine((capture, context) => {
+    const bySequence = new Map(capture.events.items.map((event) => [event.sequence, event]));
+    if (bySequence.size !== capture.events.items.length)
+        context.addIssue({
+            code: "custom",
+            path: ["events", "items"],
+            message: "Event sequence numbers must be unique",
+        });
+    for (const [index, event] of capture.events.items.entries()) {
+        if (event.kind !== "network-content")
+            continue;
+        const source = bySequence.get(event.source_event_sequence);
+        if (source?.kind !== event.phase ||
+            source.transaction_id !== event.transaction_id ||
+            source.sequence >= event.sequence)
+            context.addIssue({
+                code: "custom",
+                path: ["events", "items", index, "source_event_sequence"],
+                message: "Network content must reference an earlier matching transaction phase",
+            });
+    }
+    if (capture.events.retained !== capture.events.items.length)
+        context.addIssue({
+            code: "custom",
+            path: ["events", "retained"],
+            message: "Retained event count must equal items length",
+        });
+    if (capture.steps.length !== capture.scenario.action_count + 1)
+        context.addIssue({
+            code: "custom",
+            path: ["steps"],
+            message: "Capture must include initial state and one entry per action",
+        });
+    const expectedIndices = capture.steps.map((_, index) => index);
+    if (capture.steps.some(({ step_index: index }, offset) => index !== expectedIndices[offset]))
+        context.addIssue({
+            code: "custom",
+            path: ["steps"],
+            message: "Step indices must be contiguous from zero",
+        });
+    if (capture.events.items.some(({ step_index: index }) => index >= capture.steps.length))
+        context.addIssue({
+            code: "custom",
+            path: ["events", "items"],
+            message: "Event references an unknown step index",
+        });
+});