# Vercel の Sensitive 環境変数が誰にも読み戻せない状態を、作り直さずに解消して恒久化する ## この指示書で解決すること - Vercel の本番環境変数がすべて **Sensitive** 型で入っていて、`vercel env pull --environment=production` でも API でも値が `[SENSITIVE]` / 空になり、新しい PC や担当者へ共有できない。 - 発行元（LINE・SaaS の API キー等）で作り直すと連携先の再設定が連鎖するので、**作り直さずに**現行の値を取り出したい。 - 二度と同じ状態にならないよう、**登録の入口を1本化し、ずれを毎日検出**したい。 ## 前提（公式仕様） - Sensitive 値は作成後にダッシュボード・CLI・API から読めないが、ビルドと実行時には渡される。 - Development ターゲットには Sensitive を置けない（`vercel env pull` 用に読める必要があるため）。→ **Development をチームが読める正本にできる**。 - 出典: https://vercel.com/docs/environment-variables/sensitive-environment-variables ## 手順 A: 現行値を作り直さずに1回だけ取り出す（本番トラフィックに影響させない） 1. 現状を測る（値は扱わない）: `GET /v10/projects//env?teamId=` で key / type / target / updatedAt を一覧化し、「production にあって development に無いキー」を数える。 2. 作業ブランチではなく **main から切った clean worktree** を作る（共有クローンの未コミット変更を本番デプロイに混ぜない）。`.vercel/project.json` をコピーする。 3. ローカルで RSA-3072 鍵ペアを作る（秘密鍵はローカルのみ・権限 600）。 4. 一時ルート（例 `/api/admin/env-export-once`）を追加する。条件: - `Authorization: Bearer ` 一致 かつ `VERCEL_ENV === "production"` 以外は **404**。 - 対象キーの `process.env` を JSON 化 → AES-256-GCM で暗号化 → AES 鍵を **公開鍵 RSA-OAEP(SHA-256)** で包んで返す（平文は一度もネットワークに出さない）。 - ミドルウェアの認証除外パス配下に置く（例: `/api/admin` が Bearer 認証前提で除外されている等）。 5. `vercel deploy --prod --skip-domain` でデプロイする。**本番の環境変数を持つが本番ドメインには割り当てない**ので、利用者・cron には影響しない。 6. Deployment Protection がある場合、生成 URL は保護される。`vercel curl` は bypass トークンを自動生成するので、以後はそのトークンを `x-vercel-protection-bypass` ヘッダに付けて `fetch` する（`vercel curl` 経由で引数に Authorization を渡すと shell で崩れることがある）。 7. 1回だけ取得し、ローカルで復号。画面には **値を出さず sha256 先頭8桁と長さだけ**出して照合表を作る。 8. 直ちに後始末し、すべて実測で確認する: - `DELETE /v13/deployments/` → 生成 URL が 404。 - `PATCH /v1/projects//protection-bypass` `{ "revoke": { "secret": "<自動生成分>", "regenerate": false } }` → bypass 残数が元に戻る。 - 本番ドメインの同パスも 404。 - 復号済み JSON と秘密鍵をローカルから削除。 ## 手順 B: Development を正本にする 1. 取り出した全キーを Development（type=encrypted）へ書き、`GET /v1/projects//env/?decrypt=true` で **全件読み戻して一致**を確認。 2. 秘密でない設定（モデル名・タイムゾーン・メール一覧・公開 URL・シート/フォルダ ID 等）は、**値の形式を正規表現で検査してから**本番も通常型へ作り直す（Sensitive ⇔ 通常の型変更は PATCH できないので delete→create）。実行中デプロイの env は作成時点で固定なので、同じ値なら挙動は変わらない。 3. 他 PC は `vercel env pull .env.local --environment=development --yes` だけで全値を取れる。 4. 注意: 以前に別経路で配った値が本番と食い違っていることがある（実例: 3/11 キーが不一致）。**本番値を正**として上書きし、旧値の持ち主へ伝える。 ## 手順 C: 恒久化（入口1本＋毎日の見張り） 1. **登録の入口** `scripts/env-set.mjs`（`pnpm env:set KEY`、値は stdin）: - 対象 target を含む既存定義を delete → production（Sensitive。`--plain` で通常型）と development（通常型）を create → development を decrypt 読み戻しして一致確認。 - Preview には既定で入れない（PR プレビューに本番秘密を渡さない）。 2. **見張り** `scripts/env-parity.mjs`: production と development のキー名・updatedAt を比較し、「development に無い」「production だけ新しい（猶予5分）」を検出 → Discord Bot で DM → exit 1。値は扱わない。 - Windows で `fetch` 直後に `process.exit()` すると libuv のアサーションで落ちることがある → `process.exitCode` で返す。 3. **GitHub Actions** `env-parity.yml` を毎日実行。secrets: `VERCEL_TOKEN` / Bot トークン / 通知先ユーザー ID。 4. **VERCEL_TOKEN の落とし穴**: `vercel login`（OAuth）で得た CLI トークン（`vca_` 期限付き＋`vcr_` 回転式 refresh）からは `POST /v3/user/tokens` が **403「Cannot create tokens for this app」**。refresh トークンを CI に置くと回転で手元の CLI ログインが切れる。→ 長期トークンは人がダッシュボード（Account Settings → Tokens、Scope=対象チーム、No Expiration）で発行する。ワンクリックのランチャーで「ブラウザでトークン画面を開く → 非表示入力で貼り付け → API で読めるか検証 → `gh secret set` → `gh workflow run` → 結果表示」まで自動化すると、人の操作は発行と貼り付けだけになる。 5. リポジトリの開発ルール（CLAUDE.md 等）に「env は `pnpm env:set` だけで投入。ダッシュボードや `vercel env add KEY production` で本番だけに入れない」を明記する。 ## 検証（完了条件） - 取り出し: 対象キー全件の sha8 一覧（値なし）。一時デプロイ 404・bypass 残数が元どおり・本番ドメイン 404。 - 正本化: development を全件 decrypt 読み戻し一致。 - 入口: 試験キー（通常型・Sensitive の2種）で env:set → 読み戻し一致 → 試験キー削除。 - 見張り: production だけに試験キーを置くと exit 1、削除で exit 0。CI の workflow_dispatch 実行が success。 ## やってはいけないこと - 取り出しルートを本番ドメインに載せる・main にマージする・平文で返す。 - 共有クローンの作業ブランチからそのまま `vercel deploy --prod`（未コミットの他作業が本番に混ざる）。 - 値をログ・チャットに出す（照合は hash 先頭8桁で行う）。 ---