Plugin-Sandbox

EmDash kann Plugins in zwei Ausführungsmodi betreiben: trusted und sandboxed. Diese Seite erklärt, wie die Modi funktionieren, welche Schutzmaßnahmen sie bieten und welche Sicherheitsimplikationen für verschiedene Deployment-Ziele gelten.

Ausführungsmodi

Trusted-Modus

Trusted Plugins laufen im selben Prozess wie deine Astro-Site. Sie werden aus npm-Paketen oder lokalen Dateien geladen und in astro.config.mjs konfiguriert:

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

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

Im Trusted-Modus:

• Capabilities sind Dokumentation, keine Durchsetzung. Ein Plugin, das ["read:content"] deklariert, kann trotzdem auf alles im Prozess zugreifen. Das Feld capabilities sagt Administratoren, was das Plugin vorhat zu nutzen.
• Keine Ressourcenlimits. CPU-, Speicher- und Netzwerknutzung sind unbegrenzt. Ein fehlerhaftes Plugin kann die gesamte Anfrage blockieren.
• Voller Prozesszugriff. Plugins teilen sich die Node.js/Workers-Runtime mit deiner Astro-Site. Sie können beliebige Module importieren, auf Umgebungsvariablen zugreifen und (unter Node.js) das Dateisystem lesen/schreiben.

Sandboxed-Modus (Cloudflare Workers)

Sandboxed Plugins laufen in isolierten V8-Isolates über Cloudflares Dynamic Worker Loader-API. Jedes Plugin erhält sein eigenes Isolate mit erzwungenen Limits.

Um Sandboxing zu aktivieren, konfiguriere den Sandbox-Runner in deiner Astro-Config:

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

Was die Sandbox erzwingt

Architektur

Sandboxed Plugins kommunizieren mit EmDash über eine RPC-Bridge:

┌─────────────────────┐     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     │
                                     └──────────────┘

Der Plugin-Code läuft in einer V8-Isolate. Er erhält ein ctx-Objekt, bei dem jede Methode ein Proxy zur Bridge ist. Die Bridge läuft im Haupt-EmDash-Worker und führt die eigentlichen DB/Storage-Operationen nach Capability-Prüfung aus.

Wrangler-Konfiguration

Sandboxing erfordert den Dynamic Worker Loader. Ergänze deine wrangler.jsonc:

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

Node.js-Deployments

Bei Deployment auf Node.js (oder jeder Nicht-Cloudflare-Plattform):

• Es wird NoopSandboxRunner verwendet. Er liefert isAvailable() === false.
• Das Laden sandboxed Plugins wirft SandboxNotAvailableError.
• Alle Plugins müssen als Trusted Plugins im Array plugins registriert werden.
• Capability-Deklarationen sind rein informativ — sie werden nicht erzwungen.

Was das für die Sicherheit bedeutet

Empfehlungen für Node.js-Deployments

1. Nur Plugins aus vertrauenswürdigen Quellen installieren. Prüfe den Quellcode vor der Installation. Bevorzuge Plugins bekannter Maintainer.
2. Capability-Deklarationen als Review-Checkliste nutzen. Auch ohne Durchsetzung dokumentieren sie den beabsichtigten Umfang. Ein Plugin mit ["network:fetch"], das kein Netz braucht, ist verdächtig.
3. Ressourcennutzung überwachen. Nutze Monitoring auf Prozessebene (z. B. --max-old-space-size, Health Checks), um fehlerhafte Plugins zu erkennen.
4. Cloudflare für nicht vertrauenswürdige Plugins erwägen. Wenn du Plugins unbekannter Herkunft brauchst (z. B. aus einem Marketplace), deploye auf Cloudflare Workers, wo Sandboxing verfügbar ist.

Gleiche API, andere Garantien

Der Plugin-Code ist in beiden Modi identisch. Die definePlugin()-API, die Form von ctx, Hooks, Routes und Storage funktionieren gleich. Was sich ändert, ist die Durchsetzung:

// 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 }),
			});
		},
	},
});

Ziel: Plugin-Autoren entwickeln lokal im Trusted-Modus (schnellere Iteration, einfacheres Debugging) und deployen in Production im Sandboxed-Modus — ohne Codeänderungen.