ci(npm): use trusted publishing OIDC instead of NPM_TOKEN

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: AMDphreak

.github/workflows/release.yml

@@ -13,6 +13,7 @@ on:
 
 permissions:
   contents: write
+  id-token: write # npm trusted publishing (OIDC) — no NPM_TOKEN secret
 
 env:
   RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && format('v{0}', inputs.version) || github.ref_name }}
@@ -36,7 +37,6 @@ jobs:
         with:
           node-version: "24"
           cache: "pnpm"
-          registry-url: https://registry.npmjs.org
 
       - name: Install dependencies
         run: pnpm install --no-frozen-lockfile
@@ -89,16 +89,28 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Setup Node.js for npm publish
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: https://registry.npmjs.org
+
       - name: Publish to npm
         continue-on-error: true
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           pnpm ui-modules:sync
           pnpm ui-modules:validate
           node -e "const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));delete p.private;fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\n')"
+          npm --version
           npm publish --access public
           npm deprecate antora-dark-theme@* "Renamed — use valentus-theme (bundled dark mode). See https://github.com/antora-supplemental/valentus-theme" || true
+        # Trusted publisher on npmjs.com (package → Settings → Trusted publishing):
+        #   Provider: GitHub Actions
+        #   Organization/user: antora-supplemental
+        #   Repository: antora-dark-mode
+        #   Workflow filename: release.yml
+        #   Environment: (leave blank unless this job sets `environment:`)
+        # Requires npm CLI ≥ 11.5.1 (Node 24 on ubuntu-latest). No NPM_TOKEN.
 
       - name: Resolve release commit
         id: rel

docs/maintainers/npm-republish-plan.md

@@ -42,7 +42,25 @@ cd Z:\code\github.com\antora-supplemental\antora-dark-mode
 pnpm publish:npm
 ```
 
-**CI:** `.github/workflows/release.yml` publishes on semver tags when `NPM_TOKEN` is configured.
+**CI:** `.github/workflows/release.yml` publishes on semver tags using [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC). No `NPM_TOKEN` — configure the trusted publisher on npmjs.com instead (see below).
+
+### npm trusted publisher (one-time, on npmjs.com)
+
+Package **antora-dark-mode** → **Settings** → **Trusted publishing** → **GitHub Actions**:
+
+| Field | Value |
+|-------|-------|
+| Organization or user | `antora-supplemental` |
+| Repository | `antora-dark-mode` |
+| Workflow filename | `release.yml` |
+| Environment | _(leave blank — workflow does not use a deployment environment)_ |
+| Allowed actions | `npm publish` |
+
+Requires npm CLI ≥ 11.5.1 (Node 24 on GitHub-hosted runners). Provenance is generated automatically.
+
+`workflow_dispatch` re-runs use the same `release.yml` filename — no separate npm entry needed.
+
+After trusted publishing works, consider **Settings → Publishing access → Require 2FA and disallow tokens** for maximum security.
 
 ```powershell
 # After publish — deprecate legacy package name (if you own antora-dark-theme)
@@ -60,7 +78,7 @@ npm deprecate antora-dark-theme@* "Renamed — use antora-dark-mode. See https:/
 
 ## CI
 
-`.github/workflows/release.yml` — no change required for npm; optional future job for `npm publish` with `NPM_TOKEN` and `environment: npm` if maintainers want automated registry publish again.
+`.github/workflows/release.yml` — npm publish via **trusted publishing** (OIDC, `id-token: write`). Configure the trusted publisher on npmjs.com for workflow `release.yml`; no `NPM_TOKEN` secret. See `docs/maintainers/npm-republish-plan.md`.
 
 ## Related docs
 

docs/modules/guide/pages/index.adoc

@@ -6,10 +6,6 @@ Dark mode toggle, FOUC prevention, and CSS overrides for the Antora Default UI.
 
 For composed doc-site chrome (mast, header, layout), see link:https://github.com/antora-supplemental/valentus-theme[valentus-theme].
 
-== Demo
-
-https://antora-supplemental.github.io/antora-dark-mode[Live demo on GitHub Pages]
-
 == Install
 
 See xref:installation.adoc[Installation], xref:ui-modules.adoc[UI Modules], and xref:npm-distribution.adoc[npm distribution].

docs/modules/guide/pages/npm-distribution.adoc

@@ -71,10 +71,12 @@ Tarball ships overlay assets only:
 
 . Bump `package.json` version (semver aligned with git tag, e.g. `1.3.0`).
 . Temporarily remove `"private": true` for publish only.
-. `npm publish --access public` from repo root.
+. `npm publish --access public` from repo root (local) **or** push a semver tag / run the Release workflow (CI uses link:https://docs.npmjs.com/trusted-publishers/[npm trusted publishing] — OIDC, no `NPM_TOKEN`).
 . Restore `"private": true` in git.
 . `npm deprecate antora-dark-mode@* ""` to clear the retirement banner on all versions.
 
+CI trusted publisher (npmjs.com → package → Settings → Trusted publishing → GitHub Actions): org `antora-supplemental`, repo `antora-dark-mode`, workflow `release.yml`, environment blank.
+
 === 3. README and docs
 
 * Replace `README.md` retirement notice with overlay-first install (link to Installation).