ものしり

第2部 使いこなす

第8章 プラグインの利用と開発(1)利用編

プラグインの選び方と使い方、そして作り方を学ぶ。

読了の目安 約 25 分 ・ EmDash 1.3.1 / Astro 7 系(確認日 2026-10-29)

この章で学ぶこと

  • EmDash のプラグインが「何をできるか」と、サンドボックス型 (sandboxed) とネイティブ型 (native) の違い
  • プラグインの入れ方 3 通り (レジストリ、sandboxed: []、plugins: []) と、選び分けの基準
  • インストール時の同意ダイアログに並ぶ権限 (capabilities) の読み方
  • サンドボックスが「守ること」と「守らないこと」
  • 更新、アンインストール、Marketplace からの移行、アップグレード時の破壊的変更
  • 供給網 (サプライチェーン) を含めた、利用者側のセキュリティの考え方

この章は 2 分冊の前半です。後半の「開発編」(08b-plugins-dev.md) では、プラグインを自作して公開するまでを扱います。基準バージョンは EmDash 1.3.1 (commit 403e4eb、2026-10-28)、確認日は 2026-10-29 です。コマンド、設定名、権限名は公式ドキュメントのとおりに記載しています。

注意: プラグインの公開 (publish) と、レジストリの検索クライアントの API は、公式ドキュメント上「Experimental (実験的)」と明記されています(レジストリからのインストール自体が Experimental と書かれているわけではありません)。API や記録の形式が予告なく変わる可能性があるため、関連パッケージは正確なバージョンに固定してください。


1. プラグインとは何か

なぜ理解が必要か

WordPress では、プラグインは PHP ファイルであり、サイトと同じ権限で動きます。EmDash のプラグインは「定義された拡張面 (extension surface)」を通じてのみ本体に作用する設計で、信頼の考え方が根本から違います。導入判断の前に、この違いを押さえてください。

できること

公式ドキュメントによれば、プラグインは次のことができます。コンテンツ保存・メディアアップロード・コメント・スケジュール・自身のライフサイクルへの反応、専用コレクションと KV へのデータ保存、管理画面のページやウィジェットの追加、/_emdash/api/plugins/<id>/<route> の API ルート、許可リスト付きの外部 HTTP、メール送信です。

プラグインは、管理画面の「プラグイン」で一覧できます(画面 8-1)。何も設定していないサイトでは、画面 8-1 のように空の状態で表示されます。

画面 8-1: プラグインの画面(プラグインが設定されていない状態)

2 つの形式

プラグインには 2 つの形式があります。

  • サンドボックス型: 設定されたサンドボックスランナーが管理する、別のランタイムで動きます。宣言した EmDash API にしか触れず、プラットフォームが対応する範囲でリソース制限がかかります。管理者がレジストリからインストールできます。サイト開発者が astro.config.mjs の sandboxed: [] に登録する方法もあります。
  • ネイティブ型: Astro サイトと同じプロセスで動きます。ランタイムへの完全なアクセスがあり、React 管理画面、Portable Text のレンダリングコンポーネント、公開ページへの HTML 注入ができます。npm からインストールし、astro.config.mjs を編集してデプロイし直す必要があります。

公式の方針は「ネイティブ固有の機能が要らないならサンドボックス型を選ぶ」です。

図 8-1 に、2つの形式の違いを示します。

図 8-1: サンドボックス型とネイティブ型の違い

注意: EmDash のプラグインは Astro のインテグレーションではありません。emdash() インテグレーションに渡すものです。両方の性質が必要な場合は、EmDash のフックも登録する Astro インテグレーションとして配布できる、と公式は述べています。

WordPress との違い (利用者の視点)

WordPress のプラグインは、公式ディレクトリで審査を受けても、実行時には PHP の全権限を持ちます。EmDash のサンドボックス型は、審査とは別に「実行時に何ができるか」を技術的に絞り、インストール時の同意ダイアログで権限を見せ、権限が増える更新には再同意を求めます。ただしネイティブ型はホストと同じアクセスを持つ、と公式は説明しています。筆者の見解として、WordPress のプラグインと同じ前提(信頼できるものだけ入れる)で扱うべきです。入手経路は、レジストリ (plugins.emdashcms.com) と npm です。


2. インストール方法の選び方

なぜ必要か

同じ「プラグインを入れる」でも、方法によって誰が・どこで・どの権限で動かすかが変わります。選択を誤ると、意図せず信頼の範囲を広げます。

3 通りの方法の比較

公式ドキュメントの比較表を、要点に絞って示します。

レジストリ npm + sandboxed: [] npm + plugins: []
インストールと更新 管理画面 依存追加とデプロイ 依存追加とデプロイ
実行場所 サンドボックスランナー サンドボックスランナー サイトのプロセス
EmDash へのアクセス 宣言された API のみ 宣言された API のみ 宣言された API に加え、プロセスへの直接アクセス
Node.js API と直接の fetch() 使えない 使えない 使える
React 管理画面コンポーネント 使えない 使えない 使える
Portable Text レンダラー 使えない 使えない 使える

図 8-2 に、3通りの方法で実行場所と使えることがどう変わるかをまとめます。

図 8-2: プラグインの3通りのインストール方法

選び分けは次のとおりです。

  1. まずレジストリにあるサンドボックス型を探す。
  2. React 管理画面、Portable Text レンダラー、ページフラグメント、プロセスへの直接アクセスが必須ならネイティブ型。
  3. 開発中のプラグインや、レジストリ外のサンドボックス型は sandboxed: [] で登録する。

ファーストパーティのプラグイン (Field Kit、AI Search など) は、ネイティブ型として plugins: [] に入れる例が公式にあります。

// astro.config.mjs (ネイティブ型の例: Field Kit)
import { fieldKitPlugin } from "@emdash-cms/plugin-field-kit";

emdash({ plugins: [fieldKitPlugin()] });

落とし穴

plugins: [] に移したサンドボックス型は、隔離もリソース制限もなく、fetch() の直接呼び出しや環境変数の読み取りが可能です。公式も「ランナーがないなら、すべてのプラグインを信頼面ではネイティブとして扱え」と述べています。


3. サンドボックスを使えるようにする

なぜ必要か

レジストリからのインストールも、sandboxed: [] の読み込みも、ランナーが前提です。ランナーがなければ、インストールと更新は SANDBOX_NOT_AVAILABLE で失敗します。レジストリの閲覧については、公式ドキュメントのファイル間で記述が異なります。plugin-sandbox と installing(Worker Loader の LOADER がない場合)は「閲覧は残る」(plugin-sandbox は「明示的に registry を設定した場合」)と書く一方、registry と configuration は「sandboxRunner を設定し sandbox が false でないときに既定でレジストリが有効になる」と書いています。本書は両方を示すにとどめ、ランナー未設定のサイトで閲覧できるかは、registry を明示した上でご自身の環境で確認してください。

前提条件

レジストリ経由のインストールには、次の 3 つが必要です。

  • plugins:manage 権限を持つ管理者アカウント
  • プラグインバンドルを保存する、設定済みのストレージ
  • 利用可能なサンドボックスランナー

どうやる

プラットフォームごとにランナーが違います。

Cloudflare Workers Node.js
sandboxRunner sandbox() (@emdash-cms/cloudflare) "@emdash-cms/sandbox-workerd/sandbox"
必要なもの Workers Paid プラン、worker_loaders バインディング LOADER、Worker のエントリから PluginBridge を export workerd パッケージ
強制される制限 CPU 時間、サブリクエスト、実時間 実時間のみ

Cloudflare では、各プラグインが Worker Loader で作られる Dynamic Worker として動きます。*-cloudflare テンプレートは PluginBridge の export を含みますが、LOADER バインディングはコメントアウトされています。新規プロジェクトが無料プランでデプロイできるようにするためです。有料プランで wrangler.jsonc の worker_loaders を有効化し、再ビルドします。

// wrangler.jsonc (抜粋)
{ "worker_loaders": [{ "binding": "LOADER" }] }
// astro.config.mjs (Cloudflare)
import { sandbox } from "@emdash-cms/cloudflare";
emdash({ sandboxRunner: sandbox() });

Node.js では、npm install @emdash-cms/sandbox-workerd workerd のあと、sandboxRunner: "@emdash-cms/sandbox-workerd/sandbox" を指定します。workerd は子プロセスとして起動し、サーバーの環境変数のうち PATH、HOME、TMPDIR、TMP、TEMP、LANG、LC_ALL だけを渡します。つまりサーバーの秘密情報は、既定ではサンドボックスに入りません。

リソース制限

CPU 時間 50 ms、サブリクエスト 10、実時間 30 秒、メモリ 128 MB が固定の制限です(設定項目なし)。Cloudflare は CPU 時間、サブリクエスト、実時間を強制します。Node.js のランナーが強制するのは実時間だけで、メモリはどちらもプラグイン単位では強制されません。

落とし穴

  • sandbox: false は sandboxed: [] をプロセス内で動かすデバッグ用です。公式は本番で使うなと明記し、Cloudflare Workers では起動が拒否されます。
  • Hyperdrive 構成ではサンドボックス型は使えません(DB ブリッジが DB という D1 バインディングを直接使うため)。
  • workerd が 60 秒以内に 5 回を超えてクラッシュすると、ランナーは再起動を諦めます(公式の本文は "more than five times within 60 seconds"、ログ例は "crashed 5 times in 60 seconds, giving up" で、文言が少し異なります。本書は本文に従います)。サーバーの再起動で復帰します。

4. レジストリからインストールする

なぜレジストリか

レジストリはサンドボックス型プラグインの公式カタログです。誰でも plugins.emdashcms.com で閲覧でき、管理者は管理画面の Registry から確認とインストールができます。sandboxRunner を設定し sandbox が false でないサイトでは、既定で https://registry.emdashcms.com が使われます(前述のとおり、ランナーなしでの閲覧可否は資料間で記述が異なります)。別の集約サーバー (aggregator) を使う、ポリシーを設定する、発見機能を無効にする場合は、設定リファレンスの registry を参照してください。

手順

  1. 管理画面で Registry を開く。
  2. タイトル、説明、または完全な公開名 (例: @example.com/my-gallery) で検索し、詳細ページを開く。
  3. リリースを選び、発行者、メタデータ、要求される権限、検証状況を確認する。
  4. Install を選ぶ。
  5. 同意ダイアログで、検証済みのリリース識別子と権限を確認し、承認する。

何が検証されるか

同意ダイアログを出す前に、EmDash は次を確認します。

  • ダウンロードしたバンドルのチェックサム、名前、バージョン、権限
  • 発行者がビルドの来歴 (provenance) を要求している場合は、その証跡

どれかが失敗するとインストールは止まります。更新時にも同じ検証を繰り返します。

公開名と発行者 (Atmosphere アカウント)

レジストリのプラグインの公開名は、発行者の現在の Atmosphere アカウントのハンドルとパッケージのスラッグでできています。たとえば example.com が公開した my-gallery は @example.com/my-gallery です。Atmosphere アカウントは、Bluesky などで使われる、利用者が所有する移植可能な ID です (AT Protocol)。EmDash は、読み込む前にハンドルを発行者の安定したアカウント識別子 (DID) に解決します。

ハンドルが発行者に解決されなくなったと確定すると、管理画面は INVALID HANDLE と表示し、新規インストールを止めます(既存のインストールは動き続けます)。一時的な失敗は Handle unavailable として表示されます。

ヒント: 公式の説明では、ハンドルは変わりうるので、安定した本人性は DID とスラッグの組です。自作のディレクトリを作る場合も、DID を安定した識別子として扱います(レジストリクライアントの説明)。


5. 権限 (capabilities) の読み方

なぜ重要か

同意ダイアログの権限一覧は、サンドボックス型プラグインについて EmDash が利用者に見せる「契約書」です(「ほぼ唯一」という強調は筆者の見解です)。承認した権限は、その操作を実際に許可します。公式の注意書きは、redirects:write を例に「訪問者の送り先を変えられる」と書いています。

権限の一覧

公式の権限リファレンスから、運用判断に重要なものを抜き出して整理します。

権限 与えられるアクセス 運用上の注目点
content:read コンテンツの読み取り 公式の権限リファレンスに下書きの扱いの明記はない(getPublicUrl() は下書きで null)
content:write 作成・更新・削除(read を含意) 自分のものに限らず全コンテンツを編集できる
content:publish 公開・非公開・予約 公開状態を変えられる
redirects:write リダイレクトルール 訪問者の送り先を変えられる
media:read / media:bytes:read / media:metadata:write メタデータの読み取り / ファイルの中身 / メタデータの書き込み この3つは互いを含意しない
media:write アップロード・削除 互換のため media:read を含意(上の3つとは別の権限)
comments:read コメント(名前・メール・IP ハッシュ等) 個人情報を含む
users:read ユーザー検索 コメント系フックの登録にも必要
network:request 宣言したホストへの HTTP ダイアログでホスト名を確認できる
network:request:unrestricted 任意のホストへの HTTP 宛先を運用者が実行時に入力する用途向け
email:send メール送信 送信プロバイダーが別途必要

ほかに schema:read、taxonomies:*、bylines:read、content:revisions:read、content:restore、comments:moderate、hooks.*:register などがあります(全一覧は「権限とセキュリティ」)。

覚えておきたい読み方のポイントは次のとおりです。

  • 含意 (implication): content:write は content:read を含みます。両方が並んでいなくても不自然ではありません。
  • 分離: メディアの media:read、media:bytes:read、media:metadata:write は互いを含意しません。タクソノミーや執筆者(bylines)の権限もコンテンツ権限とは別です。
  • network:request と network:request:unrestricted: 前者は許可ホストが固定で、同意ダイアログに名前が出ます。後者は宛先が固定されません。固定の外部 API に接続するだけのプラグインが後者を要求していたら、疑ってください。
  • MCP ツール: プラグインが MCP (Model Context Protocol) ツールとして公開するルートを宣言した場合、ダイアログに表示されます。
  • 公開ルート: 認証なしで呼べるルートを持つプラグインのインストールにも同意が必要です。

更新時の再同意

次の場合、更新は再同意を求めます。EmDash は承認されるまで、インストール済みのバージョンを置き換えません。

  • 権限が増える
  • MCP ツールが増える
  • ルートが認証付きから公開に変わる

権限の実害を見積もる

公式が強調するように、権限は粗い粒度です。「content:write を持つプラグインは、自分が作成したものに限らず、あらゆるコンテンツを書き換えられる」という前提で見てください。下の表は、筆者の見解として、導入前の自問を整理したものです。

問い 見るポイント
機能に対して権限は最小か 「画像の alt を補うだけ」なのに media:write や content:write を要求していないか
外部通信はあるか network:request の許可ホストは機能と一致するか
個人情報に触れるか comments:read、users:read の理由が説明されているか
公開ルートはあるか 認証なしでの呼び出しが何に使われるか

6. 更新、アンインストール、Marketplace からの移行

更新

  1. 管理画面の Plugins を開く。
  2. Check for updates を選ぶ。
  3. 更新のあるレジストリ上のプラグインで Update を選ぶ。
  4. 同意ダイアログを確認して承認する。

明示的な更新は前進のみです。最新リリースに追従している場合は、発行者が最新リリースを取り下げると、ロールバックされることがあります。それ以外のタイミングで古いリリースに戻したい場合は、アンインストールしてから、レジストリのページでそのバージョンをインストールし直します。

アンインストール

Plugins で対象を展開し、Uninstall を選びます。バンドルが削除され、読み込まれなくなります。プラグインのストレージデータは既定で残ります。再インストールで使わないと確信できるときだけ、Also delete plugin storage data を選んでください。

Marketplace からレジストリへ

以前の Marketplace 方式のサイトでは、アップグレード後、新しいプラグインの発見はレジストリに移ります。既存の Marketplace プラグインは、marketplace オプションが設定されている間、動作・更新・アンインストールができます。

移行の手順は次のとおりです。

  1. サンドボックスを用意する (sandboxRunner を設定し、sandbox を false にしない)。
  2. EmDash をアップグレードし、Plugins で Check for updates を実行して、Marketplace と表示されたプラグインの必要な更新を適用する。
  3. 各プラグインについて、一時的に維持するか、レジストリのパッケージに置き換えるか、アンインストールするかを決める。
  4. すべて置き換えるかアンインストールしたら、marketplace オプションを削除して再起動する。

注意: Marketplace とレジストリのインストールは、別の ID、バンドル、ストレージを持ちます。レジストリのパッケージを入れても、Marketplace 版の設定やデータはコピーされません。データを持つプラグインの置き換えは、発行者の移行手順に従ってください。更新が必要な Marketplace プラグインが残っている間に marketplace を削除すると、以後のリリースを取得できなくなります。

npm のプラグインを更新するとき

設定管理のプラグインは、依存関係を更新してデプロイすることで更新されます。公式のアップグレードガイドによれば、plugin-audit-log、plugin-webhook-notifier、plugin-atproto の 3 つは、名前付き export とファクトリ呼び出しをやめ、デフォルト export(plugins: [auditLog] のように呼び出しなし)になりました。後者 2 つはサンドボックス型なので sandboxed: に入れます。ファクトリ引数だった設定は管理画面の設定ページへ移っています。Field Kit は fieldKitPlugin() のままです。


7. セキュリティ上の注意

なぜ独立した節にするか

プラグインは、サイト運用で外部コードを取り込む数少ない入口です。導入の判断基準を 3 つの観点で整理します。ここで述べる評価は公式の記述に基づきますが、運用への当てはめは筆者の見解です。

観点 1: 最小権限

  • 同意ダイアログの権限は、そのプラグインの機能説明と突き合わせる。
  • network:request:unrestricted は、宛先を運用者が実行時に決めるプラグイン(Webhook 送信など)に限る。
  • 更新で権限が増えるときは、新機能の説明がなければ承認しない。EmDash は再同意を強制しますが、承認の判断は利用者の責任です。
  • ネイティブ型には権限の同意の仕組みがありません。公式も「ネイティブのインストールには権限同意のプロンプトがない」と述べています。READMEの宣言を読み、コードを自分で確認する必要があります。

観点 2: サンドボックスの境界

サンドボックスが強制するもの(公式の記述)は次のとおりです。

  • 能力宣言のない ctx.* は存在しない(呼べない)。
  • ストレージと KV はプラグイン ID に閉じ、他のプラグインの領域は読めない。
  • 直接の fetch() は遮断され、ctx.http.fetch() だけが許可ホストの検証を通る。
  • 環境変数、ファイルシステム、プラットフォームのバインディングは見えない。
  • CPU、サブリクエスト、実時間の制限 (Cloudflare)。

サンドボックスが強制しない、と公式が書いていることも重要です。

  • 許可された権限の中での振る舞い: content:write ならあらゆるコンテンツを書き換えられる。
  • 編集ロック: プログラムからの書き込みは、編集者が持つ助言ロックでは止まらない。
  • サイドチャネル: タイミング、ログ出力、保存データは、ホスト環境へ適切にアクセスできる人から見える。サンドボックスは運用者に対する機密性の境界ではない。
  • ランナー不在時: plugins: [] に移すとネイティブ同等の信頼が必要になる。

図 8-3 に、サンドボックスが強制するものと強制しないものを並べます。

図 8-3: サンドボックスが強制するものとしないもの

network:request:unrestricted を持つプラグインについても、公式は次のように述べています。HTTP と HTTPS のみ、内部ホストとプライベートアドレスのブロック、リダイレクトごとの再検査、オリジンをまたぐリダイレクトでの認証ヘッダーの削除は適用されます。ただし、宛先の制限そのものはなくなります。

観点 3: サプライチェーン

レジストリ経由のインストールでは、次の仕組みが働きます。

段階 仕組み
発行者の本人性 Atmosphere アカウントの DID に結びつく。ハンドルが変わっても DID は不変
ダウンロードの完全性 チェックサム、名前、バージョン、権限の再検証
来歴 発行者が要求した場合、ビルドの来歴(GitHub Actions のビルド証明)を検証
取り下げ 取り下げられたリリースはラベルで除外される。最新追従の更新は戻ることがある
変更の再同意 権限、MCP ツール、公開ルートの増加で再承認

ただし、これらは「誰が・どのバイト列を」の保証であり、「そのコードが安全か」の保証ではありません。レジストリは発見のための索引で、集約サーバーは自分が書いたわけではない記録を中継するため、信頼しない索引として扱われています(公式のレジストリクライアントの記述)。

npm 経由のプラグイン(sandboxed: []、plugins: [])は、レジストリの検証を通りません。通常の npm パッケージと同じ供給網のリスク(乗っ取り、依存関係の混入)があるため、バージョンの固定、ロックファイルの運用、公開元の確認が必要です。特に plugins: [] のネイティブ型は、公式が「インストールするのは信頼できる発行者のものだけ」と明記しています。

セキュリティ: プラグインのバージョンを変えるときは、権限の差分を確認する習慣を付けてください。レジストリ経由なら同意ダイアログがそれを見せてくれます。npm 経由では、自分で変更履歴を読む必要があります。

セキュリティ: EMDASH_ENCRYPTION_KEY を失うと、暗号化されたプラグイン設定(シークレット)は復号できなくなります。データベースのバックアップだけでは復旧できないので、キーの全リストをシークレットマネージャーなどに別途保管してください。


まとめ

  • プラグインはサンドボックス型とネイティブ型に分かれ、既定の選択はサンドボックス型。
  • レジストリからの導入には、管理者権限、ストレージ、サンドボックスランナーが要る。Cloudflare では Workers Paid と LOADER、Node.js では workerd が要る。
  • 同意ダイアログの権限は契約書として読む。粒度は粗く、許可された範囲での振る舞いは制限されない。
  • 更新は再同意付き。データはアンインストールしても既定で残る。
  • ネイティブ型と、plugins: [] に移したサンドボックス型は、WordPress のプラグインと同様にホストと同じ信頼で扱う。

理解度チェック

  1. レジストリ経由のインストールを可能にするために、Cloudflare Workers で必要な設定を 3 つ挙げてください。
  2. content:write を持つサンドボックス型プラグインがサンドボックス上で「できないこと」と「できてしまうこと」を、それぞれ 1 つ挙げてください。
  3. プラグインの更新が再同意を求める条件を 3 つ挙げてください。
  4. ランナーが使えない環境で、sandboxed: [] のプラグインを plugins: [] に移すと何が変わりますか。
  5. Node.js のサンドボックスランナーで、強制される制限はどれですか。Cloudflare との違いも答えてください。
  6. アンインストールしたプラグインのデータは、既定でどうなりますか。

答え

  1. Workers Paid プラン、worker_loaders バインディング LOADER、Worker エントリからの PluginBridge の export(emdash() に sandboxRunner: sandbox() を設定することも必要)。
  2. できないこと: 直接の fetch()、環境変数の読み取り、他のプラグインのストレージの読み取りなど。できてしまうこと: 自分が作っていない他のコンテンツも含む、あらゆるコンテンツの書き換え。
  3. 権限が増える、MCP ツールが増える、ルートが認証付きから公開に変わる。
  4. 隔離とリソース制限がなくなり、fetch() の直接呼び出しや環境変数の読み取りが可能になる。能力宣言は ctx の API を絞り続ける。
  5. 実時間 (30 秒) のみ。Cloudflare は CPU 時間 (50 ms) とサブリクエスト (10) も強制する。
  6. 残る。Also delete plugin storage data を選んだ場合だけ削除される。

出典

公式ドキュメント(URL は 2026-10-29 に実在(HTTP 200)を確認しました)。

  • プラグインの概要・導入: https://docs.emdashcms.com/plugins/overview/ 、https://docs.emdashcms.com/plugins/installing/ 、https://docs.emdashcms.com/plugins/registry/ 、https://docs.emdashcms.com/plugins/migrate-from-marketplace/ 、https://docs.emdashcms.com/plugins/upgrading-sites/
  • 形式と権限: https://docs.emdashcms.com/plugins/creating-plugins/choosing-a-format/ 、https://docs.emdashcms.com/plugins/creating-plugins/capabilities/
  • サンドボックス: https://docs.emdashcms.com/deployment/plugin-sandbox/