Skip to content

feat(nextjs): sandboxed pdf.js preview on browsers without a PDF viewer - #61

Merged
JamesCarnley merged 2 commits into
mainfrom
feat/pdfjs-mobile-fallback
Nov 4, 2026
Merged

JamesCarnley merged 2 commits into
mainfrom
feat/pdfjs-mobile-fallback

Conversation

@JamesCarnley

Copy link
Copy Markdown
Member

Summary

  • Browsers with no built-in PDF viewer (navigator.pdfViewerEnabled === false, e.g. Chrome on Android) now get an inline PDF preview drawn by pdf.js inside a sandboxed iframe, instead of only a Download button.
  • Browsers with a viewer keep the native, unsandboxed frame from ADR-0069, unchanged. They never download pdf.js.
  • New dependency: pdfjs-dist 6.4.299, pinned exactly (released 2026-10-03; 6.5 was three days old).
  • ADR-0070 records the decision and amends ADR-0069's third guard. specs/overview.md is updated.

Why

Chrome for Android can open a PDF full-screen on a top-level navigation (Chrome 135+), but it still can't show one inside a page and reports pdfViewerEnabled === false. So phones saw no preview for the most common document type in the corpus. James asked for pdf.js where it's needed, with native rendering everywhere else.

How it stays isolated (ADR-0056):

  • Sandbox: the frame is sandbox="allow-scripts" with no allow-same-origin, so it has an opaque origin.
  • CSP: default-src 'none', scripts inline or blob: only, no eval, no connect.
  • Code and bytes posted in: the app fetches pdf.js as text and posts it in with the bytes, and the frame imports it from its own blob: URLs. An opaque origin can't load the app's module files, and Chromium won't start a blob Worker there, so pdf.js parses on the frame's main thread.
  • Canvas only: pages are drawn to canvases, with no annotation or text layer, so there are no live links.
  • Hostile-PDF bounds: at most 300 pages are laid out, each canvas is capped at 16 MP, and off-screen pages are freed.

Build detail: webpack emits the two pdf.js files under a .txt name. Otherwise the production minifier re-parses the .mjs assets as scripts and the build fails.

Known limits (in ADR-0070):

  • With no network, JPEG2000/JBIG2 images can render blank and non-embedded fonts are substituted.
  • There's no text selection or search in the fallback view.
  • On Android the frame usually shares the app's main thread while parsing.

Permanence tier

Ephemeral (client render path). It adds a dependency and amends an ADR, so it is recorded as ADR-0070.

Specs / ADRs touched or checked

  • ADR-0070: new.
  • ADR-0069: Status line notes the partial amendment. Guards 1–2 and the native path still hold.
  • ADR-0056: confirmed. Render isolation is kept for the new path.
  • specs/overview.md: render-isolation invariant updated.

Test plan

Tested in the built-in browser against Sepolia data, with pdfViewerEnabled forced to false:

  • bitcoin.pdf renders inline, at phone width with an Android UA, and fullscreen.
  • Later pages render on scroll, and page 1 redraws after scrolling back.
  • Switching to uniswap-v3-core.pdf re-renders, images included. ethereum-whitepaper-2014.pdf renders with substituted fonts.
  • Blob URLs inside the frame are blob:null/…, which confirms the opaque origin.

Other checks:

  • Native path: the old unsandboxed blob frame is used and pdf.js is never fetched.
  • Production export: yarn build succeeds, the emitted pdf.js files are byte-identical to the package's, and bitcoin.pdf renders from the exported site served with an /explorer/* fallback.
  • CI gates: yarn next:lint, yarn hardhat:lint, yarn next:check-types, yarn docs:check and the nextjs unit tests (184 pass).
  • Not tested on a physical Android device or iPhone. This Mac has no emulator. Please open a PDF in the explorer on a phone before merging.

Review: an adversarial security review and a correctness review found no P0 or P1 findings. Their P2s are fixed in the second commit:

  • hostile page counts and page sizes
  • unbounded canvas memory
  • "Loading PDF…" sticking when page 1 fails

Accepted P3s are listed in that commit message.

Agents involved

  • Dev: Claude Opus 5.5
  • Review: Claude Opus 5.5 (adversarial security-review subagent), Claude Opus 5.5 (correctness code-review subagent)
  • Orchestrator: James

🤖 Generated with Claude Code

JamesCarnley and others added 2 commits November 4, 2026 07:47
…a viewer

Chrome on Android reports navigator.pdfViewerEnabled === false and
can't show a PDF in a frame, so per ADR-0069 phones got only a
Download button for the corpus's most common document type.

Browsers with a built-in viewer keep the native, unsandboxed frame
(ADR-0069, unchanged). Without one, the explorer now draws the PDF
with pdf.js (pdfjs-dist 6.4.299, pinned) inside an
allow-scripts-only sandboxed iframe with a no-network, no-eval CSP,
so untrusted PDF bytes are parsed in an opaque origin, never the
app's. The opaque frame can't load the app's module files, so the
page fetches pdf.js as text and posts it in with the bytes; the frame
imports it from its own blob URLs. Chromium refuses a Worker from a
blob in an opaque origin, so pdf.js parses on the frame's main thread.
Pages render lazily to canvases; no annotation/text layer, so no live
links. pdf.js is only fetched when the fallback runs.

webpack emits the two pdf.js files under a .txt name: the production
minifier otherwise re-parses the .mjs assets as scripts and fails.

ADR-0070 records the decision and amends ADR-0069's third guard;
specs/overview.md updated.

Verified in the built-in browser against Sepolia data with
pdfViewerEnabled forced false: bitcoin.pdf renders inline, at phone
width (Android UA), and fullscreen; later pages render on scroll;
switching to uniswap-v3-core.pdf re-renders (images included). Blob
URLs in the frame are blob:null, i.e. opaque origin. With a native
viewer, the old unsandboxed blob frame is used and pdf.js is never
fetched. Production static export builds; the emitted pdf.js files
are byte-identical to the package's and render from the export.
next lint, hardhat lint, check-types, docs:check and the nextjs unit
tests pass. Not run on a physical Android device.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Permanence-tier: Ephemeral
Addresses the expert review of the sandboxed pdf.js fallback.

- Page count and page size are attacker-chosen, and on Android the
  sandboxed frame shares the app's main thread. The frame now lays out
  at most 300 pages (then points to Download) and caps each canvas at
  16 MP, so a tiny file claiming 100k pages or a 1x14400 MediaBox
  can't hang or OOM the tab.
- Pages far out of view are cleared (bitmap freed, aspect-ratio keeps
  the layout) and redrawn when they come back; in-flight renders are
  cancelled. The observer uses root: document because rootMargin is
  ignored for the implicit root in a cross-origin frame.
- A page-1 render failure now shows the "use Download" message
  instead of "Loading PDF..." forever; later failures leave that page
  blank.
- The app posts pdf.js and the bytes to each frame once, so a frame
  that navigates itself can't make it re-post in a loop, and skips the
  copy if the frame was replaced while pdf.js was fetching.
- ADR-0070 no longer overstates the CSP: pdf.js makes no requests,
  but script that escaped pdf.js could still navigate the frame or
  use WebRTC; the boundary is the opaque origin, as for the HTML
  preview. Documents the missing wasm decoders / standard fonts.

Verified in the built-in browser with pdfViewerEnabled forced false:
ethereum-whitepaper-2014.pdf renders, deep pages render on scroll and
page 1 redraws after scrolling back. next lint, hardhat lint,
check-types, docs:check, nextjs unit tests and the production build
pass.

Accepted, not changed: script-src 'unsafe-inline' (no HTML-injection
path into the frame; a hash would need build-time sync), the optional
@napi-rs/canvas dependency pdfjs-dist pulls in (no install hook,
never loaded in the browser build), layout jumps on mixed page sizes,
fullscreen re-parsing the PDF.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Reviewed-by: Claude Opus 5.5 <noreply@anthropic.com>
Tested-by: Claude Opus 5.5 <noreply@anthropic.com>
Permanence-tier: Ephemeral
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-04T02:28:41.137093Z 3d04f0a PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@JamesCarnley
JamesCarnley merged commit 71f6f38 into main Nov 4, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant