From 052d762209264448b3f88c485e0fdf42c4b8cfc3 Mon Sep 17 00:00:00 2001 From: DeryFerd Date: Sun, 15 Nov 2026 16:17:44 +0700 Subject: [PATCH] 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. --- src/shields/formats/gguf-layout.ts | 27 ++++++++++-- src/shields/formats/model.ts | 17 ++++++++ tests/gguf-layout.test.ts | 68 ++++++++++++++++++++++++++++++ 3 files changed, 109 insertions(+), 3 deletions(-) diff --git a/src/shields/formats/gguf-layout.ts b/src/shields/formats/gguf-layout.ts index 16199bd..e681c7a 100644 --- a/src/shields/formats/gguf-layout.ts +++ b/src/shields/formats/gguf-layout.ts @@ -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]); } diff --git a/src/shields/formats/model.ts b/src/shields/formats/model.ts index d537876..dd4ad6f 100644 --- a/src/shields/formats/model.ts +++ b/src/shields/formats/model.ts @@ -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 }), diff --git a/tests/gguf-layout.test.ts b/tests/gguf-layout.test.ts index 44205df..5ec252e 100644 --- a/tests/gguf-layout.test.ts +++ b/tests/gguf-layout.test.ts @@ -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();