feat(release): adopt npm OIDC trusted publishing with provenance

[kylemcd]

Description

Replaces the long-lived NPM_TOKEN in release.yml with npm OIDC trusted publishing + provenance, and restructures the release pipeline so the short-lived OIDC token is isolated to a job that runs nothing but yarn npm publish. Implements KNO-13137.

Why. Today one static NPM_TOKEN can publish every @knocklabs package from anywhere if it leaks. OIDC swaps it for a token minted per run that expires in minutes and only works from this repo's release.yml, and provenance cryptographically links each published tarball to the exact commit + workflow run. The job split is the post-TanStack architecture: that compromise worked because the release job held publish power while also running yarn install/build, so malicious dependency code read the token from runner memory. Here, install/build run in a job with no publish power, and the id-token job runs no untrusted code.

How — release.yml is now four jobs:

Job	Role	id-token	Install
version	Opens the Changesets "Version Packages" PR	no	yes
build	yarn build:packages, uploads dist (runs dependency scripts)	no	yes
publish	Runs only yarn npm publish → OIDC + provenance	yes	no
release	Pushes git tags + GitHub Releases via changesets/action	no	yes

Also in this PR:

• Yarn 4.9.1 → 4.16.0 — scoped-package OIDC support landed in 4.10.3. Kept behavior-neutral: enableScripts: true and npmMinimalAgeGate: 0 pinned in .yarnrc.yml to preserve pre-bump behavior; npmPublishRegistry set to registry.npmjs.org.
• Registry-diff publish gate (.github/scripts/list-unpublished-packages.mjs) so build/publish/release only run when there are new versions, plus a fail-loud pre-flight that points a new (unenrolled) package at the bootstrap runbook instead of a cryptic npm auth error.
• repository metadata (incl. directory) added/fixed on all 9 packages — required for provenance.
• scripts/configure-trusted-publishers.mjs (yarn release:configure-trust) to enroll trusted publishers, and the OIDC publishing + new-package bootstrap runbook folded into RELEASES.md.

Preserved (no functional regression): npm dist-tags (latest/canary/rc), workspace: → version substitution, --tolerate-republish, prerelease/canary→main promotion logic, git tags (incl. private example apps), and GitHub Releases with changelog notes.

Validated locally: build, type:check, lint, format:check, and the full test suite (878 tests) pass on Yarn 4.16; yarn --immutable passes with the committed lockfile; yarn npm publish substitutes workspace: ranges and engages --provenance with no install. The OIDC handshake itself is exercised on the first real release (going direct to main, no canary pre-flight).

Todos

Out-of-repo rollout (npm org admin), not code changes:

• Enroll trusted publishers: npm login → yarn release:configure-trust
• Create the production-release environment in GitHub settings
• After the first successful OIDC release, delete the NPM_TOKEN secret (kept until then as a one-revert rollback)

[linear-code]

KNO-13137

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5ac4ce1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
javascript-ms-teams-connect-example	Ready	Preview, Comment	Jun 9, 2026 3:31pm
javascript-nextjs-example	Ready	Preview, Comment	Jun 9, 2026 3:31pm
javascript-slack-connect-example	Ready	Preview, Comment	Jun 9, 2026 3:31pm
javascript-slack-kit-example	Ready	Preview, Comment	Jun 9, 2026 3:31pm

[kylemcd]

• feat(release): adopt npm OIDC trusted publishing with provenance #1011 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d118806. Configure here.}

[cursor]

Exit prerelease SHA mismatch

High Severity

After the auto exit-prerelease step bumps versions and pushes a new commit, the version job keeps running and Detect unpublished packages reads those updated local package.json files. build, publish, and release check out the original workflow github.sha, so they can build and publish different versions than the gate decided on.

Additional Locations (1)

• .github/workflows/release.yml#L148-L159

 

^{Reviewed by Cursor Bugbot for commit d118806. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 63.55%. Comparing base (7ef0f23) to head (d118806).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1011   +/-   ##
=======================================
  Coverage   63.55%   63.55%           
=======================================
  Files         208      208           
  Lines        9924     9924           
  Branches     1280     1280           
=======================================
  Hits         6307     6307           
  Misses       3592     3592           
  Partials       25       25