O npm ganhou um tipo de token desenhado para automação de publicação: stage-only. Ele permite enviar uma nova versão para uma área de staging, mas não publicá-la diretamente no registry. A liberação exige que um maintainer revise o pacote e aprove com autenticação de dois fatores.
A separação ataca um problema conhecido de supply chain. Se a credencial do CI for roubada, o atacante não consegue transformar sozinho um tarball adulterado em versão pública. O pipeline prepara; uma pessoa autorizada confirma.
Como funciona o fluxo
# No CI, com token stage-only
npm stage publish
# Revisão pelo maintainer
npm stage list
npm stage view [email protected]
npm stage download [email protected]
# Aprovação exige 2FA
npm stage approve [email protected]Também é possível rejeitar a versão. O maintainer pode baixar exatamente o artefato preparado, inspecionar conteúdo e metadados e só então aprovar. Várias versões podem ficar em staging, mas uma combinação de pacote e versão continua única, e a tag escolhida faz parte do item preparado.
O token não é somente leitura
“Stage-only” descreve a restrição sobre publicar novas versões, não uma credencial incapaz de alterar qualquer coisa. A documentação alerta que esse token ainda pode ter outras permissões de escrita, como mudanças em dist-tags e depreciação. Escopo mínimo e proteção do secret continuam necessários.
O pacote também precisa já existir, o usuário aprovador deve ter acesso de publicação e sua conta precisa usar 2FA. O fluxo exige npm CLI 11.15.0 ou superior e Node.js 22.14.0 ou superior.
Trusted publishing continua relevante
Trusted publishing troca tokens persistentes por identidade federada do provedor de CI. O npm permite combinar esse mecanismo com permissão stage-only. É uma defesa melhor que guardar um token longo: reduz o valor de um secret vazado e mantém a aprovação humana antes da publicação.
O anúncio também aponta para janeiro de 2027 como alvo para remover publicação direta com tokens que ignoram 2FA. Equipes que ainda dependem desse caminho deveriam tratar staging ou trusted publishing como migração planejada, não esperar a desativação.
O que revisar no artefato
- Nome, versão e dist-tag pretendida.
- Arquivos incluídos pelo
filese pelo.npmignore. - Scripts de instalação e publicação.
- Dependências e alterações no lockfile.
- Proveniência, assinatura e correspondência com o commit aprovado.
A aprovação humana só adiciona valor se houver algo verificável. Para pacotes frequentes, automatize a comparação do tarball com o commit, gere SBOM ou proveniência e mostre o diff ao maintainer. O objetivo não é criar um botão cerimonial; é colocar uma barreira informada entre a credencial de build e o registry público.
Adoção gradual
O recurso é opt-in. Comece por um pacote de risco moderado, atualize o CLI do pipeline, conceda apenas a permissão necessária e documente quem aprova em férias ou incidentes. Meça o tempo entre staging e publicação para evitar que a segurança gere atalhos informais.
Stage-only não resolve toda a cadeia de software, mas remove uma capacidade poderosa do CI: publicar sem supervisão. Em um ecossistema no qual uma credencial comprometida pode alcançar milhões de instalações, essa divisão de responsabilidade é uma melhoria concreta.
