Sandbox de plugins

EmDash puede ejecutar plugins en dos modos: trusted y sandboxed. Esta página explica cómo funciona cada uno, qué protecciones ofrecen y las implicaciones de seguridad según el destino de despliegue.

Modos de ejecución

Modo trusted

Los plugins trusted se ejecutan en el mismo proceso que tu sitio Astro. Se cargan desde paquetes npm o archivos locales y se configuran en astro.config.mjs:

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

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

En modo trusted:

• Las capabilities son documentación, no aplicación. Un plugin que declara ["read:content"] aún puede acceder a todo en el proceso. El campo capabilities indica a los administradores qué el plugin pretende usar.
• Sin límites de recursos. El uso de CPU, memoria y red no está acotado. Un plugin defectuoso puede bloquear toda la petición.
• Acceso completo al proceso. Los plugins comparten el runtime Node.js/Workers con tu sitio Astro. Pueden importar cualquier módulo, acceder a variables de entorno y leer/escribir el sistema de archivos (en Node.js).

Modo sandboxed (Cloudflare Workers)

Los plugins sandboxed se ejecutan en aislamientos V8 aislados proporcionados por la API Dynamic Worker Loader de Cloudflare. Cada plugin obtiene su propio aislamiento con límites aplicados.

Para habilitar el sandboxing, configura el sandbox runner en tu config de Astro:

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

Qué impone el sandbox

Arquitectura

Los plugins sandboxed se comunican con EmDash a través de un puente 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     │
                                     └──────────────┘

El código del plugin corre en un aislamiento V8. Recibe un objeto ctx donde cada método es un proxy al puente. El puente corre en el worker principal de EmDash y realiza las operaciones reales de base de datos/almacenamiento tras validar capabilities.

Configuración de Wrangler

El sandboxing requiere Dynamic Worker Loader. Añade a tu wrangler.jsonc:

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

Despliegues en Node.js

Al desplegar en Node.js (o cualquier plataforma que no sea Cloudflare):

• Se usa NoopSandboxRunner. Devuelve isAvailable() === false.
• Intentar cargar plugins sandboxed lanza SandboxNotAvailableError.
• Todos los plugins deben registrarse como trusted en el array plugins.
• Las declaraciones de capabilities son solo informativas: no se aplican.

Qué implica para la seguridad

Recomendaciones para despliegues en Node.js

1. Instala plugins solo de fuentes de confianza. Revisa el código fuente antes de instalar. Prefiere plugins de maintainers conocidos.
2. Usa las capabilities como lista de revisión. Aunque no se apliquen, documentan el alcance pretendido. Un plugin con ["network:fetch"] que no necesita red es sospechoso.
3. Supervisa el uso de recursos. Usa monitorización a nivel de proceso (p. ej. --max-old-space-size, health checks) para detectar plugins descontrolados.
4. Valora Cloudflare para plugins no confiables. Si necesitas ejecutar plugins de origen desconocido (p. ej. marketplace), despliega en Cloudflare Workers, donde el sandboxing está disponible.

Misma API, distintas garantías

El código del plugin es idéntico en ambos modos. La API definePlugin(), la forma de ctx, hooks, routes y storage funcionan igual. Lo que cambia es la aplicación:

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

El objetivo es que los autores desarrollen en local en modo trusted (iteración más rápida, depuración más sencilla) y desplieguen en producción en modo sandboxed sin cambiar código.