Files
faunosteo/.claude/tasks/contracts/2026-10-11-step-06-attachment-scan.md

5.0 KiB

CONTRACT — step-06 bounded attachment extraction (BLK-009, options A + B)

  • date: 2026-10-11 | flow: ship-feature (executor, security loop) | branch: feature/step-06-pdf-archives
  • status: active
  • spec: docs/development/PDF_IMPORT_HARDENING.md §2-§4

REQUEST (IMMUTABLE)

Remove pdf-lib's parser from the import path: locate the Faunosteo attachment by scanning the PDF bytes, inflate it with the capped native inflater, never call PDFDocument.load on untrusted input in the browser. Export without object streams so the Filespec name and the Info keywords stay visible to the scanner. Existing archives (with object streams) must still import. Tests include an object-stream bomb that the new reader never inflates.

ACCEPTANCE CRITERIA

  1. packages/pdf/src/attachment/scan.ts: findEmbeddedFiles(bytes: Uint8Array): EmbeddedFileCandidate[] walks the bytes (bounded by MAX_PDF_BYTES) for stream dictionaries containing /Type /EmbeddedFile (also /Type/EmbeddedFile without space), reads a direct /Length N when present else locates endstream, handles stream\r\n and stream\n, records { offset, length, filter: 'FlateDecode' | null, name: string | null } where name comes from a visible /Filespec dict whose /EF << /F n 0 R >> points at that stream's object number (object header n 0 obj before the dict), when visible; candidates ordered: named osteo-report* first, then file order. readAttachmentBytes(bytes): Promise<Uint8Array>: for each candidate, raw bytes (or inflateFlate under MAX_ATTACHMENT_BYTES when Flate) → first whose decoded text parses as JSON with a numeric envelopeVersion or version wins; none → no_attachment, or attachment_stripped when the bytes carry the keyword stamp (/Keywords followed by a literal (…) or hex <…> string decoding to a text containing faunosteo-archive). CHECK: cd packages/pdf && corepack pnpm vitest run tests/scan.test.ts 2>&1 | grep -E "Tests " | tail -1 EXPECT: Tests .* passed
  2. readReportArchive(bytes, map) uses the scanner only: %PDF- header check + size cap → invalid_pdf; no PDFDocument.load anywhere under packages/pdf/src/read.ts or src/attachment/; readAttachedDocument becomes readAttachedDocument(bytes: Uint8Array): Promise<unknown> (bytes, not a PDFDocument) and the compare CLI (apps/app/scripts/compare-reports.ts) uses it without loading the PDF. CHECK: grep -rn "PDFDocument.load|PDFDocument.load" packages/pdf/src apps/app/scripts | wc -l EXPECT: 0
  3. Export: pdfDoc.save({ useObjectStreams: false }); a test asserts the saved bytes contain the literal /Type /Filespec with (osteo-report.json) (or its hex) in clear and no /Type /ObjStm; every golden suite stays green (goldens record text/images/links only).
  4. Compatibility tests (tests/scan.test.ts + existing read.test.ts): the frozen fixtures apps/app/tests/fixtures/report-v2.full.pdf, report-v2.minimal.pdf, report-v3.bare.pdf (all written WITH object streams) import with the same outcomes as before; a fresh envelope PDF imports; a PDF with two embedded files (a decoy EmbeddedFile first, then the Faunosteo one) picks the Faunosteo one; a PDF whose /Length is an indirect reference (craft by hand) is read through the endstream fallback; \r\n after stream; a foreign PDF → no_attachment; a stamped PDF without attachment → attachment_stripped (write it with useObjectStreams: false so the stamp is visible; also document that older stamped files with object streams fall back to no_attachment).
  5. Bomb test: a PDF containing an object stream (/Type /ObjStm /Filter /FlateDecode) whose data is a deflate bomb (≥ 64 MiB of zeros compressed to a few hundred KB, built in the test with node:zlib) plus a valid Faunosteo attachment: readReportArchive returns the report in under 2 s and the process RSS does not grow by more than 64 MiB (measure process.memoryUsage().rss before/after); the same bytes also carry an attachment-sized bomb variant: an EmbeddedFile stream inflating past 16 MiB → no_attachment (inflate cancelled), never a hang.
  6. Docs: docs/PDF-FORMAT.md "Reading an archive" step 2 (byte scan, no object-graph parse, object streams never inflated) and "Known limits" (pdf-lib removed from the import path; remaining: CLI on the same scanner, pdf-lib kept for generation, prerequisites unchanged for external users); docs/development/PDF_IMPORT_HARDENING.md §4 marked done with the commit, §5 unchanged.
  7. Green from the root: corepack pnpm typecheck && corepack pnpm lint && corepack pnpm test:run; git diff --quiet 8b86b92 HEAD -- apps/app/tests/fixtures/goldens.

FILE SCOPE

packages/pdf/src/{attachment/scan.ts (new), attachment/read.ts, attachment/inflate.ts, read.ts, export.ts, index.ts, errors.ts}, packages/pdf/tests/** , apps/app/scripts/compare-reports.ts, apps/app/scripts/compare/report.ts, apps/app/tests/unit/scripts.compare.test.ts, apps/app/tests/unit/pdf.import.test.ts (if it loads a PDFDocument), docs/PDF-FORMAT.md, docs/development/PDF_IMPORT_HARDENING.md. Nothing else.