Antigravity の OAuth トークンが OS キーリングに保存されるようになった—ヘッドレス運用で認証を崩さない設計

保管バックエンドを明示的に選ぶ

保管庫が「あるかもしれない／ないかもしれない」に依存した自動化は、環境が少し変わるたびに崩れます。ヘッドレス運用では、暗黙の既定に任せず、使う保管バックエンドを明示的に固定するのが安定します。

多くの認証まわりのツールは、環境変数か設定ファイルで保管バックエンドを選べるように作られています。手元の版で選択肢の名前は変わり得るので、antigravity --help や設定ドキュメントで実際のキー名を確認してから、次のように「環境ごとに宣言する」形にします。

#!/usr/bin/env bash
# 目的: 実行環境に応じて保管バックエンドを1つに固定する。
# 「たまたま動く」をやめ、どの経路で保存されるかを常に自分で握る。
set -euo pipefail
 
CRED_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/antigravity"
mkdir -p "$CRED_DIR"
chmod 700 "$CRED_DIR"
 
if has_secret_service; then
  # デスクトップ相当: OS キーリングに任せる。
  export ANTIGRAVITY_CRED_BACKEND="keyring"
else
  # ヘッドレス: 権限を絞ったファイルに固定する。
  export ANTIGRAVITY_CRED_BACKEND="file"
  export ANTIGRAVITY_CRED_FILE="$CRED_DIR/credentials.json"
fi
 
echo "[keyring] backend=${ANTIGRAVITY_CRED_BACKEND}"

ここで has_secret_service は前節の関数です。変数名（ANTIGRAVITY_CRED_BACKEND など）はあくまで例で、実際のツールが読む環境変数名に置き換えてください。設計上の意図は変わりません——保存経路を実行時に一意に決め、ログに残すことです。どこに保存されたか分からないトークンは、後で必ず調査を長引かせます。

ファイルフォールバックを安全に設計する

ヘッドレスでキーリングが使えないとき、素朴にトークンを平文ファイルへ書くと、今度は権限が問題になります。ホームディレクトリ配下でも、既定のマスク次第では同一グループから読めてしまいます。ここは「動く」だけでなく「読めない」ことまで設計します。

#!/usr/bin/env bash
# 目的: ファイルフォールバック時に、書き込みと同時に権限を 0600 へ落とす。
# 「書けた」ことと「他人に読めない」ことは別問題。両方を1つの操作で保証する。
set -euo pipefail
 
write_credentials() {
  local dest="$1" payload="$2"
  local tmp
  tmp="$(mktemp "${dest}.XXXXXX")"       # 同一ディレクトリに一時ファイルを作る
  chmod 600 "$tmp"                        # 中身を書く前に権限を絞る
  printf '%s' "$payload" > "$tmp"
  mv -f "$tmp" "$dest"                    # 原子的に差し替える（読み手が半端な状態を見ない）
  chmod 600 "$dest"
}
 
# 検証: 保存直後に、権限が想定どおりかを必ず確かめる。
verify_permissions() {
  local f="$1"
  local mode
  mode="$(stat -c '%a' "$f" 2>/dev/null || stat -f '%Lp' "$f")
  if [ "$mode" != "600" ]; then
    echo "[keyring] 権限が 600 ではありません（現在 ${mode}）。中止します。" >&2
    return 1
  fi
  echo "[keyring] 権限 600 を確認しました"
}

三点、意図を補足します。第一に、権限を落とすのは中身を書く前です。先に書いてから chmod すると、その一瞬だけ他人に読める窓が開きます。第二に、mktemp と mv -f で原子的に差し替えます。トークンの更新中に別プロセスが読みにきても、半分だけ書かれた壊れた JSON を掴ませないためです。第三に、書いたあと必ず stat で 0600 を確認します。私はこの検証を省いて、umask が緩い CI コンテナでだけファイルがグループ可読になっていたのを、後から冷や汗とともに見つけたことがあります。

平文で置くことに抵抗があれば、保存前にマシン固有の鍵で暗号化する層を挟めます。ただしその鍵をどこに置くのか、という同じ問題が入れ子になるだけなので、まずは 0600 と最小権限のディレクトリ（0700）で守り、そのうえで必要なら暗号化を足す、という順序を私は好みます。鍵そのものの入れ替えについては、無人のエージェントを止めずに鍵を入れ替える で扱った重複期間つきローテーションの考え方が、そのまま応用できます。

Linux のヘッドレスでキーリングを「あえて」立てる選択

ファイルフォールバックが基本線ですが、どうしても Secret Service を使いたい場合——たとえば既存のツール群がキーリング前提で作られている場合——には、ヘッドレスでも応答者を立てる手があります。使うかどうかは別として、選択肢として知っておくと判断に幅が出ます。

#!/usr/bin/env bash
# 目的: ヘッドレス Linux で、その場かぎりの D-Bus セッションと
#       解錠済み gnome-keyring を起動し、そのシェルの中でジョブを走らせる。
# 注意: 解錠パスフレーズの受け渡しが新たな秘密管理の対象になる点は理解しておく。
set -euo pipefail
 
run_with_keyring() {
  local passphrase="$1"; shift
  dbus-run-session -- bash -c '
    printf "%s" "'"$passphrase"'" \
      | gnome-keyring-daemon --unlock --components=secrets >/dev/null 2>&1
    exec "$@"
  ' _ "$@"
}
 
# 使い方: パスフレーズは環境変数などから安全に渡す（ハードコードしない）。
# run_with_keyring "$KEYRING_PASSPHRASE" antigravity run my-task

正直に言えば、これは便利さと引き換えに、解錠パスフレーズという新しい秘密を運用対象に増やします。トークンを守るための仕組みが、別の秘密を生む。この入れ子を割に合うと見るかどうかは、既存資産の量しだいです。まっさらな自動化を新しく組むなら、私はファイルフォールバックの単純さを推奨します。既存のキーリング依存が厚い現場なら、この起動ラッパーで橋を架けるほうが移行の傷が浅くなります。

保存場所ごとに、トークンの生死を確かめる

保管戦略を選んだら、最後に「そこに生きたトークンが本当にあるか」を本処理の前に確かめます。バックエンドが違えば確認方法も違うので、経路ごとに検査を分けます。

#!/usr/bin/env bash
# 目的: 選んだバックエンドに応じて、本処理の前にトークンの存在と鮮度を確かめる。
# 「保存できているつもり」を、実行のたびに事実として検証し直す。
set -uo pipefail
 
preflight_credentials() {
  case "${ANTIGRAVITY_CRED_BACKEND:-}" in
    keyring)
      # キーリング経由: ツールの認証状態確認コマンドに委ねる。
      antigravity auth status >/dev/null 2>&1
      ;;
    file)
      local f="${ANTIGRAVITY_CRED_FILE:?}"
      [ -s "$f" ] || return 1                 # 空でないこと
      verify_permissions "$f" || return 1     # 権限が 0600 であること
      # 有効期限が読めるなら、残り時間が短すぎないかも見る。
      ;;
    *)
      echo "[keyring] backend 未設定。経路を先に確定してください。" >&2
      return 2
      ;;
  esac
}
 
if ! preflight_credentials; then
  echo "[keyring] 認証プリフライト失敗。本処理に入らず終了します。" >&2
  exit 78   # EX_CONFIG として明示的に失敗させる
fi
echo "[keyring] 認証プリフライト OK"

この「本処理の直前に軽い検査を1回だけ挟む」型は、認証に限らず無人運用の土台になります。より一般的なプリフライトの組み方は スケジュール実行の直前に Antigravity CLI が本当に応答するかを1回だけ確かめる にまとめてあります。認証チェックはそのプリフライトの一項目として組み込むと、失敗の切り分けがきれいになります。

私の運用では、トークンの有効期限が残り 10 分を切っていたら本処理の前に先回りして更新する、という余白も持たせています。境界ぎりぎりのトークンで長い処理に入ると、途中で切れて 401 に落ちるからです。5 分でも足りることは多いのですが、複数サイトを順に処理する私のジョブでは 1 本が 10 分近くかかることがあり、そこに合わせて余白を決めました。この数字は、自分のジョブの最長実行時間から逆算するのが確実です。

複数マシンでトークンを同期すべきか

最後に、設計判断として一番迷うところに触れます。同じアカウントで 3 台のマシン（手元のデスクトップ、常駐サーバー、CI）を回すとき、トークンを 1 箇所に集めて同期したくなります。けれど私は、同期しない方針を採っています。

理由は二つあります。ひとつは、同期の仕組み自体が新しい攻撃面と障害点になること。トークンを配って回るパイプラインが壊れれば、全台が同時に沈黙します。もうひとつは、リフレッシュトークンの取り回しです。複数の場所から同じリフレッシュトークンを同時に使うと、片方の更新がもう片方のトークンを無効化し、互いに蹴り合う競合が起きることがあります。

代わりに、マシンごとに独立して認証を持たせ、それぞれが自分の保管庫（デスクトップはキーリング、サーバーと CI はファイル）でトークンを完結させます。台数が増えれば初期ログインの手間は増えますが、1 台の障害が他へ波及しない独立性のほうを、無人運用では優先したいと考えています。この判断は環境によって変わり得るので、あくまで私自身の現在地としてお読みください。

次のアクション

まず、いま無人で動いている実行環境で、この記事の最初のスニペット（has_secret_service）を 1 回だけ走らせてみてください。デスクトップでは「あり」、サーバーでは「なし」と出るはずです。その一行の差が、これまでの「サーバーだけ認証が切れる」の答えになっているかもしれません。そこから、保存経路を明示的に固定する設計へ一歩進められます。

保管場所という視点は、一度持つと認証まわりのログの読み方がはっきり変わります。私自身まだ運用しながら調整を続けている途中ですが、同じ静かな失敗に手を焼いている方の遠回りが少しでも減れば嬉しいです。お読みいただきありがとうございました。