📑 feat: Add Standalone File Extraction Service

[lia-by-librechat]

Scope

Standalone PDF/DOCX extraction microservice with its own package, image and Compose recipe. No existing code-api server, /exec, LibreChat or RAG API changes. No AWS, Redis, S3, Kata or gVisor dependency.

binary request → parser-free supervisor → restricted request-local worker → validated structured text → cleanup → response

PDF returns ordered, one-based page segments. Used fonts must have interpretable mappings; Type3/composite fonts require complete Unicode maps. Null optional encoding entries are treated as absent; non-core fonts without a usable standard or Unicode map fail closed. Unknown glyph names, missing fonts, incomplete maps and codec recovery or graphics-state font selection fail with UNSUPPORTED_ENCODING. DOCX returns ordered body paragraphs and tables, including nested tables. Merged-cell text is extracted once, with tab placeholders retaining grid positions. Only a closed body grammar of paragraphs, tables, direct runs/hyperlinks and known text primitives is supported. Other content structures, fields, inline images and wrappers return UNSUPPORTED_CONTENT, never successful partial text. Formatting is ignored. OCR, spreadsheets, headers/footers, text boxes, images and previews are not advertised. Authorization, policy, identity, chunking, embeddings, rollback and persistence remain caller-owned.

Deployment

docker compose -f packages/extraction/compose.yaml up --build -d --wait

Requires Linux with Landlock ABI 3+ (normally kernel 6.2+) and Docker's default seccomp profile. The shipped non-root, read-only, capability-free container has no network. Share only its socket volume with the caller, read-only; caller GID 10001 authorizes socket access. No application storage, credentials or Docker socket mounts.

Each parser is a fresh restricted subprocess, not a disposable container/VM. Landlock limits file access to its job and packaged runtime; an additional seccomp filter blocks networking, process creation, process control and IPC. Workers receive no inherited application environment or descriptors. Container and host kernel are shared; kernel exploits, side channels and container-wide OOM are outside the boundary. No privileged mode, relaxed isolation or unsafe fallback.

API and limits

• GET /v1/capabilities advertises version, formats, structure and limits.
• POST /v1/extract-text: raw bytes with Content-Type: application/octet-stream, exact Content-Length, X-Extraction-Version: 1, and X-Extraction-Format: pdf|docx.
• Response: UTF-8 JSON with version, operation, format, input SHA-256, exact text byte count and ordered {kind,index,text} segments. No base64 or upload/download workflow.
• No scripts, paths, fetch URLs, runtime selection, arbitrary parser options or query parameters.

Bound	Limit
Input / text / wire result	10 / 1 / 3 MiB
Decoded aggregate / individual stream or ZIP entry	32 / 8 MiB
ZIP entries / PDF pages / table columns	512 / 128 / 512
Admitted requests, including upload/delivery	2
Request deadline / worker CPU	10 / 8 seconds
Worker address space / container memory	512 / 768 MiB
Scratch tmpfs	96 MiB, 1,024 inodes

Malformed, encrypted, empty and unsupported-encoding documents return safe error codes, not repaired/partial text or raw parser errors. ZIP inflation is measured independently of forged size/CRC metadata. Cancellation/deadlines kill workers and wait for close; scratch cleanup precedes success. Admission remains held through response delivery. Cleanup failure quarantines the backend. Missing isolation/dependencies prevent startup.

Verification

• Scoped formatting, TypeScript no-emit check/build and 14 focused tests passed.
• Real PDF/DOCX endpoint cases and 75 adversarial fixtures passed, including exact limits, nested/merged tables, PDF forms/font mappings and forged ZIP metadata, closed DOCX grammar, standard and unknown wrappers and renamed XML parts. XML eligibility follows OPC content types, not filename extensions alone.
• Shipped Compose resource/mount/security assertions, cross-job/credential/network/process/IPC probes, cancellation/deadline cleanup, fail-closed isolation absence and crash restart passed.
• Distinct caller UID with GID 10001 succeeded through a read-only socket mount; caller without the group was denied.
• Qualified locally: Docker 29.8.2, Linux 7.0.0-1013-aws x86_64, Node 24.16.0, Python 3.13.16. Extraction CI also passed on Ubuntu's hosted runner.

Run npm ci --ignore-scripts, npm run format:check, npm run typecheck, npm test, and npm run test:container in packages/extraction.

Not qualified: ARM, Docker Desktop or other runtime recipes. Private researcher reproduction was unavailable. No application routing or LibreOffice re-enablement is included.

[lia-by-librechat]

Head: fd70a0d6d327ef4c207610c085ee642da5fdfe2d

Standalone PDF/DOCX extraction service with bounded binary transport, structured text, restricted request-local workers, and a hardened Compose recipe. No /exec or client migration changes.

Local typecheck, build, formatting, lifecycle tests, and container qualification passed before publication. Frozen-head checks are running alongside CI.

[lia-by-librechat]

Head: e5b4fef516986e1679d89a11823b3eae873d6428

Independent-review findings:

• P1: worker process-control restrictions fixed.
• P2: nested DOCX table extraction fixed.

Added native isolation and nested-table regressions. PDF bounds now cover uncompressed streams and intermediate inflation buffers. Container qualification uses invocation-scoped resources.

Focused checks and CI are running for this head.

[lia-by-librechat]

Head: 8fd61b244e856768e1b7a5adf753d335418b664a

• Prior P1 worker-control and P2 nested-table findings remain fixed.
• P2 PDF recovery/completeness finding fixed.
• Startup compatibility and measured ZIP inflation verified.

Local checks passed: formatting, no-emit typecheck, build, 13 focused tests, real PDF/DOCX extraction, 19 adversarial fixtures, hardened Compose isolation, cancellation, cleanup and restart.

Fresh independent review and CI cover this head.

[danny-avila]

@codex review the latest head, final review

[chatgpt-codex-connector]

Codex Review Summary

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

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-04T16:45:02.423362Z	8fd61b2	Manual request

ℹ️ 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.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Delightful!

Reviewed commit: 8fd61b244e

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[lia-by-librechat]

Head: 08bf1dd4d015317ebf20f4651e2878ce6ceafe11

Fixed both P2 DOCX findings: unsupported content-control/body wrappers now fail explicitly; XML validation follows OPC content types, including renamed parts. Prior worker-control, nested-table and PDF policy findings remain fixed.

Local checks passed: scoped formatting, no-emit typecheck/build, 14 focused tests, real document extraction and 30 adversarial fixtures, hardened Compose qualification, cancellation, cleanup and restart.

No documentation changes remain in the PR. Deployment, protocol and boundary details are in its description. Fresh exact-head review and CI are running.

[lia-by-librechat]

Head: 59e1328d9db6733763a96b33ccea9888d108751c

Fixed the P2 remaining-run-wrapper finding with a closed DOCX content grammar. Direct paragraphs/tables/runs/hyperlinks and known text primitives are supported; other content structures fail explicitly. Positive fixtures preserve formatting-adjacent text, links, tabs and breaks. Standard and unknown wrapper regressions pass.

Local verification passed: formatting, no-emit typecheck/build, 14 focused tests, 44 adversarial endpoint fixtures and hardened Compose isolation/lifecycle qualification. All earlier findings remain fixed.

Fresh independent review and CI cover this head.

[lia-by-librechat]

Head: d284d851a70afa2d4f0d25c9b65bc9992996ce6d

Fixed the P2 merged-cell finding. DOCX traversal consumes physical cells once and preserves grid placeholders. Horizontal, vertical, rectangular, nested and 600-KiB merged-cell cases pass. Invalid continuations/spans, hidden continuation content, legacy merges and excessive table width fail explicitly.

Local verification passed: formatting, no-emit typecheck/build, 14 focused tests, 49 adversarial endpoint fixtures and hardened Compose qualification. Prior findings remain fixed. Fresh independent review and CI cover this head.

[lia-by-librechat]

Head: 5337f3ab97384fad9adbc2f9c058969036de2ba3

Fixed the P2 PDF font-mapping finding. Used text operands require interpretable, complete mappings before decoding; unknown glyphs, missing fonts, incomplete Unicode maps, malformed codecs and unsupported graphics-state font selection fail explicitly. Real valid Unicode/ligature/emoji/composite/Form cases pass.

Local verification passed: scoped formatting, no-emit typecheck/build, 14 focused tests, 63 adversarial endpoint fixtures and shipped hardened Compose isolation/lifecycle qualification. All earlier findings remain fixed. Fresh independent review and CI cover this head.

[lia-by-librechat]

Head: 520b49dd76eecf1a493fe2b6c32b07375f7e2989

Fixed the P2 null-encoding finding. Direct/indirect null optional font entries are normalized to absence; non-core fonts need an effective standard encoding or complete character map. Type1/TrueType null/absent/empty-dictionary regressions and valid core/null/Unicode cases pass.

Local verification passed: formatting, no-emit typecheck/build, 14 focused tests, 75 adversarial endpoint fixtures and shipped hardened Compose isolation/lifecycle qualification. All earlier findings remain fixed. Fresh independent review and CI cover this head.

[lia-by-librechat]

Head: 520b49dd76eecf1a493fe2b6c32b07375f7e2989

Independent exact-head review complete: no findings. Source and focused boundary checks covered this head; the reviewer did not rerun native parser/container qualification. All 12 CI checks pass.

Local verification: scoped formatting, no-emit typecheck/build, 14 focused tests, real PDF/DOCX extraction with 75 adversarial fixtures, and shipped hardened Compose isolation/cancellation/cleanup/restart qualification passed.

Prior finding	Severity	Disposition
R1 Worker queued signals	P1	Fixed e5b4fef
R2 Nested DOCX tables	P2	Fixed e5b4fef
R3 Swallowed PDF policy errors	P2	Fixed 8fd61b2
R4 DOCX content-control omission	P2	Fixed 08bf1dd
R5 Renamed XML preflight	P2	Fixed 08bf1dd
R6 Remaining DOCX run wrappers	P2	Fixed 59e1328
R7 Merged-cell duplication	P2	Fixed d284d85
R8 Unmappable PDF fonts	P2	Fixed 5337f3a, null path completed by R9
R9 Null optional encodings	P2	Fixed 520b49d

No rejected or outstanding findings. Earlier incomplete review is not counted as clean.

Qualified locally on Linux x86_64 with Landlock ABI 3+, Docker 29.8.2, Node 24.16.0 and Python 3.13.16. ARM, Docker Desktop and other runtime recipes remain unqualified. Private researcher reproduction was unavailable. No application routing, /exec change or LibreOffice re-enablement.