Files
reverse-engineering-anything/scripts/fixtures/managed/pe.mjs
T
morluto 0ef08895f1 build(scripts): use JSDoc in .mjs files as the single type source (#11769)
* build(scripts): use JSDoc in .mjs files as the single type source

Fixes #11616

Refs #11545

* test(verify): cover sibling declaration rejection for typed scripts
2026-11-16 14:58:17 -05:00

639 lines
19 KiB
JavaScript

import { Buffer } from "node:buffer";
/**
* @typedef {{
* readonly body?: Buffer;
* readonly flags?: number;
* readonly implFlags?: number;
* readonly name: string;
* readonly rva?: number;
* }} ManagedPeFixtureMethod
*/
/**
* @typedef {{
* readonly cliFlags?: number;
* readonly corruptMetadataSignature?: boolean;
* readonly fieldName?: string;
* readonly fields?: readonly {
* readonly name: string;
* readonly flags?: number;
* readonly signature?: Buffer;
* }[];
* readonly constants?: readonly {
* readonly typeCode: number;
* readonly padding?: number;
* readonly parentRaw?: number;
* readonly value: Buffer;
* }[];
* readonly ilBody?: Buffer;
* readonly machine?: number;
* readonly metadataValidMaskExtra?: bigint;
* readonly methodImplFlags?: number;
* readonly methodName?: string;
* readonly methods?: readonly ManagedPeFixtureMethod[];
* readonly mvid?: Buffer;
* readonly pinvoke?: {
* readonly importName?: string;
* readonly mappingFlags?: number;
* readonly memberRow?: number;
* readonly moduleName?: string;
* };
* readonly readyToRun?: boolean;
* readonly references?: readonly string[];
* readonly resourceData?: Buffer;
* readonly targetFramework?: string | null;
* readonly typeName?: string;
* readonly typeNamespace?: string;
* }} ManagedPeFixtureOptions
*/
/** A method whose metadata row has an RVA. @typedef {ManagedPeFixtureMethod & { readonly rva: number }} PlacedFixtureMethod */
const textEncoder = new TextEncoder();
const DEFAULT_MVID = Buffer.from([
0x33, 0x22, 0x11, 0x00, 0x55, 0x44, 0x77, 0x66, 0x88, 0x99, 0xaa, 0xbb, 0xcc,
0xdd, 0xee, 0xff,
]);
/** @param {number} value */
const align4 = (value) => (value + 3) & ~3;
/** @param {string} value */
const cString = (value) => Buffer.from(`${value}\0`, "utf8");
class StringHeap {
/** @type {Buffer[]} */
#chunks = [Buffer.from([0])];
#size = 1;
/** @param {string} value */
add(value) {
if (value.length === 0) return 0;
const index = this.#size;
const chunk = cString(value);
this.#chunks.push(chunk);
this.#size += chunk.length;
return index;
}
toBuffer() {
return Buffer.concat(this.#chunks);
}
}
class BlobHeap {
/** @type {Buffer[]} */
#chunks = [Buffer.from([0])];
#size = 1;
/** @param {Buffer} value */
add(value) {
if (value.length === 0) return 0;
if (value.length > 0x7f)
throw new RangeError("Managed PE fixture blob is too large");
const index = this.#size;
this.#chunks.push(Buffer.from([value.length]), value);
this.#size += value.length + 1;
return index;
}
toBuffer() {
return Buffer.concat(this.#chunks);
}
}
/** @param {number} value */
const u16 = (value) => {
const bytes = Buffer.alloc(2);
bytes.writeUInt16LE(value, 0);
return bytes;
};
/** @param {number} value */
const u32 = (value) => {
const bytes = Buffer.alloc(4);
bytes.writeUInt32LE(value, 0);
return bytes;
};
/** @param {Buffer} [mvid] */
const guidHeap = (mvid = DEFAULT_MVID) => {
if (mvid.length !== 16)
throw new RangeError("Managed PE fixture MVID must be 16 bytes");
return Buffer.from(mvid);
};
/** @param {number} name */
const moduleRow = (name) =>
Buffer.concat([u16(0), u16(name), u16(1), u16(0), u16(0)]);
/**
* @param {number} name
* @param {number} namespace
*/
const typeRefRow = (name, namespace) =>
Buffer.concat([u16(0), u16(name), u16(namespace)]);
/**
* @param {number} name
* @param {number} namespace
* @param {number} fieldList
* @param {number} methodList
*/
const typeDefRow = (name, namespace, fieldList, methodList) =>
Buffer.concat([
u32(0x0010_0001),
u16(name),
u16(namespace),
u16((1 << 2) | 1),
u16(fieldList),
u16(methodList),
]);
/**
* @param {number} name
* @param {number} signature
* @param {number} [flags]
*/
const fieldRow = (name, signature, flags = 0x0001) =>
Buffer.concat([u16(flags), u16(name), u16(signature)]);
/**
* @param {{
* readonly flags?: number;
* readonly implFlags?: number;
* readonly name: number;
* readonly rva: number;
* readonly signature: number;
* }} row
*/
const methodDefRow = ({
flags = 0x0016,
implFlags = 0,
name,
rva,
signature,
}) =>
Buffer.concat([
u32(rva),
u16(implFlags),
u16(flags),
u16(name),
u16(signature),
u16(0),
]);
/**
* @param {number} name
* @param {number} signature
*/
const memberRefRow = (name, signature) =>
Buffer.concat([u16((1 << 3) | 1), u16(name), u16(signature)]);
/** @param {number} name */
const moduleRefRow = (name) => Buffer.concat([u16(name)]);
/**
* @param {number} importName
* @param {number} importScope
* @param {number} mappingFlags
* @param {number} [memberRow]
*/
const implMapRow = (importName, importScope, mappingFlags, memberRow = 1) =>
Buffer.concat([
u16(mappingFlags),
u16((memberRow << 1) | 1),
u16(importName),
u16(importScope),
]);
/** @param {number} name */
const assemblyRow = (name) =>
Buffer.concat([
u32(0x0000_8004),
u16(1),
u16(2),
u16(3),
u16(4),
u32(0),
u16(0),
u16(name),
u16(0),
]);
/**
* @param {number} name
* @param {number} keyOrToken
*/
const assemblyRefRow = (name, keyOrToken) =>
Buffer.concat([
u16(8),
u16(0),
u16(0),
u16(0),
u32(0),
u16(keyOrToken),
u16(name),
u16(0),
u16(0),
]);
/** @param {number} value */
const customAttributeRow = (value) =>
Buffer.concat([u16((1 << 5) | 14), u16((1 << 3) | 3), u16(value)]);
/** @param {number} name */
const manifestResourceRow = (name) =>
Buffer.concat([u32(0), u32(2), u16(name), u16(0)]);
/** @param {string} value */
const fixedStringAttributeBlob = (value) => {
const bytes = Buffer.from(textEncoder.encode(value));
if (bytes.length > 0x7f)
throw new RangeError("Managed PE fixture target framework is too long");
return Buffer.concat([Buffer.from([1, 0, bytes.length]), bytes, u16(0)]);
};
/**
* @param {number} relativeOffset
* @param {number} size
* @param {string} name
*/
const metadataStreamHeader = (relativeOffset, size, name) => {
const named = cString(name);
const paddedName = Buffer.alloc(align4(named.length));
named.copy(paddedName);
return Buffer.concat([u32(relativeOffset), u32(size), paddedName]);
};
/**
* @param {Buffer} tables
* @param {Buffer} strings
* @param {Buffer} guid
* @param {Buffer} blob
*/
const metadataRoot = (tables, strings, guid, blob) => {
const version = Buffer.from("v4.0.30319\0\0", "utf8");
const header = Buffer.concat([
u32(0x424a_5342),
u16(1),
u16(1),
u32(0),
u32(version.length),
version,
u16(0),
u16(4),
]);
const streamHeaderSize =
metadataStreamHeader(0, 0, "#~").length +
metadataStreamHeader(0, 0, "#Strings").length +
metadataStreamHeader(0, 0, "#GUID").length +
metadataStreamHeader(0, 0, "#Blob").length;
let offset = align4(header.length + streamHeaderSize);
const tablesOffset = offset;
offset = align4(offset + tables.length);
const stringsOffset = offset;
offset = align4(offset + strings.length);
const guidOffset = offset;
offset = align4(offset + guid.length);
const blobOffset = offset;
const headers = Buffer.concat([
metadataStreamHeader(tablesOffset, tables.length, "#~"),
metadataStreamHeader(stringsOffset, strings.length, "#Strings"),
metadataStreamHeader(guidOffset, guid.length, "#GUID"),
metadataStreamHeader(blobOffset, blob.length, "#Blob"),
]);
const root = Buffer.alloc(align4(blobOffset + blob.length));
header.copy(root, 0);
headers.copy(root, header.length);
tables.copy(root, tablesOffset);
strings.copy(root, stringsOffset);
guid.copy(root, guidOffset);
blob.copy(root, blobOffset);
return root;
};
/**
* @param {ReadonlyMap<number, readonly Buffer[]>} rows Rows by metadata table number.
* @param {bigint} [extraValidMask]
*/
const tablesStream = (rows, extraValidMask = 0n) => {
let valid = extraValidMask;
for (const table of rows.keys()) valid |= 1n << BigInt(table);
const header = Buffer.alloc(24);
header.writeUInt8(2, 4);
header.writeUInt8(1, 7);
header.writeBigUInt64LE(valid, 8);
const counts = [];
for (let index = 0; index <= 44; index += 1) {
const tableRows = rows.get(index);
if (tableRows !== undefined) counts.push(u32(tableRows.length));
}
const data = [];
for (let index = 0; index <= 44; index += 1) {
const tableRows = rows.get(index);
if (tableRows !== undefined) data.push(...tableRows);
}
return Buffer.concat([header, ...counts, ...data]);
};
const defaultIlBody = Buffer.from([
0x32, 0x02, 0x7b, 0x01, 0x00, 0x00, 0x04, 0x28, 0x01, 0x00, 0x00, 0x0a, 0x2a,
]);
const retOnlyIlBody = Buffer.from([0x2a]);
export const alternateMvid = Buffer.from([
0xde, 0xad, 0xbe, 0xef, 0x44, 0x33, 0x66, 0x55, 0xaa, 0xbb, 0xcc, 0xdd, 0xee,
0xff, 0x11, 0x22,
]);
/**
* The fixture's methods: the caller's, or one method from the single-method options.
* @param {ManagedPeFixtureOptions} options
* @returns {readonly ManagedPeFixtureMethod[]}
*/
const managedFixtureMethods = (options) =>
options.methods ?? [
{
name: options.methodName ?? "Main",
body: options.ilBody ?? defaultIlBody,
flags: options.pinvoke === undefined ? 0x0016 : 0x2016,
implFlags: options.methodImplFlags ?? 0,
},
];
/**
* @param {ManagedPeFixtureOptions} options
* @param {readonly PlacedFixtureMethod[]} methods
*/
const buildManagedMetadata = (options, methods) => {
const strings = new StringHeap();
const blobs = new BlobHeap();
const namedMethods = methods.map((method) => ({
method,
name: strings.add(method.name),
}));
const moduleName = strings.add("Fixture.dll");
const assemblyName = strings.add("Fixture.Managed");
const attributeName = strings.add("TargetFrameworkAttribute");
const attributeNamespace = strings.add("System.Runtime.Versioning");
const constructorName = strings.add(".ctor");
const typeName = strings.add(options.typeName ?? "Program");
const typeNamespace = strings.add(options.typeNamespace ?? "Fixture");
const fields = options.fields ?? [{ name: options.fieldName ?? "counter" }];
const namedFields = fields.map((field) => ({
field,
name: strings.add(field.name),
}));
const pinvokeModuleName =
options.pinvoke === undefined
? null
: strings.add(options.pinvoke.moduleName ?? "user32.dll");
const pinvokeImportName =
options.pinvoke === undefined
? null
: strings.add(options.pinvoke.importName ?? "MessageBoxW");
const resourceName = strings.add("Fixture.resources");
const referenceNames = options.references ?? ["System.Runtime"];
const referenceStringIndexes = referenceNames.map((name) =>
strings.add(name),
);
const tokenBlob = blobs.add(Buffer.from("b77a5c561934e089", "hex"));
const fieldRows = namedFields.map(({ field, name }) =>
fieldRow(
name,
blobs.add(field.signature ?? Buffer.from([0x06, 0x08])),
field.flags,
),
);
const constantRows = (options.constants ?? []).map((constant) =>
Buffer.concat([
Buffer.from([constant.typeCode, constant.padding ?? 0]),
u16(constant.parentRaw ?? 4),
u16(blobs.add(constant.value)),
]),
);
const methodSignature = blobs.add(Buffer.from([0x00, 0x00, 0x01]));
const constructorSignature = blobs.add(Buffer.from([0x20, 0x01, 0x01, 0x0e]));
const attributeBlob = blobs.add(
fixedStringAttributeBlob(
options.targetFramework ?? ".NETCoreApp,Version=v8.0",
),
);
const methodRows = namedMethods.map(({ method, name }) =>
methodDefRow({
name,
signature: methodSignature,
rva: method.rva,
flags: method.flags ?? 0x0016,
implFlags: method.implFlags ?? 0,
}),
);
// Rows by metadata table number; the stream orders tables by number.
/** @type {Map<number, Buffer[]>} */
const rows = new Map([
[0, [moduleRow(moduleName)]],
[1, [typeRefRow(attributeName, attributeNamespace)]],
[2, [typeDefRow(typeName, typeNamespace, 1, 1)]],
[4, fieldRows],
[6, methodRows],
[10, [memberRefRow(constructorName, constructorSignature)]],
[12, [customAttributeRow(attributeBlob)]],
[32, [assemblyRow(assemblyName)]],
[35, referenceStringIndexes.map((name) => assemblyRefRow(name, tokenBlob))],
[40, [manifestResourceRow(resourceName)]],
]);
if (constantRows.length > 0) rows.set(11, constantRows);
if (pinvokeModuleName !== null)
rows.set(26, [moduleRefRow(pinvokeModuleName)]);
if (pinvokeImportName !== null)
rows.set(28, [
implMapRow(
pinvokeImportName,
1,
options.pinvoke?.mappingFlags ?? 0x0344,
options.pinvoke?.memberRow ?? 1,
),
]);
const metadata = metadataRoot(
tablesStream(rows, options.metadataValidMaskExtra ?? 0n),
strings.toBuffer(),
guidHeap(options.mvid),
blobs.toBuffer(),
);
if (options.corruptMetadataSignature === true) metadata.writeUInt32LE(0, 0);
return metadata;
};
/**
* @param {number} value
* @param {number} boundary
*/
const align = (value, boundary) => Math.ceil(value / boundary) * boundary;
/**
* File offsets of each part; a method with RVA zero has no mapped body (`null`).
* @param {ManagedPeFixtureOptions} options
* @param {readonly ManagedPeFixtureMethod[]} methods
* @param {number} metadataLength
*/
const managedFixtureLayout = (options, methods, metadataLength) => {
const resourceLength =
4 + (options.resourceData ?? Buffer.from("resource-data")).length;
const metadataOffset = 0x0300;
const resourceOffset = Math.max(
0x0800,
align(metadataOffset + metadataLength, 0x200),
);
const readyToRunOffset = Math.max(
0x0900,
align(resourceOffset + resourceLength, 0x200),
);
/** @type {(number | null)[]} */
const methodOffsets = [];
let nextMethodOffset = Math.max(
0x0a00,
align(readyToRunOffset + (options.readyToRun === true ? 4 : 0), 0x200),
);
for (const method of methods) {
// RVA zero denotes a method without a mapped IL body, such as P/Invoke.
if (method.rva === 0) {
methodOffsets.push(null);
continue;
}
const offset =
method.rva === undefined
? nextMethodOffset
: 0x0200 + (method.rva - 0x2000);
methodOffsets.push(offset);
nextMethodOffset =
Math.max(offset, nextMethodOffset) +
align(Math.max(0x20, (method.body ?? retOnlyIlBody).length), 0x20);
}
return { metadataOffset, resourceOffset, readyToRunOffset, methodOffsets };
};
/**
* @param {ManagedPeFixtureOptions} options
* @param {readonly PlacedFixtureMethod[]} methods
* @param {Buffer} metadata
*/
const buildManagedImage = (options, methods, metadata) => {
const resourceData = options.resourceData ?? Buffer.from("resource-data");
const resourceDirectory = Buffer.concat([
u32(resourceData.length),
resourceData,
]);
const { metadataOffset, resourceOffset, readyToRunOffset, methodOffsets } =
managedFixtureLayout(options, methods, metadata.length);
const contentEnd = Math.max(
metadataOffset + metadata.length,
resourceOffset + resourceDirectory.length,
readyToRunOffset + (options.readyToRun === true ? 4 : 0),
...methods.flatMap((method, index) => {
const offset = methodOffsets[index];
return offset === null || offset === undefined
? []
: [offset + (method.body ?? retOnlyIlBody).length];
}),
0x1000,
);
const imageSize = align(contentEnd, 0x200);
const image = Buffer.alloc(imageSize);
image.write("MZ", 0, "ascii");
image.writeUInt32LE(0x80, 0x3c);
image.writeUInt32LE(0x0000_4550, 0x80);
const coff = 0x84;
const machine = options.machine ?? 0x014c;
const pe32Plus = machine === 0x8664 || machine === 0xaa64;
const optionalSize = pe32Plus ? 0x00f0 : 0x00e0;
const directoryOffset = pe32Plus ? 112 : 96;
image.writeUInt16LE(machine, coff);
image.writeUInt16LE(1, coff + 2);
image.writeUInt16LE(optionalSize, coff + 16);
image.writeUInt16LE(0x0102, coff + 18);
const optional = coff + 20;
image.writeUInt16LE(pe32Plus ? 0x020b : 0x010b, optional);
image.writeUInt32LE(0x2000, optional + 20);
if (pe32Plus) image.writeBigUInt64LE(0x0040_0000n, optional + 24);
else image.writeUInt32LE(0x0040_0000, optional + 28);
image.writeUInt32LE(0x1000, optional + 32);
image.writeUInt32LE(0x200, optional + 36);
image.writeUInt32LE(align(0x2000 + imageSize - 0x200, 0x1000), optional + 56);
image.writeUInt32LE(0x200, optional + 60);
image.writeUInt32LE(16, optional + directoryOffset - 4);
image.writeUInt32LE(0x2000, optional + directoryOffset + 14 * 8);
image.writeUInt32LE(72, optional + directoryOffset + 14 * 8 + 4);
const section = optional + optionalSize;
image.write(".text\0\0\0", section, "ascii");
image.writeUInt32LE(imageSize - 0x200, section + 8);
image.writeUInt32LE(0x2000, section + 12);
image.writeUInt32LE(imageSize - 0x200, section + 16);
image.writeUInt32LE(0x0200, section + 20);
image.writeUInt32LE(0x6000_0020, section + 36);
const cli = 0x0200;
image.writeUInt32LE(72, cli);
image.writeUInt16LE(2, cli + 4);
image.writeUInt16LE(5, cli + 6);
image.writeUInt32LE(0x2100, cli + 8);
image.writeUInt32LE(metadata.length, cli + 12);
image.writeUInt32LE(options.cliFlags ?? 1, cli + 16);
image.writeUInt32LE(0x0600_0001, cli + 20);
image.writeUInt32LE(0x2000 + (resourceOffset - 0x0200), cli + 24);
image.writeUInt32LE(resourceDirectory.length, cli + 28);
if (options.readyToRun === true) {
image.writeUInt32LE(0x2000 + (readyToRunOffset - 0x0200), cli + 64);
image.writeUInt32LE(4, cli + 68);
image.write("RTR\0", readyToRunOffset, "ascii");
}
methods.forEach((method, index) => {
const offset = methodOffsets[index];
if (offset === null || offset === undefined) return;
(method.body ?? retOnlyIlBody).copy(image, offset);
});
metadata.copy(image, metadataOffset);
resourceDirectory.copy(image, resourceOffset);
return image;
};
/**
* Build a source-owned PE/CLI fixture without committing compiled binaries.
* @param {ManagedPeFixtureOptions} [options]
*/
export const buildManagedPeFixture = (options = {}) => {
const methods = managedFixtureMethods(options);
const provisionalMetadata = buildManagedMetadata(
options,
methods.map((method) => ({ ...method, rva: method.rva ?? 0x2800 })),
);
const layout = managedFixtureLayout(
options,
methods,
provisionalMetadata.length,
);
const methodsWithRvas = methods.map((method, index) => ({
...method,
rva: method.rva ?? bodyRva(layout.methodOffsets[index]),
}));
const metadata = buildManagedMetadata(options, methodsWithRvas);
return buildManagedImage(options, methodsWithRvas, metadata);
};
/**
* The RVA of a method body the layout placed. A method without an RVA always
* has a placed body; only an explicit RVA of zero has none.
* @param {number | null | undefined} offset
*/
const bodyRva = (offset) => {
if (offset === null || offset === undefined)
throw new RangeError("Managed PE fixture method body was not placed");
return 0x2000 + (offset - 0x0200);
};
export const buildNativePeFixture = () => {
const image = buildManagedPeFixture();
const cliDirectory = 0x84 + 20 + 96 + 14 * 8;
image.writeUInt32LE(0, cliDirectory);
image.writeUInt32LE(0, cliDirectory + 4);
return image;
};