Bac à sable des plugins

EmDash peut exécuter les plugins selon deux modes : trusted et sandboxed. Cette page explique le fonctionnement de chaque mode, les protections offertes et les implications de sécurité selon la cible de déploiement.

Modes d’exécution

Mode trusted

Les plugins trusted s’exécutent dans le même processus que votre site Astro. Ils sont chargés depuis des paquets npm ou des fichiers locaux et configurés dans astro.config.mjs :

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

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

En mode trusted :

• Les capabilities sont de la documentation, pas une application. Un plugin déclarant ["read:content"] peut tout de même accéder à tout dans le processus. Le champ capabilities indique aux administrateurs ce que le plugin prévoit d’utiliser.
• Pas de limites de ressources. L’usage CPU, mémoire et réseau n’est pas borné. Un plugin défaillant peut bloquer toute la requête.
• Accès processus complet. Les plugins partagent le runtime Node.js/Workers avec votre site Astro. Ils peuvent importer n’importe quel module, lire les variables d’environnement et accéder au système de fichiers (sous Node.js).

Mode sandboxed (Cloudflare Workers)

Les plugins sandboxed s’exécutent dans des isolates V8 isolés fournis par l’API Dynamic Worker Loader de Cloudflare. Chaque plugin dispose de son propre isolate avec des limites appliquées.

Pour activer le sandboxing, configurez le sandbox runner dans votre config Astro :

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

Ce que le sandbox impose

Architecture

Les plugins sandboxed communiquent avec EmDash via un pont RPC :

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

Le code du plugin tourne dans un isolate V8. Il reçoit un objet ctx où chaque méthode est un proxy vers le pont. Le pont tourne dans le worker EmDash principal et effectue les opérations base/stockage après validation des capabilities.

Configuration Wrangler

Le sandboxing nécessite Dynamic Worker Loader. Ajoutez à votre wrangler.jsonc :

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

Déploiements Node.js

Lors d’un déploiement sur Node.js (ou toute plateforme non Cloudflare) :

• NoopSandboxRunner est utilisé. Il renvoie isAvailable() === false.
• Tenter de charger des plugins sandboxed lève SandboxNotAvailableError.
• Tous les plugins doivent être enregistrés comme trusted dans le tableau plugins.
• Les déclarations de capabilities sont purement informatives — elles ne sont pas appliquées.

Conséquences pour la sécurité

Recommandations pour les déploiements Node.js

1. N’installez des plugins que depuis des sources de confiance. Auditez le code source avant installation. Préférez les plugins de mainteneurs connus.
2. Utilisez les capabilities comme checklist de revue. Même non appliquées, elles documentent la portée prévue. Un plugin déclarant ["network:fetch"] sans besoin réseau est suspect.
3. Surveillez l’usage des ressources. Utilisez une supervision au niveau processus (ex. --max-old-space-size, health checks) pour détecter les plugins déréglés.
4. Envisagez Cloudflare pour les plugins non fiables. Si vous devez exécuter des plugins d’origine inconnue (ex. marketplace), déployez sur Cloudflare Workers où le sandboxing est disponible.

Même API, garanties différentes

Le code du plugin est identique quel que soit le mode. L’API definePlugin(), la forme de ctx, hooks, routes et storage fonctionnent de la même façon. Ce qui change, c’est l’application :

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

L’objectif est de permettre aux auteurs de développer en local en mode trusted (itération plus rapide, débogage plus simple) et de déployer en production en mode sandboxed sans modifier le code.