Skip to content

feat(conversion): establish provider-neutral Office adapter contract - #306

Draft
seonghobae wants to merge 220 commits into
mainfrom
feat/office-conversion-adapter-contract
Draft

seonghobae wants to merge 220 commits into
mainfrom
feat/office-conversion-adapter-contract

Conversation

@seonghobae

@seonghobae seonghobae commented Aug 9, 2026 •

Copy link
Copy Markdown
Collaborator

Objective

Advance issue #5 with a provider-neutral, fail-closed Office conversion contract before selecting or embedding a production Office runtime. Protected main still ships validated PDF passthrough plus a fail-closed non-PDF conversion boundary; this Draft does not claim production Office transformed-format support.

Fresh exact state — 2026-08-11

Directly revalidated on exact source head 42ee91b5d1d94f209218616bb79e34fa955dcf4f against protected main 55d7ae8647208e301f282350f076eeddaba61d11:

  • open, Draft, mergeable;
  • exact-head CI 31487721202: success;
  • Maven test job 93766851131: checked out exact head 42ee91b5d1d94f209218616bb79e34fa955dcf4f, ran mvn -B --no-transfer-progress verify, 676 tests, 0 failures, 0 errors, 0 skips, all JaCoCo coverage checks met, public Javadocs passed, BUILD SUCCESS;
  • Maven synthetic merge compatibility job 93766851040: success;
  • buyer-readiness script job 93766851189: success;
  • Security Scan 31487721176: success;
  • SAST Semgrep 31487721175: success;
  • fuzz 31487721183: success;
  • formal reviews: none; unresolved inline review threads: none at the latest direct refetch;
  • automated checks/comments/model output remain evidence, never qualifying independent approval.

The exact Maven log still emits the known duplicate Commons Logging warning; that separate issue #320 already has a current-base repair in PR #340 and is not duplicated here.

Latest test-first remediation — reject VBA project active content

RED

Test-only head 2abf9aa05dfdc1776fdf74ac71d9825212c465d9 added OfficeSourceMacroPolicyTest.adapterRejectsVbaProjectBeforeProvider. Exact-head CI 31477021105 checked out that revision and failed with exactly one intentional regression: the DOCX fixture containing word/vbaProject.bin reached the provider instead of failing closed. Security Scan, SAST and fuzz were otherwise successful on that RED head.

GREEN

Current exact head 42ee91b5d1d94f209218616bb79e34fa955dcf4f rejects a ZIP-package entry whose final path segment is vbaProject.bin (case-insensitive) during the already-bounded central-directory preflight, before provider invocation. The regression now passes with controlled MALFORMED_INPUT / source Office package contains prohibited active content, and the provider call count remains zero. Full exact-head mvn verify, coverage, Javadocs, merge compatibility, Security Scan, SAST and fuzz are GREEN.

Microsoft's Open XML macro specifications identify the VBA Project as the macro-bearing package part with content type application/vnd.ms-office.vbaProject and the VBA-project relationship type. This slice deliberately rejects the known VBA project part before any untrusted Office runtime receives the package; it does not claim complete OOXML active-content relationship/content-type validation.

Current pre-provider package boundary

ZIP-family Office candidates currently require standard single-disk EOCD/central-directory framing; present bounded records; matching local-header signatures and entry names; no ZIP64/split-disk sentinel framing; no encrypted entries; matching compression method; only Stored (0) or Deflate (8); internally consistent Stored/Deflate size metadata; matching data-descriptor/CRC/size authority where applicable; compressed payload bounded before the central directory; duplicate-entry rejection; safe relative entry paths; and rejection of VBA project parts before provider invocation.

ODF candidates (odt, ods, odp) additionally require:

  • META-INF/manifest.xml;
  • no unexpected META-INF/ entry outside the manifest plus the current bounded signature-name allowance;
  • when mimetype exists: first local ZIP entry, Stored, no local-header extra field, and byte-equal to the declared ODF media type;
  • bounded manifest extraction (maximum 1 MiB expanded bytes);
  • namespace-aware non-validating StAX with DTD/external entities disabled;
  • manifest:manifest root validation and exact manifest:version="1.4";
  • root / media-type consistency when the package mimetype contract is present;
  • ordinary package-file inventory represented exactly once in the manifest under the current bounded policy.

Passing these checks is intentionally not complete OOXML/ODF/OLE/archive-expansion/macro/embedded-object/malware/fidelity qualification.

Standards authority

  • OASIS Open. (2025). Open Document Format for Office Applications (OpenDocument) Version 1.4, Part 2: Packages.
  • Microsoft. [MS-OFFMACRO2]: Office Macro-Enabled File Format Structure / VBA Project part requirements.

The implementation uses only bounded facts that are directly testable at Clearfolio's pre-provider trust boundary. It does not claim complete schema or macro-enabled-format conformance.

Post-provider and remaining qualification

A provider result is accepted only when tenant/job/generation/source-format/adapter/policy/correlation/source-digest binding matches, output stays within byte/page ceilings, and a non-empty unencrypted PDF passes active-content/action policy. Safe internal GoTo and valid absolute http/https/mailto user URI actions are preserved; malformed/relative/unsafe schemes, prohibited or unknown actions, unsafe /AA, JavaScript/embedded-file/catalog-associated-file paths and unsafe chains fail closed without dereferencing external hyperlinks.

This PR still does not select/embed an Office runtime. Production process ownership remains outside the Clearfolio API-container trust boundary; in-process/container-local LocalOfficeManager remains rejected. Before any transformed-format production support claim the repository still needs deeper OOXML/ODF/legacy-container relationship and content-type qualification, archive expansion limits, broader macro/OLE/embedded-object/external-resource policy, sandboxed sidecar or authenticated remote runtime, process/queue/transport/cancellation limits, malware/quarantine, exact runtime license/SBOM/provenance, realistic authorized Korean/English Office fidelity corpus, resource/crash/restart/readiness evidence, fresh review and live repository protection.

A successful adapter call, package check or Office-process exit is never a supported-format or fidelity oracle.

Merge gate

Keep Draft. Continue only bounded issue-#5 qualification while this branch lease is stable. Before integration, reconcile the unique Office-contract delta onto the current protected baseline without losing newer protected-main semantics, regenerate exact-head/base-sensitive gates and realistic fidelity/sandbox evidence, and obtain any qualifying independent approval required by live repository policy.

@coderabbitai

coderabbitai Bot commented Aug 9, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 289756a1-247d-41d0-9b52-5c8e5098606f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Copy link
Copy Markdown
Collaborator Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Aug 9, 2026 •

Copy link
Copy Markdown
⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@opencode-agent opencode-agent Bot added area: api API, protocol, event, or external contract priority: medium Normal-priority or P2 work status: draft Draft pull request type: feature New or expanded product capability labels Aug 22, 2026
@seonghobae seonghobae added the enhancement New feature or request label Sep 7, 2026 — with ChatGPT Codex Connector
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: api API, protocol, event, or external contract enhancement New feature or request priority: medium Normal-priority or P2 work status: draft Draft pull request type: feature New or expanded product capability

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant