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

.github/workflows/publish.yml

@@ -144,11 +144,16 @@
     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,14 @@
           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. 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.5.1
 
       - name: Download all artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -276,11 +283,16 @@
     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 +307,14 @@
           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. 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.5.1
 
       - 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