プラグインの作成

既存の AuthrimPlugin を使うコードを拡張する場合は組み込み方式を、Runner のフックと承認済みホスト機能を使う場合は動的 Worker を選びます。二つのインターフェースは互換ではありません。

組み込みプラグイン API

リポジトリに合わせて Node.js 22 以降・pnpm 9 と、対応する ar-lib-plugin を使います。AuthrimPlugin には id、version、capabilities、configSchema、meta、同期メソッドの register(registry, config) が必要です。任意の initialize は登録前に実行されます。対応するメソッドでハンドラーを登録し、呼び出し元 Worker のローダーに組み込みます。

型に対応した例は packages/ar-lib-plugin/src/builtin/ にあります。import やメタデータの登録だけでは、プロトコルフローへ接続されません。以前の例にあった仮の ^1.0.0 への依存指定は使用しないでください。

動的アカウントフックの最小例

この例はアカウント作成イベントを確認して応答するだけで、外部への操作は行いません。インストールと実行契約の確認用です。業務処理に使う前に、実際の処理、入力検証、冪等性の扱いを追加してください。

plugins/example-account-hook/authrim.plugin-worker-capabilities.json を作成します。

{
  "schemaVersion": 1,
  "pluginId": "example-account-hook",
  "backend": "dynamic_worker",
  "workerBundle": { "path": "bundle.json" },
  "resourceScope": "tenant",
  "visibility": "tenant",
  "bindings": [],
  "resources": [],
  "capabilities": [{
    "name": "hook.account.lifecycle",
    "execution": "async",
    "failurePolicy": "retry_async",
    "timeoutMs": 5000,
    "mutationScopes": [],
    "asyncOutbox": {
      "enabled": true,
      "succeededRetentionDays": 7,
      "deadLetterRetentionDays": 90
    }
  }],
  "credentials": [],
  "egressAllowedHosts": []
}

Worker のモジュールは次のように記述できます。

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (request.method !== 'POST' || url.pathname !== '/internal/plugin-hook') {
      return new Response(null, { status: 404 });
    }
    const event = await request.json();
    if (
      request.headers.get('X-Authrim-Plugin-Contract') !== 'hook-reference-v1' ||
      event.capability !== 'hook.account.lifecycle' ||
      event.eventType !== 'account.created' ||
      event.eventVersion !== 1
    ) {
      return new Response(null, { status: 400 });
    }
    return new Response(null, { status: 204 });
  }
};

マニフェストと同じ場所に bundle.json を作成します。schemaVersion: 1、同じ pluginId、検証した compatibilityDate、compatibilityFlags 配列、mainModule: "index.js"、modules: { "index.js": "<JavaScript 全文を JSON 文字列にしたもの>" } を持つ JSON オブジェクトです。JSON.stringify でシリアライズし、エスケープしていない複数行の JavaScript を JSON に貼り付けないでください。npm パッケージ名や URL ではなく、Worker のバンドルを渡します。

現在のローダーの上限は 64 モジュール、バンドルは 2 MiB です。依存コードは対応するモジュール内容にまとめ、実行時のパッケージインストールを前提にしないでください。

アクセス権を追加する

外部サービスを呼ぶ場合は、完全一致の送信先ホストと認証情報スロットを宣言します。必要に応じて、承認済みホストインターフェースやテナント用のプラグインリソースを宣言します。Core・PII への直接バインディングや Cloudflare 管理トークンは、マニフェスト検証で拒否されます。

非同期フックでは retry_async と outbox の有効化を揃えます。同期フックでは outbox を無効にし、対応する同期ポリシーを使用します。ポリシーの文字列を指定しても、呼び出し元の拒否動作を回避する権限にはなりません。

デプロイ前の確認

packages/setup/src/core/external-capabilities.ts のパーサーで検証し、Runner の契約に沿ってテストします。不正入力、失敗応答、タイムアウト、再試行、重複配送、宣言したホスト・リソース権限を越える操作を確認してください。対象機能の Runner のテストも参考になります。

次にデプロイと能力と実行契約を参照してください。