プラグインの能力と実行契約
ハンドラーを作る前に実行方式を選びます。組み込みレジストリの notifier.email と、Runner の notifier.send は同じ契約ではありません。
組み込み API
Section titled “組み込み API”ar-lib-plugin は、通知、IdP、認証方式の登録メソッドを提供します。組み込みの人間確認プラグインは設定を提供し、実行時の検証は Authrim の認証・Runner 経路が行います。実際の型は core/types.ts と core/registry.ts を参照してください。能力名を宣言するだけで、新しいハンドラーがログインフローへ接続されるわけではありません。
通知ハンドラーは send(notification): Promise<SendResult> を実装します。通知にはチャネル、宛先、本文、任意のメール・テンプレート情報があり、結果には success と任意の messageId、errorCode、retryable などがあります。本番のハンドラーでは本文や認証情報をログに出さないでください。
Runner の契約
Section titled “Runner の契約”| 能力・グループ | 現在の契約 |
|---|---|
notifier.send | 通知配送。非同期では暗号化済みの配信内容への参照を渡せます |
hook.account.lifecycle | アカウントイベント。現在のインストール解決処理が受け付けるのは account.created で、任意のライフサイクルイベントではありません |
human_verification.verify | 同期の人間確認判定 |
policy.decision | 同期のポリシー判定 |
flow.{hookName} | 対応する呼び出し経路で使う同期フローフック |
能力にはインストール、適合するポリシー、実際の呼び出し側が必要です。マニフェストで名前を宣言しても、公開 API やフローのノードが自動生成されるわけではありません。
同期処理の応答
Section titled “同期処理の応答”動的な同期フックは /internal/plugin-sync/{group} で JSON を受け取り、X-Authrim-Plugin-Contract ヘッダーで契約を識別します。正常な応答は HTTP 200 で、結果には次の二つのフィールドだけを含めます。
{"decision":"deny","reasonCode":"policy_rejected"}人間確認とポリシーでは allow・deny、フローでは continue・deny を使います。reasonCode は Runner の定義するコード形式に従います。SyncHookService は不正な応答、タイムアウト、実行不可を拒否として扱います。マニフェストの型に fail_open があることだけを根拠に、どの経路でも使用可能とは説明できません。
非同期処理の応答
Section titled “非同期処理の応答”動的な非同期フックの経路は /internal/plugin-hook です。テナント、インストール、能力、イベントのバージョン、冪等性キー、参照または解決済みの配信内容を受け取ります。成功時は HTTP 204 を返します。失敗時は同期ログイン応答ではなく、Runner の再試行・デッドレターポリシーで処理します。
外部への操作は再試行に耐える必要があります。下流の処理にも冪等性キーを使ってください。必要な処理が完了する前に 204 を返すと、処理が失われる可能性があります。
ホスト機能へのアクセス
Section titled “ホスト機能へのアクセス”Runner が承認済みのインターフェースとプラグイン用リソースを渡します。アカウントのメタデータ書き込みには、操作 ID と期待するバージョンを受け取る専用サービスを使います。アカウント DB に任意の SQL を実行する方式ではありません。外部通信にはゲートウェイのホスト・認証情報ポリシーが適用されます。