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 IDと短期OIDCトークンの利用方法に加え、承認が必要な範囲と管理された静的シークレットの代替手段を示します。

主な機能

  1. 01短期Vercel OIDCトークンの利用
  2. 02ブラウザーセッション経由で保護されたPreviewにアクセス
  3. 03保護機能や環境エラーの診断
  4. 04人による承認が必要な範囲の明示
  5. 05承認済みの静的シークレット代替手段

活用シーン

  1. 01同一プロジェクトの保護されたPreviewを開く
  2. 02Trusted 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 を返す場合。

Trusted Sources ルールを編集するための、サポート対象の Vercel CLI や公開 REST API はありません。権限を持つ担当者が対象プロジェクトの Settings → Deployment Protection → Trusted Sources を開き、必要な呼び出し元と環境のマッピングのみを追加する必要があります。ローカルトークンの環境は development であるため、保護された Production にアクセスするには development から production へのマッピングが必要です。

必要なルールを明示して作業を人に引き継ぎます。アクセス制御の変更にブラウザー自動化を使用したり、無関係な環境マッピングを広げたりしないでください。担当者がルールの保存を確認した後、認証済みの open を再試行します。

人による対応が必要な条件

Vercel CLI がすでに認証済みで、対象プロジェクトとスコープが分かっている場合、同一プロジェクトの開発環境から Preview へのアクセスは、人の介入なしで実行できます。次の場合に限り、人による対応が必要です。

  • Vercel CLI に認証済みのアイデンティティがなく、既存の VERCEL_TOKEN もない場合。対話型の vc login にはユーザーの操作が必要です。
  • インストール済みの Vercel CLI が 53.3.0 より古く、トークンを発行する前にアップグレードが必要な場合。
  • トークン発行に必要な対象プロジェクトまたはスコープを安全に推定できない場合。
  • Trusted Sources ルールの追加または変更が必要な場合。ダッシュボードのみがサポート対象の管理画面であり、アクセス制御が変更されます。
  • 呼び出し元プロジェクトで Secure Backend Access with OIDC Federation が無効になっており、Settings → Security で再度有効にする必要がある場合。
  • 静的シークレットのフォールバックを有効化またはローテーションする必要があり、エージェントがそのアクセス制御変更について明示的な承認を必要とする場合。承認後、エージェントはダッシュボード操作を必要とせず、代わりに vc project protection を使用できます。

エージェントは各ケースを診断して必要な操作を正確に伝え、ユーザーが完了を確認した後に作業を続行できます。

正しいヘッダーを使用する

Vercel が発行したトークンを次のように送信します。

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

x-vercel-oidc-token に置き換えないでください。このヘッダーはワークロードの ID を 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 を設定すると、ドメインが公開されます。エージェントのブロックを解除するだけの目的で使用しないでください。
  • OIDC トークン、バイパスシークレット、認証済み URL、保存済みの状態を、ログ、スクリーンショット、ソースファイル、ユーザー向けの出力に含めないでください。

コメント

Markdown 対応