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.

Why now. The July 9 stable release (run) failed publishing @knocklabs/eslint-config@0.0.6 — npm rejected the NPM_TOKEN PUT with a 404 (a masked permission rejection; the package exists) — and the topological publish aborted, stranding 6 packages (client@0.21.14, react@0.11.23, …) versioned on main but absent from npm. OIDC replaces the token whose per-package grants are failing, and the registry-diff gate below picks up the stranded versions automatically on the first post-merge release.

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.17.1 — scoped-package OIDC support landed in 4.10.3. npmMinimalAgeGate: 0 pinned in .yarnrc.yml to preserve pre-bump behavior (install-script hardening already landed on main in chore: harden Yarn install scripts in the JS SDK #1019); npmPublishRegistry set to registry.npmjs.org.
• changesets/action pinned to v1.9.0 — picks up the fix for GitHub Releases not being created when some packages fail to publish, and custom version/publish command argument parsing.
• 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.
• Dead prepublishOnly removed from @knocklabs/client — Yarn Berry only runs prepack/postpack/prepublish, so it never executed under our publish flow; removing it keeps the install-less publish job honest.
• 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.
• A TODO(changesets-action-v2) note in release.yml: changesets/action v2 + Changesets v3 (both prerelease) decompose into sub-actions that would replace the custom gate/artifact/tag glue here once stable — blocked today on v2/v3 stabilizing and Changesets publishing yarn repos through npm (which can't rewrite workspace: ranges).

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 (940 tests) pass on Yarn 4.17.1; 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 / GitHub settings), not code changes:

• Enroll trusted publishers: npm login → yarn release:configure-trust
• Create the production-release environment in GitHub settings
• Add protection rules to production-release (deployment branch policy for main/canary/rc; optionally required reviewers) — it currently has none, so it only scopes the OIDC claim
• 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: f547f23

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	Jul 9, 2026 4:52pm
javascript-nextjs-example	Ready	Preview, Comment	Jul 9, 2026 4:52pm
javascript-slack-connect-example	Ready	Preview, Comment	Jul 9, 2026 4:52pm
javascript-slack-kit-example	Ready	Preview, Comment	Jul 9, 2026 4:52pm

[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 5ad53bd. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 64.71%. Comparing base (4c95d69) to head (f547f23).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1011   +/-   ##
=======================================
  Coverage   64.71%   64.71%           
=======================================
  Files         212      212           
  Lines       10275    10275           
  Branches     1406     1406           
=======================================
  Hits         6649     6649           
  Misses       3601     3601           
  Partials       25       25