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

+20 -89
View File
@@ -1,105 +1,36 @@
import {
PDFDict,
PDFHexString,
PDFName,
PDFRawStream,
PDFStream,
PDFString,
type PDFDocument,
} from 'pdf-lib'
import { ArchiveReadError } from '../errors'
import { inflateFlate, MAX_ATTACHMENT_BYTES } from './inflate'
import {
ARCHIVE_STAMP,
hasPdfHeader,
locateAttachment,
MAX_PDF_BYTES,
} from './scan'
/**
* Finds the Faunosteo attachment of a loaded PDF: the Filespec whose file
* name starts with `osteo-report` first, else the first embedded file
* (today's behaviour, kept as the fallback). pdf-lib 1.17 exposes no
* attachment API, so this walks the indirect objects.
* The raw JSON a Faunosteo PDF carries, read from the bytes alone (BLK-009):
* no PDF object graph is parsed, so no object stream is ever inflated. pdf-lib
* stays on the export side.
*/
export const ATTACHMENT_NAME_PREFIX = 'osteo-report'
export const PDF_KEYWORD = 'faunosteo-archive/1'
export { ATTACHMENT_NAME_PREFIX } from './scan'
export const PDF_KEYWORD = `${ARCHIVE_STAMP}/1`
const TYPE = PDFName.of('Type')
const F = PDFName.of('F')
function textOf(value: unknown): string | null {
if (value instanceof PDFString || value instanceof PDFHexString) {
return value.decodeText()
/** Size cap first, then the `%PDF-` header: anything else is `invalid_pdf`. */
function assertPdfBytes(bytes: Uint8Array): void {
if (bytes.byteLength > MAX_PDF_BYTES || !hasPdfHeader(bytes)) {
throw new ArchiveReadError('invalid_pdf')
}
return null
}
/** The embedded stream of a `/Filespec` named for a Faunosteo report. */
function namedFilespecStream(dict: PDFDict): PDFStream | null {
if (dict.get(TYPE) !== PDFName.of('Filespec')) return null
const name = textOf(dict.lookup(F))
if (name === null || !name.startsWith(ATTACHMENT_NAME_PREFIX)) return null
const files = dict.lookup(PDFName.of('EF'))
if (!(files instanceof PDFDict)) return null
const stream = files.lookup(F)
return stream instanceof PDFStream ? stream : null
}
/** Today's heuristic: an `/EmbeddedFile` stream or a JSON-subtyped one. */
function looksLikeEmbeddedJson(stream: PDFStream): boolean {
const type = String(stream.dict.lookup(TYPE) ?? '')
const subtype = String(stream.dict.lookup(PDFName.of('Subtype')) ?? '')
return (
type.includes('EmbeddedFile') ||
subtype.includes('application/json') ||
subtype.includes('application#2Fjson')
)
}
function locateAttachment(pdfDoc: PDFDocument): PDFStream | null {
const objects = pdfDoc.context.enumerateIndirectObjects()
for (const [, object] of objects) {
if (!(object instanceof PDFDict)) continue
const stream = namedFilespecStream(object)
if (stream) return stream
}
for (const [, object] of objects) {
if (object instanceof PDFStream && looksLikeEmbeddedJson(object)) {
return object
}
}
return null
}
/** Stream bytes, inflated when Flate-encoded; null when unreadable or over the cap. */
async function attachmentBytes(stream: PDFStream): Promise<Uint8Array | null> {
const contents =
stream instanceof PDFRawStream ? stream.contents : stream.getContents()
if (contents.byteLength > MAX_ATTACHMENT_BYTES) return null
const filter = String(stream.dict.lookup(PDFName.of('Filter')) ?? '')
if (!filter.includes('FlateDecode')) return contents
return inflateFlate(contents)
}
/** A PDF stamped as an archive but holding no attachment lost it in a viewer. */
function missingAttachmentError(pdfDoc: PDFDocument): ArchiveReadError {
const stamped = (pdfDoc.getKeywords() ?? '').includes('faunosteo-archive')
return new ArchiveReadError(stamped ? 'attachment_stripped' : 'no_attachment')
}
/**
* The raw JSON carried by the PDF, whatever its shape (bare report of any
* version or archive envelope), before any validation: what the archive
* check tool shows next to the read result. Throws ArchiveReadError.
* check tool shows next to the read result. Throws ArchiveReadError
* (`invalid_pdf`, `no_attachment`, `attachment_stripped`).
*/
export async function readAttachedDocument(
pdfDoc: PDFDocument,
bytes: Uint8Array,
): Promise<unknown> {
const stream = locateAttachment(pdfDoc)
if (!stream) throw missingAttachmentError(pdfDoc)
const bytes = await attachmentBytes(stream)
if (!bytes || bytes.byteLength > MAX_ATTACHMENT_BYTES) {
throw new ArchiveReadError('no_attachment')
}
try {
return JSON.parse(new TextDecoder().decode(bytes)) as unknown
} catch {
throw new ArchiveReadError('no_attachment')
}
assertPdfBytes(bytes)
return (await locateAttachment(bytes)).data
}
+441
View File
@@ -0,0 +1,441 @@
import { ArchiveReadError } from '../errors'
import { inflateFlate, MAX_ATTACHMENT_BYTES } from './inflate'
/**
* Locates the Faunosteo attachment by scanning the PDF bytes (BLK-009): a
* stream object can never live inside an object stream, so every
* `/Type /EmbeddedFile` dictionary and its data are in clear in the file.
* Nothing here parses the object graph, the xref or an `/ObjStm`, so the
* only inflation on the import path is the capped one of `inflateFlate`.
* The scanner never throws on garbage: it returns fewer candidates.
*/
/** A Faunosteo PDF weighs a few hundred KB; anything larger is not one. */
export const MAX_PDF_BYTES = 50 * 1024 * 1024
export const ATTACHMENT_NAME_PREFIX = 'osteo-report'
/** The keyword stamp every archive carries (`faunosteo-archive/<n>`). */
export const ARCHIVE_STAMP = 'faunosteo-archive'
/** Candidates beyond this count are ignored: a crafted file cannot make the reader loop. */
const MAX_CANDIDATES = 32
/** A stream or Filespec dictionary is small; a longer one is skipped. */
const MAX_DICT_BYTES = 4096
/** Window read before a dictionary for its `n 0 obj` header. */
const HEADER_WINDOW = 48
export interface EmbeddedFileCandidate {
/** First byte of the stream data. */
offset: number
/** Byte count of the stream data (declared, or measured to `endstream`). */
length: number
filter: 'FlateDecode' | null
/** From a visible `/Filespec` whose `/EF /F` points at this stream. */
name: string | null
}
const encode = (text: string): Uint8Array =>
Uint8Array.from(text, (c) => c.charCodeAt(0))
const TYPE = encode('/Type')
const EMBEDDED_FILE = encode('/EmbeddedFile')
const FILESPEC = encode('/Filespec')
const KEYWORDS = encode('/Keywords')
const STREAM = encode('stream')
const ENDSTREAM = encode('endstream')
const PDF_HEADER = encode('%PDF-')
// ---------------------------------------------------------------------------
// Byte helpers: every loop is bounded by `end` (at most MAX_PDF_BYTES)
function isWhitespace(byte: number): boolean {
return (
byte === 0x20 ||
byte === 0x0a ||
byte === 0x0d ||
byte === 0x09 ||
byte === 0x0c ||
byte === 0x00
)
}
/** PDF delimiters and whitespace end a name token. */
function isDelimiter(byte: number): boolean {
return isWhitespace(byte) || '()<>[]{}/%'.includes(String.fromCharCode(byte))
}
/** Naive forward search; the needle's first byte is the fast reject. */
function indexOf(
bytes: Uint8Array,
needle: Uint8Array,
from: number,
end: number,
): number {
const last = end - needle.length
const first = needle[0]!
for (let i = Math.max(from, 0); i <= last; i += 1) {
if (bytes[i] !== first) continue
let j = 1
while (j < needle.length && bytes[i + j] === needle[j]) j += 1
if (j === needle.length) return i
}
return -1
}
function skipWhitespace(bytes: Uint8Array, from: number, end: number): number {
let i = from
while (i < end && isWhitespace(bytes[i]!)) i += 1
return i
}
/** Latin-1 view of a small window (never the whole file). */
function latin1(bytes: Uint8Array, start: number, end: number): string {
let out = ''
for (let i = start; i < end; i += 1) out += String.fromCharCode(bytes[i]!)
return out
}
/** UTF-16BE with BOM (how pdf-lib writes text strings) or Latin-1 bytes. */
function decodeTextBytes(raw: number[]): string {
if (raw.length >= 2 && raw[0] === 0xfe && raw[1] === 0xff) {
let out = ''
for (let i = 2; i + 1 < raw.length; i += 2) {
out += String.fromCharCode((raw[i]! << 8) | raw[i + 1]!)
}
return out
}
return String.fromCharCode(...raw)
}
/** A `(literal)` or `<hex>` string token as text; null for anything else. */
export function decodePdfString(token: string): string | null {
if (token.startsWith('<') && token.endsWith('>')) {
const hex = token.slice(1, -1).replace(/[^0-9a-fA-F]/g, '')
const raw: number[] = []
for (let i = 0; i + 1 < hex.length; i += 2) {
raw.push(parseInt(hex.slice(i, i + 2), 16))
}
return decodeTextBytes(raw)
}
if (token.startsWith('(') && token.endsWith(')')) {
const body = token.slice(1, -1).replace(/\\([()\\])/g, '$1')
return decodeTextBytes(Array.from(body, (c) => c.charCodeAt(0) & 0xff))
}
return null
}
// ---------------------------------------------------------------------------
// Dictionaries: `/Type /Name` matches and their `<< … >>` bounds
/** Every `/Type /<name>` (space optional) whose name ends on a delimiter. */
function findTypedDicts(
bytes: Uint8Array,
name: Uint8Array,
end: number,
): number[] {
const hits: number[] = []
let from = 0
while (hits.length < MAX_CANDIDATES) {
const at = indexOf(bytes, name, from, end)
if (at < 0) break
from = at + name.length
const after = at + name.length
if (after < end && !isDelimiter(bytes[after]!)) continue
let before = at
while (before > 0 && isWhitespace(bytes[before - 1]!)) before -= 1
const typeAt = before - TYPE.length
if (typeAt >= 0 && indexOf(bytes, TYPE, typeAt, before) === typeAt) {
hits.push(typeAt)
}
}
return hits
}
/** Index of the `<<` opening the dictionary holding `pos` (nested dicts skipped); -1 when none. */
function dictStart(bytes: Uint8Array, pos: number): number {
const floor = Math.max(0, pos - MAX_DICT_BYTES)
let depth = 0
let i = pos
while (i - 2 >= floor) {
const pair = (bytes[i - 2]! << 8) | bytes[i - 1]!
if (pair === 0x3e3e)
depth += 1 // >>
else if (pair === 0x3c3c) {
if (depth === 0) return i - 2
depth -= 1
}
i -= pair === 0x3e3e || pair === 0x3c3c ? 2 : 1
}
return -1
}
/** Index just past the `>>` closing the dictionary opened at `start`; -1 when none. */
function dictEnd(bytes: Uint8Array, start: number, end: number): number {
const limit = Math.min(end, start + MAX_DICT_BYTES)
let depth = 0
let i = start
while (i + 1 < limit) {
const pair = (bytes[i]! << 8) | bytes[i + 1]!
if (pair === 0x3c3c) depth += 1
else if (pair === 0x3e3e) {
depth -= 1
if (depth === 0) return i + 2
}
i += pair === 0x3c3c || pair === 0x3e3e ? 2 : 1
}
return -1
}
interface DictSpan {
start: number
end: number
text: string
objectNumber: number | null
}
/** The dictionary around a `/Type` match, its text and the `n 0 obj` header before it. */
function dictAround(
bytes: Uint8Array,
pos: number,
end: number,
): DictSpan | null {
const start = dictStart(bytes, pos)
if (start < 0) return null
const close = dictEnd(bytes, start, end)
if (close < 0) return null
const header = latin1(bytes, Math.max(0, start - HEADER_WINDOW), start)
const match = /(\d{1,10})\s+\d{1,10}\s+obj\s*$/.exec(header)
return {
start,
end: close,
text: latin1(bytes, start, close),
objectNumber: match ? Number(match[1]) : null,
}
}
// ---------------------------------------------------------------------------
// Stream data bounds
/** Data offset after `stream` + `\r\n` or `\n`; -1 when the keyword is missing. */
function streamDataOffset(
bytes: Uint8Array,
dictClose: number,
end: number,
): number {
const at = skipWhitespace(bytes, dictClose, end)
if (indexOf(bytes, STREAM, at, Math.min(end, at + STREAM.length)) !== at) {
return -1
}
let i = at + STREAM.length
if (bytes[i] === 0x0d) i += 1
if (bytes[i] !== 0x0a) return -1
return i + 1
}
/** A direct `/Length N` (never an `N 0 R` reference), when it lands on `endstream`. */
function declaredLength(
bytes: Uint8Array,
dict: string,
offset: number,
end: number,
): number | null {
const match = /\/Length\s+(\d{1,10})(?!\d)(?!\s+\d+\s+R)/.exec(dict)
if (!match) return null
const length = Number(match[1])
if (offset + length > end) return null
const tail = skipWhitespace(bytes, offset + length, end)
const found = indexOf(
bytes,
ENDSTREAM,
tail,
Math.min(end, tail + ENDSTREAM.length),
)
return found === tail ? length : null
}
/** Fallback for an indirect or wrong `/Length`: up to `endstream`, the EOL before it dropped. */
function measuredLength(
bytes: Uint8Array,
offset: number,
end: number,
): number | null {
const at = indexOf(bytes, ENDSTREAM, offset, end)
if (at < 0) return null
let stop = at
if (stop > offset && bytes[stop - 1] === 0x0a) stop -= 1
if (stop > offset && bytes[stop - 1] === 0x0d) stop -= 1
return stop - offset
}
function filterOf(dict: string): EmbeddedFileCandidate['filter'] {
return /\/Filter\s*(\[\s*)?\/FlateDecode\b/.test(dict) ? 'FlateDecode' : null
}
function candidateOf(
bytes: Uint8Array,
dict: DictSpan,
end: number,
): Omit<EmbeddedFileCandidate, 'name'> | null {
const offset = streamDataOffset(bytes, dict.end, end)
if (offset < 0) return null
const length =
declaredLength(bytes, dict.text, offset, end) ??
measuredLength(bytes, offset, end)
if (length === null) return null
return { offset, length, filter: filterOf(dict.text) }
}
// ---------------------------------------------------------------------------
// Filespec names and the keyword stamp
const STRING_TOKEN = String.raw`\((?:\\.|[^\\)])*\)|<[0-9a-fA-F\s]*>`
/** `/F` (else `/UF`) of a Filespec dictionary, the `/EF` sub-dictionary set aside. */
function filespecName(dict: string): string | null {
const withoutEf = dict.replace(/\/EF\s*<<[\s\S]*?>>/, '')
const f = new RegExp(String.raw`/F\s*(${STRING_TOKEN})`).exec(withoutEf)
const uf = new RegExp(String.raw`/UF\s*(${STRING_TOKEN})`).exec(withoutEf)
const token = f?.[1] ?? uf?.[1]
return token ? decodePdfString(token) : null
}
/** Object number of the stream a Filespec's `/EF << /F n 0 R >>` points at. */
function filespecStreamObject(dict: string): number | null {
const ef = /\/EF\s*<<([\s\S]*?)>>/.exec(dict)
const ref = ef ? /\/F\s+(\d{1,10})\s+\d{1,10}\s+R/.exec(ef[1]!) : null
return ref ? Number(ref[1]) : null
}
/** Stream object number → file name, from every Filespec dictionary in clear. */
function filespecNames(bytes: Uint8Array, end: number): Map<number, string> {
const names = new Map<number, string>()
for (const pos of findTypedDicts(bytes, FILESPEC, end)) {
const dict = dictAround(bytes, pos, end)
if (!dict) continue
const target = filespecStreamObject(dict.text)
const name = filespecName(dict.text)
if (target !== null && name !== null && !names.has(target)) {
names.set(target, name)
}
}
return names
}
/** The string token right after a `/Keywords` key, as text. */
function keywordsAt(
bytes: Uint8Array,
keyAt: number,
end: number,
): string | null {
const start = skipWhitespace(bytes, keyAt + KEYWORDS.length, end)
const limit = Math.min(end, start + MAX_DICT_BYTES)
const window = latin1(bytes, start, limit)
const token = new RegExp(`^(?:${STRING_TOKEN})`).exec(window)
return token ? decodePdfString(token[0]) : null
}
/** True when a visible `/Keywords` string carries the archive stamp. */
export function hasArchiveStamp(bytes: Uint8Array): boolean {
const end = Math.min(bytes.byteLength, MAX_PDF_BYTES)
let from = 0
for (let n = 0; n < MAX_CANDIDATES; n += 1) {
const at = indexOf(bytes, KEYWORDS, from, end)
if (at < 0) return false
from = at + KEYWORDS.length
if (isDelimiter(bytes[from] ?? 0x20)) {
if (keywordsAt(bytes, at, end)?.includes(ARCHIVE_STAMP)) return true
}
}
return false
}
/** `%PDF-` within the first KiB, as viewers accept it. */
export function hasPdfHeader(bytes: Uint8Array): boolean {
return indexOf(bytes, PDF_HEADER, 0, Math.min(bytes.byteLength, 1024)) >= 0
}
// ---------------------------------------------------------------------------
// Public scan
/**
* Every `/Type /EmbeddedFile` stream of the file, named when its Filespec
* is in clear (export without object streams); `osteo-report*` names first,
* then file order. At most MAX_CANDIDATES, within MAX_PDF_BYTES.
*/
export function findEmbeddedFiles(bytes: Uint8Array): EmbeddedFileCandidate[] {
const end = Math.min(bytes.byteLength, MAX_PDF_BYTES)
const names = filespecNames(bytes, end)
const found: EmbeddedFileCandidate[] = []
for (const pos of findTypedDicts(bytes, EMBEDDED_FILE, end)) {
const dict = dictAround(bytes, pos, end)
if (!dict) continue
const candidate = candidateOf(bytes, dict, end)
if (!candidate) continue
const name =
dict.objectNumber === null ? null : (names.get(dict.objectNumber) ?? null)
found.push({ ...candidate, name })
}
const named = (c: EmbeddedFileCandidate) =>
c.name?.startsWith(ATTACHMENT_NAME_PREFIX) ? 0 : 1
return found.sort((a, b) => named(a) - named(b))
}
/** Raw or inflated stream data under the attachment cap; null when unusable. */
async function candidateBytes(
bytes: Uint8Array,
candidate: EmbeddedFileCandidate,
): Promise<Uint8Array | null> {
if (candidate.length > MAX_ATTACHMENT_BYTES) return null
const data = bytes.subarray(
candidate.offset,
candidate.offset + candidate.length,
)
if (candidate.filter === null) return data
return inflateFlate(data)
}
/** JSON with a numeric `envelopeVersion` or `version`; undefined otherwise. */
function parseVersioned(data: Uint8Array): unknown {
let parsed: unknown
try {
parsed = JSON.parse(new TextDecoder().decode(data))
} catch {
return undefined
}
if (typeof parsed !== 'object' || parsed === null) return undefined
const record = parsed as Record<string, unknown>
const versioned =
typeof record['envelopeVersion'] === 'number' ||
typeof record['version'] === 'number'
return versioned ? parsed : undefined
}
export interface LocatedAttachment {
bytes: Uint8Array
data: unknown
}
/**
* The first candidate whose data is a versioned JSON document, decoded once.
* None: `attachment_stripped` when the stamp is visible, else `no_attachment`.
*/
export async function locateAttachment(
bytes: Uint8Array,
): Promise<LocatedAttachment> {
for (const candidate of findEmbeddedFiles(bytes)) {
const data = await candidateBytes(bytes, candidate)
if (!data) continue
const parsed = parseVersioned(data)
if (parsed !== undefined) return { bytes: data, data: parsed }
}
throw new ArchiveReadError(
hasArchiveStamp(bytes) ? 'attachment_stripped' : 'no_attachment',
)
}
/** The attachment's decoded bytes (BLK-009 reader). Throws ArchiveReadError. */
export async function readAttachmentBytes(
bytes: Uint8Array,
): Promise<Uint8Array> {
return (await locateAttachment(bytes)).bytes
}