Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
import { isUtf8 } from "node:buffer";
import { TextDecoder } from "node:util";
import { setImmediate } from "node:timers/promises";
import type { JsonValue } from "../domain/jsonValue.js";
import type {
ModelMetadata,
ModelTensor,
ModelArtifactPartialTensor,
} from "../domain/model/modelArtifact.js";
import { ModelHeaderReader } from "./ModelHeaderReader.js";
import {
MODEL_ARRAY_PREVIEW,
MODEL_METADATA_NESTING,
ModelFormatFailure,
ModelReportBudget,
rejectModel,
} from "./ModelFormat.js";
import { ggmlType } from "./ModelTensorTypes.js";
const NAMES = [
"UINT8",
"INT8",
"UINT16",
"INT16",
"UINT32",
"INT32",
"FLOAT32",
"BOOL",
"STRING",
"ARRAY",
"UINT64",
"INT64",
"FLOAT64",
] as const;
const WIDTHS = [1, 1, 2, 2, 4, 4, 4, 1, 8, 12, 8, 8, 8];
export interface GgufProgress {
onHeader(info: {
version: number;
byte_order: "little" | "big";
declared_metadata_count: number;
declared_tensor_count: number;
}): void;
onMetadata(row: ModelMetadata): void;
onAlignment(alignment: number): void;
onMetadataComplete(): void;
onTensorsStarted(): void;
onTensorDeclaration(row: ModelArtifactPartialTensor): void;
}
/** Explicit-endian GGUF v2/v3 metadata and tensor-directory parser. */
export class GgufHeader {
#little = true;
readonly #budget = new ModelReportBudget();
constructor(readonly reader: ModelHeaderReader) {}
async #unsigned(width: 4 | 8): Promise<number> {
const b = await this.reader.take(width);
const value =
width === 4
? BigInt(this.#little ? b.readUInt32LE() : b.readUInt32BE())
: this.#little
? b.readBigUInt64LE()
: b.readBigUInt64BE();
if (value > BigInt(Number.MAX_SAFE_INTEGER))
throw new ModelFormatFailure(
"capacity",
"Header length/count exceeds exact host offset precision",
"exact-offset",
);
return Number(value);
}
async #text(retain: boolean, maximum?: number): Promise<string> {
const length = await this.#unsigned(8);
if (maximum !== undefined && length > maximum)
rejectModel("GGUF name exceeds its format byte limit");
if (retain) this.#budget.charge(6 * length + 2);
this.reader.guarantee(length);
// Omitted preview entries still need validation, but not decoded strings.
// Keep the streaming decoder for values spanning multiple read chunks.
if (!retain && length <= 65536) {
if (!isUtf8(await this.reader.take(length)))
rejectModel("GGUF string is not valid UTF-8");
return "";
}
const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
let result = "";
try {
for (let left = length; left > 0;) {
const n = Math.min(left, 65536);
const text = decoder.decode(await this.reader.take(n), {
stream: true,
});
if (retain) result += text;
left -= n;
}
const tail = decoder.decode();
if (retain) result += tail;
} catch (cause) {
if (cause instanceof TypeError)
rejectModel("GGUF string is not valid UTF-8");
throw cause;
}
return result;
}
async #value(
type: number,
retain: boolean,
depth = 0,
): Promise<{
value: JsonValue;
element_type: string | null;
element_count: number | null;
complete: boolean;
}> {
if (NAMES[type] === undefined)
rejectModel(`Unknown GGUF metadata type ${String(type)}`);
if (depth > MODEL_METADATA_NESTING)
throw new ModelFormatFailure(
"capacity",
`GGUF metadata nesting exceeds ${String(MODEL_METADATA_NESTING)} array frames`,
"metadata-nesting",
);
if (type === 8)
return {
value: await this.#text(retain),
element_type: null,
element_count: null,
complete: true,
};
if (type === 9) {
const element = await this.#unsigned(4);
const count = await this.#unsigned(8);
const minimum = WIDTHS[element];
if (minimum === undefined)
rejectModel(`Unknown GGUF array element type ${String(element)}`);
this.reader.guarantee(count * minimum);
const preview: JsonValue[] = [];
if (retain)
this.#budget.charge(128 + Math.min(count, MODEL_ARRAY_PREVIEW) * 64);
let complete = count <= MODEL_ARRAY_PREVIEW;
for (let index = 0; index < count; index++) {
if (index % 4096 === 4095) await setImmediate();
this.reader.guarantee((count - index) * minimum);
if (
element !== 8 &&
element !== 9 &&
(!retain || index >= MODEL_ARRAY_PREVIEW)
) {
let left = (count - index) * minimum;
while (left > 0) {
const size = Math.min(left, 65536);
const bytes = await this.reader.take(size);
if (element === 7 && bytes.some((byte) => byte !== 0 && byte !== 1))
rejectModel("GGUF boolean must be 0 or 1");
left -= size;
}
break;
}
const keep = retain && index < MODEL_ARRAY_PREVIEW;
const value = await this.#value(element, keep, depth + 1);
if (keep)
preview.push(
element === 9
? {
type: "ARRAY",
element_type: value.element_type,
element_count: value.element_count,
preview: value.value,
preview_complete: value.complete,
}
: value.value,
);
complete &&= value.complete;
}
return {
value: preview,
element_type: NAMES[element] ?? null,
element_count: count,
complete,
};
}
const b = await this.reader.take(WIDTHS[type] ?? 0);
let value: JsonValue;
switch (type) {
case 0:
value = b.readUInt8();
break;
case 1:
value = b.readInt8();
break;
case 2:
value = this.#little ? b.readUInt16LE() : b.readUInt16BE();
break;
case 3:
value = this.#little ? b.readInt16LE() : b.readInt16BE();
break;
case 4:
value = this.#little ? b.readUInt32LE() : b.readUInt32BE();
break;
case 5:
value = this.#little ? b.readInt32LE() : b.readInt32BE();
break;
case 6:
value = this.#little ? b.readFloatLE() : b.readFloatBE();
break;
case 7:
if (b[0] !== 0 && b[0] !== 1)
rejectModel("GGUF boolean must be 0 or 1");
value = b[0] === 1;
break;
case 10:
value = (
this.#little ? b.readBigUInt64LE() : b.readBigUInt64BE()
).toString();
break;
case 11:
value = (
this.#little ? b.readBigInt64LE() : b.readBigInt64BE()
).toString();
break;
case 12:
value = this.#little ? b.readDoubleLE() : b.readDoubleBE();
break;
default:
return rejectModel("Unsupported GGUF scalar");
}
if (Object.is(value, -0)) value = "-0";
if (typeof value === "number" && !Number.isFinite(value))
value = Number.isNaN(value)
? "NaN"
: value > 0
? "+Infinity"
: "-Infinity";
return {
value: retain ? value : null,
element_type: null,
element_count: null,
complete: true,
};
}
async read(progress?: GgufProgress): Promise<{
version: number;
byte_order: "little" | "big";
alignment: number;
tensor_data_offset: number;
metadata: ModelMetadata[];
tensors: ModelTensor[];
}> {
const versionBytes = await this.reader.take(4);
const littleVersion = versionBytes.readUInt32LE();
const bigVersion = versionBytes.readUInt32BE();
let version: number;
if (littleVersion === 2 || littleVersion === 3) {
this.#little = true;
version = littleVersion;
} else if (bigVersion === 2 || bigVersion === 3) {
this.#little = false;
version = bigVersion;
} else {
throw new ModelFormatFailure(
"unsupported",
`GGUF version bytes ${versionBytes.toString("hex")} are unsupported (little-endian ${String(littleVersion)}, big-endian ${String(bigVersion)}; byte order unknown); supported versions are 2 and 3`,
);
}
if (!this.#little && version !== 3)
rejectModel("Big-endian GGUF requires version 3");
const tensorCount = await this.#unsigned(8);
const metadataCount = await this.#unsigned(8);
progress?.onHeader({
version,
byte_order: this.#little ? "little" : "big",
declared_metadata_count: metadataCount,
declared_tensor_count: tensorCount,
});
this.#budget.charge((tensorCount + metadataCount) * 512);
this.reader.guarantee(tensorCount * 20 + metadataCount * 13);
const metadata: ModelMetadata[] = [];
const keys = new Set<string>();
let alignment = 32;
for (let index = 0; index < metadataCount; index++) {
this.reader.guarantee((metadataCount - index) * 13 + tensorCount * 20);
const start = this.reader.position;
const key = await this.#text(true, 65535);
// Numeric hierarchy components occur in standardized base_model.{id} keys.
if (
!/^[a-z0-9]+(?:_[a-z0-9]+)*(?:\.[a-z0-9]+(?:_[a-z0-9]+)*)*$/u.test(key)
)
rejectModel(
"GGUF metadata keys require ASCII lower-snake-case hierarchy components",
);
if (keys.has(key)) rejectModel(`Duplicate GGUF metadata key ${key}`);
keys.add(key);
const type = await this.#unsigned(4);
const parsed = await this.#value(type, true);
const row = {
index,
key,
type: NAMES[type] ?? String(type),
value: parsed.value,
element_type: parsed.element_type,
element_count: parsed.element_count,
preview_complete: parsed.complete,
source_offset: start,
source_length: this.reader.position - start,
json_pointer: null,
} satisfies ModelMetadata;
if (key === "general.alignment") {
if (
type !== 4 ||
typeof parsed.value !== "number" ||
parsed.value === 0 ||
parsed.value % 8 !== 0
)
rejectModel(
"GGUF general.alignment must be a positive UINT32 multiple of eight",
);
alignment = parsed.value;
progress?.onAlignment(alignment);
}
metadata.push(row);
progress?.onMetadata(row);
}
if (!keys.has("general.alignment")) progress?.onAlignment(alignment);
progress?.onMetadataComplete();
progress?.onTensorsStarted();
const tensors: ModelArtifactPartialTensor[] = [];
const names = new Set<string>();
for (let index = 0; index < tensorCount; index++) {
this.reader.guarantee((tensorCount - index) * 20);
const start = this.reader.position;
const name = await this.#text(true, 64);
if (names.has(name)) rejectModel(`Duplicate GGUF tensor name ${name}`);
names.add(name);
const dimensions = await this.#unsigned(4);
if (dimensions > 4)
rejectModel("GGUF tensor dimension count must be at most 4");
const shape: string[] = [];
let parameters = 1n;
for (let d = 0; d < dimensions; d++) {
const b = await this.reader.take(8);
const value = this.#little ? b.readBigUInt64LE() : b.readBigUInt64BE();
shape.push(value.toString());
parameters *= value;
}
const id = await this.#unsigned(4);
const offset = await this.#unsigned(8);
if (offset % alignment !== 0)
rejectModel(`GGUF tensor ${name} offset is not aligned`);
const type = ggmlType(id);
let length: number | null = null;
if (type !== undefined) {
if (BigInt(shape[0] ?? "1") % BigInt(type[1]) !== 0n)
rejectModel(
`GGUF tensor ${name} first dimension is not divisible by the quantization block size`,
);
const bytes = (parameters / BigInt(type[1])) * BigInt(type[2]);
if (bytes > BigInt(this.reader.size))
rejectModel(
`GGUF tensor ${name} declared byte length exceeds the file`,
);
length = Number(bytes);
}
const tensor = {
index,
name,
type: type?.[0] ?? `UNKNOWN_${String(id)}`,
type_id: id,
shape,
data_offset: offset,
file_offset: null,
byte_length: length,
parameter_count: parameters.toString(),
byte_length_state: length === null ? "unknown" : "derived",
storage_validation: "not-established",
source_offset: start,
source_length: this.reader.position - start,
json_pointer: null,
} satisfies ModelArtifactPartialTensor;
tensors.push(tensor);
progress?.onTensorDeclaration(tensor);
}
const tensor_data_offset =
Math.ceil(this.reader.position / alignment) * alignment;
if (tensor_data_offset > this.reader.size)
rejectModel("GGUF tensor data section begins outside the file");
for (const tensor of tensors) {
const offset = BigInt(tensor_data_offset) + BigInt(tensor.data_offset);
if (
offset > BigInt(this.reader.size) ||
offset + BigInt(tensor.byte_length ?? 0) > BigInt(this.reader.size)
)
rejectModel(`GGUF tensor ${tensor.name} range is outside the file`);
tensor.file_offset = Number(offset);
}
const completeTensors: ModelTensor[] = tensors.map((tensor) => ({
...tensor,
file_offset: tensor.file_offset!,
storage_validation:
tensor.byte_length === null ? "unknown" : "consistent",
}));
return {
version,
byte_order: this.#little ? "little" : "big",
alignment,
tensor_data_offset,
metadata,
tensors: completeTensors,
};
}
}