プラグインの設定

組み込みプラグインと動的 Runner インストールでは、設定の扱いが異なります。すべてのプラグインを KV の設定マージだけで説明することはできません。

組み込みのスキーマ

AuthrimPlugin は Zod スキーマを持ちます。Admin UI の説明にはフィールドの description を使い、実行時にも設定を検証します。

import { z } from 'zod';
const configSchema = z.object({
  apiKey: z.string().min(1).describe('プロバイダーの API キー'),
  timeout: z.number().int().min(1000).max(30000).default(10000),
});

スキーマを変換してフォームを生成できますが、すべての Zod の refinement や union が同等の UI になるわけではありません。Admin の更新処理は、組み込みメール・人間確認の設定を明示的に検証します。

設定の解決とスコープ

組み込みの経路では、初期設定・環境変数、全体の KV 設定、テナント別の上書きを順に組み合わせます。スキーマの既定値は解析時に適用します。主な KV キーは次のとおりです。

plugins:config:{pluginId}
plugins:config:{pluginId}:tenant:{tenantId}
plugins:enabled:{pluginId}
plugins:enabled:{pluginId}:tenant:{tenantId}

/api/admin/plugins/... は現在のテナントを使用します。システム管理者用の /api/admin/platform/plugins/... は全体操作や明示的なテナント選択を扱います。単に URL の先頭を交換すればよいのではなく、認可の範囲が異なります。

秘密情報

Admin の設定更新は、フィールド名または secret_fields の指定から秘密情報を判定します。秘密情報の保存には PLUGIN_ENCRYPTION_KEY が必要です。現在のヘルパーは KEY_MANAGER_SECRET で代用しません。暗号化できない場合は秘密情報不足のエラーで拒否し、平文のまま保存を続けることはありません。

応答内の秘密情報はマスクされます。表示されたマスクを新しい認証情報として保存せず、対応する UI・API の更新方法で既存値を保持してください。再帰的なマスクの深さは既定で 20 までで、それより深い値はマスクされずに残る場合があります。任意の深さまで保護されると考えず、設定を浅く保ち、入力構造も検証してください。

動的 Worker の認証情報

動的インストールでは、Runner が認証情報と設定のバージョンを管理します。Admin の config API は空でない文字列の認証情報を受け取り、期待するバージョンを付けて replaceDynamicPluginCredentials を呼びます。組み込みの任意オブジェクトのマージとは異なり、置き換えとして扱います。送信した認証情報を応答にそのまま返すことはありません。

認証情報は承認済みマニフェストのスロットに従います。マニフェストに送信先の完全一致ホストと、ヘッダー・Bearer の注入方法を指定し、ゲートウェイが承認済みリクエストに適用します。親 Worker の環境シークレットをプラグインへ渡す方式ではありません。

反映とリセット

設定変更では、プロバイダー情報の再反映やキャッシュの無効化が発生する場合があります。全体設定の変更がすべての経路に反映済みと判断する前に、結果の状態を確認してください。テナント設定のリセットは DELETE /api/admin/plugins/:id/config で、バックエンドによって効果が異なります。

設定とテストメールは Admin UI、コードや能力ポリシーの変更はデプロイを参照してください。