Dotenvx
Docs Ops
← back to blog Mot

Scott (Mot) Motte

Rotate NPM Tokens with Dotenvx Ops. Automatically.

NPM’s new short-lived tokens strengthen security, but they make rotation painful. Every 90 days (or sooner) you have to manually create a fresh token, set it in your CI, and make sure nothing breaks. 1

This was a real problem for us. We publish 64 npm packages, and rotating tokens across all of them by hand was not going to be sustainable. Every expiration meant touching dozens of pipelines and praying the next publish didn’t fail.

So we built a solution. Introducing Dotenvx Rotate - part of Dotenvx Ops.

How It Works

Install dotenvx-ops.

$ curl -sfS https://dotenvx.com/ops | sh

Run rotate npm connect to connect npm.

$ dotenvx-ops rotate npm connect

When prompted enter your npm username and password.

$ dotenvx-ops rotate npm connect
✔ npm username: USERNAME
✔ npm password: PASSWORD

This opens a local browser session, connecting your npm account.

IMPORTANT: Note that this is local only - this way we can bypass the need for storing your credentials.

Complete any 2FA steps manually.

On success, return to your CLI, and you will see a passcard created.

$ dotenvx-ops rotate npm connect
✔ npm username: USERNAME
✔ npm password: PASSWORD
✔ connected [https://ops.dotenvx.com/go/pas_1234..]

Dotenvx Passcards are special connectors allowing account access.

Next, use the passcard to rotate your npm token.

Rotate

Run rotate on the passcard.

$ dotenvx-ops rotate dotenvx://pas_1234..
⠏ rotating..

It takes 10-30 seconds. On success, it returns a Dotenvx Rotation Token (ROT).

$ dotenvx-ops rotate dotenvx://pas_1234..
✔ rotated [https://ops.dotenvx.com/go/pas_1234..]
⮕ next run [dotenvx-ops get dotenvx://rot_a2c4..]

Dotenvx Rotation Tokens (ROTs) are special tokens that can change value. You can think of them as proxy tokens.

Next, let’s get the value for it.

Get

Run get on the rotation token.

$ dotenvx-ops get dotenvx://rot_a2c4..
npm_d2cJ..

It returns your npm token. Cool!

Rotate Again

Run rotate on the passcard again.

$ dotenvx-ops rotate dotenvx://pas_1234..
✔ rotated [https://ops.dotenvx.com/go/pas_1234..]
⮕ next run [dotenvx-ops get dotenvx://rot_a2c4..]

And get the ROT again.

$ dotenvx-ops get dotenvx://rot_a2c4..
npm_cbGY..

The value changed. Way cool!

That’s the ROT at work. ROTs introduce a new key rotation primitive: the npm token rotates, the reference does not. This is useful for operations, especially CI/CD.

CI/CD

Previously, our CI/CD had npm publish with a hardcoded secrets.NPM_TOKEN:

npm:
  ...
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: '18.x'
        registry-url: 'https://registry.npmjs.org'
    - run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Step 1

We first replaced secrets.NPM_TOKEN with env.NODE_AUTH_TOKEN.

npm:
  ...
  runs-on: ubuntu-latest
  steps:
    ...
    - run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ env.NODE_AUTH_TOKEN }}

Step 2

Then we added a step to:

npm:
  ...
  runs-on: ubuntu-latest
  steps:
    ...
    - run: |
        curl -sfS https://dotenvx.sh/ops | sh
        echo "NODE_AUTH_TOKEN=$(dotenvx-ops get dotenvx://rot_a2c4 --token '${{ secrets.DOTENVX_OPS_TOKEN }}')" >> $GITHUB_ENV
    - run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ env.NODE_AUTH_TOKEN }}

Step 3

Last, we set DOTENVX_OPS_TOKEN in GitHub Actions Secrets (or GitLab CI, CircleCI, or wherever you run your automated npm publishing).

Tip: Find your DOTENVX_OPS_TOKEN on your Dotenvx Settings Page.

On your next CI run, it will inject the latest rotated NPM token and successfully publish your npm module(s).

Incredible!

Conclusion

Publishing now works indefinitely with rotating NPM tokens, powered by a new rotation primitive (ROTs) and passcard connectors.

  • NPM token leaked? Just rotate it - all your operations still work.
  • Employee left who knew the old token? Rotate it - all your operations still work.
  • NPM token should be rotated every N days for compliance? Put it on a schedule - all your operations still work.

This has worked really well for us. If it sounds useful, you can use it too. Sign up for Dotenvx Ops.

P.S. If you’re running this at enterprise scale with compliance requirements, scheduled rotation, or broader CI/CD concerns, please get in touch. We’d like to help.

1 Strengthening npm security: Important changes to authentication and token management

Subscribe via RSS or follow us @dotenvx 𝕏