Secure Your Npm Publishes: Migrate Before Dec 2025!

Hey everyone, let's talk about something super important for all you folks publishing packages to npm. We've got a ticking clock, and it's all about how we authenticate our npm publishes. The good ol' classic npm tokens are on their way out, with a hard expiration date of December 9, 2025. That might sound far off, but trust me, when it comes to infrastructure changes and potential publishing disruptions, that deadline will sneak up on us faster than a Monday morning.

The Urgent Deadline: Why Classic npm Tokens Are Expiring

Classic npm tokens are becoming a thing of the past, and it's for a very good reason: security. While convenient, these tokens are long-lived and, if compromised, can grant broad access to your npm packages. npm, like many other platform providers, is continuously enhancing its security posture to protect the open-source ecosystem. The current status is a big, flashing red ⚠️ Urgent sign: we are currently relying on these classic tokens for our npm publishing needs, and failing to migrate before December 9, 2025, will lead to significant publishing disruptions. Imagine trying to push an urgent bug fix or a new feature release only to find your CI/CD pipeline grinding to a halt because of an expired token! It's a nightmare scenario we definitely want to avoid. This isn't just a recommendation; it's a mandatory security upgrade that will ultimately make our software supply chain more resilient and secure. We're talking about adopting modern best practices that eliminate the risks associated with static, long-lived credentials. So, guys, this isn't just busywork; it's about protecting our work and ensuring smooth operations moving forward. Let's dig into the solutions and get this sorted out!

The Future of npm Publishing: Trusted Publishing (Our Top Pick!)

Alright, let's dive into the recommended solution: Trusted Publishing with GitHub Actions OIDC. This is, hands down, the best way to go for most of us, especially if your publishing workflow runs through GitHub Actions. Why is it our top pick, you ask? Well, it's all about eliminating the headache of token management and supercharging our security posture. With trusted publishing, you're essentially telling npm, "Hey, GitHub Actions is vouching for this publish, and you can trust it!" No more manually creating tokens, storing them as secrets, or remembering to rotate them every few months. It's a game-changer for security and operational efficiency. The magic behind this is OpenID Connect (OIDC), an authentication layer on top of OAuth 2.0. In simple terms, OIDC allows your GitHub Actions workflow to securely identify itself to npm without needing a long-lived npm secret. Instead, GitHub provides a short-lived, tamper-proof ID token to npm, which npm then verifies. If everything checks out, npm provides a temporary, scoped token just for that publishing job. This process significantly reduces the attack surface because there are no static credentials floating around that can be stolen or misused. This means better security, less manual intervention, and a more robust publishing pipeline. Plus, trusted publishing includes provenance statements, which provide verifiable information about how a package was built and published, adding another layer of trust and transparency to our releases. This is huge for supply chain security, letting consumers verify the origin of the packages they depend on. This shift isn't just about avoiding a deadline; it's about embracing a more secure and automated future for our npm packages.

What is Trusted Publishing and Why It's Awesome

Trusted publishing is a modern security feature that fundamentally changes how authentication works for npm package releases. Instead of relying on static, long-lived access tokens that you have to manage yourself, it leverages a mechanism called OpenID Connect (OIDC). Specifically, with GitHub Actions OIDC, your workflow itself securely authenticates with npm. This means the GitHub Action directly tells npm, "Hey, I'm jukasdrj/alexandria running the publish.yml workflow, and I'm authorized to publish this package." npm then verifies this claim using the OIDC ID token provided by GitHub. If the verification is successful, npm issues a temporary, highly-scoped token to your GitHub Actions runner, which is then used for the npm publish command. This token is short-lived, often only valid for the duration of the job, and is generated on the fly, making it incredibly difficult for attackers to intercept or reuse. This is a massive leap forward in security, guys! The benefits are numerous and compelling. First and foremost, you get no tokens to manage or rotate. Seriously, think about the cognitive load and potential for human error that this eliminates. No more scrambling to update secrets or dealing with expired tokens causing CI/CD failures. Second, it utilizes GitHub Actions OIDC for secure, temporary authentication, drastically reducing the risk of credential leaks. A long-lived token stored as an environment variable or secret is a juicy target for attackers; a token that exists for mere minutes and is tied to a specific job is far less appealing. Third, it offers better security because there are no long-lived credentials sitting around waiting to be compromised. Each publish action gets its own, unique, ephemeral credential. And finally, it enables automated publishing on release with an integrated, secure mechanism, streamlining our development and deployment workflows. This also comes with provenance statements, which means every package you publish will have verifiable metadata about its origin and build process, adding an invaluable layer of trust and transparency for anyone consuming your package. This really is the gold standard for secure, efficient npm publishing in a CI/CD environment.

Step-by-Step Guide for Setting Up Trusted Publishing

Alright, let's get down to the nitty-gritty of implementing trusted publishing. This process is straightforward but requires careful attention to detail to ensure everything is configured correctly. The goal here is to establish a secure link between our GitHub repository and npm, allowing our GitHub Actions workflows to publish packages without needing a manually managed npm token. First, we need to configure npm for Trusted Publishing. Head over to your package's access settings on npm.com. Specifically, for @ooheydrj/alexandria-worker, you'd navigate to https://www.npmjs.com/settings/~/packages/@ooheynerds/alexandria-worker/access. Here, you'll find an option to enable "Provenance and trusted publishing". Make sure this is checked! After enabling it, you'll need to configure the GitHub repository that's authorized to publish this package. For our case, this will be jukasdrj/alexandria. This step tells npm exactly which GitHub repository is allowed to trigger trusted publishes for this specific package. Then, you need to specify the workflow name that will perform the publishing. This is typically the path to your GitHub Actions workflow file, like .github/workflows/publish.yml. This granular control ensures that only specific workflows from authorized repositories can publish, adding another layer of security. Next up, we create our GitHub Actions Workflow. This is the YAML file that defines our publishing process. Create .github/workflows/publish.yml with the following content. Pay close attention to the permissions block, especially id-token: write. This is the crucial permission that allows your GitHub Actions workflow to request an OIDC ID token, which is essential for trusted publishing. Without this, your workflow won't be able to authenticate securely with npm. The setup-node action, when configured with registry-url: 'https://registry.npmjs.org' and when id-token: write is enabled in your workflow, can automatically fetch a temporary npm token via OIDC and set it as NODE_AUTH_TOKEN for subsequent steps. This means we don't need to manually pass secrets.NPM_TOKEN in this ideal tokenless setup. It's truly awesome!

name: Publish to npm

on:
  release:
    types: [published]
  workflow_dispatch:

permissions:
  contents: read
  id-token: write # Required for trusted publishing

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
          # This will automatically provision an npm token via OIDC if id-token: write is set
          # and make it available as NODE_AUTH_TOKEN
      
      - name: Install dependencies
        run: cd worker && npm ci
      
      - name: Publish to npm
        run: cd worker && npm publish --provenance --access public
        # NODE_AUTH_TOKEN is automatically set by actions/setup-node with OIDC
        # No need for secrets.NPM_TOKEN here in a true trusted publishing setup

Once the workflow is in place and the npm settings are updated, it's time to test publishing. The simplest way to do this is to create a test release on GitHub. This will trigger your publish.yml workflow. The workflow should then automatically publish your package to npm. After the workflow completes successfully, make sure to verify the package appears on npm and, crucially, that it displays the provenance badge. This badge is a visual confirmation that trusted publishing is working correctly and that your package's origin can be verified. This entire setup ensures that our npm publishing process is not only secure but also incredibly efficient, minimizing manual intervention and reducing the risk of human error.

The Alternative: Granular Access Tokens

While trusted publishing is our gold standard, we understand that sometimes it might not be immediately feasible or might not fit every single workflow. For those scenarios, or as a temporary measure, npm also offers granular access tokens. This is our alternative solution, and it's still a significant improvement over the expiring classic tokens, but it comes with its own set of responsibilities. Think of granular access tokens as highly specialized keys: they only open specific doors for a limited time. Unlike the broad access of classic tokens, granular tokens allow you to define precisely what actions they can perform (e.g., publish, read) and on which packages (e.g., just @ooheynerds/alexandria-worker). This level of specificity is a massive security upgrade because even if a granular token is compromised, the damage is contained. However, the biggest differentiator and a critical point to remember is their limited lifespan. These tokens are now limited to 90 days, and npm enforces 2FA (Two-Factor Authentication) by default when you create them. This means you'll need to be proactive about managing and rotating these tokens. Setting up reminders and having a clear process for rotation is absolutely essential to avoid publishing interruptions every three months. If you decide to go this route, consider integrating token rotation into your operational calendar. While not as hands-off as trusted publishing, granular tokens provide a robust and secure alternative for situations where direct OIDC integration might be challenging or for scenarios requiring more manual control over publishing. It's about finding the right balance between security, convenience, and your specific needs.

When to Consider Granular Tokens

Granular access tokens serve as a robust alternative when trusted publishing isn't feasible or when you require more fine-grained, manual control over your publishing process. There are several scenarios where opting for granular tokens makes perfect sense. For instance, if your CI/CD setup isn't GitHub Actions – perhaps you're using GitLab CI, Jenkins, or another platform that doesn't natively support npm's OIDC integration for trusted publishing as seamlessly – then granular access tokens become your go-to secure method. They provide a portable authentication mechanism that can be integrated into virtually any CI/CD environment. Another reason might be for manual publishing workflows or for specific automation tasks that are outside the scope of your primary GitHub Actions pipelines. Maybe you have a script that publishes a pre-release version from a local machine, or a custom tool that needs npm access. In these cases, a granular token allows you to grant just the necessary permissions without exposing broader access. Furthermore, if you're dealing with older projects or complex legacy systems where migrating to a full OIDC-based trusted publishing setup would be a significant undertaking, granular tokens offer a pragmatic, immediate security upgrade without a complete overhaul. They allow you to deprecate classic tokens and meet the security requirements within the given timeline, even if the long-term goal is still to move to trusted publishing. The key benefit here is the ability to scope down access significantly. You can create a token that only has permission to publish to a specific package (e.g., @ooheynerds/alexandria-worker) and nothing else. This dramatically reduces the blast radius if the token ever falls into the wrong hands. You can even restrict the token's usage to specific IP ranges, adding another layer of security, though for CI/CD, this often means allowing GitHub Actions IP ranges or