ものしり

第2部 使いこなす

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

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

この章で学ぶこと

  • サンドボックス型とネイティブ型のどちらで作るかの判断基準
  • emdash-plugin CLI で最初のサンドボックス型プラグインを作り、動かすまで
  • マニフェスト (emdash-plugin.jsonc)、フック、API ルート、ストレージ、設定、権限の書き方
  • Block Kit による管理画面と、ネイティブ型の React 管理画面・ページフラグメント
  • テスト、レジストリへの公開、GitHub Actions による委任リリース
  • WordPress のプラグイン開発との対応

前半の「利用編」(08a-plugins-use.md) の知識を前提にします。基準バージョンは EmDash 1.3.1 (commit 403e4eb、2026-10-28)、確認日は 2026-10-29 です。内容は公式ドキュメントに基づきます。「筆者の見解」と書いた箇所だけが筆者の判断です。

注意: プラグインの公開(レジストリ、委任リリース)は公式が Experimental と明記しています。@emdash-cms/plugin-cli は正確なバージョンに固定してください。


1. 形式の選び方

なぜ最初に決めるか

形式によって、書き方、配布方法、信頼の境界がすべて変わります。後から変えると書き直しになるため、書き始める前に決めます。

比較

サンドボックス型 ネイティブ型
記述 emdash-plugin.jsonc と src/plugin.ts definePlugin() のディスクリプター
配布 レジストリ(署名付きリリース) npm
実行場所 サンドボックスランナーの隔離環境 サイトと同じプロセス
管理画面 Block Kit(JSON で記述) React、または Block Kit
設定画面 Block Kit と ctx.settings admin.settingsSchema(自動生成フォーム)または Block Kit
Portable Text レンダラー 不可 componentsEntry で Astro コンポーネントを提供
ページへの出力 page:metadata(meta、property、許可リストの link、JSON-LD) page:metadata と page:fragments
コンストラクターのオプション なし(KV から実行時に読む) ディスクリプターの options

判断基準

公式の方針は、サンドボックス型を既定にし、次のいずれかが要るときだけネイティブ型にする、です。

  1. React の管理画面ページやウィジェットが必要。
  2. 独自の Portable Text ブロックの Astro レンダリングコンポーネントが必要。
  3. 訪問者のブラウザへ生の HTML、スクリプト、スタイルシートを注入する必要がある(page:fragments)。

構造化データや SEO メタデータで足りるなら page:metadata を使い、サンドボックスに留まります。stylesheet や prefetch のようなリソース読み込みの rel は、意図的に許可されていません。

図 8-4 に示すように、ネイティブ型を選ぶのは、いずれかの条件に当てはまるときだけです。

図 8-4: ネイティブ型を選ぶ判断

ネイティブ型のコストも公式に列挙されています。

  • すべてのサイトが npm 追加、設定編集、再デプロイを行う。
  • 隔離がない。フック内の未処理の拒否 (unhandled rejection) が、周囲のリクエストを巻き込む。
  • 利用者に信頼の負担がかかる。能力宣言だけでは、コードにできることのすべてを示せない。

ヒント: 両形式は PluginContext、ストレージ、KV、ほとんどのフック名を共有します。違いはシグネチャで、サンドボックス型のフックは (event, ctx)、ルートは (routeCtx, ctx) の 2 引数、ネイティブ型のルートは 1 つのコンテキストオブジェクトを受け取ります。


2. 最初のサンドボックス型プラグイン

準備

Node.js と pnpm、サンドボックスランナーを設定したサイト、マニフェストの publisher に書く Atmosphere アカウントのハンドルか DID が必要です。

雛形の作成

pnpm dlx @emdash-cms/plugin-cli init save-log
cd save-log
pnpm install

init は発行者、作者、セキュリティ連絡先、ソースリポジトリを尋ね、emdash-plugin.jsonc、src/plugin.ts、package.json、tests/plugin.test.ts、vitest.config.ts、AGENTS.md などを作ります。.claude/ と .agents/ には、AI コーディングエージェント向けの指示とスキルへのリンクが入ります。

マニフェストと実装

マニフェストには slug、publisher、capabilities: ["content:read"](content:afterSave が保存内容を渡すため)、storage: { events: { indexes: ["savedAt"] } } を宣言します。

// src/plugin.ts
import type { SandboxedPlugin } from "emdash/plugin";

const plugin: SandboxedPlugin = {
  hooks: {
    "content:afterSave": {
      handler: async (event, ctx) => {
        const savedAt = new Date().toISOString();
        const contentId = String(event.content.id);
        await ctx.storage.events.put(`${savedAt}:${contentId}`, {
          savedAt, collection: event.collection, contentId,
        });
      },
    },
  },
  routes: {
    health: {
      public: true,
      handler: async (_routeCtx, ctx) => ({ ok: true, plugin: ctx.plugin.id }),
    },
  },
};
export default plugin;

SandboxedPlugin 型の注釈で、event と ctx の型がフック名から推論されます。ランタイムの emdash への依存は増えません。

動かす

雛形のテスト tests/plugin.test.ts は元の hello ルートを呼ぶため、src/plugin.ts を health ルートに差し替えたら、テストも書き換えます。そのままだと test が失敗します。公式の例は次のとおりです。

import { afterEach, describe, expect, it } from "vitest";
import { createPluginTestHost, type PluginTestHost } from "@emdash-cms/plugin-test";

let host: PluginTestHost | undefined;
afterEach(async () => {
  await host?.dispose();
  host = undefined;
});

describe("health route", () => {
  it("identifies the running plugin", async () => {
    host = await createPluginTestHost();
    const result = await host.invokeRoute("health");
    expect(result).toEqual({ ok: true, plugin: "save-log" });
  });
});

テストは createPluginTestHost() でプラグインをビルドし、Worker Loader と PluginBridge 経由でルートを呼びます。書き換えたら、次を実行します。

pnpm run validate && pnpm run typecheck && pnpm run test && pnpm run build

build は dist/plugin.mjs(フックとルート)、dist/manifest.json、dist/index.mjs(サイトが取り込むデフォルト export のディスクリプター)を作ります。dist/ は生成物なので、Git に入れません。

サイト側では pnpm add file:../save-log で追加し、sandboxed: [saveLog] に登録します。プラグインのディレクトリで pnpm dev(変更を監視して再ビルド)、サイトで開発サーバーを起動し、/_emdash/api/plugins/save-log/health を開くと、{ "success": true, "data": { ... } } の形式で返ります。

注意: ランナーが使えないと、sandboxed のプラグインは黙ってスキップされます。起動時の警告を確認してください。


3. マニフェスト

役割

emdash-plugin.jsonc は、識別情報、信頼の契約、レジストリ掲載情報を 1 つに持つファイルです。JSONC なのでコメントと末尾カンマが使えます。$schema を残すとエディターが補完します。

主なフィールド

必須は slug(小文字始まり、[a-z0-9_-]、最大 64 文字)、publisher、license、author(s)、security(Contacts) です。version は package.json と一致させるか片方にだけ書きます(両方なければビルド失敗)。信頼の契約は capabilities、allowedHosts、storage(既定は空)、管理画面は admin.pages / admin.widgets(宣言したら admin ルートが必須)、リリース情報は repo、release.requires(EmDash と Astro のバージョン範囲)、release.artifacts です。

slug は npm パッケージ名とは別物です。@example/plugin-gallery というパッケージでも、slug は gallery にします。

信頼の契約は変えたら新バージョン

インストール済みのサイトは、以前の宣言に同意しています。capabilities、allowedHosts、storage を変えるときは新バージョンを出し、広げる場合はメジャーバージョンにします。

公開者の固定 (publisher pinning)

公開前に、CLI はマニフェストの publisher と、有効なセッションのアカウントを比較します。一致しなければ MANIFEST_PUBLISHER_MISMATCH で失敗し、回避フラグはありません。emdash-plugin whoami で確認し、emdash-plugin switch <did> で切り替えます。誤ったアカウントからの公開を防ぐ仕組みで、ハンドルは別の DID に移りうるため、固定には DID が向いています。

emdash-plugin validate はオフラインで、未知のフィールド、無効な値、network:request なのに allowedHosts が空、といった項目間の誤りを検出します。


4. フック

なぜフックか

WordPress のアクション/フィルターに相当する拡張点です。宣言時に決まり、実行時の動的登録はありません。すべてのフックは (event, ctx) を受け取ります。

主なフック

  • ライフサイクル: plugin:install / activate / deactivate / uninstall(権限不要)
  • コンテンツ(前): content:beforeSave(content:write。変更後のコンテンツ、拒否、void を返す)、content:beforeDelete(content:read。false で取り消し)
  • 公開ポリシー: content:beforePublish / beforeSchedule / beforeUnpublish(hooks.content-policy:register。{ cancel: true, reason } で拒否)
  • コンテンツ(後): content:afterSave / afterDelete / afterPublish / afterUnpublish / afterRestore / afterSchedule / afterUnschedule(content:read)
  • メディア、cron、メール(email:deliver は排他的)、コメント(comment:moderate は排他的、users:read)、執筆者
  • 公開ページ: page:metadata(権限不要)、page:fragments(ネイティブ専用、hooks.page-fragments:register)

beforeSave の戻り値でコンテンツを書き換える使い方は、WordPress のフィルターに近いものです。

保存の拒否

サンドボックスからは { __emdashSandboxHookResult: true, version: 1, error: { code: "SAVE_REJECTED", reason: "…" } } を返して保存を拒否します。reason は 1〜500 文字のプレーンテキストで、編集者に表示されます(HTML は不可)。それ以外の例外は汎用の CONTENT_HOOK_ERROR になります。ネイティブ型では ContentSaveRejectedError を投げます。

公開状態の変化に反応する

content:afterPublish、afterUnpublish、afterRestore、afterDelete は、公開・非公開・復元・削除の後に動きます。外部のサービスへの通知や、検索インデックスの更新に使えます。公式の挙動は次のとおりです。

  • afterPublish は、予約公開が実行されたときも動く。
  • afterRestore で戻るのは、スケジュールなしの下書き。
  • afterDelete の permanent は、ゴミ箱への移動なら false、完全削除なら true。
  • 後フックは操作が成功した後に実行される。エラーは記録されるだけで、操作は取り消せない。

実行順序、タイムアウト、エラーポリシー

項目 内容
priority 既定 100。小さいほど先に実行
timeout 既定 5000 ms(プロセス内実行)
errorPolicy "abort"(既定)か "continue"。continue は失敗を記録して次へ進む
dependencies 指定したプラグインの後に実行

注意: 隔離されたサンドボックスのランナーは、priority、timeout、dependencies、errorPolicy を使いません。プラグインをロード順に呼び、実時間の上限だけを適用します(Cloudflare と Node.js のランナーはどちらも既定 30 秒)。2 つのサンドボックス型プラグインの協調や、隔離フックの失敗からの回復にフックのメタデータを使わないでください。これらが効くのは、ネイティブ型または plugins: [] で動かす場合です。


5. API ルート

位置づけ

WordPress の REST (register_rest_route) に相当します。ルートは /_emdash/api/plugins/<slug>/<route-name> にマウントされ、管理画面や外部連携から呼ばれます。ルート名にスラッシュを含められます。

認証と CSRF

ルートは既定で認証が必要です。 非公開ルートは、後方互換のため既定で plugins:manage 権限を要求します。機能に合う、より狭い EmDash の権限(例: content:create)があれば、permission で指定します。Cookie 認証のリクエストは、すべての HTTP メソッドで X-EmDash-Request: 1 ヘッダーも必要です(管理画面は自動で付けます)。トークン認証はこのヘッダーが不要ですが、admin スコープとルートの権限は要ります。

認証を外すには public: true を指定します。公開ルートはインターネットに公開されます。データを変更しうるクロスオリジンのブラウザリクエストは防がれますが(別または不正な Origin は 403)、Webhook などの非ブラウザのクライアントは通るので、誰でも呼べると考え、入力の検証と署名の確認をします。公開ルートの追加には、インストール時と更新時に再同意が必要です。

非公開ルートの routeCtx.user が、認証済みの呼び出し元です。リクエスト本文から呼び出し元を読んではいけません。他人になりすませてしまうためです。

入力検証

routeCtx.input の型は unknown です。zod で検証し、safeParse の失敗は例外ではなく JSON の結果で返します。

const input = z.object({
  limit: z.coerce.number().int().min(1).max(100).default(50),
});
// GET では入力はクエリ文字列。値はすべて文字列なので z.coerce を使う
const parsed = input.safeParse(routeCtx.input);
if (!parsed.success) return { ok: false, error: { code: "VALIDATION_ERROR" } };

本文の形式は request.body で none、json、text、bytes、form-data から選べます。既定の上限は 1 MiB、最大 8 MiB です。戻り値は { success: true, data: ... } の封筒で包まれます。想定内の失敗は安定したエラーコードを JSON で返し、例外はまさかの失敗に限ります。例外のメッセージが応答に含まれうるため、認証情報、個人情報、内部パス、スタックトレースを入れてはいけません。

MCP ツールと外部 API

mcp.tools に非公開ルートを紐づけると MCP ツール(<pluginId>__<toolName>)になります。入力スキーマは必須で、元に戻しにくい操作には destructive: true を付け、管理者が別途有効化します。外部 API の呼び出しは network:request と allowedHosts を宣言して ctx.http.fetch() を使います(本文は各 8 MiB まで、リダイレクトはホップごとに検査)。


6. ストレージ、KV、設定

使い分け

データ 使うもの
運用データ(ログ、投稿内容、キャッシュ) ctx.storage(宣言したコレクション)
利用者が変える小さな値 ctx.settings
内部状態、カーソル ctx.kv の state: プレフィックス
再利用できる計算結果 ctx.kv の cache: プレフィックス
編集者が通常のエディターで直すデータ サイトのコレクション(プラグインのストレージではない)

ストレージ

コレクションとインデックスをマニフェストの storage に宣言します。宣言していないコレクションへのアクセスは例外になります。クエリと並び替えは、インデックス済みフィールドのみです(全表スキャンを防ぐため)。

const result = await ctx.storage.submissions.query({
  where: { formId: "contact", status: "pending" },
  orderBy: { createdAt: "desc" },
  limit: 20, // 既定 50、最大 100
});
// result.items / result.cursor / result.hasMore

複合インデックス ["formId", "createdAt"] は、formId で絞り込み、createdAt で並び替えるクエリに効きます。先頭以外のフィールドだけの絞り込みには効かないので、その検索が多いなら別のインデックスを足します。インデックスを足す更新では、次のロード時に作成されます。ユニークインデックスは、重複データがあると作れません。インデックスもトラスト契約の一部なので、変更したらバージョンを上げます。

並行更新には getVersioned() と compareAndSet()(リビジョン一致時のみ書き込み)、原子的更新には updateIf() が使えます。リトライには上限を設けます。

設定

ctx.settings はプラグインごとに名前空間が分かれていて、能力宣言が要りません。設定ページは、マニフェストの admin.pages と admin.settingsSchema、そして admin ルートで作ります。type: "secret" のフィールドは AES-GCM で暗号化されて保存されます。Block Kit の secret_input はブラウザ上の入力を隠すだけなので、暗号化には settingsSchema への宣言が要ります。シークレットは管理画面に返らず、空欄のまま保存しても値は書き換わらないようにします(has_value で「設定済み」を示す)。

セキュリティ: プラグイン自身は平文を受け取り、宣言したネットワークやメールで外へ送れます。シークレットを入力する前に、そのプラグインの権限を確認してください。シークレットを導出した値もログに出してはいけません。

plugin:install は新規インストールでしか実行されません。後の版で設定を足す場合は、読み取り時に ?? 既定値 を付けます。


7. 権限の宣言

宣言は「現在のバージョンが使うものだけ」にします。将来使うかもしれないという理由で宣言すると、すべてのインストールと更新が、不要なアクセスの承認を求めてしまいます。使い始める版で足します。

フックが event を読むだけでも、対応する権限の宣言は必要です(同意ダイアログの正確さと、プロセス内実行の要件のため)。

network:request は allowedHosts が空でないこと、network:request:unrestricted は空であることをバンドル時に検査します。バンドルされた backend.js は、fs、path、child_process などの Node.js 組み込みを取り込めません。必要ならネイティブ型に移すか、Web API を使います。


8. Block Kit による管理画面

サンドボックス型は、管理画面を JSON(ブロック)で記述します。ホストが描画し、プラグインの JavaScript はブラウザで動きません。

  1. 利用者がプラグインのページを開く。
  2. 管理画面が admin ルートに page_load を送る。
  3. プラグインが BlockResponse(ブロックの配列)を返す。
  4. ボタンやフォームの操作が block_action / form_submit として送られ、新しいブロックが返る。

admin ルートは非公開で、管理画面が CSRF ヘッダーを付けますが、入力は誰でも直接呼べるので検証します。応答は、不正なブロック、安全でない URL、宣言していないページへのリンク、サイズ超過(256 KiB、ネスト 20 段、2,000 ノードなど)の場合、ブラウザに届く前に失敗します。

図 8-5 に、Block Kit での管理画面とプラグインのやり取りを示します。

図 8-5: Block Kit による管理画面のやり取り

ブロックには header、section、table、form、stats、chart、banner など、要素には button、text_input、select、toggle、secret_input などがあります。条件表示 (condition) はクライアント側で評価されます。保存済みエントリ向けの editorPanels / editorActions もあります。試作には Block Playground が便利です。


9. ネイティブプラグイン

構成

ネイティブ型は、npm パッケージとして次の 2 つの役割を持つ export を提供します。

  • ディスクリプター(activityPlugin() など): Astro の設定評価時に動き、id、version、format: "native"、entrypoint、options などの、シリアライズ可能なメタデータを返す。
  • createPlugin(): EmDash の初期化時に動き、definePlugin() の結果を返す。名前付き export の createPlugin が必須。

id は小文字・数字・ハイフンの非スコープ名(例: plugin-activity)にします。ルート URL の 1 セグメントになるためです。npm のスコープはパッケージ名と entrypoint に持たせます。バージョンは major.minor.patch の完全形です。ディスクリプターには plugins: [] で登録し、sandboxed: [] には入れられません。

ネイティブのフックは ctx の API に権限が必要です(例: content:afterSave には content:read が要り、ないとフックは動きません)。ただし公式は、ネイティブ型の能力宣言はセキュリティの境界ではないと述べています。ホストパッケージの取り込み、環境変数、直接の fetch() が可能だからです。

秘密情報は、デプロイ時のものは process.env、管理者が入力するものは secret フィールドと EMDASH_ENCRYPTION_KEY で扱います。

追加できる面

  • 生成された設定フォーム: admin.settingsSchema(string、number、boolean、select、secret、url、email)
  • React 管理画面: adminEntry と admin.entry を一致させ、pages、widgets、fields、contentEditorPanels、contentListColumns を export
  • Portable Text: admin.portableTextBlocks と、componentsEntry の blockComponents(Astro コンポーネント)
  • ページフラグメント: page:fragments で external-script、inline-script、html を head、body:start、body:end に注入

React 管理画面では、Kumo のコンポーネント、apiFetch()(CSRF ヘッダーを付与)、Lingui を使います。React、Kumo、Lingui などのホストのライブラリは、peerDependencies に置き、管理画面のバンドルに 2 つ目のインスタンスが入らないようにします。ページフラグメントには、レイアウトに EmDashHead、EmDashBodyStart、EmDashBodyEnd を置く必要があります。置かない配置先には出力されません。生の HTML は検証されず、そのまま挿入されます。補間する値は、文脈に合わせてエンコードしてください。

配布とレジストリ境界

npm pack のタールボールを使い捨てのサイトに入れ、管理画面の全ての面と Portable Text ブロックを実際に開いて確認します。dist/ に加え src/admin、src/astro もパッケージに含めます(ホストのビルドが処理するため)。ネイティブ型はレジストリに公開できません。 インストール時の同意がないため、更新で権限や許可ホストが増えるときはリリースノートに明記します。


10. テスト

@emdash-cms/plugin-test は、プラグインをビルドし、ローカルの Worker Loader と D1 を使って、本番と同じ PluginBridge を通して動かします。emdash-plugin init の雛形に含まれます。

  • createPluginTestHost(): フックやルートをサンドボックスの輸送路で直接呼ぶ(シリアライズ、権限の強制、ストレージ、ルートのロジック)。
  • createPluginRuntimeTestHost(): 実際のコンテンツ保存、有効化、メディア、コメント、スケジュールを通し、ホストの操作がプラグインに届くことを確かめる。

注意点は次のとおりです。

  • 直接呼び出しは、ルートの認証・権限・CSRF を通りません。確かめるには actions.routes.request() を使います。
  • 各テストで dispose() し、afterPublish のような遅延タスクは await host.waitForDeferredTasks() を待ってから検査します。
  • 管理画面の React 描画や、デプロイ先の CPU・メモリ・サブリクエスト制限は再現されません。

11. CLI

@emdash-cms/plugin-cli のバイナリは emdash-plugin です。

コマンド 内容
init [name] 雛形の作成
build / dev dist/ の生成 / 変更の監視と再ビルド(150 ms でデバウンス。失敗時は最後に成功した dist/ を残す)
validate [path] マニフェストのオフライン検証
bundle dist/ とアセットをレジストリ用タールボールにする(--validate-only あり)
publish ビルド、アップロード、リリース記録の書き込み
update-package [--yes] 公開済みプロフィールの変更。--yes なしは差分のプレビューのみ
profile setup / release setup / release plan / release prepare 委任リリース用
login / logout / whoami / switch 発行者セッション
search / info レジストリの検索と、掲載チェックの確認

旧パッケージ @emdash-cms/registry-cli は plugin-cli に改名され、旧能力名(network:fetch など)は現在の名前(network:request など)に置き換えられました。サンドボックス型は definePlugin() ではなく SandboxedPlugin 型の定数をデフォルト export し、利用者側は括弧なしのデフォルト import で取り込みます。ファクトリ引数だった設定は ctx.settings に移します。


12. 公開とリリース

バンドルの検査

bundle は、展開後の合計 256 KB 以下、1 ファイル 128 KB 以下、20 ファイル以下、backend.js に Node.js 組み込みがないこと、能力名が正しいこと、network:request と allowedHosts の整合を検査します。

直接公開

emdash-plugin login alice.example.com
emdash-plugin publish

パッケージとリスト画像を自分の PDS(個人データサーバー)にアップロードし、リリース記録を書きます。バージョンは既定で不変で、同じバージョンの再公開は拒否されます(--allow-overwrite は取り下げ扱いになりうるので、新バージョンを出すのが原則)。版の付け方は、信頼契約を広げるならメジャー、フックやルートの追加ならマイナー、修正ならパッチです。

委任リリース (GitHub Actions)

GitHub Actions がタグや手動実行でビルドして公開する方式です。リポジトリに Atmosphere アカウントの資格情報を置きません。設定の流れは次のとおりです。

  1. emdash-plugin login で所有者としてサインインし、emdash-plugin release setup でプロフィールと .github/workflows/emdash-release.yml を用意する(承認条件と来歴の要否を選ぶ)。
  2. リリースサービスのダッシュボードで Authorize publishing。付与されるのはリリース記録の作成とブロブのアップロードだけで、プロフィールの編集、リリースの更新・削除は含まれません。
  3. タグ(<slug>@<version>)の push、Changesets との連携、または手動実行でリリースする。初回はリポジトリとリファレンスの範囲を承認し、権限が増えるリリースはパスキーによる承認待ちになる。

サービスは、GitHub の OIDC トークン、署名済みプロフィールとの一致、チェックサム、GitHub のビルド来歴、宣言された権限とバンドルの一致、バージョンが未使用であることなどを確認してから書き込みます。現時点では、公開リポジトリだけが対象です(検証が GitHub の公開 Sigstore ルートを信頼するため)。GitHub のワークフローは、必要な権限だけを個別のジョブに与え、サードパーティの Action をコミットで固定します。


13. WordPress との対応

WordPress EmDash 補足
アクション (add_action) content:after*、cron、media:afterUpload など 後フックは結果を変えられない
フィルター (add_filter) content:beforeSave、email:beforeSend、comment:beforeCreate など 戻り値で変更。拒否も戻り値
優先度 priority(既定 100、小さいほど先) 隔離ランナーでは使われない
オプション (get_option) ctx.settings、ctx.kv プラグインごとに名前空間が分かれる。シークレットは暗号化
カスタムテーブル ctx.storage(宣言したコレクション) インデックスの宣言が必要。インデックス外の検索は不可
REST API プラグインのルート 既定で認証あり。permission で絞る。public: true は明示
管理メニュー (add_menu_page) admin.pages、admin.widgets サンドボックス型は Block Kit、ネイティブ型は React
設定 API admin.settingsSchema、Block Kit のフォーム
ショートコード/ブロック Portable Text ブロックと blockComponents レンダラーはネイティブ型のみ
wp_head への出力 page:metadata(構造化)、page:fragments(ネイティブのみ)
公式ディレクトリ レジストリ(Atmosphere アカウントによる署名付きリリース) 発行者の本人性が DID に結びつく
権限の確認 能力宣言と同意ダイアログ WordPress にはない
実行権限 PHP の全権限 サンドボックス型は絞られる

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

開発者の責任

利用編の第 8 節は利用者側の観点でした。ここでは作る側のチェックリストを示します。

最小権限

  • 宣言は現在のバージョンが使うものだけにする。network:request:unrestricted は、宛先を運用者が入力する場合に限る。固定の宛先は allowedHosts に列挙する。
  • permission は機能に合う最も狭いものにする。既定の plugins:manage のままにしない。
  • 公開ルートは最小限にし、入力の検証と、可能なら署名の確認をする。
  • MCP ツールは、元に戻しにくい操作に destructive: true を付ける。

サンドボックス

  • 例外のメッセージに、秘密、個人情報、パス、スタックトレースを入れない。
  • 生の HTML を扱うなら、ネイティブ型になる前に page:metadata で足りないか考える。
  • サンドボックス型を plugins: [] に移すと、隔離は失われる。READMEに、その前提を書く。

サプライチェーン

  • 依存パッケージは最小限にし、バンドルはサイズと Node.js 組み込みの検査を通す。
  • 公開者は DID で固定し、公開は委任リリースと来歴(provenance)を必須にする(profile setup の --provenance の既定は required。「推奨」と明記した資料は見つからず、必須にする運用は筆者の見解)。
  • 資格情報を CI に置かない。委任リリースが付与するのは、リリース記録の作成とブロブのアップロードのみ。
  • ネイティブ型の README には、ネイティブである理由、宣言した権限と許可ホストの用途、設定、必要なレイアウトコンポーネント、アップグレードの手順を書く。能力宣言を隔離の境界と説明してはいけない。
  • 配布するパッケージは、公式が勧める手順どおり、npm pack のタールボールで確認する。

まとめ

  • 形式はサンドボックス型が既定。React 管理画面、Portable Text レンダラー、ページフラグメント、プロセスへの直接アクセスが必要なときだけネイティブ型。
  • 1 つの emdash-plugin.jsonc と src/plugin.ts が基本。信頼の契約(権限、許可ホスト、ストレージ)を変えたら新バージョン。
  • ルートは既定で認証あり。入力は必ず検証する。
  • 管理画面は Block Kit(サンドボックス)か React(ネイティブ)。
  • 公開は emdash-plugin publish か、GitHub Actions による委任リリース。ネイティブ型は npm のみ。

理解度チェック

  1. サンドボックス型で page:fragments を使えない理由を説明し、代わりに何を使えるか答えてください。
  2. emdash-plugin.jsonc の slug と npm のパッケージ名は同じですか。ルート URL との関係も説明してください。
  3. 隔離されたサンドボックスのランナー上で、errorPolicy や priority を当てにできないのはなぜですか。
  4. 非公開ルートの既定の権限と、Cookie 認証での追加要件を答えてください。
  5. 委任リリースでは、リポジトリにどの資格情報を置きますか。リリースサービスに付与される権限は何ですか。
  6. WordPress のフィルターに近い EmDash のフックを 1 つ挙げ、戻り値で何ができるか答えてください。

答え

  1. その出力はサンドボックス外のブラウザでファーストパーティのコードとして動くため、ネイティブ専用。代わりに page:metadata(meta、property、許可リストの link、JSON-LD)を使える。
  2. 別物。slug はルート URL とストレージの識別に使われ、小文字始まりの [a-z][a-z0-9_-]*。npm 名は @example/plugin-gallery でも slug は gallery にする。
  3. 隔離されたランナーは、プラグインをロード順に呼び、実時間の上限だけを適用するため。これらが効くのはプロセス内実行。
  4. 既定は plugins:manage。permission で狭められる。Cookie 認証では X-EmDash-Request: 1 ヘッダーが全メソッドで必要。
  5. 置かない(Atmosphere アカウントの資格情報は保存しない)。GitHub の OIDC がワークフローを識別し、サービスにはリリース記録の作成とブロブのアップロードだけが付与される。
  6. content:beforeSave。変更後のコンテンツを返して書き換えるか、SAVE_REJECTED の結果で保存を拒否できる。

出典

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

  • プラグイン開発(/plugins/creating-plugins/):
    • https://docs.emdashcms.com/plugins/creating-plugins/choosing-a-format/
    • https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin/
    • https://docs.emdashcms.com/plugins/creating-plugins/manifest/
    • https://docs.emdashcms.com/plugins/creating-plugins/hooks/
    • https://docs.emdashcms.com/plugins/creating-plugins/api-routes/
    • https://docs.emdashcms.com/plugins/creating-plugins/storage/
    • https://docs.emdashcms.com/plugins/creating-plugins/settings/
    • https://docs.emdashcms.com/plugins/creating-plugins/capabilities/
    • https://docs.emdashcms.com/plugins/creating-plugins/block-kit/
    • https://docs.emdashcms.com/plugins/creating-plugins/testing/
    • https://docs.emdashcms.com/plugins/creating-plugins/cli/
    • https://docs.emdashcms.com/plugins/creating-plugins/migrating-to-the-cli/
    • https://docs.emdashcms.com/plugins/creating-plugins/publishing/
    • https://docs.emdashcms.com/plugins/creating-plugins/delegated-releases/
  • ネイティブプラグイン(/plugins/creating-native-plugins/):
    • https://docs.emdashcms.com/plugins/creating-native-plugins/your-first-native-plugin/
    • https://docs.emdashcms.com/plugins/creating-native-plugins/react-admin/
    • https://docs.emdashcms.com/plugins/creating-native-plugins/portable-text-components/
    • https://docs.emdashcms.com/plugins/creating-native-plugins/page-fragments/
    • https://docs.emdashcms.com/plugins/creating-native-plugins/distributing/
  • フックのリファレンス: https://docs.emdashcms.com/reference/hooks/
  • サンドボックス: https://docs.emdashcms.com/deployment/plugin-sandbox/