vercel-labs/protected-vercel-deployments

Implantações Vercel protegidas

Use a identidade Vercel existente do chamador e um token OIDC de curta duração. Não desabilite a Proteção de Implantação, torne a implantação pública ou peça um segredo bypass estático primeiro.

Preview do mesmo projeto

Um token de desenvolvimento local para o projeto alvo pode acessar as implantações Preview protegidas desse projeto através da regra padrão de autoacesso do Trusted Sources. Nenhuma configuração de Trusted Sources é normalmente necessária.

Confirme a identidade local e a versão da CLI Vercel:

vc whoami
vc --version

Exija Vercel CLI 53.3.0 ou mais nova antes de executar vc project token. As versões 50.25.0 a 53.2.x escrevem o token em stderr, então a substituição de comando não captura nada e a credencial pode aparecer em logs. Se a versão instalada for mais antiga, pare e peça ao usuário para atualizá-la. Não tente capturar ou recuperar o token do stderr.

Defina o projeto alvo e o escopo explicitamente. Se eles não puderem ser inferidos com segurança, pergunte ao usuário. Em um diretório cujo link .vercel/project.json existente foi verificado em relação ao alvo, vc project token sem um nome de projeto também é válido. Não execute vc link apenas para obter um token OIDC: as versões atuais da CLI Vercel também puxam variáveis de desenvolvimento para .env.local ao vincular.

Crie uma sessão de navegador nomeada, gere um token OIDC de desenvolvimento com a CLI Vercel e injete-o sem imprimi-lo ou persistí-lo:

export AGENT_BROWSER_SESSION="$(agent-browser session id --scope worktree --prefix vercel-preview)"
export VERCEL_PREVIEW_URL="https://my-app.vercel.app"
export VERCEL_PROJECT="my-app"
export VERCEL_SCOPE="my-team"

(
  TOKEN="$(vc project token "$VERCEL_PROJECT" --scope "$VERCEL_SCOPE")"
  test -n "$TOKEN"
  agent-browser open "$VERCEL_PREVIEW_URL" --headers \
    "{\"x-vercel-trusted-oidc-idp-token\":\"$TOKEN\"}"
)

agent-browser snapshot -i

Continue o fluxo de trabalho normal nessa mesma sessão. O cabeçalho é escopo para a origem alvo e se aplica ao documento, scripts, estilos, fontes e requisições na página. Se a sessão do navegador for fechada ou reiniciada, repita o comando open autenticado.

Nunca imprima o token, cole-o no código-fonte ou salve-o em um arquivo de ambiente.

Outros ambientes e chamadores

A configuração de Trusted Sources é necessária quando:

• um token de desenvolvimento local precisa alcançar uma implantação de Produção protegida;
• o chamador pertence a outro projeto ou time Vercel;
• as regras de autoacesso do projeto alvo foram personalizadas; ou
• a Vercel retorna TRUSTED_SOURCES_ENVIRONMENT_MISMATCH.

Não há CLI Vercel ou API REST pública suportada para editar regras de Trusted Sources. Um humano autorizado deve abrir Settings → Deployment Protection → Trusted Sources do projeto alvo e adicionar apenas o mapeamento de chamador e ambiente necessário. Um token local tem o ambiente development, então o acesso à Produção protegida requer development para production.

Pare e repasse a regra exata para o humano. Não use automação de navegador para alterar o controle de acesso e não amplie mapeamentos de ambiente não relacionados. Repita o open autenticado depois que o humano confirmar que a regra foi salva.

Limites de intervenção humana

O caminho de Preview para desenvolvimento do mesmo projeto deve ser executado sem intervenção humana quando a CLI Vercel já está autenticada e o projeto alvo e escopo são conhecidos. Um humano é necessário apenas quando:

• a CLI Vercel não tem identidade autenticada e nenhum VERCEL_TOKEN existente; vc login interativo requer o usuário;
• a CLI Vercel instalada é mais antiga que 53.3.0 e deve ser atualizada antes da geração do token;
• o projeto alvo ou escopo correto não pode ser inferido com segurança para a geração do token;
• uma regra de Trusted Sources deve ser adicionada ou alterada; o dashboard é a única superfície de gerenciamento suportada, e isso altera o controle de acesso;
• o Acesso Seguro de Backend com Federação OIDC foi desabilitado no projeto chamador e deve ser reabilitado em Settings → Security; ou
• o fallback de segredo estático deve ser habilitado ou rotacionado e o agente precisa de autorização explícita para essa alteração de controle de acesso. Após aprovação, o agente pode usar vc project protection em vez de exigir interação com o dashboard.

O agente pode diagnosticar cada caso e indicar a ação exata necessária, depois continuar após o usuário confirmar a conclusão.

Use o cabeçalho correto

Envie o token emitido pela Vercel como:

x-vercel-trusted-oidc-idp-token: <VERCEL_OIDC_TOKEN>

Não substitua por x-vercel-oidc-token. Esse cabeçalho carrega a identidade da carga de trabalho para uma Function Vercel; ele não autentica uma requisição de entrada através da Proteção de Implantação.

Diagnosticar falhas

• Redirecionamento para vercel.com/login: A Proteção de Implantação não aceitou a requisição.
• TRUSTED_SOURCES_ENVIRONMENT_MISMATCH: o token é válido, mas seu ambiente chamador não pode alcançar o ambiente alvo.
• 401 ou 403 da aplicação após a proteção passar: depure a autenticação própria da aplicação separadamente.
• 404 da aplicação em uma rota propositalmente ausente: a requisição passou pela Proteção de Implantação e alcançou a aplicação.

Fallback de segredo estático

Use Protection Bypass for Automation apenas quando OIDC não for viável ou a ferramenta não puder enviar o cabeçalho Trusted Sources. Habilitá-lo ou rotacioná-lo altera o controle de acesso, portanto, obtenha autorização explícita primeiro. Crie um segredo dedicado para que possa ser rotacionado independentemente, mantenha-o em uma variável de ambiente e passe-o como cabeçalho:

vc project protection enable <project> --protection-bypass \
  --protection-bypass-secret "$VERCEL_AUTOMATION_BYPASS_SECRET"

agent-browser open "$VERCEL_PREVIEW_URL" --headers \
  "{\"x-vercel-protection-bypass\":\"$VERCEL_AUTOMATION_BYPASS_SECRET\",\"x-vercel-set-bypass-cookie\":\"true\"}"

A diretiva de cookie cria um cookie _vercel_jwt reutilizável. Trate o estado salvo do navegador contendo esse cookie como uma credencial.

Evite becos sem saída

• Não existe comando CLI vercel share. Links Compartilháveis são destinados a pessoas e não são o caminho de automação.
• vercel curl é útil para requisições HTTP, mas não pode renderizar e interagir com uma página.
• Exceções de Proteção de Implantação tornam o domínio público. Não as use apenas para desbloquear um agente.
• Não exponha tokens OIDC, segredos bypass, URLs autenticadas ou estado salvo em logs, capturas de tela, arquivos fonte ou saída visível ao usuário.