Files
reverse-engineering-anything/scripts/lib/mcp-verifier-results.mjs
T
morluto b3ca03972a build(scripts): type-check the Evidence verification scripts against src (#11579)
* build(scripts): type-check the Evidence verification scripts against src

Six JavaScript callers kept passing `undefined` as an Evidence subject
after `createEvidence` stopped accepting it (#11536); `npm run typecheck`
saw only the TypeScript callers. The scripts import built modules by
relative `../dist/` paths, which a checker resolves to the built JavaScript
(or nothing, before a build) rather than the source types.

A package-private `#dist/*` import alias resolves to `./dist/*` at run
time, and `tsconfig.scripts.json` maps it to `./src/*` and checks the
listed scripts with `checkJs` under the main compiler options. `typecheck`,
and so `check:fast`, runs it; turbo's typecheck inputs include the scripts
and the new config.

First slice: `verify-package-evidence.mjs` (its evidence-bundle import
becomes static), `verify/javascript/output.mjs` and
`verify/javascript/digests.mjs`, with the JSDoc types the check required.

Refs #11545

* build(scripts): type-check the MCP verifier results and Ghidra snapshot lifecycle helpers (#11590)

* build(scripts): type-check the managed app manifest verifier (#11592)

* build(scripts): type-check the managed oracles and completion report (#11605)

oracles.mjs and completion-report.mjs join tsconfig.scripts.json (72 errors). ensureIlspy is an assertion function, the ILSpy import returns the imported Evidence and reads its normalized result through managedReconstructionImportResultSchema, the manifest-rejection controls are named records walked by a checked field lookup, and the completion report names its input.
2026-11-16 08:04:12 +08:00

354 lines
12 KiB
JavaScript

import { isDeepStrictEqual } from "node:util";
import { z } from "zod";
import { authenticateParsedEvidenceBundle } from "#dist/domain/evidenceBundle.js";
import { analysisErrorProjectionSchema } from "#dist/domain/analysisErrorProjectionSchema.js";
import { toolContract } from "#dist/contracts/toolContracts.js";
import {
expandProviderCapabilities,
expandToolAvailability,
providerCapabilitySet,
} from "#dist/contracts/toolOutputSchemaPrimitives.js";
import { compareUnicodeCodePoints } from "#dist/domain/unicodeCodePointOrder.js";
/** @typedef {import("@modelcontextprotocol/client").CallToolResult} CallToolResult */
/** @typedef {(typeof import("#dist/contracts/toolContracts.js").TOOL_CONTRACTS)[number]} PublicToolContract */
/** @typedef {PublicToolContract["name"]} ToolName */
/**
* @template {ToolName} N
* @typedef {Extract<PublicToolContract, { readonly name: N }>} NamedToolContract
*/
/**
* @template {PublicToolContract} C
* @typedef {z.output<C["outputSchema"]>} ToolOutput
*/
/**
* The member an MCP verifier projects: Evidence `normalized_result` or
* lifecycle `result`.
* @template {PublicToolContract} C
* @typedef {ToolOutput<C> extends { readonly normalized_result: infer R }
* ? R
* : ToolOutput<C> extends { readonly result: infer R }
* ? R
* : never} OperationResult
*/
/** @typedef {OperationResult<NamedToolContract<"binary_session">>} SessionStatus */
/**
* Session status as verifiers read it, with compact capability and tool
* groups expanded.
* @typedef {ReturnType<typeof expandMcpSessionStatus>} ExpandedSessionStatus
*/
/**
* @template {ToolName} N
* @typedef {N extends "binary_session"
* ? ExpandedSessionStatus
* : OperationResult<NamedToolContract<N>>} VerifierOperationResult
*/
/**
* Read the textual JSON projection from one MCP tool call.
* @param {CallToolResult} result
* @returns {string}
*/
export const mcpTextValue = (result) => {
const text = result.content.find((item) => item.type === "text")?.text;
if (typeof text !== "string") throw new Error("Tool result omitted text");
return text;
};
/**
* @param {CallToolResult} result
* @returns {unknown}
*/
const jsonValue = (result) => JSON.parse(mcpTextValue(result));
/**
* Sort canonical contract names using REA's code-point ordering.
* @param {Iterable<string>} names
* @returns {string[]}
*/
export const sortVerifierNames = (names) =>
[...names].sort(compareUnicodeCodePoints);
const toolErrorEnvelope = z.object({ error: z.unknown() });
/**
* Read the complete canonical diagnostic from an MCP tool failure.
* @param {CallToolResult} result
*/
export const requireMcpToolError = (result) => {
if (result.isError !== true) throw new Error("Expected an MCP tool failure");
return analysisErrorProjectionSchema.parse(
toolErrorEnvelope.parse(jsonValue(result)).error,
);
};
/**
* Validate the complete output against its exact named contract, retaining
* inline Evidence. Evidence outputs return the unprojected JSON value that
* satisfied the contract, so downstream parseEvidence authenticates source
* facts rather than a schema projection.
* @template {ToolName} N
* @param {CallToolResult} result
* @param {N} operation
* @param {NamedToolContract<N>} [contract]
* @returns {ToolOutput<NamedToolContract<N>>}
*/
export const requireMcpOutput = (
result,
operation,
contract = toolContract(operation),
) => {
if (result.isError === true)
throw new Error(`${operation} failed: ${mcpTextValue(result)}`);
if (contract.name !== operation)
throw new Error(`${operation} received the ${contract.name} contract`);
const text = jsonValue(result);
// parse on a contract union widens to every contract's output; the guard
// above bound this contract to the operation's name.
const output = /** @type {ToolOutput<NamedToolContract<N>>} */ (
contract.outputSchema.parse(text)
);
if (result.structuredContent !== undefined) {
// The producer emits both representations from the same JSON value.
// Compare before schema projection can discard disagreeing source fields.
if (!isDeepStrictEqual(text, result.structuredContent))
throw new Error(`${operation} text and structured results disagree`);
}
return Object.hasOwn(output, "normalized_result")
? /** @type {ToolOutput<NamedToolContract<N>>} */ (text)
: output;
};
/**
* @param {PublicToolContract} contract
* @returns {"normalized_result" | "result"}
*/
const operationResultKey = (contract) => {
const schema = contract.outputSchema;
if (!("shape" in schema))
throw new Error(`${contract.name} has an unsupported MCP output schema`);
const evidence = Object.hasOwn(schema.shape, "normalized_result");
const lifecycle = Object.hasOwn(schema.shape, "result");
if (evidence === lifecycle)
throw new Error(`${contract.name} has an unsupported MCP output schema`);
return evidence ? "normalized_result" : "result";
};
/**
* Expand compact session metadata once at the verifier boundary. The caller
* has validated the status against the binary_session contract, so a summary
* carries summary candidates without capability sets; complete detail must
* still expand every candidate's capabilities.
* @param {SessionStatus} status
*/
export const expandMcpSessionStatus = (status) => ({
...status,
capabilities: expandProviderCapabilities(status.capabilities),
analysis_provider_candidates:
status.detail === "summary"
? status.analysis_provider_candidates
: expandProviderCandidates(status.analysis_provider_candidates),
tool_availability: expandToolAvailability(status.tool_availability),
});
/**
* Expand provider capability groups while retaining candidate identity/state.
* @template {{ readonly capabilities: unknown }} Candidate
* @param {readonly Candidate[]} candidates
*/
const expandProviderCandidates = (candidates) =>
candidates.map((candidate) => ({
...candidate,
capabilities: expandProviderCapabilities(
providerCapabilitySet.array().parse(candidate.capabilities),
),
}));
/**
* Expand CLI provider capability groups at the same owning boundary.
* @template {{
* readonly capabilities: unknown;
* readonly analysis_provider_candidates: readonly { readonly capabilities: unknown }[];
* }} Providers
* @param {Providers} providers
*/
export const expandProviderOutput = (providers) => ({
...providers,
capabilities: expandProviderCapabilities(
providerCapabilitySet.array().parse(providers.capabilities),
),
analysis_provider_candidates: expandProviderCandidates(
providers.analysis_provider_candidates,
),
});
/**
* Expand the CLI capabilities command's compact provider descriptor groups.
* @template {{ readonly capabilities: unknown }} Capabilities
* @param {Capabilities} capabilities
*/
export const expandCapabilitiesOutput = (capabilities) => ({
...capabilities,
capabilities: expandProviderCapabilities(
providerCapabilitySet.array().parse(capabilities.capabilities),
),
});
/**
* Validate an Evidence-producing tool output and return its normalized result.
* @template {ToolName} N
* @param {CallToolResult} result
* @param {N} operation
* @returns {OperationResult<NamedToolContract<N>>}
*/
export const requireMcpEvidenceResult = (result, operation) => {
const contract = toolContract(operation);
if (operationResultKey(contract) !== "normalized_result")
throw new Error(`${operation} requires the lifecycle result extractor`);
return projectOperationResult(
requireMcpOutput(result, operation, contract),
"normalized_result",
);
};
/**
* Validate a lifecycle tool output and return its operation result.
* @template {ToolName} N
* @param {CallToolResult} result
* @param {N} operation
* @returns {VerifierOperationResult<N>}
*/
export const requireMcpLifecycleResult = (result, operation) => {
const contract = toolContract(operation);
if (operationResultKey(contract) !== "result")
throw new Error(`${operation} requires the Evidence result extractor`);
return expandOperationResult(
operation,
projectOperationResult(
requireMcpOutput(result, operation, contract),
"result",
),
);
};
/**
* Require an authenticated complete bundle without changing summary-capable readers.
* @param {CallToolResult} result
*/
export const requireMcpEvidenceBundle = (result) => {
const bundle = requireMcpOutput(result, "get_evidence_bundle").result;
if ("kind" in bundle)
throw new Error(
"get_evidence_bundle returned summary metadata instead of complete Evidence",
);
return authenticateParsedEvidenceBundle(bundle);
};
/**
* Project a mixed verifier call using its exact named canonical output schema.
* @template {ToolName} N
* @param {CallToolResult} result
* @param {N} operation
* @param {NamedToolContract<N>} [contract]
* @returns {VerifierOperationResult<N>}
*/
export const requireMcpOperationResult = (
result,
operation,
contract = toolContract(operation),
) =>
expandOperationResult(
operation,
projectOperationResult(
requireMcpOutput(result, operation, contract),
operationResultKey(contract),
),
);
/**
* Read the member that operationResultKey selected from the contract.
* @template {PublicToolContract} C
* @param {ToolOutput<C>} output
* @param {"normalized_result" | "result"} key
* @returns {OperationResult<C>}
*/
const projectOperationResult = (output, key) =>
/** @type {Record<typeof key, OperationResult<C>>} */ (output)[key];
/**
* @template {ToolName} N
* @param {N} operation
* @param {OperationResult<NamedToolContract<N>>} projected
* @returns {VerifierOperationResult<N>}
*/
const expandOperationResult = (operation, projected) =>
/** @type {VerifierOperationResult<N>} */ (
operation === "binary_session"
? expandMcpSessionStatus(/** @type {SessionStatus} */ (projected))
: projected
);
const providerReference = z.object({ id: z.string() });
const versionedProviderReference = z.object({
id: z.string(),
version: z.string(),
});
const providerProvenance = z.object({
provider: providerReference,
analysis_profile: z.object({ provider: versionedProviderReference }),
});
const workflowProvenance = z.object({
provider: providerReference,
analysis_profile: z.object({
provider: providerReference,
parameters: z.object({
upstream_analysis_profile: z.object({
provider: versionedProviderReference,
}),
}),
}),
});
/**
* Verify provider identity directly from the tool result.
* @param {CallToolResult} result
* @param {string} operation
* @param {string} providerId
*/
export const requireEvidenceProvider = (result, operation, providerId) => {
const evidence = providerProvenance.safeParse(jsonValue(result));
if (
!evidence.success ||
evidence.data.provider.id !== providerId ||
evidence.data.analysis_profile.provider.id !== providerId
) {
throw new Error(`${operation} omitted its concrete provider provenance`);
}
};
/**
* Verify composed workflow and upstream provider provenance inline.
* @param {CallToolResult} result
* @param {string} operation
* @param {{ readonly workflowProviderId: string; readonly upstreamProviderId: string }} expected
*/
export const requireWorkflowEvidenceProvider = (
result,
operation,
expected,
) => {
const evidence = workflowProvenance.safeParse(jsonValue(result));
if (
!evidence.success ||
evidence.data.provider.id !== expected.workflowProviderId ||
evidence.data.analysis_profile.provider.id !==
expected.workflowProviderId ||
evidence.data.analysis_profile.parameters.upstream_analysis_profile.provider
.id !== expected.upstreamProviderId
) {
throw new Error(
`${operation} omitted its composed workflow or upstream provenance`,
);
}
};