On this page · 13 sections
- What ends in January 2027, and what has already changed
- Why the bee-js release changes the advice
- Which publish paths survive January 2027
- Path A: OIDC trusted publishing on GitHub Actions, GitLab and CircleCI
- Path B: stage-only tokens for Jenkins, self-hosted runners and self-managed GitLab
- The approval step: who presses the button
- Provenance: what you keep, what you lose, what it proves
- Decision table
- Worked example: a 120-person US and UK SaaS company
- US and UK notes
- Migration checklist
- How eCorpIT can help
- References
Summary. npm will remove the ability to publish new package versions directly with a granular access token in January 2027. No exact day has been announced; GitHub's changelog of 8 July 2026 says around January 2027. Treat any CI job that runs npm publish with an NPM_TOKEN secret as broken from 1 January. Two routes remain. OIDC trusted publishing works from GitHub-hosted Actions runners, GitLab.com shared runners and CircleCI cloud, needs npm CLI 11.5.1 and Node 22.14.0 or later, and can still be allowed to publish directly. Everywhere else, including Jenkins and self-hosted runners, a stage-only token runs npm stage publish (npm CLI 11.15.0 or later) and a maintainer approves each version with 2FA. New trusted-publisher configurations expire if unused for 48 hours. The 9 November hijack of @ethersphere/bee-js went out through trusted publishing with genuine provenance and stayed live for about 75 minutes. Our advice: stage-only permission even on OIDC, a stage-only token everywhere else, and a named approver rota before 31 December.
About this article. This is for maintainers, release engineers and platform teams who publish npm packages from CI. We checked every date, command, version and limit against npm's documentation, the GitHub Changelog, the npm registry, the GitHub Advisory Database, the StepSecurity and Socket incident reports, and US and UK government texts on 21 November 2026. npm changes these controls often, so re-check before you rely on them; this is not legal or compliance advice, and no vendor paid for inclusion. Researched with AI assistance and checked against the primary sources listed in the references.
What ends in January 2027, and what has already changed
npm's access-token page says bypass-2FA tokens with direct-publish access are being deprecated and that publishing new versions directly with a granular access token will be removed in January 2027. It tells you to move automation to a Read and write (stage only) token and the staging workflow. The page was last edited on 10 September 2026.
GitHub's changelog of 8 July 2026, which made npm v12 generally available, is narrower: 2FA-bypass tokens lose direct publishing around January 2027 and keep only reading private packages and staging a publish that a person approves with 2FA. The ways forward are trusted publishing with OIDC or staged publishing with human approval.
A token without bypass already meets a 2FA prompt on npm publish, which CI cannot answer, so plan on the docs' broader wording: from January, no granular token publishes directly from automation. We found no exact day in npm's docs or the GitHub Changelog as of 21 November.
The timeline draws on those pages, npm's trusted-publishing guide and three more changelog posts.
| Date | Change | Source |
|---|---|---|
| November 2025 | Legacy access tokens removed; only granular tokens remain | npm docs |
| 20 May 2026 | Trusted-publisher configurations created before this date allow npm publish only | npm docs |
| 22 May 2026 | Staged publishing generally available, npm CLI 11.15.0 or later | GitHub Changelog |
| 8 July 2026 | npm v12 generally available; bypass-2FA deprecation announced | GitHub Changelog |
| August 2026 | Bypass-2FA tokens lose account, token, maintainer and organisation actions | npm docs |
| 3 September 2026 | New trusted-publisher configurations allow npm stage publish by default | npm docs |
| 2 October 2026 | Unvalidated trusted-publisher configurations expire after 48 hours; issue_comment tokens rejected; staging can create new packages | GitHub Changelog |
| January 2027 | Direct publishing with granular access tokens removed | npm docs |
The practical deadline is earlier. If your team freezes changes in late December, you want one real release through the new path before then. We suggest Friday 11 December 2026 as the date every pipeline is migrated and tested.
Why the bee-js release changes the advice
Swapping a token for trusted publishing is only half the job, as the 9 November compromise of @ethersphere/bee-js shows. GitHub's advisory lists version 13.3.0 as malware and says any machine that installed it should be treated as fully compromised.
StepSecurity reports that the malicious commit was made under the project's bee-worker release identity at 23:59:54 UTC on 8 November, and the v13.3.0 GitHub release followed under the same identity at 00:06:01 UTC on 9 November. That release started the existing workflow, which published 13.3.0 to npm at 00:09:50 UTC through GitHub Actions trusted publishing. Socket says npm removed it at 01:24:58 UTC, about 75 minutes later, and that bee-js had used trusted publishing, with no long-lived npm token, since January 2026.
Three details matter for this migration:
- No npm token was needed. In Socket's reading, the project's own workflow, running its own code from the attacker's tag, published the attacker's commit.
- The provenance was real. Socket verified the attestation end to end; it had the same shape as the clean 13.2.0 release, so provenance alone could not tell them apart.
- Nothing paused the publish. The
publishenvironment had no required reviewers, and the deployment went from creation to success in 73 seconds. A stage-only trusted publisher would have held 13.3.0 until a maintainer approved it with 2FA.
The reports differ on one point: StepSecurity describes an unsigned direct commit to the upcoming branch, while Socket says the commit belonged to no branch and never went through a pull request. How the credentials were stolen has not been established. Either way, the January cut-off closes the token path but does nothing about a trusted publisher still allowed to run npm publish straight to latest.
Which publish paths survive January 2027
Putting the token table in npm's stage reference next to the access-token page gives this picture.
| Credential in CI | npm publish today | npm publish after January 2027 | npm stage publish | Provenance |
|---|---|---|---|---|
| Granular token, publish and stage, Bypass 2FA on | Publishes if package publishing access allows | Removed | Can stage | Only with the provenance flag on supported cloud CI |
| Granular token without bypass | 2FA prompt, so CI fails | Removed, per the docs wording | Can stage | As above |
| Granular token, stage only | Rejected with E_STAGE_REQUIRED | Same | Can stage | As above |
| Trusted publishing (OIDC) | Publishes if direct publish is allowed | Not named in the January removal | Can stage if allowed | Automatic on GitHub Actions and GitLab for a public repo and public package |
| Maintainer's interactive session | 2FA prompt | Unchanged | Can stage | None from a laptop |
A stage-only token is not a general security boundary: it can still deprecate versions and move dist-tags, so guard it like any other secret. And the January removal, as npm words it, covers granular access tokens only, so a trust relationship that allows direct publish can still ship without a human.
Path A: OIDC trusted publishing on GitHub Actions, GitLab and CircleCI
npm supports trusted publishing from GitHub Actions on GitHub-hosted runners, GitLab CI/CD on GitLab.com shared runners, and CircleCI cloud. Self-hosted runners are not supported; npm says support is planned. Each package can have up to 10 trusted publishers.
Each trusted publisher binds identity fields: repository and workflow file for GitHub, project and CI file path for GitLab, organisation, project and pipeline IDs for CircleCI. Its allowed-actions setting decides whether the workflow may also run npm publish or npm dist-tag; npm stage publish is always allowed. Configurations created before 20 May 2026 were set to npm publish only, so check older ones. Dist-tag management over OIDC needs npm CLI 11.21.0 or 12.2.0 or later.
For many packages the CLI is faster. npm trust needs npm 11.15.0 or later and account 2FA, and refuses bypass-2FA tokens.
# GitHub Actions: stage-only trust for one package
npm trust github @acme/ui-kit --file release.yml --repo acme/ui-kit \
--env npm-release --allow-stage-publish --yes
# GitLab.com: stage-only trust
npm trust gitlab @acme/sdk --file .gitlab-ci.yml \
--project acme/platform/sdk --allow-stage-publish --yes
# Check what is configured
npm trust list @acme/ui-kit
npm's bulk method is a loop with --yes: after the first 2FA challenge you can skip 2FA for five minutes, which with a two-second sleep between calls covers about 80 packages. One conflict: the npm trust page (edited 2 June 2026) allows one configuration per package, the trusted-publishing guide (edited 6 October 2026) allows 10. Add any second configuration on the website.
GitHub Actions workflow
Keep id-token: write on the publishing job only, and refuse release commits that are not on your protected branch, the check Socket says bee-js lacked.
name: release
on:
release:
types: [published]
permissions:
contents: read
jobs:
stage:
runs-on: ubuntu-latest
environment: npm-release
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- name: Refuse release commits that are not on main
run: git merge-base --is-ancestor "$GITHUB_SHA" origin/main
- uses: actions/setup-node@v6
with:
node-version: '24'
registry-url: 'https://registry.npmjs.org'
package-manager-cache: false
- run: npm ci
- run: npm test
- run: npm stage publish
The branch check only helps if direct pushes to main are blocked. npm's example pins v6 of actions/checkout and actions/setup-node; both now have v7 releases, so pin the major you have tested, ideally by commit SHA.
The traps, per npm's docs: the workflow filename must match exactly, including .yml; repository.url in package.json must match the repository; and with workflow_call, validation checks the calling workflow's name and both workflows need id-token: write. npm does not check a configuration when you save it, so a mismatch surfaces as ENEEDAUTH at publish time. Since 2 October, npm also rejects trusted-publishing tokens from issue_comment events, alongside pull_request_target, so publish from push, release or workflow_dispatch. GitHub's separate default block on pull_request_target in public repositories starts on 2 December 2026, as our pull_request_target guide explains.
GitLab CI/CD job
GitLab needs an ID token with the npm audience, plus a Sigstore token for provenance.
publish:
stage: publish
image: node:24
id_tokens:
NPM_ID_TOKEN:
aud: "npm:registry.npmjs.org"
SIGSTORE_ID_TOKEN:
aud: sigstore
script:
- npm ci
- npm run build --if-present
- npm stage publish
only:
- tags
This works on GitLab.com shared runners only. Self-managed GitLab and GitLab.com projects on their own runners belong in Path B.
CircleCI job
CircleCI fetches an OIDC token in the job, and the npm CLI exchanges it for a short-lived publish token.
export NPM_ID_TOKEN=$(circleci run oidc get --claims '{"aud": "npm:registry.npmjs.org"}')
npm stage publish
npm does not generate provenance for CircleCI trusted publishing, so these packages carry no attestation.
The 48-hour validation window
Since 2 October, a new trusted-publisher configuration must complete its first successful publish within 48 hours, which binds it to the repository's immutable identity. An expired one cannot be used or edited; delete it and create another. GitHub says this limits the risk of trusting a repository name that later changes hands. Neither page says whether a staged publish awaiting approval counts, so test the full cycle on one package first, and do not create trust relationships in bulk on a Friday unless you can push a pre-release before Sunday.
Path B: stage-only tokens for Jenkins, self-hosted runners and self-managed GitLab
Outside the three supported providers, staging with a granular token is the only automated route left: Jenkins, Azure Pipelines, Bitbucket Pipelines, TeamCity, Buildkite, self-hosted Actions runners and self-managed GitLab.
Create the token with Read and write (stage only) on specific packages or scopes, an expiry date and an IP range limited to your CI egress. Leave Bypass 2FA off, because staging never prompts for 2FA. One token covers up to 50 packages or scopes. Store it in the CI credential store and change one command.
# .npmrc in the CI workspace
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
# Jenkins, Azure Pipelines, Bitbucket or self-hosted runner step
npm stage publish --tag latest
A leftover npm publish fails with E_STAGE_REQUIRED, the error to search for in January build logs. The staged tag cannot be changed, so a wrong tag means npm stage reject and a fresh stage, and pre-release versions need an explicit --tag. Since 2 October, npm stage publish can also create a new package; npm publishes a public 0.0.0-stage placeholder and keeps the real version private until a maintainer approves it.
Be careful with the package setting that disallows tokens: npm's docs say granular access tokens cannot be used under it, whatever their bypass flag, with no exception for staging, so leave token-staged packages on the default or test first. Self-hosted runners also give no provenance, because npm requires a cloud-hosted GitHub Actions or GitLab runner; if consumers want it, move only the release job to a hosted runner.
The approval step: who presses the button
Staging moves the risk decision from CI to a person, so approval needs an owner. OIDC tokens cannot approve: listing, viewing, approving and rejecting stages need interactive authentication on the CLI or npmjs.com.
npm stage list @acme/ui-kit
npm stage view <stage-id>
npm stage download <stage-id> # inspect the tarball
npm stage approve <stage-id> --otp 123456
On npmjs.com, the Staged Packages tab shows each version's dist-tag, publisher and SHASUM. Batch approval handles up to 100 versions with one 2FA challenge, one version per package, and npm says it is still rolling out.
Write down four rules before January:
- Who approves. At least two maintainers per package with 2FA, so a holiday does not block a hotfix.
- What they check. Version, dist-tag and publisher in
npm stage view, a diff ofpackage.jsonscripts against the last release, and whether the commit came from a merged pull request.
- How fast. For example, within four working hours, covering US Eastern and UK hours if maintainers span the Atlantic.
- Emergencies. A maintainer can still publish interactively with 2FA from a trusted device.
Once trusted publishing works for a package, npm recommends setting it to Require two-factor authentication and disallow tokens and revoking old automation tokens; that setting does not affect trusted publishers.
Provenance: what you keep, what you lose, what it proves
npm generates provenance automatically for trusted publishing from GitHub Actions or GitLab CI/CD when both the repository and the package are public, with no flag needed. Private repositories and CircleCI publishes get none. npm stage publish also accepts --provenance for token-based publishes from supported cloud CI.
npm's own docs say established provenance does not mean a package is free of malicious code; it gives a verifiable link to source and build instructions that you still have to judge. keyv shipped with valid GitHub Actions provenance in August, as our provenance and cooldown guide explains, and bee-js did the same in November. Provenance tells a consumer which repository, workflow and commit produced a tarball, which helps incident response. It is not a review. Consumers can verify attestations with npm audit signatures; publishers should pair provenance with protected release branches, a branch check and human approval for latest. Our npm supply-chain hardening article covers the consumer-side controls.
Decision table
| Choose | If |
|---|---|
| OIDC trusted publishing, stage only | Your release job runs on GitHub-hosted runners, GitLab.com shared runners or CircleCI cloud, and you can staff approvals within a working day |
| OIDC trusted publishing, direct publish allowed | You ship frequent canary or nightly builds to a non-latest tag, and you add required environment reviewers, protected tags and a branch check to reduce the bee-js risk |
| Stage-only granular token | You run Jenkins, Azure Pipelines, Bitbucket, self-hosted runners or self-managed GitLab, or cannot move the release job to a hosted runner |
| Manual publish with 2FA | A package ships a few times a year and automation would cost more than it saves |
| Move the release job to a hosted runner | You need provenance for public packages but build on self-hosted infrastructure today |
Avoid splitting one package across two release paths without a reason. Every extra trusted publisher or token is one more way to ship.
Worked example: a 120-person US and UK SaaS company
This example uses our planning assumptions, not measured data, and no vendor prices. The company has engineers in Boston and Manchester and publishes 30 npm packages: 20 public packages released from GitHub Actions, 6 private packages released from GitHub Actions in private repositories, and 4 packages built on a self-managed GitLab instance. It ships about 80 versions a month. Engineering time is costed at an assumed loaded rate of $110 an hour for the US team or £80 an hour for the UK team.
One-off migration
26 packages to OIDC trusted publishing 26 x 0.5 h = 13.0 h
4 packages to stage-only tokens 4 x 1.0 h = 4.0 h
12 release workflows edited and tested 12 x 1.5 h = 18.0 h
Approval runbook, rota and dry runs = 6.0 h
Total = 41.0 h
US team: 41 x $110 = $4,510 UK team: 41 x £80 = £3,280
Ongoing approvals (batched twice a week)
9 sessions a month x 15 minutes = 2.25 h
4 major releases a month x 30 minutes of review = 2.0 h
Total = 4.25 h a month
US team: 4.25 x $110 = $467.50 UK team: 4.25 x £80 = £340
The one-off cost is about a week of one engineer's time; the recurring half-day a month buys a human check on every version that reaches users. The 10 private-repository and GitLab packages (6 plus 4) get no provenance either way. Doing nothing is not free: from January, any package still on an NPM_TOKEN stops releasing until someone fixes it under pressure.
US and UK notes
United States. OMB memo M-26-05 of 23 January 2026 rescinded M-22-18 and M-23-16, the memos that made software producers selling to federal agencies attest to secure development practices. Agencies may still choose to use the Secure Software Development Attestation Form, which CISA released on 11 March 2024 and has since archived, and may ask for SBOMs by contract. The form is now an agency-by-agency request, not a blanket rule. Where a buyer still asks, short-lived OIDC credentials, a per-release approval record and provenance attestations are practical evidence, so keep the approval history and CI logs.
United Kingdom. The government's voluntary Software Security Code of Practice, co-designed with the NCSC and updated on 15 January 2026, sets 14 principles across four themes. In its build-environment theme, principle 2.1 covers keeping unauthorised access out of the build environment and 2.2 covers controlling and logging changes to it. Removing long-lived publish tokens and logging each approval map directly to those two. The code also says buyers can cite its principles in supplier contracts, and it comes with a self-assessment form vendors can share.
Migration checklist
- Inventory every publish path by Friday 27 November. Search CI configs for
npm publish,NPM_TOKEN,NODE_AUTH_TOKENand release tools that call npm, such as semantic-release or changesets. List each package, its CI system, its runner type and who maintains it.
- List tokens. In each maintainer's npm account, record which granular tokens have write access and Bypass 2FA enabled.
- Upgrade the CLI. Staging needs npm 11.15.0 or later and Node 22.14.0 or later; plain trusted publishing needs npm 11.5.1. The current CLI is 12.2.3, released on 18 November 2026, and npm 12 itself declares Node 22.22.2 or later on the 22 line, 24.15.0 or later on the 24 line, or Node 26.
- Create trust relationships in small batches you can validate within 48 hours, with stage-only permission.
- Swap the publish command. Replace
npm publishwithnpm stage publishand push a pre-release through each path.
- Set up approvers, the rota and the review checklist above.
- Lock down by 11 December. On packages that publish through trusted publishing, select Require two-factor authentication and disallow tokens, then revoke old automation tokens. Leave token-staged packages on the default setting.
- Watch January builds for
E_STAGE_REQUIREDandENEEDAUTH, the two errors that point to a missed pipeline or a mismatched trust configuration.
Our TanStack trusted-publishing analysis goes deeper on isolating id-token: write, release caches and action pinning.
How eCorpIT can help
eCorpIT is a Gurugram-based technology organisation, founded in 2021, assessed at CMMI Level 5 and MSME certified, with senior-led engineering teams working across AWS, Microsoft and Google platforms. Our cybersecurity services team can inventory your npm publish paths, move release jobs to stage-only trusted publishing or stage-only tokens, and write the approval runbook your maintainers follow. Talk to us at /contact-us/.
Last updated: 21 November 2026.