ci: publish to npm via trusted publishing instead of a stored token (#549)

* ci: publish to npm via trusted publishing instead of a stored token

The crates.io job has been using trusted publishing for a while, but the two
npm jobs still authenticated with `secrets.NPM_TOKEN` — they set
`//registry.npmjs.org/:_authToken` from it and only used `id-token: write` to
attest provenance. So a long-lived npm credential with publish rights to the
whole scope sat in the repository's secrets, which is the thing trusted
publishing exists to remove.

Dropping the token is the whole change: npm 11.5.1+ detects the Actions OIDC
token on its own, exchanges it for a short-lived publish credential, and
generates provenance automatically on that path. The `npm install -g` pin moves
from `npm@11` to `npm@^11.5.1` to state the version that behavior needs. The
`--provenance` flags stay: they are redundant under trusted publishing but keep
the intent visible, and `publishConfig.provenance` already requests it anyway.

The `npm` environment is now load-bearing rather than decorative. A trusted
publisher entry names the repository, the workflow file, and the environment,
so all three are part of the identity — renaming any of them stops publishing
until every package's entry is updated. Both are called out where they appear.

Trusted publishing cannot create a package that does not exist yet, because the
publisher entry lives on the package's settings page. `release.md` now
documents that bootstrap step for npm alongside the equivalent crates.io one,
including the version-bump-before-pack detail that decides whether the tarball
pins its `@ox-content/*` dependencies to the right release.

Setup this needs before the next tag: a trusted publisher entry per package on
npmjs.com, and `NPM_TOKEN` can be revoked once they are in place.

* ci: pin the npm version installed in the publish jobs

Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>

---------

Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>

Author: ubugeeei

.github/workflows/publish.yml

@@ -144,11 +144,16 @@ jobs:
     name: Publish @ox-content/napi
     runs-on: ubuntu-latest
     needs: build-napi
+    # The npm environment is part of the trusted publisher identity: each
+    # package's publisher on npmjs.com names this repository, the workflow file,
+    # and this environment. Renaming any of them stops publishing until the
+    # publisher entry is updated to match.
     environment: npm
-    env:
-      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
     permissions:
       contents: read
+      # Mints the OIDC token npm exchanges for a short-lived publish
+      # credential. This is the only credential in play — there is no
+      # long-lived npm token in the repository's secrets.
       id-token: write
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -163,12 +168,15 @@ jobs:
           run-install: true
 
       - name: Setup npm registry
-        run: |
-          npm config set registry https://registry.npmjs.org
-          npm config set //registry.npmjs.org/:_authToken "$NODE_AUTH_TOKEN"
+        run: npm config set registry https://registry.npmjs.org
 
-      - name: Install npm 11+ (required for OIDC trusted publishing)
-        run: npm install -g npm@11
+      # Trusted publishing needs 11.5.1 at minimum; the runner's bundled npm
+      # trails that, so pin an exact version rather than a range. No auth
+      # token is configured: npm detects the Actions OIDC
+      # token and exchanges it for a publish credential itself, and it also
+      # generates provenance automatically on that path.
+      - name: Install npm with trusted publishing support
+        run: npm install -g npm@11.19.0 # zizmor: ignore[adhoc-packages]
 
       - name: Download all artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -276,11 +284,16 @@ jobs:
     name: Publish npm packages
     runs-on: ubuntu-latest
     needs: publish-napi
+    # The npm environment is part of the trusted publisher identity: each
+    # package's publisher on npmjs.com names this repository, the workflow file,
+    # and this environment. Renaming any of them stops publishing until the
+    # publisher entry is updated to match.
     environment: npm
-    env:
-      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
     permissions:
       contents: read
+      # Mints the OIDC token npm exchanges for a short-lived publish
+      # credential. This is the only credential in play — there is no
+      # long-lived npm token in the repository's secrets.
       id-token: write
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -295,12 +308,15 @@ jobs:
           run-install: true
 
       - name: Setup npm registry
-        run: |
-          npm config set registry https://registry.npmjs.org
-          npm config set //registry.npmjs.org/:_authToken "$NODE_AUTH_TOKEN"
-
-      - name: Install npm 11+ (required for OIDC trusted publishing)
-        run: npm install -g npm@11
+        run: npm config set registry https://registry.npmjs.org
+
+      # Trusted publishing needs 11.5.1 at minimum; the runner's bundled npm
+      # trails that, so pin an exact version rather than a range. No auth
+      # token is configured: npm detects the Actions OIDC
+      # token and exchanges it for a publish credential itself, and it also
+      # generates provenance automatically on that path.
+      - name: Install npm with trusted publishing support
+        run: npm install -g npm@11.19.0 # zizmor: ignore[adhoc-packages]
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable

docs/content/release.md

@@ -45,6 +45,50 @@ The release script verifies that every crate listed in
 order still matters because crates.io must see each dependency before Cargo can
 package a dependent crate.
 
+## npm Authentication
+
+The npm jobs publish through GitHub Actions Trusted Publishing. There is no npm
+token in the repository's secrets: `id-token: write` lets the job mint an OIDC
+token, npm exchanges it for a short-lived publish credential, and provenance is
+attested automatically on that path.
+
+Each package carries its own trusted publisher entry on npmjs.com, naming this
+repository, `.github/workflows/publish.yml`, and the `npm` environment. All
+three are part of the identity, so renaming the workflow file or the environment
+breaks publishing until every entry is updated to match.
+
+Entries are needed for the workspace packages (`@ox-content/napi`,
+`@ox-content/islands`, `@ox-content/vite-plugin`, `@ox-content/unplugin`, the
+four `@ox-content/vite-plugin-{vue,react,svelte,solid}` integrations, and
+`@ox-content/wasm`) and for each `@ox-content/napi-*` platform binding package
+the N-API build publishes.
+
+## First-Time npm Publishing
+
+Trusted publishing cannot create a package that does not exist yet: the
+publisher entry is configured on the package's settings page, so the package has
+to be there first. Same shape as the crates.io restriction below.
+
+A release that introduces a new npm package therefore needs one manual publish
+by a maintainer with local npm credentials, before the tag is pushed:
+
+```bash
+corepack pnpm --filter @ox-content/vite-plugin-new build
+cd npm/vite-plugin-ox-content-new
+corepack pnpm pack --pack-destination /tmp
+npm publish /tmp/ox-content-vite-plugin-new-<version>.tgz --access public --provenance=false
+```
+
+Bump every workspace package to the release version before packing, or the
+tarball will pin its `@ox-content/*` dependencies to the previous one.
+`--provenance=false` is required because provenance generation needs CI; the
+package's `publishConfig` turns it on, and subsequent versions get it from the
+workflow.
+
+Then add the trusted publisher entry on npmjs.com and push the tag. The publish
+steps skip versions that already exist, so the bootstrap publish is not
+republished.
+
 ## First-Time Crate Publishing
 
 The crates.io job uses GitHub Actions Trusted Publishing. Trusted Publishing can