refactor(parsers): decode LEB128 through one owner (#10695)

* refactor(parsers): decode LEB128 through one owner

src/domain/leb128.ts owns LEB128 decoding: width, sign and whether padding may extend an encoding are stated per format, and overflow never wraps. ELF attributes, ELF unwind tables, Mach-O bind/rebase operands, Go build-info, protobuf captures and WABT custom names use it instead of six local loops.

* fix(macho): charge rebase operand bytes against the work budget while decoding
This commit is contained in:
morluto authored and GitHub committed 2026-11-15 13:45:36 +08:00
1 parent a67dbe07a4
commit 51e9dc156f
9 files changed
+287 -138

No files matched your search

+3 -8
View File
@@ -1,4 +1,5 @@
import { captureBudgets } from "../CaptureBudgets.js";
import { readLeb128, ULEB64 } from "../../../domain/leb128.js";
import { err, ok, type Result } from "../../../domain/result.js";
import { setImmediate } from "node:timers/promises";
import type { ProtobufField } from "../../../domain/protobufWire.js";
@@ -35,14 +36,8 @@ export const readProtobufVarint = (
start: number,
end = bytes.length,
): { value: bigint; end: number } | undefined => {
let value = 0n;
for (let index = 0; index < 10 && start + index < end; index++) {
const byte = bytes[start + index]!;
if (index === 9 && byte > 1) return undefined;
value |= BigInt(byte & 127) << BigInt(index * 7);
if (byte < 128) return { value, end: start + index + 1 };
}
return undefined;
const read = readLeb128(bytes, start, end, ULEB64);
return "failure" in read ? undefined : { value: read.value, end: read.next };
};
const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+6 -10
View File
@@ -1,17 +1,13 @@
import { readLeb128, ULEB32 } from "./leb128.js";
/** Read a bounded 32-bit ULEB value within an ELF attribute scope. */
export const readElfAttributeUleb = (
bytes: Uint8Array,
offset: number,
end: number,
): { readonly value: number; readonly next: number } | undefined => {
let value = 0;
for (let index = 0; index < 5 && offset + index < end; index += 1) {
const byte = bytes[offset + index]!;
value += (byte & 0x7f) * 2 ** (7 * index);
if ((byte & 0x80) === 0)
return value <= 0xffffffff
? { value, next: offset + index + 1 }
: undefined;
}
return undefined;
const read = readLeb128(bytes, offset, end, ULEB32);
return "failure" in read
? undefined
: { value: Number(read.value), next: read.next };
};
+81
View File
@@ -0,0 +1,81 @@
import { expect, it } from "vitest";
import { readLeb128, SLEB64, ULEB32, ULEB64 } from "./leb128.js";
const read = (bytes: readonly number[], encoding = ULEB64) =>
readLeb128(Uint8Array.from(bytes), 0, bytes.length, encoding);
it.each([
[[0x00], ULEB64, 0n],
[[0xe5, 0x8e, 0x26], ULEB64, 624_485n],
[[0x7f], SLEB64, -1n],
[[0xc0, 0xbb, 0x78], SLEB64, -123_456n],
[[0xff, 0xff, 0xff, 0xff, 0x0f], ULEB32, 0xffff_ffffn],
[
[0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x01],
ULEB64,
0xffff_ffff_ffff_ffffn,
],
[
[0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x7f],
SLEB64,
-(2n ** 63n),
],
[
[0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x00],
SLEB64,
2n ** 63n - 1n,
],
] as const)("decodes %j", (bytes, encoding, value) => {
expect(read(bytes, encoding)).toEqual({ value, next: bytes.length });
});
it.each([
["a 33-bit value in 32 bits", [0xff, 0xff, 0xff, 0xff, 0x1f], ULEB32, 4],
["a sixth byte in 32 bits", [0x80, 0x80, 0x80, 0x80, 0x80, 0x00], ULEB32, 5],
[
"a 65-bit value",
[0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x02],
ULEB64,
9,
],
[
"a sign that does not repeat",
[0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x01],
SLEB64,
9,
],
] as const)("refuses %s as overflow", (_, bytes, encoding, at) => {
expect(read(bytes, encoding)).toEqual({ failure: "overflow", at });
});
it("refuses an encoding that runs past its end as truncated", () => {
expect(read([0x80, 0x80])).toEqual({ failure: "truncated", at: 2 });
expect(readLeb128(Uint8Array.from([0x80, 0x00]), 0, 1, ULEB64)).toEqual({
failure: "truncated",
at: 1,
});
});
it("accepts padding only where the format allows it, and only as the sign", () => {
const padded = [
0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x81, 0x80, 0x00,
];
expect(read(padded)).toEqual({ failure: "overflow", at: 10 });
expect(read(padded, { ...ULEB64, padding: true })).toEqual({
value: 0xffff_ffff_ffff_ffffn,
next: padded.length,
});
expect(
read([0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x80, 0x81, 0x01], {
...ULEB64,
padding: true,
}),
).toEqual({ failure: "overflow", at: 10 });
expect(
read([0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f], {
...SLEB64,
padding: true,
}),
).toEqual({ value: -1n, next: 11 });
});
+81
View File
@@ -0,0 +1,81 @@
/**
* The one LEB128 decoder. Formats differ only in the integer width, the sign,
* and whether redundant padding bytes may extend an encoding; each states
* those choices here instead of re-deriving the overflow rules.
*/
export interface Leb128Encoding {
readonly signed: boolean;
/** Width of the integer the encoding must fit. */
readonly bits: 32 | 64;
/**
* Whether bytes that only repeat the sign (or zero) may extend the encoding
* past `ceil(bits / 7)` bytes. Mach-O opcode operands allow this; DWARF,
* ELF attribute, Go and protobuf readers stop at the minimal width.
*/
readonly padding?: boolean;
}
/** Why no value was decoded: the bytes ended first, or the value or encoding exceeds `bits`. */
export type Leb128Failure = "truncated" | "overflow";
export type Leb128Read =
| { readonly value: bigint; readonly next: number }
| {
readonly failure: Leb128Failure;
/** Offset of the byte that overflowed, or of the end the encoding ran past. */
readonly at: number;
};
export const ULEB32: Leb128Encoding = { signed: false, bits: 32 };
export const ULEB64: Leb128Encoding = { signed: false, bits: 64 };
export const SLEB64: Leb128Encoding = { signed: true, bits: 64 };
/**
* Decode one LEB128 integer from `bytes[offset, end)`.
*
* Bits beyond `bits` must repeat the sign (signed) or be zero (unsigned);
* otherwise the read fails as `overflow` and never wraps.
*/
export const readLeb128 = (
bytes: Uint8Array,
offset: number,
end: number,
encoding: Leb128Encoding,
): Leb128Read => {
const { signed, bits } = encoding;
const limit = Math.min(end, bytes.length);
const maximumBytes =
encoding.padding === true ? Number.POSITIVE_INFINITY : Math.ceil(bits / 7);
let value = 0n;
let shift = 0;
let negative = false;
for (let index = offset, count = 0; ; index++, count++) {
if (count >= maximumBytes) return { failure: "overflow", at: index };
if (index < 0 || index >= limit) return { failure: "truncated", at: index };
const byte = bytes[index]!;
const payload = byte & 0x7f;
if (shift >= bits) {
// A padding byte carries no value bits; it can only repeat the sign.
if (payload !== (negative ? 0x7f : 0))
return { failure: "overflow", at: index };
} else if (shift + 7 > bits) {
const kept = bits - shift;
const high = payload >> kept;
if (signed) {
negative = ((payload >> (kept - 1)) & 1) === 1;
if (high !== (negative ? 0x7f >> kept : 0))
return { failure: "overflow", at: index };
} else if (high !== 0) return { failure: "overflow", at: index };
value |= BigInt(payload & ((1 << kept) - 1)) << BigInt(shift);
} else value |= BigInt(payload) << BigInt(shift);
shift += 7;
if ((byte & 0x80) === 0) {
if (signed) {
if (shift < bits) {
if ((payload & 0x40) !== 0) value -= 1n << BigInt(shift);
} else if (negative) value -= 1n << BigInt(bits);
}
return { value, next: index + 1 };
}
}
};
+31 -37
View File
@@ -1,3 +1,4 @@
import { readLeb128, ULEB64 } from "../domain/leb128.js";
import type {
FileMapping,
ZeroFillMapping,
@@ -349,44 +350,37 @@ const readInlineExtent = (
remaining: number,
maximumBytes: number,
): { readonly location: GoStringLocation; readonly next: number } => {
let length = 0n;
for (let index = 0; index < 10; index++) {
if (index >= remaining)
throw new BinaryFormatFailure(
"malformed",
"Go build-info varint is truncated",
);
const byte = reader.bytes[offset + index] ?? 0;
if (index === 9 && byte > 1)
throw new BinaryFormatFailure(
"malformed",
"Go build-info varint overflows 64 bits",
);
length |= BigInt(byte & 127) << BigInt(index * 7);
if ((byte & 128) === 0) {
if (length > BigInt(remaining - index - 1))
throw new BinaryFormatFailure(
"malformed",
"Go build-info string range is truncated",
);
if (length > BigInt(maximumBytes))
throw new BinaryResourceFailure(
"build-info",
maximumBytes,
`Go build-info string length exceeds max_build_info_bytes=${String(maximumBytes)}`,
);
const size = Number(length);
const start = offset + index + 1;
return {
location: { offset: start, bytes: size },
next: start + size,
};
}
}
throw new BinaryFormatFailure(
"malformed",
"Go build-info varint is unterminated",
const read = readLeb128(
reader.bytes,
offset,
offset + Math.max(0, remaining),
ULEB64,
);
if ("failure" in read)
throw new BinaryFormatFailure(
"malformed",
read.failure === "truncated"
? "Go build-info varint is truncated"
: "Go build-info varint overflows 64 bits",
);
const start = read.next;
const length = read.value;
if (length > BigInt(remaining - (start - offset)))
throw new BinaryFormatFailure(
"malformed",
"Go build-info string range is truncated",
);
if (length > BigInt(maximumBytes))
throw new BinaryResourceFailure(
"build-info",
maximumBytes,
`Go build-info string length exceeds max_build_info_bytes=${String(maximumBytes)}`,
);
const size = Number(length);
return {
location: { offset: start, bytes: size },
next: start + size,
};
};
interface PointerStringContext {
+30
View File
@@ -478,6 +478,36 @@ const legacyRebaseInput = (stream: Buffer) => {
};
};
it("charges a padded rebase operand that exhausts the work budget", () => {
// Work is bounded by twice the source bytes (0x20000). Each padded
// SET_SEGMENT_AND_OFFSET_ULEB stream charges ~51 KiB, so the third exhausts
// the budget and a later valid stream must not run on uncharged work.
const data = Buffer.alloc(0x10000);
const padding = 0xc800;
const padded = Buffer.concat([
Buffer.from([0x11, 0x20]),
Buffer.alloc(padding, 0x80),
Buffer.from([0, 0]),
]);
padded.copy(data, 0x2000);
const valid = Buffer.from([0x11, 0x20, 0x80, 0x02, 0x51, 0]);
valid.copy(data, 0xf000);
const stream = { offset: 0x2000, size: padded.length };
const fixups = parsePointerFixups(
data,
{
chained: null,
binds: [],
rebases: [stream, stream, stream, { offset: 0xf000, size: valid.length }],
dylibs: [],
},
[{ address: BASE, size: 0x2000n, offset: 0, executable: false }],
BASE,
);
expect(fixups).toMatchObject({ examined: 4, decoded: 2 });
expect(fixups.issues).toHaveLength(2);
});
it("marks only opcode-selected pointer slots rebased, including target zero", () => {
// SET_TYPE(pointer), SET_SEGMENT(offset 0x100), DO once,
// ADD_ADDR(0x10), DO once, DONE.
+40 -41
View File
@@ -5,6 +5,7 @@ import {
unsupportedInput,
} from "../domain/parseFailure.js";
import type { Segment } from "./AppleMachoSelection.js";
import { readLeb128, type Leb128Read } from "../domain/leb128.js";
import { issue } from "./AppleDispatchDecodeFacts.js";
import type { DecodeIssue } from "./AppleDispatchDecodeFacts.js";
import { decodeMachoName, type MachoName } from "./AppleMachoNames.js";
@@ -887,6 +888,16 @@ const chainedFixups = (
};
};
/** Mach-O opcode operands are 64-bit, and padding may extend their encoding. */
const MACHO_ULEB = { signed: false, bits: 64, padding: true } as const;
const MACHO_SLEB = { signed: true, bits: 64, padding: true } as const;
/** The offset after the last byte read, including an overflowing byte. */
const consumedEnd = (read: Leb128Read): number =>
"failure" in read
? read.at + (read.failure === "overflow" ? 1 : 0)
: read.next;
const uleb = (
bytes: Buffer,
cursor: { at: number },
@@ -894,28 +905,29 @@ const uleb = (
stream: "bind" | "rebase" = "bind",
rebaseWork?: { workRemaining: number },
): bigint => {
let value = 0n;
let shift = 0;
for (;;) {
if (cursor.at >= end)
throw truncatedInput("macho", `Truncated ${stream} opcode operand`);
if (rebaseWork !== undefined) {
if (rebaseWork.workRemaining === 0)
throw malformedInput(
"macho",
"Legacy rebase parsing exceeded the source-derived work budget",
);
rebaseWork.workRemaining--;
}
const byte = bytes[cursor.at++] ?? 0;
const slice = byte & 0x7f;
if ((shift === 63 && slice > 1) || (shift === 64 && slice !== 0))
throw malformedInput("macho", `Oversized ${stream} opcode operand`);
if (shift < 64) value |= BigInt(slice) << BigInt(shift);
// Padding may extend the encoding, but never the represented integer.
shift = Math.min(64, shift + 7);
if ((byte & 0x80) === 0) return value;
const start = cursor.at;
// A rebase operand reads no further than its remaining work allows, so a
// padded operand cannot be rescanned past the budget by a later stream.
const bound =
rebaseWork === undefined
? end
: Math.min(end, start + rebaseWork.workRemaining);
const read = readLeb128(bytes, start, bound, MACHO_ULEB);
cursor.at = consumedEnd(read);
if (rebaseWork !== undefined) {
// Each byte read is charged, including those of a failed operand.
rebaseWork.workRemaining -= cursor.at - start;
if ("failure" in read && read.failure === "truncated" && read.at < end)
throw malformedInput(
"macho",
"Legacy rebase parsing exceeded the source-derived work budget",
);
}
if ("failure" in read)
throw read.failure === "truncated"
? truncatedInput("macho", `Truncated ${stream} opcode operand`)
: malformedInput("macho", `Oversized ${stream} opcode operand`);
return read.value;
};
interface RebaseFacts {
@@ -1176,26 +1188,13 @@ function* parseLegacyRebasesSteps(
}
const sleb = (bytes: Buffer, cursor: { at: number }, end: number): bigint => {
let value = 0n;
let shift = 0;
let byte = 0;
do {
if (cursor.at >= end)
throw truncatedInput("macho", "Truncated bind opcode operand");
byte = bytes[cursor.at++] ?? 0;
const slice = byte & 0x7f;
if (
(shift === 63 && slice !== 0 && slice !== 0x7f) ||
(shift === 64 && slice !== (value < 0n ? 0x7f : 0))
)
throw malformedInput("macho", "Oversized bind opcode operand");
if (shift < 64)
value = BigInt.asIntN(64, value | (BigInt(slice) << BigInt(shift)));
shift = Math.min(64, shift + 7);
} while ((byte & 0x80) !== 0);
return shift < 64 && (byte & 0x40) !== 0
? value - (1n << BigInt(shift))
: value;
const read = readLeb128(bytes, cursor.at, end, MACHO_SLEB);
cursor.at = consumedEnd(read);
if ("failure" in read)
throw read.failure === "truncated"
? truncatedInput("macho", "Truncated bind opcode operand")
: malformedInput("macho", "Oversized bind opcode operand");
return read.value;
};
/** Registers of the `LC_DYLD_INFO` bind state machine. */
+3 -23
View File
@@ -1,4 +1,5 @@
import { admitElfLoadSegment } from "../../domain/elfProgramHeader.js";
import { readLeb128, SLEB64, ULEB64 } from "../../domain/leb128.js";
import { assertArtifactReadActive } from "../../artifacts/ArtifactFileOperation.js";
import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
import { readElfDynamicEntry } from "../../domain/elfDynamicEntry.js";
@@ -474,29 +475,8 @@ export const parseElfUnwindRanges = (
end: number,
signed: boolean,
): { readonly value: bigint; readonly next: number } | null => {
let result = 0n;
let shift = 0n;
let pos = offset;
let byte = 0;
while (pos < end && pos < bytes.length && shift <= 63n) {
byte = bytes[pos] ?? 0;
pos += 1;
// At bit 63 only one value bit remains; signed padding repeats that bit.
const payload = byte & 0x7f;
if (
shift === 63n &&
(signed ? payload !== 0 && payload !== 0x7f : payload > 1)
)
return null;
result |= BigInt(payload) << shift;
shift += 7n;
if ((byte & 0x80) === 0) {
// Ten-byte signed operands have 70 encoded bits, including sign padding.
if (signed && (byte & 0x40) !== 0) result |= -1n << shift;
return { value: result, next: pos };
}
}
return null;
const read = readLeb128(bytes, offset, end, signed ? SLEB64 : ULEB64);
return "failure" in read ? null : read;
};
const safeInt = (value: bigint): number | null =>
value >= BigInt(Number.MIN_SAFE_INTEGER) &&
+12 -19
View File
@@ -1,4 +1,5 @@
import { WabtAdmissionError } from "./WabtAdmissionError.js";
import { readLeb128, ULEB32 } from "../domain/leb128.js";
/** WABT prints names with %.*s, so an embedded NUL ends their display. */
const wabtDisplayedName = (name: string | undefined): string | undefined =>
@@ -99,24 +100,16 @@ const invalidCustomNameEnd = (
): number | undefined => {
if (bytes === undefined || end > bytes.length || start >= end)
return undefined;
let length = 0;
let position = start;
for (let shift = 0; shift <= 28; shift += 7) {
const byte = bytes[position++];
if (byte === undefined || position > end || (shift === 28 && byte > 15))
return undefined;
length += (byte & 0x7f) * 2 ** shift;
if ((byte & 0x80) !== 0) continue;
const nameEnd = position + length;
if (nameEnd > end) return undefined;
try {
new TextDecoder("utf-8", { fatal: true }).decode(
bytes.subarray(position, nameEnd),
);
return undefined;
} catch {
return nameEnd;
}
const read = readLeb128(bytes, start, end, ULEB32);
if ("failure" in read) return undefined;
const nameEnd = read.next + Number(read.value);
if (nameEnd > end) return undefined;
try {
new TextDecoder("utf-8", { fatal: true }).decode(
bytes.subarray(read.next, nameEnd),
);
return undefined;
} catch {
return nameEnd;
}
return undefined;
};