feat: add npm OIDC trusted publishing support

[GarthDB]

Add npm OIDC Trusted Publishing Support

Overview

This PR adds support for npm's OIDC trusted publishing, eliminating the need for long-lived NPM_TOKEN secrets. This provides enhanced security through cryptographic provenance attestation and short-lived credentials.

Benefits

• No token management: Eliminates the need to create, store, and rotate NPM_TOKEN secrets
• Cryptographic provenance: Automatically generates attestation proving packages were built from the specified repository and workflow
• Enhanced security: Uses short-lived OIDC tokens instead of long-lived authentication tokens
• Eliminates token leakage risk: No secrets to accidentally commit or expose

Changes

New Input Parameter

• Added oidcAuth boolean input (default: false) to enable OIDC authentication

OIDC Validation

• Validates npm CLI version is 11.5.1 or higher (required for OIDC support)
• Verifies id-token: write permission is granted in workflow
• Detects and warns about conflicting NPM_TOKEN configuration
• Provides clear error messages with remediation steps

Authentication Setup

• Skips .npmrc creation in OIDC mode (npm CLI auto-detects OIDC credentials)
• Explicitly passes OIDC environment variables to publish command for compatibility with toolchains that start fresh shells (e.g., proto, moon)
• Maintains full backward compatibility with existing NPM_TOKEN authentication

Environment Variables Handling

• Ensures ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN are passed through to child processes
• Critical for compatibility with toolchain managers and nested process execution

Testing

• 30 tests passing (all existing tests + new OIDC tests)
• 9 new unit tests for OIDC validation logic
• 13 integration tests for authentication setup
• Validation test workflow included (.github/workflows/test-oidc-validation.yml)
• Backward compatibility verified - all existing NPM_TOKEN tests still pass

Documentation

• Comprehensive OIDC setup guide with prerequisites
• Migration instructions from NPM_TOKEN to OIDC
• Example workflows for both authentication methods
• Clear explanation of benefits and provenance attestation
• Troubleshooting section with validation requirements

Backward Compatibility

✅ Fully backward compatible - existing workflows using NPM_TOKEN continue to work without any changes.

The oidcAuth parameter defaults to false, so this is an opt-in feature.

Example Usage

With OIDC (Recommended for New Projects)

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write
  id-token: write  # Required for OIDC

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      
      # Ensure npm 11.5.1+
      - run: npm install -g npm@latest
      
      - run: yarn install
      
      - uses: changesets/action@v1
        with:
          publish: yarn release
          oidcAuth: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # No NPM_TOKEN needed!

Migration Path

For existing projects using NPM_TOKEN:

1. Update workflow to ensure npm 11.5.1+
2. Configure trusted publisher on npmjs.com
3. Add id-token: write permission
4. Set oidcAuth: true
5. Remove NPM_TOKEN from workflow and GitHub secrets

Prerequisites for OIDC

1. npm CLI version 11.5.1 or higher
2. Trusted publisher configured on npmjs.com (Settings → Publishing Access)
3. Workflow with id-token: write permission

Additional Context

This implementation has been thoroughly tested in production:

• Successfully published multiple packages with OIDC
• Verified provenance attestation generation
• Tested with various version bumps (patch, minor, major)
• Compatible with standard Node.js setup and toolchain managers

Related Issues

Resolves #515 (if exists - npm OIDC support request)

[changeset-bot]

⚠️ No Changeset found

Latest commit: b7f2e60

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Andarist]

I just landed #545 that chooses a simpler approach of conditionally messing with .npmrc files when the process.env.NPM_TOKEN is configured. I think that supersedes this PR here and I'm going to close this. Please feel free to respond back if you think the approach taken here is better and needs extra consideration.

[GarthDB]

Hey @Andarist, thanks for reviewing and the feedback.

Personally, I ran into some real-world issues when testing OIDC in production (at Adobe) that the simpler approach doesn't address, mostly around identifying why it was failing. If you wanted to help people avoid that, some validation would be nice.

Without validation, users get cryptic npm errors instead of actionable feedback:

With #545 (no validation):

npm error code ENEEDAUTH
npm error need auth This command requires you to be logged in to https://registry.npmjs.org/

With validation (this PR):

Error: npm version 10.8.1 detected. npm 11.5.1+ required for OIDC.
Add step to your workflow:
  - run: npm install -g npm@latest

The first experience is frustrating - you don't know if it's a permission issue, npm version issue, or configuration issue. The second tells you exactly what's wrong and how to fix it.

I ran into these 4 real issues that I had to debug and figure out (with many test pull requests) before finding the root issues:

1. npm version too old - Many workflows don't update npm, so they're running 10.x which doesn't support OIDC
2. Missing id-token: write - Easy to forget this permission
3. Conflicting auth - Users accidentally leave NPM_TOKEN set while trying OIDC
4. Toolchain compatibility - Some tools (proto shims, etc.) need explicit env passing

If you don't think it's the role of the changesets action to validate, that totally makes sense as well.

Another alternative would be to keep #545 as the default behavior, but add an opt-in oidcAuth: true flag that enables validation? This would give users the simple path (current #545 behavior) by default, while adding validation.

If that doesn't seem to align with the project, I could consider splitting the validation functionality into a separate action for validation and debugging when needed.

I'd be happy to adjust whatever you think is needed.