npm 收緊免 2FA token：自動發布要點揀 OIDC 定人手批准

iThome 報道指，npm 已經落實首階段限制：設定咗 Bypass 2FA 嘅 granular access token（GAT），而家唔可以再改動敏感帳戶、組織同套件設定。呢項安排早喺 2026 年 7 月 8 日預告過，7 月 31 日嘅公告只係確認首批限制正式生效，唔係突然推出嘅新政策。

今次封邊啲權限

受影響嘅操作包括建立或刪除 token、改套件存取權同 maintainer、修改 trusted publishing 設定，仲有管理組織、團隊成員同套件權限。以往 CI/CD 用嘅 GAT 如果洩漏，攻擊者除咗可以發布惡意版本，仲可能加新 maintainer、開另一枚 token，將一次洩漏變成長期控制。npm 而家要求呢批管理操作經網頁或 CLI 完成互動式 2FA，先截斷呢條擴權路線。

自動 npm publish 暫時未停。 GitHub 話下一階段先會收走 Bypass 2FA GAT 嘅直接發布能力，目標時間係 2027 年 1 月左右；呢個係官方 target，仍有機會調整。改動落實後，呢類 token 預計只可讀取私有 package，或者將版本送入 staged publishing，公開前要 maintainer 用 2FA 批准。

圖片：Wikimedia Commons — Tony Webster from Minneapolis, Minnesota, United States（CC BY 2.0）

先查清楚 secret 入面係乜

今次只針對 npm granular access token，而且要開咗 Bypass 2FA。GitHub personal access token、GitHub App token 同 Actions 入面嘅 GITHUB_TOKEN 都冇受今次改動影響。不過有個位好易睇漏：你可以將 npm GAT 存入 GitHub Actions secret，再叫佢做 NPM_TOKEN 或其他名；個 secret 容器冇事，入面嗰枚 npm token 仍然受限制。判斷時要睇認證資料本身，唔好淨係睇變數名。

路線一：OIDC 保留全自動發布

想保留 tag 一出、測試過關就自動公開 package，官方主推 trusted publishing。npm 會核對指定 CI/CD 平台、repository 同發布檔案，再用 OIDC 換取短期認證，唔使長期保存一枚有寫入權限嘅 npm token。GitHub Actions 要加入 id-token: write，npm 套件設定亦要填啱 repository 同發布檔名；轉好之後先試一次發布，確認成功先停用舊 token，會穩陣好多。

呢條路現時支援 GitHub-hosted Actions runner、GitLab.com shared runner 同 CircleCI cloud；self-hosted runner 暫時未支援。官方文件亦要求 npm CLI 11.5.1 或以上、Node.js 22.14.0 或以上，每個 package 同一時間只可設定一個 trusted publisher。私有 dependency 亦要另外處理：OIDC 負責發布，但 npm ci 下載私有 package 仍可能要一枚唯讀 token。

路線二：版本先暫存，再由人批准

如果套件影響面大、公司本身有 release approval，或者唔想有人盜用帳戶後一撳就公開新版本，可以改用 staged publishing。CI/CD 執行 npm stage publish，先將 package 放入暫存區；maintainer 睇過內容後，再喺 CLI 或 npm 網站用 2FA 批准。公開時間會多一個人手關卡，不過半夜誤發版本、release key 洩漏同惡意改動，都多一次截停機會。

Staged publishing 要 npm CLI 11.15.0 或以上、Node.js 22.14.0 或以上，帳戶亦要開 2FA；新 package 首次發布唔支援 staged，要已經存在於 registry。實際上兩條路亦可以疊埋用：以 OIDC 將 CI/CD 權限鎖成只准 stage，再交由 maintainer 批准。代價係每次 release 都有人值守，更新密密出嘅小型 library 未必受得落。

CI/CD 發布線自查清單

先搜尋 repository secrets、組織 secrets、.npmrc 同部署平台有冇 NPM_TOKEN、NODE_AUTH_TOKEN 或 npm registry 認證；再登入 npm 核對 token 類型、權限、到期日同 Bypass 2FA 狀態。跟住列出邊啲 job 會跑 npm publish、改 maintainer、改 package access 或管理團隊，亦要查 reusable workflow、手動 dispatch、monorepo 同 self-hosted runner，免得只改咗主線嗰份設定。

遷移時先揀全自動 OIDC，抑或 staged 加人手批准；升級 Node.js 同 npm CLI，再喺測試 package 或非關鍵版本試一次。確認 repository URL、發布檔名、OIDC permission 同私有 dependency 讀取都正常，先移除舊寫入 token。最後最好加 tag 保護、發布環境批准同定期權限盤點，尤其係多人共同維護嘅套件。

GitHub 仲未將 2027 年 1 月寫成不可更改嘅死線，但依賴 Bypass 2FA GAT 直接發布嘅團隊，唔應等到正式截停先改。先盤點、試通新認證，再撤走長期寫入 token，會少好多臨急修 release pipeline 嘅風險。

參考來源

• iThome — NPM限制可免除2FA的權杖管理權限，2027年1月再取消直接發布能力 — original report
• GitHub Changelog：Restricting npm bypass-2FA granular access tokens — 官方生效公告，列明受限制操作、不受影響嘅 GitHub token 類型同 2027 年目標。
• GitHub Changelog：npm install-time security and GAT bypass2fa deprecation — 原始預告，可確認政策早於 7 月初公布，今次唔係全新政策。
• npm Docs：Trusted publishing for npm packages — OIDC 支援平台、版本要求、GitHub Actions 權限、限制同遷移次序嘅官方文件。
• npm Docs：Staged publishing for npm packages — 分階段發布、2FA 批准、版本要求同新 package 限制嘅官方說明。

本文根據原文及公開資料整理；資料有出入時，以原文及官方資料為準。