NPM Classic Token Revocation: Migrate To Trusted Publishing

by ADMIN 60 views

Hey guys! Big changes are happening with NPM (Node Package Manager) that you need to be aware of. They're revoking the old-school classic tokens, and if you're using them, you need to switch things up to avoid problems. This guide will walk you through the changes and how to migrate to Trusted Publishing, which is the recommended solution. Let's get started!

The Big News: Classic Tokens are Going Away!

So, what's the deal? NPM is beefing up its security, which is always a good thing. They've sent out emails letting everyone know about these changes. Here’s a quick recap of the important bits:

  • Phase 1 Changes: Started on October 13th, with new granular tokens that have a maximum lifespan of 90 days (7 days by default). Plus, new TOTP 2FA configurations are disabled (existing ones still work).
  • Early November: This is the big one. All classic tokens will be permanently revoked.

What does this mean for you? If you're using these classic tokens in any kind of automation – like your CI/CD pipelines (Continuous Integration/Continuous Deployment) or local development – you must migrate to granular access tokens before early November. Otherwise, you'll run into issues publishing your packages. So, this is a critical update, and you need to take action!

Why the change? Well, recent supply chain attacks have shown that these long-lived, easy-to-compromise tokens are a major security risk. NPM is taking steps to protect the ecosystem, and your packages, from potential threats. It's all about making things safer for everyone. Remember, security is a shared responsibility, and these changes are crucial.

Why Migrate to Trusted Publishing?

Because the old tokens are being revoked, you'll need a new way to get your packages published. The good news? Trusted Publishing is the recommended solution, and it's already supported by ioBroker tools. It's a secure way to automate your publishing process without relying on those soon-to-be-obsolete tokens. Think of it as a streamlined, secure handshake between your code and the NPM registry.

How to Migrate: Step-by-Step Guide to Trusted Publishing

Alright, let’s get into the nitty-gritty. Here's how to migrate to Trusted Publishing. This process involves a few steps to configure things properly:

1. Set Up Your NPM Trust Relationship

First, you need to set up the trust relationship in your NPM account. Follow these steps. They're pretty straightforward, but it is important to follow carefully so that everything works correctly.

  1. Log in to npmjs.com: Use the account that has publishing rights for your package. You'll need to be logged into the correct account to make the necessary changes.

  2. Navigate to your package page: Go to https://www.npmjs.com/package/YOUR-PACKAGE-NAME. Make sure to replace YOUR-PACKAGE-NAME with the actual name of your package. Then, click on the "Settings" tab.

  3. Configure Trusted Publishing: Scroll down to the "Publishing access" section. This is where the magic happens. Click on either "Automate publishing with GitHub Actions" or "Add trusted publisher."

    • Fill in the required info. This is where you connect your GitHub repository to NPM. Be super careful with these details – they're case-sensitive!

      • Repository owner: Enter your GitHub username or organization (e.g., ioBroker).
      • Repository name: Enter your adapter repository name (e.g., ioBroker.your-adapter).
      • Workflow name: This is crucial. Enter test-and-release.yml (or whatever the name of your release workflow is).
      • Environment: Leave this blank unless you have a specific environment setup. In most cases, it can remain empty.

    • IMPORTANT: Double-check everything. The information is case-sensitive, meaning capitalization matters. A small typo can cause the whole thing to fail, so make sure everything is exact!

  4. Save the Configuration: Once you've entered all the details, save the configuration. This action finalizes the link between your GitHub repository and NPM.

For more detailed instructions, you can check out the official documentation:

2. Adjust Your test-and-release.yml Workflow (If You Use the Standard Workflow)

If you're using the standard test-and-release.yml workflow, you'll need to make some changes to that file. Don’t worry; it's not too complicated.

  1. Open test-and-release.yml: Edit this file, either directly on GitHub or in your local development environment.

  2. Remove npm-token from the deploy section: Locate the job named 'deploy'. It should resemble this:

    # Deploys the final package to NPM
deploy:
  needs: [check-and-lint, adapter-tests]

  # Trigger this step only when a commit on any branch is tagged with a version number
  if: |
    contains(github.event.head_commit.message, '[skip ci]') == false &&
    github.event_name == 'push' &&
    startsWith(github.ref, 'refs/tags/v')

  runs-on: ubuntu-latest

  # Write permissions are required to create Github releases
  permissions:
    contents: write

  steps:
    - uses: ioBroker/testing-action-deploy@v1
      with:
        node-version: '20.x'
        # Uncomment the following line if your adapter cannot be installed using 'npm ci'
        # install-command: 'npm install'
        build: true
        npm-token: ${{ secrets.NPM_TOKEN }}
        github-token: ${{ secrets.GITHUB_TOKEN }}
    • Find the line that begins with npm-token:. Then remove this entire line or comment it out by adding a # at the beginning.
    • Locate the permissions: block. Add a line that says id-token: write. Make sure the indentation is correct to avoid YAML errors. If the permissions block is missing, add it, including the contents: write line, as shown in the example.

  3. Test Your Release and Deploy Workflow: Test the functionality by creating a test release. This is important to ensure everything is working correctly before you do a real release.

  4. Remove the NPM_TOKEN Secret: Once you've confirmed that everything works, you can remove the NPM_TOKEN secret from your GitHub repository settings. This step is optional, but it's good practice for security.

3. For Custom or Outdated Workflows

If you're not using the standard test-and-release.yml workflow, here’s what you should do:

  • Consider using the standard workflow. This is the easiest and most recommended path. The standard workflow is designed to work seamlessly with the ioBroker ecosystem and is regularly updated.
  • If you must keep your custom workflow, try to integrate the ioBroker/testing-action-deploy@v1 action. This will help you leverage some of the benefits of the standard workflow.
  • If you're going completely custom, follow the NPM Trusted Publishing documentation for guidance. Remember these points:
    • Workflow Name: Ensure you entered the correct workflow name when setting up Trusted Publishing.
    • NPM Version: Make sure you're using the latest npm release during deployment. Use npm install -g npm@latest in your workflow, close to your deploy command. Older versions of npm might cause issues. Avoid updating npm for the entire workflow.
    • No Token: Do not use a token or try to log in to npm directly. Use npm publish without any special authorization.

Upcoming: A Helping Hand

Great news! A tool is in development to help generate a PR (Pull Request) that will automatically add the required changes to your test-and-release.yml workflow. If you use the standard workflow, you might get a PR soon. But, if you don’t use the standard workflow, you will not receive a PR. Keep an eye out for that helpful update!

If you've got questions, please reach out to the development channels on Telegram or GitHub (invites are available at https://www.iobroker.dev) or leave a comment and mention me (@mcm1957). I'm here to help!

Thank you for maintaining your adapter! Let's work together to provide the best user experience. Your contribution is greatly appreciated. Remember, these changes are vital for the security of your packages and the health of the entire NPM ecosystem.

Best regards, ioBroker Check and Service Bot