Files
reverse-engineering-anything/scripts/verify/managed/manifest-parser.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

260 lines
7.0 KiB
JavaScript

import { isRecord } from "#dist/domain/isRecord.js";
/** @typedef {ReturnType<typeof parseManagedAppManifest>} ManagedAppManifest */
/** @typedef {ManagedAppManifest["methods"][number]} ManagedAppManifestMethod */
/** @typedef {NonNullable<ManagedAppManifest["application_graph"]>} ManagedAppManifestGraph */
/**
* Parse a caller-selected managed app manifest into its checked expectations.
* @param {unknown} rawManifest
*/
export function parseManagedAppManifest(rawManifest) {
const manifest = object(rawManifest, "manifest");
const target = object(manifest.target, "manifest.target");
const methods = array(manifest.methods, "manifest.methods");
ensure(methods.length > 0, "manifest.methods must not be empty");
return {
label: optionalString(manifest.label, "manifest.label"),
target: {
path: string(target.path, "manifest.target.path"),
sha256: digest(target.sha256, "manifest.target.sha256"),
mvid: optionalCliMetadataGuid(target.mvid, "manifest.target.mvid"),
assembly_name: optionalString(
target.assembly_name,
"manifest.target.assembly_name",
),
runtime_family: optionalString(
target.runtime_family,
"manifest.target.runtime_family",
),
managed_architecture: optionalString(
target.managed_architecture,
"manifest.target.managed_architecture",
),
},
methods: methods.map((method, index) =>
parseManagedAppManifestMethod(method, index),
),
application_graph: parseManagedAppManifestGraph(manifest.application_graph),
};
}
/** @param {unknown} rawGraph */
function parseManagedAppManifestGraph(rawGraph) {
if (rawGraph === undefined) return undefined;
const graph = object(rawGraph, "manifest.application_graph");
const expectedKinds =
graph.expected_node_kinds === undefined
? []
: array(
graph.expected_node_kinds,
"manifest.application_graph.expected_node_kinds",
).map((kind, index) =>
string(
kind,
`manifest.application_graph.expected_node_kinds[${String(index)}]`,
),
);
const traces =
graph.feature_traces === undefined
? []
: array(
graph.feature_traces,
"manifest.application_graph.feature_traces",
).map((trace, index) => parseManagedAppManifestTrace(trace, index));
ensure(
expectedKinds.length > 0 || traces.length > 0,
"manifest.application_graph must declare expected_node_kinds or feature_traces",
);
return {
expected_node_kinds: expectedKinds,
feature_traces: traces,
};
}
/**
* @param {unknown} rawTrace
* @param {number} index
*/
function parseManagedAppManifestTrace(rawTrace, index) {
const prefix = `manifest.application_graph.feature_traces[${String(index)}]`;
const trace = object(rawTrace, prefix);
const match = trace.match ?? "exact";
ensure(
match === "exact" || match === "contains",
`${prefix}.match must be exact or contains`,
);
const caseSensitive = trace.case_sensitive ?? true;
ensure(
typeof caseSensitive === "boolean",
`${prefix}.case_sensitive must be a boolean`,
);
const minMatchedSeeds = trace.min_matched_seeds ?? 1;
ensure(
typeof minMatchedSeeds === "number" &&
Number.isInteger(minMatchedSeeds) &&
minMatchedSeeds > 0,
`${prefix}.min_matched_seeds must be a positive integer`,
);
return {
label: optionalString(trace.label, `${prefix}.label`),
method_token: methodToken(trace.method_token, `${prefix}.method_token`),
seed: string(trace.seed, `${prefix}.seed`),
match,
case_sensitive: caseSensitive,
min_matched_seeds: minMatchedSeeds,
};
}
/**
* @param {unknown} rawMethod
* @param {number} index
*/
function parseManagedAppManifestMethod(rawMethod, index) {
const prefix = `manifest.methods[${String(index)}]`;
const method = object(rawMethod, prefix);
const token = methodToken(method.token, `${prefix}.token`);
return {
label: optionalString(method.label, `${prefix}.label`),
token,
signature_sha256: digest(
method.signature_sha256,
`${prefix}.signature_sha256`,
),
il_size: nonNegativeInteger(method.il_size, `${prefix}.il_size`),
il_sha256:
method.il_sha256 === undefined
? undefined
: digest(method.il_sha256, `${prefix}.il_sha256`),
normalized_il_sha256: digest(
method.normalized_il_sha256,
`${prefix}.normalized_il_sha256`,
),
};
}
/**
* @param {unknown} value
* @param {string} name
* @returns {{ readonly [key: string]: unknown }}
*/
function object(value, name) {
ensure(isRecord(value), `${name} must be an object`);
return value;
}
/**
* @param {unknown} value
* @param {string} name
* @returns {readonly unknown[]}
*/
function array(value, name) {
ensure(Array.isArray(value), `${name} must be an array`);
return value;
}
/**
* @param {unknown} value
* @param {string} name
* @returns {string}
*/
function string(value, name) {
ensure(
typeof value === "string" && value.length > 0,
`${name} must be a non-empty string`,
);
return value;
}
/**
* @param {unknown} value
* @param {string} name
*/
function optionalString(value, name) {
if (value === undefined) return undefined;
return string(value, name);
}
/**
* @param {unknown} value
* @param {string} name
* @returns {number}
*/
function nonNegativeInteger(value, name) {
ensure(
typeof value === "number" && Number.isInteger(value) && value >= 0,
`${name} must be a non-negative integer`,
);
return value;
}
/**
* @param {unknown} value
* @param {string} name
*/
function digest(value, name) {
const text = string(value, name);
ensure(/^[a-f0-9]{64}$/u.test(text), `${name} must be a lowercase sha256`);
return text;
}
/**
* @param {unknown} value
* @param {string} name
*/
function optionalCliMetadataGuid(value, name) {
if (value === undefined) return undefined;
if (value === null) return null;
const text = string(value, name);
ensure(
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(
text,
),
`${name} must be a lowercase GUID`,
);
return text;
}
/**
* @param {unknown} value
* @param {string} name
*/
function metadataToken(value, name) {
const text = string(value, name);
ensure(/^0x[0-9a-f]{8}$/u.test(text), `${name} must be a metadata token`);
return text;
}
/**
* @param {unknown} value
* @param {string} name
*/
function methodToken(value, name) {
const token = metadataToken(value, name);
ensure(
token.startsWith("0x06"),
`${name} must be a MethodDef token beginning with 0x06`,
);
return token;
}
/**
* The MethodDef row a checked method token names.
* @param {string} token
*/
export function methodTokenRow(token) {
const row = Number.parseInt(token.slice(4), 16);
ensure(row > 0, `method token ${token} has an invalid row id`);
return row;
}
/**
* @param {unknown} condition
* @param {string} message
* @returns {asserts condition}
*/
export function ensure(condition, message) {
if (!condition)
throw new Error(`managed app manifest verification failed: ${message}`);
}