権限（Capabilities）とセキュリティ

権限の宣言

権限は、slug などの信頼に関する取り決め（trust contract）の項目と並べて、emdash-plugin.jsonc に書きます。

{
	"slug": "plugin-hello",
	// ...identity + profile...

	"capabilities": ["content:read", "network:request"],
	"allowedHosts": ["api.example.com"]
}

プラグインが実際に必要とするものだけを宣言します。レジストリはインストールの前にこれらの権限をサイトの運営者に表示するため、余分な宣言があるたびに、プラグインが使わないアクセスの承認を運営者に求めることになります。

権限のリファレンス

プラグインに必要な権限は、次の規則によって変わります。

• 包含関係。 content:write は自動的に content:read を含みます。media:write は media:read を、network:request:unrestricted は network:request を含みます。両方を列挙する必要はありません。
• タクソノミーは、読み取り専用の別の窓口です。 taxonomies:read を宣言すると、ctx.taxonomies を通じて、タクソノミーの定義、そのターム、エントリーに割り当てられたタームにアクセスできます。これは content:read とは独立しています。プラグインがコンテンツとその分類の両方を読む場合は、両方を宣言します。プラグインからタクソノミーに書き込む手段はありません。
• network:request:unrestricted は、ユーザーが設定するURLのためにあります。 運営者が送信先のURLを入力するWebhookプラグインは、マニフェストに書かれていないホストにアクセスする必要があります。常に決まったAPIを呼び出すプラグインは、network:request と allowedHosts を使ってください。
• email:send は、権限だけでなく設定によっても制限されます。 プラグインは email:send を宣言できますが、ほかのプラグインが email:deliver の送信手段を登録している場合にのみ ctx.email が渡されます。

ロケールを指定したコンテンツの作成

ctx.content.create() は、新しいエントリーのロケールを指定する3番目の引数を省略可能な形で受け付けます。

const post = await ctx.content.create(
	"posts",
	{ title: "繁體中文" },
	{ locale: "zh-tw" },
);

ロケールの照合は大文字と小文字を区別せず、サイトのロケール設定での大文字・小文字の表記で保存されます。そのため、設定されている表記が zh-TW であれば、zh-tw は zh-TW になります。明示的に指定したロケールの形式が正しくない場合は、常に例外が発生します。i18nが設定されている場合は、設定済みのロケールの一覧にないロケールを明示的に指定したときにも例外が発生します。このオプションを省略すると、EmDashはサイトで設定されたデフォルトのロケールを使います。i18nの設定がないサイトでは、デフォルトの en のままです。

ネットワークの許可ホスト

network:request を持つプラグインは、allowedHosts に列挙したホストにだけリクエストを送れます。先頭の *. は、指定したドメインとそのサブドメインの両方に一致します。

"capabilities": ["network:request"],
"allowedHosts": [
	"api.example.com",     // exact host
	"*.cdn.example.com"    // cdn.example.com and any subdomain
]

ブリッジは、リクエストを転送する前に、リクエストURLのホストを許可リストと照合します。宣言されていないホストへのリクエストは、サンドボックスの外に出ることなく、プラグインの中で例外になります。

network:request:unrestricted は、マニフェストのホストの許可リストを使いません。それでもサンドボックスのブリッジは、HTTPとHTTPSだけを受け付け、既知の内部ホストとプライベートなアドレスの直接指定をブロックし、リダイレクトのたびに再確認し、リダイレクトが別のオリジンにまたがる場合は認証情報のヘッダーを取り除きます。制限なしのアクセスは、運営者が実行時に送信先を指定する場合にだけ使ってください。送信先が決まっている場合は、同意ダイアログにホスト名が表示されるように、network:request とホストを明示して宣言してください。

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

サンドボックスランナーが有効な場合、ランタイムは次のことを強制します。

サンドボックスが強制しないこと

権限の仕組みでは扱わない、また扱えないことがいくつかあります。

• 許可した権限の範囲内での動作。 content:write を持つプラグインは、自分が作ったコンテンツだけでなく、あらゆるコンテンツを編集できます。権限は大まかな単位です。「このプラグインはコンテンツに書き込める」ことを表し、「このプラグインは自分が作ったコンテンツにだけ書き込める」ことは表しません。運営者は、そのアクセスを許可する前に、プラグインのコードと公開者を評価する必要があります。
• エントリーの編集ロック。 ctx.content.update() と ctx.content.delete() は、プログラムによる書き込みです。編集者がエントリーの勧告的な編集ロックを持っていても、これらはブロックされません。プラグインと編集者の両方が同じエントリーを更新する可能性がある場合は、プラグインの書き込みを編集者と調整してください。
• Node.jsでの運営者の信頼。 設定したサンドボックスランナーが利用できないと報告した場合（Cloudflare Worker Loaderがない、Node側のランナーがインストールされていない、など）、sandboxed: [] のプラグインは起動時にスキップされます。それらを plugins: [] に移して同じプロセス内で実行することはできます。ただしその場合は、V8のisolateもリソース制限もなく、プラグインは fetch() を直接呼び出したり、環境変数を読んだりできます。ネイティブ型と同じ水準の信頼として扱ってください。
• サイドチャネル。 処理時間、ログ出力、保存されたデータはすべて、ホスト環境に適切なアクセス権を持つ人なら誰でも見られます。サンドボックスを、それを実行している運営者に対する機密保持の境界として使わないでください。

権限への同意

運営者がレジストリからサンドボックス型プラグインをインストールするとき、EmDashは宣言された権限を一覧にした同意ダイアログを表示します。権限を追加する更新（たとえば、これまでコンテンツを読むだけだったプラグインが、ネットワークリクエストを送ろうとする場合）は、権限の差分として表示され、新しいバージョンが有効になる前にあらためて承認が必要です。

将来使うかもしれない権限を宣言すると、インストールや更新のたびに不要なアクセスの承認を求めることになります。現在のバージョンが使う権限を列挙し、権限を使い始めるバージョンでその権限を追加します。

バンドル時の検証

emdash-plugin bundle と emdash-plugin publish は、追加で次のことを確認します。

• 宣言した権限はすべて、認識されている権限の一覧に含まれている必要があります（書き間違いがあるとビルドが失敗します）。
• network:request には空でない allowedHosts が必要です。network:request:unrestricted では allowedHosts を空にする必要があります。権限とホストを参照してください。
• バンドルした backend.js は、Node.jsの組み込みモジュール（fs、path、child_process など）をインポートできません。サンドボックスのランタイムはこれらを提供しないためです。

作成時に書く項目はマニフェストのリファレンスを、バンドル時の確認はバンドルと公開を参照してください。