# 共有秘密をローテーションしても配布先PCを締め出さない鍵配布サーバの設計と復旧手順 チームの全PCへ AI/API のキーを自動配布する小さなサーバ（以下 keyserve）を運用するときの、 **「共有秘密を張り替えた瞬間に全端末が永久に締め出される」事故を防ぐ設計**と、 すでに締め出してしまった場合の**復旧手順**をまとめた指示書。 対象読者: AI エージェント（Claude Code / Codex 等）にこの作業をやらせる人。 前提スタック: Node.js のサーバレス関数（Vercel/Cloudflare/Lambda いずれでも可）＋ 各PCで動く配布クライアント（Node スクリプト）。 --- ## 1. 最小構成（これだけで動く） - サーバ: `POST /api/keys` のみ。認証は **HMAC-SHA256(共有秘密, unixtime)** をヘッダで受ける。 - `x--ts`（unix 秒）と `x--auth`（hex 64桁）。`|now - ts| <= 300` 秒、比較は `crypto.timingSafeEqual`。 - 秘密は環境変数に置く。配布リポジトリが public なら**暗号文であっても鍵をリポジトリに置かない**。 - サーバの返り値: `{ files: { "<ファイル名>": "<中身>", ... } }`。クライアントは `~/./` 配下へ書く。 - クライアント: 1日1回だけ実行（前回実行時刻を state ファイルに保存して間引く）。失敗しても起動処理を止めない。 ### 認証の受け口は必ず「複数本」にする ```js const candidates = [ ...(process.env.SHARED_SECRET ? [{ secret: process.env.SHARED_SECRET, label: 'primary' }] : []), ...list(process.env.SHARED_SECRET_LEGACY).map((s, i) => ({ secret: s, label: `legacy#${i + 1}` })), ...list(process.env.ENROLL_SECRETS).map((s, i) => ({ secret: s, label: `enroll#${i + 1}` })), ]; // list() は JSON 配列 / 改行 / カンマ区切りのどれでも受ける ``` - `primary`: 現行の正規の秘密。**サーバは応答に必ず `keyserve.env`（= primary の入ったファイル）を含めて返す**。 こうすると「一時トークンで1回だけ叩けば、以後は正規の秘密で通る」状態を自動で作れる。 - `legacy`: 移行期間だけ有効な旧秘密。**ローテーションの生命線**。 - `enroll`: 新規端末・締め出された端末の受け入れ用の使い捨てトークン。使い終わったら消す。 - 一致した**ラベルだけ**をログに出す（値は絶対に出さない）。 --- ## 2. 事故の型: 「既存ならスキップ」に更新対象を乗せてはいけない 配布クライアントは事故防止のため、こう書かれがち: ```js if (fs.existsSync(destination)) continue; // ← 既存は絶対に上書きしない fs.writeFileSync(destination, contents, { flag: 'wx', mode: 0o600 }); ``` 手で編集した API キーを潰さないという意味では正しい。だが、この既定に **「サーバ側で変わりうる値」＝ 共有秘密そのもの（`keyserve.env`）を乗せると詰む**。 サーバの `primary` を張り替えた瞬間に、各PCは古い秘密で叩き続ける →`401` → 新しい秘密を受け取る手段が無い → **永久に自己回復できない**。しかも失敗はログにしか出ないので数日誰も気付かない。 ### 正しい実装（更新対象だけ明示的に上書き分岐） ```js const cleaned = contents.replace(/^/, ''); if (fs.existsSync(destination)) { // 秘密ファイルだけは中身が変わっていたら更新する。他の配布ファイルは従来どおりスキップ。 if (name !== 'keyserve.env' || fs.readFileSync(destination, 'utf8') === cleaned) continue; fs.writeFileSync(destination, cleaned, { encoding: 'utf8', mode: 0o600 }); log(`refreshed: ${name}`); // 値は出さない continue; } fs.writeFileSync(destination, cleaned, { encoding: 'utf8', flag: 'wx', mode: 0o600 }); ``` - 中身が同じなら**書かない**（mtime を動かさない）＝ 無駄な差分と再起動を誘発しない。 - `401` かつ秘密ファイルが存在する場合は、可視メッセージに 「サーバ側で秘密がローテーションされた可能性があります」を添える。原因に直結する一文があるだけで復旧が早い。 - **失敗は必ず人の見る場所（チャットの通知先）へ1行出す**。ログファイルだけに出す実装が「数日誰も気付かない」の原因。 ただし24時間に1回に抑止し、通知本文に秘密値を含めない。 --- ## 3. ローテーションの正しい順序（②から始めない） 1. **クライアント修正を先に配布**（上の上書き分岐）。配布経路は git pull / zip 取得など、 **鍵の認証に依存しない**経路であること。ここが認証に依存していると鶏卵になる。 2. `primary` を新しいランダム値へ張り替える（例: `crypto.randomBytes(48).toString('base64url')`）。 3. 同時に `LEGACY` へ**各端末が今持っている旧値**を入れる。これが移行期間の唯一の生命線。 4. 再デプロイ（環境変数はデプロイ時にスナップショットされる基盤が多い。**変更しただけでは効かない**）。 5. 各端末が「旧値で 200 → 新 primary を受領して上書き」まで進んだことを**実測**する。 6. 確認できてから `LEGACY` を削除して再デプロイ。使い捨ての `ENROLL` もここで消す。 ### 実測の仕方（ここを省くと直ったつもりで終わる） - 端末側: 配布クライアントのログに `refreshed: <秘密ファイル>` が出ているか。 - サーバ側: ランタイムログに `auth via legacy` が残っていないか。 - 疎通テスト（値を出力しないスクリプトで）: **新 primary=200 / 旧値(legacy)=200 / でたらめな秘密=401** の3点を必ず確認する。 「200 が返った」だけでは不十分で、**認証が効いていること（401 側）** まで見る。 --- ## 4. 環境変数の落とし穴 - **暗号化された環境変数は CLI で読み戻せないことがある**（値が空で返る）。 「既存値を読んで merge して置き換える」は成立しない。**新しい変数名を足す**設計にする （`KEYS_JSON`, `KEYS_JSON_EXTRA`, `KEYS_JSON_EXTRA2` … をサーバ側で全部 merge する）。 読み戻せると誤解したまま `rm → add` すると、**配布中の鍵一式を丸ごと失う**。 - 削除→追加の間に失敗すると `primary` が消えた状態になる。**新しい値は必ず先にローカルへ書いてから**張り替える （復旧できる状態を作ってから壊す）。 - 一時トークンは「発行 → 渡す → 使わせる → **消す**」までを1セットにする。消し忘れると、 チャット履歴や作業ログに平文で残った1本で**全社のキー一式が引ける**状態が続く。 --- ## 5. AI に作業させるときの指示テンプレ ``` 目的: <サービス名> の共有秘密をローテーションする。端末を1台も締め出さないこと。 前提として先に調べて報告すること: - 配布クライアントは新しい秘密を「上書き」で受け取れる実装になっているか（既存ならスキップになっていないか） - 旧秘密を残す LEGACY 相当の受け口がサーバ側にあるか - 現在どの端末が認証できているか（ログの 401 を実測する） そのうえで ①クライアント修正 → ②新値へ張り替え＋旧値を LEGACY へ → ③再デプロイ → ④新primary=200 / legacy=200 / でたらめ=401 を実測 → ⑤移行確認後に LEGACY と一時トークンを削除、の順で行う。 秘密値は出力しない（指紋 sha256 の先頭8桁と HTTP status だけ報告する）。 ``` - 秘密を扱うスクリプトは **値を print しない**設計にし、確認は「指紋・件数・status」で行う。 - 一時ファイルに書いた秘密は作業後に削除する。 --- ## 6. チェックリスト - [ ] サーバは primary / legacy / enroll の複数本を受け付け、一致ラベルだけをログに出す - [ ] 応答に「現行 primary 入りのファイル」を必ず含める（端末が自動で正規化される） - [ ] クライアントは秘密ファイルだけ上書き更新、他は既存スキップ - [ ] 失敗（401）は人の見る通知先へ1行、24時間抑止つき、秘密値なし - [ ] ローテーションは「クライアント修正 → 張り替え＋LEGACY → 再デプロイ → 実測 → LEGACY 削除」の順 - [ ] 暗号化 env は読み戻せない前提で、追加は新しい変数名で行う - [ ] 一時トークンは削除まで完了して初めて「閉じた」と言う ---