Discord bot の Administrator を剥がす — 「自分では外せない」壁の越え方

運用中の Discord bot に Administrator が付いたままになっている状態を、人手の UI 操作なしで最小権限へ直す手順。AI エージェントにそのまま渡して実行させられる粒度で書いてある。

前提と用語

• GUILD_ID … 対象サーバーの ID
• TARGET_BOT_ID … 権限を絞りたい bot の user id
• TARGET_ROLE_ID … その bot に付いている、Administrator を持つロールの id
• CHANNEL_IDS … その bot が実際に投稿・参照するチャンネル id の一覧

1. 最初に必ず position を測る（ここを飛ばすと必ず詰む）

Discord の permission hierarchy により、bot は自分の最上位ロールを編集・剥奪できない。PATCH /guilds/{GUILD_ID}/roles/{TARGET_ROLE_ID} も DELETE /guilds/{GUILD_ID}/members/{TARGET_BOT_ID}/roles/{TARGET_ROLE_ID} も、対象ロールが自分の最上位ロールより下でなければ通らない。Administrator を持っていても例外ではない。

GET /guilds/{GUILD_ID}/roles                      # 各ロールの position と permissions
GET /guilds/{GUILD_ID}/members/{TARGET_BOT_ID}    # その bot のロール一覧

判定: position が TARGET_ROLE_ID より大きく、かつ MANAGE_ROLES(0x10000000) か Administrator を持つ別の主体を探す。無ければ、この作業はサーバー所有者の手操作でしか完了しない（そこで止めて報告する。迂回しない）。

2. チャンネル権限を「明示付与」に置き換える（Administrator を外す前に必ず）

Administrator は全チャンネルを素通しするので、外した瞬間に閲覧権限ゼロの private チャンネルが 403 50001 Missing Access になる。先に明示 overwrite を張る。

PUT /channels/{CHANNEL_ID}/permissions/{TARGET_BOT_ID}
{"type": 1, "allow": "<bitmask>", "deny": "0"}

ビット値を自分で足すときは必ず検算する。よくある事故は VIEW_CHANNEL の抜け:

権限	値
VIEW_CHANNEL	1024
SEND_MESSAGES	2048
SEND_TTS_MESSAGES	4096
EMBED_LINKS	16384
READ_MESSAGE_HISTORY	65536

view+send+embed = 19456、それに TTS を足すと 23552。22528 は VIEW_CHANNEL が抜けた誤りで、Administrator が付いている間は動いてしまうため気付けない。付与後は GET /channels/{CHANNEL_ID} で read-back し、既存の overwrite が1件も増減していないことを変更前スナップショットと突き合わせる。

3. 上位 bot の資格情報が「読めない」場合の唯一の経路

上位 bot がホスティング環境（Vercel 等）で動いている場合、その token は往々にして secret/sensitive 指定で読み出せない。さらに production 限定スコープだと preview 環境にも存在しない。つまり:

• token をローカルへ持ってきて叩く → 不可
• preview にデプロイして安全に検証してから本番 → 不可（preview には token が無く 503）

残るのは「その bot 自身のアプリにロール編集の口を足して production へデプロイし、実行時 env の token で動かす」だけ。token を一度も読まずに実行できるのが利点。

手順:

1. アプリに一時エンドポイントを追加する。ADMIN_FIX_SECRET（自分で生成した新しい secret）の Bearer 一致を必須にし、不一致は 401。対象 guild を GUILD_ID に限定し、変更前の値を返す。 既存の secret は読めないので、検証用の secret は自分で新規に作るのがポイント。
2. vercel env add ADMIN_FIX_SECRET production → 現行の本番デプロイ id を退避してから vercel deploy --prod。
3. デプロイ直後に、既存機能が生きていること・誤 secret で 401 が返ることを確認する。異常なら即ロールバック（退避した READY デプロイを promote）。
4. 一時エンドポイント経由で PATCH /guilds/{GUILD_ID}/roles/{TARGET_ROLE_ID} に {"permissions":"0"}。変更前の値を記録してから実行。
5. 対象 bot 自身の資格情報で GET /guilds/{GUILD_ID}/roles して read-back。
6. 対象 bot の本番の実処理（cron route 等）をそのまま1回走らせ、投稿 → GET /channels/{id}/messages?limit=5 で read-back → DELETE → 再取得 404/10008 まで確認する。1つでも失敗したら即 {"permissions":"8"} へ戻し、戻したあと再実行して復旧を確認する。
7. 後片付け（必須）: 一時エンドポイントを削除して再デプロイ、vercel env rm ADMIN_FIX_SECRET、削除後に 404/405 と既存機能 200 を確認、ローカルの secret ファイルを削除。

4. 落とし穴（実測で踏んだもの）

• エージェントの「変更していません」を信じない。 変更系 API を実行したのに報告へ載せない事例があった。親側が GET で直接 read-back し、変更前スナップショットとの差分で判定する。
• リポジトリに remote が無いプロジェクトに「PR 必須」と指示すると止まる。 CLI デプロイ運用のリポでは PR を要求せずローカルブランチ + commit に切り替える。さらに、実装がバンドル退避されただけで master に入っていないと、本番だけが先に進み、次のデプロイで機能が消える。デプロイした内容は必ず既定ブランチへ取り込む。
• 2xx を成功と見なさない。 投稿は必ず read-back で message id の実在を確認し、テスト投稿は削除して 404/10008 まで見る。
• 費用対効果を先に出す。 所有者が UI でトグルを1回押せば 30 秒で終わる作業に、共有本番サービスのデプロイ2往復を投じる取引になることがある。着手前に一行で提示して判断を仰ぐ。

5. 完了条件のテンプレ

• 対象ロールの permissions が 0、かつ非管理者状態で本番の実処理が全チャンネルへ到達することを read-back 付きで実測済み
• 一時エンドポイントと一時 env が消えており、既存機能が 200
• 失敗時は元の permissions へ戻し、復旧まで確認済み