@emdash-cms/cloudflare 0.0.1

package/src/sandbox/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Cloudflare Sandbox Runner - RUNTIME ENTRY
+ *
+ * This module is loaded at runtime when plugins need to be sandboxed.
+ * It imports cloudflare:workers and should NOT be imported at config time.
+ *
+ * For config-time usage, import { sandbox } from "@emdash-cms/cloudflare" instead.
+ *
+ */
+
+export { CloudflareSandboxRunner, createSandboxRunner, type PluginBridgeProps } from "./runner.js";
+export { PluginBridge, setEmailSendCallback, type PluginBridgeEnv } from "./bridge.js";
+export { generatePluginWrapper } from "./wrapper.js";

package/src/sandbox/runner.ts

@@ -0,0 +1,357 @@
+/**
+ * Cloudflare Sandbox Runner
+ *
+ * Uses Worker Loader to run plugins in isolated V8 isolates.
+ * Plugins communicate with the host via a BRIDGE service binding
+ * that enforces capabilities and scopes operations.
+ *
+ * This module imports directly from cloudflare:workers to access
+ * the LOADER binding and PluginBridge export. It's only loaded
+ * when the user configures `sandboxRunner: "@emdash-cms/cloudflare/sandbox"`.
+ *
+ */
+
+import { env, exports } from "cloudflare:workers";
+import type {
+	SandboxRunner,
+	SandboxedPlugin,
+	SandboxEmailSendCallback,
+	SandboxOptions,
+	SandboxRunnerFactory,
+	SerializedRequest,
+	PluginManifest,
+} from "emdash";
+
+import { setEmailSendCallback } from "./bridge.js";
+import type { WorkerLoader, WorkerStub, PluginBridgeBinding, WorkerLoaderLimits } from "./types.js";
+import { generatePluginWrapper } from "./wrapper.js";
+
+/**
+ * Default resource limits for sandboxed plugins.
+ *
+ * cpuMs and subrequests are enforced by Worker Loader at the V8 isolate level.
+ * wallTimeMs is enforced by the runner via Promise.race.
+ * memoryMb is declared for API compatibility but NOT currently enforced —
+ * Worker Loader doesn't expose a memory limit option. V8 isolates have a
+ * platform-level memory ceiling (~128MB) but it's not configurable per-worker.
+ */
+const DEFAULT_LIMITS = {
+	cpuMs: 50,
+	memoryMb: 128,
+	subrequests: 10,
+	wallTimeMs: 30_000,
+} as const;
+
+export interface PluginBridgeProps {
+	pluginId: string;
+	pluginVersion: string;
+	capabilities: string[];
+	allowedHosts: string[];
+	storageCollections: string[];
+}
+
+/**
+ * Get the Worker Loader binding from env
+ */
+function getLoader(): WorkerLoader | null {
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Worker Loader binding accessed from untyped env object
+	return (env as Record<string, unknown>).LOADER as WorkerLoader | null;
+}
+
+/**
+ * Get the PluginBridge from exports (loopback binding)
+ */
+function getPluginBridge(): ((opts: { props: PluginBridgeProps }) => PluginBridgeBinding) | null {
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- PluginBridge accessed from untyped cloudflare:workers exports
+	return (exports as Record<string, unknown>).PluginBridge as
+		| ((opts: { props: PluginBridgeProps }) => PluginBridgeBinding)
+		| null;
+}
+
+/**
+ * Resolved resource limits with defaults applied.
+ */
+interface ResolvedLimits {
+	cpuMs: number;
+	memoryMb: number;
+	subrequests: number;
+	wallTimeMs: number;
+}
+
+/**
+ * Resolve resource limits by merging user-provided overrides with defaults.
+ */
+function resolveLimits(limits?: SandboxOptions["limits"]): ResolvedLimits {
+	return {
+		cpuMs: limits?.cpuMs ?? DEFAULT_LIMITS.cpuMs,
+		memoryMb: limits?.memoryMb ?? DEFAULT_LIMITS.memoryMb,
+		subrequests: limits?.subrequests ?? DEFAULT_LIMITS.subrequests,
+		wallTimeMs: limits?.wallTimeMs ?? DEFAULT_LIMITS.wallTimeMs,
+	};
+}
+
+/**
+ * Cloudflare sandbox runner using Worker Loader.
+ */
+export class CloudflareSandboxRunner implements SandboxRunner {
+	private plugins = new Map<string, CloudflareSandboxedPlugin>();
+	private options: SandboxOptions;
+	private resolvedLimits: ResolvedLimits;
+	private siteInfo?: { name: string; url: string; locale: string };
+
+	constructor(options: SandboxOptions) {
+		this.options = options;
+		this.resolvedLimits = resolveLimits(options.limits);
+		this.siteInfo = options.siteInfo;
+
+		// Wire email send callback if provided at construction time
+		setEmailSendCallback(options.emailSend ?? null);
+	}
+
+	/**
+	 * Set the email send callback for sandboxed plugins.
+	 * Called after the EmailPipeline is created, since the pipeline
+	 * doesn't exist when the sandbox runner is constructed.
+	 */
+	setEmailSend(callback: SandboxEmailSendCallback | null): void {
+		setEmailSendCallback(callback);
+	}
+
+	/**
+	 * Check if Worker Loader is available.
+	 */
+	isAvailable(): boolean {
+		return !!getLoader() && !!getPluginBridge();
+	}
+
+	/**
+	 * Load a sandboxed plugin.
+	 *
+	 * @param manifest - Plugin manifest with capabilities and storage declarations
+	 * @param code - The bundled plugin JavaScript code
+	 */
+	async load(manifest: PluginManifest, code: string): Promise<SandboxedPlugin> {
+		const pluginId = `${manifest.id}:${manifest.version}`;
+
+		// Return cached plugin if available
+		const existing = this.plugins.get(pluginId);
+		if (existing) return existing;
+
+		const loader = getLoader();
+		const pluginBridge = getPluginBridge();
+
+		if (!loader) {
+			throw new Error(
+				"Worker Loader not available. Add worker_loaders binding to wrangler config.",
+			);
+		}
+
+		if (!pluginBridge) {
+			throw new Error(
+				"PluginBridge not available. Export PluginBridge from your worker entrypoint.",
+			);
+		}
+
+		const plugin = new CloudflareSandboxedPlugin(
+			manifest,
+			code,
+			loader,
+			pluginBridge,
+			this.resolvedLimits,
+			this.siteInfo,
+		);
+
+		this.plugins.set(pluginId, plugin);
+		return plugin;
+	}
+
+	/**
+	 * Terminate all loaded plugins.
+	 */
+	async terminateAll(): Promise<void> {
+		for (const plugin of this.plugins.values()) {
+			await plugin.terminate();
+		}
+		this.plugins.clear();
+	}
+}
+
+/**
+ * A plugin running in a Worker Loader isolate.
+ *
+ * IMPORTANT: Worker stubs and bridge bindings are tied to request context.
+ * We must create fresh stubs for each invocation to avoid I/O isolation errors:
+ * "Cannot perform I/O on behalf of a different request"
+ */
+class CloudflareSandboxedPlugin implements SandboxedPlugin {
+	readonly id: string;
+	readonly manifest: PluginManifest;
+	private loader: WorkerLoader;
+	private createBridge: (opts: { props: PluginBridgeProps }) => PluginBridgeBinding;
+	private code: string;
+	private wrapperCode: string | null = null;
+	private limits: ResolvedLimits;
+	private siteInfo?: { name: string; url: string; locale: string };
+
+	constructor(
+		manifest: PluginManifest,
+		code: string,
+		loader: WorkerLoader,
+		createBridge: (opts: { props: PluginBridgeProps }) => PluginBridgeBinding,
+		limits: ResolvedLimits,
+		siteInfo?: { name: string; url: string; locale: string },
+	) {
+		this.id = `${manifest.id}:${manifest.version}`;
+		this.manifest = manifest;
+		this.code = code;
+		this.loader = loader;
+		this.createBridge = createBridge;
+		this.limits = limits;
+		this.siteInfo = siteInfo;
+	}
+
+	/**
+	 * Create a fresh worker stub for the current request.
+	 *
+	 * Worker Loader stubs contain bindings (like BRIDGE) that are tied to the
+	 * request context in which they were created. Reusing stubs across requests
+	 * causes "Cannot perform I/O on behalf of a different request" errors.
+	 *
+	 * The Worker Loader internally caches the V8 isolate, so we only pay the
+	 * cost of creating the bridge binding and stub wrapper per request.
+	 */
+	private createWorker(): WorkerStub {
+		// Cache the wrapper code (CPU-bound, no I/O context issues)
+		if (!this.wrapperCode) {
+			this.wrapperCode = generatePluginWrapper(this.manifest, {
+				site: this.siteInfo,
+			});
+		}
+
+		// Create fresh bridge binding for THIS request
+		const bridgeBinding = this.createBridge({
+			props: {
+				pluginId: this.manifest.id,
+				pluginVersion: this.manifest.version || "0.0.0",
+				capabilities: this.manifest.capabilities || [],
+				allowedHosts: this.manifest.allowedHosts || [],
+				storageCollections: Object.keys(this.manifest.storage || {}),
+			},
+		});
+
+		// Build Worker Loader limits from resolved resource limits
+		const loaderLimits: WorkerLoaderLimits = {
+			cpuMs: this.limits.cpuMs,
+			subRequests: this.limits.subrequests,
+		};
+
+		// Get a fresh stub with the new bridge binding.
+		// Worker Loader caches the isolate but the stub/bindings are per-call.
+		return this.loader.get(this.id, () => ({
+			compatibilityDate: "2025-01-01",
+			mainModule: "plugin.js",
+			modules: {
+				"plugin.js": { js: this.wrapperCode! },
+				"sandbox-plugin.js": { js: this.code },
+			},
+			// Block direct network access - plugins must use ctx.http via bridge
+			globalOutbound: null,
+			// Enforce resource limits at the V8 isolate level
+			limits: loaderLimits,
+			env: {
+				// Plugin metadata
+				PLUGIN_ID: this.manifest.id,
+				PLUGIN_VERSION: this.manifest.version || "0.0.0",
+				// Bridge binding for all host operations
+				BRIDGE: bridgeBinding,
+			},
+		}));
+	}
+
+	/**
+	 * Run a function with wall-time enforcement.
+	 *
+	 * CPU limits and subrequest limits are enforced by the Worker Loader
+	 * at the V8 isolate level. Wall-time is enforced here because Worker
+	 * Loader doesn't expose a wall-time limit — a plugin could stall
+	 * indefinitely waiting on network I/O.
+	 */
+	private async withWallTimeLimit<T>(operation: string, fn: () => Promise<T>): Promise<T> {
+		const wallTimeMs = this.limits.wallTimeMs;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+
+		const timeout = new Promise<never>((_, reject) => {
+			timer = setTimeout(() => {
+				reject(
+					new Error(
+						`Plugin ${this.manifest.id} exceeded wall-time limit of ${wallTimeMs}ms during ${operation}`,
+					),
+				);
+			}, wallTimeMs);
+		});
+
+		try {
+			return await Promise.race([fn(), timeout]);
+		} finally {
+			if (timer !== undefined) clearTimeout(timer);
+		}
+	}
+
+	/**
+	 * Invoke a hook in the sandboxed plugin.
+	 *
+	 * CPU and subrequest limits are enforced by Worker Loader.
+	 * Wall-time is enforced here.
+	 */
+	async invokeHook(hookName: string, event: unknown): Promise<unknown> {
+		return this.withWallTimeLimit(`hook:${hookName}`, () => {
+			const worker = this.createWorker();
+			const entrypoint = worker.getEntrypoint<PluginEntrypoint>("default");
+			return entrypoint.invokeHook(hookName, event);
+		});
+	}
+
+	/**
+	 * Invoke an API route in the sandboxed plugin.
+	 *
+	 * CPU and subrequest limits are enforced by Worker Loader.
+	 * Wall-time is enforced here.
+	 */
+	async invokeRoute(
+		routeName: string,
+		input: unknown,
+		request: SerializedRequest,
+	): Promise<unknown> {
+		return this.withWallTimeLimit(`route:${routeName}`, () => {
+			const worker = this.createWorker();
+			const entrypoint = worker.getEntrypoint<PluginEntrypoint>("default");
+			return entrypoint.invokeRoute(routeName, input, request);
+		});
+	}
+
+	/**
+	 * Terminate the sandboxed plugin.
+	 */
+	async terminate(): Promise<void> {
+		// Worker Loader manages isolate lifecycle - nothing to do here
+		this.wrapperCode = null;
+	}
+}
+
+/**
+ * The RPC interface exposed by the plugin wrapper.
+ */
+interface PluginEntrypoint {
+	invokeHook(hookName: string, event: unknown): Promise<unknown>;
+	invokeRoute(routeName: string, input: unknown, request: SerializedRequest): Promise<unknown>;
+}
+
+/**
+ * Factory function for creating the Cloudflare sandbox runner.
+ *
+ * Matches the SandboxRunnerFactory signature. The LOADER and PluginBridge
+ * are obtained internally from cloudflare:workers imports.
+ */
+export const createSandboxRunner: SandboxRunnerFactory = (options) => {
+	return new CloudflareSandboxRunner(options);
+};

package/src/sandbox/types.ts

@@ -0,0 +1,181 @@
+/**
+ * Cloudflare-specific types for sandbox runner
+ */
+
+import type { D1Database, R2Bucket } from "@cloudflare/workers-types";
+
+/**
+ * Environment bindings required for sandbox runner.
+ * These must be configured in wrangler.jsonc.
+ */
+export interface CloudflareSandboxEnv {
+	/** Worker Loader binding for spawning plugin isolates */
+	LOADER?: WorkerLoader;
+	/** D1 database for plugin storage and bridge operations */
+	DB: D1Database;
+	/** R2 bucket for plugin code storage (optional if loading from config) */
+	PLUGINS?: R2Bucket;
+}
+
+/**
+ * Worker Loader binding type.
+ * This is the API provided by Cloudflare's Worker Loader feature.
+ */
+export interface WorkerLoader {
+	/**
+	 * Get or create a dynamic worker instance.
+	 *
+	 * @param name - Unique identifier for this worker instance
+	 * @param config - Configuration function returning worker setup
+	 * @returns A stub to interact with the dynamic worker
+	 */
+	get(name: string, config: () => WorkerLoaderConfig | Promise<WorkerLoaderConfig>): WorkerStub;
+}
+
+/**
+ * Configuration for a dynamically loaded worker.
+ */
+export interface WorkerLoaderConfig {
+	/** Compatibility date for the worker */
+	compatibilityDate?: string;
+	/** Name of the main module (must be in modules) */
+	mainModule: string;
+	/** Map of module names to their code */
+	modules: Record<string, string | { js: string }>;
+	/** Environment bindings to pass to the worker */
+	env?: Record<string, unknown>;
+	/**
+	 * Outbound fetch handler.
+	 * Set to null to block all network access.
+	 * Set to a service binding to intercept/proxy requests.
+	 */
+	globalOutbound?: null | object;
+	/**
+	 * Resource limits enforced at the V8 isolate level.
+	 * Analogous to Workers for Platforms custom limits.
+	 */
+	limits?: WorkerLoaderLimits;
+}
+
+/**
+ * Resource limits for a dynamically loaded worker.
+ * Enforced by the Worker Loader runtime at the V8 isolate level.
+ */
+export interface WorkerLoaderLimits {
+	/** Maximum CPU time in milliseconds per invocation */
+	cpuMs?: number;
+	/** Maximum number of subrequests (fetch/service-binding calls) per invocation */
+	subRequests?: number;
+}
+
+/**
+ * Stub returned by Worker Loader for interacting with dynamic workers.
+ */
+export interface WorkerStub {
+	/**
+	 * Get the default entrypoint (fetch handler).
+	 */
+	fetch(request: Request): Promise<Response>;
+
+	/**
+	 * Get a named entrypoint class instance for RPC.
+	 */
+	getEntrypoint<T = unknown>(name?: string): T;
+}
+
+/**
+ * Plugin manifest - loaded from manifest.json in plugin bundle.
+ */
+export interface LoadedPluginManifest {
+	id: string;
+	version: string;
+	capabilities: string[];
+	allowedHosts: string[];
+	storage: Record<string, { indexes: Array<string | string[]> }>;
+	hooks: string[];
+	routes: string[];
+}
+
+/**
+ * Content item shape returned by bridge content operations.
+ * Matches core's ContentItem from plugins/types.ts.
+ */
+interface BridgeContentItem {
+	id: string;
+	type: string;
+	data: Record<string, unknown>;
+	createdAt: string;
+	updatedAt: string;
+}
+
+/**
+ * Media item shape returned by bridge media operations.
+ * Matches core's MediaItem from plugins/types.ts.
+ */
+interface BridgeMediaItem {
+	id: string;
+	filename: string;
+	mimeType: string;
+	size: number | null;
+	url: string;
+	createdAt: string;
+}
+
+/**
+ * Type for the PluginBridge binding passed to sandboxed workers.
+ * This is the RPC interface exposed by PluginBridge WorkerEntrypoint.
+ */
+export interface PluginBridgeBinding {
+	// KV
+	kvGet(key: string): Promise<unknown>;
+	kvSet(key: string, value: unknown): Promise<void>;
+	kvDelete(key: string): Promise<boolean>;
+	kvList(prefix?: string): Promise<Array<{ key: string; value: unknown }>>;
+	// Storage
+	storageGet(collection: string, id: string): Promise<unknown>;
+	storagePut(collection: string, id: string, data: unknown): Promise<void>;
+	storageDelete(collection: string, id: string): Promise<boolean>;
+	storageQuery(
+		collection: string,
+		opts?: { limit?: number; cursor?: string },
+	): Promise<{ items: Array<{ id: string; data: unknown }>; hasMore: boolean; cursor?: string }>;
+	storageCount(collection: string): Promise<number>;
+	storageGetMany(collection: string, ids: string[]): Promise<Map<string, unknown>>;
+	storagePutMany(collection: string, items: Array<{ id: string; data: unknown }>): Promise<void>;
+	storageDeleteMany(collection: string, ids: string[]): Promise<number>;
+	// Content
+	contentGet(collection: string, id: string): Promise<BridgeContentItem | null>;
+	contentList(
+		collection: string,
+		opts?: { limit?: number; cursor?: string },
+	): Promise<{ items: BridgeContentItem[]; cursor?: string; hasMore: boolean }>;
+	contentCreate(collection: string, data: Record<string, unknown>): Promise<BridgeContentItem>;
+	contentUpdate(
+		collection: string,
+		id: string,
+		data: Record<string, unknown>,
+	): Promise<BridgeContentItem>;
+	contentDelete(collection: string, id: string): Promise<boolean>;
+	// Media
+	mediaGet(id: string): Promise<BridgeMediaItem | null>;
+	mediaList(opts?: {
+		limit?: number;
+		cursor?: string;
+		mimeType?: string;
+	}): Promise<{ items: BridgeMediaItem[]; cursor?: string; hasMore: boolean }>;
+	mediaUpload(
+		filename: string,
+		contentType: string,
+		bytes: ArrayBuffer,
+	): Promise<{ mediaId: string; storageKey: string; url: string }>;
+	mediaDelete(id: string): Promise<boolean>;
+	// Network
+	httpFetch(
+		url: string,
+		init?: RequestInit,
+	): Promise<{ status: number; headers: Record<string, string>; text: string }>;
+	// Email
+	emailSend(message: { to: string; subject: string; text: string; html?: string }): Promise<void>;
+	// Logging
+	log(level: "debug" | "info" | "warn" | "error", msg: string, data?: unknown): void;
+}