diff --git a/src/domain/analysisView/EnvironmentManifestAccumulator.ts b/src/domain/analysisView/EnvironmentManifestAccumulator.ts index 5dd44d28d2..fb3018c064 100644 --- a/src/domain/analysisView/EnvironmentManifestAccumulator.ts +++ b/src/domain/analysisView/EnvironmentManifestAccumulator.ts @@ -16,7 +16,8 @@ import { } from "./recordedResponseBody.js"; import { readRecordedRequestBody } from "./recordedExchangeBody.js"; import { isJson, isJsonLike, mediaTypeEssence } from "./recordedMediaType.js"; -import type { UnsignedAnalysisView } from "./analysisView.js"; +import { z } from "zod"; +import { environmentManifestFields } from "./environmentManifestSchema.js"; import type { ScenarioResponseBodyRetention } from "./scenarioCaptureRecords.js"; import { WebNetworkProjectionAccumulator } from "./WebNetworkProjectionAccumulator.js"; import { @@ -55,21 +56,13 @@ import { type RouteTemplate, } from "./webNetworkRouteTemplates.js"; -type Manifest = Extract; -type ManifestFields = Pick< - Manifest, - | "origin" - | "name" - | "tools" - | "records" - | "excluded" - | "unknowns" - | "templated_groups" - | "coverage" - | "limitations" ->; -type Tool = Manifest["tools"][number]; -type Exclusion = Manifest["excluded"][number]; +type ManifestCore = { + [Key in keyof typeof environmentManifestFields]: z.output< + (typeof environmentManifestFields)[Key] + >; +}; +type Tool = ManifestCore["tools"][number]; +type Exclusion = ManifestCore["excluded"][number]; type RequestLine = Extract; interface RecordLine { @@ -134,7 +127,7 @@ const WRITE_METHODS = new Set(["POST", "PUT", "PATCH"]); const BODILESS_WRITE_METHODS = new Set([...WRITE_METHODS, "DELETE"]); /** Quotes, separators and brackets a four-part composite key adds around its texts. */ const KEY_OVERHEAD_CHARS = 32; -const UNKNOWNS: Manifest["unknowns"] = [ +const UNKNOWNS: ManifestCore["unknowns"] = [ { kind: "authorization-model", statement: @@ -477,7 +470,7 @@ export class EnvironmentManifestAccumulator extends WebNetworkProjectionAccumula } /** Project the complete manifest; tools, records and exclusions are sorted deterministically. */ - finish(): Result { + finish() { const primary = primaryOrigin(this.#origins); const toolGroups: GroupState[] = []; const exclusions = new Map(); diff --git a/src/domain/analysisView/EnvironmentStateAccumulator.ts b/src/domain/analysisView/EnvironmentStateAccumulator.ts index bf8b2763c5..4808d9506f 100644 --- a/src/domain/analysisView/EnvironmentStateAccumulator.ts +++ b/src/domain/analysisView/EnvironmentStateAccumulator.ts @@ -11,7 +11,6 @@ import { WEB_NETWORK_CAPTURE_LIMITS, type WebNetworkCaptureRecord, } from "../webNetworkCapture.js"; -import type { UnsignedAnalysisView } from "./analysisView.js"; import { EnvironmentManifestAccumulator } from "./EnvironmentManifestAccumulator.js"; import { isJsonLike, mediaTypeEssence } from "./recordedMediaType.js"; import { readRecordedRequestBody } from "./recordedExchangeBody.js"; @@ -40,23 +39,6 @@ import { textBytes, } from "./webNetworkRouteTemplates.js"; -type StateView = Extract; -type StateFields = Pick< - StateView, - | "origin" - | "name" - | "timeline" - | "types" - | "entities" - | "documents" - | "views" - | "writes" - | "write_clock" - | "unknowns" - | "coverage" - | "limitations" ->; - /** * Levels the state's own nesting adds above a recorded value: Evidence, a `data/get` reply and a * JSON-RPC response hold a body's members about ten levels down, so a body must leave this much @@ -102,19 +84,19 @@ interface RecordEntry { readonly record: WebNetworkCaptureRecord; } -const UNKNOWNS: StateView["unknowns"] = [ +const UNKNOWNS = [ { - kind: "authorization-model", + kind: "authorization-model" as const, statement: "Authorization headers and cookies are structurally excluded from captures; the state states no authorization model.", }, { - kind: "response-semantics", + kind: "response-semantics" as const, statement: "Views reproduce their recorded responses from the state; they do not establish how the application computes responses, derived values or values copied outside entity objects.", }, { - kind: "state-transition", + kind: "state-transition" as const, statement: "The state is one snapshot from before the first related recorded write; write effects are modelled only from the calls the capture recorded, and served only where its later reads confirmed them.", }, @@ -340,7 +322,7 @@ export class EnvironmentStateAccumulator extends EnvironmentManifestAccumulator } /** Project the init state of the manifest's primary origin; records keep timeline order. */ - finishState(): Result { + finishState() { const manifest = this.finish(); if (!manifest.ok) return manifest; const entries = [...this.#entries.values()].filter( diff --git a/src/domain/analysisView/WebNetworkApiSurfaceAccumulator.ts b/src/domain/analysisView/WebNetworkApiSurfaceAccumulator.ts index 5f603b26b3..fbbf65426d 100644 --- a/src/domain/analysisView/WebNetworkApiSurfaceAccumulator.ts +++ b/src/domain/analysisView/WebNetworkApiSurfaceAccumulator.ts @@ -7,7 +7,8 @@ import { type WebNetworkCaptureRecord, } from "../webNetworkCapture.js"; import { pageViewCoverage } from "./analysisViewCoverage.js"; -import type { UnsignedAnalysisView } from "./analysisView.js"; +import { z } from "zod"; +import { apiSurfaceFields } from "./apiSurfaceSchema.js"; import { WebNetworkProjectionAccumulator } from "./WebNetworkProjectionAccumulator.js"; import { CAPTURE_CONTAINER_BYTES, @@ -23,9 +24,13 @@ import { type RouteTemplate, } from "./webNetworkRouteTemplates.js"; -type Surface = Extract; -type Group = Surface["groups"][number]; -type Exclusion = Surface["excluded_records"][number]; +type ApiSurfaceFields = { + [Key in keyof typeof apiSurfaceFields]: z.output< + (typeof apiSurfaceFields)[Key] + >; +}; +type Group = ApiSurfaceFields["groups"][number]; +type Exclusion = ApiSurfaceFields["excluded_records"][number]; interface GroupState { readonly method: string; readonly origin: string; @@ -181,18 +186,7 @@ export class WebNetworkApiSurfaceAccumulator extends WebNetworkProjectionAccumul return ok(undefined); } - page( - offset: number, - limit: number, - ): Pick< - Surface, - | "coverage" - | "groups" - | "templated_groups" - | "excluded_records" - | "limitations" - | "unknowns" - > { + page(offset: number, limit: number) { this.#groups.sort( (a, b) => compare(a.origin, b.origin) || diff --git a/src/domain/analysisView/WebNetworkProjectionAccumulator.ts b/src/domain/analysisView/WebNetworkProjectionAccumulator.ts index 0c9d7128e3..05099da027 100644 --- a/src/domain/analysisView/WebNetworkProjectionAccumulator.ts +++ b/src/domain/analysisView/WebNetworkProjectionAccumulator.ts @@ -14,7 +14,7 @@ import { import { admitAnalysisViewData } from "./analysisViewDataAdmission.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { analysisViewResultInputError } from "./analysisViewParent.js"; -import type { AnalysisViewParent } from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; import { ENTRY_BYTES, textBytes, diff --git a/src/domain/analysisView/analysisView.ts b/src/domain/analysisView/analysisView.ts index cb32f401f7..b68199ab1c 100644 --- a/src/domain/analysisView/analysisView.ts +++ b/src/domain/analysisView/analysisView.ts @@ -1,184 +1,32 @@ -import { analysisViewCoverageSchema } from "./analysisViewCoverage.js"; -import { - javaScriptRouteInventorySourceSchema, - javaScriptRouteInventorySchema, -} from "../javascript/javascriptRouteInventory.js"; -import { nativeFunctionMatchingContextSchema } from "../native/functionMatching.js"; -import { - nativeObservationViewRequestSchema, - nativeContextViewRequestSchema, - nativeObservationItemsSchemas, - nativeContextItemsSchemas, - nativeSourceContextReferenceSchema, - nativeObservationOperationSchema, -} from "./nativeObservationSchemas.js"; -import { - NATIVE_OBSERVATION_OPERATIONS, - type NativeObservationOperation, -} from "../native/nativeObservation.js"; +import { NATIVE_OBSERVATION_OPERATIONS } from "../native/nativeObservation.js"; import { projectNativeObservationView } from "./nativeObservationView.js"; -import { - devicetreeViewRequestSchema, - devicetreeViewItemsSchema, - devicetreeSummarySchema, - devicetreePageContextSchema, - projectDevicetreeView, -} from "./devicetreeView.js"; -import { - apkSignatureViewRequestSchema, - apkSignatureViewItemsSchema, -} from "../apkSignature/apkSignatureQuery.js"; -import { - projectApkSignatureView, - apkSignatureSummarySchema, - apkSignatureSourceCoverageSchema, -} from "./apkSignatureView.js"; +import { projectDevicetreeView } from "./devicetreeView.js"; +import { projectApkSignatureView } from "./apkSignatureView.js"; import { byteEntropySchema } from "../native/byteEntropy.js"; -import { - erlangBeamViewRequestSchema, - erlangBeamViewPageSchema, - erlangBeamSummarySchema, - projectErlangBeamView, -} from "./erlangBeamView.js"; -import { - pythonPycViewRequestSchema, - pythonPycViewItemsSchema, - pythonPycSummarySchema, - projectPythonPycView, -} from "./pythonPycView.js"; -import { - nativeExportsViewRequestSchema, - nativeExportsViewItemsSchema, - nativeExportsSummarySchema, - projectNativeExportsView, -} from "./nativeExportsView.js"; -import { - byteEntropySummarySchema, - projectByteEntropyView, -} from "./byteEntropyView.js"; +import { projectErlangBeamView } from "./erlangBeamView.js"; +import { projectPythonPycView } from "./pythonPycView.js"; +import { projectNativeExportsView } from "./nativeExportsView.js"; +import { projectByteEntropyView } from "./byteEntropyView.js"; import { parseAnalysisViewResult, analysisViewResultInputError, } from "./analysisViewParent.js"; -import { - javaScriptRoutesViewRequestSchema, - javaScriptRoutesViewItemsSchema, - javaScriptRoutesViewSummarySchema, - projectJavaScriptRoutesView, -} from "./javascriptRoutesView.js"; -import { - webBundleViewRequestSchema, - webBundleViewItemsSchema, - webBundleSummarySchema, - projectWebBundleView, -} from "./webBundleView.js"; -import { webBundleAnalysisSchema } from "../webBundleAnalysis.js"; -import { recordedBrowserOriginSchema } from "../browserObservation.js"; -import { - sourceToBundleViewRequestSchema, - sourceToBundleViewItemsSchema, - sourceToBundleViewContextSchema, - projectSourceToBundleView, -} from "./sourceToBundleView.js"; -import { - gpuCodeObjectsViewRequestSchema, - gpuCodeObjectsSummarySchema, - gpuCodeObjectsItemsSchema, - gpuCodeObjectsPtxPageSchema, - projectGpuCodeObjectsView, -} from "./gpuCodeObjectsView.js"; -import { gpuCodeObjectsObjectSchema } from "../gpu/gpuCodeObjects.js"; -import { modelArtifactViewRequestSchema } from "../model/modelArtifactQuery.js"; -import { - projectModelArtifactView, - modelArtifactSummarySchema, - modelArtifactViewItemsSchema, - modelArtifactViewContextSchema, -} from "./modelArtifactView.js"; -import { - commandSummaryContext, - gdbCommandSummarySchema, - projectCommandObservationView, -} from "./commandObservationView.js"; -import { - fridaSessionStatusSummarySchema, - fridaSessionStatusViewContext, - projectFridaSessionStatusView, -} from "./fridaSessionStatusView.js"; -import { commandObservationSchema } from "../commandObservation.js"; -import { - rustBinaryViewPageSchema, - rustBinaryViewRequestSchema, -} from "../rust/rustBinaryQuery.js"; -import { - goBinarySummarySchema, - goBinaryViewContextSchema, - goBinaryViewPageSchema, - goBinaryViewRequestSchema, - projectGoBinaryView, -} from "./goBinaryView.js"; -import { - rustBinarySummarySchema, - rustBinaryViewContextSchema, - projectRustBinaryView, -} from "./rustBinaryView.js"; -import { - projectNativeFunctionMatchingView, - nativeFunctionMatchingViewRequestSchema, - nativeFunctionMatchingViewItemsSchema, -} from "./nativeFunctionMatchingView.js"; -import { - protobufViewRequestSchema, - protobufViewItemsSchema, - protobufViewContextSchema, -} from "./protobufCaptureView.js"; -import { - nativeInventoryViewRequestSchema, - nativeInventoryViewRowSchema, - nativeInventorySummarySchema, - projectNativeInventoryView, -} from "./nativeInventoryView.js"; -import { nativeViewSourceContext } from "./nativeViewContext.js"; -import { - NATIVE_INVENTORY_OPERATIONS, - nativeInventoryOperationSchema, -} from "../native/nativeInventory.js"; - -import { - evidenceFileReferenceSchema, - retainedEvidenceReferenceSchema, -} from "../evidenceReference.js"; +import { projectJavaScriptRoutesView } from "./javascriptRoutesView.js"; +import { projectWebBundleView } from "./webBundleView.js"; +import { projectSourceToBundleView } from "./sourceToBundleView.js"; +import { projectGpuCodeObjectsView } from "./gpuCodeObjectsView.js"; +import { projectModelArtifactView } from "./modelArtifactView.js"; +import { projectCommandObservationView } from "./commandObservationView.js"; +import { projectFridaSessionStatusView } from "./fridaSessionStatusView.js"; +import { projectGoBinaryView } from "./goBinaryView.js"; +import { projectRustBinaryView } from "./rustBinaryView.js"; +import { projectNativeFunctionMatchingView } from "./nativeFunctionMatchingView.js"; +import { projectNativeInventoryView } from "./nativeInventoryView.js"; +import { NATIVE_INVENTORY_OPERATIONS } from "../native/nativeInventory.js"; import { z } from "zod"; -import { - browserScenarioSummarySchema, - browserScenarioViewContextSchema, - browserScenarioViewItemsSchema, - browserScenarioViewRequestSchema, -} from "./browserScenarioViewSchemas.js"; import { projectBrowserScenarioView } from "./browserScenarioView.js"; -import { - nativeLoadImageViewRequestSchema, - nativeLoadImageViewItemsSchema, - nativeLoadImageSummarySchema, - projectNativeLoadImageView, -} from "./nativeLoadImageView.js"; -import { - desktopViewRequestSchema, - desktopViewItemsSchema, - desktopSummarySchema, - projectDesktopApplicationView, -} from "./desktopApplicationView.js"; -import { desktopCoverageSchema } from "../desktopApplication.js"; -import { - javascriptModuleReferencesRequestSchema, - javascriptModuleReferenceSchema, -} from "./javascriptModuleReferences.js"; -import { javascriptApplicationSourceCoverageSchema } from "./javascriptApplicationCoverage.js"; -import { - javascriptFactsViewRequestSchema, - javascriptFactRowSchema, -} from "./javascriptFactsView.js"; -import { javaScriptSourceSelectionSchema } from "../javascript/javascriptSourceSelection.js"; +import { projectNativeLoadImageView } from "./nativeLoadImageView.js"; +import { projectDesktopApplicationView } from "./desktopApplicationView.js"; import { AnalysisUnsupportedTargetError } from "../analysisErrorCore.js"; import { @@ -186,25 +34,11 @@ import { analysisViewInputError, } from "./analysisViewErrors.js"; import { digestCanonicalValue } from "../canonicalDigest.js"; -import { digestSchema, prefixedDigestSchema } from "../digests.js"; -import { evidenceSchema, type Evidence } from "../evidence.js"; -import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js"; +import { digestSchema } from "../digests.js"; import { err, ok, type Result } from "../result.js"; import type { AnalysisError } from "../analysisErrorBase.js"; -import { - binaryLayoutSchema, - safeParseOwnedBinaryLayout, -} from "../native/binaryLayout.js"; -import { bundleResourceRootSchema } from "../apple/bundleResourceRoot.js"; -import { - functionDossierSchema, - functionFacetAvailabilitySchema, -} from "../native/functionDossier.js"; -import { - artifactGraphManifestSchema, - artifactInventoryCoverageSchema, -} from "../artifactGraph.js"; -import { artifactInspectionResultSchema } from "../artifactInspection.js"; +import { safeParseOwnedBinaryLayout } from "../native/binaryLayout.js"; +import { functionDossierSchema } from "../native/functionDossier.js"; import { parseOwnedJavaScriptApplicationAnalysisSteps, type JavaScriptApplicationAnalysisResult, @@ -214,62 +48,16 @@ import { projectJavaScriptApplicationView } from "./javascriptApplicationView.js import { createApiSurfaceAccumulator, projectWebNetworkApiSurfaceView, - apiSurfaceFields, - apiSurfaceViewSchema, } from "./webNetworkApiSurfaceView.js"; import { projectNativeFunctionView } from "./nativeFunctionView.js"; -import { - projectEvmInterfaceView, - evmViewRequestSchema, - evmViewItemSchema, - evmSummarySchema, -} from "./evmInterfaceView.js"; -import { - projectArtifactInventoryView, - artifactInventoryViewRequestSchema, - artifactInventoryItemsSchema, - artifactInventorySummarySchema, -} from "./artifactInventoryView.js"; -import { - projectManagedArtifactView, - managedViewRequestSchema, - managedViewItemSchema, - managedSummarySchema, - managedViewContextSchema, -} from "./managedArtifactView.js"; -import { - managedMembersViewRequestSchema, - managedMembersViewPageSchema, - managedMemberSummarySchema, - managedMembersViewContextSchema, -} from "./managedMemberViewSchemas.js"; +import { projectEvmInterfaceView } from "./evmInterfaceView.js"; +import { projectArtifactInventoryView } from "./artifactInventoryView.js"; +import { projectManagedArtifactView } from "./managedArtifactView.js"; import { projectManagedMemberView } from "./managedMemberView.js"; -import { - projectWasmArtifactView, - wasmViewRequestSchema, - wasmViewItemSchema, - wasmSummarySchema, -} from "./wasmArtifactView.js"; -import { - machoSummarySchema, - machoViewContextSchema, - machoViewRows, - machoViewRequestSchema, - projectMachoView, -} from "./machoView.js"; -import { - interfaceBuilderSummarySchema, - interfaceBuilderViewContextSchema, - interfaceBuilderViewItemsSchema, - interfaceBuilderViewRequestSchema, - projectInterfaceBuilderView, -} from "./interfaceBuilderView.js"; -import { - projectWebNetworkCaptureView, - captureViewRequestSchema, - captureViewItemsSchema, - captureSummarySchema, -} from "./webNetworkCaptureView.js"; +import { projectWasmArtifactView } from "./wasmArtifactView.js"; +import { projectMachoView } from "./machoView.js"; +import { projectInterfaceBuilderView } from "./interfaceBuilderView.js"; +import { projectWebNetworkCaptureView } from "./webNetworkCaptureView.js"; import type { WebNetworkApiSurfaceAccumulator } from "./WebNetworkApiSurfaceAccumulator.js"; import type { EnvironmentManifestAccumulator } from "./EnvironmentManifestAccumulator.js"; import type { EnvironmentStateAccumulator } from "./EnvironmentStateAccumulator.js"; @@ -277,1262 +65,155 @@ import { admitAnalysisViewData } from "./analysisViewDataAdmission.js"; import { createEnvironmentManifestAccumulator, projectEnvironmentManifestView, - environmentManifestFields, - environmentManifestViewRequestSchema, } from "./environmentManifestView.js"; import { createEnvironmentStateAccumulator, - environmentStateFields, - environmentStateViewRequestSchema, projectEnvironmentStateView, } from "./environmentStateView.js"; +import { projectEnvironmentCoverageView } from "./environmentCoverageView.js"; +import { projectPcapCaptureView } from "./pcapCaptureView.js"; +import { projectAndroidPackageView } from "./androidPackageView.js"; +import { projectAndroidSymbolSummary } from "./androidSymbolView.js"; +import { projectAndroidJniView } from "./androidJniView.js"; +import { projectDartAotView } from "./dartAotView.js"; +import { projectIl2cppMetadataView } from "./il2cppMetadataView.js"; + +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import type { GroupingViewKind } from "./analysisViewShape.js"; import { - environmentCoverageFields, - environmentCoverageViewRequestSchema, - projectEnvironmentCoverageView, -} from "./environmentCoverageView.js"; + analysisViewRequestSchema, + analysisViewSourceSchema, + inspectAnalysisViewInputSchema, + type AnalysisViewRequest, + type InspectAnalysisViewInput, +} from "./analysisViewRequest.js"; import { - pcapViewRequestSchema, - pcapViewPageSchema, - pcapSummarySchema, - projectPcapCaptureView, -} from "./pcapCaptureView.js"; -import { - qlogViewRequestSchema, - qlogViewPageSchema, - qlogViewContextSchema, -} from "./qlogCaptureView.js"; -import { - projectAndroidPackageView, - androidPackageSummarySchema, - androidViewRequestSchema, - androidManifestViewItemSchema, - androidManifestViewRequestSchema, - androidComponentsViewRequestSchema, - androidComponentSummaryViewRequestSchema, - androidComponentViewRowSchema, - androidComponentViewContextSchema, - androidComponentSummarySchema, -} from "./androidPackageView.js"; -import { - projectAndroidSymbolSummary, - androidClassSummarySchema, - androidMethodSummarySchema, -} from "./androidSymbolView.js"; -import { - projectAndroidJniView, - androidJniSummarySchema, -} from "./androidJniView.js"; -import { - androidJniViewRequestSchema, - androidJniViewItemsSchema, -} from "../android/androidJniQuery.js"; -import { - projectDartAotView, - dartAotSummarySchema, - dartAotViewRequestSchema, - dartAotViewContextSchema, -} from "./dartAotView.js"; -import { - projectIl2cppMetadataView, - il2cppMetadataSummarySchema, - il2cppMetadataViewRequestSchema, - il2cppMetadataViewContextSchema, - il2cppMetadataViewItemsSchema, -} from "./il2cppMetadataView.js"; - -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.int().nonnegative(), -}); -const nameSelectorSchema = z.strictObject({ - name: z - .string() - .describe( - "Exact UTF-8 section or symbol name, matched against retained source bytes. Use index for non-UTF-8 names or unresolved name bytes.", - ), -}); -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.int().nonnegative(), - limit: z.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", - "swift_string_literals", - "swift_string_literal_omissions", - "native_api", - "value_flow_summary", - "value_flow_operations", - "value_flow_def_use", - "value_flow_effects", - "value_flow_parameters", - "value_flow_parameter_uses", - ]), - offset: z.int().nonnegative().default(0), - limit: z.int().positive().default(64), -}); - -/** Caller-selected projection of already completed analysis Evidence. */ -export const analysisViewRequestSchema = z.discriminatedUnion("kind", [ - nativeObservationViewRequestSchema, - nativeContextViewRequestSchema, - devicetreeViewRequestSchema, - erlangBeamViewRequestSchema, - pythonPycViewRequestSchema, - nativeExportsViewRequestSchema, - javaScriptRoutesViewRequestSchema, - webBundleViewRequestSchema, - nativeFunctionMatchingViewRequestSchema, - sourceToBundleViewRequestSchema, - summaryViewSchema, - goBinaryViewRequestSchema, - rustBinaryViewRequestSchema, - desktopViewRequestSchema, - facetViewSchema, - itemViewSchema, - pageViewSchema, - javascriptModuleReferencesRequestSchema, - javascriptFactsViewRequestSchema, - nativeViewSchema, - nativeInventoryViewRequestSchema, - nativeLoadImageViewRequestSchema, - artifactInventoryViewRequestSchema, - wasmViewRequestSchema, - machoViewRequestSchema, - interfaceBuilderViewRequestSchema, - evmViewRequestSchema, - managedViewRequestSchema, - managedMembersViewRequestSchema, - androidViewRequestSchema, - androidJniViewRequestSchema, - apiSurfaceViewSchema, - environmentManifestViewRequestSchema, - environmentStateViewRequestSchema, - environmentCoverageViewRequestSchema, - captureViewRequestSchema, - browserScenarioViewRequestSchema, - protobufViewRequestSchema, - qlogViewRequestSchema, - pcapViewRequestSchema, - dartAotViewRequestSchema, - il2cppMetadataViewRequestSchema, - apkSignatureViewRequestSchema, - modelArtifactViewRequestSchema, - gpuCodeObjectsViewRequestSchema, -]); - -// 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, an exact same-session retained reference, or one local Evidence file. */ -export const analysisViewSourceSchema = z.discriminatedUnion("kind", [ - retainedEvidenceReferenceSchema, - z.strictObject({ - kind: z.literal("inline"), - evidence: inlineEvidenceInputSchema, - }), - evidenceFileReferenceSchema, -]); - -/** Public inspect_analysis_view input. */ -export const inspectAnalysisViewInputSchema = z.strictObject({ - source: analysisViewSourceSchema, - view: analysisViewRequestSchema, -}); - -const artifactSchema = z.strictObject({ - path: z - .string() - .describe( - "Selected artifact path, or the canonical resource root when resource-only Evidence has no executable subject.", - ), - sha256: digestSchema.nullable(), -}); - -const layoutSummarySchema = z.strictObject({ - bytes: binaryLayoutSchema.shape.artifact.shape.bytes, - format: binaryLayoutSchema.shape.format, - architecture: binaryLayoutSchema.shape.architecture, - image_type: binaryLayoutSchema.shape.image_type, - 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.int().nonnegative(), - segments: z.int().nonnegative(), - symbols: z.int().nonnegative(), - relocations: z.int().nonnegative(), - }), - limitation_count: z.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.int().nonnegative(), -}); - -const viewResultBase = { - parent_evidence_id: prefixedDigestSchema("ev"), - parent_operation: z.enum([ - "inspect_python_pyc", - "inspect_erlang_beam", - "inspect_devicetree", - "inspect_byte_entropy", - "inspect_native_exports", - "inspect_binary_layout", - "inspect_go_binary", - "gdb_console", - "frida_session_status", - "inspect_with_objdump", - "inspect_desktop_application", - "analyze_javascript_application", - "analyze_web_bundle", - "analyze_function", - "inspect_artifact", - "inventory_artifact", - "inspect_wasm_artifact", - "inspect_macho", - "decode_interface_builder", - "inspect_evm_interface", - "inspect_managed_artifact", - "inspect_managed_members", - "inspect_web_network_capture", - "inspect_android_package", - "inspect_android_class", - "inspect_android_method", - "inspect_android_jni_bindings", - "inspect_pcap_capture", - "inspect_dart_aot", - "inspect_il2cpp_metadata", - "inspect_model_artifact", - "inspect_gpu_code_objects", - ...NATIVE_INVENTORY_OPERATIONS, - ...NATIVE_OBSERVATION_OPERATIONS, - "match_native_functions", - ]), - parent_digest: digestSchema, - view_digest: digestSchema, - artifact: artifactSchema, - coverage: analysisViewCoverageSchema, - limitations: z.array(z.string()), - unknowns: z.array(z.string()), -} as const; - -const summaryViewResultBase = { - kind: z.literal("summary"), - view: summaryViewSchema, - ...viewResultBase, -} as const; - -const nativeObservationSummaryFor = < - Operation extends NativeObservationOperation, ->( - operation: Operation, -) => - z.strictObject({ - ...summaryViewResultBase, - ...nativeViewSourceContext, - artifact: artifactSchema.nullable(), - parent_operation: z.literal(operation), - source_context: nativeSourceContextReferenceSchema, - summary: z.strictObject({ observations: z.int().nonnegative() }), - items: nativeObservationItemsSchemas[operation], - }); -export const nativeObservationSummaryViewResultSchemas = { - procedure_address: nativeObservationSummaryFor("procedure_address"), - procedure_callees: nativeObservationSummaryFor("procedure_callees"), - procedure_callers: nativeObservationSummaryFor("procedure_callers"), - resolve_containing_procedure: nativeObservationSummaryFor( - "resolve_containing_procedure", - ), - get_call_graph: nativeObservationSummaryFor("get_call_graph"), -}; -const nativeObservationSummaryViewResultSchema = z.discriminatedUnion( - "parent_operation", - [ - nativeObservationSummaryViewResultSchemas.procedure_address, - nativeObservationSummaryViewResultSchemas.procedure_callees, - nativeObservationSummaryViewResultSchemas.procedure_callers, - nativeObservationSummaryViewResultSchemas.resolve_containing_procedure, - nativeObservationSummaryViewResultSchemas.get_call_graph, - ], -); -const nativeObservationPageFor = ( - operation: Operation, -) => - nativeObservationSummaryFor(operation) - .omit({ kind: true, view: true }) - .extend({ - kind: z.literal("native-observation"), - view: nativeObservationViewRequestSchema, - }); -const nativeObservationPageViewResultSchema = z.discriminatedUnion( - "parent_operation", - [ - nativeObservationPageFor("procedure_address"), - nativeObservationPageFor("procedure_callees"), - nativeObservationPageFor("procedure_callers"), - nativeObservationPageFor("resolve_containing_procedure"), - nativeObservationPageFor("get_call_graph"), - ], -); -const nativeContextFor = ( - facet: Facet, -) => - z.strictObject({ - ...viewResultBase, - ...nativeViewSourceContext, - kind: z.literal("native-context"), - artifact: artifactSchema.nullable(), - parent_operation: nativeObservationOperationSchema, - source_context: nativeSourceContextReferenceSchema, - facet: z.literal(facet), - view: nativeContextViewRequestSchema.extend({ facet: z.literal(facet) }), - items: nativeContextItemsSchemas[facet], - }); -const nativeContextViewResultSchema = z.discriminatedUnion("facet", [ - nativeContextFor("overview"), - nativeContextFor("analysis-profile"), - nativeContextFor("limitations"), - nativeContextFor("result-limitations"), -]); - -export const byteEntropySummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - summary: byteEntropySummarySchema, - parent_operation: z.literal("inspect_byte_entropy"), -}); - -export const nativeExportsSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_native_exports"), - summary: nativeExportsSummarySchema, -}); - -export const devicetreeSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_devicetree"), - summary: devicetreeSummarySchema, -}); -export const erlangBeamSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_erlang_beam"), - summary: erlangBeamSummarySchema, -}); -export const erlangBeamTableViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("beam"), - parent_operation: z.literal("inspect_erlang_beam"), - view: erlangBeamViewRequestSchema, - beam: erlangBeamSummarySchema, - page: erlangBeamViewPageSchema, -}); - -export const pythonPycSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_python_pyc"), - summary: pythonPycSummarySchema, -}); - -export const pythonPycCodeObjectsViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("python-pyc"), - parent_operation: z.literal("inspect_python_pyc"), - view: pythonPycViewRequestSchema, - pyc: pythonPycSummarySchema, - items: pythonPycViewItemsSchema, -}); - -/** Opt-in command delivery keeps output once and retains the complete parent. */ -export const gdbCommandSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...commandSummaryContext, - parent_operation: z.literal("gdb_console"), - artifact: artifactSchema.nullable(), - summary: gdbCommandSummarySchema, -}); - -export const objdumpSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...commandSummaryContext, - parent_operation: z.literal("inspect_with_objdump"), - artifact: artifactSchema.nullable(), - summary: commandObservationSchema, -}); - -export const fridaSessionStatusSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...fridaSessionStatusViewContext, - parent_operation: z.literal("frida_session_status"), - artifact: artifactSchema.nullable(), - summary: fridaSessionStatusSummarySchema, -}); - -/** Opt-in Go delivery retains original bytes and exposes build identity/counts. */ -export const goBinarySummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...goBinaryViewContextSchema.shape, - parent_operation: z.literal("inspect_go_binary"), - summary: goBinarySummarySchema, -}); - -/** Compact source identity and counts, retaining the complete embedded graph. */ -export const rustBinarySummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...rustBinaryViewContextSchema.shape, - parent_operation: z.literal("inspect_rust_binary"), - summary: rustBinarySummarySchema, -}); - -export const rustBinaryPageViewResultSchema = z.strictObject({ - ...viewResultBase, - ...rustBinaryViewContextSchema.shape, - kind: z.literal("rust"), - parent_operation: z.literal("inspect_rust_binary"), - view: rustBinaryViewRequestSchema, - rust: rustBinarySummarySchema, - page: rustBinaryViewPageSchema, -}); - -/** Summary `inspect_binary_layout` detail returns; no other view kind. */ -export const binaryLayoutSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - summary: layoutSummarySchema, - parent_operation: z.literal("inspect_binary_layout"), -}); - -/** Summary `analyze_javascript_application` detail returns; no other view kind. */ -export const javascriptApplicationSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - summary: javascriptSummarySchema, - parent_operation: z.literal("analyze_javascript_application"), -}); - -/** Typed reference page; full item observations remain available separately. */ -export const javascriptModuleReferencesViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("javascript"), - view: javascriptModuleReferencesRequestSchema, - parent_operation: z.literal("analyze_javascript_application"), - rows: z.array(javascriptModuleReferenceSchema), - source_coverage: javascriptApplicationSourceCoverageSchema, -}); - -/** Paged retained observations with exact selected properties and provenance. */ -const javascriptFactsViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("javascript-facts"), - view: javascriptFactsViewRequestSchema, - parent_operation: z.literal("analyze_javascript_application"), - rows: z.array(javascriptFactRowSchema), - source_coverage: javascriptApplicationSourceCoverageSchema, -}); - -/** Exact summary carrier for artifact inspection's optional delivery contract. */ -export const artifactInventorySummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.enum(["inspect_artifact", "inventory_artifact"]), - summary: artifactInventorySummarySchema, -}); - -export const desktopApplicationSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_desktop_application"), - summary: desktopSummarySchema, -}); - -/** Exact summary carrier for WASM inspection's optional delivery contract. */ -export const wasmArtifactSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_wasm_artifact"), - summary: wasmSummarySchema, -}); - -/** Exact slice identity and collection counts for Mach-O's selected delivery. */ -export const machoSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_macho"), - summary: machoSummarySchema, -}); - -/** Decoded documents and graph counts for Interface Builder's selected delivery. */ -export const interfaceBuilderSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("decode_interface_builder"), - resource_root: bundleResourceRootSchema.optional(), - summary: interfaceBuilderSummarySchema, -}); - -/** Exact inferred-interface summary for EVM's caller-selected delivery. */ -export const evmInterfaceSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_evm_interface"), - summary: evmSummarySchema, -}); - -/** Exact metadata overview for the managed artifact's selected delivery. */ -export const managedArtifactSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_managed_artifact"), - summary: managedSummarySchema, -}); - -/** Exact member selection, coverage and counts for the selected delivery. */ -export const managedMemberSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_managed_members"), - summary: managedMemberSummarySchema, -}); - -/** Exact historical capture summary, with no body or member-inventory payload. */ -export const webNetworkCaptureSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_web_network_capture"), - summary: captureSummarySchema, -}); - -/** Compact outcomes and the focus screen from a retained browser scenario. */ -export const browserScenarioSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - artifact: z.null(), - parent_operation: z.literal("capture_browser_scenario"), - summary: browserScenarioSummarySchema, -}); - -/** Exact package declarations with retained decoded manifest text. */ -export const androidPackageSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_android_package"), - summary: androidPackageSummarySchema, -}); -export const androidJniSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_android_jni_bindings"), - summary: androidJniSummarySchema, -}); -export const androidJniPageViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("android-jni"), - parent_operation: z.literal("inspect_android_jni_bindings"), - view: androidJniViewRequestSchema, - items: androidJniViewItemsSchema, - source: androidJniSummarySchema.pick({ - native_inventory: true, - library_inventory: true, - selection: true, - }), -}); - -/** Exact class facts with complete raw protocol Evidence retained separately. */ -export const androidClassSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_android_class"), - summary: androidClassSummarySchema, -}); - -/** Exact selected method body, source coverage and optional mapping facts. */ -export const androidMethodSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_android_method"), - summary: androidMethodSummarySchema, -}); - -/** Legacy manifest views keep their original shape; new facets are explicit. */ -export const androidManifestViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("android"), - facet: z.literal("manifest").optional(), - view: androidManifestViewRequestSchema, - item: androidManifestViewItemSchema, - parent_operation: z.literal("inspect_android_package"), -}); -export const androidComponentsViewResultSchema = z.strictObject({ - ...viewResultBase, - ...androidComponentViewContextSchema.shape, - kind: z.literal("android"), - facet: z.literal("components"), - view: androidComponentsViewRequestSchema, - items: z.array(androidComponentViewRowSchema), - byte_limited: z.boolean(), - parent_operation: z.literal("inspect_android_package"), -}); -export const androidComponentSummaryViewResultSchema = z.strictObject({ - ...viewResultBase, - ...androidComponentViewContextSchema.shape, - kind: z.literal("android"), - facet: z.literal("component-summary"), - view: androidComponentSummaryViewRequestSchema, - summary: androidComponentSummarySchema, - parent_operation: z.literal("inspect_android_package"), -}); -const androidPackageViewResultSchema = z.discriminatedUnion("facet", [ + nativeObservationSummaryViewResultSchemas, + byteEntropySummaryViewResultSchema, + nativeExportsSummaryViewResultSchema, + devicetreeSummaryViewResultSchema, + erlangBeamSummaryViewResultSchema, + erlangBeamTableViewResultSchema, + pythonPycSummaryViewResultSchema, + pythonPycCodeObjectsViewResultSchema, + gdbCommandSummaryViewResultSchema, + objdumpSummaryViewResultSchema, + fridaSessionStatusSummaryViewResultSchema, + goBinarySummaryViewResultSchema, + rustBinarySummaryViewResultSchema, + rustBinaryPageViewResultSchema, + binaryLayoutSummaryViewResultSchema, + javascriptApplicationSummaryViewResultSchema, + javascriptModuleReferencesViewResultSchema, + artifactInventorySummaryViewResultSchema, + desktopApplicationSummaryViewResultSchema, + wasmArtifactSummaryViewResultSchema, + machoSummaryViewResultSchema, + interfaceBuilderSummaryViewResultSchema, + evmInterfaceSummaryViewResultSchema, + managedArtifactSummaryViewResultSchema, + managedMemberSummaryViewResultSchema, + webNetworkCaptureSummaryViewResultSchema, + browserScenarioSummaryViewResultSchema, + androidPackageSummaryViewResultSchema, + androidJniSummaryViewResultSchema, + androidJniPageViewResultSchema, + androidClassSummaryViewResultSchema, + androidMethodSummaryViewResultSchema, androidManifestViewResultSchema, androidComponentsViewResultSchema, androidComponentSummaryViewResultSchema, -]); - -export const pcapCaptureSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_pcap_capture"), - summary: pcapSummarySchema, -}); - -/** Exact snapshot and pool-coverage carrier for selected AOT delivery. */ -export const dartAotSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_dart_aot"), - summary: dartAotSummarySchema, -}); - -export const javaScriptRoutesViewResultSchema = z.strictObject({ - ...viewResultBase, - artifact: artifactSchema.nullable(), - kind: z.literal("javascript-routes"), - parent_operation: z.enum([ - "analyze_javascript_application", - "analyze_web_bundle", - ]), - view: javaScriptRoutesViewRequestSchema, - inventory_id: javaScriptRouteInventorySchema.shape.inventory_id, - source_manifest_sha256: digestSchema, - source_coverage: javaScriptRouteInventorySchema.shape.coverage, - inventory_capacity: javaScriptRouteInventorySchema.shape.capacity, - capture_url: z.string().nullable(), - items: javaScriptRoutesViewItemsSchema, - sources: z.array(javaScriptRouteInventorySourceSchema), - summary: javaScriptRoutesViewSummarySchema.nullable(), - byte_limited: z.boolean(), -}); - -/** Compact web bundle findings retain endpoint observations and inference candidates. */ -export const webBundleSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - artifact: artifactSchema.nullable(), - parent_operation: z.literal("analyze_web_bundle"), - target_url: z.string(), - target_origin: recordedBrowserOriginSchema.nullable().optional(), - source_unknowns: webBundleAnalysisSchema.shape.unknowns, - summary: webBundleSummarySchema, -}); - -export const webBundlePageViewResultSchema = z.strictObject({ - ...viewResultBase, - artifact: artifactSchema.nullable(), - kind: z.literal("web-bundle"), - parent_operation: z.literal("analyze_web_bundle"), - target_url: z.string(), - target_origin: recordedBrowserOriginSchema.nullable().optional(), - source_unknowns: webBundleAnalysisSchema.shape.unknowns, - view: webBundleViewRequestSchema, - completeness: webBundleAnalysisSchema.shape.completeness, - items: webBundleViewItemsSchema, - summary: webBundleSummarySchema.nullable(), - byte_limited: z.boolean(), -}); - -export const gpuCodeObjectsSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_gpu_code_objects"), - summary: gpuCodeObjectsSummarySchema, -}); -export const gpuCodeObjectsPageViewResultSchema = z.strictObject({ - kind: z.literal("gpu-code-objects"), - view: gpuCodeObjectsViewRequestSchema, - items: gpuCodeObjectsItemsSchema, - ptx: gpuCodeObjectsPtxPageSchema.nullable(), - source_coverage: gpuCodeObjectsObjectSchema.shape.coverage, - ...viewResultBase, - parent_operation: z.literal("inspect_gpu_code_objects"), -}); - -export const apkSignatureSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_apk_signature"), - summary: apkSignatureSummarySchema, -}); -export const apkSignaturePageViewResultSchema = z.strictObject({ - ...viewResultBase, - kind: z.literal("apk-signature"), - parent_operation: z.literal("inspect_apk_signature"), - view: apkSignatureViewRequestSchema, - items: apkSignatureViewItemsSchema, - source_coverage: apkSignatureSourceCoverageSchema, -}); - -export const modelArtifactSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_model_artifact"), - summary: modelArtifactSummarySchema, -}); - -export const modelArtifactPageViewResultSchema = z.strictObject({ - kind: z.literal("model-artifact"), - view: modelArtifactViewRequestSchema, - items: modelArtifactViewItemsSchema, - ...viewResultBase, - ...modelArtifactViewContextSchema.shape, - parent_operation: z.literal("inspect_model_artifact"), -}); - -/** Metadata identity and row counts for selected IL2CPP delivery. */ -export const il2cppMetadataSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("inspect_il2cpp_metadata"), - summary: il2cppMetadataSummarySchema, -}); - -/** Exact inventory summary with the original observation's provider and query. */ -export const nativeInventorySummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...nativeViewSourceContext, - parent_operation: nativeInventoryOperationSchema, - artifact: artifactSchema.nullable(), - summary: nativeInventorySummarySchema, -}); - -/** Compact provider load observations retain the independent verification state. */ -export const nativeLoadImageSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - ...nativeViewSourceContext, - artifact: artifactSchema.nullable(), - parent_operation: z.literal("inspect_native_load_image"), - summary: nativeLoadImageSummarySchema, -}); - -/** Compact native matching discovery retains the complete matching report. */ -export const nativeFunctionMatchingSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - artifact: z.null(), - parent_operation: z.literal("match_native_functions"), - summary: nativeFunctionMatchingContextSchema, -}); - -/** Rows observed for one facet, or null when the provider declared that facet unavailable. */ -const declaredFacetCountSchema = z - .number() - .int() - .nonnegative() - .nullable() - .describe( - "Observed rows; null when facet_availability declares the facet unavailable, so no rows is not evidence of none.", - ); - -/** Rows of an optional dossier record, or null when the dossier omitted it. */ -const recordedFacetCountSchema = z - .number() - .int() - .nonnegative() - .nullable() - .describe( - "Observed rows; null when the dossier did not record the facet (the native facet view reports it not recorded), so no rows is not evidence of none.", - ); - -/** Rows of one value-flow facet, or null when value flow is unavailable. */ -const valueFlowFacetCountSchema = z - .number() - .int() - .nonnegative() - .nullable() - .describe( - "Observed rows; null when value_flow.available is false because native_value_flow was not recorded or the provider declared it unavailable (unknowns names which), so no rows is not evidence of none.", - ); - -/** Compact analyze_function dossier; the complete dossier stays retained for facet paging. */ -export const nativeFunctionSummarySchema = z.strictObject({ - procedure: z.strictObject({ - name: z.string(), - address: z.string(), - }), - pseudocode: z.strictObject({ - available: z - .boolean() - .describe( - "Provider facet_availability for pseudocode when declared; otherwise whether decompiled text is present. The flag is authoritative over raw length.", - ), - code_units: z - .number() - .int() - .nonnegative() - .describe( - "Pseudocode length in UTF-16 code units, the unit inspect_analysis_view pages pseudocode by.", - ), - }), - value_flow: z.strictObject({ - available: z.boolean(), - truncated: z - .boolean() - .describe( - "True only when value-flow is available and the provider truncated it; false when value-flow is unavailable (see available).", - ), - }), - facet_availability: functionFacetAvailabilitySchema - .nullable() - .describe( - "The provider's declared availability per facet, or null when it declared none. Unavailable facets name their reason here and in unknowns.", - ), - counts: z.strictObject({ - assembly: declaredFacetCountSchema, - basic_blocks: declaredFacetCountSchema, - comments: declaredFacetCountSchema, - callers: declaredFacetCountSchema, - callees: declaredFacetCountSchema, - incoming_references: declaredFacetCountSchema, - outgoing_references: declaredFacetCountSchema, - unresolved_calls: recordedFacetCountSchema, - referenced_strings: declaredFacetCountSchema, - referenced_names: declaredFacetCountSchema, - swift_string_literals: recordedFacetCountSchema, - swift_string_literal_omissions: recordedFacetCountSchema, - value_flow_operations: valueFlowFacetCountSchema, - value_flow_def_use: valueFlowFacetCountSchema, - value_flow_effects: valueFlowFacetCountSchema, - value_flow_parameters: valueFlowFacetCountSchema, - value_flow_parameter_uses: valueFlowFacetCountSchema, - }), - limitation_count: z.number().int().nonnegative(), -}); - -/** Compact analyze_function summary that retains the complete native dossier Evidence. */ -export const nativeFunctionSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - parent_operation: z.literal("analyze_function"), - procedure_address: z.string().nullable(), - summary: nativeFunctionSummarySchema, -}); - -export const sourceToBundleSummaryViewResultSchema = z.strictObject({ - ...summaryViewResultBase, - artifact: z.null(), - parent_operation: z.literal("compare_source_to_bundle"), - summary: sourceToBundleViewContextSchema, -}); -export const sourceToBundlePageViewResultSchema = z.strictObject({ - ...viewResultBase, - ...sourceToBundleViewContextSchema.shape, - kind: z.literal("source-to-bundle"), - artifact: z.null(), - parent_operation: z.literal("compare_source_to_bundle"), - view: sourceToBundleViewRequestSchema, - items: sourceToBundleViewItemsSchema, -}); - -/** Bind the existing nested facet selection to its producer-owned rows. */ -const machoPage = (facet: Facet) => - z.strictObject({ - ...viewResultBase, - ...machoViewContextSchema.shape, - kind: z.literal("macho"), - parent_operation: z.literal("inspect_macho"), - view: machoViewRequestSchema.extend({ facet: z.literal(facet) }), - item: machoViewRows[facet], - }); - -// The input tag preserves kind dispatch; the output projection advertises the -// correlated pages without adding a discriminator to their public wire shape. -const machoPageViewResultSchema = z - .object({ kind: z.literal("macho") }) - .passthrough() - .pipe( - z.union([ - machoPage("entrypoints"), - machoPage("architectures"), - machoPage("build_metadata"), - machoPage("load_commands"), - machoPage("dependencies"), - machoPage("imports"), - machoPage("exports"), - machoPage("segments"), - machoPage("encryption"), - machoPage("provenance"), - ]), - ); - -/** Projected facts for one selected view of retained analysis Evidence. */ -export const analysisViewResultSchema = z.discriminatedUnion("kind", [ - nativeObservationPageViewResultSchema, - nativeContextViewResultSchema, + pcapCaptureSummaryViewResultSchema, + dartAotSummaryViewResultSchema, javaScriptRoutesViewResultSchema, + webBundleSummaryViewResultSchema, webBundlePageViewResultSchema, - sourceToBundlePageViewResultSchema, - z.strictObject({ - ...viewResultBase, - ...nativeFunctionMatchingContextSchema.shape, - kind: z.literal("function-matches"), - artifact: z.null(), - view: nativeFunctionMatchingViewRequestSchema, - items: nativeFunctionMatchingViewItemsSchema, - parent_operation: z.literal("match_native_functions"), - }), - 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({ - ...viewResultBase, - ...environmentManifestFields, - kind: z.literal("environment-manifest"), - parent_operation: z.enum([ - "inspect_web_network_capture", - "capture_browser_scenario", - ]), - view: environmentManifestViewRequestSchema, - }), - z.strictObject({ - ...viewResultBase, - ...environmentStateFields, - kind: z.literal("environment-state"), - parent_operation: z.enum([ - "inspect_web_network_capture", - "capture_browser_scenario", - ]), - view: environmentStateViewRequestSchema, - }), - z.strictObject({ - ...viewResultBase, - ...environmentCoverageFields, - kind: z.literal("environment-coverage"), - parent_operation: z.enum([ - "inspect_web_network_capture", - "capture_browser_scenario", - ]), - view: environmentCoverageViewRequestSchema, - }), - z.discriminatedUnion("parent_operation", [ - nativeObservationSummaryViewResultSchema, - erlangBeamSummaryViewResultSchema, - devicetreeSummaryViewResultSchema, - pythonPycSummaryViewResultSchema, - nativeExportsSummaryViewResultSchema, - byteEntropySummaryViewResultSchema, - gdbCommandSummaryViewResultSchema, - objdumpSummaryViewResultSchema, - fridaSessionStatusSummaryViewResultSchema, - goBinarySummaryViewResultSchema, - rustBinarySummaryViewResultSchema, - binaryLayoutSummaryViewResultSchema, - desktopApplicationSummaryViewResultSchema, - javascriptApplicationSummaryViewResultSchema, - artifactInventorySummaryViewResultSchema, - wasmArtifactSummaryViewResultSchema, - machoSummaryViewResultSchema, - interfaceBuilderSummaryViewResultSchema, - evmInterfaceSummaryViewResultSchema, - managedArtifactSummaryViewResultSchema, - managedMemberSummaryViewResultSchema, - webNetworkCaptureSummaryViewResultSchema, - browserScenarioSummaryViewResultSchema, - androidPackageSummaryViewResultSchema, - androidJniSummaryViewResultSchema, - androidClassSummaryViewResultSchema, - androidMethodSummaryViewResultSchema, - pcapCaptureSummaryViewResultSchema, - dartAotSummaryViewResultSchema, - il2cppMetadataSummaryViewResultSchema, - apkSignatureSummaryViewResultSchema, - modelArtifactSummaryViewResultSchema, - gpuCodeObjectsSummaryViewResultSchema, - nativeInventorySummaryViewResultSchema, - nativeLoadImageSummaryViewResultSchema, - nativeFunctionMatchingSummaryViewResultSchema, - nativeFunctionSummaryViewResultSchema, - sourceToBundleSummaryViewResultSchema, - webBundleSummaryViewResultSchema, - ]), - z.strictObject({ - ...viewResultBase, - kind: z.literal("devicetree"), - parent_operation: z.literal("inspect_devicetree"), - view: devicetreeViewRequestSchema, - devicetree: devicetreePageContextSchema, - items: devicetreeViewItemsSchema, - }), - erlangBeamTableViewResultSchema, - pythonPycCodeObjectsViewResultSchema, - z.strictObject({ - ...viewResultBase, - kind: z.literal("native-exports"), - parent_operation: z.literal("inspect_native_exports"), - view: nativeExportsViewRequestSchema, - exports: nativeExportsSummarySchema, - items: nativeExportsViewItemsSchema, - }), - z.strictObject({ - ...viewResultBase, - ...nativeViewSourceContext, - kind: z.literal("native-inventory"), - parent_operation: nativeInventoryOperationSchema, - artifact: artifactSchema.nullable(), - view: nativeInventoryViewRequestSchema, - rows: z.array(nativeInventoryViewRowSchema), - }), - z.strictObject({ - ...viewResultBase, - kind: z.literal("native-load-image"), - ...nativeViewSourceContext, - verification_status: z.enum(["unsupported", "verified", "mismatch"]), - parent_operation: z.literal("inspect_native_load_image"), - artifact: artifactSchema.nullable(), - view: nativeLoadImageViewRequestSchema, - items: nativeLoadImageViewItemsSchema, - }), - z.strictObject({ - kind: z.literal("protobuf"), - view: protobufViewRequestSchema, - items: protobufViewItemsSchema, - ...viewResultBase, - ...protobufViewContextSchema.shape, - parent_operation: z.literal("inspect_web_network_capture"), - }), - z.strictObject({ - kind: z.literal("capture"), - view: captureViewRequestSchema, - items: captureViewItemsSchema, - ...viewResultBase, - parent_operation: z.literal("inspect_web_network_capture"), - }), - z.strictObject({ - kind: z.literal("browser-scenario"), - view: browserScenarioViewRequestSchema, - items: browserScenarioViewItemsSchema, - ...viewResultBase, - ...browserScenarioViewContextSchema.shape, - artifact: z.null(), - parent_operation: z.literal("capture_browser_scenario"), - }), - z.strictObject({ - kind: z.literal("qlog"), - view: qlogViewRequestSchema, - page: qlogViewPageSchema, - context: qlogViewContextSchema, - ...viewResultBase, - parent_operation: z.literal("inspect_web_network_capture"), - }), - z.strictObject({ - kind: z.literal("pcap"), - view: pcapViewRequestSchema, - page: pcapViewPageSchema, - source_coverage: z.enum(["complete", "partial"]), - ...viewResultBase, - parent_operation: z.literal("inspect_pcap_capture"), - }), - z.strictObject({ - kind: z.literal("facet"), - view: facetViewSchema, - facet: jsonValueSchema, - ...viewResultBase, - }), - z.strictObject({ - ...viewResultBase, - ...goBinaryViewContextSchema.shape, - kind: z.literal("go"), - parent_operation: z.literal("inspect_go_binary"), - view: goBinaryViewRequestSchema, - page: goBinaryViewPageSchema, - }), - rustBinaryPageViewResultSchema, - z.strictObject({ - kind: z.literal("item"), - view: itemViewSchema, - item: jsonValueSchema, - ...viewResultBase, - }), - z.strictObject({ - kind: z.literal("page"), - view: pageViewSchema, - items: z.array(jsonValueSchema), - ...viewResultBase, - }), - javascriptModuleReferencesViewResultSchema, - javascriptFactsViewResultSchema, - z.strictObject({ - kind: z.literal("native"), - view: nativeViewSchema, - procedure_address: z.string().nullable(), - item: jsonValueSchema, - ...viewResultBase, - }), - z.strictObject({ - kind: z.literal("wasm"), - view: wasmViewRequestSchema, - item: wasmViewItemSchema, - ...viewResultBase, - }), - z.strictObject({ - kind: z.literal("desktop-application"), - view: desktopViewRequestSchema, - items: desktopViewItemsSchema, - ...viewResultBase, - source_coverage: desktopCoverageSchema, - parent_operation: z.literal("inspect_desktop_application"), - }), - machoPageViewResultSchema, - z.strictObject({ - kind: z.literal("interface-builder"), - view: interfaceBuilderViewRequestSchema, - items: interfaceBuilderViewItemsSchema, - ...viewResultBase, - resource_root: bundleResourceRootSchema.optional(), - ...interfaceBuilderViewContextSchema.shape, - parent_operation: z.literal("decode_interface_builder"), - }), - z.strictObject({ - kind: z.literal("evm"), - view: evmViewRequestSchema, - item: evmViewItemSchema, - ...viewResultBase, - parent_operation: z.literal("inspect_evm_interface"), - }), - z.strictObject({ - kind: z.literal("managed"), - view: managedViewRequestSchema, - item: managedViewItemSchema, - ...viewResultBase, - ...managedViewContextSchema.shape, - parent_operation: z.literal("inspect_managed_artifact"), - }), - z.strictObject({ - kind: z.literal("managed-members"), - view: managedMembersViewRequestSchema, - page: managedMembersViewPageSchema, - ...viewResultBase, - ...managedMembersViewContextSchema.shape, - parent_operation: z.literal("inspect_managed_members"), - }), - androidPackageViewResultSchema, - androidJniPageViewResultSchema, - z.strictObject({ - kind: z.literal("dart-aot"), - view: dartAotViewRequestSchema, - items: z.array(z.string()), - ...viewResultBase, - ...dartAotViewContextSchema.shape, - parent_operation: z.literal("inspect_dart_aot"), - }), - apkSignaturePageViewResultSchema, - modelArtifactPageViewResultSchema, + gpuCodeObjectsSummaryViewResultSchema, gpuCodeObjectsPageViewResultSchema, - z.strictObject({ - kind: z.literal("il2cpp-metadata"), - view: il2cppMetadataViewRequestSchema, - items: il2cppMetadataViewItemsSchema, - ...viewResultBase, - ...il2cppMetadataViewContextSchema.shape, - parent_operation: z.literal("inspect_il2cpp_metadata"), - }), - z.strictObject({ - kind: z.literal("inventory"), - view: artifactInventoryViewRequestSchema, - source_coverage: artifactInventoryCoverageSchema.exactOptional(), - manifest: artifactGraphManifestSchema, - inventory_evidence_ids: z.array(prefixedDigestSchema("ev")).min(1), - source_complete: z.boolean(), - items: artifactInventoryItemsSchema, - ...viewResultBase, - }), -]); - -export type AnalysisViewRequest = z.output; -export type InspectAnalysisViewInput = z.output< - typeof inspectAnalysisViewInputSchema ->; -export type AnalysisViewResult = z.output; - -/** Parent record already resolved from inline Evidence or a session reference. */ -export interface AnalysisViewParent { - readonly evidenceId: string; - readonly operation: string; - readonly normalizedResult: unknown; - readonly provider?: Evidence["provider"]; - readonly analysisProfile?: Evidence["analysis_profile"]; - readonly authority?: Evidence["authority"]; - readonly environment?: Evidence["environment"]; - /** The owner proved normalizedResult belongs to a sealed, deep-frozen Evidence snapshot. */ - readonly sealedResult?: boolean; - /** Subject presentation for this delivery, including explicit absence. */ - readonly subject?: Evidence["subject"]; - readonly limitations: readonly string[]; - readonly artifact?: { readonly path: string; readonly sha256: string } | null; - /** Parent Evidence parameters, when the parent operation records them. */ - readonly parameters?: unknown; -} - -/** View payload before the content digest is attached. */ -type WithoutViewDigest = T extends { readonly view_digest: string } - ? Omit - : never; -export type UnsignedAnalysisView = WithoutViewDigest; + apkSignatureSummaryViewResultSchema, + apkSignaturePageViewResultSchema, + modelArtifactSummaryViewResultSchema, + modelArtifactPageViewResultSchema, + il2cppMetadataSummaryViewResultSchema, + nativeInventorySummaryViewResultSchema, + nativeLoadImageSummaryViewResultSchema, + nativeFunctionMatchingSummaryViewResultSchema, + nativeFunctionSummarySchema, + nativeFunctionSummaryViewResultSchema, + sourceToBundleSummaryViewResultSchema, + sourceToBundlePageViewResultSchema, + analysisViewResultSchema, + type AnalysisViewResult, + type UnsignedAnalysisView, +} from "./analysisViewResult.js"; +export { + analysisViewRequestSchema, + analysisViewSourceSchema, + inspectAnalysisViewInputSchema, + type AnalysisViewRequest, + type InspectAnalysisViewInput, + type AnalysisViewParent, +}; +export { type GroupingViewKind }; +export { + nativeObservationSummaryViewResultSchemas, + byteEntropySummaryViewResultSchema, + nativeExportsSummaryViewResultSchema, + devicetreeSummaryViewResultSchema, + erlangBeamSummaryViewResultSchema, + erlangBeamTableViewResultSchema, + pythonPycSummaryViewResultSchema, + pythonPycCodeObjectsViewResultSchema, + gdbCommandSummaryViewResultSchema, + objdumpSummaryViewResultSchema, + fridaSessionStatusSummaryViewResultSchema, + goBinarySummaryViewResultSchema, + rustBinarySummaryViewResultSchema, + rustBinaryPageViewResultSchema, + binaryLayoutSummaryViewResultSchema, + javascriptApplicationSummaryViewResultSchema, + javascriptModuleReferencesViewResultSchema, + artifactInventorySummaryViewResultSchema, + desktopApplicationSummaryViewResultSchema, + wasmArtifactSummaryViewResultSchema, + machoSummaryViewResultSchema, + interfaceBuilderSummaryViewResultSchema, + evmInterfaceSummaryViewResultSchema, + managedArtifactSummaryViewResultSchema, + managedMemberSummaryViewResultSchema, + webNetworkCaptureSummaryViewResultSchema, + browserScenarioSummaryViewResultSchema, + androidPackageSummaryViewResultSchema, + androidJniSummaryViewResultSchema, + androidJniPageViewResultSchema, + androidClassSummaryViewResultSchema, + androidMethodSummaryViewResultSchema, + androidManifestViewResultSchema, + androidComponentsViewResultSchema, + androidComponentSummaryViewResultSchema, + pcapCaptureSummaryViewResultSchema, + dartAotSummaryViewResultSchema, + javaScriptRoutesViewResultSchema, + webBundleSummaryViewResultSchema, + webBundlePageViewResultSchema, + gpuCodeObjectsSummaryViewResultSchema, + gpuCodeObjectsPageViewResultSchema, + apkSignatureSummaryViewResultSchema, + apkSignaturePageViewResultSchema, + modelArtifactSummaryViewResultSchema, + modelArtifactPageViewResultSchema, + il2cppMetadataSummaryViewResultSchema, + nativeInventorySummaryViewResultSchema, + nativeLoadImageSummaryViewResultSchema, + nativeFunctionMatchingSummaryViewResultSchema, + nativeFunctionSummarySchema, + nativeFunctionSummaryViewResultSchema, + sourceToBundleSummaryViewResultSchema, + sourceToBundlePageViewResultSchema, + analysisViewResultSchema, + type AnalysisViewResult, + type UnsignedAnalysisView, +}; /** Attach the content digest that must change when projected bytes change. */ export const sealAnalysisView = ( @@ -1591,46 +272,63 @@ const parentArtifactPath = (parent: AnalysisViewParent): string => { return parent.evidenceId; }; +/** Check a projector result against the result union before sealing it. */ +const sealProjected = ( + projected: Result, +): Result => + projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + /** Named source owners for views that need no extra decoder or accumulator. */ -const retainedViewProjectors = new Map([ - ...NATIVE_OBSERVATION_OPERATIONS.map( - (operation) => [operation, projectNativeObservationView] as const, +type RetainedViewProjector = ( + parent: AnalysisViewParent, + view: AnalysisViewRequest, +) => Result; + +/** Register a projector whose inferred result must be in the result union. */ +const retain = ( + operation: string, + project: RetainedViewProjector, +): readonly [string, RetainedViewProjector] => [operation, project]; + +const retainedViewProjectors = new Map([ + ...NATIVE_OBSERVATION_OPERATIONS.map((operation) => + retain(operation, projectNativeObservationView), ), - ["inspect_erlang_beam", projectErlangBeamView], - ["inspect_devicetree", projectDevicetreeView], - ["inspect_native_exports", projectNativeExportsView], - ["inspect_native_load_image", projectNativeLoadImageView], - ["inspect_python_pyc", projectPythonPycView], - ["frida_session_status", projectFridaSessionStatusView], - ["gdb_console", projectCommandObservationView], - ["inspect_with_objdump", projectCommandObservationView], - ["inspect_go_binary", projectGoBinaryView], - ["inspect_rust_binary", projectRustBinaryView], - ...NATIVE_INVENTORY_OPERATIONS.map( - (operation) => [operation, projectNativeInventoryView] as const, + retain("inspect_erlang_beam", projectErlangBeamView), + retain("inspect_devicetree", projectDevicetreeView), + retain("inspect_native_exports", projectNativeExportsView), + retain("inspect_native_load_image", projectNativeLoadImageView), + retain("inspect_python_pyc", projectPythonPycView), + retain("frida_session_status", projectFridaSessionStatusView), + retain("gdb_console", projectCommandObservationView), + retain("inspect_with_objdump", projectCommandObservationView), + retain("inspect_go_binary", projectGoBinaryView), + retain("inspect_rust_binary", projectRustBinaryView), + ...NATIVE_INVENTORY_OPERATIONS.map((operation) => + retain(operation, projectNativeInventoryView), ), - ["inspect_desktop_application", projectDesktopApplicationView], - ["inspect_wasm_artifact", projectWasmArtifactView], - ["inspect_macho", projectMachoView], - ["decode_interface_builder", projectInterfaceBuilderView], - ["inspect_evm_interface", projectEvmInterfaceView], - ["inspect_managed_artifact", projectManagedArtifactView], - ["inspect_managed_members", projectManagedMemberView], - ["inspect_android_package", projectAndroidPackageView], - ["inspect_android_class", projectAndroidSymbolSummary], - ["inspect_android_method", projectAndroidSymbolSummary], - ["inspect_android_jni_bindings", projectAndroidJniView], - ["capture_browser_scenario", projectBrowserScenarioView], - ["inspect_dart_aot", projectDartAotView], - ["inspect_il2cpp_metadata", projectIl2cppMetadataView], - ["inspect_apk_signature", projectApkSignatureView], - ["inspect_model_artifact", projectModelArtifactView], - ["inspect_gpu_code_objects", projectGpuCodeObjectsView], - ["match_native_functions", projectNativeFunctionMatchingView], - ["compare_source_to_bundle", projectSourceToBundleView], - ["inspect_artifact", projectArtifactInventoryView], - ["inventory_artifact", projectArtifactInventoryView], - ["analyze_web_bundle", projectWebBundleView], + retain("inspect_desktop_application", projectDesktopApplicationView), + retain("inspect_wasm_artifact", projectWasmArtifactView), + retain("inspect_macho", projectMachoView), + retain("decode_interface_builder", projectInterfaceBuilderView), + retain("inspect_evm_interface", projectEvmInterfaceView), + retain("inspect_managed_artifact", projectManagedArtifactView), + retain("inspect_managed_members", projectManagedMemberView), + retain("inspect_android_package", projectAndroidPackageView), + retain("inspect_android_class", projectAndroidSymbolSummary), + retain("inspect_android_method", projectAndroidSymbolSummary), + retain("inspect_android_jni_bindings", projectAndroidJniView), + retain("capture_browser_scenario", projectBrowserScenarioView), + retain("inspect_dart_aot", projectDartAotView), + retain("inspect_il2cpp_metadata", projectIl2cppMetadataView), + retain("inspect_apk_signature", projectApkSignatureView), + retain("inspect_model_artifact", projectModelArtifactView), + retain("inspect_gpu_code_objects", projectGpuCodeObjectsView), + retain("match_native_functions", projectNativeFunctionMatchingView), + retain("compare_source_to_bundle", projectSourceToBundleView), + retain("inspect_artifact", projectArtifactInventoryView), + retain("inventory_artifact", projectArtifactInventoryView), + retain("analyze_web_bundle", projectWebBundleView), ]); /** Budgets retained across source admission and the selected grouping projection. */ @@ -1674,13 +372,6 @@ export const prepareAnalysisViewProjection = ( }; }; -/** Views that group a capture's records into tools. */ -export type GroupingViewKind = - | "api-surface" - | "environment-manifest" - | "environment-state" - | "environment-coverage"; - type GroupingViewRequest = Extract< AnalysisViewRequest, { kind: GroupingViewKind } @@ -1699,7 +390,7 @@ const projectGroupingView = ( parent: AnalysisViewParent, view: GroupingViewRequest, accumulators: AnalysisViewAccumulators, -): Result => { +) => { if (view.kind === "api-surface") return projectWebNetworkApiSurfaceView( parent, @@ -1732,29 +423,29 @@ export const projectAnalysisView = ( ); if (view.kind === "javascript-routes") { const projected = projectJavaScriptRoutesView(parent, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (view.kind === "web-bundle") { const projected = projectWebBundleView(parent, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (isGroupingView(view)) { const grouped = projectGroupingView(parent, view, accumulators); - return grouped.ok ? ok(sealAnalysisView(grouped.value)) : grouped; + return sealProjected(grouped); } if (parent.operation === "inspect_web_network_capture") { const projected = projectWebNetworkCaptureView(parent, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (parent.operation === "inspect_pcap_capture") { const projected = projectPcapCaptureView(parent, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (parent.operation === "inspect_byte_entropy") { const report = parseAnalysisViewResult(byteEntropySchema, parent); if (!report.ok) return report; const projected = projectByteEntropyView(parent, report.value, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (parent.operation === "inspect_binary_layout") { const layout = parseAnalysisViewResult( @@ -1763,7 +454,7 @@ export const projectAnalysisView = ( ); if (!layout.ok) return layout; const projected = projectBinaryLayoutView(parent, layout.value, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (parent.operation === "analyze_javascript_application") { const analysis = parseJavaScriptParent(parent.normalizedResult); @@ -1773,18 +464,18 @@ export const projectAnalysisView = ( analysis.value, view, ); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } if (parent.operation === "analyze_function") { const native = parseAnalysisViewResult(functionDossierSchema, parent); if (!native.ok) return native; const projected = projectNativeFunctionView(parent, native.value, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } const project = retainedViewProjectors.get(parent.operation); if (project !== undefined) { const projected = project(parent, view); - return projected.ok ? ok(sealAnalysisView(projected.value)) : projected; + return sealProjected(projected); } return err(unsupportedParent(parent)); }; diff --git a/src/domain/analysisView/analysisViewCycles.test.ts b/src/domain/analysisView/analysisViewCycles.test.ts new file mode 100644 index 0000000000..d4441ac681 --- /dev/null +++ b/src/domain/analysisView/analysisViewCycles.test.ts @@ -0,0 +1,167 @@ +import { parse } from "@babel/parser"; +import { traverseFast, type Node } from "@babel/types"; +import { readdirSync, readFileSync, statSync } from "node:fs"; +import { dirname, join, relative, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { describe, expect, it } from "vitest"; + +const root = dirname(fileURLToPath(import.meta.url)); + +/** String specifiers only, matching scripts/lib/module-boundaries.mjs. */ +const literalValue = (node: Node | null | undefined): string | undefined => { + if (node?.type === "StringLiteral") return node.value; + if (node?.type === "TemplateLiteral" && node.expressions.length === 0) + return node.quasis[0]?.value.cooked ?? undefined; + return undefined; +}; + +const importSpecifier = (node: Node): string | undefined => { + switch (node.type) { + case "ImportDeclaration": + case "ExportAllDeclaration": + case "TSImportType": + return literalValue(node.source); + case "ExportNamedDeclaration": + case "ImportExpression": + return literalValue(node.source); + case "TSImportEqualsDeclaration": + return node.moduleReference.type === "TSExternalModuleReference" + ? literalValue(node.moduleReference.expression) + : undefined; + default: + return undefined; + } +}; + +/** Import and re-export specifiers, using the same Babel nodes as the module-boundary guard. */ +export const relativeSpecifiers = (source: string): readonly string[] => { + const specifiers: string[] = []; + const tree = parse(source, { sourceType: "module", plugins: ["typescript"] }); + traverseFast(tree, (node) => { + const specifier = importSpecifier(node); + if (specifier?.startsWith(".") === true) specifiers.push(specifier); + }); + return specifiers; +}; + +/** + * Cycles that already existed outside the analysis-view hub. Membership is + * exact so a new edge cannot hide inside the allow-list. + */ +const allowedCycles = [ + [ + "StateRecordChronology.ts", + "environmentStateListQuery.ts", + "environmentStateRules.ts", + "environmentStateWriteRules.ts", + ], + ["environmentStateGate.ts", "environmentStateListFacts.ts"], + ["environmentStateWriteAddress.ts", "environmentStateWriteEffects.ts"], +]; + +const productionFiles = (directory: string): string[] => { + const files: string[] = []; + for (const name of readdirSync(directory)) { + const path = join(directory, name); + if (statSync(path).isDirectory()) files.push(...productionFiles(path)); + else if (name.endsWith(".ts") && !name.includes(".test.")) files.push(path); + } + return files; +}; + +const importGraph = (): Map> => { + const files = new Set( + productionFiles(root).map((path) => relative(root, path)), + ); + const graph = new Map>(); + for (const file of files) { + const source = readFileSync(join(root, file), "utf8"); + const edges = new Set(); + for (const spec of relativeSpecifiers(source)) { + const resolved = resolve(dirname(join(root, file)), spec).replace( + /\.js$/, + ".ts", + ); + const target = relative(root, resolved); + if (files.has(target)) edges.add(target); + } + graph.set(file, edges); + } + return graph; +}; + +const stronglyConnected = ( + graph: Map>, +): readonly (readonly string[])[] => { + let index = 0; + const stack: string[] = []; + const onStack = new Set(); + const indices = new Map(); + const low = new Map(); + const components: string[][] = []; + const visit = (node: string): void => { + indices.set(node, index); + low.set(node, index); + index += 1; + stack.push(node); + onStack.add(node); + for (const next of graph.get(node) ?? []) { + if (!indices.has(next)) { + visit(next); + low.set(node, Math.min(low.get(node) ?? index, low.get(next) ?? index)); + } else if (onStack.has(next)) { + low.set( + node, + Math.min(low.get(node) ?? index, indices.get(next) ?? index), + ); + } + } + if (low.get(node) === indices.get(node)) { + const component: string[] = []; + let member = ""; + while (member !== node) { + member = stack.pop() ?? node; + onStack.delete(member); + component.push(member); + } + if (component.length > 1) components.push(component.sort()); + } + }; + for (const node of [...graph.keys()].sort()) { + if (!indices.has(node)) visit(node); + } + return components.sort( + (left, right) => + right.length - left.length || left.join().localeCompare(right.join()), + ); +}; + +describe("analysis view import cycles", () => { + it("reads side-effect imports and ignores import-like text", () => { + expect( + relativeSpecifiers(` + // from "./commented.js" + /* import "./block-comment.js"; */ + const text = "from './string.js'"; + import "./side-effect.js"; + import { value } from "./named.js"; + export { value as again } from "./reexported.js"; + const loaded = import("./dynamic.js"); + `), + ).toEqual([ + "./side-effect.js", + "./named.js", + "./reexported.js", + "./dynamic.js", + ]); + }); + + it("keeps projectors from importing the request and result hub", () => { + const cycles = stronglyConnected(importGraph()).map((cycle) => + cycle.join("\n"), + ); + expect(cycles).toEqual( + allowedCycles.map((cycle) => [...cycle].sort().join("\n")), + ); + }); +}); diff --git a/src/domain/analysisView/analysisViewParent.ts b/src/domain/analysisView/analysisViewParent.ts index 9e2d9e2311..4f1698ccd1 100644 --- a/src/domain/analysisView/analysisViewParent.ts +++ b/src/domain/analysisView/analysisViewParent.ts @@ -1,10 +1,29 @@ import type { z } from "zod"; import type { AnalysisInputError } from "../analysisErrorCore.js"; import type { AnalysisError } from "../analysisErrorBase.js"; +import type { Evidence } from "../evidence.js"; import { analysisInputErrorFromIssues } from "../inputIssueProjection.js"; import { err, ok, type Result } from "../result.js"; -import type { AnalysisViewParent } from "./analysisView.js"; import { ownedJsonValueSchema } from "../jsonValue.js"; + +/** Parent record already resolved from inline Evidence or a session reference. */ +export interface AnalysisViewParent { + readonly evidenceId: string; + readonly operation: string; + readonly normalizedResult: unknown; + readonly provider?: Evidence["provider"]; + readonly analysisProfile?: Evidence["analysis_profile"]; + readonly authority?: Evidence["authority"]; + readonly environment?: Evidence["environment"]; + /** The owner proved normalizedResult belongs to a sealed, deep-frozen Evidence snapshot. */ + readonly sealedResult?: boolean; + /** Subject presentation for this delivery, including explicit absence. */ + readonly subject?: Evidence["subject"]; + readonly limitations: readonly string[]; + readonly artifact?: { readonly path: string; readonly sha256: string } | null; + /** Parent Evidence parameters, when the parent operation records them. */ + readonly parameters?: unknown; +} import { canBorrowParsedJsonSnapshot, freezeOwnedJsonTreeSnapshot, diff --git a/src/domain/analysisView/analysisViewRequest.ts b/src/domain/analysisView/analysisViewRequest.ts new file mode 100644 index 0000000000..697b0ac9c8 --- /dev/null +++ b/src/domain/analysisView/analysisViewRequest.ts @@ -0,0 +1,132 @@ +import { + nativeObservationViewRequestSchema, + nativeContextViewRequestSchema, +} from "./nativeObservationSchemas.js"; +import { devicetreeViewRequestSchema } from "./devicetreeView.js"; +import { apkSignatureViewRequestSchema } from "../apkSignature/apkSignatureQuery.js"; +import { erlangBeamViewRequestSchema } from "./erlangBeamView.js"; +import { pythonPycViewRequestSchema } from "./pythonPycView.js"; +import { nativeExportsViewRequestSchema } from "./nativeExportsView.js"; +import { javaScriptRoutesViewRequestSchema } from "./javascriptRoutesView.js"; +import { webBundleViewRequestSchema } from "./webBundleView.js"; +import { sourceToBundleViewRequestSchema } from "./sourceToBundleView.js"; +import { gpuCodeObjectsViewRequestSchema } from "./gpuCodeObjectsView.js"; +import { modelArtifactViewRequestSchema } from "../model/modelArtifactQuery.js"; +import { rustBinaryViewRequestSchema } from "../rust/rustBinaryQuery.js"; +import { goBinaryViewRequestSchema } from "./goBinaryView.js"; +import { nativeFunctionMatchingViewRequestSchema } from "./nativeFunctionMatchingView.js"; +import { protobufViewRequestSchema } from "./protobufCaptureView.js"; +import { nativeInventoryViewRequestSchema } from "./nativeInventoryView.js"; + +import { + evidenceFileReferenceSchema, + retainedEvidenceReferenceSchema, +} from "../evidenceReference.js"; +import { z } from "zod"; +import { browserScenarioViewRequestSchema } from "./browserScenarioViewSchemas.js"; +import { nativeLoadImageViewRequestSchema } from "./nativeLoadImageView.js"; +import { desktopViewRequestSchema } from "./desktopApplicationView.js"; +import { javascriptModuleReferencesRequestSchema } from "./javascriptModuleReferences.js"; +import { javascriptFactsViewRequestSchema } from "./javascriptFactsView.js"; +import { evidenceSchema } from "../evidence.js"; +import { apiSurfaceViewSchema } from "./webNetworkApiSurfaceView.js"; +import { evmViewRequestSchema } from "./evmInterfaceView.js"; +import { artifactInventoryViewRequestSchema } from "./artifactInventoryView.js"; +import { managedViewRequestSchema } from "./managedArtifactView.js"; +import { managedMembersViewRequestSchema } from "./managedMemberViewSchemas.js"; +import { wasmViewRequestSchema } from "./wasmArtifactView.js"; +import { machoViewRequestSchema } from "./machoView.js"; +import { interfaceBuilderViewRequestSchema } from "./interfaceBuilderView.js"; +import { captureViewRequestSchema } from "./webNetworkCaptureView.js"; +import { environmentManifestViewRequestSchema } from "./environmentManifestView.js"; +import { environmentStateViewRequestSchema } from "./environmentStateView.js"; +import { environmentCoverageViewRequestSchema } from "./environmentCoverageView.js"; +import { pcapViewRequestSchema } from "./pcapCaptureView.js"; +import { qlogViewRequestSchema } from "./qlogCaptureView.js"; +import { androidViewRequestSchema } from "./androidPackageView.js"; +import { androidJniViewRequestSchema } from "../android/androidJniQuery.js"; +import { dartAotViewRequestSchema } from "./dartAotView.js"; +import { il2cppMetadataViewRequestSchema } from "./il2cppMetadataView.js"; +import { + facetViewSchema, + itemViewSchema, + nativeViewSchema, + pageViewSchema, + summaryViewSchema, +} from "./analysisViewShape.js"; +/** Caller-selected projection of already completed analysis Evidence. */ +export const analysisViewRequestSchema = z.discriminatedUnion("kind", [ + nativeObservationViewRequestSchema, + nativeContextViewRequestSchema, + devicetreeViewRequestSchema, + erlangBeamViewRequestSchema, + pythonPycViewRequestSchema, + nativeExportsViewRequestSchema, + javaScriptRoutesViewRequestSchema, + webBundleViewRequestSchema, + nativeFunctionMatchingViewRequestSchema, + sourceToBundleViewRequestSchema, + summaryViewSchema, + goBinaryViewRequestSchema, + rustBinaryViewRequestSchema, + desktopViewRequestSchema, + facetViewSchema, + itemViewSchema, + pageViewSchema, + javascriptModuleReferencesRequestSchema, + javascriptFactsViewRequestSchema, + nativeViewSchema, + nativeInventoryViewRequestSchema, + nativeLoadImageViewRequestSchema, + artifactInventoryViewRequestSchema, + wasmViewRequestSchema, + machoViewRequestSchema, + interfaceBuilderViewRequestSchema, + evmViewRequestSchema, + managedViewRequestSchema, + managedMembersViewRequestSchema, + androidViewRequestSchema, + androidJniViewRequestSchema, + apiSurfaceViewSchema, + environmentManifestViewRequestSchema, + environmentStateViewRequestSchema, + environmentCoverageViewRequestSchema, + captureViewRequestSchema, + browserScenarioViewRequestSchema, + protobufViewRequestSchema, + qlogViewRequestSchema, + pcapViewRequestSchema, + dartAotViewRequestSchema, + il2cppMetadataViewRequestSchema, + apkSignatureViewRequestSchema, + modelArtifactViewRequestSchema, + gpuCodeObjectsViewRequestSchema, +]); + +// 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, an exact same-session retained reference, or one local Evidence file. */ +export const analysisViewSourceSchema = z.discriminatedUnion("kind", [ + retainedEvidenceReferenceSchema, + z.strictObject({ + kind: z.literal("inline"), + evidence: inlineEvidenceInputSchema, + }), + evidenceFileReferenceSchema, +]); + +/** Public inspect_analysis_view input. */ +export const inspectAnalysisViewInputSchema = z.strictObject({ + source: analysisViewSourceSchema, + view: analysisViewRequestSchema, +}); + +export type AnalysisViewRequest = z.output; +export type InspectAnalysisViewInput = z.output< + typeof inspectAnalysisViewInputSchema +>; diff --git a/src/domain/analysisView/analysisViewResult.ts b/src/domain/analysisView/analysisViewResult.ts new file mode 100644 index 0000000000..f7ee6a1aa1 --- /dev/null +++ b/src/domain/analysisView/analysisViewResult.ts @@ -0,0 +1,1277 @@ +import { analysisViewCoverageSchema } from "./analysisViewCoverage.js"; +import { + javaScriptRouteInventorySourceSchema, + javaScriptRouteInventorySchema, +} from "../javascript/javascriptRouteInventory.js"; +import { nativeFunctionMatchingContextSchema } from "../native/functionMatching.js"; +import { + nativeObservationViewRequestSchema, + nativeContextViewRequestSchema, + nativeObservationItemsSchemas, + nativeContextItemsSchemas, + nativeSourceContextReferenceSchema, + nativeObservationOperationSchema, +} from "./nativeObservationSchemas.js"; +import { + NATIVE_OBSERVATION_OPERATIONS, + type NativeObservationOperation, +} from "../native/nativeObservation.js"; +import { + devicetreeViewRequestSchema, + devicetreeViewItemsSchema, + devicetreeSummarySchema, + devicetreePageContextSchema, +} from "./devicetreeView.js"; +import { + apkSignatureViewRequestSchema, + apkSignatureViewItemsSchema, +} from "../apkSignature/apkSignatureQuery.js"; +import { + apkSignatureSummarySchema, + apkSignatureSourceCoverageSchema, +} from "./apkSignatureView.js"; +import { + erlangBeamViewRequestSchema, + erlangBeamViewPageSchema, + erlangBeamSummarySchema, +} from "./erlangBeamView.js"; +import { + pythonPycViewRequestSchema, + pythonPycViewItemsSchema, + pythonPycSummarySchema, +} from "./pythonPycView.js"; +import { + nativeExportsViewRequestSchema, + nativeExportsViewItemsSchema, + nativeExportsSummarySchema, +} from "./nativeExportsView.js"; +import { byteEntropySummarySchema } from "./byteEntropyView.js"; +import { + javaScriptRoutesViewRequestSchema, + javaScriptRoutesViewItemsSchema, + javaScriptRoutesViewSummarySchema, +} from "./javascriptRoutesView.js"; +import { + webBundleViewRequestSchema, + webBundleViewItemsSchema, + webBundleSummarySchema, +} from "./webBundleView.js"; +import { webBundleAnalysisSchema } from "../webBundleAnalysis.js"; +import { recordedBrowserOriginSchema } from "../browserObservation.js"; +import { + sourceToBundleViewRequestSchema, + sourceToBundleViewItemsSchema, + sourceToBundleViewContextSchema, +} from "./sourceToBundleView.js"; +import { + gpuCodeObjectsViewRequestSchema, + gpuCodeObjectsSummarySchema, + gpuCodeObjectsItemsSchema, + gpuCodeObjectsPtxPageSchema, +} from "./gpuCodeObjectsView.js"; +import { gpuCodeObjectsObjectSchema } from "../gpu/gpuCodeObjects.js"; +import { modelArtifactViewRequestSchema } from "../model/modelArtifactQuery.js"; +import { + modelArtifactSummarySchema, + modelArtifactViewItemsSchema, + modelArtifactViewContextSchema, +} from "./modelArtifactView.js"; +import { + commandSummaryContext, + gdbCommandSummarySchema, +} from "./commandObservationView.js"; +import { + fridaSessionStatusSummarySchema, + fridaSessionStatusViewContext, +} from "./fridaSessionStatusView.js"; +import { commandObservationSchema } from "../commandObservation.js"; +import { + rustBinaryViewPageSchema, + rustBinaryViewRequestSchema, +} from "../rust/rustBinaryQuery.js"; +import { + goBinarySummarySchema, + goBinaryViewContextSchema, + goBinaryViewPageSchema, + goBinaryViewRequestSchema, +} from "./goBinaryView.js"; +import { + rustBinarySummarySchema, + rustBinaryViewContextSchema, +} from "./rustBinaryView.js"; +import { + nativeFunctionMatchingViewRequestSchema, + nativeFunctionMatchingViewItemsSchema, +} from "./nativeFunctionMatchingView.js"; +import { + protobufViewRequestSchema, + protobufViewItemsSchema, + protobufViewContextSchema, +} from "./protobufCaptureView.js"; +import { + nativeInventoryViewRequestSchema, + nativeInventoryViewRowSchema, + nativeInventorySummarySchema, +} from "./nativeInventoryView.js"; +import { nativeViewSourceContext } from "./nativeViewContext.js"; +import { + NATIVE_INVENTORY_OPERATIONS, + nativeInventoryOperationSchema, +} from "../native/nativeInventory.js"; +import { z } from "zod"; +import { + browserScenarioSummarySchema, + browserScenarioViewContextSchema, + browserScenarioViewItemsSchema, + browserScenarioViewRequestSchema, +} from "./browserScenarioViewSchemas.js"; +import { + nativeLoadImageViewRequestSchema, + nativeLoadImageViewItemsSchema, + nativeLoadImageSummarySchema, +} from "./nativeLoadImageView.js"; +import { + desktopViewRequestSchema, + desktopViewItemsSchema, + desktopSummarySchema, +} from "./desktopApplicationView.js"; +import { desktopCoverageSchema } from "../desktopApplication.js"; +import { + javascriptModuleReferencesRequestSchema, + javascriptModuleReferenceSchema, +} from "./javascriptModuleReferences.js"; +import { javascriptApplicationSourceCoverageSchema } from "./javascriptApplicationCoverage.js"; +import { + javascriptFactsViewRequestSchema, + javascriptFactRowSchema, +} from "./javascriptFactsView.js"; +import { javaScriptSourceSelectionSchema } from "../javascript/javascriptSourceSelection.js"; +import { digestSchema, prefixedDigestSchema } from "../digests.js"; +import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js"; +import { binaryLayoutSchema } from "../native/binaryLayout.js"; +import { bundleResourceRootSchema } from "../apple/bundleResourceRoot.js"; +import { functionFacetAvailabilitySchema } from "../native/functionDossier.js"; +import { + artifactGraphManifestSchema, + artifactInventoryCoverageSchema, +} from "../artifactGraph.js"; +import { + apiSurfaceFields, + apiSurfaceViewSchema, +} from "./webNetworkApiSurfaceView.js"; +import { + evmViewRequestSchema, + evmViewItemSchema, + evmSummarySchema, +} from "./evmInterfaceView.js"; +import { + artifactInventoryViewRequestSchema, + artifactInventoryItemsSchema, + artifactInventorySummarySchema, +} from "./artifactInventoryView.js"; +import { + managedViewRequestSchema, + managedViewItemSchema, + managedSummarySchema, + managedViewContextSchema, +} from "./managedArtifactView.js"; +import { + managedMembersViewRequestSchema, + managedMembersViewPageSchema, + managedMemberSummarySchema, + managedMembersViewContextSchema, +} from "./managedMemberViewSchemas.js"; +import { + wasmViewRequestSchema, + wasmViewItemSchema, + wasmSummarySchema, +} from "./wasmArtifactView.js"; +import { + machoSummarySchema, + machoViewContextSchema, + machoViewRows, + machoViewRequestSchema, +} from "./machoView.js"; +import { + interfaceBuilderSummarySchema, + interfaceBuilderViewContextSchema, + interfaceBuilderViewItemsSchema, + interfaceBuilderViewRequestSchema, +} from "./interfaceBuilderView.js"; +import { + captureViewRequestSchema, + captureViewItemsSchema, + captureSummarySchema, +} from "./webNetworkCaptureView.js"; +import { + environmentManifestFields, + environmentManifestViewRequestSchema, +} from "./environmentManifestView.js"; +import { + environmentStateFields, + environmentStateViewRequestSchema, +} from "./environmentStateView.js"; +import { + environmentCoverageFields, + environmentCoverageViewRequestSchema, +} from "./environmentCoverageView.js"; +import { + pcapViewRequestSchema, + pcapViewPageSchema, + pcapSummarySchema, +} from "./pcapCaptureView.js"; +import { + qlogViewRequestSchema, + qlogViewPageSchema, + qlogViewContextSchema, +} from "./qlogCaptureView.js"; +import { + androidPackageSummarySchema, + androidManifestViewItemSchema, + androidManifestViewRequestSchema, + androidComponentsViewRequestSchema, + androidComponentSummaryViewRequestSchema, + androidComponentViewRowSchema, + androidComponentViewContextSchema, + androidComponentSummarySchema, +} from "./androidPackageView.js"; +import { + androidClassSummarySchema, + androidMethodSummarySchema, +} from "./androidSymbolView.js"; +import { androidJniSummarySchema } from "./androidJniView.js"; +import { + androidJniViewRequestSchema, + androidJniViewItemsSchema, +} from "../android/androidJniQuery.js"; +import { + dartAotSummarySchema, + dartAotViewRequestSchema, + dartAotViewContextSchema, +} from "./dartAotView.js"; +import { + il2cppMetadataSummarySchema, + il2cppMetadataViewRequestSchema, + il2cppMetadataViewContextSchema, + il2cppMetadataViewItemsSchema, +} from "./il2cppMetadataView.js"; +import { + facetViewSchema, + itemViewSchema, + nativeViewSchema, + pageViewSchema, + summaryViewSchema, +} from "./analysisViewShape.js"; +const artifactSchema = z.strictObject({ + path: z + .string() + .describe( + "Selected artifact path, or the canonical resource root when resource-only Evidence has no executable subject.", + ), + sha256: digestSchema.nullable(), +}); + +const layoutSummarySchema = z.strictObject({ + bytes: binaryLayoutSchema.shape.artifact.shape.bytes, + format: binaryLayoutSchema.shape.format, + architecture: binaryLayoutSchema.shape.architecture, + image_type: binaryLayoutSchema.shape.image_type, + 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.int().nonnegative(), + segments: z.int().nonnegative(), + symbols: z.int().nonnegative(), + relocations: z.int().nonnegative(), + }), + limitation_count: z.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.int().nonnegative(), +}); + +const viewResultBase = { + parent_evidence_id: prefixedDigestSchema("ev"), + parent_operation: z.enum([ + "inspect_python_pyc", + "inspect_erlang_beam", + "inspect_devicetree", + "inspect_byte_entropy", + "inspect_native_exports", + "inspect_binary_layout", + "inspect_go_binary", + "gdb_console", + "frida_session_status", + "inspect_with_objdump", + "inspect_desktop_application", + "analyze_javascript_application", + "analyze_web_bundle", + "analyze_function", + "inspect_artifact", + "inventory_artifact", + "inspect_wasm_artifact", + "inspect_macho", + "decode_interface_builder", + "inspect_evm_interface", + "inspect_managed_artifact", + "inspect_managed_members", + "inspect_web_network_capture", + "inspect_android_package", + "inspect_android_class", + "inspect_android_method", + "inspect_android_jni_bindings", + "inspect_pcap_capture", + "inspect_dart_aot", + "inspect_il2cpp_metadata", + "inspect_model_artifact", + "inspect_gpu_code_objects", + ...NATIVE_INVENTORY_OPERATIONS, + ...NATIVE_OBSERVATION_OPERATIONS, + "match_native_functions", + ]), + parent_digest: digestSchema, + view_digest: digestSchema, + artifact: artifactSchema, + coverage: analysisViewCoverageSchema, + limitations: z.array(z.string()), + unknowns: z.array(z.string()), +} as const; + +const summaryViewResultBase = { + kind: z.literal("summary"), + view: summaryViewSchema, + ...viewResultBase, +} as const; + +const nativeObservationSummaryFor = < + Operation extends NativeObservationOperation, +>( + operation: Operation, +) => + z.strictObject({ + ...summaryViewResultBase, + ...nativeViewSourceContext, + artifact: artifactSchema.nullable(), + parent_operation: z.literal(operation), + source_context: nativeSourceContextReferenceSchema, + summary: z.strictObject({ observations: z.int().nonnegative() }), + items: nativeObservationItemsSchemas[operation], + }); +export const nativeObservationSummaryViewResultSchemas = { + procedure_address: nativeObservationSummaryFor("procedure_address"), + procedure_callees: nativeObservationSummaryFor("procedure_callees"), + procedure_callers: nativeObservationSummaryFor("procedure_callers"), + resolve_containing_procedure: nativeObservationSummaryFor( + "resolve_containing_procedure", + ), + get_call_graph: nativeObservationSummaryFor("get_call_graph"), +}; +const nativeObservationSummaryViewResultSchema = z.discriminatedUnion( + "parent_operation", + [ + nativeObservationSummaryViewResultSchemas.procedure_address, + nativeObservationSummaryViewResultSchemas.procedure_callees, + nativeObservationSummaryViewResultSchemas.procedure_callers, + nativeObservationSummaryViewResultSchemas.resolve_containing_procedure, + nativeObservationSummaryViewResultSchemas.get_call_graph, + ], +); +const nativeObservationPageFor = ( + operation: Operation, +) => + nativeObservationSummaryFor(operation) + .omit({ kind: true, view: true }) + .extend({ + kind: z.literal("native-observation"), + view: nativeObservationViewRequestSchema, + }); +const nativeObservationPageViewResultSchema = z.discriminatedUnion( + "parent_operation", + [ + nativeObservationPageFor("procedure_address"), + nativeObservationPageFor("procedure_callees"), + nativeObservationPageFor("procedure_callers"), + nativeObservationPageFor("resolve_containing_procedure"), + nativeObservationPageFor("get_call_graph"), + ], +); +const nativeContextFor = ( + facet: Facet, +) => + z.strictObject({ + ...viewResultBase, + ...nativeViewSourceContext, + kind: z.literal("native-context"), + artifact: artifactSchema.nullable(), + parent_operation: nativeObservationOperationSchema, + source_context: nativeSourceContextReferenceSchema, + facet: z.literal(facet), + view: nativeContextViewRequestSchema.extend({ facet: z.literal(facet) }), + items: nativeContextItemsSchemas[facet], + }); +const nativeContextViewResultSchema = z.discriminatedUnion("facet", [ + nativeContextFor("overview"), + nativeContextFor("analysis-profile"), + nativeContextFor("limitations"), + nativeContextFor("result-limitations"), +]); + +export const byteEntropySummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + summary: byteEntropySummarySchema, + parent_operation: z.literal("inspect_byte_entropy"), +}); + +export const nativeExportsSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_native_exports"), + summary: nativeExportsSummarySchema, +}); + +export const devicetreeSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_devicetree"), + summary: devicetreeSummarySchema, +}); +export const erlangBeamSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_erlang_beam"), + summary: erlangBeamSummarySchema, +}); +export const erlangBeamTableViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("beam"), + parent_operation: z.literal("inspect_erlang_beam"), + view: erlangBeamViewRequestSchema, + beam: erlangBeamSummarySchema, + page: erlangBeamViewPageSchema, +}); + +export const pythonPycSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_python_pyc"), + summary: pythonPycSummarySchema, +}); + +export const pythonPycCodeObjectsViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("python-pyc"), + parent_operation: z.literal("inspect_python_pyc"), + view: pythonPycViewRequestSchema, + pyc: pythonPycSummarySchema, + items: pythonPycViewItemsSchema, +}); + +/** Opt-in command delivery keeps output once and retains the complete parent. */ +export const gdbCommandSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...commandSummaryContext, + parent_operation: z.literal("gdb_console"), + artifact: artifactSchema.nullable(), + summary: gdbCommandSummarySchema, +}); + +export const objdumpSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...commandSummaryContext, + parent_operation: z.literal("inspect_with_objdump"), + artifact: artifactSchema.nullable(), + summary: commandObservationSchema, +}); + +export const fridaSessionStatusSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...fridaSessionStatusViewContext, + parent_operation: z.literal("frida_session_status"), + artifact: artifactSchema.nullable(), + summary: fridaSessionStatusSummarySchema, +}); + +/** Opt-in Go delivery retains original bytes and exposes build identity/counts. */ +export const goBinarySummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...goBinaryViewContextSchema.shape, + parent_operation: z.literal("inspect_go_binary"), + summary: goBinarySummarySchema, +}); + +/** Compact source identity and counts, retaining the complete embedded graph. */ +export const rustBinarySummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...rustBinaryViewContextSchema.shape, + parent_operation: z.literal("inspect_rust_binary"), + summary: rustBinarySummarySchema, +}); + +export const rustBinaryPageViewResultSchema = z.strictObject({ + ...viewResultBase, + ...rustBinaryViewContextSchema.shape, + kind: z.literal("rust"), + parent_operation: z.literal("inspect_rust_binary"), + view: rustBinaryViewRequestSchema, + rust: rustBinarySummarySchema, + page: rustBinaryViewPageSchema, +}); + +/** Summary `inspect_binary_layout` detail returns; no other view kind. */ +export const binaryLayoutSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + summary: layoutSummarySchema, + parent_operation: z.literal("inspect_binary_layout"), +}); + +/** Summary `analyze_javascript_application` detail returns; no other view kind. */ +export const javascriptApplicationSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + summary: javascriptSummarySchema, + parent_operation: z.literal("analyze_javascript_application"), +}); + +/** Typed reference page; full item observations remain available separately. */ +export const javascriptModuleReferencesViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("javascript"), + view: javascriptModuleReferencesRequestSchema, + parent_operation: z.literal("analyze_javascript_application"), + rows: z.array(javascriptModuleReferenceSchema), + source_coverage: javascriptApplicationSourceCoverageSchema, +}); + +/** Paged retained observations with exact selected properties and provenance. */ +const javascriptFactsViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("javascript-facts"), + view: javascriptFactsViewRequestSchema, + parent_operation: z.literal("analyze_javascript_application"), + rows: z.array(javascriptFactRowSchema), + source_coverage: javascriptApplicationSourceCoverageSchema, +}); + +/** Exact summary carrier for artifact inspection's optional delivery contract. */ +export const artifactInventorySummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.enum(["inspect_artifact", "inventory_artifact"]), + summary: artifactInventorySummarySchema, +}); + +export const desktopApplicationSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_desktop_application"), + summary: desktopSummarySchema, +}); + +/** Exact summary carrier for WASM inspection's optional delivery contract. */ +export const wasmArtifactSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_wasm_artifact"), + summary: wasmSummarySchema, +}); + +/** Exact slice identity and collection counts for Mach-O's selected delivery. */ +export const machoSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_macho"), + summary: machoSummarySchema, +}); + +/** Decoded documents and graph counts for Interface Builder's selected delivery. */ +export const interfaceBuilderSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("decode_interface_builder"), + resource_root: bundleResourceRootSchema.optional(), + summary: interfaceBuilderSummarySchema, +}); + +/** Exact inferred-interface summary for EVM's caller-selected delivery. */ +export const evmInterfaceSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_evm_interface"), + summary: evmSummarySchema, +}); + +/** Exact metadata overview for the managed artifact's selected delivery. */ +export const managedArtifactSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_managed_artifact"), + summary: managedSummarySchema, +}); + +/** Exact member selection, coverage and counts for the selected delivery. */ +export const managedMemberSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_managed_members"), + summary: managedMemberSummarySchema, +}); + +/** Exact historical capture summary, with no body or member-inventory payload. */ +export const webNetworkCaptureSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_web_network_capture"), + summary: captureSummarySchema, +}); + +/** Compact outcomes and the focus screen from a retained browser scenario. */ +export const browserScenarioSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + artifact: z.null(), + parent_operation: z.literal("capture_browser_scenario"), + summary: browserScenarioSummarySchema, +}); + +/** Exact package declarations with retained decoded manifest text. */ +export const androidPackageSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_android_package"), + summary: androidPackageSummarySchema, +}); +export const androidJniSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_android_jni_bindings"), + summary: androidJniSummarySchema, +}); +export const androidJniPageViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("android-jni"), + parent_operation: z.literal("inspect_android_jni_bindings"), + view: androidJniViewRequestSchema, + items: androidJniViewItemsSchema, + source: androidJniSummarySchema.pick({ + native_inventory: true, + library_inventory: true, + selection: true, + }), +}); + +/** Exact class facts with complete raw protocol Evidence retained separately. */ +export const androidClassSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_android_class"), + summary: androidClassSummarySchema, +}); + +/** Exact selected method body, source coverage and optional mapping facts. */ +export const androidMethodSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_android_method"), + summary: androidMethodSummarySchema, +}); + +/** Legacy manifest views keep their original shape; new facets are explicit. */ +export const androidManifestViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("android"), + facet: z.literal("manifest").optional(), + view: androidManifestViewRequestSchema, + item: androidManifestViewItemSchema, + parent_operation: z.literal("inspect_android_package"), +}); +export const androidComponentsViewResultSchema = z.strictObject({ + ...viewResultBase, + ...androidComponentViewContextSchema.shape, + kind: z.literal("android"), + facet: z.literal("components"), + view: androidComponentsViewRequestSchema, + items: z.array(androidComponentViewRowSchema), + byte_limited: z.boolean(), + parent_operation: z.literal("inspect_android_package"), +}); +export const androidComponentSummaryViewResultSchema = z.strictObject({ + ...viewResultBase, + ...androidComponentViewContextSchema.shape, + kind: z.literal("android"), + facet: z.literal("component-summary"), + view: androidComponentSummaryViewRequestSchema, + summary: androidComponentSummarySchema, + parent_operation: z.literal("inspect_android_package"), +}); +const androidPackageViewResultSchema = z.discriminatedUnion("facet", [ + androidManifestViewResultSchema, + androidComponentsViewResultSchema, + androidComponentSummaryViewResultSchema, +]); + +export const pcapCaptureSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_pcap_capture"), + summary: pcapSummarySchema, +}); + +/** Exact snapshot and pool-coverage carrier for selected AOT delivery. */ +export const dartAotSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_dart_aot"), + summary: dartAotSummarySchema, +}); + +export const javaScriptRoutesViewResultSchema = z.strictObject({ + ...viewResultBase, + artifact: artifactSchema.nullable(), + kind: z.literal("javascript-routes"), + parent_operation: z.enum([ + "analyze_javascript_application", + "analyze_web_bundle", + ]), + view: javaScriptRoutesViewRequestSchema, + inventory_id: javaScriptRouteInventorySchema.shape.inventory_id, + source_manifest_sha256: digestSchema, + source_coverage: javaScriptRouteInventorySchema.shape.coverage, + inventory_capacity: javaScriptRouteInventorySchema.shape.capacity, + capture_url: z.string().nullable(), + items: javaScriptRoutesViewItemsSchema, + sources: z.array(javaScriptRouteInventorySourceSchema), + summary: javaScriptRoutesViewSummarySchema.nullable(), + byte_limited: z.boolean(), +}); + +/** Compact web bundle findings retain endpoint observations and inference candidates. */ +export const webBundleSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + artifact: artifactSchema.nullable(), + parent_operation: z.literal("analyze_web_bundle"), + target_url: z.string(), + target_origin: recordedBrowserOriginSchema.nullable().optional(), + source_unknowns: webBundleAnalysisSchema.shape.unknowns, + summary: webBundleSummarySchema, +}); + +export const webBundlePageViewResultSchema = z.strictObject({ + ...viewResultBase, + artifact: artifactSchema.nullable(), + kind: z.literal("web-bundle"), + parent_operation: z.literal("analyze_web_bundle"), + target_url: z.string(), + target_origin: recordedBrowserOriginSchema.nullable().optional(), + source_unknowns: webBundleAnalysisSchema.shape.unknowns, + view: webBundleViewRequestSchema, + completeness: webBundleAnalysisSchema.shape.completeness, + items: webBundleViewItemsSchema, + summary: webBundleSummarySchema.nullable(), + byte_limited: z.boolean(), +}); + +export const gpuCodeObjectsSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_gpu_code_objects"), + summary: gpuCodeObjectsSummarySchema, +}); +export const gpuCodeObjectsPageViewResultSchema = z.strictObject({ + kind: z.literal("gpu-code-objects"), + view: gpuCodeObjectsViewRequestSchema, + items: gpuCodeObjectsItemsSchema, + ptx: gpuCodeObjectsPtxPageSchema.nullable(), + source_coverage: gpuCodeObjectsObjectSchema.shape.coverage, + ...viewResultBase, + parent_operation: z.literal("inspect_gpu_code_objects"), +}); + +export const apkSignatureSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_apk_signature"), + summary: apkSignatureSummarySchema, +}); +export const apkSignaturePageViewResultSchema = z.strictObject({ + ...viewResultBase, + kind: z.literal("apk-signature"), + parent_operation: z.literal("inspect_apk_signature"), + view: apkSignatureViewRequestSchema, + items: apkSignatureViewItemsSchema, + source_coverage: apkSignatureSourceCoverageSchema, +}); + +export const modelArtifactSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_model_artifact"), + summary: modelArtifactSummarySchema, +}); + +export const modelArtifactPageViewResultSchema = z.strictObject({ + kind: z.literal("model-artifact"), + view: modelArtifactViewRequestSchema, + items: modelArtifactViewItemsSchema, + ...viewResultBase, + ...modelArtifactViewContextSchema.shape, + parent_operation: z.literal("inspect_model_artifact"), +}); + +/** Metadata identity and row counts for selected IL2CPP delivery. */ +export const il2cppMetadataSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_il2cpp_metadata"), + summary: il2cppMetadataSummarySchema, +}); + +/** Exact inventory summary with the original observation's provider and query. */ +export const nativeInventorySummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...nativeViewSourceContext, + parent_operation: nativeInventoryOperationSchema, + artifact: artifactSchema.nullable(), + summary: nativeInventorySummarySchema, +}); + +/** Compact provider load observations retain the independent verification state. */ +export const nativeLoadImageSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + ...nativeViewSourceContext, + artifact: artifactSchema.nullable(), + parent_operation: z.literal("inspect_native_load_image"), + summary: nativeLoadImageSummarySchema, +}); + +/** Compact native matching discovery retains the complete matching report. */ +export const nativeFunctionMatchingSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + artifact: z.null(), + parent_operation: z.literal("match_native_functions"), + summary: nativeFunctionMatchingContextSchema, +}); + +/** Rows observed for one facet, or null when the provider declared that facet unavailable. */ +const declaredFacetCountSchema = z + .number() + .int() + .nonnegative() + .nullable() + .describe( + "Observed rows; null when facet_availability declares the facet unavailable, so no rows is not evidence of none.", + ); + +/** Rows of an optional dossier record, or null when the dossier omitted it. */ +const recordedFacetCountSchema = z + .number() + .int() + .nonnegative() + .nullable() + .describe( + "Observed rows; null when the dossier did not record the facet (the native facet view reports it not recorded), so no rows is not evidence of none.", + ); + +/** Rows of one value-flow facet, or null when value flow is unavailable. */ +const valueFlowFacetCountSchema = z + .number() + .int() + .nonnegative() + .nullable() + .describe( + "Observed rows; null when value_flow.available is false because native_value_flow was not recorded or the provider declared it unavailable (unknowns names which), so no rows is not evidence of none.", + ); + +/** Compact analyze_function dossier; the complete dossier stays retained for facet paging. */ +export const nativeFunctionSummarySchema = z.strictObject({ + procedure: z.strictObject({ + name: z.string(), + address: z.string(), + }), + pseudocode: z.strictObject({ + available: z + .boolean() + .describe( + "Provider facet_availability for pseudocode when declared; otherwise whether decompiled text is present. The flag is authoritative over raw length.", + ), + code_units: z + .number() + .int() + .nonnegative() + .describe( + "Pseudocode length in UTF-16 code units, the unit inspect_analysis_view pages pseudocode by.", + ), + }), + value_flow: z.strictObject({ + available: z.boolean(), + truncated: z + .boolean() + .describe( + "True only when value-flow is available and the provider truncated it; false when value-flow is unavailable (see available).", + ), + }), + facet_availability: functionFacetAvailabilitySchema + .nullable() + .describe( + "The provider's declared availability per facet, or null when it declared none. Unavailable facets name their reason here and in unknowns.", + ), + counts: z.strictObject({ + assembly: declaredFacetCountSchema, + basic_blocks: declaredFacetCountSchema, + comments: declaredFacetCountSchema, + callers: declaredFacetCountSchema, + callees: declaredFacetCountSchema, + incoming_references: declaredFacetCountSchema, + outgoing_references: declaredFacetCountSchema, + unresolved_calls: recordedFacetCountSchema, + referenced_strings: declaredFacetCountSchema, + referenced_names: declaredFacetCountSchema, + swift_string_literals: recordedFacetCountSchema, + swift_string_literal_omissions: recordedFacetCountSchema, + value_flow_operations: valueFlowFacetCountSchema, + value_flow_def_use: valueFlowFacetCountSchema, + value_flow_effects: valueFlowFacetCountSchema, + value_flow_parameters: valueFlowFacetCountSchema, + value_flow_parameter_uses: valueFlowFacetCountSchema, + }), + limitation_count: z.number().int().nonnegative(), +}); + +/** Compact analyze_function summary that retains the complete native dossier Evidence. */ +export const nativeFunctionSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("analyze_function"), + procedure_address: z.string().nullable(), + summary: nativeFunctionSummarySchema, +}); + +export const sourceToBundleSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + artifact: z.null(), + parent_operation: z.literal("compare_source_to_bundle"), + summary: sourceToBundleViewContextSchema, +}); +export const sourceToBundlePageViewResultSchema = z.strictObject({ + ...viewResultBase, + ...sourceToBundleViewContextSchema.shape, + kind: z.literal("source-to-bundle"), + artifact: z.null(), + parent_operation: z.literal("compare_source_to_bundle"), + view: sourceToBundleViewRequestSchema, + items: sourceToBundleViewItemsSchema, +}); + +/** Bind the existing nested facet selection to its producer-owned rows. */ +const machoPage = (facet: Facet) => + z.strictObject({ + ...viewResultBase, + ...machoViewContextSchema.shape, + kind: z.literal("macho"), + parent_operation: z.literal("inspect_macho"), + view: machoViewRequestSchema.extend({ facet: z.literal(facet) }), + item: machoViewRows[facet], + }); + +// The input tag preserves kind dispatch; the output projection advertises the +// correlated pages without adding a discriminator to their public wire shape. +const machoPageViewResultSchema = z + .object({ kind: z.literal("macho") }) + .passthrough() + .pipe( + z.union([ + machoPage("entrypoints"), + machoPage("architectures"), + machoPage("build_metadata"), + machoPage("load_commands"), + machoPage("dependencies"), + machoPage("imports"), + machoPage("exports"), + machoPage("segments"), + machoPage("encryption"), + machoPage("provenance"), + ]), + ); + +/** Projected facts for one selected view of retained analysis Evidence. */ +export const analysisViewResultSchema = z.discriminatedUnion("kind", [ + nativeObservationPageViewResultSchema, + nativeContextViewResultSchema, + javaScriptRoutesViewResultSchema, + webBundlePageViewResultSchema, + sourceToBundlePageViewResultSchema, + z.strictObject({ + ...viewResultBase, + ...nativeFunctionMatchingContextSchema.shape, + kind: z.literal("function-matches"), + artifact: z.null(), + view: nativeFunctionMatchingViewRequestSchema, + items: nativeFunctionMatchingViewItemsSchema, + parent_operation: z.literal("match_native_functions"), + }), + 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({ + ...viewResultBase, + ...environmentManifestFields, + kind: z.literal("environment-manifest"), + parent_operation: z.enum([ + "inspect_web_network_capture", + "capture_browser_scenario", + ]), + view: environmentManifestViewRequestSchema, + }), + z.strictObject({ + ...viewResultBase, + ...environmentStateFields, + kind: z.literal("environment-state"), + parent_operation: z.enum([ + "inspect_web_network_capture", + "capture_browser_scenario", + ]), + view: environmentStateViewRequestSchema, + }), + z.strictObject({ + ...viewResultBase, + ...environmentCoverageFields, + kind: z.literal("environment-coverage"), + parent_operation: z.enum([ + "inspect_web_network_capture", + "capture_browser_scenario", + ]), + view: environmentCoverageViewRequestSchema, + }), + z.discriminatedUnion("parent_operation", [ + nativeObservationSummaryViewResultSchema, + erlangBeamSummaryViewResultSchema, + devicetreeSummaryViewResultSchema, + pythonPycSummaryViewResultSchema, + nativeExportsSummaryViewResultSchema, + byteEntropySummaryViewResultSchema, + gdbCommandSummaryViewResultSchema, + objdumpSummaryViewResultSchema, + fridaSessionStatusSummaryViewResultSchema, + goBinarySummaryViewResultSchema, + rustBinarySummaryViewResultSchema, + binaryLayoutSummaryViewResultSchema, + desktopApplicationSummaryViewResultSchema, + javascriptApplicationSummaryViewResultSchema, + artifactInventorySummaryViewResultSchema, + wasmArtifactSummaryViewResultSchema, + machoSummaryViewResultSchema, + interfaceBuilderSummaryViewResultSchema, + evmInterfaceSummaryViewResultSchema, + managedArtifactSummaryViewResultSchema, + managedMemberSummaryViewResultSchema, + webNetworkCaptureSummaryViewResultSchema, + browserScenarioSummaryViewResultSchema, + androidPackageSummaryViewResultSchema, + androidJniSummaryViewResultSchema, + androidClassSummaryViewResultSchema, + androidMethodSummaryViewResultSchema, + pcapCaptureSummaryViewResultSchema, + dartAotSummaryViewResultSchema, + il2cppMetadataSummaryViewResultSchema, + apkSignatureSummaryViewResultSchema, + modelArtifactSummaryViewResultSchema, + gpuCodeObjectsSummaryViewResultSchema, + nativeInventorySummaryViewResultSchema, + nativeLoadImageSummaryViewResultSchema, + nativeFunctionMatchingSummaryViewResultSchema, + nativeFunctionSummaryViewResultSchema, + sourceToBundleSummaryViewResultSchema, + webBundleSummaryViewResultSchema, + ]), + z.strictObject({ + ...viewResultBase, + kind: z.literal("devicetree"), + parent_operation: z.literal("inspect_devicetree"), + view: devicetreeViewRequestSchema, + devicetree: devicetreePageContextSchema, + items: devicetreeViewItemsSchema, + }), + erlangBeamTableViewResultSchema, + pythonPycCodeObjectsViewResultSchema, + z.strictObject({ + ...viewResultBase, + kind: z.literal("native-exports"), + parent_operation: z.literal("inspect_native_exports"), + view: nativeExportsViewRequestSchema, + exports: nativeExportsSummarySchema, + items: nativeExportsViewItemsSchema, + }), + z.strictObject({ + ...viewResultBase, + ...nativeViewSourceContext, + kind: z.literal("native-inventory"), + parent_operation: nativeInventoryOperationSchema, + artifact: artifactSchema.nullable(), + view: nativeInventoryViewRequestSchema, + rows: z.array(nativeInventoryViewRowSchema), + }), + z.strictObject({ + ...viewResultBase, + kind: z.literal("native-load-image"), + ...nativeViewSourceContext, + verification_status: z.enum(["unsupported", "verified", "mismatch"]), + parent_operation: z.literal("inspect_native_load_image"), + artifact: artifactSchema.nullable(), + view: nativeLoadImageViewRequestSchema, + items: nativeLoadImageViewItemsSchema, + }), + z.strictObject({ + kind: z.literal("protobuf"), + view: protobufViewRequestSchema, + items: protobufViewItemsSchema, + ...viewResultBase, + ...protobufViewContextSchema.shape, + parent_operation: z.literal("inspect_web_network_capture"), + }), + z.strictObject({ + kind: z.literal("capture"), + view: captureViewRequestSchema, + items: captureViewItemsSchema, + ...viewResultBase, + parent_operation: z.literal("inspect_web_network_capture"), + }), + z.strictObject({ + kind: z.literal("browser-scenario"), + view: browserScenarioViewRequestSchema, + items: browserScenarioViewItemsSchema, + ...viewResultBase, + ...browserScenarioViewContextSchema.shape, + artifact: z.null(), + parent_operation: z.literal("capture_browser_scenario"), + }), + z.strictObject({ + kind: z.literal("qlog"), + view: qlogViewRequestSchema, + page: qlogViewPageSchema, + context: qlogViewContextSchema, + ...viewResultBase, + parent_operation: z.literal("inspect_web_network_capture"), + }), + z.strictObject({ + kind: z.literal("pcap"), + view: pcapViewRequestSchema, + page: pcapViewPageSchema, + source_coverage: z.enum(["complete", "partial"]), + ...viewResultBase, + parent_operation: z.literal("inspect_pcap_capture"), + }), + z.strictObject({ + kind: z.literal("facet"), + view: facetViewSchema, + facet: jsonValueSchema, + ...viewResultBase, + }), + z.strictObject({ + ...viewResultBase, + ...goBinaryViewContextSchema.shape, + kind: z.literal("go"), + parent_operation: z.literal("inspect_go_binary"), + view: goBinaryViewRequestSchema, + page: goBinaryViewPageSchema, + }), + rustBinaryPageViewResultSchema, + z.strictObject({ + kind: z.literal("item"), + view: itemViewSchema, + item: jsonValueSchema, + ...viewResultBase, + }), + z.strictObject({ + kind: z.literal("page"), + view: pageViewSchema, + items: z.array(jsonValueSchema), + ...viewResultBase, + }), + javascriptModuleReferencesViewResultSchema, + javascriptFactsViewResultSchema, + z.strictObject({ + kind: z.literal("native"), + view: nativeViewSchema, + procedure_address: z.string().nullable(), + item: jsonValueSchema, + ...viewResultBase, + }), + z.strictObject({ + kind: z.literal("wasm"), + view: wasmViewRequestSchema, + item: wasmViewItemSchema, + ...viewResultBase, + }), + z.strictObject({ + kind: z.literal("desktop-application"), + view: desktopViewRequestSchema, + items: desktopViewItemsSchema, + ...viewResultBase, + source_coverage: desktopCoverageSchema, + parent_operation: z.literal("inspect_desktop_application"), + }), + machoPageViewResultSchema, + z.strictObject({ + kind: z.literal("interface-builder"), + view: interfaceBuilderViewRequestSchema, + items: interfaceBuilderViewItemsSchema, + ...viewResultBase, + resource_root: bundleResourceRootSchema.optional(), + ...interfaceBuilderViewContextSchema.shape, + parent_operation: z.literal("decode_interface_builder"), + }), + z.strictObject({ + kind: z.literal("evm"), + view: evmViewRequestSchema, + item: evmViewItemSchema, + ...viewResultBase, + parent_operation: z.literal("inspect_evm_interface"), + }), + z.strictObject({ + kind: z.literal("managed"), + view: managedViewRequestSchema, + item: managedViewItemSchema, + ...viewResultBase, + ...managedViewContextSchema.shape, + parent_operation: z.literal("inspect_managed_artifact"), + }), + z.strictObject({ + kind: z.literal("managed-members"), + view: managedMembersViewRequestSchema, + page: managedMembersViewPageSchema, + ...viewResultBase, + ...managedMembersViewContextSchema.shape, + parent_operation: z.literal("inspect_managed_members"), + }), + androidPackageViewResultSchema, + androidJniPageViewResultSchema, + z.strictObject({ + kind: z.literal("dart-aot"), + view: dartAotViewRequestSchema, + items: z.array(z.string()), + ...viewResultBase, + ...dartAotViewContextSchema.shape, + parent_operation: z.literal("inspect_dart_aot"), + }), + apkSignaturePageViewResultSchema, + modelArtifactPageViewResultSchema, + gpuCodeObjectsPageViewResultSchema, + z.strictObject({ + kind: z.literal("il2cpp-metadata"), + view: il2cppMetadataViewRequestSchema, + items: il2cppMetadataViewItemsSchema, + ...viewResultBase, + ...il2cppMetadataViewContextSchema.shape, + parent_operation: z.literal("inspect_il2cpp_metadata"), + }), + z.strictObject({ + kind: z.literal("inventory"), + view: artifactInventoryViewRequestSchema, + source_coverage: artifactInventoryCoverageSchema.exactOptional(), + manifest: artifactGraphManifestSchema, + inventory_evidence_ids: z.array(prefixedDigestSchema("ev")).min(1), + source_complete: z.boolean(), + items: artifactInventoryItemsSchema, + ...viewResultBase, + }), +]); + +export type AnalysisViewResult = z.output; + +/** View payload before the content digest is attached. */ +type WithoutViewDigest = T extends { readonly view_digest: string } + ? Omit + : never; +export type UnsignedAnalysisView = WithoutViewDigest; diff --git a/src/domain/analysisView/analysisViewShape.ts b/src/domain/analysisView/analysisViewShape.ts new file mode 100644 index 0000000000..8a9bf062b8 --- /dev/null +++ b/src/domain/analysisView/analysisViewShape.ts @@ -0,0 +1,127 @@ +import { z } from "zod"; +import { prefixedDigestSchema } from "../digests.js"; + +export const summaryViewSchema = z.strictObject({ kind: z.literal("summary") }); +export const facetViewSchema = z.strictObject({ + kind: z.literal("facet"), + facet: z.enum(["mitigations", "linkage"]), +}); +const indexSelectorSchema = z.strictObject({ + index: z.int().nonnegative(), +}); +const nameSelectorSchema = z.strictObject({ + name: z + .string() + .describe( + "Exact UTF-8 section or symbol name, matched against retained source bytes. Use index for non-UTF-8 names or unresolved name bytes.", + ), +}); +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. + */ +export const itemViewSchema = z.discriminatedUnion("collection", [ + moduleItemViewSchema, + sectionOrSymbolItemViewSchema, +]); +export const pageViewSchema = z.strictObject({ + kind: z.literal("page"), + collection: z.enum(["sections", "symbols", "modules"]), + offset: z.int().nonnegative(), + limit: z.int().positive(), +}); + +/** Bounded native function facets of already authenticated analyze_function Evidence. */ +export 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", + "swift_string_literals", + "swift_string_literal_omissions", + "native_api", + "value_flow_summary", + "value_flow_operations", + "value_flow_def_use", + "value_flow_effects", + "value_flow_parameters", + "value_flow_parameter_uses", + ]), + offset: z.int().nonnegative().default(0), + limit: z.int().positive().default(64), +}); + +export type SummaryAnalysisView = z.output; +export type FacetAnalysisView = z.output; +export type ItemAnalysisView = z.output; +export type PageAnalysisView = z.output; +export type NativeFacetAnalysisView = z.output; + +/** Views that group a capture's records into tools. */ +export type GroupingViewKind = + | "api-surface" + | "environment-manifest" + | "environment-state" + | "environment-coverage"; + +/** + * View request already admitted by analysisViewRequestSchema. + * Projectors use this supertype so they do not import the request union. + */ +export type AdmittedView = { readonly kind: string }; + +/** + * Restore the owning schema output after admission. + * analysisViewRequestSchema already checked the fields for these kinds. + */ +export const ownedView = ( + view: AdmittedView, + ...kinds: readonly View["kind"][] +): View | undefined => + (kinds as readonly string[]).includes(view.kind) ? (view as View) : undefined; + +/** Narrow an admitted view after the projector has rejected other kinds. */ +export function assertOwnedView( + view: AdmittedView, + ...kinds: readonly View["kind"][] +): asserts view is View { + if (!(kinds as readonly string[]).includes(view.kind)) { + throw new Error( + `Analysis view kind ${JSON.stringify(view.kind)} is not owned by this projector.`, + ); + } +} diff --git a/src/domain/analysisView/androidJniView.ts b/src/domain/analysisView/androidJniView.ts index c91407956b..6c978d81cb 100644 --- a/src/domain/analysisView/androidJniView.ts +++ b/src/domain/analysisView/androidJniView.ts @@ -6,17 +6,20 @@ import { androidJniDeclarationSchema, androidJniLibrarySchema, } from "../android/androidJniBindings.js"; -import { androidJniViewItemsSchema } from "../android/androidJniQuery.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; +import { + androidJniViewItemsSchema, + androidJniViewRequestSchema, +} from "../android/androidJniQuery.js"; import { AnalysisResourceConstraintError } from "../analysisErrorCore.js"; import type { JsonValue } from "../jsonValue.js"; import { jsonValueByteLength } from "../jsonValueByteLength.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { ANALYSIS_VIEW_PAGE_BUDGET_RECOVERY, analysisViewInputError, @@ -63,8 +66,8 @@ export const androidJniSummarySchema = reportSchema /** Source facts are already parsed; views never reopen the APK or rerun either reader. */ export const projectAndroidJniView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if ( parent.operation !== "inspect_android_jni_bindings" || (view.kind !== "summary" && view.kind !== "android-jni") @@ -79,6 +82,9 @@ export const projectAndroidJniView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "android-jni"); const parsed = readReport(parent); if (!parsed.ok) return parsed; const report = parsed.value; @@ -98,7 +104,19 @@ export const projectAndroidJniView = ( "unknowns", ), }; - let result: UnsignedAnalysisView; + const overBudget = (value: object): boolean => + jsonValueByteLength(value as unknown as JsonValue, 1024 * 1024 - 128) > + 1024 * 1024 - 128; + const budgetError = () => + err( + new AnalysisResourceConstraintError( + "inspect_analysis_view", + "transport", + "JNI view exceeds its 1 MiB serialized allowance.", + { parent_evidence_id: parent.evidenceId, limit_bytes: 1024 * 1024 }, + ANALYSIS_VIEW_PAGE_BUDGET_RECOVERY, + ), + ); if (view.kind === "summary") { const bindings = report.bindings.slice(0, 64); const candidateIds = new Set( @@ -124,9 +142,9 @@ export const projectAndroidJniView = ( unknown: 0, }; for (const binding of report.bindings) counts[binding.status]++; - result = { + const summary = { ...shared, - kind: "summary", + kind: "summary" as const, view, coverage: pageViewCoverage(0, bindings.length, report.bindings.length), summary: { @@ -152,6 +170,8 @@ export const projectAndroidJniView = ( ), }, }; + if (overBudget(summary)) return budgetError(); + return ok(summary); } else { const indices = view.indices === undefined ? undefined : new Set(view.indices); @@ -240,9 +260,9 @@ export const projectAndroidJniView = ( library_inventory: report.library_inventory, selection: report.selection, }; - result = { + const page = { ...shared, - kind: "android-jni", + kind: "android-jni" as const, view, source, items: androidJniViewItemsSchema.parse(selected.rows), @@ -252,19 +272,7 @@ export const projectAndroidJniView = ( selected.total, ), }; + if (overBudget(page)) return budgetError(); + return ok(page); } - if ( - jsonValueByteLength(result as unknown as JsonValue, 1024 * 1024 - 128) > - 1024 * 1024 - 128 - ) - return err( - new AnalysisResourceConstraintError( - "inspect_analysis_view", - "transport", - "JNI view exceeds its 1 MiB serialized allowance.", - { parent_evidence_id: parent.evidenceId, limit_bytes: 1024 * 1024 }, - ANALYSIS_VIEW_PAGE_BUDGET_RECOVERY, - ), - ); - return ok(result); }; diff --git a/src/domain/analysisView/androidPackageView.ts b/src/domain/analysisView/androidPackageView.ts index e4a029ed4a..ec6809186d 100644 --- a/src/domain/analysisView/androidPackageView.ts +++ b/src/domain/analysisView/androidPackageView.ts @@ -11,11 +11,13 @@ import { jsonValueByteLength } from "../jsonValueByteLength.js"; import type { JsonValue } from "../jsonValue.js"; import { err, ok, type Result } from "../result.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { androidViewRequestSchema } from "../android/androidPackageQuery.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -106,8 +108,8 @@ const choose = ( /** Project authenticated retained facts without reopening the APK or engine. */ export const projectAndroidPackageView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "android") return err( analysisViewInputError([ @@ -119,6 +121,9 @@ export const projectAndroidPackageView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "android"); if (parent.operation !== "inspect_android_package") return err( analysisViewInputError([ @@ -166,7 +171,7 @@ export const projectAndroidPackageView = ( if (view.kind === "summary") { const { text, ...manifest } = report.manifest; return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -174,7 +179,7 @@ export const projectAndroidPackageView = ( manifest: { ...manifest, text_code_units: text.length, - text_included: false, + text_included: false as const, }, }, coverage: completeWithinViewCoverage(1, 1), @@ -189,7 +194,7 @@ export const projectAndroidPackageView = ( ); if (!page.ok) return page; return ok({ - kind: "android", + kind: "android" as const, view, ...shared, item: { @@ -295,10 +300,10 @@ export const projectAndroidPackageView = ( ]++; summary.declaration_coverage[row.declaration_coverage]++; } - const result: UnsignedAnalysisView = { + const result = { ...context, - kind: "android", - facet: "component-summary", + kind: "android" as const, + facet: "component-summary" as const, view, summary, coverage: completeWithinViewCoverage(rows.length, rows.length), @@ -365,10 +370,10 @@ export const projectAndroidPackageView = ( bytes += added; items.push(item); } - const result: UnsignedAnalysisView = { + const result = { ...context, - kind: "android", - facet: "components", + kind: "android" as const, + facet: "components" as const, view, items, byte_limited, diff --git a/src/domain/analysisView/androidSymbolView.test.ts b/src/domain/analysisView/androidSymbolView.test.ts index 32397d1a06..72c38013f0 100644 --- a/src/domain/analysisView/androidSymbolView.test.ts +++ b/src/domain/analysisView/androidSymbolView.test.ts @@ -1,4 +1,6 @@ import { expect, it, vi } from "vitest"; +import { z } from "zod"; +import { androidComponentsViewRequestSchema } from "../android/androidPackageQuery.js"; import { createEvidence } from "../evidence.js"; import { immutableJsonSnapshotMember } from "../immutableJson.js"; import { @@ -7,11 +9,18 @@ import { projectAnalysisView, type AnalysisViewParent, } from "./analysisView.js"; +import type { AdmittedView } from "./analysisViewShape.js"; import { androidClassSummarySchema, - projectAndroidSymbolSummary, + projectAndroidSymbolSummary as projectAdmittedAndroidSymbolSummary, } from "./androidSymbolView.js"; +const projectAndroidSymbolSummary = ( + parent: Parameters[0], + view: z.input, +): ReturnType => + projectAdmittedAndroidSymbolSummary(parent, view satisfies AdmittedView); + type Operation = "inspect_android_class" | "inspect_android_method"; const engine = { name: "jadx", diff --git a/src/domain/analysisView/androidSymbolView.ts b/src/domain/analysisView/androidSymbolView.ts index 688d7b8401..3a39270ecf 100644 --- a/src/domain/analysisView/androidSymbolView.ts +++ b/src/domain/analysisView/androidSymbolView.ts @@ -1,14 +1,14 @@ -import type { AnalysisError } from "../analysisErrorBase.js"; import { AnalysisResourceConstraintError } from "../analysisErrorCore.js"; import { androidResultSchemas } from "../android/androidAnalysis.js"; import type { JsonValue } from "../jsonValue.js"; import { jsonValueByteLength } from "../jsonValueByteLength.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -27,9 +27,9 @@ const PAGE_BYTES = 1024 * 1024; const DIGEST_BYTES = jsonValueByteLength({ view_digest: "0".repeat(64) }) - 1; const PROJECTION_BYTES = PAGE_BYTES - DIGEST_BYTES; -const boundedSummary = ( - result: UnsignedAnalysisView, -): Result => +const boundedSummary = ( + result: View, +) => jsonValueByteLength(result as unknown as JsonValue, PROJECTION_BYTES) > PROJECTION_BYTES ? err( @@ -53,9 +53,10 @@ const boundedSummary = ( /** Reuse authenticated Android facts without reopening the APK, mapping or engine. */ export const projectAndroidSymbolSummary = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary") + admitted: AdmittedView, +) => { + const view = ownedView(admitted, "summary"); + if (view === undefined) return err( analysisViewInputError([ { @@ -115,7 +116,7 @@ export const projectAndroidSymbolSummary = ( if (!parsed.ok) return parsed; return boundedSummary({ ...shared, - parent_operation: "inspect_android_class", + parent_operation: "inspect_android_class" as const, summary: parsed.value, }); } @@ -123,7 +124,7 @@ export const projectAndroidSymbolSummary = ( if (!parsed.ok) return parsed; return boundedSummary({ ...shared, - parent_operation: "inspect_android_method", + parent_operation: "inspect_android_method" as const, summary: parsed.value, unknowns: [ ...shared.unknowns, diff --git a/src/domain/analysisView/apiSurfaceSchema.ts b/src/domain/analysisView/apiSurfaceSchema.ts new file mode 100644 index 0000000000..b788e95ab5 --- /dev/null +++ b/src/domain/analysisView/apiSurfaceSchema.ts @@ -0,0 +1,67 @@ +import { z } from "zod"; +import { ROUTE_RULES } from "./webNetworkRouteTemplates.js"; + +export const apiSurfaceViewSchema = z.strictObject({ + kind: z.literal("api-surface"), + offset: z.int().nonnegative().default(0), + limit: z.int().positive().default(50), + include_query_parameter_names: z + .boolean() + .optional() + .describe( + "Include distinct observed query parameter names and their original record ordinals; names do not establish required parameters or a complete API schema.", + ), +}); +const ruleSchema = z.enum(ROUTE_RULES); +const groupSchema = z.strictObject({ + method: z.string(), + origin: z.string(), + path_template: z.string(), + templated_segments: z.array( + z.strictObject({ + segment_index: z.int().nonnegative(), + rule: ruleSchema, + basis: z.literal("inferred"), + observed_values: z.array(z.string()), + }), + ), + record_ordinals: z.array(z.int().nonnegative()), + statuses: z.array(z.number()), + content_types: z.array(z.string()), + query_parameter_names: z + .array( + z.strictObject({ + name: z.string(), + record_ordinals: z.array(z.int().nonnegative()), + }), + ) + .optional(), + flags: z.array( + z.enum(["single-sample", "mixed-statuses", "mixed-content-types"]), + ), +}); +export const apiSurfaceFields = { + records: z.strictObject({ + examined: z.int().nonnegative(), + total: z.int().nonnegative(), + excluded: z.int().nonnegative(), + }), + templated_groups: z + .int() + .nonnegative() + .describe( + "Groups across every page that carry at least one templated segment.", + ), + groups: z.array(groupSchema), + excluded_records: z.array( + z.strictObject({ + ordinal: z.int().nonnegative(), + reason: z.enum([ + "url-redacted", + "url-unparseable", + "request-unavailable", + "method-unavailable", + ]), + }), + ), +}; diff --git a/src/domain/analysisView/apkSignatureView.ts b/src/domain/analysisView/apkSignatureView.ts index 8172766d2e..812c3cf2c7 100644 --- a/src/domain/analysisView/apkSignatureView.ts +++ b/src/domain/analysisView/apkSignatureView.ts @@ -9,17 +9,18 @@ import { import { apkSignatureSchemeSchema, apkSignatureViewItemsSchema, - type apkSignatureViewRequestSchema, + apkSignatureViewRequestSchema, } from "../apkSignature/apkSignatureQuery.js"; import { isImmutableJsonSnapshot } from "../immutableJson.js"; import type { JsonValue } from "../jsonValue.js"; import { err, ok, type Result } from "../result.js"; import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { @@ -263,8 +264,8 @@ function* records( export const projectApkSignatureView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "apk-signature") return err( analysisViewInputError([ @@ -276,6 +277,9 @@ export const projectApkSignatureView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "apk-signature"); const parsed = read(parent); if (!parsed.ok) return parsed; const { report, summary } = parsed.value; @@ -297,7 +301,7 @@ export const projectApkSignatureView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary, @@ -324,7 +328,7 @@ export const projectApkSignatureView = ( items.push(item); } return ok({ - kind: "apk-signature", + kind: "apk-signature" as const, view, ...shared, source_coverage: summary.source_coverage, diff --git a/src/domain/analysisView/artifactInventoryView.test.ts b/src/domain/analysisView/artifactInventoryView.test.ts index fc510639e4..4323daebd5 100644 --- a/src/domain/analysisView/artifactInventoryView.test.ts +++ b/src/domain/analysisView/artifactInventoryView.test.ts @@ -100,8 +100,7 @@ const page = (source: AnalysisViewParent, view: unknown) => { artifactInventoryViewRequestSchema.parse(view), ); if (!result.ok) throw result.error; - if (result.value.kind !== "inventory") - throw new Error("Expected an inventory page"); + if (!("items" in result.value)) throw new Error("Expected an inventory page"); return result.value; }; afterEach(() => vi.restoreAllMocks()); diff --git a/src/domain/analysisView/artifactInventoryView.ts b/src/domain/analysisView/artifactInventoryView.ts index d0b8773edb..f3608826ef 100644 --- a/src/domain/analysisView/artifactInventoryView.ts +++ b/src/domain/analysisView/artifactInventoryView.ts @@ -27,11 +27,12 @@ import { type InventorySet, } from "../artifactInventoryEvidence.js"; import type { ArtifactInspectionResult } from "../artifactInspection.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -231,8 +232,8 @@ const sourceFailure = ( /** Project exact source records; exhausted pages cover available records, not runtime behavior. */ export const projectArtifactInventoryView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { const operation = parent.operation; if (operation !== "inventory_artifact" && operation !== "inspect_artifact") return err( @@ -248,6 +249,9 @@ export const projectArtifactInventoryView = ( "Artifact Evidence supports summary and inventory views.", ), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "inventory"); const parsed = parseSource(parent); if (!parsed.ok) return parsed; const source = parsed.value; @@ -301,22 +305,21 @@ export const projectArtifactInventoryView = ( "Parent inventory is partial; counts and exhausted pages cover only available records. Missing matches do not establish absence.", ]), ], - } satisfies Pick< - UnsignedAnalysisView, - | "parent_evidence_id" - | "parent_operation" - | "parent_digest" - | "artifact" - | "limitations" - | "unknowns" - >; + } satisfies { + parent_evidence_id: string; + parent_operation: "inspect_artifact" | "inventory_artifact"; + parent_digest: string; + artifact: { path: string; sha256: string }; + limitations: readonly string[]; + unknowns: readonly string[]; + }; if (view.kind === "summary") { const examined = inventory.nodes.length + inventory.occurrences.length + inventory.edges.length; return ok({ - kind: "summary", + kind: "summary" as const, view, summary: { manifest: inventory.manifest, @@ -373,7 +376,7 @@ export const projectArtifactInventoryView = ( : inventory.integrityContradictions.length, }; return ok({ - kind: "inventory", + kind: "inventory" as const, view, manifest: inventory.manifest, inventory_evidence_ids: [...evidenceIds], @@ -406,7 +409,7 @@ const occurrencePage = (source: InventorySource, view: OccurrenceView) => { const nodePage = ( source: InventorySource, view: Extract< - AnalysisViewRequest, + z.output, { kind: "inventory"; collection: "nodes" } >, ) => { @@ -451,7 +454,7 @@ const inventoryCounts = (source: InventorySource): InventoryCounts => { }; type OccurrenceView = Extract< - AnalysisViewRequest, + z.output, { kind: "inventory"; collection: "occurrences" } >; diff --git a/src/domain/analysisView/binaryLayoutView.ts b/src/domain/analysisView/binaryLayoutView.ts index b4b7865ff4..f3d38e7aec 100644 --- a/src/domain/analysisView/binaryLayoutView.ts +++ b/src/domain/analysisView/binaryLayoutView.ts @@ -5,12 +5,15 @@ import { import type { AnalysisError } from "../analysisErrorBase.js"; import type { BinaryLayout } from "../native/binaryLayout.js"; import { err, ok, type Result } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, - GroupingViewKind, -} from "./analysisView.js"; + AdmittedView, + FacetAnalysisView, + ItemAnalysisView, + PageAnalysisView, + SummaryAnalysisView, +} from "./analysisViewShape.js"; +import { assertOwnedView } from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage as completeCoverage, @@ -171,8 +174,8 @@ const layoutSummary = (layout: BinaryLayout) => ({ export const projectBinaryLayoutView = ( parent: AnalysisViewParent, layout: BinaryLayout, - view: Exclude, -): Result => { + view: AdmittedView, +) => { const shared = parentFields(parent, layout); if (view.kind === "native") return err( @@ -190,9 +193,10 @@ export const projectBinaryLayoutView = ( return err( layoutIncompatible("EVM views require inspect_evm_interface Evidence."), ); - if (view.kind === "summary") + if (view.kind === "summary") { + assertOwnedView(view, "summary"); return ok({ - kind: "summary", + kind: "summary" as const, view, summary: layoutSummary(layout), coverage: completeCoverage( @@ -207,15 +211,19 @@ export const projectBinaryLayoutView = ( ), ...shared, }); - if (view.kind === "facet") + } + if (view.kind === "facet") { + assertOwnedView(view, "facet"); return ok({ - kind: "facet", + kind: "facet" as const, view, facet: view.facet === "mitigations" ? layout.mitigations : layout.linkage, coverage: completeCoverage(1, 1), ...shared, }); + } if (view.kind === "item") { + assertOwnedView(view, "item"); if (view.collection === "modules") return err( layoutIncompatible( @@ -228,7 +236,7 @@ export const projectBinaryLayoutView = ( : selectLayoutItem(view.collection, layout.symbols, view.selector); if (!selected.ok) return selected; return ok({ - kind: "item", + kind: "item" as const, view, item: selected.value, coverage: completeCoverage( @@ -246,6 +254,7 @@ export const projectBinaryLayoutView = ( "Layout views require summary, facet, item or page selections.", ), ); + assertOwnedView(view, "page"); if (view.collection === "modules") return err( layoutIncompatible( @@ -259,7 +268,7 @@ export const projectBinaryLayoutView = ( ? pageRows(layout.sections, view.offset, view.limit) : pageRows(layout.symbols, view.offset, view.limit); return ok({ - kind: "page", + kind: "page" as const, view, items: [...items], coverage: pageCoverage(view.offset, items.length, rows.length), @@ -270,7 +279,7 @@ export const projectBinaryLayoutView = ( const selectLayoutItem = ( collection: "sections" | "symbols", rows: readonly Row[], - selector: Extract["selector"], + selector: ItemAnalysisView["selector"], ): Result => { if ("index" in selector) return selectIndexed(collection, rows, selector.index); diff --git a/src/domain/analysisView/browserScenarioView.ts b/src/domain/analysisView/browserScenarioView.ts index a64363a275..b2df96a119 100644 --- a/src/domain/analysisView/browserScenarioView.ts +++ b/src/domain/analysisView/browserScenarioView.ts @@ -6,7 +6,7 @@ import { } from "../browserScenarioCapture.js"; import type { BrowserScenarioStep as Step } from "../browserScenarioCaptureValues.js"; import { compareAsciiStrings } from "../canonicalOrdering.js"; -import { err, ok, type Result } from "../result.js"; +import { err, ok } from "../result.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { completeWithinViewCoverage, @@ -14,11 +14,12 @@ import { type AnalysisViewCoverage, } from "./analysisViewCoverage.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { ARTIFACT_SECTIONS, stepRowSchema, @@ -314,10 +315,15 @@ const pageRecords = ( /** Project retained scenario Evidence without relaunching the browser or replaying actions. */ export const projectBrowserScenarioView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "browser-scenario") return err(unsupportedView()); + assertOwnedView( + view, + "summary", + "browser-scenario", + ); const parsed = readCapture(parent); if (!parsed.ok) return parsed; const capture = parsed.value; @@ -339,7 +345,7 @@ export const projectBrowserScenarioView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -371,7 +377,7 @@ export const projectBrowserScenarioView = ( ]), ); return ok({ - kind: "browser-scenario", + kind: "browser-scenario" as const, view, ...shared, source_completeness: capture.completeness, diff --git a/src/domain/analysisView/byteEntropyView.ts b/src/domain/analysisView/byteEntropyView.ts index c00e15a8a1..ae04201a6e 100644 --- a/src/domain/analysisView/byteEntropyView.ts +++ b/src/domain/analysisView/byteEntropyView.ts @@ -1,13 +1,13 @@ import { z } from "zod"; import { AnalysisInputError } from "../analysisErrorCore.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { byteEntropySchema, type ByteEntropy } from "../native/byteEntropy.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage } from "./analysisViewCoverage.js"; export const byteEntropySummarySchema = byteEntropySchema @@ -22,8 +22,8 @@ export const byteEntropySummarySchema = byteEntropySchema export const projectByteEntropyView = ( parent: AnalysisViewParent, report: ByteEntropy, - view: Exclude, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary") return err( new AnalysisInputError("inspect_analysis_view", undefined, [ @@ -35,11 +35,12 @@ export const projectByteEntropyView = ( }, ]), ); + assertOwnedView(view, "summary"); return ok({ - kind: "summary", + kind: "summary" as const, view, parent_evidence_id: parent.evidenceId, - parent_operation: "inspect_byte_entropy", + parent_operation: "inspect_byte_entropy" as const, parent_digest: parent.evidenceId.slice(3), artifact: { path: report.artifact.path, sha256: report.artifact.sha256 }, summary: { @@ -61,6 +62,6 @@ export const projectByteEntropyView = ( limitations: [ ...new Set([...parent.limitations, ...report.limitations]), ].sort(), - unknowns: [], + unknowns: [] as string[], }); }; diff --git a/src/domain/analysisView/commandObservationView.ts b/src/domain/analysisView/commandObservationView.ts index 6779a7255e..19d5482d88 100644 --- a/src/domain/analysisView/commandObservationView.ts +++ b/src/domain/analysisView/commandObservationView.ts @@ -1,5 +1,4 @@ import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { commandObservationSchema, gdbCommandResultSchema, @@ -8,12 +7,13 @@ import { digestSchema } from "../digests.js"; import { providerSchema } from "../evidence.js"; import { analysisInputErrorFromIssues } from "../inputIssueProjection.js"; import { jsonValueSchema } from "../jsonValue.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -42,9 +42,10 @@ export const gdbCommandSummarySchema = gdbCommandResultSchema /** Select existing owner facts without parsing a command or its output protocol. */ export const projectCommandObservationView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary") + admitted: AdmittedView, +) => { + const view = ownedView(admitted, "summary"); + if (view === undefined) return err( analysisViewInputError([ { @@ -136,7 +137,7 @@ export const projectCommandObservationView = ( const { console, target, log, ...records } = parsed.value; return ok({ ...shared, - parent_operation: "gdb_console", + parent_operation: "gdb_console" as const, summary: { ...records, available_counts: { @@ -170,7 +171,7 @@ export const projectCommandObservationView = ( ); return ok({ ...shared, - parent_operation: "inspect_with_objdump", + parent_operation: "inspect_with_objdump" as const, summary: report, }); }; diff --git a/src/domain/analysisView/dartAotView.ts b/src/domain/analysisView/dartAotView.ts index 83625736f0..d1c196bf24 100644 --- a/src/domain/analysisView/dartAotView.ts +++ b/src/domain/analysisView/dartAotView.ts @@ -1,14 +1,14 @@ import { analysisViewInputError } from "./analysisViewErrors.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { flutterResultSchemas } from "../flutter/flutterBuildAnalysis.js"; -import { err, ok, type Result } from "../result.js"; +import { err, ok } from "../result.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -47,9 +47,12 @@ export const dartAotViewContextSchema = z.strictObject({ /** Reuse authenticated AOT Evidence without opening the APK or rescanning its ELF. */ export const projectDartAotView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "dart-aot") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "dart-aot"); + if (view === undefined) return err( analysisViewInputError([ { @@ -90,7 +93,7 @@ export const projectDartAotView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { ...report, string_pool }, @@ -99,7 +102,7 @@ export const projectDartAotView = ( const collection = report.string_pool[view.collection]; const items = collection.slice(view.offset, view.offset + view.limit); return ok({ - kind: "dart-aot", + kind: "dart-aot" as const, view, ...shared, items, diff --git a/src/domain/analysisView/desktopApplicationView.ts b/src/domain/analysisView/desktopApplicationView.ts index a179baf873..3be4848187 100644 --- a/src/domain/analysisView/desktopApplicationView.ts +++ b/src/domain/analysisView/desktopApplicationView.ts @@ -16,13 +16,13 @@ import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { ok, err, type Result } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; +import { ok, err } from "../result.js"; // Bound diagnostic context independently of the retained report size. Previews // are display values; stable file IDs select the original paths and all issues. @@ -146,9 +146,12 @@ type DesktopViewRow = DesktopApplication[DesktopCollection][number]; const validatedParents = new WeakSet(); export const projectDesktopApplicationView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "desktop-application") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "desktop-application"); + if (view === undefined) return err( analysisViewInputError([ { @@ -272,7 +275,7 @@ export const projectDesktopApplicationView = ( else group.count++; } return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -342,7 +345,7 @@ export const projectDesktopApplicationView = ( ), ); return ok({ - kind: "desktop-application", + kind: "desktop-application" as const, view, ...shared, source_coverage: report.coverage, diff --git a/src/domain/analysisView/devicetreeView.ts b/src/domain/analysisView/devicetreeView.ts index c27e1a12ed..54232e38f4 100644 --- a/src/domain/analysisView/devicetreeView.ts +++ b/src/domain/analysisView/devicetreeView.ts @@ -1,12 +1,12 @@ import { z } from "zod"; import { devicetreeSchema } from "../firmware/devicetree.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -57,8 +57,8 @@ export const devicetreePageContextSchema = devicetreeSchema const readReport = createAnalysisViewResultReader(devicetreeSchema); export const projectDevicetreeView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { const invalid = (message: string) => err( analysisViewInputError([ @@ -69,6 +69,9 @@ export const projectDevicetreeView = ( return invalid( "Devicetree Evidence supports summary and devicetree views.", ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "devicetree"); const parsed = readReport(parent); if (!parsed.ok) return parsed; const r = parsed.value; @@ -99,7 +102,7 @@ export const projectDevicetreeView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary: { ...context, summary: r.summary }, coverage: completeWithinViewCoverage(r.nodes.length, r.nodes.length), @@ -148,7 +151,7 @@ export const projectDevicetreeView = ( const { items, total } = selected; return ok({ ...shared, - kind: "devicetree", + kind: "devicetree" as const, view, devicetree: { ...context, alias_count: r.summary.aliases.length }, items, diff --git a/src/domain/analysisView/environmentCoverageView.ts b/src/domain/analysisView/environmentCoverageView.ts index 40cca47794..4cd86896d4 100644 --- a/src/domain/analysisView/environmentCoverageView.ts +++ b/src/domain/analysisView/environmentCoverageView.ts @@ -1,11 +1,6 @@ import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; import { templateRulesSchema } from "./environmentManifestView.js"; import type { StateView } from "./environmentStateRules.js"; import { @@ -154,18 +149,18 @@ export const summarizeEnvironmentCoverage = (state: { /** Project the state an environment would serve and summarize which tools it answers from that state. */ export const projectEnvironmentCoverageView = ( parent: AnalysisViewParent, - view: Extract, + view: z.output, accumulator = createEnvironmentStateAccumulator(view), -): Result => { +) => { const projected = projectEnvironmentStateView( parent, - { kind: "environment-state", template_rules: view.template_rules }, + { kind: "environment-state" as const, template_rules: view.template_rules }, accumulator, ); if (!projected.ok) return projected; const state = projected.value; return ok({ - kind: "environment-coverage", + kind: "environment-coverage" as const, view, parent_evidence_id: state.parent_evidence_id, parent_operation: state.parent_operation, diff --git a/src/domain/analysisView/environmentManifestSchema.ts b/src/domain/analysisView/environmentManifestSchema.ts new file mode 100644 index 0000000000..9abea82b90 --- /dev/null +++ b/src/domain/analysisView/environmentManifestSchema.ts @@ -0,0 +1,90 @@ +import { z } from "zod"; +import { jsonRecordSchema } from "../jsonRecord.js"; +import { TEMPLATE_RULES } from "./environmentManifestRules.js"; +import { ROUTE_RULES } from "./webNetworkRouteTemplates.js"; + +const manifestRuleSchema = z.enum([...ROUTE_RULES, ...TEMPLATE_RULES]); +const jsonTypeNameSchema = z.enum([ + "string", + "number", + "boolean", + "object", + "array", + "null", +]); +const toolSchema = z.strictObject({ + name: z.string(), + method: z.string(), + path_template: z.string(), + api_surface_template: z + .string() + .describe("Four-rule template of the tool's earliest record."), + params: z.array( + z.strictObject({ + index: z.number().int().nonnegative(), + name: z.string(), + rule: manifestRuleSchema, + basis: z.literal("inferred"), + observed_values: z.array(z.string()), + }), + ), + query_parameter_names: z.array(z.string()), + body_shape: z + .strictObject({ + type: z.literal("object"), + properties: jsonRecordSchema(jsonTypeNameSchema), + }) + .nullable(), + statuses: z.array(z.number()), + content_types: z.array(z.string()), + record_ordinals: z.array(z.number().int().nonnegative()), +}); +export const environmentManifestFields = { + origin: z + .string() + .describe("Primary origin: the origin with the most JSON-like records."), + name: z + .string() + .describe( + "Kebab-case environment name derived from the primary origin host.", + ), + tools: z.array(toolSchema), + records: z + .array( + z.strictObject({ + ordinal: z.number().int().nonnegative(), + method: z.string(), + path: z.string(), + status: z.number().nullable(), + content_type: z.string().nullable(), + }), + ) + .describe( + "Pointers to the retained parent records cited by tools; no bodies.", + ), + excluded: z.array( + z.strictObject({ + method: z.string(), + origin: z.string(), + path_template: z.string(), + reason: z.enum(["other-origin", "ui-page-or-asset", "non-json"]), + }), + ), + unknowns: z.array( + z.strictObject({ + kind: z.enum([ + "authorization-model", + "response-semantics", + "state-transition", + ]), + statement: z.string(), + }), + ), + templated_groups: z + .number() + .int() + .nonnegative() + .describe( + "Tools and excluded groups that carry at least one templated segment.", + ), +}; diff --git a/src/domain/analysisView/environmentManifestView.ts b/src/domain/analysisView/environmentManifestView.ts index 9dcd88f8f4..cabf1085d4 100644 --- a/src/domain/analysisView/environmentManifestView.ts +++ b/src/domain/analysisView/environmentManifestView.ts @@ -1,15 +1,11 @@ import { z } from "zod"; -import { jsonRecordSchema } from "../jsonRecord.js"; import type { WebNetworkCaptureRecord } from "../webNetworkCapture.js"; import { AnalysisUnsupportedTargetError } from "../analysisErrorCore.js"; import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { ownedView, type AdmittedView } from "./analysisViewShape.js"; import { EnvironmentManifestAccumulator } from "./EnvironmentManifestAccumulator.js"; import { TEMPLATE_RULES, @@ -20,7 +16,9 @@ import { admitScenarioCaptureParent, type ScenarioResponseBodyRetention, } from "./scenarioCaptureRecords.js"; -import { ROUTE_RULES } from "./webNetworkRouteTemplates.js"; +import { environmentManifestFields } from "./environmentManifestSchema.js"; + +export { environmentManifestFields }; /** Opt-in template rules, each listed at most once; shared by every view that groups tools. */ export const templateRulesSchema = z @@ -44,92 +42,6 @@ export const environmentManifestViewRequestSchema = z.strictObject({ ), }); -const manifestRuleSchema = z.enum([...ROUTE_RULES, ...TEMPLATE_RULES]); -const jsonTypeNameSchema = z.enum([ - "string", - "number", - "boolean", - "object", - "array", - "null", -]); -const toolSchema = z.strictObject({ - name: z.string(), - method: z.string(), - path_template: z.string(), - api_surface_template: z - .string() - .describe("Four-rule template of the tool's earliest record."), - params: z.array( - z.strictObject({ - index: z.number().int().nonnegative(), - name: z.string(), - rule: manifestRuleSchema, - basis: z.literal("inferred"), - observed_values: z.array(z.string()), - }), - ), - query_parameter_names: z.array(z.string()), - body_shape: z - .strictObject({ - type: z.literal("object"), - properties: jsonRecordSchema(jsonTypeNameSchema), - }) - .nullable(), - statuses: z.array(z.number()), - content_types: z.array(z.string()), - record_ordinals: z.array(z.number().int().nonnegative()), -}); -export const environmentManifestFields = { - origin: z - .string() - .describe("Primary origin: the origin with the most JSON-like records."), - name: z - .string() - .describe( - "Kebab-case environment name derived from the primary origin host.", - ), - tools: z.array(toolSchema), - records: z - .array( - z.strictObject({ - ordinal: z.number().int().nonnegative(), - method: z.string(), - path: z.string(), - status: z.number().nullable(), - content_type: z.string().nullable(), - }), - ) - .describe( - "Pointers to the retained parent records cited by tools; no bodies.", - ), - excluded: z.array( - z.strictObject({ - method: z.string(), - origin: z.string(), - path_template: z.string(), - reason: z.enum(["other-origin", "ui-page-or-asset", "non-json"]), - }), - ), - unknowns: z.array( - z.strictObject({ - kind: z.enum([ - "authorization-model", - "response-semantics", - "state-transition", - ]), - statement: z.string(), - }), - ), - templated_groups: z - .number() - .int() - .nonnegative() - .describe( - "Tools and excluded groups that carry at least one templated segment.", - ), -}; - /** The records, coverage and identity a manifest projects from, for either parent kind. */ export interface CaptureParent { readonly operation: @@ -227,28 +139,36 @@ const addCaptureRecords = ( /** Create the manifest budget with its selected query names and template rules. */ export const createEnvironmentManifestAccumulator = ( - view: AnalysisViewRequest, -): EnvironmentManifestAccumulator => - view.kind === "environment-manifest" - ? new EnvironmentManifestAccumulator( + view: AdmittedView, +): EnvironmentManifestAccumulator => { + const selected = ownedView< + z.output + >(view, "environment-manifest"); + return selected === undefined + ? new EnvironmentManifestAccumulator() + : new EnvironmentManifestAccumulator( undefined, - view.include_query_parameter_names, - view.template_rules, - ) - : new EnvironmentManifestAccumulator(); + selected.include_query_parameter_names, + selected.template_rules, + ); +}; /** Project retained request lines, from a HAR or a browser scenario, into a replayable tool surface; templates are inferences. */ export const projectEnvironmentManifestView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, - accumulator = createEnvironmentManifestAccumulator(view), -): Result => { - if (view.kind !== "environment-manifest") + admitted: AdmittedView, + accumulator = createEnvironmentManifestAccumulator(admitted), +) => { + const view = ownedView>( + admitted, + "environment-manifest", + ); + if (view === undefined) return err( new AnalysisUnsupportedTargetError( "inspect_analysis_view", parent.evidenceId, - `View ${view.kind} is unsupported for parent operation ${parent.operation}; environment-manifest requires inspect_web_network_capture or capture_browser_scenario.`, + `View ${admitted.kind} is unsupported for parent operation ${parent.operation}; environment-manifest requires inspect_web_network_capture or capture_browser_scenario.`, ), ); const grouped = groupCaptureRecords(parent, view.kind, view.template_rules, { @@ -265,7 +185,7 @@ export const projectEnvironmentManifestView = ( const manifest = accumulator.finish(); if (!manifest.ok) return manifest; return ok({ - kind: "environment-manifest", + kind: "environment-manifest" as const, view, parent_evidence_id: parent.evidenceId, parent_operation: capture.operation, diff --git a/src/domain/analysisView/environmentStateView.ts b/src/domain/analysisView/environmentStateView.ts index 82e0f0fb32..044dd91931 100644 --- a/src/domain/analysisView/environmentStateView.ts +++ b/src/domain/analysisView/environmentStateView.ts @@ -1,13 +1,8 @@ import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js"; import { jsonRecordSchema } from "../jsonRecord.js"; -import { ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; import { EnvironmentStateAccumulator } from "./EnvironmentStateAccumulator.js"; import { DELETED_FLAGS } from "./environmentStateRules.js"; import { isClockZone } from "./environmentStateWriteValues.js"; @@ -558,23 +553,17 @@ export const environmentStateFields = { }; /** State extraction and coverage share the same budget and template-rule policy. */ -export const createEnvironmentStateAccumulator = ( - view: Extract< - AnalysisViewRequest, - { kind: "environment-state" | "environment-coverage" } - >, -): EnvironmentStateAccumulator => +export const createEnvironmentStateAccumulator = (view: { + readonly template_rules: z.output; +}): EnvironmentStateAccumulator => new EnvironmentStateAccumulator(undefined, view.template_rules); /** Extract the init state a capture's reads observed and each read tool's render plan; types and identity are inferences. */ export const projectEnvironmentStateView = ( parent: AnalysisViewParent, - view: Extract, + view: z.output, accumulator = createEnvironmentStateAccumulator(view), -): Result< - Extract, - AnalysisError -> => { +) => { const grouped = groupCaptureRecords(parent, view.kind, view.template_rules, { accumulator, noun: "state", @@ -586,7 +575,7 @@ export const projectEnvironmentStateView = ( const state = accumulator.finishState(); if (!state.ok) return state; return ok({ - kind: "environment-state", + kind: "environment-state" as const, view, parent_evidence_id: parent.evidenceId, parent_operation: grouped.value.operation, diff --git a/src/domain/analysisView/erlangBeamView.ts b/src/domain/analysisView/erlangBeamView.ts index e2e25c2939..7f14f88ee2 100644 --- a/src/domain/analysisView/erlangBeamView.ts +++ b/src/domain/analysisView/erlangBeamView.ts @@ -1,12 +1,12 @@ import { z } from "zod"; import { erlangBeamSchema, type ErlangBeam } from "../erlang/beam.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -165,9 +165,12 @@ const selectRows = (rows: readonly Row[] | null, view: BeamView) => { /** Project retained BEAM facts without reopening files or reinterpreting chunks. */ export const projectErlangBeamView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "beam") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "beam"); + if (view === undefined) return err( analysisViewInputError([ { @@ -215,7 +218,7 @@ export const projectErlangBeamView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary, coverage: completeWithinViewCoverage(chunks.length, chunks.length), @@ -223,7 +226,7 @@ export const projectErlangBeamView = ( const selected = selectRows(parsed.value[view.collection], view); return ok({ ...shared, - kind: "beam", + kind: "beam" as const, view, beam: summary, page: { collection: view.collection, items: selected.rows }, diff --git a/src/domain/analysisView/evmInterfaceView.ts b/src/domain/analysisView/evmInterfaceView.ts index 246e525a0f..9a5148aa0a 100644 --- a/src/domain/analysisView/evmInterfaceView.ts +++ b/src/domain/analysisView/evmInterfaceView.ts @@ -1,15 +1,15 @@ import { analysisViewInputError } from "./analysisViewErrors.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import { evmInterfaceSchema } from "../evm/evmInterface.js"; -import { err, ok, type Result } from "../result.js"; +import { err, ok } from "../result.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -51,9 +51,12 @@ export const evmSummarySchema = z.strictObject({ /** Select already authenticated producer facts; no interpreter or provider is invoked. */ export const projectEvmInterfaceView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "evm") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "evm"); + if (view === undefined) return err( analysisViewInputError([ { @@ -96,7 +99,7 @@ export const projectEvmInterfaceView = ( const { hex: _hex, ...bytecode } = report.bytecode; const { stdout, ...diagnostics } = report.diagnostics; return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -118,7 +121,7 @@ export const projectEvmInterfaceView = ( if (view.facet === "functions") { const item = report.functions.slice(view.offset, view.offset + view.limit); return ok({ - kind: "evm", + kind: "evm" as const, view, item, ...shared, @@ -134,5 +137,7 @@ export const projectEvmInterfaceView = ( ? report.bytecode.hex : report.diagnostics[view.facet]; const page = analysisTextPage(text, view.offset, view.limit, view.facet); - return page.ok ? ok({ kind: "evm", view, ...page.value, ...shared }) : page; + return page.ok + ? ok({ kind: "evm" as const, view, ...page.value, ...shared }) + : page; }; diff --git a/src/domain/analysisView/fridaSessionStatusView.ts b/src/domain/analysisView/fridaSessionStatusView.ts index 87ee04b696..b2bf3989cb 100644 --- a/src/domain/analysisView/fridaSessionStatusView.ts +++ b/src/domain/analysisView/fridaSessionStatusView.ts @@ -1,13 +1,13 @@ import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { providerSchema } from "../evidence.js"; import { fridaSessionStatusSchema } from "../fridaSessionStatus.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -27,9 +27,10 @@ export const fridaSessionStatusViewContext = { /** Summarize captured facts without interpreting caller-authored message payloads. */ export const projectFridaSessionStatusView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary") + admitted: AdmittedView, +) => { + const view = ownedView(admitted, "summary"); + if (view === undefined) return err( analysisViewInputError([ { @@ -60,11 +61,11 @@ export const projectFridaSessionStatusView = ( ); const { messages, ...status } = report.value; return ok({ - kind: "summary", + kind: "summary" as const, view, parent_evidence_id: parent.evidenceId, parent_digest: parent.evidenceId.slice(3), - parent_operation: "frida_session_status", + parent_operation: "frida_session_status" as const, artifact: null, source_provider: parent.provider ?? null, source_parameters: parameters.data, diff --git a/src/domain/analysisView/goBinaryView.ts b/src/domain/analysisView/goBinaryView.ts index 83e2510a07..54e11cfb09 100644 --- a/src/domain/analysisView/goBinaryView.ts +++ b/src/domain/analysisView/goBinaryView.ts @@ -1,19 +1,19 @@ import { binaryMetadataArchitecture } from "../binaryMetadataArchitecture.js"; import { metadataReportSubjectFormat } from "../apple/machoTargetSelection.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { goBinarySchema, goBuildInfoSchema, goModuleMetadataSchema, goModuleSchema, } from "../go/goBinary.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -107,9 +107,12 @@ const parseReport = createAnalysisViewResultReader(goBinarySchema); /** Query the existing metadata owner's facts; never reopen or reinterpret a file. */ export const projectGoBinaryView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "go") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "go"); + if (view === undefined) return err( analysisViewInputError([ { @@ -183,7 +186,7 @@ export const projectGoBinaryView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -242,10 +245,10 @@ export const projectGoBinaryView = ( }), ); return ok({ - kind: "go", + kind: "go" as const, view, ...shared, - page: { collection: "dependencies", rows: selected.rows }, + page: { collection: "dependencies" as const, rows: selected.rows }, coverage: pageViewCoverage( view.offset, selected.rows.length, @@ -266,10 +269,10 @@ export const projectGoBinaryView = ( }), ); return ok({ - kind: "go", + kind: "go" as const, view, ...shared, - page: { collection: "settings", rows: selected.rows }, + page: { collection: "settings" as const, rows: selected.rows }, coverage: pageViewCoverage( view.offset, selected.rows.length, diff --git a/src/domain/analysisView/gpuCodeObjectsView.ts b/src/domain/analysisView/gpuCodeObjectsView.ts index 671489002b..f8d82e6b29 100644 --- a/src/domain/analysisView/gpuCodeObjectsView.ts +++ b/src/domain/analysisView/gpuCodeObjectsView.ts @@ -12,11 +12,12 @@ import { type GpuCodeObjects, } from "../gpu/gpuCodeObjects.js"; import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { ANALYSIS_VIEW_PAGE_BUDGET_RECOVERY, analysisViewInputError, @@ -222,9 +223,12 @@ const readGpuFacts = ( }; export const projectGpuCodeObjectsView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "gpu-code-objects") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "gpu-code-objects"); + if (view === undefined) return err( analysisViewInputError([ { @@ -258,7 +262,7 @@ export const projectGpuCodeObjectsView = ( }; if (view.kind === "summary") { return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { ...summary, limitations: shared.limitations }, @@ -312,7 +316,7 @@ export const projectGpuCodeObjectsView = ( ), ); return ok({ - kind: "gpu-code-objects", + kind: "gpu-code-objects" as const, view, ...shared, source_coverage: report.coverage, @@ -324,7 +328,7 @@ export const projectGpuCodeObjectsView = ( byte_length: artifact.byte_length, text, offset: view.offset, - offset_unit: "utf16-code-unit", + offset_unit: "utf16-code-unit" as const, }, coverage: pageViewCoverage( view.offset, @@ -419,7 +423,7 @@ export const projectGpuCodeObjectsView = ( ), ); return ok({ - kind: "gpu-code-objects", + kind: "gpu-code-objects" as const, view, ...shared, source_coverage: report.coverage, diff --git a/src/domain/analysisView/il2cppMetadataView.test.ts b/src/domain/analysisView/il2cppMetadataView.test.ts index 67d1109700..9aa9a4b9e4 100644 --- a/src/domain/analysisView/il2cppMetadataView.test.ts +++ b/src/domain/analysisView/il2cppMetadataView.test.ts @@ -1,5 +1,6 @@ import { createEmptyIl2cppMetadataFixture } from "../il2cpp/il2cppMetadata.fixture.js"; import { afterEach, expect, it, vi } from "vitest"; +import { z } from "zod"; import { il2cppMetadataParentSchema, type Il2cppMetadata, @@ -7,7 +8,22 @@ import { import { createEvidence } from "../evidence.js"; import { freezeJsonSnapshot } from "../immutableJson.js"; import { jsonObjectSchema } from "../jsonValue.js"; -import { projectIl2cppMetadataView } from "./il2cppMetadataView.js"; +import type { AdmittedView, SummaryAnalysisView } from "./analysisViewShape.js"; +import { + il2cppMetadataViewRequestSchema, + projectIl2cppMetadataView as projectAdmittedIl2cppMetadataView, +} from "./il2cppMetadataView.js"; + +type Il2cppMetadataViewInput = + | SummaryAnalysisView + | z.input; + +/** Check a caller selection against the closed request, then pass the admitted view. */ +const projectIl2cppMetadataView = ( + parent: Parameters[0], + view: Il2cppMetadataViewInput, +): ReturnType => + projectAdmittedIl2cppMetadataView(parent, view satisfies AdmittedView); afterEach(() => { vi.restoreAllMocks(); @@ -638,7 +654,15 @@ const genericLinked = (): Il2cppMetadata => { it("pages generic method instances by definition, state, address, name and field", () => { const source = parent(freezeJsonSnapshot(genericLinked()), true); - const view = (filters: Record) => { + const view = ( + filters: Omit< + Extract< + Il2cppMetadataViewInput, + { collection: "generic_method_instances" } + >, + "kind" | "collection" | "offset" | "limit" + >, + ) => { const result = projectIl2cppMetadataView(source, { kind: "il2cpp-metadata", collection: "generic_method_instances", @@ -649,7 +673,15 @@ it("pages generic method instances by definition, state, address, name and field if (!result.ok) throw result.error; return result.value; }; - const items = (filters: Record) => { + const items = ( + filters: Omit< + Extract< + Il2cppMetadataViewInput, + { collection: "generic_method_instances" } + >, + "kind" | "collection" | "offset" | "limit" + >, + ) => { const value = view(filters); return "items" in value ? value.items : undefined; }; diff --git a/src/domain/analysisView/il2cppMetadataView.ts b/src/domain/analysisView/il2cppMetadataView.ts index e62d2a4fd2..1d89c1c26a 100644 --- a/src/domain/analysisView/il2cppMetadataView.ts +++ b/src/domain/analysisView/il2cppMetadataView.ts @@ -25,11 +25,12 @@ import { } from "../il2cpp/il2cppMetadata.js"; import { err, ok, type Result } from "../result.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -519,9 +520,12 @@ const selection = (view: Request, report: Report) => { /** Reuse retained facts; source indices stay distinct from filtered page offsets. */ export const projectIl2cppMetadataView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "il2cpp-metadata") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "il2cpp-metadata"); + if (view === undefined) return err( analysisViewInputError([ { @@ -653,7 +657,7 @@ export const projectIl2cppMetadataView = ( }), }))(report.binary); return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -729,7 +733,7 @@ export const projectIl2cppMetadataView = ( } } return ok({ - kind: "il2cpp-metadata", + kind: "il2cpp-metadata" as const, view, ...shared, items, diff --git a/src/domain/analysisView/interfaceBuilderView.ts b/src/domain/analysisView/interfaceBuilderView.ts index 06e132f150..2d5a32757f 100644 --- a/src/domain/analysisView/interfaceBuilderView.ts +++ b/src/domain/analysisView/interfaceBuilderView.ts @@ -15,11 +15,12 @@ import { import { err, ok, type Result } from "../result.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { selectViewRows } from "./selectViewRows.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -183,9 +184,12 @@ const summarizeInterfaceBuilder = ( /** Project retained decode_interface_builder Evidence without reopening archives. */ export const projectInterfaceBuilderView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "interface-builder") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "interface-builder"); + if (view === undefined) return err( analysisViewInputError([ { @@ -230,7 +234,7 @@ export const projectInterfaceBuilderView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, ...summarizeInterfaceBuilder(report, limitations.length), @@ -262,7 +266,7 @@ export const projectInterfaceBuilderView = ( ? selectDocumentRows(graph.nodes, view, document) : selectDocumentRows(graph.edges, view, document); return ok({ - kind: "interface-builder", + kind: "interface-builder" as const, view, items: selected.rows, ...shared, diff --git a/src/domain/analysisView/javascriptApplicationView.ts b/src/domain/analysisView/javascriptApplicationView.ts index b63898d0b8..46872962ec 100644 --- a/src/domain/analysisView/javascriptApplicationView.ts +++ b/src/domain/analysisView/javascriptApplicationView.ts @@ -8,24 +8,31 @@ import { jsonObjectSchema, type JsonValue } from "../jsonValue.js"; import type { JavaScriptApplicationAnalysisResult } from "../javascript/javascriptApplicationAnalysis.js"; import type { ApplicationNode } from "../javascript/javascriptApplicationGraphSchemas.js"; import { err, ok, type Result } from "../result.js"; +import { z } from "zod"; import type { JavaScriptModuleReference } from "./javascriptModuleReferences.js"; +import { javascriptModuleReferencesRequestSchema } from "./javascriptModuleReferences.js"; import { javascriptApplicationSourceCoverage, javascriptStaticSourceCoverageSummary, type JavaScriptApplicationSourceCoverage, } from "./javascriptApplicationCoverage.js"; -import { projectJavaScriptFacts } from "./javascriptFactsView.js"; +import { + projectJavaScriptFacts, + javascriptFactsViewRequestSchema, +} from "./javascriptFactsView.js"; import { boundedViewMessages, completeWithinViewCoverage as completeCoverage, pageViewCoverage as pageCoverage, } from "./analysisViewCoverage.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, - GroupingViewKind, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type ItemAnalysisView, + type PageAnalysisView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; const OPERATION = "inspect_analysis_view"; @@ -96,9 +103,8 @@ const modulePage = ( view: { readonly offset: number; readonly limit: number; - readonly where?: Extract< - AnalysisViewRequest, - { kind: "javascript" } + readonly where?: z.output< + typeof javascriptModuleReferencesRequestSchema >["where"]; }, ): { entries: ModuleEntry[]; total: number } => { @@ -281,7 +287,7 @@ const parentFields = ( const selectModule = ( modules: readonly ModuleEntry[], - selector: Extract["selector"], + selector: ItemAnalysisView["selector"], ): Result => { if ("node_id" in selector) { const matches = modules.filter( @@ -342,8 +348,8 @@ const selectModule = ( export const projectJavaScriptApplicationView = ( parent: AnalysisViewParent, analysis: JavaScriptApplicationAnalysisResult, - view: Exclude, -): Result => { + view: AdmittedView, +) => { if ( view.kind !== "summary" && view.kind !== "item" && @@ -356,6 +362,13 @@ export const projectJavaScriptApplicationView = ( "JavaScript application Evidence supports summary, module item/page, typed module references or selected JavaScript facts.", ), ); + assertOwnedView< + | SummaryAnalysisView + | ItemAnalysisView + | PageAnalysisView + | z.output + | z.output + >(view, "summary", "item", "page", "javascript", "javascript-facts"); const sourceCoverage = javascriptApplicationSourceCoverage(analysis); const { fields: shared, limitationCount } = parentFields( parent, @@ -366,7 +379,7 @@ export const projectJavaScriptApplicationView = ( const { rows, total } = projectJavaScriptFacts(analysis.graph.nodes, view); return ok({ ...shared, - kind: "javascript-facts", + kind: "javascript-facts" as const, view, rows, source_coverage: sourceCoverage, @@ -378,7 +391,7 @@ export const projectJavaScriptApplicationView = ( const rows = entries.map(moduleReference); return ok({ ...shared, - kind: "javascript", + kind: "javascript" as const, view, rows, source_coverage: sourceCoverage, @@ -393,7 +406,7 @@ export const projectJavaScriptApplicationView = ( 0, ); return ok({ - kind: "summary", + kind: "summary" as const, view, summary: { input_path: analysis.input_path, @@ -438,7 +451,7 @@ export const projectJavaScriptApplicationView = ( const selected = selectModule(modules, view.selector); if (!selected.ok) return selected; return ok({ - kind: "item", + kind: "item" as const, view, item: moduleItem(selected.value.node, selected.value.path), coverage: completeCoverage(1, modules.length), @@ -458,7 +471,7 @@ export const projectJavaScriptApplicationView = ( path, })); return ok({ - kind: "page", + kind: "page" as const, view, items, coverage: pageCoverage(view.offset, items.length, total), diff --git a/src/domain/analysisView/javascriptRoutesView.ts b/src/domain/analysisView/javascriptRoutesView.ts index cabb87dd7c..f28569c133 100644 --- a/src/domain/analysisView/javascriptRoutesView.ts +++ b/src/domain/analysisView/javascriptRoutesView.ts @@ -21,11 +21,8 @@ import { type JavaScriptRouteInventorySource, } from "../javascript/javascriptRouteInventory.js"; import { javaScriptRouteMechanismSchema } from "../javascript/javascriptRouteFacts.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { assertOwnedView, type AdmittedView } from "./analysisViewShape.js"; import { ANALYSIS_VIEW_PAGE_BUDGET_RECOVERY, analysisViewInputError, @@ -319,10 +316,14 @@ const captureIdentity = z.object({ /** Historical projection: no source file reads, browser connection or reanalysis. */ export const projectJavaScriptRoutesView = ( parent: AnalysisViewParent, - selected: AnalysisViewRequest, -): Result => { + selected: AdmittedView, +) => { if (selected.kind !== "javascript-routes") return err(inputError("Select a javascript-routes view.")); + assertOwnedView>( + selected, + "javascript-routes", + ); const operation = parent.operation; if ( operation !== "analyze_javascript_application" && @@ -452,7 +453,7 @@ export const projectJavaScriptRoutesView = ( item: Record; sources: readonly string[]; }, - ): Result => { + ) => { const rows = candidates(source, ids).filter(predicate), items: Record[] = [], refs = new Map(); diff --git a/src/domain/analysisView/machoView.ts b/src/domain/analysisView/machoView.ts index ef8d382530..6c471e5880 100644 --- a/src/domain/analysisView/machoView.ts +++ b/src/domain/analysisView/machoView.ts @@ -9,11 +9,12 @@ import { } from "../native/nativeInspection.js"; import { err, ok, type Result } from "../result.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -155,9 +156,12 @@ const summarizeMacho = ( /** Project retained inspect_macho Evidence without rerunning native tools. */ export const projectMachoView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "macho") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "macho"); + if (view === undefined) return err( analysisViewInputError([ { @@ -203,7 +207,7 @@ export const projectMachoView = ( parent.limitations, ); return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, limitations, diff --git a/src/domain/analysisView/managedArtifactView.ts b/src/domain/analysisView/managedArtifactView.ts index 0e64e4c30d..5dcb92b1d5 100644 --- a/src/domain/analysisView/managedArtifactView.ts +++ b/src/domain/analysisView/managedArtifactView.ts @@ -1,18 +1,18 @@ import { analysisViewInputError } from "./analysisViewErrors.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import { managedArtifactInspectionSchema, managedMemberInspectionSchema, } from "../managed/managedArtifact.js"; -import { err, ok, type Result } from "../result.js"; +import { err, ok } from "../result.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -72,9 +72,12 @@ export const managedViewIdentityUnknowns = ( /** Project authenticated metadata without reading a path or invoking a provider. */ export const projectManagedArtifactView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "managed") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "managed"); + if (view === undefined) return err( analysisViewInputError([ { @@ -116,7 +119,7 @@ export const projectManagedArtifactView = ( }; const total = references.length + resources.length + attributes.length; return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { ...summary, reported_counts, identity_scope }, @@ -126,7 +129,7 @@ export const projectManagedArtifactView = ( const collection = report[view.collection]; const item = collection.slice(view.offset, view.offset + view.limit); return ok({ - kind: "managed", + kind: "managed" as const, view, item, ...shared, diff --git a/src/domain/analysisView/managedMemberView.test.ts b/src/domain/analysisView/managedMemberView.test.ts index 7bafab84a8..e6d8f401f4 100644 --- a/src/domain/analysisView/managedMemberView.test.ts +++ b/src/domain/analysisView/managedMemberView.test.ts @@ -107,7 +107,7 @@ it("intersects exact filters before paging and preserves identity while omitting request, ); if (!result.ok) throw result.error; - if (result.value.kind !== "managed-members") throw new Error("Wrong view"); + if (!("page" in result.value)) throw new Error("Wrong view"); expect(result.value.page).toEqual({ collection: "methods", source_count: 4, @@ -161,7 +161,7 @@ it("keeps unresolved exact-filter candidates unknown under complete and partial }), ); if (!result.ok) throw result.error; - if (result.value.kind !== "managed-members") throw new Error("Wrong view"); + if (!("page" in result.value)) throw new Error("Wrong view"); expect(result.value).toMatchObject({ source_coverage: { state }, coverage: { total: 1 }, @@ -220,7 +220,7 @@ it("distinguishes empty selectors from omitted selectors and pages projections w expect(full.value).toMatchObject({ page: { collection: "methods", rows: report.methods.slice(1, 3) }, }); - if (full.value.kind !== "managed-members") throw new Error("Wrong view"); + if (!("page" in full.value)) throw new Error("Wrong view"); expect(full.value.page.rows).toEqual(report.methods.slice(1, 3)); }); diff --git a/src/domain/analysisView/managedMemberView.ts b/src/domain/analysisView/managedMemberView.ts index 1888c9afa5..f11c4b04b0 100644 --- a/src/domain/analysisView/managedMemberView.ts +++ b/src/domain/analysisView/managedMemberView.ts @@ -1,20 +1,22 @@ import { analysisViewInputError } from "./analysisViewErrors.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import { managedMemberInspectionSchema, type ManagedMemberInspection, } from "../managed/managedArtifact.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js"; +import { z } from "zod"; +import { managedMembersViewRequestSchema } from "./managedMemberViewSchemas.js"; import { managedViewIdentityUnknowns } from "./managedArtifactView.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; @@ -275,8 +277,8 @@ const summarizeMembers = ( /** Project authenticated member Evidence without reading a path or invoking a provider. */ export const projectManagedMemberView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "managed-members") return err( analysisViewInputError([ @@ -288,6 +290,9 @@ export const projectManagedMemberView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "managed-members"); const parsed = parseMemberReport(parent); if (!parsed.ok) return parsed; const report = parsed.value; @@ -317,7 +322,7 @@ export const projectManagedMemberView = ( 0, ); return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary, @@ -345,7 +350,7 @@ export const projectManagedMemberView = ( `${page.unresolved_filter_rows} source rows have unknown requested names or declaring types and may match the filters; the matched total excludes them.`, ); return ok({ - kind: "managed-members", + kind: "managed-members" as const, view, page, ...shared, diff --git a/src/domain/analysisView/modelArtifactView.ts b/src/domain/analysisView/modelArtifactView.ts index e71d6a9815..9ddb513059 100644 --- a/src/domain/analysisView/modelArtifactView.ts +++ b/src/domain/analysisView/modelArtifactView.ts @@ -1,4 +1,7 @@ -import { modelTypeRowSchema } from "../model/modelArtifactQuery.js"; +import { + modelArtifactViewRequestSchema, + modelTypeRowSchema, +} from "../model/modelArtifactQuery.js"; import { z } from "zod"; import { modelArtifactSchema, @@ -14,11 +17,12 @@ import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { isImmutableJsonSnapshot } from "../immutableJson.js"; import type { JsonValue } from "../jsonValue.js"; import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, boundedViewMessages, @@ -180,8 +184,8 @@ const read = (parent: AnalysisViewParent): Result => { /** Historical pages never reopen weights or report a scoped header digest as full-file identity. */ export const projectModelArtifactView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "model-artifact") return err( analysisViewInputError([ @@ -193,6 +197,9 @@ export const projectModelArtifactView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "model-artifact"); const parsed = read(parent); if (!parsed.ok) return parsed; const { @@ -225,7 +232,7 @@ export const projectModelArtifactView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -318,7 +325,7 @@ export const projectModelArtifactView = ( return result; }); return ok({ - kind: "model-artifact", + kind: "model-artifact" as const, view, ...shared, source: report.artifact, diff --git a/src/domain/analysisView/nativeExportsView.ts b/src/domain/analysisView/nativeExportsView.ts index d0d8d1ee97..1d9be08030 100644 --- a/src/domain/analysisView/nativeExportsView.ts +++ b/src/domain/analysisView/nativeExportsView.ts @@ -5,13 +5,13 @@ import { elfNativeExportsSchema as elf, type NativeExports, } from "../native/nativeExports.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -88,8 +88,8 @@ const readReport = createAnalysisViewResultReader(nativeExportsSchema); /** Read selected export facts without reopening the artifact or reinterpreting its tables. */ export const projectNativeExportsView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { const invalid = (message: string) => err( analysisViewInputError([ @@ -100,6 +100,9 @@ export const projectNativeExportsView = ( return invalid( "Native export Evidence supports summary and native-exports views.", ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "native-exports"); const parsed = readReport(parent); if (!parsed.ok) return parsed; const report = parsed.value; @@ -131,7 +134,7 @@ export const projectNativeExportsView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary, coverage: completeWithinViewCoverage(exports.length, exports.length), @@ -158,7 +161,7 @@ export const projectNativeExportsView = ( ); return ok({ ...shared, - kind: "native-exports", + kind: "native-exports" as const, view, exports: summary, items: selected.rows, @@ -246,7 +249,7 @@ export const projectNativeExportsView = ( ); return ok({ ...shared, - kind: "native-exports", + kind: "native-exports" as const, view, exports: summary, items: selected.rows, diff --git a/src/domain/analysisView/nativeFunctionMatchingView.ts b/src/domain/analysisView/nativeFunctionMatchingView.ts index e6870322aa..4d5d8cfe3d 100644 --- a/src/domain/analysisView/nativeFunctionMatchingView.ts +++ b/src/domain/analysisView/nativeFunctionMatchingView.ts @@ -16,11 +16,12 @@ import { } from "./analysisViewCoverage.js"; import { err, ok, type Result } from "../result.js"; import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import type { JsonValue } from "../jsonValue.js"; const matchRow = nativeFunctionMatchSchema.extend({ @@ -259,9 +260,13 @@ const selectedItems = ( /** Query immutable matching facts without copying full alias groups into selected pages. */ export const projectNativeFunctionMatchingView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "function-matches") + admitted: AdmittedView, +) => { + const view = ownedView< + | SummaryAnalysisView + | z.output + >(admitted, "summary", "function-matches"); + if (view === undefined) return err( analysisViewInputError([ { @@ -283,7 +288,7 @@ export const projectNativeFunctionMatchingView = ( const shared = sharedContext(parent, entry.report); if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: context, @@ -292,7 +297,7 @@ export const projectNativeFunctionMatchingView = ( const rows = filterRows(entry, view), items = selectedItems(entry, view, rows); return ok({ - kind: "function-matches", + kind: "function-matches" as const, view, ...shared, ...context, diff --git a/src/domain/analysisView/nativeFunctionView.ts b/src/domain/analysisView/nativeFunctionView.ts index dea093806e..8ce34ee53f 100644 --- a/src/domain/analysisView/nativeFunctionView.ts +++ b/src/domain/analysisView/nativeFunctionView.ts @@ -4,12 +4,14 @@ import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; import type { FunctionDossier } from "../native/functionDossier.js"; import { jsonValueSchema } from "../jsonValue.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type NativeFacetAnalysisView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -62,7 +64,7 @@ const parentFields = ( const nativeRows = ( dossier: FunctionDossier, facet: Exclude< - Extract["facet"], + NativeFacetAnalysisView["facet"], "procedure" | "pseudocode" | "native_api" | "value_flow_summary" >, ): readonly unknown[] | undefined => { @@ -196,11 +198,11 @@ const summarizeDossier = (dossier: FunctionDossier) => { }; const summaryView = ( - view: Extract, + view: SummaryAnalysisView, dossier: FunctionDossier, common: ReturnType, -): UnsignedAnalysisView => ({ - kind: "summary", +) => ({ + kind: "summary" as const, view, summary: summarizeDossier(dossier), coverage: completeWithinViewCoverage(1, 1), @@ -216,12 +218,17 @@ const summaryView = ( export const projectNativeFunctionView = ( parent: AnalysisViewParent, dossier: FunctionDossier, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "native" && view.kind !== "summary") return err( viewError("analyze_function Evidence requires a native or summary view."), ); + assertOwnedView( + view, + "summary", + "native", + ); const artifact = parent.artifact; if (!artifact) return err( @@ -239,8 +246,8 @@ export const projectNativeFunctionView = ( const availability = facetAvailability(dossier, view.facet); if (availability?.available === false) common.unknowns = uniqueSorted([...common.unknowns, availability.reason]); - const singleton = (item: unknown): UnsignedAnalysisView => ({ - kind: "native", + const singleton = (item: unknown) => ({ + kind: "native" as const, view, item: jsonValueSchema.parse(item), coverage: completeWithinViewCoverage(1, 1), @@ -286,7 +293,7 @@ export const projectNativeFunctionView = ( if (view.facet === "pseudocode") { const page = analysisTextPage(dossier.pseudocode, view.offset, view.limit); return page.ok - ? ok({ kind: "native", view, ...page.value, ...common }) + ? ok({ kind: "native" as const, view, ...page.value, ...common }) : page; } const rows = nativeRows(dossier, view.facet); @@ -305,7 +312,7 @@ export const projectNativeFunctionView = ( ); const items = rows.slice(view.offset, view.offset + view.limit); return ok({ - kind: "native", + kind: "native" as const, view, item: jsonValueSchema.parse(items), coverage: pageViewCoverage(view.offset, items.length, rows.length), diff --git a/src/domain/analysisView/nativeInventoryView.ts b/src/domain/analysisView/nativeInventoryView.ts index 2ef5dedccc..01c22de8c0 100644 --- a/src/domain/analysisView/nativeInventoryView.ts +++ b/src/domain/analysisView/nativeInventoryView.ts @@ -6,13 +6,13 @@ import { isNativeInventoryOperation, nativeInventoryRowsSchemas, } from "../native/nativeInventory.js"; -import { err, ok, type Result } from "../result.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -68,8 +68,8 @@ const readStrings = createAnalysisViewResultReader( /** Project already completed provider observations without another provider read or sort. */ export const projectNativeInventoryView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if ( !isNativeInventoryOperation(parent.operation) || (view.kind !== "summary" && view.kind !== "native-inventory") @@ -84,6 +84,9 @@ export const projectNativeInventoryView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "native-inventory"); const strings = parent.operation === "list_strings" || parent.operation === "search_strings"; @@ -113,16 +116,16 @@ export const projectNativeInventoryView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary: { collection: strings - ? "strings" + ? ("strings" as const) : parent.operation === "list_names" - ? "names" - : "procedures", + ? ("names" as const) + : ("procedures" as const), row_count: rows.length, - discovery_coverage: "unknown", + discovery_coverage: "unknown" as const, selectable_fields: fieldSchema.options, }, coverage: completeWithinViewCoverage(rows.length, rows.length), @@ -137,7 +140,7 @@ export const projectNativeInventoryView = ( const selected = rows.slice(view.offset, view.offset + view.limit); return ok({ ...shared, - kind: "native-inventory", + kind: "native-inventory" as const, view, rows: selected.map((record, index) => ({ source_index: view.offset + index, diff --git a/src/domain/analysisView/nativeLoadImageView.ts b/src/domain/analysisView/nativeLoadImageView.ts index c8908989de..c4975e00dc 100644 --- a/src/domain/analysisView/nativeLoadImageView.ts +++ b/src/domain/analysisView/nativeLoadImageView.ts @@ -10,13 +10,13 @@ import { } from "../native/nativeLoadImage.js"; import { nativeAddressObservationSchema } from "../native/nativeAddress.js"; import { jsonValueSchema } from "../jsonValue.js"; -import { err, ok, type Result } from "../result.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -199,9 +199,12 @@ const selectRows = (source: readonly (Row | string)[], view: PageRequest) => { /** Query the owner's parsed historical observations without reopening the target. */ export const projectNativeLoadImageView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "native-load-image") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "native-load-image"); + if (view === undefined) return err( analysisViewInputError([ { @@ -257,7 +260,7 @@ export const projectNativeLoadImageView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary: { verification: smallVerification, @@ -289,7 +292,7 @@ export const projectNativeLoadImageView = ( const page = selectRows(selected ?? [], view); return ok({ ...shared, - kind: "native-load-image", + kind: "native-load-image" as const, verification_status: report.status, view, items: nativeLoadImageViewItemsSchema.parse({ diff --git a/src/domain/analysisView/nativeObservationView.ts b/src/domain/analysisView/nativeObservationView.ts index a8c9d85ceb..a532242c2d 100644 --- a/src/domain/analysisView/nativeObservationView.ts +++ b/src/domain/analysisView/nativeObservationView.ts @@ -1,4 +1,5 @@ import type { AnalysisError } from "../analysisErrorBase.js"; +import { z } from "zod"; import { evidenceSubjectIdentity } from "../evidence.js"; import { digestCanonicalValue } from "../canonicalDigest.js"; import { jsonValueSchema } from "../jsonValue.js"; @@ -9,11 +10,12 @@ import { nativeObservationSourceSchemas, type NativeObservation, } from "../native/nativeObservation.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { @@ -21,6 +23,8 @@ import { completeWithinViewCoverage, } from "./analysisViewCoverage.js"; import { + nativeContextViewRequestSchema, + nativeObservationViewRequestSchema, nativeSourceContextSchema, type NativeSourceContext, } from "./nativeObservationSchemas.js"; @@ -166,7 +170,7 @@ const observationRows = ( }; const contextRows = ( source: NativeSourceContext, - view: Extract, + view: z.output, ) => { switch (view.facet) { case "overview": { @@ -245,8 +249,8 @@ const contextRows = ( /** Select recorded native facts without repeating provider profiles or complete caveat inventories. */ export const projectNativeObservationView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if ( view.kind !== "summary" && view.kind !== "native-observation" && @@ -262,6 +266,11 @@ export const projectNativeObservationView = ( }, ]), ); + assertOwnedView< + | SummaryAnalysisView + | z.output + | z.output + >(view, "summary", "native-observation", "native-context"); const source = readSource(parent); if (!source.ok) return source; const context = readContext(parent, source.value); @@ -296,7 +305,7 @@ export const projectNativeObservationView = ( const { total, ...page } = contextRows(context.value, view); return ok({ ...common, - kind: "native-context", + kind: "native-context" as const, ...page, parent_operation: source.value.operation, coverage: @@ -321,6 +330,6 @@ export const projectNativeObservationView = ( coverage: pageViewCoverage(selection.offset, page.items.rows.length, total), }; return view.kind === "summary" - ? ok({ ...observation, kind: "summary", view }) - : ok({ ...observation, kind: "native-observation", view }); + ? ok({ ...observation, kind: "summary" as const, view }) + : ok({ ...observation, kind: "native-observation" as const, view }); }; diff --git a/src/domain/analysisView/pcapCaptureView.ts b/src/domain/analysisView/pcapCaptureView.ts index 5ca03a1875..cc7f05b9b7 100644 --- a/src/domain/analysisView/pcapCaptureView.ts +++ b/src/domain/analysisView/pcapCaptureView.ts @@ -4,11 +4,12 @@ import { pcapEvidenceSchemas } from "../pcap/pcapAnalysis.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; import type { AnalysisError } from "../analysisErrorBase.js"; import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -253,9 +254,12 @@ const selectRows = ( /** Historical packet facts are paged without reopening the source or rerunning Wireshark. */ export const projectPcapCaptureView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "pcap") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "pcap"); + if (view === undefined) return err( analysisViewInputError([ { @@ -284,7 +288,7 @@ export const projectPcapCaptureView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: summarize(capture), @@ -303,14 +307,15 @@ export const projectPcapCaptureView = ( ); if (!text.ok) return text; return ok({ - kind: "pcap", + kind: "pcap" as const, view, ...shared, source_coverage: capture.coverage, page: { - facet: "diagnostics", + facet: "diagnostics" as const, text: text.value.item.text, - status: value === undefined ? "unknown" : "retained", + status: + value === undefined ? ("unknown" as const) : ("retained" as const), }, coverage: text.value.coverage, unknowns: @@ -325,7 +330,7 @@ export const projectPcapCaptureView = ( const selected = selectRows(capture, view); return selected.ok ? ok({ - kind: "pcap", + kind: "pcap" as const, view, ...shared, source_coverage: capture.coverage, diff --git a/src/domain/analysisView/pythonPycView.ts b/src/domain/analysisView/pythonPycView.ts index 1cd0381c08..8676db842e 100644 --- a/src/domain/analysisView/pythonPycView.ts +++ b/src/domain/analysisView/pythonPycView.ts @@ -3,13 +3,13 @@ import { pythonPycSchema, type PythonPycCodeObject, } from "../python/pythonPyc.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -62,9 +62,12 @@ const readReport = createAnalysisViewResultReader(pythonPycSchema); /** Project code-constant references from historical facts, without reopening the pyc. */ export const projectPythonPycView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "python-pyc") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "python-pyc"); + if (view === undefined) return err( analysisViewInputError([ { @@ -96,7 +99,7 @@ export const projectPythonPycView = ( if (view.kind === "summary") return ok({ ...shared, - kind: "summary", + kind: "summary" as const, view, summary, coverage: completeWithinViewCoverage( @@ -132,7 +135,7 @@ export const projectPythonPycView = ( ); return ok({ ...shared, - kind: "python-pyc", + kind: "python-pyc" as const, view, pyc: summary, items: selected.rows, diff --git a/src/domain/analysisView/rustBinaryView.ts b/src/domain/analysisView/rustBinaryView.ts index 5354e2441e..027d17eeda 100644 --- a/src/domain/analysisView/rustBinaryView.ts +++ b/src/domain/analysisView/rustBinaryView.ts @@ -1,26 +1,29 @@ import { binaryMetadataArchitecture } from "../binaryMetadataArchitecture.js"; import { metadataReportSubjectFormat } from "../apple/machoTargetSelection.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { rustBinarySchema, rustAuditableMetadataSchema, rustcCommitSchema, type RustBinary, } from "../rust/rustBinary.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import { + createAnalysisViewResultReader, + type AnalysisViewParent, +} from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; +import { rustBinaryViewRequestSchema } from "../rust/rustBinaryQuery.js"; import { boundedViewMessages, completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; -import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { selectViewRows } from "./selectViewRows.js"; const count = z.number().int().nonnegative(); @@ -108,8 +111,8 @@ const summarize = ( /** Query owner-normalized facts without reopening a source or walking dependency paths. */ export const projectRustBinaryView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if (view.kind !== "summary" && view.kind !== "rust") return err( analysisViewInputError([ @@ -120,6 +123,9 @@ export const projectRustBinaryView = ( }, ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(view, "summary", "rust"); const parsed = parseReport(parent); if (!parsed.ok) return parsed; const report = parsed.value; @@ -177,7 +183,7 @@ export const projectRustBinaryView = ( const summary = summarize(report); if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary, @@ -214,11 +220,11 @@ export const projectRustBinaryView = ( }), ); return ok({ - kind: "rust", + kind: "rust" as const, view, ...shared, rust: summary, - page: { collection: "packages", rows: selected.rows }, + page: { collection: "packages" as const, rows: selected.rows }, coverage: pageViewCoverage( view.offset, selected.rows.length, @@ -246,11 +252,11 @@ export const projectRustBinaryView = ( }), ); return ok({ - kind: "rust", + kind: "rust" as const, view, ...shared, rust: summary, - page: { collection: "edges", rows: selected.rows }, + page: { collection: "edges" as const, rows: selected.rows }, coverage: pageViewCoverage( view.offset, selected.rows.length, diff --git a/src/domain/analysisView/scenarioCaptureRecords.ts b/src/domain/analysisView/scenarioCaptureRecords.ts index f43d8fedd0..59e7294293 100644 --- a/src/domain/analysisView/scenarioCaptureRecords.ts +++ b/src/domain/analysisView/scenarioCaptureRecords.ts @@ -17,7 +17,7 @@ import type { JsonValue } from "../jsonValue.js"; import { err, ok, type Result } from "../result.js"; import type { WebNetworkCaptureRecord } from "../webNetworkCapture.js"; import { analysisViewResultInputError } from "./analysisViewParent.js"; -import type { AnalysisViewParent } from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; import type { WebNetworkProjectionAccumulator } from "./WebNetworkProjectionAccumulator.js"; import { ENTRY_BYTES, textBytes } from "./webNetworkRouteTemplates.js"; diff --git a/src/domain/analysisView/sourceToBundleView.ts b/src/domain/analysisView/sourceToBundleView.ts index 38a2f616b5..9443b52b67 100644 --- a/src/domain/analysisView/sourceToBundleView.ts +++ b/src/domain/analysisView/sourceToBundleView.ts @@ -4,13 +4,13 @@ import { sourceToBundleComparisonResultSchema, type SourceToBundleComparisonResult, } from "../javascript/sourceToBundleComparisonSchemas.js"; -import { err, ok, type Result } from "../result.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createAnalysisViewResultReader } from "./analysisViewParent.js"; import { @@ -109,9 +109,12 @@ const columns = ( /** Page facts owned by a complete comparison; page exhaustion does not upgrade source coverage. */ export const projectSourceToBundleView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "source-to-bundle") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "source-to-bundle"); + if (view === undefined) return err( analysisViewInputError([ { @@ -153,7 +156,7 @@ export const projectSourceToBundleView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: context, @@ -234,7 +237,7 @@ export const projectSourceToBundleView = ( } } return ok({ - kind: "source-to-bundle", + kind: "source-to-bundle" as const, view, ...shared, ...context, diff --git a/src/domain/analysisView/wasmArtifactView.ts b/src/domain/analysisView/wasmArtifactView.ts index de6b65fb31..4d16729658 100644 --- a/src/domain/analysisView/wasmArtifactView.ts +++ b/src/domain/analysisView/wasmArtifactView.ts @@ -1,18 +1,18 @@ import { analysisViewInputError } from "./analysisViewErrors.js"; import { z } from "zod"; -import type { AnalysisError } from "../analysisErrorBase.js"; import { uniqueSorted } from "../canonicalOrdering.js"; -import { err, ok, type Result } from "../result.js"; +import { err, ok } from "../result.js"; import { parseAnalysisViewResult } from "./analysisViewParent.js"; import { wasmArtifactSchema, wasmArtifactMatchesSubject, } from "../wasm/wasmArtifact.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + ownedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, @@ -74,9 +74,12 @@ export const wasmSummarySchema = z.strictObject({ /** Read the exact retained WABT forms with source identity and explicit uncertainty. */ export const projectWasmArtifactView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { - if (view.kind !== "summary" && view.kind !== "wasm") + admitted: AdmittedView, +) => { + const view = ownedView< + SummaryAnalysisView | z.output + >(admitted, "summary", "wasm"); + if (view === undefined) return err( analysisViewInputError([ { @@ -131,7 +134,7 @@ export const projectWasmArtifactView = ( }; if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -173,7 +176,7 @@ export const projectWasmArtifactView = ( ]), ); return ok({ - kind: "wasm", + kind: "wasm" as const, view, item: report.tool_profile, coverage: completeWithinViewCoverage(1, 1), @@ -188,13 +191,13 @@ export const projectWasmArtifactView = ( const text = view.facet === "wat" ? report.wat.text : report[view.facet]; const page = analysisTextPage(text, view.offset, view.limit, view.facet); return page.ok - ? ok({ kind: "wasm", view, ...page.value, ...shared }) + ? ok({ kind: "wasm" as const, view, ...page.value, ...shared }) : page; } const rows = report[view.facet]; const item = rows.slice(view.offset, view.offset + view.limit); return ok({ - kind: "wasm", + kind: "wasm" as const, view, item, coverage: pageViewCoverage(view.offset, item.length, rows.length), diff --git a/src/domain/analysisView/webBundleView.ts b/src/domain/analysisView/webBundleView.ts index 75b55fe6f2..fadf8b78e5 100644 --- a/src/domain/analysisView/webBundleView.ts +++ b/src/domain/analysisView/webBundleView.ts @@ -9,11 +9,12 @@ import { type WebBundleAnalysis, } from "../webBundleAnalysis.js"; import { recordedBrowserOriginSchema } from "../browserObservation.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { boundedViewMessages, completeWithinViewCoverage, @@ -119,8 +120,8 @@ const choose = ( /** Historical projection of completed analyze_web_bundle Evidence. */ export const projectWebBundleView = ( parent: AnalysisViewParent, - selected: AnalysisViewRequest, -): Result => { + selected: AdmittedView, +) => { if (selected.kind !== "web-bundle" && selected.kind !== "summary") return err( analysisViewInputError([ @@ -132,6 +133,9 @@ export const projectWebBundleView = ( ]), ); + assertOwnedView< + SummaryAnalysisView | z.output + >(selected, "summary", "web-bundle"); if (parent.operation !== "analyze_web_bundle") return err( analysisViewInputError([ @@ -216,8 +220,8 @@ export const projectWebBundleView = ( if (selected.kind === "summary") { const summary = buildSummary(); - const result: UnsignedAnalysisView = { - kind: "summary", + const result = { + kind: "summary" as const, view: selected, ...shared, summary, @@ -234,8 +238,8 @@ export const projectWebBundleView = ( const view = selected; if (view.collection === "summary") { const summary = buildSummary(); - const result: UnsignedAnalysisView = { - kind: "web-bundle", + const result = { + kind: "web-bundle" as const, view, ...shared, completeness: report.completeness, @@ -261,7 +265,7 @@ export const projectWebBundleView = ( rows: readonly T[], matches: ((row: T, source_index: number) => boolean) | undefined, project: (row: T, source_index: number) => Item, - ): Result => { + ) => { const baseEnvelope = { ...shared, kind: "web-bundle" as const, @@ -323,7 +327,7 @@ export const projectWebBundleView = ( } const coverage = pageViewCoverage(view.offset, items.length, total); - const result: UnsignedAnalysisView = { + const result = { ...shared, kind: "web-bundle" as const, view, diff --git a/src/domain/analysisView/webNetworkApiSurfaceView.ts b/src/domain/analysisView/webNetworkApiSurfaceView.ts index 40da068fa3..d1bd0224c7 100644 --- a/src/domain/analysisView/webNetworkApiSurfaceView.ts +++ b/src/domain/analysisView/webNetworkApiSurfaceView.ts @@ -1,96 +1,39 @@ import { z } from "zod"; import { AnalysisUnsupportedTargetError } from "../analysisErrorCore.js"; -import type { AnalysisError } from "../analysisErrorBase.js"; -import { err, ok, type Result } from "../result.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import { err, ok } from "../result.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + ownedView, + type AdmittedView, +} from "./analysisViewShape.js"; import { WebNetworkApiSurfaceAccumulator } from "./WebNetworkApiSurfaceAccumulator.js"; import { admitHarCaptureParent } from "./WebNetworkProjectionAccumulator.js"; -import { ROUTE_RULES } from "./webNetworkRouteTemplates.js"; -export const apiSurfaceViewSchema = z.strictObject({ - kind: z.literal("api-surface"), - offset: z.int().nonnegative().default(0), - limit: z.int().positive().default(50), - include_query_parameter_names: z - .boolean() - .optional() - .describe( - "Include distinct observed query parameter names and their original record ordinals; names do not establish required parameters or a complete API schema.", - ), -}); -const ruleSchema = z.enum(ROUTE_RULES); -const groupSchema = z.strictObject({ - method: z.string(), - origin: z.string(), - path_template: z.string(), - templated_segments: z.array( - z.strictObject({ - segment_index: z.int().nonnegative(), - rule: ruleSchema, - basis: z.literal("inferred"), - observed_values: z.array(z.string()), - }), - ), - record_ordinals: z.array(z.int().nonnegative()), - statuses: z.array(z.number()), - content_types: z.array(z.string()), - query_parameter_names: z - .array( - z.strictObject({ - name: z.string(), - record_ordinals: z.array(z.int().nonnegative()), - }), - ) - .optional(), - flags: z.array( - z.enum(["single-sample", "mixed-statuses", "mixed-content-types"]), - ), -}); -export const apiSurfaceFields = { - records: z.strictObject({ - examined: z.int().nonnegative(), - total: z.int().nonnegative(), - excluded: z.int().nonnegative(), - }), - templated_groups: z - .int() - .nonnegative() - .describe( - "Groups across every page that carry at least one templated segment.", - ), - groups: z.array(groupSchema), - excluded_records: z.array( - z.strictObject({ - ordinal: z.int().nonnegative(), - reason: z.enum([ - "url-redacted", - "url-unparseable", - "request-unavailable", - "method-unavailable", - ]), - }), - ), -}; +import { apiSurfaceFields, apiSurfaceViewSchema } from "./apiSurfaceSchema.js"; + +export { apiSurfaceFields, apiSurfaceViewSchema }; /** Create the budget and query-name policy shared by admission and projection. */ export const createApiSurfaceAccumulator = ( - view: AnalysisViewRequest, -): WebNetworkApiSurfaceAccumulator => - new WebNetworkApiSurfaceAccumulator( - undefined, - view.kind === "api-surface" && view.include_query_parameter_names === true, + view: AdmittedView, +): WebNetworkApiSurfaceAccumulator => { + const selected = ownedView>( + view, + "api-surface", ); + return new WebNetworkApiSurfaceAccumulator( + undefined, + selected?.include_query_parameter_names === true, + ); +}; /** Group retained HAR request lines; format matches do not establish handler identity. */ export const projectWebNetworkApiSurfaceView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, + view: AdmittedView, accumulator = createApiSurfaceAccumulator(view), -): Result => { +) => { if (view.kind !== "api-surface") return err( new AnalysisUnsupportedTargetError( @@ -99,6 +42,7 @@ export const projectWebNetworkApiSurfaceView = ( `View ${view.kind} is unsupported for parent operation ${parent.operation}; api-surface requires inspect_web_network_capture.`, ), ); + assertOwnedView>(view, "api-surface"); const admitted = admitHarCaptureParent(parent, "api-surface", accumulator); if (!admitted.ok) return admitted; const capture = admitted.value; @@ -124,10 +68,10 @@ export const projectWebNetworkApiSurfaceView = ( } const page = accumulator.page(view.offset, view.limit); return ok({ - kind: "api-surface", + kind: "api-surface" as const, view, parent_evidence_id: parent.evidenceId, - parent_operation: "inspect_web_network_capture", + parent_operation: "inspect_web_network_capture" as const, parent_digest: parent.evidenceId.slice(3), artifact: { path: capture.artifact.path, sha256: capture.artifact.sha256 }, records: { diff --git a/src/domain/analysisView/webNetworkCaptureView.ts b/src/domain/analysisView/webNetworkCaptureView.ts index 90555e317e..83c737ea9b 100644 --- a/src/domain/analysisView/webNetworkCaptureView.ts +++ b/src/domain/analysisView/webNetworkCaptureView.ts @@ -1,4 +1,7 @@ -import { projectProtobufCapturePage } from "./protobufCaptureView.js"; +import { + projectProtobufCapturePage, + protobufViewRequestSchema, +} from "./protobufCaptureView.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import { createHash } from "node:crypto"; import { z } from "zod"; @@ -17,17 +20,19 @@ import { type WebNetworkCaptureRecord, type WebNetworkCapture, } from "../webNetworkCapture.js"; -import type { - AnalysisViewParent, - AnalysisViewRequest, - UnsignedAnalysisView, -} from "./analysisView.js"; +import type { AnalysisViewParent } from "./analysisViewParent.js"; +import { + assertOwnedView, + type AdmittedView, + type SummaryAnalysisView, +} from "./analysisViewShape.js"; import { completeWithinViewCoverage, pageViewCoverage, } from "./analysisViewCoverage.js"; import { qlogSummarySchema, + qlogViewRequestSchema, summarizeQlogCapture, projectQlogCapturePage, } from "./qlogCaptureView.js"; @@ -468,8 +473,8 @@ const parseCaptureParent = ( /** Page immutable retained facts; no capture file, provider or network is consulted. */ export const projectWebNetworkCaptureView = ( parent: AnalysisViewParent, - view: AnalysisViewRequest, -): Result => { + view: AdmittedView, +) => { if ( view.kind !== "summary" && view.kind !== "capture" && @@ -486,6 +491,12 @@ export const projectWebNetworkCaptureView = ( }, ]), ); + assertOwnedView< + | SummaryAnalysisView + | z.output + | z.output + | z.output + >(view, "summary", "capture", "protobuf", "qlog"); const parsed = parseCaptureParent(parent); if (!parsed.ok) return parsed; const report = parsed.value; @@ -519,7 +530,7 @@ export const projectWebNetworkCaptureView = ( }); if (view.kind === "summary") return ok({ - kind: "summary", + kind: "summary" as const, view, ...shared, summary: { @@ -558,7 +569,7 @@ export const projectWebNetworkCaptureView = ( const projected = projectQlogCapturePage(report.qlog, view); return projected.ok ? ok({ - kind: "qlog", + kind: "qlog" as const, view, ...shared, ...projected.value, @@ -571,7 +582,7 @@ export const projectWebNetworkCaptureView = ( } const records = report.records.slice(view.offset, view.offset + view.limit); return ok({ - kind: "capture", + kind: "capture" as const, view, ...shared, items: captureViewItemsSchema.parse(