npm vai bloquear publish com token bypass-2FA: como migrar

Resposta rápida

Se o seu CI ainda usa NPM_TOKEN com permissão para ignorar 2FA e executa npm publish, planeje a migração antes de janeiro de 2027. O npm pretende retirar desses tokens a capacidade de publicar versões diretamente. A mudança anunciada não desativou os tokens existentes agora, mas esperar a primeira falha deixa o release sem margem para teste.

Prefira trusted publishing com OIDC quando o pipeline roda em um provedor compatível. Ele troca o token permanente por uma credencial curta vinculada ao workflow. Se OIDC ainda não atende o ambiente, crie um token Read and write (stage only), substitua npm publish por npm stage publish e exija que uma pessoa revise e aprove a versão com 2FA.

O que muda e quando

Desde 18 de setembro de 2026, o npm permite criar um token granular Read and write (stage only). Ele envia uma versão para revisão, mas o registro rejeita uma tentativa de npm publish feita com esse token, mesmo quando a opção de ignorar 2FA está configurada. A adoção é voluntária e não altera os tokens atuais neste momento.

O prazo anunciado é janeiro de 2027. A partir da transição planejada, tokens granulares bypass-2FA não poderão mais publicar diretamente. Eles ainda poderão ler pacotes privados e preparar uma publicação. O aviso se refere a tokens granulares do npm, não a GitHub PAT, token de GitHub App ou GITHUB_TOKEN.

Escolha entre OIDC e stage-only

Trusted publishing é o caminho preferível quando GitHub Actions usa runner hospedado pelo GitHub, GitLab CI/CD usa runner compartilhado do GitLab.com ou CircleCI usa a nuvem do serviço. O npm aceita a identidade OIDC do job e elimina o segredo de escrita duradouro. A configuração pode permitir npm publish direto ou somente npm stage publish.

Stage-only é a ponte para pipelines que ainda dependem de token, inclusive runners próprios que não são suportados pelo trusted publishing no momento. Ele adiciona revisão humana sem conceder publicação direta ao CI. Em troca, cada versão precisa ser aprovada com 2FA e o segredo continua sendo uma credencial de escrita que deve ser protegida e rotacionada.

• Use OIDC se o provedor e o tipo de runner forem compatíveis e o workflow puder ser identificado com precisão.
• Use OIDC com npm stage publish se quiser credencial temporária e aprovação humana no mesmo fluxo.
• Use token stage-only quando OIDC ainda não estiver disponível no ambiente.
• Não mantenha npm publish com token bypass-2FA como solução de longo prazo.

Inventário seguro antes de alterar o pipeline

Localize o workflow de release e identifique apenas o nome do secret usado pelo npm, sem imprimir seu valor. Procure por npm publish, NODE_AUTH_TOKEN, NPM_TOKEN e arquivos .npmrc gerados durante o job. Confirme quem tem acesso ao pacote e onde a aprovação ficará registrada.

Trusted publishing requer npm CLI 11.5.1 ou mais recente e Node.js 22.14.0 ou mais recente. Staged publishing exige npm CLI 11.15.0 ou mais recente e o mesmo mínimo de Node.js. O pacote já precisa existir no registro, a conta do mantenedor precisa ter 2FA e a pessoa responsável pela aprovação precisa ter acesso de publicação.

• Registre o pacote, o workflow e o tipo de runner usados em cada release.
• Confira as versões com node --version e npm --version sem exibir variáveis de ambiente.
• Confirme que o pacote já existe no npm e que ao menos dois mantenedores conhecem o fluxo de aprovação.
• Faça a mudança primeiro em um pacote de menor risco ou em uma versão de teste válida.
• Defina como reverter o workflow sem reativar um token já exposto ou revogado.

Como migrar para trusted publishing com OIDC

Nas configurações do pacote no npmjs.com, abra Trusted Publisher e escolha o provedor. Para GitHub Actions, informe organização ou usuário, repositório e somente o nome do arquivo do workflow, com extensão .yml ou .yaml. O arquivo precisa existir em .github/workflows. Um environment é opcional e pode adicionar aprovação ou restrições do GitHub.

No workflow, conceda id-token: write e contents: read. Use runner hospedado pelo GitHub, Node 22.14.0 ou mais recente e npm 11.5.1 ou mais recente. O npm CLI detecta o ambiente OIDC e troca a identidade por credencial temporária. Remova NODE_AUTH_TOKEN do job de publicação depois que um teste controlado confirmar o novo caminho.

• Cadastre o workflow exato como trusted publisher nas configurações do pacote.
• Escolha se a identidade poderá executar npm publish ou apenas npm stage publish.
• Adicione permissions com id-token: write e contents: read ao job de release.
• Atualize Node e npm para versões compatíveis e execute testes e build antes da publicação.
• Publique uma versão controlada, valide o pacote no registro e só então revogue o token antigo.

Como migrar para um token stage-only

Crie um token granular com Read and write (stage only) limitado aos pacotes necessários. Guarde-o no cofre de segredos do CI, substitua o token anterior e altere o comando final para npm stage publish. Uma tentativa de npm publish deve falhar com essa credencial; isso confirma que o pipeline perdeu a capacidade de liberar uma versão sem revisão.

O envio para staging não exige o código de 2FA. A aprovação exige. Liste versões com npm stage list, examine uma versão com npm stage view e, quando necessário, baixe o conteúdo com npm stage download. Depois de verificar pacote, versão, arquivos e provenance, um mantenedor publica com npm stage approve usando 2FA.

• Crie o token stage-only com o menor escopo de pacotes e prazo possível.
• Atualize o secret do CI sem registrar o valor em logs, commits ou artefatos.
• Troque npm publish por npm stage publish e execute uma release controlada.
• Revise a versão no npmjs.com ou pelos comandos npm stage list e npm stage view.
• Aprove com npm stage approve e 2FA somente depois da conferência.
• Revogue o token bypass-2FA antigo quando o novo fluxo estiver comprovado.

Por que a publicação ainda falha

Se npm publish falhar com o token stage-only, o bloqueio está funcionando: use npm stage publish. Se o comando stage não existir, atualize primeiro o npm CLI. Se o pacote for novo e nunca tiver sido publicado, staged publishing não se aplica; faça a criação inicial por um fluxo compatível e adote staging nas versões seguintes.

Falhas de OIDC costumam vir de runner próprio, nome de workflow diferente do cadastrado, repositório ou organização incorretos, ausência de id-token: write ou versão antiga do npm. Um erro de aprovação pode indicar 2FA ausente, sessão expirada ou falta de acesso de publicação. Antes de trocar permissões, confira também o npm Status para separar configuração local de incidente no registro.

Limites e cuidados de segurança

Stage-only não transforma o token em leitura. A documentação informa que ele ainda pode mover dist-tags e descontinuar versões, além de outras operações de escrita. Restrinja pacote, validade e acesso ao secret. Nunca teste com echo, debug de ambiente ou upload de arquivos que possam conter .npmrc.

OIDC reduz o risco de um segredo duradouro, mas não corrige um workflow comprometido. Restrinja gatilhos, permissões, actions externas e ambientes de release. Staging também não substitui revisão: compare o tarball, os scripts, a versão e a origem antes de aprovar. Uma pessoa que apenas confirma o botão mantém o mesmo risco lógico em outra etapa.

Plano de migração sem interromper releases

Mantenha o processo atual apenas durante uma janela curta e registrada. Prepare a alternativa, publique uma versão controlada, confirme instalação e integridade em um projeto isolado e acompanhe o primeiro ciclo completo. Não revogue a credencial anterior antes da validação, mas também não a deixe ativa depois que o novo fluxo estiver estável.

• Semana 1: inventarie pacotes, secrets, runners, versões e responsáveis.
• Semana 2: configure OIDC ou stage-only em um pacote de menor risco.
• Semana 3: teste staging, revisão, aprovação, instalação e recuperação de falha.
• Semana 4: migre os demais pacotes, revogue tokens antigos e registre o procedimento.
• Antes de janeiro de 2027: execute um teste de release sem qualquer token bypass-2FA disponível.

Próxima ação útil

Este guia foi verificado em 22 de setembro de 2026. Abra hoje o workflow de release, identifique se ele usa npm publish com NPM_TOKEN e confirme o tipo de runner. Se OIDC for compatível, cadastre o trusted publisher. Caso contrário, crie um token stage-only para um pacote existente e documente quem revisará a primeira versão.

Depois do teste, revogue o token bypass-2FA antigo, revise o histórico de logs para garantir que nenhum segredo apareceu e monitore o status oficial do npm durante a próxima publicação. Reavalie a documentação perto de janeiro de 2027, pois o cronograma e a cobertura de provedores podem mudar.

Fontes consultadas

Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.

• Stage-only npm tokens for safer automationGitHub Changelog
• Trusted publishing for npm packagesnpm Docs
• Staged publishing for npm packagesnpm Docs
• Restricting npm bypass-2FA granular access tokensGitHub Changelog
• npm Statusnpm