🔒 ci: publish to npm via Trusted Publishing (OIDC) instead of NPM_TOKEN

.github/workflows/publish.yml

@@ -47,13 +47,27 @@ jobs:
     needs: verify-tag
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    environment: npm
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
         with:
           node-version: 22
           registry-url: https://registry.npmjs.org/
           cache: npm
+      # Trusted Publishing needs npm >= 11.5.1; the npm bundled with Node 22
+      # is older. Pin the upgrade rather than installing npm@latest inside the
+      # job that holds the OIDC token.
+      - name: Ensure npm supports Trusted Publishing
+        run: |
+          have="$(npm --version)"
+          if [ "$(printf '%s\n' 11.5.1 "$have" | sort -V | head -n1)" != "11.5.1" ]; then
+            npm install -g npm@11.5.1
+          fi
+          npm --version
       # Dependency lifecycle scripts must not run in the job that holds the
       # OIDC token used for npm provenance.
       - run: npm ci --ignore-scripts
@@ -69,9 +83,14 @@ jobs:
           echo "$out"
           test "$out" = "@hivecommons/pluk ${GITHUB_REF_NAME#v}"
           test -d node_modules/@hivecommons/pluk/patterns
-      - run: npm publish --access public --provenance
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Require OIDC token for npm Trusted Publishing
+        run: |
+          if [ -z "$ACTIONS_ID_TOKEN_REQUEST_URL" ]; then
+            echo "::error::ACTIONS_ID_TOKEN_REQUEST_URL is not set; the job needs 'id-token: write' for npm Trusted Publishing"
+            exit 1
+          fi
+      - name: Publish package with provenance (Trusted Publishing)
+        run: npm publish --access public --provenance
 
   release:
     name: GitHub release

runbooks/publish-failure.md

@@ -30,7 +30,10 @@ The tag does not match `package.json`, is not reachable from `main`, or
 ## `publish` failed (version not on npm)
 
 If `npm view @hivecommons/pluk@X.Y.Z version` returns nothing, the failure was
-tests, build, smoke-test, or registry/auth (`NPM_TOKEN`). Fix the cause, then use
+tests, build, smoke-test, or registry/auth. Auth uses npm Trusted Publishing
+(OIDC) via the `npm` GitHub Environment — there is no `NPM_TOKEN`; if npm rejects
+the publish, check the Trusted Publisher on npmjs.com (org `hivecommons`, repo
+`pluk`, workflow `publish.yml`, environment `npm`). Fix the cause, then use
 **Re-run failed jobs** on the run. If the fix needs a code change, follow the
 `verify-tag` path above to retag.