npm has removed classic tokens, capped write tokens at 90 days and is now closing the last path for long-lived tokens to publish without a human. GitHub, which runs the npm registry, made these changes in stages from November 2025 in response to worms that spread by stealing publish tokens, and the next stage is targeted for January 2027. This guide is the dated runbook: what changed and when, which pipelines and people are affected, how to find every token still in use, and how to move each release path to trusted publishing or staged publishing without breaking it. It is for package maintainers, release engineers and platform teams who own npm publishing. Token hardening in depth is in the npm Tokens Security Guide and OIDC setup in the npm Trusted Publishing and Provenance Guide.
This is an independent guide from NHI Mgmt Group, based on npm's public documentation as of November 2026. It is not sponsored or reviewed by npm. Product features change, so confirm settings against npm's current documentation.
Key takeaways
- Classic tokens are gone for good. They were permanently revoked on 9 December 2025 and cannot be recreated, so any pipeline still holding one is already failing or quietly not publishing.
- Write tokens now expire. Granular tokens with write access are limited to 90 days and enforce 2FA unless "Bypass 2FA" is ticked, which turns rotation into a recurring operational task.
- Bypass-2FA tokens are being cut back. Since the change announced on 31 July 2026 they cannot manage tokens, maintainers or trusted publishing settings, and npm targets January 2027 to stop them publishing directly.
- Trusted publishing is the destination for CI. OIDC from GitHub Actions, GitLab CI/CD or CircleCI cloud replaces stored tokens and, for public repositories and packages on GitHub and GitLab, adds provenance automatically.
- Lock the door after you move. Once a package publishes through trusted publishing, set "Require two-factor authentication and disallow tokens" so a stolen token cannot publish it.
What is changing and why
Long-lived npm publish tokens stored in CI secrets and developer machines can republish every package their owner controls if stolen. The registry's changes remove standing publish credentials step by step, so that publishing needs either a workload identity (OIDC) or a human with 2FA.
| Credential | Status as of 8 November 2026 | Typical use |
|---|---|---|
| Classic token (automation, publish, read-only) | Revoked; cannot be created | None |
| Session token from npm login | Short-lived; announced as two hours, later extended to 12 hours according to an npm maintainer; 2FA enforced on publish | Interactive publishing from a workstation |
| Granular token, read-only | Supported; scoped to packages, scopes, orgs, optional CIDR list | Installing private packages in CI |
| Granular token, read and write | Maximum 90 days; 2FA required unless Bypass 2FA is set | Legacy CI publishing (being phased out for bypass tokens) |
| Granular token, read and write (stage only) | Supported since September 2026 | CI stages a release; a maintainer approves with 2FA |
| Trusted publisher (OIDC) | Supported for GitHub Actions, GitLab CI/CD, CircleCI cloud | CI publishing with no stored secret |
Official timeline and current status
Dates are from the GitHub changelog and npm documentation, checked on 8 November 2026. Future dates are targets and may move.
| Date | Change |
|---|---|
| 5 November 2025 | Classic token creation disabled on the website, CLI and API; existing write granular tokens capped at 90 days; new write granular tokens enforce 2FA by default |
| 19 November 2025 (planned) | Original date for revoking classic tokens; moved to 9 December |
| 9 December 2025 | All classic tokens permanently revoked; npm login issues short-lived session tokens; npm token create, list and revoke manage granular tokens from the CLI; 2FA on by default for new packages |
| 3 February 2026 | Existing granular tokens set to expire later were shortened to expire on this date |
| 31 July 2026 (announced) | Bypass-2FA granular tokens can no longer create or delete tokens, change package access, maintainers or trusted publishing configuration, or manage org and team membership; npm documentation describes this as applying from August 2026 |
| 18 September 2026 | Stage-only tokens and npm stage publish available (npm CLI 11.15.0 or later, Node.js 22.14.0 or later) |
| January 2027 (target) | Direct publishing through bypass-2FA tokens to be removed, leaving private package reads and staged publishes; npm's token documentation describes this as removal of direct publishing with granular tokens |
Not affected by any of this: GitHub personal access tokens, fine-grained tokens, GitHub App tokens and GITHUB_TOKEN in Actions.
Who and what is affected
- CI pipelines that publish with a stored token: every NPM_TOKEN secret with write access in GitHub, GitLab, Jenkins, Azure Pipelines or other systems. These now need rotation every 90 days at most and, if they bypass 2FA, lose direct publishing in January 2027.
- Self-hosted runners and other CI: as of November 2026 the npm docs describe trusted publishing for the three listed hosted CI providers, so for other pipelines use stage-only tokens or move the release job to a supported hosted runner.
- Automation that manages npm: scripts that create tokens, add maintainers or change access using a bypass token stopped working after the July 2026 change and now need an interactive 2FA step.
- Developers: local publishing works through npm login sessions with 2FA. Long-lived tokens in ~/.npmrc are gone or expiring, which is the intended outcome.
- Private package consumers: CI that installs private packages should use read-only granular tokens, which expire and need a rotation owner.
- Yarn v1 and v2 users: rely on a legacy login endpoint npm temporarily restored; treat it as at risk of removal.
Every one of these tokens is a non-human identity with an owner, scope and expiry. See the CI/CD Pipeline Identity Security Guide.
Finding affected systems and identities
- List tokens per account: each maintainer runs npm token list and reviews tokens on npmjs.com, noting permissions, packages, CIDR limits, bypass 2FA and expiry. An account can hold up to 1,000 granular tokens, so look for clutter.
- Search CI secret stores: enumerate secrets named NPM_TOKEN, NODE_AUTH_TOKEN or similar in every organisation and project, and map each to the workflow that uses it.
- Search code and images: scan repositories, container images and build caches for .npmrc files containing _authToken lines. See the Git Secret Scanning Guide.
- Check package settings: for each package record the Publishing access setting and any configured trusted publishers.
- Identify the release path: for each package, record who or what publishes it today (person, workflow, runner type) and which target path it will move to.
| Finding | Risk | Action |
|---|---|---|
| Write token with Bypass 2FA, all packages | Highest: stolen token publishes everything the user can | Replace with trusted publishing or stage-only, revoke |
| Write token scoped to one package, no CIDR | High | Migrate; meanwhile add CIDR and short expiry |
| Read-only token in CI | Medium: private code exposure | Keep, scope to needed packages, assign rotation owner |
| Package with default Publishing access | Bypass tokens can still publish until January 2027 | Set "disallow tokens" once trusted publishing works |
Migration options
| Option | Best for | Requirements | Trade-offs |
|---|---|---|---|
| Trusted publishing (OIDC) | Public or private packages built on GitHub-hosted runners, GitLab.com shared runners or CircleCI cloud | npm CLI 11.5.1+, Node 22.14.0+; GitHub id-token: write; GitLab id_tokens with audience npm:registry.npmjs.org | No self-hosted runners; up to 10 trusted publishers per package; connections cannot be edited, only deleted and recreated |
| Staged publishing with a stage-only token | Unsupported CI or self-hosted runners; teams wanting human release approval | npm CLI 11.15.0+, Node 22.14.0+, maintainer 2FA | A maintainer must approve each release; the token still exists and must be rotated |
| Interactive publish with 2FA | Small projects released by hand | npm login with 2FA | Depends on a person; no provenance from a workstation |
| Bypass-2FA write token | Temporary bridge only | Maximum 90 days | Loses direct publishing at the January 2027 target |
- Configuring trusted publishing: on npmjs.com, add the publisher with the GitHub owner, repository and workflow filename (including .yml), or the GitLab namespace, project and CI file path, plus an optional environment. Using a protected environment with required reviewers adds a human gate on the CI side. See the GitHub Actions OIDC Federation Hardening Guide.
- First publish deadline: a new trusted publisher configuration must complete a successful publish within two days or it expires, so schedule the change when a release is ready.
- Provenance: trusted publishing from a public repository for a public package on GitHub or GitLab generates provenance without the --provenance flag. It is not generated for private repositories or CircleCI. Consumers verify with npm audit signatures. Provenance shows where a package was built; it does not prove the code is safe.
- Stage-only tokens: create with npm token create and packages-and-scopes-permission set to read-write-stage-only, scoped to the package, with a CIDR range for your runners and a short expiry. The pipeline runs npm stage publish; a maintainer approves with 2FA.
Choosing a path by organisation size
- Single maintainer, few packages: trusted publishing from GitHub Actions or GitLab CI/CD is usually a one-afternoon change per package; for occasional releases, interactive publishing with 2FA is acceptable and needs no tokens at all.
- Open source project with several maintainers: trusted publishing tied to a protected environment, plus staged publishing where the project wants a second maintainer to approve releases. Remove maintainers who no longer release, since each one can still publish interactively.
- Enterprise with private registry mirrors and self-hosted runners: self-hosted runners rule out trusted publishing today, so plan stage-only tokens per package, CIDR-limited to runner egress addresses, with a named approver group. Track the January 2027 target as a programme milestone, not a per-team task.
Testing and rollback
- Pick a low-risk package first: configure trusted publishing and publish a prerelease (a dist-tag such as next) to confirm the OIDC exchange works.
- Keep the old token for one cycle: leave the existing token in place but unused, then revoke it after the first successful trusted publish. Rollback is reverting the workflow to the token step.
- Confirm provenance: check the package page shows provenance and run npm audit signatures in a consumer project.
- Tighten publishing access: set "Require two-factor authentication and disallow tokens". If a release then fails, the setting can be reverted while you fix the workflow.
- Revoke and verify: run npm token revoke on retired tokens, delete the CI secrets and confirm no workflow still references them.
Risks of doing nothing
- Release outages: expiring 90-day tokens and the January 2027 change will stop publishing pipelines, often discovered during an urgent security fix.
- Worm exposure: any write token on a developer laptop or CI secret store is exactly what worm-style malware harvests (MITRE ATT&CK T1552.001, T1528) before republishing packages (T1195.002).
- Reduced downstream assurance: without provenance, consumers cannot tie your releases to a source repository and workflow.
| Framework | Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev. 5 | IA-5, AC-6, SR-4 | Token lifetime and rotation; least-privilege token scope; provenance of released components |
| NIST CSF 2.0 | PR.AA-01, PR.AA-05 | Managed credentials for CI identities; least privilege for publish rights |
| MITRE ATT&CK v20 | T1195.002, T1528, T1552.001 | Supply chain compromise via stolen publish tokens |
Metrics to track: number of write tokens across maintainers (target zero for CI); share of packages publishing through trusted publishing; share of packages set to "disallow tokens"; median token age; share of releases with provenance; time from token exposure alert to revocation.
Practitioner checklist
- Run npm token list for every maintainer account and record purpose, scope, bypass 2FA and expiry.
- Inventory NPM_TOKEN style secrets across all CI systems and map each to a workflow.
- Scan repositories and images for .npmrc files with _authToken values and revoke anything found.
- Move each package on supported hosted runners to trusted publishing, with a protected CI environment.
- Move self-hosted or unsupported pipelines to stage-only tokens and staged publishing before January 2027.
- Rewrite any automation that manages tokens or maintainers to use an interactive 2FA step.
- Set "Require two-factor authentication and disallow tokens" on every migrated package.
- Keep read-only tokens for private installs scoped, CIDR-limited and on a rotation calendar.
- Verify provenance with npm audit signatures and record the January 2027 target in the release runbook.
Standards and references
- GitHub Changelog: npm security update, classic token creation disabled and granular token changes
- GitHub Changelog: npm classic tokens revoked, session-based auth and CLI token management
- GitHub Changelog: Restricting npm bypass-2FA granular access tokens
- GitHub Changelog: Stage-only npm tokens for safer automation
- npm Docs: Trusted publishing for npm packages
- npm Docs: About access tokens
- npm Docs: Requiring 2FA for package publishing and settings modification
- npm Docs: Generating provenance statements
Related NHI Mgmt Group resources: npm Tokens Security Guide · npm Trusted Publishing and Provenance Guide · CI/CD Pipeline Identity Security Guide