diff --git a/.claude/tasks/contracts/2026-10-11-step-06-attachment-scan.md b/.claude/tasks/contracts/2026-10-11-step-06-attachment-scan.md new file mode 100644 index 00000000..e28a4ea1 --- /dev/null +++ b/.claude/tasks/contracts/2026-10-11-step-06-attachment-scan.md @@ -0,0 +1,23 @@ +# 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`: 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` (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.