mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 21:23:45 +00:00
* fix(mcp): preserve caller-selected binary session paths * test(mcp): verify caller paths across snapshot replay * test(mcp): separate session alias and snapshot replay coverage * fix(evidence): preserve selected paths across binary workflows * fix(evidence): retain authentication admission for caller aliases
418 lines
14 KiB
TypeScript
418 lines
14 KiB
TypeScript
import type { DolHeader } from "./gamecubeDol.js";
|
|
import {
|
|
ZIP_PACKAGE_FORMATS,
|
|
type ZipPackageFormat,
|
|
} from "./zipPackageFormat.js";
|
|
|
|
/** Provider-neutral CPU families detected from headers or explicitly selected raw loads. */
|
|
export const BINARY_ARCHITECTURES = [
|
|
"x86",
|
|
"x86_64",
|
|
"arm",
|
|
"arm64",
|
|
"arm64_32",
|
|
"mips",
|
|
"6502",
|
|
"riscv",
|
|
"powerpc",
|
|
"m68k",
|
|
"hexagon",
|
|
"xtensa",
|
|
] as const;
|
|
export type BinaryArchitecture = (typeof BINARY_ARCHITECTURES)[number];
|
|
|
|
/**
|
|
* Families admitted only by explicit raw-binary selection. Header detection
|
|
* never yields them, so detected targets and Evidence subjects exclude them.
|
|
*/
|
|
export const RAW_ONLY_ARCHITECTURES = [
|
|
"6502",
|
|
"m68k",
|
|
] as const satisfies readonly BinaryArchitecture[];
|
|
export type RawOnlyArchitecture = (typeof RAW_ONLY_ARCHITECTURES)[number];
|
|
|
|
/**
|
|
* ELF header facts for a family whose ISA and ABI are not established by the
|
|
* family name alone. Consumers admit a lane from these declarations rather than
|
|
* re-reading the header.
|
|
*/
|
|
export interface ElfFamilyMetadata {
|
|
readonly elfClass: 32 | 64;
|
|
readonly byteOrder: "little" | "big";
|
|
readonly type: number;
|
|
readonly flags: number;
|
|
}
|
|
|
|
/** Referenced CodeView debug symbols from a PE debug directory. */
|
|
export interface PeCodeViewRecord {
|
|
readonly pdbPath: string;
|
|
readonly pdbFileName: string;
|
|
readonly guid: string | null;
|
|
readonly age: number;
|
|
}
|
|
|
|
/** Families whose parsed target variant carries `ElfFamilyMetadata`. */
|
|
export const ELF_METADATA_ARCHITECTURES = [
|
|
"mips",
|
|
"riscv",
|
|
"powerpc",
|
|
] as const satisfies readonly BinaryArchitecture[];
|
|
export type ElfMetadataArchitecture =
|
|
(typeof ELF_METADATA_ARCHITECTURES)[number];
|
|
|
|
/** Families whose ISA and ABI need a separate ELF declaration to be admitted. */
|
|
export const isElfMetadataArchitecture = (
|
|
architecture: BinaryArchitecture,
|
|
): architecture is ElfMetadataArchitecture =>
|
|
(ELF_METADATA_ARCHITECTURES as readonly string[]).includes(architecture);
|
|
|
|
/** Families that require a specialized target variant instead of generic headers. */
|
|
export const HEADER_ARCHITECTURE_EXCLUSIONS = [
|
|
...ELF_METADATA_ARCHITECTURES,
|
|
...RAW_ONLY_ARCHITECTURES,
|
|
"hexagon",
|
|
"xtensa",
|
|
"arm64_32",
|
|
] as const satisfies readonly BinaryArchitecture[];
|
|
|
|
/** Recognized family with no specialized target member; the header alone is the fact. */
|
|
export type HeaderArchitecture = Exclude<
|
|
BinaryArchitecture,
|
|
(typeof HEADER_ARCHITECTURE_EXCLUSIONS)[number]
|
|
>;
|
|
|
|
/** Raw ELF facts; family recognition does not establish ISA or ABI support. */
|
|
export interface MipsElfMetadata extends ElfFamilyMetadata {
|
|
/** Undefined until inspected; null means no ABI record was observed. */
|
|
readonly abiFlags?: MipsAbiFlags | null;
|
|
/** Undefined until inspected; null means no GNU attribute section was observed. */
|
|
readonly gnuAttributes?: MipsGnuAttributes | null;
|
|
/** Unavailable declaration sources; missing records there remain unknown. */
|
|
readonly limitations?: readonly string[];
|
|
/** Complete dynamic REL declarations, or the reason they could not be inspected. */
|
|
readonly sharedLoad?:
|
|
| {
|
|
readonly status: "complete";
|
|
readonly relocationCount: number;
|
|
readonly relocationTypes: readonly number[];
|
|
readonly symbolRelativeCount: number;
|
|
}
|
|
| { readonly status: "unavailable"; readonly reason: string };
|
|
}
|
|
|
|
/** Raw ELF facts; family recognition does not establish ISA or ABI support. */
|
|
export interface RiscvElfMetadata extends ElfFamilyMetadata {
|
|
/** Undefined until `.riscv.attributes` is inspected. */
|
|
readonly isa?: RiscvIsaDeclaration;
|
|
}
|
|
|
|
/** The ISA an image declares in `.riscv.attributes`; not proof of every instruction. */
|
|
export type RiscvIsaDeclaration =
|
|
| {
|
|
readonly status: "declared";
|
|
/** `Tag_RISCV_arch` exactly as declared. */
|
|
readonly arch: string;
|
|
readonly xlen: 32 | 64;
|
|
readonly base: "i" | "e";
|
|
/** Extension names in declaration order, without versions. */
|
|
readonly extensions: readonly string[];
|
|
}
|
|
/** Every section header was examined and none declares `Tag_RISCV_arch`. */
|
|
| { readonly status: "absent" }
|
|
| {
|
|
readonly status: "unavailable";
|
|
readonly reason: string;
|
|
/** The declared string, when one was read but not understood. */
|
|
readonly arch?: string;
|
|
};
|
|
|
|
/** Declared fields of the 24-byte MIPS ABI flags record, not inferred semantics. */
|
|
export interface MipsAbiFlags {
|
|
readonly version: number;
|
|
readonly isaLevel: number;
|
|
readonly isaRevision: number;
|
|
readonly gprSize: number;
|
|
readonly cpr1Size: number;
|
|
readonly cpr2Size: number;
|
|
readonly fpAbi: number;
|
|
readonly isaExtension: number;
|
|
readonly ases: number;
|
|
readonly flags1: number;
|
|
readonly flags2: number;
|
|
}
|
|
|
|
/** File-scope GNU object attributes parsed from `SHT_GNU_ATTRIBUTES`. */
|
|
export interface MipsGnuAttributes {
|
|
/** Tag_GNU_MIPS_ABI_FP; null means this file did not declare the tag. */
|
|
readonly fpAbi: number | null;
|
|
/** Tag_GNU_MIPS_ABI_MSA vector-argument ABI; null means undeclared. */
|
|
readonly msa: number | null;
|
|
}
|
|
|
|
/** Byte range of the selected slice inside its universal Mach-O container. */
|
|
export interface UniversalMachOSlice {
|
|
readonly offset: number;
|
|
readonly size: number;
|
|
}
|
|
|
|
/** FAT-table identity; CPU family alone cannot identify a universal slice. */
|
|
export interface UniversalMachOSliceIdentity extends UniversalMachOSlice {
|
|
readonly cpuType: number;
|
|
readonly cpuSubtype: number;
|
|
}
|
|
|
|
interface BinaryTargetIdentity {
|
|
readonly path: string;
|
|
readonly sourcePath?: string;
|
|
/** Verbatim selected spelling when it differs from the inspected file path. */
|
|
readonly callerInputPath?: string;
|
|
/** Selected artifact spelling determines name-based format hints and external companions. */
|
|
readonly artifactSelectedPath?: string;
|
|
/** Info.plist of the app bundle the target was resolved from. */
|
|
readonly bundleInfoPlist?: string;
|
|
readonly sha256: string;
|
|
}
|
|
|
|
type NonExecutableMetadata = {
|
|
readonly architecture?: never;
|
|
readonly availableArchitectures?: never;
|
|
readonly executableRole?: never;
|
|
readonly managed?: never;
|
|
};
|
|
|
|
type ExecutableTarget = BinaryTargetIdentity & {
|
|
readonly kind: "executable";
|
|
readonly architecture: HeaderArchitecture;
|
|
readonly availableArchitectures: readonly HeaderArchitecture[];
|
|
};
|
|
|
|
/**
|
|
* Canonical local target identity and provider-neutral file classification.
|
|
* Each variant carries only metadata established for that exact file kind.
|
|
*/
|
|
export type BinaryTarget =
|
|
| (BinaryTargetIdentity & {
|
|
readonly kind: "executable";
|
|
readonly format: "elf";
|
|
readonly architecture: "mips";
|
|
readonly availableArchitectures: readonly "mips"[];
|
|
readonly mips: MipsElfMetadata;
|
|
readonly executableRole?: never;
|
|
readonly managed?: never;
|
|
})
|
|
| (BinaryTargetIdentity & {
|
|
readonly kind: "executable";
|
|
readonly format: "elf";
|
|
readonly architecture: "riscv";
|
|
readonly availableArchitectures: readonly "riscv"[];
|
|
readonly riscv: RiscvElfMetadata;
|
|
readonly executableRole?: never;
|
|
readonly managed?: never;
|
|
})
|
|
| (BinaryTargetIdentity & {
|
|
readonly kind: "executable";
|
|
readonly format: "elf";
|
|
readonly architecture: "powerpc";
|
|
readonly availableArchitectures: readonly "powerpc"[];
|
|
/** Family identity does not select a processor variant. */
|
|
readonly powerpc: ElfFamilyMetadata;
|
|
readonly executableRole?: never;
|
|
readonly managed?: never;
|
|
})
|
|
| (BinaryTargetIdentity & {
|
|
readonly kind: "executable";
|
|
readonly format: "elf";
|
|
readonly architecture: "hexagon";
|
|
readonly availableArchitectures: readonly "hexagon"[];
|
|
readonly executableRole?: never;
|
|
readonly managed?: never;
|
|
})
|
|
| (BinaryTargetIdentity & {
|
|
readonly kind: "executable";
|
|
readonly format: "elf";
|
|
readonly architecture: "xtensa";
|
|
readonly availableArchitectures: readonly "xtensa"[];
|
|
readonly executableRole?: never;
|
|
readonly managed?: never;
|
|
})
|
|
| (BinaryTargetIdentity & {
|
|
readonly kind: "executable";
|
|
readonly format: "mach-o";
|
|
readonly architecture: "arm64_32";
|
|
readonly availableArchitectures: readonly "arm64_32"[];
|
|
readonly universalSlice?: never;
|
|
readonly executableRole?: never;
|
|
readonly managed?: never;
|
|
})
|
|
| (ExecutableTarget & {
|
|
readonly format: "mach-o" | "elf" | "dos-mz" | "dos-com";
|
|
readonly universalSlice?: never;
|
|
readonly executableRole?: never;
|
|
readonly managed?: never;
|
|
})
|
|
| (ExecutableTarget & {
|
|
readonly format: "mach-o-universal";
|
|
/** Selected slice range a provider must analyze instead of the container. */
|
|
readonly universalSlice: UniversalMachOSlice;
|
|
/** Exact validated FAT declarations, when supplied by target admission. */
|
|
readonly universalSlices?: readonly UniversalMachOSliceIdentity[];
|
|
readonly executableRole?: never;
|
|
readonly managed?: never;
|
|
})
|
|
| (BinaryTargetIdentity & {
|
|
readonly kind: "executable";
|
|
readonly format: "raw-binary";
|
|
readonly architecture: HeaderArchitecture | RawOnlyArchitecture;
|
|
readonly availableArchitectures: readonly (
|
|
| HeaderArchitecture
|
|
| RawOnlyArchitecture
|
|
)[];
|
|
readonly entryPoint: string;
|
|
readonly entryPointSource: string;
|
|
readonly executableRole?: never;
|
|
readonly managed?: never;
|
|
})
|
|
| (BinaryTargetIdentity & {
|
|
readonly kind: "executable";
|
|
readonly format: "gamecube-dol";
|
|
/** Fixed by the DOL selection; the header does not carry a CPU family. */
|
|
readonly architecture: "powerpc";
|
|
readonly availableArchitectures: readonly ["powerpc"];
|
|
readonly byteOrder: "big";
|
|
readonly bits: 32;
|
|
/** Canonical hex entry taken from the DOL header. */
|
|
readonly entryPoint: string;
|
|
readonly entryPointSource: "dol-header";
|
|
/** Validated header: used sections, BSS, and BSS-overlapping data slots. */
|
|
readonly dol: DolHeader;
|
|
readonly executableRole?: never;
|
|
readonly managed?: never;
|
|
})
|
|
| (ExecutableTarget & {
|
|
readonly format: "pe";
|
|
/** Original COFF machine; undefined means this header fact is unavailable. */
|
|
readonly peMachine?: number;
|
|
/** Provider-neutral PE image role observed from COFF characteristics. */
|
|
readonly executableRole:
|
|
| "application"
|
|
| "shared-library"
|
|
| "non-executable";
|
|
/** Whether the PE declares a non-empty CLI header data-directory entry. */
|
|
readonly managed: boolean;
|
|
/** Referenced CodeView debug symbols from the PE debug directory, if present. */
|
|
readonly codeView?: PeCodeViewRecord;
|
|
})
|
|
| (BinaryTargetIdentity &
|
|
NonExecutableMetadata & {
|
|
readonly kind: "database";
|
|
readonly format: "analysis-database";
|
|
})
|
|
| (BinaryTargetIdentity &
|
|
NonExecutableMetadata & {
|
|
readonly kind: "archive";
|
|
readonly format:
|
|
| ZipPackageFormat
|
|
| "asar"
|
|
| "ines"
|
|
| "godot-pck"
|
|
| "unityfs"
|
|
| "wxapkg"
|
|
| "uimage"
|
|
| "android-boot-image"
|
|
| "android-ota-payload"
|
|
| "dmg"
|
|
| "pkg"
|
|
| "intel-hex"
|
|
| "srec"
|
|
| "esp-image"
|
|
| "uf2"
|
|
| "dfuse"
|
|
| "fit"
|
|
| "ntfs-mft";
|
|
})
|
|
| (BinaryTargetIdentity &
|
|
NonExecutableMetadata & {
|
|
readonly kind: "archive";
|
|
readonly format: "esp-flash-image";
|
|
/** How the dump is read; null inputs take their defaults. */
|
|
readonly espFlash: EspFlashTargetSelection;
|
|
})
|
|
| (BinaryTargetIdentity &
|
|
NonExecutableMetadata & {
|
|
readonly kind: "artifact";
|
|
readonly format: "plist" | "javascript" | "source-map";
|
|
});
|
|
|
|
/** The kind of every target variant that may carry `Format`. */
|
|
type TargetKindOf<Format> = BinaryTarget extends infer Target
|
|
? Target extends { readonly format: infer Formats; readonly kind: infer Kind }
|
|
? Format extends Formats
|
|
? Kind
|
|
: never
|
|
: never
|
|
: never;
|
|
|
|
/**
|
|
* The one kind each target format has. A target, snapshot or identity whose
|
|
* kind disagrees with its format is malformed.
|
|
*/
|
|
export const BINARY_TARGET_FORMAT_KINDS = {
|
|
"analysis-database": "database",
|
|
"mach-o": "executable",
|
|
"mach-o-universal": "executable",
|
|
elf: "executable",
|
|
pe: "executable",
|
|
"dos-mz": "executable",
|
|
"dos-com": "executable",
|
|
"raw-binary": "executable",
|
|
"gamecube-dol": "executable",
|
|
...(Object.fromEntries(
|
|
ZIP_PACKAGE_FORMATS.map((format) => [format, "archive"]),
|
|
) as Record<ZipPackageFormat, "archive">),
|
|
asar: "archive",
|
|
ines: "archive",
|
|
"godot-pck": "archive",
|
|
unityfs: "archive",
|
|
wxapkg: "archive",
|
|
uimage: "archive",
|
|
"android-boot-image": "archive",
|
|
"android-ota-payload": "archive",
|
|
dmg: "archive",
|
|
pkg: "archive",
|
|
"intel-hex": "archive",
|
|
srec: "archive",
|
|
"esp-image": "archive",
|
|
uf2: "archive",
|
|
dfuse: "archive",
|
|
"esp-flash-image": "archive",
|
|
fit: "archive",
|
|
"ntfs-mft": "archive",
|
|
plist: "artifact",
|
|
javascript: "artifact",
|
|
"source-map": "artifact",
|
|
} as const satisfies {
|
|
readonly [Format in BinaryTarget["format"]]: TargetKindOf<Format>;
|
|
};
|
|
|
|
/** Caller inputs that select how an ESP flash dump is read. */
|
|
export interface EspFlashTargetSelection {
|
|
/** The caller selected the format, so the table scan runs without a bootloader. */
|
|
readonly selected: boolean;
|
|
/** Flash address of the dump's first byte. */
|
|
readonly flashOffset: number | null;
|
|
/** Flash address of the partition table. */
|
|
readonly partitionTableOffset: number | null;
|
|
}
|
|
|
|
/** Whether an executable target contains a thin or universal Mach-O image. */
|
|
export const isMachOFormat = (
|
|
format: unknown,
|
|
): format is "mach-o" | "mach-o-universal" =>
|
|
format === "mach-o" || format === "mach-o-universal";
|
|
|
|
/** Result-affecting artifact selection; canonical packed identity remains target.path. */
|
|
export const artifactTargetSelectedPath = (target: BinaryTarget): string =>
|
|
target.kind === "archive" || target.kind === "artifact"
|
|
? (target.artifactSelectedPath ?? target.sourcePath ?? target.path)
|
|
: (target.sourcePath ?? target.path);
|