保存時の鍵を AWS KMS にする

AWS の配備（ecs / ecs-ec2）だけの機能です。Control Plane が封じて保存する秘密を、AF_MASTER_KEY から導いた鍵ではなく AWS KMS の鍵で守れます。 KMS 鍵を無効にすれば、封じた値をまとめて読めなくできます。コマンドとパラメータは ECS の手順書にあります。

全体像

あなたがやること	起きること
`10-data` を `CustodianKmsKey=create` でデプロイする	対称 KMS 鍵ができ、出力 `CustodianKmsKeyArn` にその ARN が出る
`30-ingress` を `CustodianKmsKeyArn` 付きでデプロイする	Control Plane が KMS で封じるようになる。これ以後に保存する値が KMS で守られる
`af-cp rewrap-keys` を実行する	切り替える前に保存された値も KMS で封じ直される
KMS 鍵を無効にする	切り替えたあとに封じた値が、すべてのテナントで一斉に読めなくなる

メンバーのホームごとに専用の鍵を持たせるのは、この上に重ねる別の設定です（ホームごとに鍵を分ける）。

KMS が守るもの

値はそれぞれ KMS から得た新しいデータ鍵で封じられ、テナントに結び付きます。別のテナントの名前では開けません。

MCP 接続のヘッダと、テナントが MCP サーバー用に登録したクライアントシークレット
サインインと Git OAuth のクライアントシークレット
エンジンの Hugging Face・Civitai・ComfyUI の鍵
セッションの引き継ぎと共有の提案
受信箱のメッセージとその添付
開発用ログインの署名鍵とクライアントシークレット
各ワークスペースの資格情報ストアの鍵を包んだもの
ホームごとの鍵があるホームでは、その資格情報ストアの鍵

有効にする

10-data を CustodianKmsKey=create でデプロイし、出力の CustodianKmsKeyArn を読みます。同じアカウントにある自前の対称 KMS 鍵を使っても構いません
30-ingress を CustodianKmsKeyArn=<その ARN> でデプロイします

Control Plane には AF_KEY_CUSTODIAN=kms と AF_KMS_KEY_ID が渡ります。タスクロールに付くのは、その鍵に対する kms:GenerateDataKey と kms:Decrypt だけで、Control Plane の暗号化コンテキストが付いた呼び出しに限られます。

切り替える前に知っておくこと

こと	中身
`AF_MASTER_KEY` は引き続き必須	切り替える前に保存された値はこの鍵で開き、ほかの鍵もこの鍵から導かれます。これまでどおり保管してください
自動では封じ直さない	切り替える前の値は読めるままで、守りは `AF_MASTER_KEY` だけのままです。封じ直すまで、KMS が守るのは切り替えたあとに保存した値だけです
代わりの経路はない	KMS に届かない・拒否されたときは、封じるのも開くのも KMS を名指すエラーで失敗します。KMS が封じた値を、黙って `AF_MASTER_KEY` で扱うことはありません
開いた鍵は 5 分キャッシュする	`AF_KMS_DATA_KEY_CACHE_TTL` で変えられます。`0` を指定するとキャッシュしません。KMS 鍵の無効化が効くのはこの時間のうちで、即時ではありません
`local` に戻さない	KMS が封じた値があるうちは、`local` の Control Plane はその値を、理由を示すエラーで拒否します

メンバーの資格情報は、これだけでは消せない

各ワークスペースの資格情報ストア（secrets.enc）の鍵は、AF_MASTER_KEY とメンバーから導かれます（HMAC(master, userKey)）。

KMS が包むのは、切り替えたあとに初めて鍵を保存するワークスペースの鍵だけです。すでに鍵を持つワークスペースは、再起動しても AF_MASTER_KEY で包んだままです
どちらにしても、AF_MASTER_KEY を持つ人は鍵を導いてストアを開けます。KMS 鍵を無効にしても、メンバーが保存した資格情報は消えません
この経路から AF_MASTER_KEY を外すのが、ホームごとに鍵を分けるです

KMS 鍵を無効にする

やりたいこと	すること	結果
すべてのテナントの値を読めなくする	KMS 鍵を無効にするか、削除を予定する	切り替えたあとに封じた値が、Control Plane から一斉に読めなくなります
1 つのテナントだけを止める	鍵ポリシーに、`kms:EncryptionContext:af:key_ref` がそのテナントの ID のとき `kms:Decrypt` を拒否する文を足す	そのテナントの値だけが開けなくなります。鍵の管理者が戻せる失効で、消去ではありません

鍵の無効化は配備のすべてを読めなくする手段なので、KMS 鍵を管理できる人を絞ってください。

切り替える前に保存された値を封じ直す

af-cp rewrap-keys は、切り替える前に AF_MASTER_KEY で封じた値を、すべて KMS で封じ直します。対象は KMS が守るものの全部です。実行したあとは、KMS 鍵を無効にするとこれらも読めなくなります。

Control Plane が AF_KEY_CUSTODIAN=kms で動いていることを確かめます。local では実行を拒否します。local の Control Plane は、このコマンドが書いた値を開けません
Control Plane と同じ環境（同じ AF_MASTER_KEY・AF_KMS_KEY_ID・データベースの設定・タスクロール）で、まず --dry-run を付けて実行します。ECS では Control Plane のタスク定義を使う単発のタスクとして動かします。貼り付けるコマンドは ECS の手順書にあります
--dry-run を外して実行します。終了コード 0 になるまで繰り返します
終わったら、もう一度 --dry-run で確かめます

--dry-run は何も変えず、KMS も呼びません。置き場所ごとに、KMS で封じた数・古い形式の数・封じずに保存された数を出します。封じずに保存された値は、AF_MASTER_KEY のない Control Plane が書いたもので、コマンドは触りません。

書き直しのしかた

値ごとに AF_MASTER_KEY で開き、KMS で封じ、KMS でもう一度開けることを確かめてから書きます
1 行ずつ書き、その間に行が変わっていたら書きません
中断・KMS のエラー・Decrypt の拒否では、その行を書く前に止まります。どの行も古い形式か KMS で封じたかのどちらかで、どちらも開けます
書き直したあと、何も変えずにすべての置き場所をもう一度見ます。終了コードはこの最後の確認で決まります
やることが残っていない実行は、何も変えません

終了コード	意味
終了コード 0	最後に見た時点で古い形式がなく、どの行も読めた。`--dry-run` でも同じです
終了コード 1	古い形式が残っている、読めない・書けない行がある、または途中で止まった。ログに置き場所と行の ID が出ます。値は出ません
終了コード 2	設定の問題。`kms` でない、`AF_MASTER_KEY` がない、鍵 ID がない、データベースがない

--dry-run は、封じ直す前は終了コード 1、封じ直したあとは終了コード 0 で終わります。

管理者が編集していないときに実行する

Control Plane は動かしたままで構いません。ただし次の保存は、読み出した値をそのまま書き戻します。

サインインのプロバイダや Git OAuth アプリを、秘密を入れ直さずに保存する
ComfyUI のパネルを、鍵を入れ直さずに保存する

コマンドが書き直す前に古い値を読んだ保存は、古い値を戻してしまいます。実行中に起きたものは最後の確認が見つけますが、そのあとに起きたものは見つけられません。

封じ直したあとも `AF_MASTER_KEY` は外せない

封じ直した値は、AF_MASTER_KEY だけでは開けなくなります。それでも AF_MASTER_KEY は外せず、変えてもいけません。

資格情報ストアの鍵は、今もこの鍵から導けます。コマンドが KMS に移すのは鍵を包んだ写しだけです
初めて起動するワークスペースも、同じ導きかたで鍵を得ます
ワークスペースが Control Plane を呼び返すときのトークン（Git の資格情報、Git OAuth、メモ、スケジュール、エンジン、ブランチ規則、AWS と Google Cloud のプロファイル、ドキュメント、MCP）は、この鍵から導いた鍵で署名されます
AF_KEY_CUSTODIAN=kms で AF_MASTER_KEY がないと、Control Plane は起動を拒否します

`AF_MASTER_KEY` のパラメータを自前の鍵で暗号化する

上の KMS による保管とは別の設定です。ECS では AF_MASTER_KEY の値は SSM の SecureString /af-cp/master-key にあり、指定しなければ AWS マネージドの aws/ssm 鍵で暗号化されます。

20-platform の MasterKeyKmsKeyArn に自前の鍵の ARN を設定します
そのあとで、--key-id を付けてパラメータを入れ直します

この順番を守ってください。ECS はこの値を実行ロールで復号するので、鍵が許可するのはタスクロールではなく実行ロールです。テンプレートが付けるのは、その鍵に対する kms:Decrypt だけで、SSM を経由する呼び出しに限られます。手順・鍵ポリシー・元に戻しかたは deploy/aws/ecs/cfn/PARAMETERS.md の「MasterKeyKmsKeyArn」にあります。

変わるのは、保存された値を誰が読めるかだけです。値そのものは変えてはいけません（配備の鍵を扱う）。

エージェント向け

この指示をエージェントに送ると、このページを読ませられます。

https://agent-fleet.org/docs/ja/operate/keys/kms/index.md を読んで