reverseport 0.0.0-stage → 1.0.0

package/dist/domain/analysisView/analysisView.js

@@ -0,0 +1,340 @@
+import { z } from "zod";
+import { javaScriptSourceSelectionSchema } from "../javascript/javascriptSourceSelection.js";
+import { AnalysisInputError, AnalysisUnsupportedTargetError, } from "../analysisErrorCore.js";
+import { digestCanonicalValue } from "../canonicalDigest.js";
+import { digestSchema, prefixedDigestSchema } from "../digests.js";
+import { evidenceSchema } from "../evidence.js";
+import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js";
+import { err, ok } from "../result.js";
+import { binaryLayoutSchema } from "../native/binaryLayout.js";
+import { functionDossierSchema } from "../hopperValues.js";
+import { parseOwnedJavaScriptApplicationAnalysisSteps, } from "../javascript/javascriptApplicationAnalysis.js";
+import { analysisInputErrorFromIssues } from "../inputIssueProjection.js";
+import { projectBinaryLayoutView } from "./binaryLayoutView.js";
+import { projectJavaScriptApplicationView } from "./javascriptApplicationView.js";
+import { projectWebNetworkApiSurfaceView, apiSurfaceFields, apiSurfaceViewSchema, } from "./webNetworkApiSurfaceView.js";
+import { projectNativeFunctionView } from "./nativeFunctionView.js";
+/** Public name of the selected-view workflow. */
+export const INSPECT_ANALYSIS_VIEW_OPERATION = "inspect_analysis_view";
+const summaryViewSchema = z.strictObject({ kind: z.literal("summary") });
+const facetViewSchema = z.strictObject({
+    kind: z.literal("facet"),
+    facet: z.enum(["mitigations", "linkage"]),
+});
+const indexSelectorSchema = z.strictObject({
+    index: z.number().int().nonnegative(),
+});
+const nameSelectorSchema = z.strictObject({ name: z.string() });
+const pathSelectorSchema = z.strictObject({
+    path: z
+        .string()
+        .describe("Exact observed module path or original source-map reference from a module page; an empty reference is valid."),
+});
+const nodeIdSelectorSchema = z.strictObject({
+    node_id: prefixedDigestSchema("jag_node"),
+});
+const moduleItemViewSchema = z.strictObject({
+    kind: z.literal("item"),
+    collection: z.literal("modules"),
+    selector: z.union([pathSelectorSchema, nodeIdSelectorSchema]),
+});
+const sectionOrSymbolItemViewSchema = z.strictObject({
+    kind: z.literal("item"),
+    collection: z.enum(["sections", "symbols"]),
+    selector: z.union([indexSelectorSchema, nameSelectorSchema]),
+});
+/**
+ * The collection-specific selector alternatives are expressed in the owning
+ * contract so the advertised JSON Schema preserves them: modules accept
+ * path/node_id, sections and symbols accept index/name. Refinement-only
+ * constraints do not survive JSON Schema conversion, so the advertised
+ * schema previously accepted combinations that runtime input validation
+ * rejects.
+ */
+const itemViewSchema = z.discriminatedUnion("collection", [
+    moduleItemViewSchema,
+    sectionOrSymbolItemViewSchema,
+]);
+const pageViewSchema = z.strictObject({
+    kind: z.literal("page"),
+    collection: z.enum(["sections", "symbols", "modules"]),
+    offset: z.number().int().nonnegative(),
+    limit: z.number().int().positive(),
+});
+/** Bounded native function facets of already authenticated analyze_function Evidence. */
+const nativeViewSchema = z.strictObject({
+    kind: z.literal("native"),
+    facet: z.enum([
+        "procedure",
+        "pseudocode",
+        "assembly",
+        "basic_blocks",
+        "comments",
+        "callers",
+        "callees",
+        "incoming_references",
+        "outgoing_references",
+        "unresolved_calls",
+        "referenced_strings",
+        "referenced_names",
+        "native_api",
+        "value_flow_summary",
+        "value_flow_operations",
+        "value_flow_def_use",
+        "value_flow_effects",
+        "value_flow_parameters",
+        "value_flow_parameter_uses",
+    ]),
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().positive().default(64),
+});
+/** Caller-selected projection of already completed analysis Evidence. */
+export const analysisViewRequestSchema = z.discriminatedUnion("kind", [
+    summaryViewSchema,
+    facetViewSchema,
+    itemViewSchema,
+    pageViewSchema,
+    nativeViewSchema,
+    apiSurfaceViewSchema,
+]);
+// The application owns admission and authenticated Evidence parsing. SDK and
+// CLI envelope parsing must borrow this unknown value rather than clone it
+// before admission. Advertise the owning Evidence contract in both dialects.
+const inlineEvidenceInputSchema = z.unknown().nonoptional();
+inlineEvidenceInputSchema._zod.processJSONSchema =
+    evidenceSchema._zod.processJSONSchema;
+/** Unauthenticated inline input or an exact same-session retained reference. */
+export const analysisViewSourceSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("retained-evidence"),
+        evidence_id: prefixedDigestSchema("ev"),
+    }),
+    z.strictObject({
+        kind: z.literal("inline"),
+        evidence: inlineEvidenceInputSchema,
+    }),
+]);
+/** Public inspect_analysis_view input. */
+export const inspectAnalysisViewInputSchema = z.strictObject({
+    source: analysisViewSourceSchema,
+    view: analysisViewRequestSchema,
+});
+const coverageSchema = z.strictObject({
+    status: z.enum(["complete-within-view", "page", "empty"]),
+    examined: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+    next_offset: z.number().int().nonnegative().nullable(),
+    exhausted: z.boolean(),
+});
+const artifactSchema = z.strictObject({
+    path: z
+        .string()
+        .describe("Exact recorded artifact path, including an empty string."),
+    sha256: digestSchema,
+});
+const layoutSummarySchema = z.strictObject({
+    bytes: z.number().int().nonnegative(),
+    format: z.literal("elf"),
+    architecture: z.strictObject({
+        machine: z.literal("EM_X86_64"),
+        bits: z.literal(64),
+        byte_order: z.literal("little"),
+    }),
+    image_type: z.enum(["ET_EXEC", "ET_DYN", "ET_REL"]),
+    entry: z.strictObject({
+        reported_value: z.string().min(1),
+        meaning: z.enum(["linked-virtual-address", "not-applicable", "absent"]),
+        execution_status: z.literal("unknown"),
+    }),
+    counts: z.strictObject({
+        sections: z.number().int().nonnegative(),
+        segments: z.number().int().nonnegative(),
+        symbols: z.number().int().nonnegative(),
+        relocations: z.number().int().nonnegative(),
+    }),
+    limitation_count: z.number().int().nonnegative(),
+});
+const javascriptSummarySchema = z.strictObject({
+    input_path: z.string().min(1),
+    format: z.enum(["asar", "directory"]),
+    root_artifact_sha256: digestSchema,
+    source_selection: javaScriptSourceSelectionSchema.exactOptional(),
+    statistics: jsonObjectSchema,
+    electron: jsonObjectSchema,
+    coverage: jsonObjectSchema,
+    limitation_count: z.number().int().nonnegative(),
+});
+const summaryViewResultFields = {
+    kind: z.literal("summary"),
+    view: summaryViewSchema,
+    parent_evidence_id: prefixedDigestSchema("ev"),
+    parent_digest: digestSchema,
+    view_digest: digestSchema,
+    artifact: artifactSchema,
+    coverage: coverageSchema,
+    limitations: z.array(z.string()),
+    unknowns: z.array(z.string()),
+};
+/** Summary `inspect_binary_layout` detail returns; no other view kind. */
+export const binaryLayoutSummaryViewResultSchema = z.strictObject({
+    ...summaryViewResultFields,
+    summary: layoutSummarySchema,
+    parent_operation: z.literal("inspect_binary_layout"),
+});
+/** Summary `analyze_javascript_application` detail returns; no other view kind. */
+export const javascriptApplicationSummaryViewResultSchema = z.strictObject({
+    ...summaryViewResultFields,
+    summary: javascriptSummarySchema,
+    parent_operation: z.literal("analyze_javascript_application"),
+});
+const viewResultBase = {
+    parent_evidence_id: prefixedDigestSchema("ev"),
+    parent_operation: z.enum([
+        "inspect_binary_layout",
+        "analyze_javascript_application",
+        "analyze_function",
+    ]),
+    parent_digest: digestSchema,
+    view_digest: digestSchema,
+    artifact: artifactSchema,
+    coverage: coverageSchema,
+    limitations: z.array(z.string()),
+    unknowns: z.array(z.string()),
+};
+/** Projected facts for one selected view of retained analysis Evidence. */
+export const analysisViewResultSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        ...viewResultBase,
+        ...apiSurfaceFields,
+        kind: z.literal("api-surface"),
+        parent_operation: z.literal("inspect_web_network_capture"),
+        view: apiSurfaceViewSchema,
+        artifact: z.strictObject({
+            path: z.string(),
+            sha256: digestSchema.nullable(),
+        }),
+    }),
+    z.strictObject({
+        kind: z.literal("summary"),
+        view: summaryViewSchema,
+        summary: z.union([layoutSummarySchema, javascriptSummarySchema]),
+        ...viewResultBase,
+    }),
+    z.strictObject({
+        kind: z.literal("facet"),
+        view: facetViewSchema,
+        facet: jsonValueSchema,
+        ...viewResultBase,
+    }),
+    z.strictObject({
+        kind: z.literal("item"),
+        view: itemViewSchema,
+        item: jsonValueSchema,
+        ...viewResultBase,
+    }),
+    z.strictObject({
+        kind: z.literal("page"),
+        view: pageViewSchema,
+        items: z.array(jsonValueSchema),
+        ...viewResultBase,
+    }),
+    z.strictObject({
+        kind: z.literal("native"),
+        view: nativeViewSchema,
+        procedure_address: z.string().nullable(),
+        item: jsonValueSchema,
+        ...viewResultBase,
+    }),
+]);
+/** Construct a typed input failure for one selected-view constraint. */
+export const analysisViewInputError = (issues) => new AnalysisInputError(INSPECT_ANALYSIS_VIEW_OPERATION, undefined, issues);
+/** Attach the content digest that must change when projected bytes change. */
+export const sealAnalysisView = (projection) => analysisViewResultSchema.parse({
+    ...projection,
+    view_digest: digestCanonicalValue(projection, "Analysis view"),
+});
+const parentDigest = (evidenceId) => evidenceId.slice(3);
+const parseJavaScriptParent = (input) => {
+    try {
+        // Only the existing realm-private graph proofs permit reuse. Imported or
+        // merely frozen graphs still receive full canonical validation.
+        const steps = parseOwnedJavaScriptApplicationAnalysisSteps(input);
+        let step = steps.next();
+        while (!step.done)
+            step = steps.next();
+        return ok(step.value);
+    }
+    catch (cause) {
+        if (!(cause instanceof z.ZodError))
+            throw cause;
+        return err(analysisInputErrorFromIssues(INSPECT_ANALYSIS_VIEW_OPERATION, cause.issues.map((issue) => ({
+            ...issue,
+            path: ["source", "normalized_result", ...issue.path],
+        })), { source: { normalized_result: input } }, { cause }));
+    }
+};
+const unsupportedParent = (parent) => new AnalysisUnsupportedTargetError(INSPECT_ANALYSIS_VIEW_OPERATION, parentArtifactPath(parent), `Parent Evidence operation ${JSON.stringify(parent.operation)} is not inspect_binary_layout, analyze_javascript_application or analyze_function.`);
+const parentArtifactPath = (parent) => {
+    if (typeof parent.normalizedResult === "object" &&
+        parent.normalizedResult !== null &&
+        "artifact" in parent.normalizedResult &&
+        typeof parent.normalizedResult.artifact === "object" &&
+        parent.normalizedResult.artifact !== null &&
+        "path" in parent.normalizedResult.artifact &&
+        typeof parent.normalizedResult.artifact.path === "string")
+        return parent.normalizedResult.artifact.path;
+    if (typeof parent.normalizedResult === "object" &&
+        parent.normalizedResult !== null &&
+        "input_path" in parent.normalizedResult &&
+        typeof parent.normalizedResult.input_path === "string")
+        return parent.normalizedResult.input_path;
+    return parent.evidenceId;
+};
+/** Project one selected view from authenticated parent analysis Evidence. */
+export const projectAnalysisView = (parent, view, apiSurfaceAccumulator) => {
+    const digest = parentDigest(parent.evidenceId);
+    if (!digestSchema.safeParse(digest).success)
+        return err(analysisViewInputError([
+            {
+                path: ["source"],
+                reason: "invalid_format",
+                message: "Parent Evidence ID is not a digest-backed identifier.",
+            },
+        ]));
+    if (view.kind === "api-surface" ||
+        parent.operation === "inspect_web_network_capture") {
+        const projected = projectWebNetworkApiSurfaceView(parent, view, apiSurfaceAccumulator);
+        return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;
+    }
+    if (parent.operation === "inspect_binary_layout") {
+        const layout = binaryLayoutSchema.safeParse(parent.normalizedResult);
+        if (!layout.success)
+            return err(analysisViewInputError([
+                {
+                    path: ["source"],
+                    reason: "invalid_value",
+                    message: "Parent Evidence result does not match inspect_binary_layout.",
+                },
+            ]));
+        const projected = projectBinaryLayoutView(parent, layout.data, view);
+        return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;
+    }
+    if (parent.operation === "analyze_javascript_application") {
+        const analysis = parseJavaScriptParent(parent.normalizedResult);
+        if (!analysis.ok)
+            return analysis;
+        const projected = projectJavaScriptApplicationView(parent, analysis.value, view);
+        return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;
+    }
+    if (parent.operation === "analyze_function") {
+        const native = functionDossierSchema.safeParse(parent.normalizedResult);
+        if (!native.success)
+            return err(analysisInputErrorFromIssues(INSPECT_ANALYSIS_VIEW_OPERATION, native.error.issues.map((issue) => ({
+                ...issue,
+                path: ["source", "normalized_result", ...issue.path],
+            })), { source: { normalized_result: parent.normalizedResult } }, { cause: native.error }));
+        const projected = projectNativeFunctionView(parent, native.data, view);
+        return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;
+    }
+    return err(unsupportedParent(parent));
+};

package/dist/domain/analysisView/analysisViewCoverage.js

@@ -0,0 +1,19 @@
+/** Coverage for a summary, facet, or single selected object. */
+export const completeWithinViewCoverage = (examined, total) => ({
+    status: "complete-within-view",
+    examined,
+    total,
+    next_offset: null,
+    exhausted: true,
+});
+/** Coverage for a stable page, including an offset past the collection. */
+export const pageViewCoverage = (offset, examined, total) => {
+    const exhausted = offset >= total || offset + examined >= total;
+    return {
+        status: examined === 0 ? "empty" : "page",
+        examined,
+        total,
+        next_offset: exhausted ? null : offset + examined,
+        exhausted,
+    };
+};

package/dist/domain/analysisView/binaryLayoutView.js

@@ -0,0 +1,161 @@
+import { AnalysisInputError, } from "../analysisErrorCore.js";
+import { uniqueSorted } from "../canonicalOrdering.js";
+import { err, ok } from "../result.js";
+import { completeWithinViewCoverage as completeCoverage, pageViewCoverage as pageCoverage, } from "./analysisViewCoverage.js";
+const OPERATION = "inspect_analysis_view";
+const inputError = (issues) => new AnalysisInputError(OPERATION, undefined, issues);
+const layoutUnknowns = (layout) => {
+    const unknowns = [
+        "runtime_load_base is unknown",
+        "entry_point.execution_status is unknown",
+        "relocation_inventory_completeness is unknown",
+        "linkage.convenience_maps_completeness is unknown",
+        "linkage.runtime_library_paths are unknown",
+    ];
+    if (layout.mitigations.nx_indicator === null)
+        unknowns.push("mitigations.nx_indicator is unknown");
+    if (layout.mitigations.relro === null)
+        unknowns.push("mitigations.relro is unknown");
+    return unknowns;
+};
+const displayName = (name) => name.display;
+const namedMatches = (rows, name) => rows.flatMap((row, index) => row.name.unknown_reason === null && displayName(row.name) === name
+    ? [{ index, row }]
+    : []);
+const selectNamed = (collection, rows, name) => {
+    const matches = namedMatches(rows, name);
+    if (matches.length === 1) {
+        const selected = matches[0];
+        if (selected !== undefined)
+            return ok(selected.row);
+    }
+    if (matches.length === 0)
+        return err(inputError([
+            {
+                path: ["view", "selector", "name"],
+                reason: "invalid_value",
+                message: `No ${collection} named ${JSON.stringify(name)}. Collection has ${String(rows.length)} entries; page it to inspect exact indexes and names.`,
+            },
+        ]));
+    return err(inputError([
+        {
+            path: ["view", "selector", "name"],
+            reason: "invalid_value",
+            message: `Multiple ${collection} named ${JSON.stringify(name)}; select one by index.`,
+            expected: matches.map(({ index }) => ({ index })),
+        },
+    ]));
+};
+const selectIndexed = (collection, rows, index) => {
+    const row = rows[index];
+    if (row !== undefined)
+        return ok(row);
+    return err(inputError([
+        {
+            path: ["view", "selector", "index"],
+            reason: "out_of_range",
+            message: `${collection} index ${String(index)} is outside 0..${String(Math.max(0, rows.length - 1))} (${String(rows.length)} entries).`,
+            minimum: 0,
+            maximum: Math.max(0, rows.length - 1),
+        },
+    ]));
+};
+const pageRows = (rows, offset, limit) => rows.slice(offset, offset + limit);
+const layoutIncompatible = (detail) => inputError([
+    {
+        path: ["view"],
+        reason: "invalid_value",
+        message: detail,
+    },
+]);
+const parentFields = (parent, layout) => ({
+    parent_evidence_id: parent.evidenceId,
+    parent_operation: "inspect_binary_layout",
+    parent_digest: parent.evidenceId.slice(3),
+    artifact: {
+        path: layout.artifact.path,
+        sha256: layout.artifact.sha256,
+    },
+    limitations: uniqueSorted([...parent.limitations, ...layout.limitations]),
+    unknowns: uniqueSorted([...layoutUnknowns(layout)]),
+});
+const layoutSummary = (layout) => ({
+    bytes: layout.artifact.bytes,
+    format: layout.format,
+    architecture: layout.architecture,
+    image_type: layout.image_type,
+    entry: layout.entry_point,
+    counts: {
+        sections: layout.sections.length,
+        segments: layout.segments.length,
+        symbols: layout.symbols.length,
+        relocations: layout.relocations.length,
+    },
+    limitation_count: layout.limitations.length,
+});
+/** Project one layout view without re-running the decoder. */
+export const projectBinaryLayoutView = (parent, layout, view) => {
+    const shared = parentFields(parent, layout);
+    if (view.kind === "native")
+        return err(layoutIncompatible("Native views require analyze_function Evidence."));
+    if (view.kind === "summary")
+        return ok({
+            kind: "summary",
+            view,
+            summary: layoutSummary(layout),
+            coverage: completeCoverage(layout.sections.length +
+                layout.segments.length +
+                layout.symbols.length +
+                layout.relocations.length, layout.sections.length +
+                layout.segments.length +
+                layout.symbols.length +
+                layout.relocations.length),
+            ...shared,
+        });
+    if (view.kind === "facet")
+        return ok({
+            kind: "facet",
+            view,
+            facet: view.facet === "mitigations" ? layout.mitigations : layout.linkage,
+            coverage: completeCoverage(1, 1),
+            ...shared,
+        });
+    if (view.kind === "item") {
+        if (view.collection === "modules")
+            return err(layoutIncompatible("modules collection applies to analyze_javascript_application Evidence."));
+        const selected = view.collection === "sections"
+            ? selectLayoutItem(view.collection, layout.sections, view.selector)
+            : selectLayoutItem(view.collection, layout.symbols, view.selector);
+        if (!selected.ok)
+            return selected;
+        return ok({
+            kind: "item",
+            view,
+            item: selected.value,
+            coverage: completeCoverage(1, view.collection === "sections"
+                ? layout.sections.length
+                : layout.symbols.length),
+            ...shared,
+        });
+    }
+    if (view.collection === "modules")
+        return err(layoutIncompatible("modules collection applies to analyze_javascript_application Evidence."));
+    const rows = view.collection === "sections" ? layout.sections : layout.symbols;
+    const items = view.collection === "sections"
+        ? pageRows(layout.sections, view.offset, view.limit)
+        : pageRows(layout.symbols, view.offset, view.limit);
+    return ok({
+        kind: "page",
+        view,
+        items: [...items],
+        coverage: pageCoverage(view.offset, items.length, rows.length),
+        ...shared,
+    });
+};
+const selectLayoutItem = (collection, rows, selector) => {
+    if ("index" in selector)
+        return selectIndexed(collection, rows, selector.index);
+    if ("name" in selector)
+        return selectNamed(collection, rows, selector.name);
+    return err(layoutIncompatible("Section and symbol items are selected by index or exact name."));
+};