311 lines
9.1 KiB
TypeScript
311 lines
9.1 KiB
TypeScript
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<typeof functionDossierSchema>;
|
|
|
|
/** Strictly parse a complete provider-neutral function dossier. */
|
|
export const parseFunctionDossier = (
|
|
value: JsonValue,
|
|
): Result<JsonValue, AnalysisOutputError> => {
|
|
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<readonly AddressedName[], HopperProtocolError> => {
|
|
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<readonly AddressedName[], HopperProtocolError> => {
|
|
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<readonly string[], HopperProtocolError> => {
|
|
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<readonly SegmentSummary[], HopperProtocolError> => {
|
|
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<readonly string[], HopperProtocolError> => {
|
|
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<number, HopperProtocolError> => {
|
|
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 = <T>(
|
|
expected: string,
|
|
cause: z.ZodError,
|
|
): Result<T, HopperProtocolError> =>
|
|
err(
|
|
new HopperProtocolError(`Hopper returned an invalid ${expected}`, {
|
|
cause,
|
|
}),
|
|
);
|