import { createHash } from "node:crypto"; import { nativeLoadImageSchema, type NativeLoadImage, type NativeLoadImageCheck, type NativeLoadImageObservation, } from "../domain/native/nativeLoadImage.js"; import { parseDosMzHeader, type DosMzHeader } from "../domain/dosMz.js"; import type { JsonValue } from "../domain/jsonValue.js"; import { validateDosComLength } from "../domain/dosCom.js"; import { err, ok, type Result } from "../domain/result.js"; const sha256 = (bytes: Buffer): string => createHash("sha256").update(bytes).digest("hex"); const address = (offset: number): string => `0x${offset.toString(16)}`; const limitations = [ "Verification covers original/modified FileBytes, every initialized target-backed header/module mapping, relocation records and the external entry point. Mapping ends are inclusive.", "Appended overlay bytes are identified by file extent and included in FileBytes identity; they must not be mapped as initialized header/module memory. Uninitialized allocations are reported but their contents and DOS runtime behavior are not verified.", "The fixed load segment 0x1000 describes Ghidra's analysis image, not a running DOS process. Verified import does not establish original source ownership or recovered program behavior.", "A mismatching memory digest identifies the reported source range; it does not locate the first differing byte inside that range.", ]; /** Verify measured MZ import state against the session's immutable snapshot. */ export const attestGhidraDosLoadImage = ( bytes: Buffer, targetSha256: string, observations: NativeLoadImageObservation, ): Result => { if (sha256(bytes) !== targetSha256) return err( "Ghidra load-image snapshot digest does not match the admitted target", ); const parsed = parseDosMzHeader(bytes); if (!parsed.ok) return parsed; const header = parsed.value; const loadSegment = 0x1000; const modified = Buffer.from(bytes); const expectedRelocations = []; for (let index = 0; index < header.relocationCount; index += 1) { const table = header.relocationTableOffset + index * 4; const offset = bytes.readUInt16LE(table); const segment = bytes.readUInt16LE(table + 2); const fileOffset = header.headerBytes + segment * 16 + offset; const original = modified .subarray(fileOffset, fileOffset + 2) .toString("hex"); const relocated = (modified.readUInt16LE(fileOffset) + loadSegment) & 0xffff; modified.writeUInt16LE(relocated, fileOffset); expectedRelocations.push({ address: address(loadSegment * 16 + segment * 16 + offset), segment: (loadSegment + segment) & 0xffff, offset, status: "APPLIED", type: 0, values: [segment, offset, relocated], original_bytes_hex: original, memory_bytes_hex: modified .subarray(fileOffset, fileOffset + 2) .toString("hex"), }); } const checks: NativeLoadImageCheck[] = []; const check = ( name: string, expected: JsonValue, observed: JsonValue, fileOffset: number | null = null, location: string | null = null, ): void => { checks.push({ name, matched: JSON.stringify(expected) === JSON.stringify(observed), expected, observed, file_offset: fileOffset, address: location, }); }; check( "executable_format", "Old-style DOS Executable (MZ)", observations.executable_format, ); check("language_id", "x86:LE:16:Real Mode", observations.language_id); check("compiler_spec_id", "default", observations.compiler_spec_id); check("image_base", "0x0", observations.image_base); check("default_address_space", "ram", observations.default_address_space); check("source_file_count", 1, observations.source_files.length); const source = observations.source_files[0]; check("source_file_size", bytes.length, source?.size ?? null); check("original_file_sha256", targetSha256, source?.original_sha256 ?? null); check( "modified_file_sha256", sha256(modified), source?.modified_sha256 ?? null, ); const entryAddress = address( ((loadSegment + header.entrySegment) & 0xffff) * 16 + header.entryOffset, ); check("entry_points", [entryAddress], [...observations.entry_points].sort()); // A multiset preserves duplicate relocations and aliases; iteration order is not semantic. const rows = (values: NativeLoadImageObservation["relocations"]): string[] => values .map(({ segment: _segment, offset: _offset, ...value }) => JSON.stringify(value), ) .sort(); check( "relocation_address_aliases", [], observations.relocations.filter( (row) => row.segment === null || row.offset === null || address(row.segment * 16 + row.offset) !== row.address, ), ); check( "relocation_records", rows(expectedRelocations), rows(observations.relocations), ); checkMappings(header, loadSegment * 16, bytes, modified, observations, check); return ok( nativeLoadImageSchema.parse({ status: checks.every((item) => item.matched) ? "verified" : "mismatch", format: "dos-mz", target_sha256: targetSha256, load_segment: loadSegment, header_bytes: header.headerBytes, module_bytes: header.moduleBytes, overlay_bytes: header.overlayBytes, entry: { relative_segment: header.entrySegment, offset: header.entryOffset, linear_address: entryAddress, }, observations, checks, limitations, }), ); }; const checkMappings = ( header: Pick, loadBase: number, bytes: Buffer, modified: Buffer, observations: NativeLoadImageObservation, check: ( name: string, expected: JsonValue, observed: JsonValue, fileOffset?: number | null, location?: string | null, ) => void, ): void => { const backed = observations.mappings.filter( (mapping) => mapping.source_file_index !== null, ); const sorted = [...backed].sort( (left, right) => (left.file_offset ?? -1) - (right.file_offset ?? -1), ); let covered = 0; for (let index = 0; index < sorted.length; index += 1) { const mapping = sorted[index]; if (mapping === undefined) continue; const start = mapping.file_offset; const end = start === null ? null : start + mapping.length; const headerMapping = start !== null && end !== null && start >= 0 && end <= header.headerBytes; const moduleMapping = start !== null && end !== null && start >= header.headerBytes && end <= header.imageBytes; const at = `mapping[${index}]`; check( `${at}.source_file_index`, 0, mapping.source_file_index, start, mapping.start, ); check(`${at}.file_coverage_start`, covered, start, start, mapping.start); check( `${at}.partition`, true, headerMapping || moduleMapping, start, mapping.start, ); check(`${at}.initialized`, true, mapping.initialized, start, mapping.start); check(`${at}.loaded`, moduleMapping, mapping.loaded, start, mapping.start); check( `${at}.overlay`, headerMapping, mapping.overlay, start, mapping.start, ); check( `${at}.address_space`, headerMapping ? "HEADER" : observations.default_address_space, mapping.address_space, start, mapping.start, ); const expectedStart = start === null ? null : headerMapping ? `HEADER:${address(start)}` : address(loadBase + start - header.headerBytes); const expectedEnd = start === null ? null : headerMapping ? `HEADER:${address(start + mapping.length - 1)}` : address(loadBase + start - header.headerBytes + mapping.length - 1); check(`${at}.start`, expectedStart, mapping.start, start, mapping.start); check(`${at}.end`, expectedEnd, mapping.end, start, mapping.end); check( `${at}.memory_sha256`, start !== null && end !== null && end <= bytes.length ? sha256(modified.subarray(start, end)) : null, mapping.sha256, start, mapping.start, ); covered = end ?? covered; } check("initialized_file_coverage_end", header.imageBytes, covered); check( "initialized_unbacked_mappings", [], observations.mappings.filter( (mapping) => mapping.initialized && mapping.source_file_index === null, ), ); }; /** Verify the explicit DOS COM interpretation against measured bytes and context. */ export const attestGhidraDosComLoadImage = ( bytes: Buffer, targetSha256: string, observations: NativeLoadImageObservation, ): Result => { if (sha256(bytes) !== targetSha256) return err("Ghidra COM snapshot digest does not match the admitted target"); const length = validateDosComLength(bytes.length); if (!length.ok) return length; const checks: NativeLoadImageCheck[] = []; const check = ( name: string, expected: JsonValue, observed: JsonValue, fileOffset: number | null = null, location: string | null = null, ): void => { checks.push({ name, matched: JSON.stringify(expected) === JSON.stringify(observed), expected, observed, file_offset: fileOffset, address: location, }); }; const source = observations.source_files[0]; check("executable_format", "Raw Binary", observations.executable_format); check("language_id", "x86:LE:16:Real Mode", observations.language_id); check("compiler_spec_id", "default", observations.compiler_spec_id); check("image_base", "0x0", observations.image_base); check("default_address_space", "ram", observations.default_address_space); check("source_file_count", 1, observations.source_files.length); check("source_file_size", bytes.length, source?.size ?? null); check("original_file_sha256", targetSha256, source?.original_sha256 ?? null); check("modified_file_sha256", targetSha256, source?.modified_sha256 ?? null); check("entry_points", ["0x10100"], [...observations.entry_points].sort()); check( "entry_context", [ { address: "0x10100", registers: ["CS", "DS", "ES", "SS"].map((name) => ({ name, value_hex: "0x1000", })), }, ], observations.entry_context, ); check("relocation_records", [], observations.relocations); checkMappings( { headerBytes: 0, imageBytes: bytes.length }, 0x10100, bytes, bytes, observations, check, ); return ok( nativeLoadImageSchema.parse({ status: checks.every((item) => item.matched) ? "verified" : "mismatch", format: "dos-com", target_sha256: targetSha256, load_segment: 0x1000, header_bytes: 0, module_bytes: bytes.length, overlay_bytes: 0, entry: { relative_segment: 0, offset: 0x100, linear_address: "0x10100" }, observations, checks, limitations: [ "DOS COM is a headerless interpretation explicitly selected by the caller, not format identification from file bytes.", "Verification covers complete original/modified source identity, mapped file bytes, entry and measured CS/DS/ES/SS entry context. Context 0x1000 is imposed for analysis; it is not an observed running process.", "The PSP, initial stack contents/registers, DOS interrupts, PC-98 devices and runtime behavior are not modeled or verified. No original executable bytes are changed.", "Mapping ends are inclusive; a mismatching digest identifies its source range, not the first differing byte.", ], }), ); };