[Product Gap] Qualify a sandboxed Office conversion adapter #5

Buyer-visible outcome

Replace the current non-PDF development/demo placeholder generator with a production-qualified Office-to-PDF conversion boundary that renders representative DOC/DOCX, XLS/XLSX, PPT/PPTX, ODT/ODS/ODP, and legacy files with bounded latency, deterministic evidence, tenant isolation, and no converter compromise path into the Clearfolio API process. Protected-main validated PDF passthrough remains a separate native path and must not be conflated with transformed Office fidelity.

JODConverter remains a candidate adapter, not an approved embedded dependency or production architecture. Its project is Apache-2.0 licensed, while the office runtime it controls must be reviewed and distributed separately. LibreOffice is made available under MPL-2.0 and contains components under additional licenses, so the exact runtime image and redistribution mode—not only the Java adapter license—must pass legal and SBOM review.

Architecture decision boundary

Do not start LibreOffice through LocalOfficeManager inside the Clearfolio API container. A malformed document, office-process memory leak, native parser vulnerability, hang, or privilege escalation must not share the API process, filesystem, credentials, network namespace, or tenant context.

Qualify one provider-neutral office_conversion_adapter contract with at least two implementations or test doubles:

• sandboxed_office_sidecar: an isolated local service that owns LibreOffice/JODConverter process lifecycle;
• remote_office_service: an authenticated remote converter such as a separately operated Collabora/LibreOffice Online boundary;
• deterministic_fixture_adapter: an offline test implementation for exact contract and failure-mode testing.

The public Clearfolio service must depend only on the versioned adapter interface. JODConverter, LibreOffice, Collabora, or another engine may be replaced without changing controller, job, artifact, audit, or naruon/MSA contracts.

JODConverter's current documentation distinguishes LocalOfficeManager, externally managed local processes, and remote LibreOffice Online/Collabora managers. The Clearfolio decision is stricter than the library default: process ownership must remain outside the API process/container trust boundary even if JODConverter supports starting a local office process directly.

Mandatory sandbox and data-handling controls

• Run the converter as a non-root identity with no host namespace access, no Docker socket, no cloud metadata access, and no inherited application secrets.
• Deny outbound network access by default. Record every explicitly allowed endpoint.
• Use read-only root filesystems, per-job writable temporary storage, size and inode quotas, and guaranteed cleanup after success, failure, timeout, cancellation, or crash.
• Apply seccomp/AppArmor/SELinux or equivalent policy, Linux capabilities drop, PID/memory/CPU/VRAM limits, and process-count limits.
• Scan and validate source bytes before conversion with extension, MIME, container, macro, encrypted-document, archive-depth, decompression-ratio, and malformed-structure policies.
• Treat macro-enabled, embedded-object, external-link, OLE, and active-content files as distinct policy classes; do not execute macros or follow external links.
• Use bounded task_queue_timeout, task_execution_timeout, process startup timeout, and a finite max_tasks_per_process; JODConverter documents queue/execution timeouts and process recycling because Office processes can hang or leak.
• Bind every request to immutable tenant, job, object-generation, source-digest, adapter-version, policy-version, and correlation identifiers.
• Publish output only after PDF structure validation, media-type verification, maximum-size checks, page-count limits, digest calculation, and antivirus/content-policy checks.
• Never return local paths, office command lines, stack traces, source filenames, tenant identifiers, or document content in public error payloads.
• Persist privacy-safe audit events for accepted, rejected, timed-out, cancelled, crashed, retried, quarantined, and completed conversions.

License and supply-chain qualification

• Record the exact JODConverter module and version, office-runtime version/build, container base, fonts, codecs, dictionaries, native packages, and every transitive license.
• Generate and validate CycloneDX and SPDX SBOMs for the adapter image and Java client separately.
• Produce third-party attribution directly from the reviewed SBOM; stale or manually edited evidence is a release blocker.
• Document MPL-2.0 notice/source obligations for the exact LibreOffice distribution and review every additional license shipped in the image.
• Pin images by digest and dependencies by lock/BOM; generate provenance and signed attestations.
• Define vulnerability response, rebuild SLA, end-of-life policy, rollback, and emergency engine-disable procedures.
• Obtain an explicit legal/security go/no-go record. Library-level Apache-2.0 compatibility alone is not approval to ship the complete converter runtime.

Real-world fidelity benchmark

Build a versioned corpus that contains, at minimum:

• Korean and English corporate reports with headings, tables, page breaks, footnotes, hyperlinks, and embedded fonts;
• multi-sheet workbooks with formulas, merged cells, print areas, hidden rows/columns, charts, dates, currencies, and large sparse regions;
• presentations with themes, speaker notes, charts, images, tables, transitions, and non-Latin text;
• password-protected, macro-enabled, malformed, truncated, oversized, zip-bomb-like, external-link, and unsupported fixtures;
• documents from multiple Office/LibreOffice generations and representative customer templates.

For each supported fixture, compare the produced PDF with an approved reference using:

• page count and page geometry;
• text extraction and reading-order agreement;
• font substitution and missing-glyph rate;
• table/cell placement and clipping;
• image and chart presence;
• print-area and pagination agreement;
• deterministic or bounded perceptual-image difference;
• conversion latency, peak RSS, temporary-disk use, process restarts, and failure classification.

Do not claim format support from a successful process exit alone. Publish per-format support tiers and known limitations. PR #305 introduces docs/FIDELITY_ACCEPTANCE.md as the canonical fidelity authority; until that PR integrates it remains ACTIVE_PR, while this issue keeps the same fail-closed benchmark contract.

Reliability and lifecycle contract

• Conversion is asynchronous and idempotent by tenant, source digest, policy version, and requested output contract.
• Cancellation and timeout must terminate or quarantine the exact office process generation; later jobs must not inherit its profile or temporary files.
• Retry only explicitly retryable failures with bounded attempts and backoff. Parser rejection, policy denial, password protection, and unsupported formats are not transient failures.
• A worker crash or host restart must resume from durable job/outbox state without duplicating output publication.
• Readiness must reflect actual converter capacity and policy state; liveness must not depend on one malformed customer file.
• Provide queue depth, active processes, process age/task count, conversion stage latency, timeout/crash counts, format-specific failure rates, quarantine counts, and resource saturation metrics.

Verification and merge gates

• Test-first adapter contract with deterministic red/green evidence.
• Production statement coverage 100%, branch coverage 100%, and complete beginner-readable public Javadocs/docstrings for Clearfolio-owned code.
• Real containerized conversion tests on the benchmark corpus; no skipped required Office-runtime tests.
• Hostile-file fuzzing and decompression/container-limit tests.
• Tenant-isolation, cancellation, crash-recovery, stale-generation, duplicate-request, timeout, cleanup, and no-network tests.
• CPU/RAM/disk/process pressure tests and concurrency benchmarks.
• Exact-head CI, Security Scan, SAST, dependency review, OSV/Trivy, SBOM validation, provenance, CodeRabbit/OpenCode/Noema review, zero unresolved threads, and counted independent write-authorized approval.
• Update ARCHITECTURE.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, deployment runbook, threat model, format-support matrix, and APA 7 references.

Database and modular naming

Use descriptive two-or-more-word snake_case names for durable objects, for example:

• conversion_engine
• conversion_request
• conversion_attempt
• conversion_artifact
• conversion_quarantine
• adapter_health_snapshot
• format_support_record
• conversion_audit_event

Current decision — 2026-08-09 refresh

• JODConverter Java license: Apache-2.0; library-level review passed.
• JODConverter production adoption: not approved.
• The previously cited 4.4.10 configuration page is no longer the latest documented line; current JODConverter documentation includes a 4.4.11 migration guide and current latest manager/configuration pages. Pinning an adapter version remains a qualification decision, not an assumption from this issue.
• LibreOffice runtime redistribution and exact image: legal/SBOM review required; LibreOffice's licensing page states MPL-2.0 and notes additional software/licenses varying by distribution/version.
• In-process LocalOfficeManager architecture: rejected for Clearfolio's trust boundary, even though JODConverter supports it as a normal local-manager mode.
• Sandboxed sidecar or independently operated remote service behind a provider-neutral adapter: required for qualification.
• Protected main currently has validated PDF passthrough plus PDFBox-based non-PDF development/demo placeholder generation. No production Office transformed-format support is shipped until this issue's qualification and merge gates are satisfied.

References

JODConverter. (2025). Office Managers. https://jodconverter.github.io/jodconverter/latest/getting-started/office-managers/

JODConverter. (2025). Configuration overview. https://jodconverter.github.io/jodconverter/latest/configuration/

JODConverter. (2025). Migration 4.4.11. https://jodconverter.github.io/jodconverter/latest/migration-guides/migration-guide-4.4.11/

JODConverter. (n.d.). LICENSE: Apache License, Version 2.0. https://github.com/jodconverter/jodconverter/blob/master/LICENSE

The Document Foundation. (n.d.). Licenses. https://www.libreoffice.org/licenses/