vercel-labs/protected-vercel-deployments

Despliegues de Vercel protegidos

Usa la identidad Vercel existente del usuario y un token OIDC de corta duración. No deshabilites la Protección de Despliegue, hagas público el despliegue ni solicites un secreto de omisión estático primero.

Preview del mismo proyecto

Un token de desarrollo local para el proyecto objetivo puede acceder a los despliegues de Preview protegidos de ese proyecto a través de la regla de autoacceso de Fuentes Confiables predeterminada. Normalmente no se requiere configuración de Fuentes Confiables.

Confirma la identidad local y la versión de la CLI de Vercel:

vc whoami
vc --version

Requiere la CLI de Vercel 53.3.0 o superior antes de ejecutar vc project token. Las versiones 50.25.0 a 53.2.x escriben el token en stderr, por lo que la sustitución de comandos no captura nada y la credencial puede aparecer en los registros. Si la versión instalada es anterior, detente y pide al usuario que la actualice. No intentes capturar ni recuperar el token de stderr.

Establece el proyecto y el ámbito objetivo explícitamente. Si no se pueden inferir de forma segura, pregunta al usuario. En un directorio cuyo enlace existente .vercel/project.json haya sido verificado contra el objetivo, vc project token sin un nombre de proyecto también es válido. No ejecutes vc link solo para obtener un token OIDC: las versiones actuales de la CLI de Vercel también extraen variables de desarrollo a .env.local al enlazar.

Crea una sesión de navegador con nombre, genera un token OIDC de desarrollo con la CLI de Vercel, luego inyéctalo sin imprimirlo ni persistirlo:

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

Continúa el flujo de trabajo normal en esa misma sesión. La cabecera está limitada al origen objetivo y se aplica al documento, scripts, estilos, fuentes y solicitudes dentro de la página. Si la sesión del navegador se cierra o reinicia, repite el comando open autenticado.

Nunca imprimas el token, lo pegues en el código fuente ni lo guardes en un archivo de entorno.

Otros entornos y usuarios

Se necesita configuración de Fuentes Confiables cuando:

• un token de desarrollo local debe alcanzar un despliegue de Producción protegido;
• el usuario pertenece a otro proyecto o equipo de Vercel;
• las reglas de autoacceso del proyecto objetivo fueron personalizadas; o
• Vercel devuelve TRUSTED_SOURCES_ENVIRONMENT_MISMATCH.

No existe una CLI de Vercel o API REST pública compatible para editar reglas de Fuentes Confiables. Una persona autorizada debe abrir Configuración → Protección de Despliegue → Fuentes Confiables del proyecto objetivo y agregar solo la asignación de usuario y entorno requerida. Un token local tiene el entorno development, por lo que el acceso protegido a Producción requiere development a production.

Detente y pasa la regla exacta a la persona. No uses automatización del navegador para cambiar el control de acceso ni amplíes asignaciones de entorno no relacionadas. Reintenta el open autenticado después de que la persona confirme que la regla está guardada.

Límites de intervención humana

El flujo de desarrollo al Preview del mismo proyecto debe ejecutarse sin intervención humana cuando la CLI de Vercel ya está autenticada y el proyecto y ámbito objetivo son conocidos. Se necesita una persona solo cuando:

• la CLI de Vercel no tiene una identidad autenticada ni un VERCEL_TOKEN existente; vc login interactivo requiere al usuario;
• la CLI de Vercel instalada es anterior a 53.3.0 y debe actualizarse antes de generar el token;
• el proyecto o ámbito objetivo correcto no se puede inferir de forma segura para generar el token;
• se debe agregar o cambiar una regla de Fuentes Confiables; el panel es la única superficie de gestión compatible, y esto cambia el control de acceso;
• el Acceso Backend Seguro con Federación OIDC fue deshabilitado en el proyecto solicitante y debe volver a habilitarse en Configuración → Seguridad; o
• el respaldo de secreto estático debe habilitarse o rotarse y el agente necesita autorización explícita para ese cambio de control de acceso. Después de la aprobación, el agente puede usar vc project protection en lugar de requerir interacción con el panel.

El agente puede diagnosticar cada caso y indicar la acción exacta requerida, luego continuar después de que el usuario confirme su finalización.

Usa la cabecera correcta

Envía el token emitido por Vercel como:

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

No sustituyas x-vercel-oidc-token. Esa cabecera transporta la identidad de la carga de trabajo a una Función de Vercel; no autentica una solicitud entrante a través de la Protección de Despliegue.

Diagnosticar fallos

• Redirección a vercel.com/login: La Protección de Despliegue no aceptó la solicitud.
• TRUSTED_SOURCES_ENVIRONMENT_MISMATCH: el token es válido, pero su entorno solicitante no puede alcanzar el entorno objetivo.
• 401 o 403 de la aplicación después de pasar la protección: depura la autenticación propia de la aplicación por separado.
• 404 de la aplicación en una ruta deliberadamente inexistente: la solicitud pasó la Protección de Despliegue y llegó a la aplicación.

Respaldo de secreto estático

Usa Omisión de Protección para Automatización solo cuando OIDC no sea viable o la herramienta no pueda enviar la cabecera de Fuentes Confiables. Habilitarlo o rotarlo cambia el control de acceso, así que obtén autorización explícita primero. Crea un secreto dedicado para que pueda rotarse de forma independiente, mantenlo en una variable de entorno y pásalo como cabecera:

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\"}"

La directiva de cookie crea una cookie _vercel_jwt reutilizable. Trata el estado guardado del navegador que contenga esa cookie como una credencial.

Evita puntos muertos

• No existe un comando vercel share de la CLI. Los Enlaces Compartibles están destinados a personas y no son la ruta de automatización.
• vercel curl es útil para solicitudes HTTP, pero no puede renderizar ni interactuar con una página.
• Las Excepciones de Protección de Despliegue hacen público el dominio. No las uses solo para desbloquear a un agente.
• No expongas tokens OIDC, secretos de omisión, URLs autenticadas ni estado guardado en registros, capturas de pantalla, archivos fuente ni salida visible para el usuario.