gc-vault

name	gc-vault
description	gc-vault でラップされた GCP プロジェクトに対して gcloud / gcloud storage / bq / terraform 等のコマンドを実行する際に使用する。直接の gcloud auth login やローカル credentials に頼らず、1Password に保管された bootstrap SA キーから短命の借用トークンを発行してコマンドを実行する。

gc-vault: 安全な GCP 認証ラッパー

Claude Code の Bash ツールから実行する場合は 「Claude Code から実行する手順（必読）」 に従うこと。サンドボックス解除と 1Password の認証の二段階防御で運用する。

いつ使うか

ユーザーが以下のような操作を求めたとき、本スキルを適用する：

• gcloud / gcloud storage / bq の実行（gsutil は gc-vault の認証経路では動作しない、後述）
• Terraform google provider を使う terraform plan / apply
• GCP の Client Libraries を使うスクリプト（Ruby / Python / Go 等）の起動
• cloud-sql-proxy 等の補助ツール起動

Claude Code から実行する手順（必読）

プロファイルの確認

利用可能なプロファイル名はユーザーが ~/.config/gc-vault/config.toml で定義している。プロファイル名を agent 側で把握していない場合は、以下の読み取りコマンドで確認する（サンドボックス内で動作する）。

gc-vault list

プロファイルの選び方

ユーザーの要求文に明示的な profile 名が含まれていない限り、agent は推測で profile を決めない。gc-vault list で利用可能な一覧を取得し、ユーザーに選択を促す。ユーザーの言葉遣い（「dev」「production」等）から推測することはしない（誤って本番に対して操作するリスクを避けるため）。

選択を促す具体的な方法は profile の件数で分岐する:

• 2 件以上の場合: AskUserQuestion ツールで選択肢を提示するか、平文で一覧を出して選んでもらう
• 1 件のみの場合: AskUserQuestion は最低 2 選択肢を要求するため使えない。平文で「このプロファイル <profile> で実行してよいですか？」と確認し、肯定応答を得てから進める。読み取り系コマンド（gcloud ... list / describe 等）なら、確認文中に実行予定のコマンドも併記するとやり取りが減る

手順

Bash ツール呼び出しに dangerouslyDisableSandbox: true を指定して gc-vault exec <profile> -- <command> を実行する。

Bash ツール呼び出し:
  command: gc-vault exec <profile> -- gcloud sql instances list
  dangerouslyDisableSandbox: true

実行時に発生するユーザー操作:

1. Bash 承認プロンプト（Claude Code 側）— サンドボックス解除を伴う実行をユーザーが承認
2. 1Password の認証プロンプト（1Password アプリ）— bootstrap SA キーへのアクセスを生体認証で承認

この 2 段階により、agent が意図しない gc-vault exec を呼ぼうとしても、ユーザーが少なくともどちらかで止められる。

1Password の認証が毎回要求される理由

通常、op CLI は「ターミナルセッション」単位で 1 回 1Password の認証を要求し、セッション内（10 分間 / 操作のたびに延長）は再認証なしで動作する（公式仕様）。しかし Claude Code の Bash ツールは各呼び出しごとに独立したプロセスを spawn するため、1Password 側からは 毎回別セッション として扱われ、結果的にすべての gc-vault exec で 1Password の認証が要求される。

これは 1Password / Claude Code どちらの明示的な設定でもなく、両者のプロセスモデルの相互作用から生じる挙動。1Password 設定で実現するものではない。

将来 Claude Code がプロセスを再利用するようになる、あるいは 1Password がセッション判定ロジックを変更する等で「毎回 1Password の認証」が省略される可能性がある。Bash 承認プロンプトを通過した後に 1Password の認証プロンプトが出ない場合は、防御層が 1 段に減っているため、ユーザーに警告して挙動の変化を共有すること。

1Password の認証が頻繁で煩わしい場合

連続して多数の GCP 操作が必要な場面では、毎回の Bash 承認 + 1Password の認証が運用上重くなる。その場合は、ユーザーに 「別ターミナルで gc-vault shell <profile> を起動し、そこから claude を立ち上げる」 運用（README「代替運用」を参照）への切り替えを提案する。この運用なら起動時の 1Password の認証は 1 回で済み、Claude Code 内では gcloud を直接実行できる（credentials がセッション中露出するトレードオフあり）。

切り替えの目安: 同じセッションで 3 件以上の gc-vault exec が見込まれる場合、または既に何度か実行してユーザーから「面倒」「重い」等の反応があった場合。

コマンドを組み立てる際のルール

• --project フラグは付けない（gc-vault が CLOUDSDK_CORE_PROJECT を自動セットする）
• 1 回の gc-vault exec で複数の処理を && 等で連結しない（複合コマンドにすると Bash 承認の粒度が粗くなり、ユーザーが意図を読み取りにくくなるため）
• 連続して多数のコマンドが必要な場合でも、1 コマンド = 1 gc-vault exec を保つ
• gsutil は使わず gcloud storage を使う（gsutil は CLOUDSDK_AUTH_ACCESS_TOKEN も GOOGLE_APPLICATION_CREDENTIALS も認証ソースとして直接読まないため、gc-vault exec 経由では 401 Anonymous caller になる。gcloud storage ls / cp / rsync 等が代替）

NG

• サンドボックス有効のまま gc-vault exec を呼ぶ（op がデスクトップアプリに到達できず失敗する）
• gcloud sql instances list のように gc-vault を経由しない呼び出し（クレデンシャルがないため失敗、または個人アカウントを誤用する）
• ~/.claude/settings.json の sandbox.network.allowUnixSockets への追加を提案する（実機検証で複数ソケット + 追加の IPC 経路の許可が必要と判明、設定がフラジャイル。gc-vault リポジトリの README「採用しないアプローチ」参照）

いつ使わないか

• kubectl (GKE): gke-gcloud-auth-plugin が独自フローのため非対応
• firebase CLI: 独自認証

提案するコマンドの作り方

ユーザーから「 の Cloud SQL インスタンスを確認したい」などの要望があったら：

OK: gc-vault exec <profile> -- gcloud sql instances list（dangerouslyDisableSandbox: true 付き）

NG: gcloud sql instances list --project=<project>（クレデンシャルがないため失敗）

その他の例:

gc-vault exec <profile> -- gcloud projects describe "$CLOUDSDK_CORE_PROJECT"
gc-vault exec <profile> -- gcloud run services list
gc-vault exec <profile> -- gcloud storage ls gs://my-bucket/
gc-vault exec <profile> -- bq ls
gc-vault exec <profile> -- terraform plan
gc-vault exec <profile> -- bin/rails console

環境変数

gc-vault がセットする環境変数：

• CLOUDSDK_AUTH_ACCESS_TOKEN: gcloud 系 CLI 用の短命トークン
• CLOUDSDK_CORE_PROJECT: profile の project 値
• GOOGLE_APPLICATION_CREDENTIALS: SDK / Terraform 用の impersonated_service_account 形式 ADC JSON のパス
• GCP_VAULT_ACTIVE_PROFILE: 現在のプロファイル名（プロンプト表示等）

注意事項

• アクセストークンは 30 〜 60 分で失効。長時間プロセス（cloud-sql-proxy 等）は SDK 側の自動更新（ADC 経由）に依存
• 1Password デスクトップアプリが起動・unlock されている必要がある（gc-vault が内部で op CLI を呼び出すため）
• gcloud auth login での個人アカウント認証は 使わない方針。既存の credentials は gcloud auth revoke --all + gcloud auth application-default revoke で削除可能
• Claude Code のサンドボックスは op CLI が 1Password デスクトップアプリと通信する経路（複数の Unix ソケット等）を遮断する。そのため gc-vault exec の呼び出しには dangerouslyDisableSandbox: true が必須
• 1Password の認証が毎回要求される挙動が将来変化した場合（プロンプトが省略される等）、防御層が一段減るためユーザーに伝える
• ツール本体: https://github.com/zenn-dev/gc-vault