デプロイと配布

このガイドでは、Authrimプラグインのパッケージング、配布、デプロイ方法を説明します。

配布方法

方法	対象	特徴
npmパッケージ	パブリックプラグイン	バージョン管理、依存関係の解決
モノレポ組み込み	公式プラグイン	Authrimと同時リリース
プライベートnpm	エンタープライズプラグイン	npm機構を活用しつつプライベート維持
ローカルファイル	開発/テスト	最も柔軟

npmパッケージ構造

推奨package.json

{
  "name": "@your-org/authrim-plugin-example",
  "version": "1.0.0",
  "description": "Authrim用のサンプルプラグイン",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "test": "vitest",
    "prepublishOnly": "npm run build"
  },
  "peerDependencies": {
    "@authrim/ar-lib-plugin": "^1.0.0",
    "zod": "^3.0.0"
  },
  "devDependencies": {
    "@authrim/ar-lib-plugin": "^1.0.0",
    "tsup": "^8.0.0",
    "typescript": "^5.0.0",
    "vitest": "^1.0.0",
    "zod": "^3.0.0"
  },
  "keywords": [
    "authrim",
    "authrim-plugin",
    "authentication",
    "notification"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/authrim-plugin-example"
  }
}

プロジェクト構造

authrim-plugin-example/
├── src/
│   ├── index.ts        # プラグインのエクスポート
│   ├── handler.ts      # ハンドラー実装
│   └── config.ts       # 設定スキーマ
├── test/
│   ├── index.test.ts
│   └── handler.test.ts
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── README.md
└── LICENSE

エクスポートパターン

export { myPlugin } from './plugin';
export type { MyPluginConfig } from './config';

// 便宜上のデフォルトエクスポート
export { myPlugin as default } from './plugin';

公式プラグインの基準

条件	判定	信頼レベル
`ar-lib-plugin/builtin/`に組み込み	公式	`official`
npm `@authrim/*`スコープ	公式	`official`
その他のソース	コミュニティ	`community`

バージョニング

セマンティックバージョニングに従います：

Major.Minor.Patch（例：1.5.2）
   │       │      └── バグ修正（後方互換）
   │       └────────── 新機能（後方互換）
   └────────────────── 破壊的変更

メタデータ内のプラグインバージョン

export const myPlugin: AuthrimPlugin<Config> = {
  id: 'my-plugin',
  version: '1.0.0',  // package.jsonと同期を保つ
  // ...
};

互換性宣言

メタデータでAuthrimバージョンの互換性を宣言します：

meta: {
  name: 'My Plugin',
  description: '...',
  category: 'notification',

  // 互換性
  minAuthrimVersion: '1.0.0',     // 必要な最小バージョン
  maxAuthrimVersion: '1.999.999', // オプションの最大（通常はメジャーバンプ時に設定）
}

互換性チェックの動作

状態	レベル	動作
`minAuthrimVersion`より古い	警告	ログ出力、続行
`maxAuthrimVersion`より新しい	警告	ログ出力、続行
`stability: 'deprecated'`	警告	非推奨警告
本番で`stability: 'alpha'`	警告	本番警告

デフォルトでは警告のみが発行され、プラグインのロードは続行されます。これは宣言が過度に保守的な場合を考慮しています。

環境変数による制御

# 互換性チェックレベル
PLUGIN_COMPATIBILITY_CHECK=warn   # デフォルト：警告して続行
PLUGIN_COMPATIBILITY_CHECK=error  # 非互換時に停止
PLUGIN_COMPATIBILITY_CHECK=ignore # すべてのチェックをスキップ

ビルトインの登録

Built-in plugin metadataは、Admin UIとPlugin Management APIがdiscoverできるようにplugin registry KVへ登録されます：

import { registerBuiltinPlugins } from '@authrim/ar-lib-plugin';

await registerBuiltinPlugins(env.SETTINGS);

現在のbuilt-in registration setは ar-lib-plugin がexportするnotifier plugin、つまり notifier-console, notifier-cloudflare, notifier-resend です。

Runtime loadingはWorkerのplugin context loaderで別途設定します：

import { createPluginLoader, pluginContextMiddleware } from '@authrim/ar-lib-core';
import { cloudflareEmailPlugin, resendEmailPlugin } from '@authrim/ar-lib-plugin';

app.use(
  '*',
  pluginContextMiddleware({
    loadPlugins: createPluginLoader([
      { plugin: cloudflareEmailPlugin },
      { plugin: resendEmailPlugin },
    ]),
  })
);

npmプラグインのインストール

npm経由で配布されるコミュニティプラグインの場合：

プラグインパッケージをインストール：
Terminal window
```
pnpm add @your-org/authrim-plugin-example
```

ワーカー初期化時に登録：

import { examplePlugin } from '@your-org/authrim-plugin-example';

// ワーカー初期化時
await loader.loadPlugin(examplePlugin, ctx, config);

runtime plugin loaderへ追加し、Admin APIまたは環境変数で設定

ローカル開発

開発とテスト用：

// ローカルパスからインポート
import { myPlugin } from './plugins/my-plugin';

// 初期化時に登録
await loader.loadPlugin(myPlugin, ctx, {
  apiKey: 'test-key',
  endpoint: 'http://localhost:3000',
});

公開チェックリスト

プラグインを公開する前に：

テストパス: npm test
型コンパイル: npm run build
README完備: インストール、設定、例
ライセンスファイル: 適切なライセンスを含める（MIT推奨）
Changelog: バージョン間の変更を文書化
Peer dependencies: @authrim/ar-lib-pluginとzodを宣言
Keywords: authrimとauthrim-pluginを含める
メタデータ完備: metaの全必須フィールド

READMEテンプレート

# Authrim Plugin: Example

Authrim用のサンプル通知プラグイン。

## インストール

\`\`\`bash
pnpm add @your-org/authrim-plugin-example
\`\`\`

## 設定

| フィールド | 型 | 必須 | デフォルト | 説明 |
|-----------|-----|------|---------|------|
| `apiKey` | string | ○ | - | あなたのAPIキー |
| `endpoint` | string | - | `https://api.example.com` | APIエンドポイント |
| `timeout` | number | - | `10000` | リクエストタイムアウト（ms） |

### 環境変数

\`\`\`bash
PLUGIN_EXAMPLE_CONFIG='{"apiKey":"your-key"}'
\`\`\`

### Admin API

\`\`\`bash
curl -X PUT "/api/admin/plugins/example/config" \
  -H "Authorization: Bearer {token}" \
  -d '{"config": {"apiKey": "your-key"}}'
\`\`\`

## 使用方法

このプラグインは`notifier.example`能力を提供します。

## ライセンス

MIT

セキュリティ考慮事項

プラグイン作者向け

機密情報をログに出力しない: APIキーやトークンをログに出力しない
URLを検証: SSRF攻撃を防止
タイムアウトを設定: リソース枯渇を防止
エラーを処理: スローせず構造化エラーを返す
依存関係を監査: 定期的にレビューと更新

プラグインユーザー向け

プラグインをインストールする前に：

作者の信頼性: 誰が開発したか？
ソースコードレビュー: 可能であればレビュー
依存関係の監査: 疑わしいパッケージをチェック
活動状況の確認: メンテナンスされているか？

更新通知

npmプラグイン

Admin UIにバージョン情報を表示
新バージョンの可用性は参考情報として表示
更新の決定と実行はユーザーの責任

ローカル/プライベートプラグイン

バージョン文字列のみ表示
自動更新通知機能なし

次のステップ

Admin UI管理 - コンソールでのプラグイン管理
プラグイン管理API - プラグイン操作のAPIリファレンス