Support NPM security changes with trusted publisher tokens

[jpraynaud]

Why

NPM is changing their authentication system and requires that we update our CI workflows before November, 1st. We need to update our CI to be compliant with their new authentication system as detailed in this guide.

What

Update the CI to the new NPM authentication system.

How

• Declare Mithril repository workflows in the NPM website (trust publisher): (@jpraynaud)
  • ci.yml (check if this is needed)?
  • pre-release.yml
  • release.yml
• Adapt the .github/workflows/actions/publish-npm-package action for:
  • ci.yml
  • pre-release.yml
  • release.yml
• Remove NPM_API_TOKEN_MITHRIL_CLIENT_WASM in GitHub environment secrets (@jpraynaud)

[Alenar]

Testing trusted publisher

I tried to setup npm trusted publishers on a private repository created specifically to test mimic our release model (unstable builds package, pre-release create a github release when a tag is pushed, release is triggered when ticking off 'pre-release' off the release).

I changed the mimic setup to use a shared workflow using workflow_call trigger to circumvent the limitation to only one workflow for the unique trusted published that can be setup on a npm package.

Caution

While testing I found out that npm dist-tag, that we use handle package promotion, does not currently support trusted publisher, only npm publish support it right now. cf:

Limitations and future improvements

Trusted publishing currently supports only cloud-hosted runners. Support for self-hosted runners is intended for a future release. Each package can only have one trusted publisher configured at a time, though you can update this configuration as needed.

OIDC authentication is currently limited to the publish operation. Other npm commands such as install, view, or access still require traditional authentication methods. The npm whoami command will not reflect OIDC authentication status since the authentication occurs only during the publish operation.

We intend to expand trusted publishing support to additional CI/CD providers and enhance the feature based on community feedback.

First attempt: following the doc

Publishing workflow

name: Publish npm package

on:
  workflow_call:
    inputs:
      dry_run:
        description: Dry run will not publish to npm, just test it.
        type: boolean
        required: true
      tag:
        required: false
        type: string
        default: "latest"
      package:
        required: true
        type: string
      scope:
        required: true
        type: string
      access:
        description: npm package access.
        type: string
        required: false
        default: "public"
      registry:
        description: npm registry domain.
        type: string
        required: false
        default: "registry.npmjs.org"

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout sources
        uses: actions/checkout@v4

      - uses: actions/setup-node@v6
        with:
          node-version: 24
          registry-url: https://${{ inputs.registry }}

      # Ensure npm 11.5.1 or later for trusted publishing
      - run: npm install -g npm@latest

      - name: Check npm latest version
        id: check_version
        run: |
          echo "Check latest published version for '${{ inputs.package }}' package"

          if [ "${{ inputs.tag }}" != "latest" -a "${{ inputs.tag }}" != "next" ]; then
            echo "Tag '${{ inputs.tag }}' is not valid. It should be one of 'latest' or 'next'"
            exit 1
          fi

          LOCAL_VERSION=$(cat ${{ inputs.package }}/package.json | jq -r '.version')
          NEXT_REMOTE_VERSION=$(npm view @${{ inputs.scope }}/${{ inputs.package }} dist-tags.next 2> /dev/null || true)
          LATEST_REMOTE_VERSION=$(npm view @${{ inputs.scope }}/${{ inputs.package }} dist-tags.latest 2> /dev/null || true)

          echo "Latest npmjs.com version: '$LATEST_REMOTE_VERSION'"
          echo "Next npmjs.com version: '$NEXT_REMOTE_VERSION'"
          echo "Local version: '$LOCAL_VERSION'"

          if [ "${{ inputs.tag }}" == "latest" ]; then
            if [ "$LOCAL_VERSION" == "$LATEST_REMOTE_VERSION" ]; then
              echo "Local version and remote version are the same: no need to publish to npm registry"
              DEPLOY_MODE='none'
            elif [ "$LOCAL_VERSION" == "$NEXT_REMOTE_VERSION" ]; then
              DEPLOY_MODE='promote'
            else
              DEPLOY_MODE='publish'
            fi
          else # input.tag == 'next'
            if [ "$LOCAL_VERSION" == "$LATEST_REMOTE_VERSION" ]; then
              # A latest already published: no need to tag with next
              echo "Local version and remote version are the same: no need to publish to npm registry"
              DEPLOY_MODE='none'
            elif [ "$LOCAL_VERSION" == "$NEXT_REMOTE_VERSION" ]; then
              echo "Local version and remote version are the same: no need to publish to npm registry"
              DEPLOY_MODE='none'
            else
              DEPLOY_MODE='publish'
            fi
          fi

          echo "Deploy mode: '$DEPLOY_MODE'"
          echo "Dry run: '${{ inputs.dry_run }}'"
          echo "deploy_mode=$DEPLOY_MODE" >> $GITHUB_OUTPUT
          echo "package_version=$LOCAL_VERSION" >> $GITHUB_OUTPUT

      - run: npm ci
        working-directory: ${{ inputs.package }}

      - name: Prepare publish
        shell: bash
        run: |
          cp ./LICENSE ${{ inputs.package }}

      - name: List package
        working-directory: ${{ inputs.package }}
        run: |
          echo "List '@${{ inputs.scope }}/${{ inputs.package }}' package"
          ls -al -R ./

      - name: Publish package new version
        working-directory: ${{ inputs.package }}
        if: steps.check_version.outputs.deploy_mode == 'publish'
        run: |
          if [ "${{ inputs.dry_run }}" == "false" ]; then
          echo "Publish '@${{ inputs.scope }}/${{ inputs.package }}' package"
            dry_run_option=""
          else
          echo "Publish '@${{ inputs.scope }}/${{ inputs.package }}' package (dry run)"
            dry_run_option="--dry-run"
          fi
          npm publish --tag ${{ inputs.tag }} --access ${{ inputs.access }} $dry_run_option --verbose

      - name: Promote package distribution tag to 'latest'
        if: inputs.dry_run == 'false' && steps.check_version.outputs.deploy_mode == 'promote'
        run: |
          echo "Publish '@${{ inputs.scope }}/${{ inputs.package }}' package"
          # npm whoami
          npm dist-tag add @${{ inputs.scope }}/${{ inputs.package }}@${{ steps.check_version.outputs.package_version }} latest
          npm dist-tag rm @${{ inputs.scope }}/${{ inputs.package }}@${{ steps.check_version.outputs.package_version }} next

Example of how it's called in the parent workflow (here ci.yml)

  publish-npm-test:
    uses: ./.github/workflows/npm-publish.yml
    permissions:
      id-token: write
      contents: read
    with:
      dry_run: true
      package: npm-trusted-publisher-test
      scope: ${{ vars.NPM_SCOPE }}

I could not manage to make it works, with trusted publisher the most I could get was (logs extracted from a npm publish --verbose):

npm http fetch POST 404 https://registry.npmjs.org/-/npm/v1/oidc/token/exchange/package/@user%2fpackage 760ms
npm verbose oidc Failed token exchange request with body message: OIDC token exchange error - package not found

My guess (low confidence) is it can't work right now with a workflow_call trigger, since the trusted publisher may be checking the calling workflow against the parent workflow (who dispatch the workflow_call trigger).

Second attempt: manual fetching of token using OIDC

Secondly I tried to fetch a token myself directly from the trusted publisher. This would have the advantage to be able to re-use the tokens for npm dist-tag commands.

Details

Script used to fetch the token from npm:

# Code originally from electron/npm-trusted-auth-action : https://github.com/electron/npm-trusted-auth-action/blob/main/action.yml

set -euo pipefail
# set -vx # uncomment for step by step debug

debug_jwt() {
  jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< "${1}"
  echo "Signature: $(echo "${1}" | awk -F'.' '{print $3}')"
}

if [ -z "${1-""}" ]; then echo "::error::Missing PACKAGE_FOLDER"; fi;
if [ -z "${2-""}" ]; then echo "::error::Missing REQUEST_TOKEN"; fi;
if [ -z "${3-""}" ]; then echo "::error::Missing REQUEST_URL"; fi;
if [ -z "${4-""}" ]; then echo "::error::Missing REGISTRY"; fi;

declare -r RUNNER_DEBUG=${RUNNER_DEBUG:-0}
declare -r PACKAGE_FOLDER=$1; shift
declare -r REQUEST_TOKEN=$1; shift
declare -r REQUEST_URL=$1; shift
declare -r REGISTRY=$1; shift

PACKAGE_NAME=$(jq -r ".name // empty" < "$PACKAGE_FOLDER"/package.json)
if [[ -z "$PACKAGE_NAME" ]]; then
  echo "::error::No package.json in PACKAGE_FOLDER '${PACKAGE_FOLDER}'"
  exit 1
fi

# Safely encode the package name
ENCODED_PACKAGE=$(printf "%s" "$PACKAGE_NAME" | jq -Rr @uri)

if [[ "$RUNNER_DEBUG" == "1" ]]; then
  echo "Encoded package name: $ENCODED_PACKAGE"
fi

# Request GitHub OIDC token with npm audience
OIDC_TOKEN=$(curl -sS -H "Authorization: bearer $REQUEST_TOKEN" "$REQUEST_URL&audience=nmp:$REGISTRY" \
  -H "Accept: application/json; api-version=2.0" -H "Content-Type: application/json" -d "{}" \
  | jq -r '.value // empty')

if [[ -z "$OIDC_TOKEN" ]]; then
  echo "::error::Failed to get OIDC token from GitHub"
  exit 1
fi

debug_jwt "$OIDC_TOKEN"

# Exchange OIDC token for npm auth token
RESPONSE=$(curl -sS -X POST \
  -H "Authorization: Bearer $OIDC_TOKEN" \
  -H "Accept: application/json" \
  -w "\n%{http_code}" \
  "https://$REGISTRY/-/npm/v1/oidc/token/exchange/package/$ENCODED_PACKAGE")

# Extract status code and body
HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [[ "$HTTP_CODE" != "201" ]]; then
  echo "::error::Failed to exchange token. Status: $HTTP_CODE"
  echo "::error::Body: $BODY"
  exit 1
fi

# Extract and mask the npm token
NPM_TOKEN=$(echo "$BODY" | jq -r '.token // empty')

if [[ -z "$NPM_TOKEN" ]]; then
  echo "::error::No token in response"
  exit 1
fi

export NPM_TOKEN

Steps added to the npm publishing workflow to call the script:

      - name: Authenticate with npm registry
        env:
          GITHUB_ENV: ${{ github.env }}
        run: |
          .github/workflows/scripts/npm-auth.sh \
              ${{ inputs.package }} \
              $ACTIONS_ID_TOKEN_REQUEST_TOKEN \
              $ACTIONS_ID_TOKEN_REQUEST_URL \
              ${{ inputs.registry }}
          
          echo "::add-mask::$NPM_TOKEN"
          echo "token=$NPM_TOKEN" >> $GITHUB_OUTPUT
          echo "NPM_TOKEN=$NPM_TOKEN" >> $GITHUB_ENV

This does not work as-is either:

Error: Failed to exchange token. Status: 401
Error: Body: {"message":"OIDC token exchange error - unauthorized"}
Error: Process completed with exit code 1.

There may be something missing when requesting the token, or it may be the same limitation that I was guessing on my first attempt.

Recommendation

Npm trusted publisher is still quite new and is missing features (handling of re-usable workflows, support on other commands than publish).

My recommendation right now is to keep using tokens, meaning switching to granular access tokens with a lifetime (max 90 days) as the legacy "automation" tokens that we use will be revoked next month.

We should revisit trusted publisher in 6~8 month and see if the limitations that are hindering us were lift.