reverseport 0.0.0-stage → 1.2.0

package/dist/contracts/toolSchemaMetadata.js

@@ -0,0 +1,197 @@
+import { z } from "zod";
+import { advertisedInputExamples } from "./advertisedInputExamples.js";
+import { presentInputJsonSchema } from "./inputSchemaPresentation.js";
+import { digestCanonicalValue } from "../domain/canonicalDigest.js";
+const PROPERTY_DESCRIPTIONS = {
+    addresses: "Ordered provider-normalized procedure addresses to analyze.",
+    after: "The later or right-hand observation to compare.",
+    before: "The earlier or left-hand observation to compare.",
+    boundary_id: "Exact reconstruction boundary identifier to evaluate.",
+    case_sensitive: "Whether text matching distinguishes uppercase and lowercase.",
+    cdp_endpoint: "Literal loopback Chrome DevTools Protocol endpoint.",
+    comment: "Exact analyst comment text to write.",
+    comparisons: "Validated comparison Evidence records to aggregate.",
+    coverage: "Exact reconstruction-coverage commitment to verify.",
+    direction: "Direction in which to traverse or compare relationships.",
+    document: "Exact provider document or program identity.",
+    error: "Structured, caller-actionable error when the operation fails.",
+    evidence: "Evidence record produced by this operation.",
+    evidence_id: "Stable identifier of the recorded Evidence observation.",
+    executable: "Command name or executable path to run.",
+    format: "Declared input artifact format.",
+    name: "Exact name used by this operation.",
+    pattern: "Literal text or regular expression used to filter matching results.",
+    phase: "Current plan or execution phase of the operation.",
+    plan: "Content-bound execution plan and its digest commitment.",
+    query: "Non-empty feature or text query to investigate.",
+    question: "Concrete unresolved question to retain for later investigation.",
+    result: "Primary structured result returned by this operation.",
+    left: "Left-hand input used for comparison or differential execution.",
+    limits: "Resource budgets that bound execution and retained output for this operation.",
+    mode: "Operation mode that selects the requested behavior.",
+    overwrite: "Whether an existing destination may be replaced.",
+    path: "Local filesystem path used by this operation.",
+    provider_id: "Exact deep-analysis provider ID, or automatic selection when omitted.",
+    right: "Right-hand input used for comparison or differential execution.",
+    source_evidence: "Evidence records supporting the prepared source transformation.",
+    status: "Current lifecycle or verification status.",
+    summary: "Concise evidence-backed summary of the result.",
+    symbols: "Ordered Swift symbols to demangle.",
+    target_id: "Exact CDP target identifier selected from the endpoint's target listing.",
+    unknown_id: "Exact residual-unknown identifier.",
+};
+/** Attach caller guidance to a canonical schema for the SDK wire projection. */
+export const toolInputSchemaWithMetadata = (contract) => withAdvertisedJsonSchema(contract.inputSchema, "input", (project) => (options) => {
+    const shared = project({
+        ...options,
+        libraryOptions: { reused: "ref", ...options.libraryOptions },
+    });
+    const examples = advertisedInputExamples(contract);
+    return {
+        ...presentInputJsonSchema(shared, fallbackPropertyDescription),
+        ...(examples.length === 0 ? {} : { examples }),
+    };
+});
+/** Share output definitions and content-bound validator identities on the wire. */
+export const toolOutputSchemaWithMetadata = (contract) => withAdvertisedJsonSchema(contract.outputSchema, "output", (project) => (options) => {
+    const shared = project({
+        ...options,
+        libraryOptions: { reused: "ref", ...options.libraryOptions },
+    });
+    // An explicit ID owns the reference base. Relative external references
+    // also depend on that base, so leave those projections unchanged.
+    if ("$id" in shared || hasRelativeSchemaReference(shared))
+        return shared;
+    return {
+        ...shared,
+        $id: `urn:rea:tool-output:sha256:${digestCanonicalValue({ target: options.target, schema: shared }, "Tool output schema")}`,
+    };
+});
+/**
+ * Apply a wire-presentation transform to one schema's advertised input
+ * projection. The wrapper preserves the schema's own parser and standard
+ * metadata, so both Zod registrations and plain standard schemas keep their
+ * canonical validation while only the advertised JSON changes.
+ */
+export const transformAdvertisedInputJsonSchema = (schema, transform) => {
+    const standard = Reflect.get(schema, "~standard");
+    if (!isSchemaRecord(standard))
+        return schema;
+    const jsonSchema = Reflect.get(standard, "jsonSchema");
+    if (!isSchemaRecord(jsonSchema))
+        return schema;
+    const project = Reflect.get(jsonSchema, "input");
+    if (typeof project !== "function")
+        return schema;
+    const byTarget = new Map();
+    const transformedInput = (options) => {
+        const target = Reflect.get(options, "target");
+        if (typeof target === "string") {
+            const cached = byTarget.get(target);
+            if (cached !== undefined)
+                return cached;
+        }
+        const projected = project(options);
+        const transformed = isSchemaRecord(projected)
+            ? transform(projected)
+            : projected;
+        if (typeof target === "string" && isSchemaRecord(transformed))
+            byTarget.set(target, transformed);
+        return transformed;
+    };
+    return {
+        ...schema,
+        "~standard": {
+            ...standard,
+            jsonSchema: { ...jsonSchema, input: transformedInput },
+        },
+    };
+};
+const hasRelativeSchemaReference = (schema) => {
+    const pending = [schema];
+    const visited = new WeakSet();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === null || typeof current !== "object" || visited.has(current))
+            continue;
+        visited.add(current);
+        for (const [key, value] of Object.entries(current)) {
+            if (["$id", "$ref", "$dynamicRef", "$recursiveRef"].includes(key) &&
+                typeof value === "string" &&
+                !value.startsWith("#") &&
+                !URL.canParse(value))
+                return true;
+            if (value !== null && typeof value === "object")
+                pending.push(value);
+        }
+    }
+    return false;
+};
+const withAdvertisedJsonSchema = (canonical, io, advertise = (project) => project) => {
+    // Zod's input projection drops root metadata when a descendant transforms.
+    // Preserve the parser and let the SDK own conversion of everything else.
+    const schema = canonical.meta(z.globalRegistry.get(canonical) ?? {});
+    const standard = schema["~standard"];
+    const project = standard.jsonSchema?.[io];
+    if (project === undefined)
+        throw new TypeError(`Tool ${io} schema does not expose Standard JSON Schema`);
+    Object.defineProperty(schema, "~standard", {
+        value: {
+            ...standard,
+            jsonSchema: {
+                ...standard.jsonSchema,
+                [io]: memoizeByTarget(advertise(project)),
+            },
+        },
+    });
+    return schema;
+};
+// The SDK reconverts every registered schema on each `tools/list`, although a
+// registered contract cannot change. Like the SDK's own memoized output
+// projection, the advertised value is shared and treated as read-only.
+const memoizeByTarget = (project) => {
+    const byTarget = new Map();
+    return (options) => {
+        if (options.libraryOptions !== undefined)
+            return project(options);
+        const cached = byTarget.get(options.target);
+        if (cached !== undefined)
+            return cached;
+        const projected = project(options);
+        byTarget.set(options.target, projected);
+        return projected;
+    };
+};
+const isSchemaRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const fallbackPropertyDescription = (property) => {
+    const explicit = Object.hasOwn(PROPERTY_DESCRIPTIONS, property)
+        ? PROPERTY_DESCRIPTIONS[property]
+        : undefined;
+    if (explicit !== undefined)
+        return explicit;
+    const words = property.replaceAll("_", " ");
+    if (property.startsWith("max_"))
+        return `Maximum permitted ${words.slice(4)} for this operation.`;
+    if (property.startsWith("include_"))
+        return `Whether to include ${words.slice(8)} in the result.`;
+    if (property.startsWith("expected_"))
+        return `Expected ${words.slice(9)} used to reject stale or mismatched input.`;
+    if (property.endsWith("_sha256"))
+        return `Exact SHA-256 digest of ${words.slice(0, -7)}.`;
+    if (property.endsWith("_evidence_id"))
+        return `Exact Evidence identifier for the ${words.slice(0, -12)} observation.`;
+    if (property.endsWith("_evidence_ids"))
+        return `Ordered Evidence identifiers for the ${words.slice(0, -13)} observations.`;
+    if (property.endsWith("_path"))
+        return `Local filesystem path for ${words.slice(0, -5)}.`;
+    if (property.endsWith("_uri"))
+        return `Canonical URI for ${words.slice(0, -4)}.`;
+    if (property.endsWith("_bytes"))
+        return `Byte count for ${words.slice(0, -6)}.`;
+    if (property.endsWith("_root") || property.endsWith("_roots"))
+        return `Local filesystem ${words} selected for this operation.`;
+    if (property.startsWith("is_") || property.startsWith("has_"))
+        return `Whether ${words}.`;
+    // A generic sentence would only restate the property name in every schema.
+    return undefined;
+};

package/dist/contracts/unknownContractExamples.js

@@ -0,0 +1,31 @@
+/** Exact example inputs for residual-unknown lifecycle contracts. */
+export const UNKNOWN_CONTRACT_EXAMPLES = {
+    list_unknowns: {},
+    record_unknown: {
+        question: "Does this branch require an unavailable external service?",
+        severity: "medium",
+        domain: "protocol",
+        required_authority: "controlled-replay",
+        required_confidence: "observed",
+        required_environment: null,
+        recommended_probes: [
+            { operation: "capture_process_scenario", rationale: "Replay branch." },
+        ],
+        relationships: [],
+    },
+    update_unknown: {
+        unknown_id: `unk_${"0".repeat(64)}`,
+        expected_revision: 1,
+        status: "investigating",
+        severity: "medium",
+        supporting_evidence_ids: [],
+        contradicting_evidence_ids: [],
+        required_authority: "controlled-replay",
+        required_confidence: "observed",
+        required_environment: null,
+        recommended_probes: [],
+        relationships: [],
+        resolution: null,
+    },
+    verify_unknown_resolution: { unknown_id: `unk_${"0".repeat(64)}` },
+};

package/dist/contracts/wasm/wasmToolContracts.js

@@ -0,0 +1,24 @@
+import { inspectWasmArtifactInputSchema, wasmArtifactSchema, } from "../../domain/wasm/wasmArtifact.js";
+import { toolContractMetadata } from "../toolEffects.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+/** Optional caller-supplied WABT capability with target-free CLI/MCP parity. */
+export const WASM_TOOL_CONTRACTS = [
+    {
+        name: "inspect_wasm_artifact",
+        ...toolContractMetadata("inspect_wasm_artifact"),
+        kind: "artifact-provider",
+        description: "Validate an explicit local WASM artifact with caller-supplied WABT 1.0.42, retain exact byte SHA-256, sections, upstream import/export WAT forms and decoded WAT inline as Evidence. Optionally associate selected JavaScript glue literals with explicit local candidates while preserving ambiguous URL/basename matches. Configure absolute REA_WABT_BIN_DIRECTORY. No installation, implicit fetch, WASM execution or original-source claim.",
+        inputSchema: inspectWasmArtifactInputSchema,
+        outputSchema: evidenceResultOf(wasmArtifactSchema),
+        examples: [
+            {
+                title: "Inspect a selected local WASM module",
+                input: {
+                    path: "/artifacts/module.wasm",
+                    glue_paths: [],
+                    candidate_paths: [],
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/webNetworkCaptureToolContracts.js

@@ -0,0 +1,24 @@
+import { inspectWebNetworkCaptureInputSchema, webNetworkCaptureSchema, } from "../domain/webNetworkCapture.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+/** Historical inspection is distinct from live browser capture and runtime authority. */
+export const WEB_NETWORK_CAPTURE_TOOL_CONTRACTS = [
+    {
+        name: "inspect_web_network_capture",
+        ...toolContractMetadata("inspect_web_network_capture"),
+        description: "Inspect retained local HAR 1.2 or native mitmproxy capture records without contacting recorded URLs. Returns original ordinals, pointers/byte ranges, preserved producer fields, precise numeric representations and exact exposed binary bytes inline. Excludes known transport credentials and explicitly marked values. Decodes every record before optional ordinal selection; malformed or oversized captures return no partial success. Duplicate HAR members are invalid; prototype-named members such as __proto__ are preserved as ordinary own JSON members without prototype mutation. Uses pinned upstream parsers, owned temporary files and bounded offline processes. Native mitmproxy requires caller-supplied mitmdump 12.2.3 on Linux. Browser transaction IDs, runtime attribution and original bytes of HAR Unicode text remain unknown.",
+        kind: "browser-provider",
+        inputSchema: inspectWebNetworkCaptureInputSchema,
+        outputSchema: evidenceResultOf(webNetworkCaptureSchema),
+        examples: [
+            {
+                title: "Inspect historical HAR entries",
+                input: {
+                    capture_path: "/captures/session.har",
+                    format: "har",
+                    record_ordinals: [0, 2],
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/webRuntimeToolContracts.js

@@ -0,0 +1,43 @@
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+import { observeWebExecutionInputSchema, webExecutionSchema, } from "../domain/webExecution.js";
+import { inspectWebEventListenersInputSchema, webEventListenersSchema, } from "../domain/webEventListeners.js";
+/** Native website runtime primitives distinguish instrumentation from listener inspection. */
+export const WEB_RUNTIME_TOOL_CONTRACTS = [
+    {
+        name: "observe_web_execution",
+        ...toolContractMetadata("observe_web_execution"),
+        description: "Instrument one selected CDP page for a finite, externally driven precise coverage window. Resets execution counters and prevents optimized execution until stopped. Returns complete nested UTF-16 ranges/counts, independently hashed script text and request initiator associations by session script ID. Does not navigate, click, evaluate selected code or close the externally owned page. Navigation ends document-scoped collection; workers and UI causality remain outside this claim. Emits an actual armed progress notification before external actions.",
+        kind: "browser-provider",
+        inputSchema: observeWebExecutionInputSchema,
+        outputSchema: evidenceResultOf(webExecutionSchema),
+        examples: [
+            {
+                title: "Attribute externally triggered page execution",
+                input: {
+                    cdp_endpoint: "http://127.0.0.1:9222",
+                    target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
+                    observation_ms: 10_000,
+                },
+            },
+        ],
+    },
+    {
+        name: "inspect_web_event_listeners",
+        ...toolContractMetadata("inspect_web_event_listeners"),
+        description: "Inspect listeners registered directly on the first main-document CSS match in one selected CDP page. Returns event flags, native callback locations, source ownership and exact script text/digests inline. Does not dispatch events, evaluate JavaScript or invoke handlers. Delegated ancestor/framework listeners and execution history remain unknown. Releases REA's object group and transport, preserving the external page.",
+        kind: "browser-provider",
+        inputSchema: inspectWebEventListenersInputSchema,
+        outputSchema: evidenceResultOf(webEventListenersSchema),
+        examples: [
+            {
+                title: "Find a selected button's callback source",
+                input: {
+                    cdp_endpoint: "http://127.0.0.1:9222",
+                    target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
+                    selector: "#submit",
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/webScriptToolContracts.js

@@ -0,0 +1,68 @@
+import { exportWebScriptsInputSchema, webScriptExportResultSchema, } from "../domain/webScriptExport.js";
+import { webModuleTraceInputSchema, webModuleTraceResultSchema, } from "../domain/webModuleTrace.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+import { webSourceLocationInputSchema, webSourceLocationResultSchema, } from "../domain/webSourceLocation.js";
+/** Local captured-script publication contracts shared by CLI and MCP. */
+export const WEB_SCRIPT_TOOL_CONTRACTS = [
+    {
+        name: "trace_web_source_location",
+        ...toolContractMetadata("trace_web_source_location"),
+        description: "Trace one generated position in an exported website script through an explicitly paired local source map. Verifies manifest, selected script and map SHA-256/byte identities; returns every equal-position mapping, reported source/root, resolved source URL, embedded sourcesContent and original position inline. One-based lines and zero-based UTF-16 columns; greatest generated position <= requested across lines. Duplicate sources and generated-only mappings remain distinct. Caller-selected pairing does not establish deployment authenticity or execution. Regular maps and inline indexed sections only; external section URLs are unsupported. No network access or application execution; uses the pinned upstream codec in an owned Node process with private temporary files, independent 192 MiB old-generation heap and 20-second deadline. 4 MiB map, 32 MiB reply; complete evidence or actionable resource failure. Cleanup may extend the deadline.",
+        kind: "application",
+        inputSchema: webSourceLocationInputSchema,
+        outputSchema: evidenceResultOf(webSourceLocationResultSchema),
+        examples: [
+            {
+                title: "Trace a selected captured JavaScript point to embedded original source",
+                input: {
+                    manifest_path: "/analysis/scripts/manifest.json",
+                    script_index: 0,
+                    source_map: {
+                        path: "/analysis/app.js.map",
+                        url: "https://example.test/app.js.map",
+                    },
+                    generated_position: { line: 1, column: 25 },
+                },
+            },
+        ],
+    },
+    {
+        name: "trace_web_module_imports",
+        ...toolContractMetadata("trace_web_module_imports"),
+        description: "Trace one exported website script's outgoing native ES imports/re-exports, using exact URL and optional selected import-map context. Reads a local export_web_scripts manifest and verifies the selected source's SHA-256/size; returns source positions, native resolved URLs or exact errors, every matching captured candidate and explicit unknown execution. Query/fragment identities are preserved. Computed imports and bundler IDs remain unknown. Select importer_url for unknown inline/document-base context. Caller-supplied Chromium executes only a trusted REA resolver stub in an owned context with page requests locally fulfilled/blocked; no captured application execution or asset refetch. Requires absolute REA_BROWSER_EXECUTABLE for literal imports. 32 MiB manifest, 16 MiB source, 4 MiB map and 20-second native deadline; cleanup may extend the deadline.",
+        kind: "application",
+        inputSchema: webModuleTraceInputSchema,
+        outputSchema: evidenceResultOf(webModuleTraceResultSchema),
+        examples: [
+            {
+                title: "Trace an exported module under a selected import map",
+                input: {
+                    manifest_path: "/analysis/exported-scripts/manifest.json",
+                    script_index: 0,
+                    import_map: {
+                        path: "/analysis/import-map.json",
+                        base_url: "https://example.test/app/",
+                    },
+                },
+            },
+        ],
+    },
+    {
+        name: "export_web_scripts",
+        ...toolContractMetadata("export_web_scripts"),
+        description: "Export JavaScript bytes already retained in one local inspect_web_page or capture_browser_scenario JSON capture (normalized result or complete Evidence). Writes scripts and a digest-verified manifest into an absent absolute output_directory. Returns all source URLs, script or transaction/event references, unavailable states, and an analysis_input for analyze_javascript_application when any bytes were exported. Include script sources in inspect_web_page or select capture.network.response_body in scenarios. No refetch or execution. Safe unambiguous URL layouts preserve relative module paths; versions, query variants, inline scripts, and path collisions are isolated with explicit resolution limitations.",
+        kind: "application",
+        inputSchema: exportWebScriptsInputSchema,
+        outputSchema: evidenceResultOf(webScriptExportResultSchema),
+        examples: [
+            {
+                title: "Export a saved website capture for static JavaScript analysis",
+                input: {
+                    capture_path: "/analysis/capture.json",
+                    output_directory: "/analysis/exported-scripts",
+                },
+            },
+        ],
+    },
+];

package/dist/doctorRuntime.js

@@ -0,0 +1,53 @@
+import { systemDoctorHost, } from "./application/Doctor.js";
+import { fileURLToPath } from "node:url";
+import { inspectSystemGhidraProvider } from "./ghidra/GhidraDoctor.js";
+import { inspectIdaRegistration } from "./ida/IdaDoctor.js";
+import { selectLinuxPrivateDisplayStrategy } from "./hopper/LinuxPrivateDisplayProbe.js";
+/** Compose provider diagnostics at the outer CLI adapter boundary. */
+export const createSystemDoctorHost = (environment = process.env) => systemDoctorHost({
+    environment,
+    providerInspections: async () => [
+        await inspectSystemGhidraProvider(environment),
+        inspectIdaRegistration(environment.REA_IDA_MCP_CONFIG),
+    ],
+    linuxDemoRuntimeCheck: () => inspectLinuxPrivateDisplay(environment),
+});
+const HOPPER_DEMO_HELPER_PATH = fileURLToPath(new URL("../scripts/hopper-demo-x11.py", import.meta.url));
+const inspectLinuxPrivateDisplay = async (environment) => {
+    const selection = await selectLinuxPrivateDisplayStrategy({
+        helperPath: HOPPER_DEMO_HELPER_PATH,
+        environment,
+    });
+    const value = selection.diagnostic;
+    const detail = [
+        `strategy=${selection.strategy}`,
+        `socket_directory=${value.socket_directory}`,
+        `mode=${value.socket_directory_mode ?? "unknown"}`,
+        `mount_read_only=${String(value.mount_read_only)}`,
+        `effective_mode=${value.effective_socket_directory_mode ?? "unknown"}`,
+        `effective_mount_read_only=${String(value.effective_mount_read_only)}`,
+        `wsl=${String(value.wsl)}`,
+    ].join("; ");
+    if (selection.ok)
+        return {
+            name: "hopper-demo-runtime",
+            ok: true,
+            classification: "healthy",
+            detail,
+            details: { private_display: { ...value } },
+        };
+    const missingDependency = value.failure_code === "runtime_dependency_unavailable" ||
+        value.failure_code === "x11_authorization_failed";
+    return {
+        name: "hopper-demo-runtime",
+        ok: false,
+        classification: missingDependency ? "missing_dependency" : "config_drift",
+        detail,
+        details: { private_display: { ...value } },
+        remediation: value.failure_code === "x11_socket_directory_unusable"
+            ? "Enable unprivileged user and mount namespaces, or provide a writable mode-1777 /tmp/.X11-unix directory. Do not mutate the current host mount with sudo; then rerun reverseport doctor --provider hopper."
+            : missingDependency
+                ? "Install Xvfb, xauth, Python 3, libX11, and libXtst, then rerun reverseport doctor --provider hopper."
+                : "Inspect the private-display diagnostic, correct the reported local condition, and rerun reverseport doctor --provider hopper.",
+    };
+};