Prerelease Considerations

Prerelease Considerations

⚠️ n8PDF is early — 0.1.x, freshly released and pre-1.0. It is published and hardened, but it has had little exposure in the wild and its API is not frozen until v1.0.0. Evaluate it as pre-1.0 software.

What "pre-1.0" means here

The library is published on NuGet, the suite passes, the fidelity numbers on Matching Word are real, and the security hardening is done — but 0.1.x is deliberately conservative about what it promises:

• It has shipped, but it is young. n8PDF 0.1.1 is on NuGet, published through trusted publishing (an OIDC exchange from CI, with no stored key) and carrying a signed SLSA build-provenance attestation you can verify — gh attestation verify n8PDF.0.1.1.nupkg --repo nathanpond/n8PDF; see Installation. What it does not yet have is a large base of users who have run it against their own documents. The API surface (The API) is intended to be stable, but until a v1.0.0 tag it may still change.
• The full Word comparison runs on one machine. Hosted CI covers most of the comparison fixtures; the rest are set in faces only Word ships and are compared on a machine that has Word (Validation). A green CI is not the whole story.
• The security register is closed, and the structural defences are in place. The project's own audits filed over a hundred findings — unbounded allocations, integer overflows, unbounded recursion, hang loops, process-killing stack overflows — and all are fixed, each with the attack built as a regression test. Behind that register, the hardening work added the defences a closed register and a fixed-corpus fuzzer cannot reach on their own: library-wide checked arithmetic, CodeQL and Semgrep in CI, property-based, coverage-guided, continuous and differential fuzzing, a written Threat Model and disclosure policy, a SHA-pinned supply chain, and the verifiable provenance above. That is a real change of state — but it is a statement about the attacks that were found and the defences that were built, not a proof that none remain: see Security.

User-supplied documents

Earlier this page said do not convert user-supplied documents at all, because the register held dozens of open findings a crafted document could exploit. That register is empty now — the memory-exhaustion, hang and stack-overflow findings are fixed and fuzz-guarded — so the categorical ban has served its purpose and is lifted.

What replaces it is the standard posture for untrusted-input processing, stated on Security and the Threat Model and worth restating here:

• A .docx is still attacker-controlled input, and young software has had little exposure to the wild. If you convert documents from the public, do it in a worker process with an OS-level memory cap and a timeout, with Limits set tight — and, since caller cancellation landed, pass a CancellationToken so a pathological document cannot hang the call even in-process. Treat isolation as the load-bearing defence, not a formality.
• The failure modes remain denial-of-service-shaped rather than code execution — the library is pure managed code with no unsafe — so what isolation is protecting is your service's availability.

Acceptable uses today

• Evaluation, prototyping, and fidelity testing against your own document corpus
• Internal tooling over trusted, self-authored documents
• Production use over trusted documents, with the pre-1.0 caveat that the API may change before v1.0.0
• Converting third-party documents behind the isolation posture above, where the source is genuinely untrusted
• Contributing — testing on real documents you own and filing what breaks is exactly the help the project needs (Developers)

When this page changes

The caution was always meant to soften in stages, and the big ones have happened: the hostile-input epics are closed, the structural-hardening epic is complete, and the library is published with verifiable provenance. What stands between 0.1.x and dropping the pre-1.0 caveat is not more machinery but exposure and stability — real-world use across many documents, and an API settled enough to promise at v1.0.0. Watch the issue tracker: the security label and the release history are the honest signal of where things stand.