mcpField
P
protected-vercel-deployments

protected-vercel-deployments

github.com/vercel-labs云与 DevOps44.8k41 次安装1 天前更新
代码仓库

关于 protected-vercel-deployments

protected-vercel-deployments 是用于访问受 Deployment Protection 保护的 Vercel 部署的技能。它说明如何使用调用者的 Vercel 身份和短期 OIDC 令牌，并明确授权边界及受控的静态密钥备用方案。

主要功能

  1. 01使用短期 Vercel OIDC 令牌
  2. 02通过浏览器会话访问受保护的预览部署
  3. 03诊断保护机制和环境错误
  4. 04明确需要人工批准的边界
  5. 05在获授权时使用静态密钥备用方案

适用场景

  1. 01打开同一项目受保护的 Preview
  2. 02诊断 Trusted Sources 环境不匹配
  3. 03交由人工修改所需访问规则
  4. 04OIDC 不适用时使用绕过保护

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vercel-labs/agent-browser --skill protected-vercel-deployments

安装后在 Claude Code 中输入/protected-vercel-deployments确认已加载。

详细介绍

受保护的 Vercel 部署

使用调用方现有的 Vercel 身份和短期 OIDC 令牌。不要禁用 Deployment Protection、将部署设为公开，也不要一开始就索要静态绕过密钥。

同一项目的预览环境

目标项目的本地开发令牌可以通过默认的 Trusted Sources 自访问规则访问该项目受保护的 Preview 部署。通常无需配置 Trusted Sources。

确认本地身份和 Vercel CLI 版本：

vc whoami
vc --version

运行 vc project token 前，要求 Vercel CLI 版本为 53.3.0 或更高。50.25.0 到 53.2.x 版本会将令牌写入 stderr，因此命令替换不会捕获任何内容，而且凭据可能出现在日志中。如果安装的版本较旧，请停止并要求用户升级。不要尝试从 stderr 捕获或恢复令牌。

明确设置目标项目和范围。如果无法安全推断，请询问用户。在现有 .vercel/project.json 链接已确认指向目标项目的目录中，不带项目名称运行 vc project token 也有效。不要仅为获取 OIDC 令牌而运行 vc link：当前版本的 Vercel CLI 在链接时也会将开发变量写入 .env.local。

创建一个具名浏览器会话，使用 Vercel CLI 签发开发 OIDC 令牌，然后注入该令牌，不要打印或持久化：

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

在同一会话中继续正常工作流。该标头限定于目标源站，并适用于文档、脚本、样式、字体和页面内请求。如果浏览器会话已关闭或重启，请重复经过身份验证的 open 命令。

绝不要打印令牌、将其粘贴到源代码中，或将其保存到环境文件中。

其他环境和调用方

在以下情况下需要配置 Trusted Sources：

  • 本地开发令牌必须访问受保护的 Production 部署；
  • 调用方属于另一个 Vercel 项目或团队；
  • 目标项目的自访问规则已自定义；或
  • Vercel 返回 TRUSTED_SOURCES_ENVIRONMENT_MISMATCH。

Vercel CLI 或公开 REST API 均不支持编辑 Trusted Sources 规则。必须由获授权的人员打开目标项目的 Settings → Deployment Protection → Trusted Sources，并仅添加所需的调用方和环境映射。本地令牌的环境为 development，因此访问受保护的 Production 部署需要将 development 映射到 production。

停止操作，并将确切的规则交由人员处理。不要使用浏览器自动化更改访问控制，也不要扩大无关的环境映射。人员确认规则已保存后，重试经过身份验证的 open。

需要人员介入的情况

只要 Vercel CLI 已完成身份验证，且已知目标项目和范围，同一项目从 development 访问 Preview 的流程就应无需人员介入即可运行。只有以下情况需要人员介入：

  • Vercel CLI 尚无已验证身份，也没有现有的 VERCEL_TOKEN；交互式 vc login 需要用户操作；
  • 安装的 Vercel CLI 版本低于 53.3.0，必须先升级才能签发令牌；
  • 无法安全推断用于签发令牌的正确目标项目或范围；
  • 必须添加或更改 Trusted Sources 规则；仪表板是唯一受支持的管理界面，且此操作会更改访问控制；
  • 调用方项目已禁用 Secure Backend Access with OIDC Federation，必须在 Settings → Security 中重新启用；或
  • 必须启用或轮换静态密钥回退方案，且 Agent 需要获得明确授权才能进行此访问控制更改。获批后，Agent 可以使用 vc project protection，无需通过仪表板操作。

Agent 可以诊断每种情况并说明所需的确切操作，然后在用户确认操作完成后继续。

使用正确的请求头

按如下方式发送 Vercel 签发的令牌：

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

不要替换为 x-vercel-oidc-token。该请求头会将工作负载身份传递到 Vercel Function；它不能通过 Deployment Protection 对入站请求进行身份验证。

排查故障

  • 重定向到 vercel.com/login：Deployment Protection 未接受该请求。
  • TRUSTED_SOURCES_ENVIRONMENT_MISMATCH：令牌有效，但调用方环境无法访问目标环境。
  • 通过保护后仍收到应用的 401 或 403：单独排查应用自身的身份验证。
  • 在刻意不存在的路由上收到应用的 404：请求已通过 Deployment Protection 并到达应用。

静态密钥备用方案

仅当 OIDC 不可行，或工具无法发送 Trusted Sources 请求头时，才使用 Protection Bypass for Automation。启用或轮换它会改变访问控制，因此请先取得明确授权。创建专用密钥，以便单独轮换；将其保存在环境变量中，并作为请求头传递：

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

cookie 指令会创建可重复使用的 _vercel_jwt cookie。请将包含该 cookie 的已保存浏览器状态视为凭据。

避免走入死胡同

  • 没有 vercel share CLI 命令。Shareable Links 面向的是人员，并非自动化方案。
  • vercel curl 适用于 HTTP 请求，但无法渲染页面并与之交互。
  • Deployment Protection Exceptions 会使域名公开。不要仅为了让 Agent 能够继续工作就使用它们。
  • 不要在日志、屏幕截图、源文件或面向用户的输出中暴露 OIDC 令牌、绕过密钥、经过身份验证的 URL 或已保存状态。

评论

支持 Markdown