yom-format 0.1.0

package/src/yom/byteSource.ts

@@ -0,0 +1,144 @@
+import { RangeNotSupportedError, YOMError } from "./errors.js";
+
+/**
+ * Gap 1: the byte-source abstraction every reader read goes through, so the
+ * same `YOMPackfileReader` can serve a fully in-memory `.yom` or one streamed
+ * over HTTP `Range` requests without ever loading the whole file.
+ */
+export interface ByteSource {
+  /** Total file length in bytes. */
+  readonly size: number;
+  /** Reads exactly `[offset, offset+length)`; rejects if it can't. */
+  read(offset: number, length: number): Promise<Uint8Array>;
+}
+
+/** Raised when a `ByteSource.read` cannot return the requested extent. */
+export class ByteSourceError extends YOMError {}
+
+/** A `ByteSource` over an already-resident `Uint8Array` (zero-copy slices). */
+export class MemoryByteSource implements ByteSource {
+  readonly size: number;
+  private readonly bytes: Uint8Array;
+
+  constructor(bytes: Uint8Array) {
+    this.bytes = bytes;
+    this.size = bytes.length;
+  }
+
+  read(offset: number, length: number): Promise<Uint8Array> {
+    if (offset < 0 || length < 0 || offset + length > this.bytes.length) {
+      return Promise.reject(new ByteSourceError(`read [${offset}, ${offset + length}) out of bounds (size ${this.size})`));
+    }
+    return Promise.resolve(this.bytes.subarray(offset, offset + length));
+  }
+}
+
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface HttpRangeOptions {
+  /** Override the global `fetch` (for tests / custom transports). */
+  fetch?: FetchLike;
+  /** Extra request headers (auth, etc.). */
+  headers?: Record<string, string>;
+  /** Skip the size probe if the caller already knows `Content-Length`. */
+  size?: number;
+  /** Abort in-flight requests. */
+  signal?: AbortSignal;
+}
+
+/**
+ * A `ByteSource` backed by HTTP `Range` requests. `create()` learns the total
+ * size and confirms range support up front (one `Range: bytes=0-` probe, or a
+ * caller-supplied `size`); each `read()` issues `GET Range: bytes=a-b`,
+ * validates the `206` + `Content-Range`/length, and returns the slice.
+ *
+ * The server must answer `206 Partial Content` to ranged requests; a plain
+ * `200 OK` means ranges are unsupported and `create()` throws
+ * `RangeNotSupportedError`. For cross-origin use the server must expose
+ * `Content-Range`, `Accept-Ranges`, and `Content-Length` via CORS.
+ */
+export class HttpRangeByteSource implements ByteSource {
+  readonly size: number;
+  private readonly url: string;
+  private readonly fetchFn: FetchLike;
+  private readonly headers: Record<string, string>;
+  private readonly signal?: AbortSignal;
+
+  private constructor(url: string, size: number, opts: HttpRangeOptions) {
+    this.url = url;
+    this.size = size;
+    this.fetchFn = opts.fetch ?? ((input, init) => fetch(input, init));
+    this.headers = opts.headers ?? {};
+    this.signal = opts.signal;
+  }
+
+  static async create(url: string, opts: HttpRangeOptions = {}): Promise<HttpRangeByteSource> {
+    const fetchFn: FetchLike = opts.fetch ?? ((input, init) => fetch(input, init));
+    const headers = opts.headers ?? {};
+
+    if (typeof opts.size === "number") {
+      return new HttpRangeByteSource(url, opts.size, opts);
+    }
+
+    // Probe with an open-ended range: a range-capable server answers 206 with
+    // a `Content-Range: bytes 0-.../TOTAL` from which we learn the size.
+    const res = await fetchFn(url, {
+      method: "GET",
+      headers: { ...headers, Range: "bytes=0-0" },
+      signal: opts.signal,
+    });
+    if (res.status === 200) {
+      // Server ignored the range and sent the whole body.
+      throw new RangeNotSupportedError(`server does not support range requests (status 200) for ${url}`);
+    }
+    if (res.status !== 206) {
+      throw new ByteSourceError(`unexpected status ${res.status} probing ${url}`);
+    }
+    const total = parseContentRangeTotal(res.headers.get("Content-Range"));
+    if (total === null) {
+      const len = res.headers.get("Content-Length");
+      throw new ByteSourceError(
+        `range probe missing Content-Range total for ${url} (Content-Length ${len ?? "?"})`,
+      );
+    }
+    // Drain the tiny probe body to release the connection.
+    await res.arrayBuffer().catch(() => undefined);
+    return new HttpRangeByteSource(url, total, opts);
+  }
+
+  async read(offset: number, length: number): Promise<Uint8Array> {
+    if (offset < 0 || length < 0 || offset + length > this.size) {
+      throw new ByteSourceError(`read [${offset}, ${offset + length}) out of bounds (size ${this.size})`);
+    }
+    if (length === 0) return new Uint8Array(0);
+
+    const end = offset + length - 1; // HTTP ranges are inclusive
+    const res = await this.fetchFn(this.url, {
+      method: "GET",
+      headers: { ...this.headers, Range: `bytes=${offset}-${end}` },
+      signal: this.signal,
+    });
+    if (res.status === 200) {
+      throw new RangeNotSupportedError(`server ignored range request (status 200) for ${this.url}`);
+    }
+    if (res.status !== 206) {
+      throw new ByteSourceError(`unexpected status ${res.status} reading ${this.url}`);
+    }
+    const body = new Uint8Array(await res.arrayBuffer());
+    if (body.length !== length) {
+      throw new ByteSourceError(`range read returned ${body.length} bytes, expected ${length}`);
+    }
+    return body;
+  }
+}
+
+/** Parses the `TOTAL` out of a `Content-Range: bytes A-B/TOTAL` header. */
+function parseContentRangeTotal(header: string | null): number | null {
+  if (!header) return null;
+  const slash = header.lastIndexOf("/");
+  if (slash < 0) return null;
+  const total = header.slice(slash + 1).trim();
+  if (total === "" || total === "*") return null;
+  const parsed = Number(total);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
+}

package/src/yom/bytes.ts

@@ -0,0 +1,11 @@
+export function concatBytes(chunks: Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const chunk of chunks) total += chunk.length;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}

package/src/yom/constants.ts

@@ -0,0 +1,89 @@
+import { BlobKind } from "./generated/yomu/yom/blob-kind.js";
+import { Compression } from "./generated/yomu/yom/compression.js";
+
+/**
+ * YOM v1 format constants shared by the writer, reader, and validator.
+ * Mirrors the Swift implementation in `swift/Sources/YOMFormat/YOMConstants.swift`
+ * field-for-field so Web- and native-generated `.yom` packages agree on
+ * layout. See docs/format-spec.md for rationale.
+ */
+export const YOM_FILE_EXTENSION = "yom";
+export const YOM_MIME_TYPE = "application/vnd.yomu.yom";
+export const YOM_MAGIC = new Uint8Array([0x59, 0x4f, 0x4d, 0x31]); // "YOM1"
+export const YOM_HEADER_SIZE = 4096;
+export const YOM_FORMAT_VERSION = 1;
+export const YOM_HASH_LENGTH = 32;
+export const YOM_IMAGE_BLOB_ALIGNMENT = 16;
+export const YOM_DEFAULT_BLOB_ALIGNMENT = 1;
+
+export function requiredCompression(kind: BlobKind): Compression {
+  switch (kind) {
+    case BlobKind.PageImage:
+    case BlobKind.ThumbnailImage:
+    case BlobKind.SearchPostings:
+      return Compression.None;
+    case BlobKind.OCRLayout:
+    case BlobKind.NormalizedText:
+    case BlobKind.SearchDictionary:
+      return Compression.Zstd;
+    default:
+      throw new Error(`unknown blob kind: ${kind}`);
+  }
+}
+
+export function requiredAlignment(kind: BlobKind): number {
+  switch (kind) {
+    case BlobKind.PageImage:
+    case BlobKind.ThumbnailImage:
+      return YOM_IMAGE_BLOB_ALIGNMENT;
+    default:
+      return YOM_DEFAULT_BLOB_ALIGNMENT;
+  }
+}
+
+/*
+ * -------------------------------------------------------------------------
+ * Reader-side safety limits (Gap 2 hardening).
+ *
+ * IMPORTANT: these are **reader policy, NOT format requirements**. The writer
+ * MUST NOT enforce them and the on-disk format places no upper bound on blob
+ * sizes -- a conforming `.yom` may legally exceed any of these. They exist
+ * only so a *reader* can refuse to allocate unbounded memory for a malformed
+ * or hostile file (decompression bombs, forged declared sizes) before it
+ * touches the data. Values are chosen comfortably above every real-world and
+ * fixture blob size; raise them if a legitimate corpus needs more.
+ * -------------------------------------------------------------------------
+ */
+
+/** Per-kind cap on a blob's declared `uncompressed_length`, in bytes. */
+export const MAX_BLOB_UNCOMPRESSED_IMAGE = 64 * 1024 * 1024; // page/thumbnail AVIF
+export const MAX_BLOB_UNCOMPRESSED_TEXT = 16 * 1024 * 1024; // OCR / normalized text / dictionary
+export const MAX_BLOB_UNCOMPRESSED_POSTINGS = 64 * 1024 * 1024; // search postings scale with book size
+
+/** Cap on the sum of every blob's declared `uncompressed_length` (whole-file validation). */
+export const MAX_TOTAL_UNCOMPRESSED = 4 * 1024 * 1024 * 1024;
+
+/**
+ * Reject a blob whose declared inflation ratio
+ * (`uncompressed_length / max(compressed_length, 1)`) exceeds this -- the
+ * classic zip/zstd-bomb signature. zstd rarely exceeds ~3-5x on scanned-book
+ * text/OCR, so 1000x is a generous safety margin.
+ */
+export const MAX_INFLATION_RATIO = 1000;
+
+/** The `uncompressed_length` cap that applies to a blob of the given kind. */
+export function maxBlobUncompressed(kind: BlobKind): number {
+  switch (kind) {
+    case BlobKind.PageImage:
+    case BlobKind.ThumbnailImage:
+      return MAX_BLOB_UNCOMPRESSED_IMAGE;
+    case BlobKind.SearchPostings:
+      return MAX_BLOB_UNCOMPRESSED_POSTINGS;
+    case BlobKind.OCRLayout:
+    case BlobKind.NormalizedText:
+    case BlobKind.SearchDictionary:
+      return MAX_BLOB_UNCOMPRESSED_TEXT;
+    default:
+      return MAX_BLOB_UNCOMPRESSED_TEXT;
+  }
+}

package/src/yom/errors.ts

@@ -0,0 +1,43 @@
+/**
+ * Typed error hierarchy for the YOM reader/validator hardening layers.
+ *
+ * These are all *reader-side* failures raised while opening or reading a
+ * possibly-hostile `.yom`. They exist so callers can distinguish "the input
+ * is malformed/oversized/corrupt" from ordinary programming errors, and so
+ * the size-cap / FlatBuffers-verify / HTTP-Range layers throw a stable,
+ * catchable type instead of a bare `Error`.
+ */
+
+/** Base class for every typed reader error added by the hardening layers. */
+export class YOMError extends Error {}
+
+/**
+ * A blob's declared `uncompressed_length` exceeds the reader's per-kind size
+ * cap, or its declared inflation ratio (`uncompressed / compressed`) exceeds
+ * `MAX_INFLATION_RATIO`. Raised *before* any decompression happens, so a
+ * decompression-bomb never gets to allocate memory.
+ */
+export class BlobTooLargeError extends YOMError {}
+
+/**
+ * A blob decompressed to a different byte length than its declared
+ * `uncompressed_length` (or decompression otherwise failed). Raised before
+ * the decompressed bytes are used, ahead of the final SHA-256 gate.
+ */
+export class CorruptBlobError extends YOMError {}
+
+/**
+ * The main FlatBuffers index (or an OCR layout blob) failed bounded
+ * structural verification: an offset, vtable, table, string, or vector would
+ * dereference outside the known index byte range, or a vector length is
+ * absurdly large. Raised instead of returning a booby-trapped `getRootAs*`
+ * root that could later read out of bounds.
+ */
+export class MalformedIndexError extends YOMError {}
+
+/**
+ * An HTTP source does not support range requests (it answered a ranged `GET`
+ * with `200 OK` / no `Accept-Ranges` instead of `206 Partial Content`).
+ * Callers may retry with `openURL(url, { fallbackToFullFetch: true })`.
+ */
+export class RangeNotSupportedError extends YOMError {}

package/src/yom/flatbufferVerify.ts

@@ -0,0 +1,298 @@
+import { ByteBuffer } from "flatbuffers";
+import { MainIndex } from "./generated/yomu/yom/main-index.js";
+import { MalformedIndexError } from "./errors.js";
+
+/**
+ * Gap 3: schema-aware bounded verification of the main FlatBuffers index
+ * before `getRootAsMainIndex` traversal.
+ *
+ * `flatc` emits no TypeScript verifier, so this is a hand-written structural
+ * walk (spec option B). Given the index occupies exactly `[0, indexLength)`,
+ * it bounds-checks every offset the reader could dereference -- the root table
+ * offset, each vtable, each field, each string, and each vector -- against
+ * that range. Critically, before trusting any vector it asserts
+ * `4 + count * elementStride <= remaining bytes`, so a forged huge vector
+ * count can never drive an out-of-bounds read or an O(count) allocation/hang.
+ *
+ * Two depths:
+ *  - `deep: false` (reader open, hot path): verify the root table plus the
+ *    header + length bounds of its own vectors/sub-object pointers. Cheap.
+ *  - `deep: true` (`validateYOM`): additionally recurse into every page, blob,
+ *    search term, and outline sub-table -- i.e. touch every field the reader
+ *    or validator will ever touch.
+ *
+ * On any violation it throws `MalformedIndexError`; it never reads out of
+ * bounds, never allocates from an attacker-controlled length, and never hangs.
+ */
+
+type FieldSpec =
+  | { readonly slot: number; readonly kind: "scalar"; readonly size: number }
+  | { readonly slot: number; readonly kind: "string" }
+  | { readonly slot: number; readonly kind: "table"; readonly table: string }
+  | { readonly slot: number; readonly kind: "vectorScalar"; readonly stride: number }
+  | { readonly slot: number; readonly kind: "vectorString" }
+  | { readonly slot: number; readonly kind: "vectorTable"; readonly table: string };
+
+// vtable slot for field id N == 4 + N*2 (see the generated `__offset(_, slot)` calls).
+const SCHEMAS: Record<string, readonly FieldSpec[]> = {
+  MainIndex: [
+    { slot: 4, kind: "scalar", size: 4 }, // formatVersion
+    { slot: 6, kind: "table", table: "BookMetadata" }, // book
+    { slot: 8, kind: "vectorTable", table: "PageEntry" }, // pages
+    { slot: 10, kind: "vectorTable", table: "BlobRef" }, // blobs
+    { slot: 12, kind: "scalar", size: 4 }, // ocrLayoutBlobIndex
+    { slot: 14, kind: "scalar", size: 4 }, // normalizedTextBlobIndex
+    { slot: 16, kind: "scalar", size: 4 }, // searchDictionaryBlobIndex
+    { slot: 18, kind: "scalar", size: 4 }, // searchPostingsBlobIndex
+    { slot: 20, kind: "vectorTable", table: "SearchTermRef" }, // searchTerms
+    // NOTE: `pdfExport` (slot 22) is intentionally NOT traversed. The TS
+    // reader/validator never dereference it, and the writer emits it via
+    // FlatBuffers `forceDefaults(true)`, which encodes an *absent* offset
+    // field as a present-but-sentinel value that points outside the buffer.
+    // Dereferencing it would falsely reject every writer-produced file. Its
+    // schema (below) is retained only for reference / future use.
+  ],
+  BookMetadata: [
+    { slot: 4, kind: "string" }, // title
+    { slot: 6, kind: "scalar", size: 4 }, // pageCount
+    { slot: 8, kind: "scalar", size: 1 }, // readingDirection
+    { slot: 10, kind: "scalar", size: 8 }, // createdAtUnix
+  ],
+  PageEntry: [
+    { slot: 4, kind: "scalar", size: 4 }, // pageId
+    { slot: 6, kind: "string" }, // pageLabel
+    { slot: 8, kind: "scalar", size: 4 }, // pixelWidth
+    { slot: 10, kind: "scalar", size: 4 }, // pixelHeight
+    { slot: 12, kind: "scalar", size: 4 }, // dpi
+    { slot: 14, kind: "string" }, // colorSpace
+    { slot: 16, kind: "string" }, // colorProfileRef
+    { slot: 18, kind: "vectorScalar", stride: 4 }, // mediaBox
+    { slot: 20, kind: "vectorScalar", stride: 4 }, // cropBox
+    { slot: 22, kind: "vectorScalar", stride: 4 }, // contentBox
+    { slot: 24, kind: "scalar", size: 4 }, // rotation
+    { slot: 26, kind: "scalar", size: 1 }, // readingDirection
+    { slot: 28, kind: "scalar", size: 4 }, // pageImageBlobIndex
+    { slot: 30, kind: "scalar", size: 4 }, // thumbnailBlobIndex
+    { slot: 32, kind: "vectorScalar", stride: 1 }, // imageHash
+  ],
+  BlobRef: [
+    { slot: 4, kind: "scalar", size: 1 }, // kind
+    { slot: 6, kind: "scalar", size: 8 }, // offset
+    { slot: 8, kind: "scalar", size: 8 }, // compressedLength
+    { slot: 10, kind: "scalar", size: 8 }, // uncompressedLength
+    { slot: 12, kind: "scalar", size: 1 }, // compression
+    { slot: 14, kind: "scalar", size: 4 }, // alignment
+    { slot: 16, kind: "vectorScalar", stride: 1 }, // hash
+  ],
+  SearchTermRef: [
+    { slot: 4, kind: "string" }, // term
+    { slot: 6, kind: "scalar", size: 8 }, // dictionaryOffset
+    { slot: 8, kind: "scalar", size: 8 }, // dictionaryLength
+    { slot: 10, kind: "scalar", size: 8 }, // postingsOffset
+    { slot: 12, kind: "scalar", size: 8 }, // postingsLength
+  ],
+  PDFExportMetadata: [
+    { slot: 4, kind: "vectorString" }, // pageLabels
+    { slot: 6, kind: "vectorTable", table: "OutlineEntry" }, // outline
+  ],
+  OutlineEntry: [
+    { slot: 4, kind: "string" }, // title
+    { slot: 6, kind: "scalar", size: 4 }, // pageId
+    { slot: 8, kind: "vectorTable", table: "OutlineEntry" }, // children (recursive)
+  ],
+};
+
+const MAX_DEPTH = 64;
+const UOFFSET = 4;
+
+class BoundsVerifier {
+  private readonly buf: Uint8Array;
+  private readonly len: number;
+
+  constructor(buf: Uint8Array) {
+    this.buf = buf;
+    this.len = buf.length;
+  }
+
+  private fail(reason: string): never {
+    throw new MalformedIndexError(`malformed index: ${reason}`);
+  }
+
+  /** Assert `[pos, pos+size)` lies inside the index. */
+  private require(pos: number, size: number, reason: string): void {
+    if (!Number.isInteger(pos) || pos < 0 || size < 0 || pos + size > this.len) {
+      this.fail(`${reason} (pos=${pos} size=${size} len=${this.len})`);
+    }
+  }
+
+  private i32(pos: number): number {
+    this.require(pos, 4, "read int32");
+    const b = this.buf;
+    return b[pos] | (b[pos + 1] << 8) | (b[pos + 2] << 16) | (b[pos + 3] << 24);
+  }
+
+  private u32(pos: number): number {
+    return this.i32(pos) >>> 0;
+  }
+
+  private u16(pos: number): number {
+    this.require(pos, 2, "read uint16");
+    return this.buf[pos] | (this.buf[pos + 1] << 8);
+  }
+
+  /**
+   * Bounds-verify a single optional field of the root table. Returns `false`
+   * when the field is genuinely absent OR encoded as a forced-default sentinel
+   * that points out of bounds (so a caller can safely decide not to read it);
+   * returns `true` only when the field is present and structurally sound.
+   */
+  verifyOptionalRootField(rootTable: string, field: FieldSpec, deep: boolean): boolean {
+    const tablePos = this.i32(0);
+    this.require(tablePos, 4, "root soffset");
+    const soffset = this.i32(tablePos);
+    const vtablePos = tablePos - soffset;
+    this.require(vtablePos, 4, "root vtable header");
+    const vtableSize = this.u16(vtablePos);
+    if (vtableSize < 4) this.fail("root vtable too small");
+    this.require(vtablePos, vtableSize, "root vtable body");
+    if (field.slot + 2 > vtableSize) return false;
+    const rel = this.u16(vtablePos + field.slot);
+    if (rel === 0) return false;
+    this.verifyField(tablePos + rel, field, deep, 0, rootTable);
+    return true;
+  }
+
+  /** Verify the root object offset and the table it points at. */
+  verifyRoot(rootTable: string, deep: boolean): void {
+    // getRootAs* computes rootPos = readInt32(0) + 0 (signed, like every
+    // FlatBuffers offset -- child objects can lie at lower addresses).
+    const rootPos = this.i32(0);
+    this.verifyTable(rootPos, rootTable, deep, 0);
+  }
+
+  private verifyTable(tablePos: number, tableName: string, deep: boolean, depth: number): void {
+    if (depth > MAX_DEPTH) this.fail("table nesting too deep");
+    this.require(tablePos, 4, `table ${tableName} soffset`);
+    const soffset = this.i32(tablePos);
+    const vtablePos = tablePos - soffset;
+    this.require(vtablePos, 4, `table ${tableName} vtable header`);
+    const vtableSize = this.u16(vtablePos);
+    if (vtableSize < 4) this.fail(`table ${tableName} vtable too small`);
+    this.require(vtablePos, vtableSize, `table ${tableName} vtable body`);
+    const tableSize = this.u16(vtablePos + 2);
+    this.require(tablePos, tableSize, `table ${tableName} inline data`);
+
+    const fields = SCHEMAS[tableName];
+    if (!fields) this.fail(`unknown table ${tableName}`);
+    for (const field of fields) {
+      // A field's vtable slot may lie beyond this vtable (field absent).
+      if (field.slot + 2 > vtableSize) continue;
+      const rel = this.u16(vtablePos + field.slot);
+      if (rel === 0) continue; // absent / default
+      const fieldPos = tablePos + rel;
+      this.verifyField(fieldPos, field, deep, depth, tableName);
+    }
+  }
+
+  private verifyField(fieldPos: number, field: FieldSpec, deep: boolean, depth: number, owner: string): void {
+    switch (field.kind) {
+      case "scalar":
+        this.require(fieldPos, field.size, `${owner} scalar field`);
+        return;
+      case "string":
+        this.verifyString(fieldPos, owner);
+        return;
+      case "table": {
+        // Sub-object pointer: always bounds-check the offset; recurse when deep.
+        const subPos = fieldPos + this.i32(fieldPos);
+        this.require(subPos, 4, `${owner} sub-table pointer`);
+        if (deep) this.verifyTable(subPos, field.table, deep, depth + 1);
+        return;
+      }
+      case "vectorScalar": {
+        this.verifyVectorHeader(fieldPos, field.stride, owner);
+        return;
+      }
+      case "vectorString": {
+        const { dataStart, count } = this.verifyVectorHeader(fieldPos, UOFFSET, owner);
+        if (deep) {
+          for (let i = 0; i < count; i++) {
+            const elemPos = dataStart + i * UOFFSET;
+            const strPos = elemPos + this.i32(elemPos);
+            this.verifyString(strPos, owner);
+          }
+        }
+        return;
+      }
+      case "vectorTable": {
+        const { dataStart, count } = this.verifyVectorHeader(fieldPos, UOFFSET, owner);
+        if (deep) {
+          for (let i = 0; i < count; i++) {
+            const elemPos = dataStart + i * UOFFSET;
+            const subPos = elemPos + this.i32(elemPos);
+            this.verifyTable(subPos, field.table, deep, depth + 1);
+          }
+        }
+        return;
+      }
+    }
+  }
+
+  private verifyString(fieldPos: number, owner: string): void {
+    const strPos = fieldPos + this.i32(fieldPos);
+    this.require(strPos, 4, `${owner} string length`);
+    const strLen = this.u32(strPos);
+    // +1 for FlatBuffers' implicit null terminator.
+    this.require(strPos + 4, strLen + 1, `${owner} string body`);
+  }
+
+  private verifyVectorHeader(fieldPos: number, stride: number, owner: string): { dataStart: number; count: number } {
+    const vecPos = fieldPos + this.i32(fieldPos);
+    this.require(vecPos, 4, `${owner} vector length`);
+    const count = this.u32(vecPos);
+    const dataStart = vecPos + 4;
+    // The load-bearing OOM guard: reject an oversized forged count before use.
+    if (count > (this.len - dataStart) / stride) {
+      this.fail(`${owner} vector count ${count} exceeds buffer (stride ${stride})`);
+    }
+    this.require(dataStart, count * stride, `${owner} vector body`);
+    return { dataStart, count };
+  }
+}
+
+/**
+ * Bounded structural verification of a raw (uncompressed) main-index byte
+ * range. `deep` controls whether sub-tables/vectors are recursed into
+ * (validator) or only their offsets/lengths bounds-checked (reader open).
+ * Throws `MalformedIndexError` on any violation.
+ */
+export function verifyMainIndex(indexBytes: Uint8Array, deep: boolean): void {
+  new BoundsVerifier(indexBytes).verifyRoot("MainIndex", deep);
+}
+
+/**
+ * Verify then construct the `MainIndex` root, so a malformed buffer throws
+ * `MalformedIndexError` instead of yielding a booby-trapped lazy root.
+ */
+export function getVerifiedRootAsMainIndex(indexBytes: Uint8Array, deep: boolean): MainIndex {
+  verifyMainIndex(indexBytes, deep);
+  return MainIndex.getRootAsMainIndex(new ByteBuffer(indexBytes));
+}
+
+/**
+ * True only when the index's optional `pdfExport` metadata is genuinely
+ * present and safely traversable. Because the writer emits an absent
+ * `pdfExport` via `forceDefaults(true)` (a sentinel pointing out of bounds),
+ * callers must gate any `pdfExport()`/outline read on this check.
+ */
+export function pdfExportPresent(indexBytes: Uint8Array): boolean {
+  try {
+    return new BoundsVerifier(indexBytes).verifyOptionalRootField(
+      "MainIndex",
+      { slot: 22, kind: "table", table: "PDFExportMetadata" },
+      true,
+    );
+  } catch {
+    return false;
+  }
+}

package/src/yom/generated/yomu/yom/blob-kind.ts

@@ -0,0 +1,12 @@
+// automatically generated by the FlatBuffers compiler, do not modify
+
+/* eslint-disable @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any, @typescript-eslint/no-non-null-assertion */
+
+export enum BlobKind {
+  PageImage = 0,
+  ThumbnailImage = 1,
+  OCRLayout = 2,
+  NormalizedText = 3,
+  SearchDictionary = 4,
+  SearchPostings = 5
+}