fix(gguf): bound general.alignment and refuse to truncate the tensor data section

parseGgufLayout accepted any non-zero multiple-of-8 general.alignment, so a
hostile model could claim 2^31. rebuildGguf then allocated that much zeroed
padding and clamped the data slice to the end of the buffer, dropping every
tensor while still emitting a parseable container.

- reject alignments above 1 MiB as malformed instead of clamping silently
- refuse to rebuild when the declared data section starts past the input
- fail closed when a tensor-bearing GGUF has no preservable layout

Adds regression tests for the huge alignment, the truncated data section and
the fail-closed protection path.
This commit is contained in:
DeryFerd
2026-11-15 16:17:44 +07:00
parent b2af7a50f8
commit 052d762209
3 changed files with 109 additions and 3 deletions
+24 -3
View File
@@ -27,6 +27,13 @@ const MAX_KV_COUNT = 100_000n;
const MAX_TENSOR_COUNT = 1_000_000n;
const MAX_TENSOR_DIMS = 8;
const MAX_VALUE_DEPTH = 64;
/**
* Upper bound on `general.alignment`. Real GGUF writers use 32 (some use 64 or
* 128). A hostile file can claim up to 2^31, which makes `alignUp` request a
* multi-gigabyte zeroed pad and pushes `dataStart` past the end of the file —
* dropping every tensor while still producing a parseable container.
*/
const MAX_ALIGNMENT = 1_048_576;
export interface GgufKvEntry {
readonly key: string;
@@ -145,8 +152,13 @@ export function parseGgufLayout(input: Uint8Array): GgufLayout | null {
if (next === null) return null;
if (key === "general.alignment" && valueType === GGUF_TYPE_UINT32) {
const a = bytes.readUInt32LE(valueStart);
// Spec: a non-zero multiple of 8. Ignore nonsensical values.
if (a > 0 && a % 8 === 0) alignment = a;
// Spec: a non-zero multiple of 8. Out-of-range values are treated as
// malformed rather than silently clamped, so the caller never rebuilds a
// file whose declared data section lies beyond the file itself.
if (a > 0 && a % 8 === 0) {
if (a > MAX_ALIGNMENT) return null;
alignment = a;
}
}
kvs.push({ key, start, end: next, valueType });
offset = next;
@@ -236,9 +248,18 @@ export function rebuildGguf(
]);
if (!layout.hasDataRegion) return metaAndInfos;
// A declared data section that starts past the end of the input means the
// tensor bytes cannot be preserved. Fail closed instead of emitting a
// container whose tensors silently resolve to nothing.
if (layout.dataStart > bytes.length) {
throw new Error(
`Refusing to rebuild GGUF: declared tensor-data start ${layout.dataStart} exceeds the ${bytes.length}-byte input`,
);
}
const newDataStart = alignUp(metaAndInfos.length, layout.alignment);
const pad = Buffer.alloc(newDataStart - metaAndInfos.length, 0);
const data = bytes.subarray(Math.min(layout.dataStart, bytes.length));
const data = bytes.subarray(layout.dataStart);
return Buffer.concat([metaAndInfos, pad, data]);
}
+17
View File
@@ -410,6 +410,14 @@ function parseExistingGgufHeader(bytes: Buffer): {
};
}
/** A GGUF whose tensor layout cannot be preserved; refusing beats silent weight loss. */
export class InvalidGgufLayoutError extends Error {
constructor(reason: string) {
super(`Invalid or unsupported GGUF input: ${reason}`);
this.name = "InvalidGgufLayoutError";
}
}
/**
* Builds or protects a GGUF v2/v3 (`.gguf`) model binary against REA's `GgufHeader.ts`:
* 1. Preserves all existing GGUF metadata KV entries and trailing tensor records.
@@ -521,6 +529,15 @@ export function protectGgufBuffer(
// weight. Route tensor-bearing inputs through the alignment-safe rewriter,
// which keeps tensor infos + data byte-exact and recomputes only padding.
const layout = parsed && parsed.tensorCount > 0n ? parseGgufLayout(bytes) : null;
if (parsed && parsed.tensorCount > 0n && layout === null) {
// The tensor-infos record parsed but the aligned layout did not (an
// out-of-range `general.alignment`, or tensor infos the layout parser
// rejects). Concatenating metadata in front of those infos would shift the
// data section and silently corrupt every weight — refuse instead.
throw new InvalidGgufLayoutError(
"tensor-bearing GGUF has no preservable tensor layout (hostile alignment or malformed tensor infos)",
);
}
if (layout) {
return {
buffer: rebuildGguf(bytes, layout, { appendKvs: kvEntries }),
+68
View File
@@ -68,6 +68,74 @@ print(json.dumps({
}
describe("gguf-layout alignment-safe rewrite", () => {
function makeGgufWithAlignment(alignment: number, dataBytes = 32): Buffer {
const u32 = (n: number): Buffer => {
const b = Buffer.alloc(4);
b.writeUInt32LE(n >>> 0, 0);
return b;
};
const u64 = (n: bigint | number): Buffer => {
const b = Buffer.alloc(8);
b.writeBigUInt64LE(BigInt(n), 0);
return b;
};
const str = (text: string): Buffer => {
const encoded = Buffer.from(text, "utf8");
return Buffer.concat([u64(encoded.length), encoded]);
};
return Buffer.concat([
Buffer.from("GGUF", "ascii"),
u32(3),
u64(1), // tensorCount
u64(1), // kvCount
str("general.alignment"),
u32(4), // UINT32
u32(alignment),
str("w"),
u32(1), // nDims
u64(1), // dim
u32(0), // ggml_type
u64(0), // offset
Buffer.alloc(dataBytes, 7),
]);
}
it("accepts a sane alignment and preserves the tensor bytes", () => {
const bytes = makeGgufWithAlignment(GGUF_DEFAULT_ALIGNMENT);
const layout = parseGgufLayout(bytes);
expect(layout).not.toBeNull();
expect(layout!.alignment).toBe(GGUF_DEFAULT_ALIGNMENT);
const rebuilt = rebuildGguf(bytes, layout!, { appendKvs: [] });
expect(rebuilt.length).toBeGreaterThan(layout!.dataStart);
});
it("rejects an out-of-range general.alignment instead of allocating a huge pad", () => {
// 2 GiB alignment: previously accepted, which made rebuildGguf allocate a
// ~2 GiB zeroed pad and slice away the whole tensor region.
expect(parseGgufLayout(makeGgufWithAlignment(0x80000000))).toBeNull();
expect(parseGgufLayout(makeGgufWithAlignment(0x2000000))).toBeNull();
expect(parseGgufLayout(makeGgufWithAlignment(64))).not.toBeNull();
});
it("refuses to rebuild when the declared data section starts past the input", () => {
const bytes = makeGgufWithAlignment(GGUF_DEFAULT_ALIGNMENT, 2);
const layout = parseGgufLayout(bytes);
expect(layout).not.toBeNull();
expect(layout!.dataStart).toBeGreaterThan(bytes.length);
expect(() => rebuildGguf(bytes, layout!, { appendKvs: [] })).toThrow(
/exceeds the .* input/,
);
});
it("protectGgufBuffer fails closed when a tensor-bearing GGUF has no layout", () => {
expect(() =>
protectGgufBuffer(makeGgufWithAlignment(0x80000000), {
intensity: "balanced",
seed: "gguf-alignment-test",
}),
).toThrow(/tensor-bearing GGUF has no preservable tensor layout/);
});
it("parses a real GGUF and reports the default alignment", () => {
if (!HAS_GGUF_READER) return;
const bytes = makeRealGguf();