import { z } from "zod"; import type { JsonValue } from "./jsonValue.js"; import { AnalysisOutputError, HopperProtocolError } from "./errors.js"; import { err, ok, type Result } from "./result.js"; import { nativeApiBoundarySchema } from "./nativeApiBoundary.js"; export interface AddressedName { readonly address: string; readonly name: string; } export interface SegmentSummary { readonly name: string; readonly start: string; readonly end: string; readonly readable: boolean | null; readonly writable: boolean | null; readonly executable: boolean | null; } /** Return a bounded byte distance between canonical addresses in one space. */ export const addressDistance = (start: string, end: string): number => { const left = addressCoordinate(start); const right = addressCoordinate(end); if (left === null || right === null || left.space !== right.space) return 0; const distance = right.offset - left.offset; if (distance <= 0n) return 0; return Number( distance > BigInt(Number.MAX_SAFE_INTEGER) ? BigInt(Number.MAX_SAFE_INTEGER) : distance, ); }; const addressCoordinate = ( value: string, ): { readonly space: string; readonly offset: bigint } | null => { const separator = value.lastIndexOf(":0x"); const space = separator < 0 ? "default" : value.slice(0, separator); const offset = separator < 0 ? value : value.slice(separator + 1); if (!/^0x[0-9a-f]+$/u.test(offset)) return null; return { space, offset: BigInt(offset) }; }; const procedureMapSchema = z.record(z.string(), z.string()); const addressedNamesSchema = z.array( z.object({ address: z.string(), name: z.string() }), ); const addressedNameMapSchema = z.record(z.string(), z.string()); const segmentSchema = z.object({ name: z.string().default(""), start: z.string().default(""), end: z.string().default(""), readable: z.boolean().nullable().default(null), writable: z.boolean().nullable().default(null), executable: z.boolean().nullable().default(null), }); const unavailableAnalysisFactSchema = z .object({ available: z.literal(false), reason: z.string() }) .strict(); export const procedureClassificationSchema = z .object({ external: z.boolean(), thunk: z.boolean(), thunk_target: z.string().nullable(), provenance: z.string().min(1), }) .strict(); export const procedureIdentitySchema = z .object({ address: z.string(), name: z.string(), classification: procedureClassificationSchema.nullable().default(null), }) .strict(); export const localVariableSchema = z .object({ description: z.string(), provenance: z.string().min(1), }) .strict(); /** Provider-neutral complete raw-instruction list for one analyzed function. */ export const functionInstructionWindowSchema = z .object({ procedure: procedureIdentitySchema, instructions: z.array(z.string()), limitations: z.array(z.string()), }) .strict(); const availableReferenceKindSchema = z .object({ available: z.literal(true), provenance: z.string().min(1), type: z.string(), flow: z.boolean(), call: z.boolean(), jump: z.boolean(), data: z.boolean(), read: z.boolean(), write: z.boolean(), indirect: z.boolean(), computed: z.boolean(), conditional: z.boolean(), terminal: z.boolean(), primary: z.boolean(), operand_index: z.number().int(), external: z.boolean(), }) .strict(); export const referenceKindSchema = z.discriminatedUnion("available", [ unavailableAnalysisFactSchema, availableReferenceKindSchema, ]); const referenceEdgeSchema = z .object({ source_address: z.string(), target_address: z.string(), source_procedure: procedureIdentitySchema.nullable(), target_procedure: procedureIdentitySchema.nullable(), kind: referenceKindSchema, }) .strict(); export const functionDossierSchema = z .object({ procedure: z .object({ address: z.string(), name: z.string(), classification: procedureClassificationSchema.nullable().default(null), signature: z.string().nullable(), locals: z.array(localVariableSchema), }) .strict(), pseudocode: z.string(), assembly: z.array(z.string()), comments: z.array( z .object({ address: z.string(), kind: z.enum(["comment", "inline"]), text: z.string(), }) .strict(), ), callers: z.array(procedureIdentitySchema), callees: z.array(procedureIdentitySchema), incoming_references: z.array(referenceEdgeSchema), outgoing_references: z.array(referenceEdgeSchema), referenced_strings: z.array( z .object({ address: z.string(), value: z.string(), source_address: z.string(), }) .strict(), ), referenced_names: z.array( z .object({ address: z.string(), value: z.string(), source_address: z.string(), }) .strict(), ), basic_blocks: z.array( z .object({ start: z.string(), end: z.string(), successors: z.array(z.string()), }) .strict(), ), native_api: nativeApiBoundarySchema.nullable().default(null), limitations: z.array(z.string()).default([]), }) .strict(); /** Strict analyzed-function dossier shared by provider and comparison boundaries. */ export type FunctionDossier = z.infer; /** Strictly parse a complete provider-neutral function dossier. */ export const parseFunctionDossier = ( value: JsonValue, ): Result => { const parsed = functionDossierSchema.safeParse(value); return parsed.success ? ok(parsed.data) : err( new AnalysisOutputError( "analyze_function", "provider output did not match the dossier contract", { cause: parsed.error }, ), ); }; /** Parse Hopper's direct or wrapped procedure map into stable entries. */ export const parseProcedures = ( value: JsonValue, ): Result => { const parsed = procedureMapSchema.safeParse( unwrapProperty(value, "procedures"), ); return parsed.success ? ok( Object.entries(parsed.data).map(([address, name]) => ({ address, name, })), ) : invalid("procedure map", parsed.error); }; /** Parse Hopper's direct or wrapped list of address/name records. */ export const parseNames = ( value: JsonValue, ): Result => { const unwrapped = unwrapProperty(value, "names"); const page = z .object({ items: z.array(z.object({ address: z.string(), value: z.string() })), }) .safeParse(unwrapped); if (page.success) return ok( page.data.items.map(({ address, value: name }) => ({ address, name })), ); const records = addressedNamesSchema.safeParse(unwrapped); if (records.success) return ok(records.data); const map = addressedNameMapSchema.safeParse(unwrapped); return map.success ? ok(Object.entries(map.data).map(([address, name]) => ({ address, name }))) : invalid("name list", map.error); }; /** Parse callee/caller strings from direct or wrapped Hopper results. */ export const parseRelatedAddresses = ( value: JsonValue, relation: "callees" | "callers", ): Result => { const parsed = z.array(z.string()).safeParse(unwrapProperty(value, relation)); return parsed.success ? ok(parsed.data) : invalid(`${relation} list`, parsed.error); }; /** Parse direct or wrapped Hopper segment records. */ export const parseSegments = ( value: JsonValue, ): Result => { const parsed = z .array(segmentSchema) .safeParse(unwrapProperty(value, "segments")); return parsed.success ? ok(parsed.data) : invalid("segment list", parsed.error); }; /** Parse direct or wrapped Hopper document names. */ export const parseDocuments = ( value: JsonValue, ): Result => { const parsed = z .array(z.string()) .safeParse(unwrapProperty(value, "documents")); return parsed.success ? ok(parsed.data) : invalid("document list", parsed.error); }; /** Parse a direct or wrapped list when only its cardinality is required. */ export const parseListCount = ( value: JsonValue, property: string, ): Result => { const unwrapped = unwrapProperty(value, property); const list = z.array(z.unknown()).safeParse(unwrapped); if (list.success) return ok(list.data.length); const map = z.record(z.string(), z.unknown()).safeParse(unwrapped); return map.success ? ok(Object.keys(map.data).length) : invalid(`${property} list`, map.error); }; const unwrapProperty = (value: JsonValue, property: string): JsonValue => { if ( typeof value === "object" && value !== null && !Array.isArray(value) && property in value ) { return value[property] ?? null; } return value; }; const invalid = ( expected: string, cause: z.ZodError, ): Result => err( new HopperProtocolError(`Hopper returned an invalid ${expected}`, { cause, }), );