Switch npm release to trusted publishing (OIDC).

Remove NPM_TOKEN-based auth from the release workflow and document
npm Trusted Publisher setup in RELEASING.md and AGENTS.md.

Author: digitallysavvy

.github/workflows/release.yml

@@ -18,7 +18,7 @@ on:
 permissions:
   contents: write   # create GitHub release artifacts for installers
   packages: write   # push to GitHub Container Registry (Docker)
-  id-token: write   # required for npm provenance attestations (sigstore)
+  id-token: write   # required for npm trusted publishing and provenance (OIDC)
 
 jobs:
   goreleaser:
@@ -112,8 +112,9 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: "20"
+          node-version: "24"
           registry-url: "https://registry.npmjs.org"
+          package-manager-cache: false
 
       - name: Resolve target version
         id: ver
@@ -257,10 +258,23 @@ jobs:
           ' packaging/npm/agoraio-cli/package.json > "$tmp"
           mv "$tmp" packaging/npm/agoraio-cli/package.json
 
+      - name: Prepare npm for trusted publishing
+        if: steps.mode.outputs.mode == 'publish'
+        shell: bash
+        run: |
+          set -euo pipefail
+          # Trusted publishing requires npm CLI 11.5.1+.
+          npm install -g npm@latest
+          npm --version
+          # setup-node writes an empty _authToken placeholder when registry-url is set
+          # without NODE_AUTH_TOKEN; remove it so npm uses OIDC trusted publishing.
+          if [ -n "${NPM_CONFIG_USERCONFIG:-}" ] && [ -f "$NPM_CONFIG_USERCONFIG" ]; then
+            sed -i '/^\/\/registry\.npmjs\.org\/:_authToken=/d' "$NPM_CONFIG_USERCONFIG"
+          fi
+
       - name: Publish platform packages
         shell: bash
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           PUBLISH_ARGS: ${{ steps.mode.outputs.publish_args }}
         run: |
           set -euo pipefail
@@ -271,9 +285,15 @@ jobs:
             packaging/npm/agoraio-cli-linux-x64 \
             packaging/npm/agoraio-cli-win32-x64 \
             packaging/npm/agoraio-cli-win32-arm64; do
+            package_name="$(node -p "require('./${pkg}/package.json').name")"
+            package_version="$(node -p "require('./${pkg}/package.json').version")"
+            if [ -z "$PUBLISH_ARGS" ] && npm view "${package_name}@${package_version}" version >/dev/null 2>&1; then
+              echo "${package_name}@${package_version} is already published; skipping."
+              continue
+            fi
             echo "Publishing $pkg ${PUBLISH_ARGS}"
+            # Authenticates via npm trusted publishing (OIDC) when not in dry-run mode.
             # --provenance is honored by publishConfig.provenance; passing here for clarity.
-            # When PUBLISH_ARGS contains --dry-run, no provenance attestation is created.
             if [ -n "$PUBLISH_ARGS" ]; then
               npm publish "$pkg" --access public $PUBLISH_ARGS
             else
@@ -284,11 +304,16 @@ jobs:
       - name: Publish wrapper package
         shell: bash
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           PUBLISH_ARGS: ${{ steps.mode.outputs.publish_args }}
         run: |
           set -euo pipefail
           pkg="packaging/npm/agoraio-cli"
+          package_name="$(node -p "require('./${pkg}/package.json').name")"
+          package_version="$(node -p "require('./${pkg}/package.json').version")"
+          if [ -z "$PUBLISH_ARGS" ] && npm view "${package_name}@${package_version}" version >/dev/null 2>&1; then
+            echo "${package_name}@${package_version} is already published; skipping."
+            exit 0
+          fi
           echo "Publishing $pkg ${PUBLISH_ARGS}"
           if [ -n "$PUBLISH_ARGS" ]; then
             npm publish "$pkg" --access public $PUBLISH_ARGS

AGENTS.md

@@ -258,8 +258,8 @@ packaging/npm/
 6. Smoke-tests the published wrapper with `npx --yes agoraio-cli@<tag> --version` (retry/backoff for registry propagation)
 
 **Prerequisites:**
-- `NPM_TOKEN` secret in the repo, with publish access to `agoraio-cli` and all unscoped `agoraio-cli-*` platform packages.
-- `id-token: write` workflow permission (already set in `release.yml`) — required for npm provenance.
+- npm **Trusted Publisher** configured on each package (`agoraio-cli` and all `agoraio-cli-*`), pointing at repo `AgoraIO/cli` and workflow `release.yml`.
+- `id-token: write` workflow permission (already set in `release.yml`) — required for trusted publishing and provenance.
 
 **Manual dry-run:** the workflow exposes `workflow_dispatch` with a `dry_run` input that runs `npm publish --dry-run` against a synthetic version, validating packaging without publishing.
 

RELEASING.md

@@ -25,8 +25,8 @@ The release workflow (`.github/workflows/release.yml`) then:
    - Publishes the six per-platform packages with `npm publish --provenance`
    - Publishes the wrapper package (`agoraio-cli`) with `npm publish --provenance`
    - Runs a post-publish smoke test: `npx --yes agoraio-cli@<tag> --version` with retry/backoff to handle registry propagation
-   - Requires `NPM_TOKEN` secret with publish access to `agoraio-cli` and `agoraio-cli-*`
-   - Requires `id-token: write` workflow permission for sigstore-backed npm provenance attestations
+   - Authenticates via [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC from GitHub Actions — no `NPM_TOKEN` secret)
+   - Requires `id-token: write` workflow permission (already set in `release.yml`)
 
 3. **Apt repository** job (triggered by the published release):
    - Downloads `.deb` files from the release
@@ -63,17 +63,19 @@ The release workflow exposes a `workflow_dispatch` trigger that runs the npm pub
 
 Before tagging the first real release that ships npm, confirm:
 
-- [ ] `NPM_TOKEN` secret is set in the repo (Settings → Secrets and variables → Actions). Token must have publish access to `agoraio-cli` and all unscoped `agoraio-cli-*` platform packages.
+- [ ] Each npm package has a **Trusted Publisher** configured on [npmjs.com](https://www.npmjs.com) (Package → Settings → Trusted Publisher → GitHub Actions):
+  - Repository: `AgoraIO/cli`
+  - Workflow filename: `release.yml`
+  - Configure for `agoraio-cli` and all six `agoraio-cli-{os}-{arch}` platform packages
 - [ ] `agoraio-cli` and `agoraio-cli-*` package names on npmjs.com are owned by the Agora npm org / publisher and not squatted.
-- [ ] The workflow has `id-token: write` permission (already set in `release.yml`); npm provenance requires it.
-- [ ] A `workflow_dispatch` dry-run on the current `main` succeeds end-to-end (validates packaging, scripts, provenance).
+- [ ] The workflow has `id-token: write` permission (already set in `release.yml`); trusted publishing and provenance require it.
+- [ ] A `workflow_dispatch` dry-run on the current `main` succeeds end-to-end (validates packaging and tarball contents).
 - [ ] First publish should be a release-candidate tag (e.g. `v0.1.x-rc.1`) so an unexpected failure does not affect a "latest" tag in the registry.
 
 ## Required Secrets and Variables
 
 | Name                 | Type     | Required for                    |
 | -------------------- | -------- | ------------------------------- |
-| `NPM_TOKEN`          | secret   | npm publish (active)            |
 | `APT_SIGNING_KEY`    | secret   | Signed apt repo on GitHub Pages |
 | `APT_SIGNING_KEY_ID` | variable | Signed apt repo on GitHub Pages |
 
@@ -105,7 +107,7 @@ If a published version is bad:
 
 - [ ] Enable GitHub Pages on this repo (Settings → Pages → Source: GitHub Actions)
 - [ ] Generate GPG key for apt signing; set `APT_SIGNING_KEY` and `APT_SIGNING_KEY_ID`
-- [ ] Set `NPM_TOKEN` with publish access to `agoraio-cli` and all `agoraio-cli-*` packages
+- [ ] Configure npm **Trusted Publishers** for `agoraio-cli` and all `agoraio-cli-*` packages (repo: `AgoraIO/cli`, workflow: `release.yml`)
 - [ ] Run a `workflow_dispatch` dry-run of the release workflow to validate npm packaging
 - [ ] Add Homebrew and Scoop GoReleaser blocks before announcing those channels
 - [ ] Submit first Winget manifest PR to `microsoft/winget-pkgs` after the first release