fix(pdf): bounded attachment extraction by byte scan — no pdf-lib parse on import, export without object streams (BLK-009)

This commit is contained in:
bchanot committed 2026-10-11 16:42:45 +02:00
1 parent 62b8a43e09
commit 60ee71208f
14 files changed
+1054 -198

No files matched your search

+425
View File
@@ -0,0 +1,425 @@
/**
* BLK-009: the byte-scan attachment reader. Candidates on a fresh export and
* on the frozen fixtures (object-stream layout), crafted layouts (two files,
* indirect `/Length`, `\r\n`, no space after `/Type`), garbage, the keyword
* stamp, and the object-stream bomb the reader never inflates.
*/
import { deflateSync } from 'node:zlib'
import { beforeAll, describe, expect, it } from 'vitest'
import { buildSheetSnapshot, type Report } from '@faunosteo/domain'
import {
ArchiveReadError,
defaultPdfLabels,
exportReportArchive,
findEmbeddedFiles,
readAttachedDocument,
readAttachmentBytes,
readReportArchive,
type EmbeddedFileCandidate,
} from '../src'
import { inflateFlate } from '../src/attachment/inflate'
import { decodePdfString, hasArchiveStamp } from '../src/attachment/scan'
import { readFixtureBytes } from './helpers/draft'
import {
FIXED_EXPORTED_AT,
nologosBranding,
rasterizerOf,
} from './helpers/goldens'
import { pdfWithAttachment, pdfWithoutAttachment } from './helpers/pdf'
import { loadGoldenReports, type GoldenReports } from './helpers/reports'
let golden: GoldenReports
let exported: Uint8Array
const map = () => golden.draft.migrationMap
beforeAll(async () => {
golden = loadGoldenReports()
exported = (await exportDemo()).pdf
})
async function exportDemo() {
const report: Report = golden.reports.demo
return exportReportArchive({
report,
sheet: buildSheetSnapshot(golden.draft, report),
branding: nologosBranding(),
labels: defaultPdfLabels,
locale: 'fr',
rasterizer: rasterizerOf('nologos'),
exportedAt: FIXED_EXPORTED_AT,
})
}
// ---------------------------------------------------------------------------
// Hand-built PDFs: the scanner never reads the xref, so none is written
const latin1 = (bytes: Uint8Array) => Buffer.from(bytes).toString('latin1')
const ascii = (text: string) => new Uint8Array(Buffer.from(text, 'latin1'))
function concat(parts: Uint8Array[]): Uint8Array {
const out = new Uint8Array(parts.reduce((n, p) => n + p.byteLength, 0))
let at = 0
for (const part of parts) {
out.set(part, at)
at += part.byteLength
}
return out
}
interface StreamSpec {
num: number
dict: string
data: Uint8Array
eol?: string
}
function streamObject({ num, dict, data, eol = '\n' }: StreamSpec): Uint8Array {
return concat([
ascii(`${num} 0 obj\n<<${dict}>>\nstream${eol}`),
data,
ascii('\nendstream\nendobj\n'),
])
}
function craftPdf(objects: Uint8Array[]): Uint8Array {
return concat([
ascii('%PDF-1.7\n'),
...objects,
ascii('trailer\n<< /Root 1 0 R >>\n%%EOF\n'),
])
}
/** The `n 0 obj … endobj` bytes of the object whose dictionary holds `marker`. */
function objectHolding(pdf: Uint8Array, marker: string): Uint8Array {
const text = latin1(pdf)
const at = text.indexOf(marker)
expect(at).toBeGreaterThan(0)
const start = text.lastIndexOf(' 0 obj', at)
const headerStart = text.lastIndexOf('\n', start) + 1
const end = text.indexOf('endobj', at) + 'endobj'.length
return pdf.slice(headerStart, end)
}
const BOMB_RAW = 64 * 1024 * 1024
const bomb = () => new Uint8Array(deflateSync(new Uint8Array(BOMB_RAW)))
async function rejects(
bytes: Uint8Array,
kind: ArchiveReadError['kind'],
): Promise<void> {
const promise = readReportArchive(bytes, map())
await expect(promise).rejects.toBeInstanceOf(ArchiveReadError)
await expect(promise).rejects.toMatchObject({ kind })
}
// ---------------------------------------------------------------------------
describe('findEmbeddedFiles on a fresh export (no object streams)', () => {
let candidates: EmbeddedFileCandidate[]
beforeAll(() => {
candidates = findEmbeddedFiles(exported)
})
it('finds the one Flate stream, named through its visible Filespec', async () => {
expect(candidates).toHaveLength(1)
const [c] = candidates
expect(c!.filter).toBe('FlateDecode')
expect(c!.name).toBe('osteo-report.json')
const inflated = await inflateFlate(
exported.subarray(c!.offset, c!.offset + c!.length),
)
const json = JSON.parse(new TextDecoder().decode(inflated!)) as {
envelopeVersion: number
}
expect(json.envelopeVersion).toBe(1)
})
it('the length is the declared /Length and the data ends on endstream', () => {
const [c] = candidates
const text = latin1(exported)
expect(text).toContain(`/Length ${c!.length}\n>>\nstream\n`)
expect(text.slice(c!.offset + c!.length)).toMatch(/^\r?\nendstream/)
})
it('the export keeps the Filespec, its name and the stamp in clear, no object stream', () => {
const text = latin1(exported)
expect(text).toContain('/Type /Filespec')
expect(text).toContain('/F (osteo-report.json)')
expect(text).not.toContain('/Type /ObjStm')
expect(hasArchiveStamp(exported)).toBe(true)
})
it('readAttachmentBytes returns the inflated envelope bytes', async () => {
const bytes = await readAttachmentBytes(exported)
const json = JSON.parse(new TextDecoder().decode(bytes)) as {
report: Report
}
expect(json.report).toEqual(golden.reports.demo)
})
})
describe('compatibility: frozen fixtures written with object streams', () => {
it.each([
['report-v2.full.pdf', 'v2'],
['report-v2.minimal.pdf', 'v2'],
['report-v3.bare.pdf', 'bare_v3'],
] as const)('%s → origin %s', async (name, origin) => {
const bytes = readFixtureBytes(name)
expect(latin1(bytes)).toContain('/Type /ObjStm')
const candidates = findEmbeddedFiles(bytes)
expect(candidates).toHaveLength(1)
// The Filespec is packed into the object stream: no name, the JSON decides.
expect(candidates[0]!.name).toBeNull()
expect(candidates[0]!.filter).toBe('FlateDecode')
const outcome = await readReportArchive(bytes, map())
expect(outcome.origin).toBe(origin)
})
it('a stamped PDF with object streams hides its stamp: no_attachment (documented)', async () => {
const bytes = await pdfWithoutAttachment(['faunosteo-archive/1'], true)
expect(hasArchiveStamp(bytes)).toBe(false)
await rejects(bytes, 'no_attachment')
})
})
describe('selection between several embedded files', () => {
it('a decoy EmbeddedFile first, the named Faunosteo one second: the name wins', async () => {
const bytes = await pdfWithAttachment(
'osteo-report.json',
golden.reports.demo,
{
before: ['other.json', { hello: 'world', version: 2 }],
},
)
const names = findEmbeddedFiles(bytes).map((c) => c.name)
expect(names).toEqual(['osteo-report.json', 'other.json'])
const outcome = await readReportArchive(bytes, map())
expect(outcome.origin).toBe('bare_v3')
expect(outcome.report).toEqual(golden.reports.demo)
})
it('an unnamed decoy without a version is skipped for the versioned JSON after it', async () => {
const decoy = streamObject({
num: 2,
dict: '/Type /EmbeddedFile /Length 17',
data: ascii('{"hello":"world"}'),
})
const real = objectHolding(exported, '/Type /EmbeddedFile')
const outcome = await readReportArchive(craftPdf([decoy, real]), map())
expect(outcome.origin).toBe('envelope_v1')
expect(outcome.report).toEqual(golden.reports.demo)
})
it('a foreign PDF, with or without attachments: no_attachment', async () => {
await rejects(await pdfWithoutAttachment(), 'no_attachment')
await rejects(
await pdfWithAttachment('other.json', { hello: 'world' }),
'no_attachment',
)
})
})
describe('crafted stream layouts', () => {
// UTF-8: the demo report holds an en dash that Latin-1 cannot carry.
const demoJson = () =>
new TextEncoder().encode(JSON.stringify(golden.reports.demo))
it('/Length as an indirect reference: read up to endstream', async () => {
const pdf = craftPdf([
streamObject({
num: 2,
dict: '/Type /EmbeddedFile /Length 7 0 R',
data: demoJson(),
}),
ascii('7 0 obj\n123456\nendobj\n'),
])
const [c] = findEmbeddedFiles(pdf)
expect(c!.filter).toBeNull()
expect(c!.length).toBe(demoJson().byteLength)
expect((await readReportArchive(pdf, map())).origin).toBe('bare_v3')
})
it('a wrong direct /Length that does not land on endstream: measured instead', async () => {
const pdf = craftPdf([
streamObject({
num: 2,
dict: '/Type /EmbeddedFile /Length 5',
data: demoJson(),
}),
])
expect(findEmbeddedFiles(pdf)[0]!.length).toBe(demoJson().byteLength)
expect((await readReportArchive(pdf, map())).origin).toBe('bare_v3')
})
it('CRLF after stream, /Type/EmbeddedFile unspaced, a leading /Params dict', async () => {
const data = demoJson()
const pdf = craftPdf([
streamObject({
num: 2,
dict: `/Params << /Size ${data.byteLength} >> /Type/EmbeddedFile/Length ${data.byteLength}`,
data,
eol: '\r\n',
}),
])
const [c] = findEmbeddedFiles(pdf)
expect(c!.length).toBe(data.byteLength)
expect(await readAttachmentBytes(pdf)).toEqual(data)
})
it('a Filespec with a hex /F name and an /EF listing /UF too names its stream', () => {
const name = Buffer.from('osteo-report.json', 'utf16le')
.swap16()
.toString('hex')
const pdf = craftPdf([
ascii(
`3 0 obj\n<< /Type /Filespec /F <${name}> /EF << /F 2 0 R /UF 2 0 R >> >>\nendobj\n`,
),
streamObject({
num: 2,
dict: '/Type /EmbeddedFile /Length 13',
data: ascii('{"version":3}'),
}),
])
expect(findEmbeddedFiles(pdf)[0]!.name).toBe('osteo-report.json')
})
it('decodePdfString: literal with escapes, hex ASCII, hex UTF-16BE with BOM', () => {
expect(decodePdfString('(a\\(b\\)c)')).toBe('a(b)c')
expect(decodePdfString('<6F7374656F>')).toBe('osteo')
expect(decodePdfString('<FEFF006F0073>')).toBe('os')
expect(decodePdfString('/Name')).toBeNull()
})
})
describe('the keyword stamp', () => {
it('hex (pdf-lib) and literal /Keywords strings are both read', async () => {
expect(
hasArchiveStamp(await pdfWithoutAttachment(['faunosteo-archive/1'])),
).toBe(true)
expect(hasArchiveStamp(await pdfWithoutAttachment(['other']))).toBe(false)
const literal = craftPdf([
ascii('3 0 obj\n<< /Keywords (faunosteo-archive/1) >>\nendobj\n'),
])
expect(hasArchiveStamp(literal)).toBe(true)
await rejects(literal, 'attachment_stripped')
})
})
describe('garbage never throws', () => {
const cases: [string, Uint8Array][] = [
['empty', new Uint8Array(0)],
[
'random bytes',
Uint8Array.from({ length: 4096 }, (_, i) => (i * 7919) % 256),
],
['the type alone', ascii('%PDF-1.7\n/Type /EmbeddedFile')],
[
'dict without stream',
ascii('%PDF-1.7\n<< /Type /EmbeddedFile /Length 3 >>\nendobj'),
],
[
'stream without endstream',
ascii('%PDF-1.7\n<< /Type /EmbeddedFile >>\nstream\n{"version":3}'),
],
[
'only the /EmbeddedFiles name tree key',
ascii('%PDF-1.7\n<< /Type /EmbeddedFiles >>\nstream\nx\nendstream'),
],
[
'unterminated dictionary',
ascii(
'%PDF-1.7\n<< /Type /EmbeddedFile /Length 1 << >>\nstream\nx\nendstream',
),
],
[
'hex /Keywords without a closing bracket',
ascii('%PDF-1.7\n<< /Keywords <FEFF0066'),
],
]
it.each(cases)(
'%s: no candidate, no stamp, no_attachment or invalid_pdf',
async (_name, bytes) => {
expect(findEmbeddedFiles(bytes)).toEqual([])
expect(hasArchiveStamp(bytes)).toBe(false)
await expect(readAttachedDocument(bytes)).rejects.toBeInstanceOf(
ArchiveReadError,
)
},
)
it('caps the candidates at 32', () => {
const objects = Array.from({ length: 40 }, (_, i) =>
streamObject({
num: i + 2,
dict: '/Type /EmbeddedFile /Length 1',
data: ascii('x'),
}),
)
expect(findEmbeddedFiles(craftPdf(objects))).toHaveLength(32)
})
})
describe('object-stream bomb (BLK-009)', () => {
const MiB = 1024 * 1024
const objStmBomb = () => {
const data = bomb()
return streamObject({
num: 9,
dict: `/Type /ObjStm /N 1 /First 4 /Filter /FlateDecode /Length ${data.byteLength}`,
data,
})
}
const embeddedBomb = () => {
const data = bomb()
return streamObject({
num: 8,
dict: `/Type /EmbeddedFile /Filter /FlateDecode /Length ${data.byteLength}`,
data,
})
}
it('64 MiB ObjStm bomb beside the attachment: report in ms, bomb never inflated', async () => {
const pdf = craftPdf([
objStmBomb(),
objectHolding(exported, '/Type /Filespec'),
objectHolding(exported, '/Type /EmbeddedFile'),
])
expect(pdf.byteLength).toBeLessThan(512 * 1024)
const rssBefore = process.memoryUsage().rss
const started = performance.now()
const outcome = await readReportArchive(pdf, map())
const elapsed = performance.now() - started
const rssDelta = process.memoryUsage().rss - rssBefore
console.log(
`[bomb] objstm: ${elapsed.toFixed(0)} ms, rss +${(rssDelta / MiB).toFixed(1)} MiB`,
)
expect(outcome.origin).toBe('envelope_v1')
expect(outcome.report).toEqual(golden.reports.demo)
expect(elapsed).toBeLessThan(2000)
expect(rssDelta).toBeLessThan(64 * MiB)
})
it('EmbeddedFile bomb past 16 MiB: inflation cancelled, no_attachment, no hang', async () => {
const pdf = craftPdf([objStmBomb(), embeddedBomb()])
const started = performance.now()
await rejects(pdf, 'no_attachment')
const elapsed = performance.now() - started
console.log(`[bomb] embedded: ${elapsed.toFixed(0)} ms`)
expect(elapsed).toBeLessThan(2000)
})
it('both bombs before an unnamed real attachment: bomb skipped, report read', async () => {
const pdf = craftPdf([
objStmBomb(),
embeddedBomb(),
objectHolding(exported, '/Type /EmbeddedFile'),
])
const started = performance.now()
const outcome = await readReportArchive(pdf, map())
const elapsed = performance.now() - started
console.log(`[bomb] both + unnamed attachment: ${elapsed.toFixed(0)} ms`)
expect(outcome.report).toEqual(golden.reports.demo)
expect(elapsed).toBeLessThan(2000)
})
})