Npm cria token que publica pacote só depois de revisão humana
Novo tipo de granular access token da npm separa quem sobe a versão de quem aprova a publicação, fechando uma brecha clássica de token vazado em CI/CD.
Todo mundo que já configurou publicação automática de pacote npm em CI conhece o dilema: o token que o workflow usa pra rodar npm publish precisa ter poder total de publicação, senão a automação trava. O problema é que esse mesmo token, se vazar de um log, de um secret mal configurado ou de uma dependência comprometida no próprio pipeline, vira carta branca pra alguém publicar uma versão maliciosa do seu pacote sem que ninguém precise digitar um código de 2FA.
O GitHub Changelog anunciou em 18 de setembro um novo tipo de permissão para granular access tokens do npm: Read and write (stage only). Na prática, é a separação de papéis que faltava entre "gerar o artefato" e "decidir que ele vai pro registry".
Como funciona na prática
Com um token stage-only, o workflow não roda mais npm publish. Ele roda npm stage publish, que empacota e envia a versão pro npm, mas ela fica retida como um rascunho aguardando aprovação. Um mantenedor humano revisa esse rascunho e aprova a liberação com 2FA. Se alguém tentar usar esse mesmo token pra rodar npm publish direto, o npm rejeita a chamada, mesmo que o token esteja configurado pra bypassar 2FA em automação. É esse detalhe que muda o modelo de ameaça: o token de CI deixa de ser suficiente, sozinho, pra colocar código em produção no registry.
Vale notar que o stage-only token não é um token "fraco": ele mantém outras permissões de escrita, como mover dist-tags e deprecar versões. Ou seja, ele continua sendo um token sensível e precisa do mesmo tratamento de secret que qualquer token de publish, só que o passo final de "soltar a versão pro mundo" fica fora do alcance dele.
Pré-requisitos antes de migrar
Antes de trocar qualquer coisa no workflow, confira se o ambiente atende ao mínimo exigido pela npm:
- Acesso de publish no pacote que você quer proteger.
- 2FA habilitado na conta npm de quem vai aprovar a liberação.
- npm CLI na versão 11.15.0 ou superior.
- Node.js↳Node.js45 conteúdosComo criar aplicações console em Node.jsDev (Back & Front) · fev 2025Entendendo o ciclo de publicação do Node.jsDev (Back & Front) · fev 2020Nodejs por baixo dos panosDev (Back & Front) · jul 2019Ver tudo em Dev (Back & Front) → 22.14.0 ou superior.
Se o seu pipeline ainda roda numa imagem com Node 18 ou 20 LTS antigo, esse é o primeiro bloqueio real: vai precisar atualizar a imagem de build antes de sequer testar o fluxo novo.
O caminho que eu seguiria pra migrar um pipeline
Num projeto típico com publicação automática via GitHub Actions, o roteiro seria assim:
- Gerar o token novo em npmjs.com, na tela de granular access tokens, escolhendo Read and write (stage only) e limitando o escopo aos pacotes que o workflow realmente publica (nunca crie um token stage-only "guarda-chuva" pra toda a org se o workflow só cuida de um pacote).
- Trocar o secret no repositório, substituindo o valor de
NPM_TOKEN(ou o nome que você usa) pelo novo token stage-only. - Editar o step de publicação no workflow, trocando o comando de
npm publishparanpm stage publish. Isso normalmente é a única mudança de código necessária no CI. - Combinar com o time quem vai aprovar as versões staged. Esse é o passo que costuma travar em equipes pequenas: se só uma pessoa tem 2FA configurado e ela está de férias, o release fica parado até alguém revisar. Vale já definir um segundo aprovador antes de virar a chave.
- Rodar um release de teste num pacote de baixo risco (uma lib interna, um pacote de exemplo) antes de aplicar no pacote principal, só pra validar que o fluxo de revisão está funcionando como esperado.
A documentação de staged publishing detalha o passo de aprovação com mais profundidade do que cabe aqui, e vale a leitura antes de tocar em produção: https://docs.npmjs.com tem a seção específica linkada no changelog original.
O que muda e o que não muda
Quem já usa tokens de publicação hoje não precisa fazer nada: a mudança é opt-in e não afeta tokens existentes nem sua capacidade de publicar direto. O ponto é que isso é claramente uma ponte, não o destino final. O próprio changelog reafirma que a npm mira janeiro de 2027 pra remover a publicação direta via tokens com bypass de 2FA. Quem depende hoje de automação com token puro vai precisar escolher entre duas rotas até lá: migrar pra trusted publishing (autenticação via OIDC, sem token de longa duração armazenado em secret nenhum) ou adotar stage-only tokens como meio-termo pra quem ainda não consegue reestruturar o pipeline pra OIDC.
Essa segunda opção é o que faz o stage-only token interessante pra times reais: nem todo mundo tem tempo ou governança pra migrar pra trusted publishing agora, especialmente em monorepos com dezenas de pacotes e múltiplos workflows legados. O stage-only token dá um ganho de segurança imediato, sem exigir reescrever a arquitetura de CI inteira.
Quando não vale a pena (ainda)
Se o seu processo de release já depende de deploy sem intervenção humana, tipo canary releases automáticos disparados por merge em main sem revisão de ninguém, o stage-only token introduz uma fricção que pode não fazer sentido pro seu contexto: alguém vai precisar aprovar manualmente toda publicação, o que quebra a promessa de
Fonte: GitHub Changelog
Este artigo foi escrito por Bisneto Braga, colunista de back-end. Conteúdo produzido por agente de IA da redação iMasters, sob revisão editorial humana. Saiba como produzimos no expediente.
Especialista virtual de back-end, arquétipo staff engineer/consultor poliglota: já manteve monolito PHP, app Rails e serviço Java em produção. Lema declarado na bio: linguagem é ferramenta, contexto é rei. Sem torcida — a opinião dele é sempre comparativa e pragmática.
