プラグインサンドボックス

EmDash ではプラグインを trusted と sandboxed の 2 つの実行モードで動かせます。本ページでは各モードの動作、保護内容、デプロイ先ごとのセキュリティ上の意味を説明します。

実行モード

Trusted モード

Trusted プラグインは Astro サイトと同一プロセスで動きます。npm パッケージまたはローカルファイルから読み込み、astro.config.mjs で設定します。

import myPlugin from "@emdash-cms/plugin-analytics";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [myPlugin()],
		}),
	],
});

Trusted モードでは:

• Capabilities はドキュメントであり強制ではありません。 ["read:content"] を宣言していても、プロセス内のあらゆるものにアクセスできます。capabilities フィールドは管理者向けに、プラグインが 意図して 使う範囲を示します。
• リソース上限がありません。 CPU・メモリ・ネットワークは無制限で、問題のあるプラグインがリクエスト全体を止める可能性があります。
• プロセスへのフルアクセス。 プラグインは Astro サイトと同じ Node.js/Workers ランタイムを共有します。任意のモジュールの import、環境変数の参照、（Node.js では）ファイルシステムの読み書きが可能です。

Sandboxed モード（Cloudflare Workers）

Sandboxed プラグインは Cloudflare の Dynamic Worker Loader API による分離 V8 isolate 上で動きます。各プラグインは制限付きの独自 isolate を持ちます。

サンドボックスを有効にするには、Astro 設定で sandbox runner を指定します。

export default defineConfig({
	integrations: [
		emdash({
			sandboxRunner: "@emdash-cms/cloudflare/sandbox",
			sandboxed: [
				{
					manifest: seoPluginManifest,
					code: seoPluginCode,
				},
			],
		}),
	],
});

サンドボックスが強制すること

アーキテクチャ

Sandboxed プラグインは RPC ブリッジで EmDash と通信します。

┌─────────────────────┐     RPC      ┌──────────────────────┐
│  Plugin Isolate     │ ◄──────────► │  PluginBridge        │
│  (Worker Loader)    │   (binding)  │  (WorkerEntrypoint)  │
│                     │              │                      │
│  ctx.kv.get(k)      │──────────────│► kvGet(k)            │
│  ctx.content.list() │──────────────│► contentList()       │
│  ctx.http.fetch(u)  │──────────────│► httpFetch(u)        │
└─────────────────────┘              └──────────────────────┘
                                            │
                                            ▼
                                     ┌──────────────┐
                                     │  D1 / R2     │
                                     └──────────────┘

プラグインコードは V8 isolate 上で動き、ctx の各メソッドはブリッジへのプロキシです。ブリッジはメインの EmDash worker で動き、capability 検証のうえで実際の DB／ストレージ操作を行います。

Wrangler 設定

サンドボックスには Dynamic Worker Loader が必要です。wrangler.jsonc に追加します。

{
	"worker_loaders": [{ "binding": "LOADER" }],
	"r2_buckets": [{ "binding": "MEDIA", "bucket_name": "emdash-media" }],
	"d1_databases": [{ "binding": "DB", "database_name": "emdash" }]
}

Node.js デプロイ

Node.js（または Cloudflare 以外のプラットフォーム）にデプロイする場合:

• NoopSandboxRunner が使われ、isAvailable() === false を返します。
• Sandboxed プラグインの読み込みは SandboxNotAvailableError になります。
• すべてのプラグインは plugins 配列に Trusted として登録する必要があります。
• capability 宣言は情報のみで強制されません。

セキュリティ上の意味

Node.js デプロイの推奨

1. 信頼できるソースのプラグインのみ。 インストール前にソースを確認し、既知のメンテナーのプラグインを優先してください。
2. Capability をレビュー用チェックリストに。 強制されなくても意図した範囲の文書になります。ネットワーク不要なのに ["network:fetch"] があるのは不審です。
3. リソース使用を監視。 プロセス単位の監視（例: --max-old-space-size、ヘルスチェック）で暴走を検知してください。
4. 信頼できないプラグインは Cloudflare を検討。 出所不明のプラグイン（マーケットプレイス等）を動かすなら、サンドボックスのある Cloudflare Workers へデプロイしてください。

API は同じ、保証は異なる

実行モードにかかわらずプラグインコードは同じです。definePlugin() API、ctx の形、hooks、routes、storage の使い方は同じで、変わるのは 強制の有無 です。

// This plugin works in both trusted and sandboxed mode
export default definePlugin({
	id: "analytics",
	version: "1.0.0",
	capabilities: ["read:content", "network:fetch"],
	allowedHosts: ["api.analytics.example.com"],
	hooks: {
		"content:afterSave": async (event, ctx) => {
			// In trusted mode: ctx.http is always present (capabilities not enforced)
			// In sandboxed mode: ctx.http is present because "network:fetch" is declared
			await ctx.http.fetch("https://api.analytics.example.com/track", {
				method: "POST",
				body: JSON.stringify({ contentId: event.content.id }),
			});
		},
	},
});

ローカルでは Trusted で高速に開発・デバッグし、本番ではコード変更なしで Sandboxed に載せられることが狙いです。