Design PDF resource containment and cancellation

[FHoffarth]

Successor to #8, which established the problem by measurement and is now closed. This issue
is for design, not implementation. #8 proved what the problem is; it did not prove what the
right architecture is, and nothing here should be read as a decided solution.

What #8 established

A 64 KiB PDF makes FilePass inflate 64 MiB of metadata, at roughly 1024:1, linear to at least
256 MiB with no refusal from either library. Four reachable paths, in two libraries:

#	path	triggered by	phase
1	catalog /Metadata XMP	getMetadata()	inspection + verification, 2× on the source
2	content streams	getTextContent()	verification, conditional
3	ObjStm	PDFDocument.load / getDocument	parsing itself
4	XRef stream	PDFDocument.load / getDocument	parsing itself

The only limit FilePass owns today is the 50 MB compressed input cap in sniff.ts, which
does not bound the decompressed size at all.

Equally established, and it constrains the design: the UI does not freeze, the tab does
not crash, and the file is still cleaned and verified correctly. This is CPU and memory on
the user's own device in a local-only tool, not a server-side DoS.

Three separate design questions

They are listed separately because they have different answers and may have different
verdicts. Any of them may reasonably end in "accept as documented limit".

1. Containment of parser decompression

FilePass does not perform the decompression, so it cannot bound it the way it bounds PNG.
Paths 3 and 4 happen during parsing, before FilePass knows anything about the file.

Open, not decided: whether to intercept bytes before any parser sees them, whether to
bound only what is cheaply identifiable, whether a limit can be pushed into the libraries,
whether to bound observationally (time/memory) instead of structurally, or whether to
document the limit and do nothing. Pre-inflating every flate stream ourselves is one
candidate among several and is explicitly not the assumed answer — it is close to
reimplementing part of a PDF parser, which carries its own trust cost.

2. Cancellation and run ownership

Measured: the abandoned run keeps working for 4.6 s after the user has their next answer.
runRef filters results, it does not cancel; there is no AbortController anywhere and
loadingTask.destroy() is never used to interrupt.

Open: what "the user moved on" should mean, whether the run token should own a cancellation
scope, what a partially cancelled verification means for the trust model, and whether
cancellation can be made safe given that a half-finished verification must never produce a
verdict.

3. Concurrency control

Measured: three attack files at once cost 2.91× a single one — fully additive. In the browser
a harmless PDF took 1.4× longer while an abandoned run was still active.

Open: whether PDF work should be serialised, whether a newer run should displace an older
one, and how that interacts with question 2.

Constraints carried over

• No replacement of pdf-lib or pdfjs-dist merely because they are dependencies.
• No global resource framework built by default; PNG's budget is not to be reused out of
  convenience — it works because FilePass holds that reader itself, which is not the case here.
• No change to verification semantics as a side effect.
• A design that concludes "document the limit, change nothing" is a legitimate outcome.

Done when

Each of the three questions has a written verdict — designed, deferred, or accepted as a
documented limit — with the reasoning recorded. Implementation is a separate decision after
that.

Severity

P2. Real and measured, but on the user's own device, with no incorrect sanitisation result
and no fail-open.

🤖 Generated with Claude Code

[FHoffarth]

Design decision

B) document/accept for v0.1, harden later

Design sprint, zero product-code changes. The decision is the deliverable.

New measurements taken for this decision

Three facts that were not in #8 and that moved the answer.

1. Who pays, and on which thread

case	pdf-lib (main thread, not cancellable)	pdfjs (worker, cancellable)
ObjStm 64 MiB	2 236 ms	2 768 ms
XMP 64 MiB	6 ms	2 469 ms

2. What the libraries actually offer — checked, not assumed

pdfjs loadingTask.destroy() = true, PDFWorker exported with destroy() = true,
pdf-lib abort API = false.

3. Escalation in the browser, and a prediction of mine that was wrong

payload	input	wall clock	main thread blocked	outcome
64 MiB	64 KiB	1.9–3.3 s	0 ms	accepted
256 MiB	255 KiB	7.9 s	0 ms	accepted
1 GiB	1 020 KiB	35–60 s	50 ms	accepted
ObjStm 64 MiB	64 KiB	5.8 s	69 ms	accepted

From pdf-lib's 2 236 ms on the main thread in Node I predicted a UI freeze for the ObjStm
case. Wrong — in the browser it is 69 ms. Across the whole measured range the failure
mode is degradation, never a crash. That is what decided this issue.

The options, as evaluated

	protection	trust risk	complexity	v0.1	open proofs
1. Document the limit	none technical; what protects is that there is no freeze, no crash, no wrong verdict, and it is local-only	none to the sanitisation contract; the honesty risk exists only if it stays unwritten	a README paragraph	high	behaviour near the 50 MB cap; low-memory devices
2. Concurrency ceiling	removes the additive accumulation (2.91× for three runs, 1.4× contention); does not bound a single run	low but not nil — a displaced run must never yield a verdict	low; no worker changes	workable	whether serialising without cancelling only defers the wait
3. Real cancellation	covers the pdfjs share: ~100 % of the XMP path, ~55 % of ObjStm; pdf-lib's share stays uncancellable	highest of all. verifyClean has several await points; a destroyed task makes them reject. Today that lands on unresolved → unverified, which is fail-closed by accident rather than by design	medium	questionable	whether destroy() frees worker memory promptly
4. Watchdog timeout	the only option that also covers paths not yet discovered — it bounds cost, not structures	conceptually expensive: a time limit makes refusal device-dependent. "FilePass refuses this file" would stop being a property of the file	low, but only together with 3 — without cancellation it reports a refusal while the work continues, which is a lie	weak alone	threshold; runtime distribution of real PDFs

Why B

The harm is measured and bounded: CPU time on the user's own device, in a local tool with no
tenancy boundary. No freeze, no crash, no incorrect cleaning, no fail-open. Against that, the
only option with real protection for a single run (3) touches the exact path that decides
"verified", days before an RC. The trust contract is the product; risking it for a problem
that manifests as slowness is the worse trade.

Not C, because the one unknown that mattered — does it degrade or die — was closed in this
sprint: up to a 1 GiB payload from a 1 MB file it degrades cleanly. What stays open (the
50 MB cap, weak devices) does not move the decision, since both directions give the same
answer: slower, not wrong.

Sequencing

v0.1        document the PDF resource limitation          (option 1, mandatory)
post-v0.1   1) concurrency guard                          (option 2, first hardening)
            2) cancellation architecture                  (option 3, own trust-sensitive sprint)
            option 4 only if device-dependent refusal is deliberately accepted

Option 1 is not optional within B: a limit nobody states is not an accepted decision, it is an
unnoticed one.

This issue is decision-complete. It is not "problem solved" — the follow-ups above carry
the remaining work.

Measurements in the untracked audit/run/, including the prediction marked wrong.

🤖 Generated with Claude Code

[FHoffarth]

Closing: design decision completed

Design decision completed — the resource gap is not technically eliminated. v0.1 accepts it
with documentation; hardening follows separately.

This is deliberately not "problem solved". What was decided:

B) document/accept for v0.1, harden later

The reason it could be decided at all is that the failure mode turned out to be bounded:
across the measured range — up to a 1 GiB payload from a 1 MB file — FilePass degrades, it
does not freeze, crash, or produce a wrong verdict. The cost is CPU time on the user's own
device in a local-only tool. The only option with real protection for a single run would have
touched the path that decides "verified", days before an RC, and that is the worse trade.

Carried forward, not dropped:

when	what
v0.1	document the PDF resource limitation — mandatory within B, a limit nobody states is an unnoticed one, not an accepted one
post-v0.1	concurrency guard — removes the measured additive accumulation, does not touch the trust core
post-v0.1	cancellation architecture — its own trust-sensitive sprint, not folded into the above

One thing the next reader should not inherit as an assumption: a destroyed pdfjs task
currently makes verifyClean's await points reject, which lands on unresolved → unverified.
That is fail-closed by accident, not by design. Whoever builds cancellation must not rely
on it.

🤖 Generated with Claude Code