Files
reverse-engineering-anything/src/contracts/toolEffects.test.ts
T
morluto 570658e941 test(contracts): derive tool-name oracles from their contract owners (#10787)
* test(contracts): derive tool-name oracles from their contract owners

toolEffects.test.ts kept a hand-sorted copy of the destructive tools that
every effects change had to re-record; the effects-to-annotation properties
beside it already check what the copy asserted. adbMcp.test.ts listed the
ADB tools by hand; derive them from ADB_TOOL_CONTRACTS so a new ADB tool is
checked for advertisement without a test edit.

Refs #10511

* test(contracts): keep reviewed destructive tools in a shrink-only baseline

Deleting the hand list left no test failing when a tool lost its destructive
effect. Derive each tool's destructiveHint from its audited effects and
contract, and require every name in the reviewed, sorted baseline to stay
destructive; the derived set may grow, but a tool leaves only by an explicit
baseline edit.

Refs #10511
2026-11-15 15:22:15 +08:00

192 lines
5.7 KiB
TypeScript

import { readFileSync } from "node:fs";
import { describe, expect, it } from "vitest";
import { TOOL_CONTRACTS } from "./toolContracts.js";
import {
TOOL_EFFECTS,
annotationsFromEffects,
toolSessionEffects,
type ToolEffects,
} from "./toolEffects.js";
/**
* Reviewed tools whose audited effects make them destructive. The derived set
* may grow without an edit here, but a tool leaves only by removing its name
* from this sorted file, so a dropped destructive effect is a deliberate,
* reviewed change rather than a silent loss of the client's confirmation.
*/
const REVIEWED_DESTRUCTIVE_TOOLS = JSON.parse(
readFileSync(
new URL("./destructiveTools.baseline.json", import.meta.url),
"utf8",
),
) as readonly string[];
describe("tool effects", () => {
it("keeps every reviewed destructive tool destructive", () => {
expect(REVIEWED_DESTRUCTIVE_TOOLS).toEqual(
[...new Set(REVIEWED_DESTRUCTIVE_TOOLS)].sort(),
);
const contracts = new Map<string, (typeof TOOL_CONTRACTS)[number]>(
TOOL_CONTRACTS.map((contract) => [contract.name, contract]),
);
for (const name of REVIEWED_DESTRUCTIVE_TOOLS) {
const contract = contracts.get(name);
expect(contract, `${name} has no contract`).toBeDefined();
expect(annotationsFromEffects(TOOL_EFFECTS[name]!), name).toMatchObject({
readOnlyHint: false,
destructiveHint: true,
});
expect(contract!.annotations, name).toMatchObject({
readOnlyHint: false,
destructiveHint: true,
});
}
});
it("declares the web bundle worker's private file and child process effects", () => {
const contract = TOOL_CONTRACTS.find(
({ name }) => name === "analyze_web_bundle",
);
expect(contract?.effects).toMatchObject({
mutatesSession: true,
accessesNetwork: true,
launchesProcess: true,
writesFilesystem: true,
executesForeignCode: false,
mutatesTarget: false,
});
});
it("derives destructiveHint from each destructive effect alone", () => {
// Keep annotation algebra independent of any operation's audited effects.
const base: ToolEffects = {
mutatesTarget: false,
mutatesSession: false,
writesFilesystem: false,
launchesProcess: false,
accessesNetwork: false,
changesUiState: false,
mayDiscardData: false,
executesForeignCode: false,
mutatesDevice: false,
idempotent: true,
};
expect(annotationsFromEffects(base)).toEqual({
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false,
});
for (const flag of [
"mayDiscardData",
"executesForeignCode",
"mutatesDevice",
] as const)
expect(annotationsFromEffects({ ...base, [flag]: true }), flag).toEqual({
readOnlyHint: false,
destructiveHint: true,
idempotentHint: true,
openWorldHint: false,
});
});
it("marks automatic GDB detach as destructive target execution", () => {
const effects = TOOL_EFFECTS["close_gdb_session"];
if (effects === undefined)
throw new Error("close_gdb_session is unaudited");
expect(effects).toMatchObject({
mutatesTarget: true,
executesForeignCode: true,
});
expect(annotationsFromEffects(effects).destructiveHint).toBe(true);
});
it("publishes the advertised annotations derived from canonical effects", () => {
for (const contract of TOOL_CONTRACTS)
expect(contract.annotations, contract.name).toEqual(
annotationsFromEffects(contract.effects),
);
});
});
it("advertises IDA provider effects while retaining session bases", () => {
for (const name of [
"procedure_pseudo_code",
"procedure_assembly",
"read_function_instructions",
"analyze_function",
]) {
expect(TOOL_EFFECTS[name], name).toMatchObject({
mutatesSession: true,
changesUiState: true,
accessesNetwork: true,
});
expect(toolSessionEffects(name), name).toMatchObject({
mutatesSession: true,
changesUiState: false,
accessesNetwork: false,
});
const contract = TOOL_CONTRACTS.find(
(candidate) => candidate.name === name,
);
expect(contract?.annotations, name).toMatchObject({
readOnlyHint: false,
destructiveHint: false,
openWorldHint: true,
});
}
for (const name of [
"batch_decompile",
"decompile_all",
"trace_native_values",
"inspect_native_api",
]) {
expect(TOOL_EFFECTS[name], name).toMatchObject({
changesUiState: true,
accessesNetwork: true,
});
expect(toolSessionEffects(name), name).toMatchObject({
changesUiState: false,
accessesNetwork: false,
});
}
});
it("audits network access during lifecycle cleanup across provider changes", () => {
for (const name of [
"open_binary",
"open_bundle_resources",
"close_binary",
"reset_investigation",
"start_rizin_debug_session",
"close_rizin_debug_session",
"close_gdb_session",
]) {
expect(toolSessionEffects(name).accessesNetwork, name).toBe(true);
expect(TOOL_EFFECTS[name]?.accessesNetwork, name).toBe(true);
expect(
TOOL_CONTRACTS.find((contract) => contract.name === name)?.annotations
.openWorldHint,
name,
).toBe(true);
}
});
it("advertises signature inspection's temporary snapshot filesystem writes", () => {
expect(TOOL_EFFECTS.inspect_signature).toMatchObject({
writesFilesystem: true,
mutatesTarget: false,
launchesProcess: true,
});
});
it("advertises inspect_macho's temporary private operand filesystem writes", () => {
expect(TOOL_EFFECTS.inspect_macho).toMatchObject({
writesFilesystem: true,
mutatesTarget: false,
launchesProcess: true,
});
});