TF Approval Gate

AIコーディングエージェント（Claude Code、Cursor など）が Terraform の変更を計画・ポリシーチェック・コスト見積もりできるようにする MCP サーバーでありながら、実際の人間が Slack で Approve をクリックしない限り、エージェントが terraform apply を実行することを 構造的に不可能 にします。

なぜ

AIエージェントは現在、実際のクラウドアカウントに対して直接 Terraform を記述・実行できます。単独で terraform apply を実行できるエージェントは、人間が介在しないまま、本番インフラを静かに破壊したり誤設定したりする可能性があります。TF Approval Gate はそのギャップを埋めます。すべての apply には、実際の人間の Slack クリック（または開発モードではターミナルにいる人間）だけが発行できる、署名付きの使い捨てトークンが必要です。「人間が承認した」というエージェント自身の主張は決して信頼されず、サーバーがすべてを自ら再検証します。

Related MCP server: Hivelore

動作の仕組み

1. エージェントは .tf ファイルを編集し、tf_propose_change を呼び出します。terraform plan、Checkov（設定されていれば OPA）、Infracost（設定されていれば）を実行し、safe/needs_review/blocked の推奨事項を含む1つのバンドルされた提案を返します。

2. エージェントは tf_request_approval を呼び出します。diff + ポリシー検出結果 + コストを、Approve/Reject ボタン付きで Slack に投稿します（APPROVAL_MODE=cli の場合はサーバーのターミナルにプロンプトを表示）。ポリシー検出結果がブロッキングの場合は、投稿自体を拒否します。

3. エージェントは tf_check_approval_status をポーリングします。

4. 人間が Approve をクリックすると、サーバーはクリックが許可リストに登録された Slack ユーザーからのものであることを検証し、その正確なプランのチェックサムに紐づいた署名付き使い捨てトークンを発行します。

5. エージェントはトークンを付けて tf_apply を呼び出します。サーバーは署名、有効期限、使い捨てステータス、プランのバイナリチェックサムを再検証し、クラウド側のドリフトをチェックしてから、初めて terraform apply を実行します。

完全な設計と脅威モデルについては、docs/architecture.md と docs/security-model.md を参照してください。

クイックスタート（ローカル、Slack設定不要）

git clone https://github.com/SORABH13/tf-approval-gate.git
cd tf-approval-gate
npm install
npm run build
npm run check-binaries   # confirms terraform + checkov are on PATH

PATH に Terraform と Checkov が必要です。OPA/Conftest と Infracost はオプションです（存在しない場合は機能が自動的にスキップされます）。または、何もインストールせずに、以下の Docker image を使用できます。これには3つすべてがバンドルされています。

開発モードで実行します（APPROVAL_MODE=cli は、diff をサーバーのターミナルに出力し、Slack に投稿する代わりに y/n の入力を待ちます。最初のローカルテストに適していますが、Slack よりも保証が弱いため、docs/security-model.md を参照してください）：

APPROVAL_MODE=cli TF_APPROVAL_GATE_SECRET=$(openssl rand -hex 32) npm start

次に、Claude Code（または任意の MCP クライアント）で MCP サーバーとして追加します：

{
  "mcpServers": {
    "tf-approval-gate": {
      "command": "node",
      "args": ["/absolute/path/to/tf-approval-gate/dist/index.js"],
      "env": {
        "APPROVAL_MODE": "cli",
        "TF_APPROVAL_GATE_SECRET": "<same secret as above>"
      }
    }
  }
}

エージェントを examples/local-demo に向けて（null/random プロバイダーを使用し、クラウド認証情報は不要）、tf_workspace_init → tf_propose_change → tf_request_approval → tf_apply を実行するように依頼します。

Docker / devcontainer

docker build を実行すると、Node、Terraform、Checkov、Conftest（OPA）がプリインストールされたイメージが生成されます。Docker 自体以外のホスト設定は不要です。

docker build -t tf-approval-gate .
docker run --rm -it \
  -e APPROVAL_MODE=cli \
  -e TF_APPROVAL_GATE_SECRET=$(openssl rand -hex 32) \
  -v "$(pwd)/examples/local-demo":/examples/local-demo:ro \
  -v tf-approval-gate-data:/data \
  tf-approval-gate

Slack モードの場合は、-e SLACK_BOT_TOKEN=... -e SLACK_APP_TOKEN=... -e SLACK_APPROVAL_CHANNEL=... -e SLACK_APPROVER_USER_IDS=... を追加し、APPROVAL_MODE=cli を外します。承認状態は /data ボリュームに永続化されます（SQLite バックエンド。docs/architecture.md を参照）。

VS Code / GitHub Codespaces 用の .devcontainer/devcontainer.json も含まれています。リポジトリをコンテナで開くと、terraform/checkov/conftest がすぐに利用できます。

Slackのセットアップ（本番モード）

1. examples/slack-app-manifest.yml から Slack アプリを作成します。

2. Socket Mode を有効にし、アプリレベルトークン（xapp-...）を生成します。

3. アプリをワークスペースにインストールし、ボットトークン（xoxb-...）をコピーします。

4. SLACK_BOT_TOKEN、SLACK_APP_TOKEN、SLACK_APPROVAL_CHANNEL、SLACK_APPROVER_USER_IDS（Approve/Reject をクリックできるカンマ区切りの Slack ユーザー ID）を設定します。.env.example を参照してください。

5. APPROVAL_MODE=slack（デフォルト）で実行します。

詳細な手順: docs/slack-setup.md。

ツール

完全なリファレンス: docs/tool-reference.md。

ステータス

v0.1 から v0.4 までが実装・テスト済みです。ハッピーパス（Checkov、Slack Socket Mode / CLI フォールバック）、OPA/Conftest、Infracost コスト見積もり、そしてアトミックな使い捨てトークン消費を備えた SQLite バックエンドの承認ストアが含まれます。Docker イメージと devcontainer もビルド・検証済みです。ローカルの null/random デモと実際の AWS アカウント（examples/aws-s3-demo）の両方に対して、実際のエンドツーエンド実行が行われています。完全なロードマップと公開ローンチ記事の前に残っている作業（デモGIFと外部からのコールドテスト -- CONTRIBUTING.md を参照）については、docs/architecture.md を参照してください。

ライセンス

MIT -- LICENSE を参照してください。