デプロイと配布

このガイドでは、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

エクスポートパターン

src/index.ts

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

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

公式プラグインの基準

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

重要

• メタデータのofficial: trueフラグはUI補助情報のみ
• author.name: 'Authrim'は自己申告であり検証されない
• 公式ステータスは配布元のみで決定される

バージョニング

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

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 # すべてのチェックをスキップ

ビルトインの登録

ビルトインプラグインは起動時に自動的に登録されます：

// Authrimワーカーの初期化時
import { builtinPlugins } from '@authrim/ar-lib-plugin';

for (const plugin of builtinPlugins) {
  await loader.loadPlugin(plugin, ctx, await configStore.get(plugin.id, plugin.configSchema));
}

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

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

1. プラグインパッケージをインストール：

   pnpm add @your-org/authrim-plugin-example

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

   import { examplePlugin } from '@your-org/authrim-plugin-example';
   
   // ワーカー初期化時
   await loader.loadPlugin(examplePlugin, ctx, config);

3. 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

セキュリティ考慮事項

プラグイン作者向け

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

プラグインユーザー向け

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

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

Authrimが提供しないもの

• プラグインのセキュリティ監査
• 脆弱性スキャン
• 悪意のあるプラグインの検出

コミュニティプラグインは自己責任で使用してください。

更新通知

npmプラグイン

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

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

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

次のステップ

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