Parser inventory

Every engine module that turns attacker-controlled bytes or text into structure, with the bounds it actually declares, the test that covers it and whether the fuzz harness reaches it.

"Attacker-controlled" here means one of four sources:

• a file the user picked (upload, share target, drag-and-drop, file input),
• an asset fetched over host.net or read back out of storage,
• a URL param, because URL mode is first-class and every link is public,
• a stream nested inside one of those, for example an ICC profile inside a JPEG, a CMap inside a PDF content stream or an XML part inside a .pptx zip.

Two things this page deliberately does not do. It does not list the engine's format writers as attack surface. engine/src/tiff.ts, apng.ts, webp-anim.ts, emf.ts, eps.ts, dxf.ts, hdr.ts, pptx.ts, pdfx.ts, zip-crypto.ts and pdf-crypto-r6.ts are byte emitters that consume engine-internal IR, pixel buffers or already-encoded frames from the shell, so a hostile file never reaches them (see "Writers, not parsers" below). And it does not restate the shell's own gates: the web shell caps upload size and inflates zips before the engine sees a part map, and those caps live in shells/web/src/bridge/, not here.

Fuzz coverage is the registered target list in tests/fuzz/targets.ts (ALL_TARGETS, at the end of the file). There are 37: c2pa-verify, cbor, media-sniff, pdf-map, pdf-derived, x509, file-metadata, strip-metadata, video-meta, data-import, brand-import, tar-read, epub-read, jpeg-structure, raster-decode, pptx-read, pptx-patch, pptx-bridge, icc, der-read, c2pa-extract, c2pa-containers, url-pack, wav, depth-hint, lut-parse, psd, xcf, docx-read, svg-readers, keyframes, midi, zzfxm, radiance, seal, png-unfilter and watermark-analysis. tests/fuzz-regression.test.ts replays the eight saved regression inputs in tests/fuzz/regressions/ and runs a few hundred seeded mutations per target inside the normal npm test glob; node tests/fuzz/run.ts is the standalone soak.

The table is enforced by npm run check:parser-assurance. Every parser row must match a real ALL_TARGETS entry or an owned, expiring waiver in security/parser-assurance.json; stale rows, stale register entries, target drift and expired waivers fail CI. The weekly fuzz-soak.yml workflow exercises all registered targets and retains the failing input.

The parsers

Writers, not parsers

Listing these as attack surface would overstate the problem. Each consumes engine-internal IR or already-encoded bytes the shell produced, not a file a stranger sent.

The standard to follow

engine/src/pptx-read.ts is the module to copy when you add a parser. Its caps block sits at lines 156 to 167, immediately after the public types and before the first walker, so a reviewer meets the bounds before the code they bound:

// ─── hardening caps ──────────────────────────────────────────────────────────

const MAX_PART_BYTES = 24 * 1024 * 1024; // skip parsing a part bigger than this
const MAX_PART_CHARS = 16 * 1024 * 1024;
const MAX_SLIDES = 2000;
const MAX_NODES_PER_SLIDE = 8000;
const MAX_GROUP_DEPTH = 16;
const MAX_PARAS = 4000;
const MAX_RUNS_PER_PARA = 4000;
const MAX_TABLE_ROWS = 2000;
const MAX_TABLE_COLS = 512;
const MAX_TEXT_LEN = 200_000; // per run/cell text clamp
const MAX_DFS_VISITS = 200_000; // bound any descendant search
const MAX_COORD = 1e11; // EMU magnitude clamp (slide width is ~1.2e7)

Four properties make this the exemplar rather than merely a long list.

The threat model is written down. The module header carries a SECURITY section that names it: "a hostile zip is the threat model, same as PDF". It then states the consequences as commitments, not hopes: every part is size-capped before parsing, slide, node, paragraph, run and table counts are capped, group-shape recursion is depth-capped and "a malformed or hostile part NEVER throws, we return what parsed and skip the rest".

Every cap has a unit and a real-world comparison. MAX_COORD = 1e11 carries // EMU magnitude clamp (slide width is ~1.2e7), which tells the next reader the cap sits four orders of magnitude above anything legitimate. A number with no comparison point is a number nobody can safely change later.

It says what it delegates. "XML entity-expansion (billion-laughs) is the injected parser's responsibility, but we additionally bound every DFS by a visited-node counter so a pathologically deep/wide tree can't hang us." Naming the boundary is what lets a reviewer check the other side of it, and adding the counter anyway is defence in depth for the case where a shell injects a parser without those protections.

The contract is one sentence and it is testable. Never throw, return what parsed. tests/pptx-read.test.ts asserts it, and the pptx-read fuzz target asserts it against mutated real decks.

engine/src/icc.ts is the same discipline applied to a harder format, and its caps block header is worth borrowing verbatim: "Every one of these bounds something a hostile file declares", followed by the largest value each cap was measured against across forty real profiles.

Known gaps

Verified against ALL_TARGETS in tests/fuzz/targets.ts and against each module's own source. An earlier pass over this ground over-counted, because it treated the format writers as parsers.

Every row is now mapped to a registered mutation target; there are no parser-assurance waivers. This is coverage accounting, not a proof of semantic correctness or exhaustive state exploration.

Named second-order bounds. pdf-map.ts now owns the page-wide character, token and emitted-node budgets that bound every current consumer. The derived parsers still keep their own narrower shape-specific limits (pdf-artwork.ts candidates, pdf-svg.ts paths/clips, pdf-redaction.ts covers) because their public functions can also receive hand-built PdfNode[] values.

Adding a new parser

Four requirements. All four, before the module merges.

1. *Declare named MAX_ constants in one block, near the top, before the walkers.** One constant per thing a hostile input can declare: byte length, element or record count, nesting depth, coordinate magnitude, text length. Each gets a comment with its unit and the largest legitimate value you measured. Never inline a bare number into a loop bound. If a bound is genuinely structural rather than numeric, say so in the header the way svg-path.ts and der-read.ts do, and explain why.

1. Bounds-check before reading, not after. The invariant der-read.ts states is the one to internalise: check a multi-byte length head before consuming its bytes, because an out-of-range Uint8Array read yields undefined, undefined NaN-poisons the arithmetic and a NaN comparison makes the guard that follows silently false. That is how a truncated TLV gets accepted.

1. Pick a contract, state it in the header and honour it everywhere. There are three legitimate contracts in this codebase and the choice follows from what the caller does with the answer.

• Best-effort reader, never throws, returns null or a partial result. The house contract, named after png-unfilter.ts and stated most fully in icc.ts and file-metadata.ts. Correct when a failure means "we could not read this", and the UI degrades gracefully.
• Throws promptly on malformed input. der-read.ts and the CBOR decoder in c2pa-extract.ts. Correct when a silent mis-parse would be worse than an error, which is the case for anything feeding a cryptographic check.
• Fails closed by throwing. strip-metadata.ts. Correct when returning the input unchanged would be presented to a user as a safety guarantee. A privacy or security control must never fail open.

1. Add a same-name test file, register a fuzz target, and register the parser. tests/<module>.test.ts covers the truncation, garbage and cap-tripping cases by hand. Then add a FuzzTarget to tests/fuzz/targets.ts with a small seed corpus of valid inputs, built where possible from the engine's own writer so the seeds are real container layouts, an invoke() that does not swallow errors (the runner classifies a thrown validation error as the desired behaviour, and a hang or allocation blow-up as a finding) and an entry in ALL_TARGETS. Add the parser's input, bounds, direct tests, fuzz coverage, and notes to security/parser-assurance.json, then run npm run build:parser-inventory; CI rejects stale generated Markdown. Note the entry-point comment convention at the top of the fuzz file, which records exactly which function each target hits. Any input a discovery run finds goes into tests/fuzz/regressions/ as a .bin, named for the module and the failure, and tests/fuzz-regression.test.ts will replay it on every npm test from then on.