swain-keys

swain-keys

プロジェクトごとの Git 署名と認証用キーのプロビジョニングです。

それぞれに適した署名方式で、2 種類の Forge に対応しています。

• GitHub — gh ssh-key add による SSH 署名。
• Forgejo — fj user gpg upload による GPG 署名。

Forge は origin リモート URL から自動検出されます。上書きするには SWAIN_FORGE を設定してください。

呼び出されたとき

スクリプトを特定して実行します。パスはこのスキルのディレクトリを基準とする scripts/swain-keys.sh です。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SCRIPT="$REPO_ROOT/.agents/bin/swain-keys.sh"

パスの検索に失敗した場合は、**/swain-keys/scripts/swain-keys.sh をグロブ検索します。

ワークフロー

デフォルト（引数なし、または「set up keys」）

まず --status を実行して現在の状態を表示します。

bash "$SCRIPT" --status

キーがすべてプロビジョニングされていない場合は、プロビジョニングを続行するかユーザーに確認します。

プロビジョニング（「provision keys」、「configure signing」、「set up SSH」）

プロビジョニングの全手順を実行します。

bash "$SCRIPT" --provision

GitHub の場合、スクリプトは次の処理を行います。

1. Git リモートまたはディレクトリからプロジェクト名を取得します。
2. 存在しない場合は ~/.ssh/<project>_signing を生成します（ed25519、パスフレーズなし）。
3. 設定済みの Git メールアドレスを使って ~/.ssh/allowed_signers_<project> を作成します。
4. 認証と署名の両方に使用する公開鍵を、gh ssh-key add で GitHub に追加します。
5. グローバル SSH エージェントを経由せず、GitHub SSH を ssh.github.com:443 にルーティングするホストエイリアスを設定した ~/.ssh/config.d/<project>.conf を作成します。
6. Git リモート URL をプロジェクト固有のホストエイリアスを使うように更新します。
7. SSH によるコミットとタグの署名用に、ローカル Git 設定を行います。
8. SSH 接続と署名機能を検証します。

Forgejo の場合、スクリプトは次の処理を行います。

1. Git リモートまたはディレクトリからプロジェクト名を取得します。
2. 存在しない場合は、OpenPGP ed25519 鍵を gpg --batch --generate-key で生成します（対話なし、%no-protection）。
3. GPG 公開鍵を fj user gpg upload で Forgejo にアップロードします。
4. OpenPGP 署名用にローカル Git を設定し（gpg.format=openpgp）、グローバル SSH 署名設定を上書きします。
5. リモート URL は変更しません（Forgejo の SSH 認証はユーザーの既存の SSH 設定で処理されます）。
6. 署名機能と Forgejo の GPG 鍵の状態を検証します。

ステータス（「key status」、「check keys」）

bash "$SCRIPT" --status

Forge の種類、鍵の状態、Git 設定、Forge への登録状態を表示します。該当する場合は「Forgejo に署名鍵として GPG 鍵が登録されています（検証済み：true）」と報告します。

検証（「verify keys」、「test signing」）

bash "$SCRIPT" --verify

署名機能と Forge の鍵登録をテストします。Forgejo の場合、Forge 上で GPG 鍵の Can Sign: true を確認します。

環境変数

• SWAIN_FORGE — 自動検出を上書きするには、github または forgejo を設定します。
• SWAIN_FORGEJO_HOST — Forgejo インスタンスの URL を設定します（例：https://codeberg.org）。origin に localhost が含まれる場合のデフォルトは http://localhost:3000 です。

スコープの更新への対応

GitHub

スコープが不足しているために gh ssh-key add が失敗すると、スクリプトは対応が必要であることを示すメッセージを出力します。その場合は、次の手順を実行します。

1. 追加の GitHub スコープを承認する必要があることをユーザーに伝えます。
2. 次のコマンドを提示します：gh auth refresh -s admin:public_key,admin:ssh_signing_key。
3. OAuth 用のブラウザーが開きます。操作には人間の介入が必要です。
4. ユーザーの確認後、--provision を再実行します（冪等性があるため、完了済みの手順はスキップされます）。

Forgejo

fj user gpg upload が失敗した場合は、fj が認証済みか確認します。

fj auth login

その後、--provision を再実行します。

swain-init との連携

swain-init から呼び出された場合は、ステータス確認を先に行うフローを使わず、直接 --provision を実行します。「続行しますか？」の確認は swain-init が行います。

セッションのブックマーク

プロビジョニング後、ブックマークを更新します：bash "$REPO_ROOT/.agents/bin/swain-bookmark.sh" "Provisioned keys for {project}"

エラー処理

• git リポジトリ内にいない場合：明確なメッセージを表示して失敗します。
• gh CLI が利用できない場合（GitHub）：GitHub の登録手順をスキップし、キーを手動で追加するようユーザーに警告します。
• fj CLI が利用できない場合（Forgejo）：Forgejo の登録をスキップし、GPG キーを手動でアップロードするようユーザーに警告します。
• gpg がインストールされていない場合（Forgejo）：インストール手順を表示して失敗します。
• git のメールアドレスが設定されていない場合：早い段階で失敗し、設定手順を表示します。
• すべての手順は冪等です。問題を修正した後に再実行しても安全です。