ci: publish to npm with provenance attestation

[nicolasiscoding]

Why

npm can attach a signed provenance attestation to a published package: a SLSA statement, recorded in the public Sigstore transparency log, that ties the published tarball back to the exact GitHub Actions workflow run and commit that produced it. Consumers can then verify it with npm audit signatures.

The n8n community-node registry rejected another one of our packages specifically because it was published without provenance. That package has since been fixed and re-released with an attestation, and we are now applying the same one-line change across the public TurboDocx repos that publish to npm.

What changed

One file, .github/workflows/npm-publish.yml:

1. Added a job-level permissions block to publish-npm:

   permissions:
     contents: read   # needed by actions/checkout
     id-token: write  # needed to mint the OIDC token npm uses to sign the attestation

   contents: read is included deliberately. Declaring a permissions block zeroes every scope not listed, so omitting it would break actions/checkout.
2. Added --provenance to the publish step: npm publish --access public --provenance.

Nothing else. No permissions block was added at the workflow level or to the build job.

Node 24 (already pinned in this workflow) ships npm 11.x, comfortably above the npm >= 9.5 that provenance requires, and this repo is public, so both preconditions are already satisfied.

publishConfig.provenance was deliberately NOT added

"publishConfig": { "provenance": true } in package.json would make a bare local npm publish fail. That is only desirable if GitHub Actions is genuinely the sole publisher, so I checked before adding it:

• npm view @turbodocx/html-to-docx versions --json — 30 published versions, 1.9.1 through 1.22.0.
• gh run list --workflow=npm-publish.yml -L 100 — 20 runs total in the queryable run history, the oldest being v1.13.5 (2025-08-15).

Result: every version from 1.13.5 through 1.22.0 maps cleanly to a successful workflow run (each publish timestamp lands a minute or two after its run started). But for 1.9.1 through 1.13.4 — published 2024-05-22 through 2025-06-05 — no corresponding run exists in the queryable run history. I can't tell whether those were published by hand or whether the run records have simply aged out, and I'm not going to assert either. Since the evidence doesn't establish that Actions has always been the only publisher, publishConfig is omitted here.

That costs us nothing that matters: the --provenance flag is what actually produces the attestation. publishConfig.provenance is only a guardrail against an accidental local publish — and not even an enforcement boundary, since npm gives CLI flags precedence over publishConfig, so npm publish --provenance=false would still push an unattested tarball. If we later want the guardrail, it can be added in a follow-up.

No version bump, no release

This PR does not bump the version and does not cut a release. Provenance is attached at publish time, so there is nothing to verify after merging — this simply makes the next release attested.

Whenever someone next cuts a release, that publish should produce an attestation, and it can be confirmed with:

npm view @turbodocx/html-to-docx@<version> dist.attestations

which should report a provenance entry with predicateType of https://slsa.dev/provenance/v1.

Two notes for the reviewer

• There is a dangling branch, add-npm-provenance, carrying an equivalent commit from December 2025 that never got a PR and has since fallen far behind. This PR supersedes it, and that branch can be deleted.
• Release tags are cut from main, not develop (v1.22.0 is reachable from main only). This PR targets develop, the default branch and where all other active PRs go, so the change takes effect on the first release cut after the next develop -> main promotion.

Risk

Low, and non-destructive if it goes wrong. npm builds and signs the provenance statement inside buildMetadata, which must return before the registry PUT. So if OIDC or attestation generation fails, the publish aborts before anything reaches the registry — nothing gets published and the version number stays reusable.

Worth noting for reviewers: npm publish --dry-run cannot exercise this path (npm short-circuits before the publish internals run), so the real check is the next release.

[github-actions]

TurboDocx DOCX Diff Report

Automated HTML to DOCX regression testing | Powered by TurboDocx

Summary

• ✅ Identical files: 71
• 🔄 Changed files: 0
• ➕ New files: 0
• ➖ Deleted files: 0

---

🚀 Powered by TurboDocx | html-to-docx

Automated DOCX regression testing • Catch document generation bugs before they ship • 100% open source

Generated by TurboDocx DOCX Diff workflow • Learn more