emdash 0.0.0-b → 0.0.2

package/src/plugins/request-meta.ts

@@ -0,0 +1,139 @@
+/**
+ * Request Metadata Extraction
+ *
+ * Extracts normalized metadata (IP, user agent, referer, geo) from
+ * incoming requests. Used by plugin route handlers to access request
+ * context without touching raw headers.
+ *
+ */
+
+import type { GeoInfo, RequestMeta } from "./types.js";
+
+/**
+ * Cloudflare Workers `cf` object shape (subset we use).
+ * Present on requests when running on Cloudflare Workers.
+ */
+interface CfProperties {
+	country?: string;
+	region?: string;
+	city?: string;
+}
+
+/**
+ * Loose validation for IPv4 and IPv6 addresses.
+ * Accepts digits, hex chars, dots, and colons — rejects anything else
+ * (e.g. HTML tags, scripts, or other non-IP garbage in spoofed headers).
+ */
+const IP_PATTERN = /^[\da-fA-F.:]+$/;
+
+/**
+ * Extract the first IP from an X-Forwarded-For header value.
+ * The header may contain a comma-separated list of IPs; the first
+ * entry is the original client IP.
+ *
+ * Returns null if the extracted value doesn't look like an IP address.
+ */
+function parseFirstForwardedIp(header: string): string | null {
+	const first = header.split(",")[0];
+	const trimmed = first?.trim();
+	if (!trimmed) return null;
+	return IP_PATTERN.test(trimmed) ? trimmed : null;
+}
+
+/**
+ * Get the Cloudflare `cf` object from the request, if present.
+ * Returns undefined when not running on Cloudflare Workers.
+ */
+function getCfObject(request: Request): CfProperties | undefined {
+	return (request as unknown as { cf?: CfProperties }).cf;
+}
+
+/**
+ * Extract geographic information from the Cloudflare `cf` object
+ * attached to the request. Returns null when not running on CF Workers.
+ */
+function extractGeo(cf: CfProperties | undefined): GeoInfo | null {
+	if (!cf) return null;
+
+	const country = cf.country ?? null;
+	const region = cf.region ?? null;
+	const city = cf.city ?? null;
+
+	// Only return geo if at least one field is populated
+	if (country === null && region === null && city === null) return null;
+
+	return { country, region, city };
+}
+
+/**
+ * Extract normalized request metadata from a Request object.
+ *
+ * IP resolution order:
+ * 1. `CF-Connecting-IP` header — only trusted when a `cf` object is
+ *    present on the request (proving the request came through Cloudflare's
+ *    edge, which strips/overwrites client-supplied values).
+ * 2. `X-Forwarded-For` header (first entry) — best-effort, spoofable
+ *    when there is no trusted reverse proxy.
+ * 3. `null`
+ */
+export function extractRequestMeta(request: Request): RequestMeta {
+	const headers = request.headers;
+	const cf = getCfObject(request);
+
+	// IP: only trust headers when the cf object confirms we're on Cloudflare.
+	// Without a trusted reverse proxy, X-Forwarded-For is trivially spoofable.
+	let ip: string | null = null;
+	if (cf) {
+		const cfIp = headers.get("cf-connecting-ip")?.trim();
+		if (cfIp && IP_PATTERN.test(cfIp)) {
+			ip = cfIp;
+		}
+	}
+	if (!ip && cf) {
+		// Only trust X-Forwarded-For when we're behind Cloudflare (which
+		// overwrites the header). In standalone deployments without a trusted
+		// proxy, XFF is trivially spoofable.
+		const xff = headers.get("x-forwarded-for");
+		ip = xff ? parseFirstForwardedIp(xff) : null;
+	}
+
+	const userAgent = headers.get("user-agent")?.trim() || null;
+	const referer = headers.get("referer")?.trim() || null;
+	const geo = extractGeo(cf);
+
+	return { ip, userAgent, referer, geo };
+}
+
+// =============================================================================
+// Header Sanitization for Sandbox
+// =============================================================================
+
+/**
+ * Headers that must never cross the RPC boundary to sandboxed plugins.
+ * Session tokens, auth credentials, and infrastructure headers are stripped
+ * to prevent malicious plugins from exfiltrating sensitive data.
+ */
+const SANDBOX_STRIPPED_HEADERS = new Set([
+	"cookie",
+	"set-cookie",
+	"authorization",
+	"proxy-authorization",
+	"cf-access-jwt-assertion",
+	"cf-access-client-id",
+	"cf-access-client-secret",
+	"x-emdash-request",
+]);
+
+/**
+ * Copy request headers into a plain object, stripping sensitive headers
+ * that must not be exposed to sandboxed plugin code.
+ */
+export function sanitizeHeadersForSandbox(headers: Headers): Record<string, string> {
+	const safe: Record<string, string> = {};
+	headers.forEach((value, key) => {
+		if (!SANDBOX_STRIPPED_HEADERS.has(key)) {
+			safe[key] = value;
+		}
+	});
+	return safe;
+}

package/src/plugins/routes.ts

@@ -0,0 +1,302 @@
+/**
+ * Plugin Routes v2
+ *
+ * Handles plugin API route invocation with:
+ * - Input validation via Zod schemas
+ * - Route context creation
+ * - Error handling
+ *
+ */
+
+import { PluginContextFactory, type PluginContextFactoryOptions } from "./context.js";
+import { extractRequestMeta } from "./request-meta.js";
+import type { ResolvedPlugin, RouteContext, PluginRoute } from "./types.js";
+
+/**
+ * Route metadata (public flag) without the handler.
+ * Used by the catch-all route to decide auth before dispatch.
+ */
+export interface RouteMeta {
+	public: boolean;
+}
+
+/**
+ * Result from a route invocation
+ */
+export interface RouteResult<T = unknown> {
+	success: boolean;
+	data?: T;
+	error?: {
+		code: string;
+		message: string;
+		details?: unknown;
+	};
+	status: number;
+}
+
+/**
+ * Route invocation options
+ */
+export interface InvokeRouteOptions {
+	/** The original request */
+	request: Request;
+	/** Request body (already parsed) */
+	body?: unknown;
+}
+
+/**
+ * Route handler for a plugin
+ */
+export class PluginRouteHandler {
+	private contextFactory: PluginContextFactory;
+	private plugin: ResolvedPlugin;
+
+	constructor(plugin: ResolvedPlugin, factoryOptions: PluginContextFactoryOptions) {
+		this.plugin = plugin;
+		this.contextFactory = new PluginContextFactory(factoryOptions);
+	}
+
+	/**
+	 * Invoke a route by name
+	 */
+	async invoke(routeName: string, options: InvokeRouteOptions): Promise<RouteResult> {
+		const route = this.plugin.routes[routeName];
+
+		if (!route) {
+			return {
+				success: false,
+				error: {
+					code: "ROUTE_NOT_FOUND",
+					message: `Route "${routeName}" not found in plugin "${this.plugin.id}"`,
+				},
+				status: 404,
+			};
+		}
+
+		// Validate input if schema is provided
+		let validatedInput: unknown;
+		if (route.input) {
+			const parseResult = route.input.safeParse(options.body);
+			if (!parseResult.success) {
+				return {
+					success: false,
+					error: {
+						code: "VALIDATION_ERROR",
+						message: "Invalid request body",
+						details: parseResult.error.format(),
+					},
+					status: 400,
+				};
+			}
+			validatedInput = parseResult.data;
+		} else {
+			validatedInput = options.body;
+		}
+
+		// Create route context
+		const baseContext = this.contextFactory.createContext(this.plugin);
+		const routeContext: RouteContext = {
+			...baseContext,
+			input: validatedInput,
+			request: options.request,
+			requestMeta: extractRequestMeta(options.request),
+		};
+
+		// Execute handler
+		try {
+			const result = await route.handler(routeContext);
+			return {
+				success: true,
+				data: result,
+				status: 200,
+			};
+		} catch (error) {
+			// Handle known error types
+			if (error instanceof PluginRouteError) {
+				return {
+					success: false,
+					error: {
+						code: error.code,
+						message: error.message,
+						details: error.details,
+					},
+					status: error.status,
+				};
+			}
+
+			// Unknown error
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				success: false,
+				error: {
+					code: "INTERNAL_ERROR",
+					message: `Route handler failed: ${message}`,
+				},
+				status: 500,
+			};
+		}
+	}
+
+	/**
+	 * Get all route names
+	 */
+	getRouteNames(): string[] {
+		return Object.keys(this.plugin.routes);
+	}
+
+	/**
+	 * Check if a route exists
+	 */
+	hasRoute(name: string): boolean {
+		return name in this.plugin.routes;
+	}
+
+	/**
+	 * Get route metadata without invoking the handler.
+	 * Returns null if the route doesn't exist.
+	 */
+	getRouteMeta(name: string): RouteMeta | null {
+		const route: PluginRoute | undefined = this.plugin.routes[name];
+		if (!route) return null;
+		return { public: route.public === true };
+	}
+}
+
+/**
+ * Error class for plugin routes
+ * Allows plugins to return structured errors with specific HTTP status codes
+ */
+export class PluginRouteError extends Error {
+	constructor(
+		public code: string,
+		message: string,
+		public status: number = 400,
+		public details?: unknown,
+	) {
+		super(message);
+		this.name = "PluginRouteError";
+	}
+
+	/**
+	 * Create a bad request error (400)
+	 */
+	static badRequest(message: string, details?: unknown): PluginRouteError {
+		return new PluginRouteError("BAD_REQUEST", message, 400, details);
+	}
+
+	/**
+	 * Create an unauthorized error (401)
+	 */
+	static unauthorized(message: string = "Unauthorized"): PluginRouteError {
+		return new PluginRouteError("UNAUTHORIZED", message, 401);
+	}
+
+	/**
+	 * Create a forbidden error (403)
+	 */
+	static forbidden(message: string = "Forbidden"): PluginRouteError {
+		return new PluginRouteError("FORBIDDEN", message, 403);
+	}
+
+	/**
+	 * Create a not found error (404)
+	 */
+	static notFound(message: string = "Not found"): PluginRouteError {
+		return new PluginRouteError("NOT_FOUND", message, 404);
+	}
+
+	/**
+	 * Create a conflict error (409)
+	 */
+	static conflict(message: string, details?: unknown): PluginRouteError {
+		return new PluginRouteError("CONFLICT", message, 409, details);
+	}
+
+	/**
+	 * Create an internal error (500)
+	 */
+	static internal(message: string = "Internal error"): PluginRouteError {
+		return new PluginRouteError("INTERNAL_ERROR", message, 500);
+	}
+}
+
+/**
+ * Registry for all plugin route handlers
+ */
+export class PluginRouteRegistry {
+	private handlers: Map<string, PluginRouteHandler> = new Map();
+
+	constructor(private factoryOptions: PluginContextFactoryOptions) {}
+
+	/**
+	 * Register a plugin's routes
+	 */
+	register(plugin: ResolvedPlugin): void {
+		const handler = new PluginRouteHandler(plugin, this.factoryOptions);
+		this.handlers.set(plugin.id, handler);
+	}
+
+	/**
+	 * Unregister a plugin's routes
+	 */
+	unregister(pluginId: string): void {
+		this.handlers.delete(pluginId);
+	}
+
+	/**
+	 * Invoke a plugin route
+	 */
+	async invoke(
+		pluginId: string,
+		routeName: string,
+		options: InvokeRouteOptions,
+	): Promise<RouteResult> {
+		const handler = this.handlers.get(pluginId);
+
+		if (!handler) {
+			return {
+				success: false,
+				error: {
+					code: "PLUGIN_NOT_FOUND",
+					message: `Plugin "${pluginId}" not found`,
+				},
+				status: 404,
+			};
+		}
+
+		return handler.invoke(routeName, options);
+	}
+
+	/**
+	 * Get all registered plugin IDs
+	 */
+	getPluginIds(): string[] {
+		return [...this.handlers.keys()];
+	}
+
+	/**
+	 * Get routes for a plugin
+	 */
+	getRoutes(pluginId: string): string[] {
+		return this.handlers.get(pluginId)?.getRouteNames() ?? [];
+	}
+
+	/**
+	 * Get route metadata for a specific plugin route.
+	 * Returns null if the plugin or route doesn't exist.
+	 */
+	getRouteMeta(pluginId: string, routeName: string): RouteMeta | null {
+		const handler = this.handlers.get(pluginId);
+		if (!handler) return null;
+		return handler.getRouteMeta(routeName);
+	}
+}
+
+/**
+ * Create a route registry
+ */
+export function createRouteRegistry(
+	factoryOptions: PluginContextFactoryOptions,
+): PluginRouteRegistry {
+	return new PluginRouteRegistry(factoryOptions);
+}

package/src/plugins/sandbox/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Plugin Sandbox Exports
+ *
+ */
+
+export { NoopSandboxRunner, SandboxNotAvailableError, createNoopSandboxRunner } from "./noop.js";
+
+export type {
+	SandboxRunner,
+	SandboxedPlugin,
+	SandboxRunnerFactory,
+	SandboxOptions,
+	SandboxEmailMessage,
+	SandboxEmailSendCallback,
+	ResourceLimits,
+	PluginCodeStorage,
+	SerializedRequest,
+} from "./types.js";

package/src/plugins/sandbox/noop.ts

@@ -0,0 +1,76 @@
+/**
+ * No-op Sandbox Runner
+ *
+ * Default implementation that doesn't support sandboxing.
+ * Used on platforms without Worker Loader (Node.js, Deno, etc.).
+ *
+ */
+
+import type { PluginManifest } from "../types.js";
+import type { SandboxRunner, SandboxedPlugin, SandboxOptions } from "./types.js";
+
+/**
+ * Error thrown when attempting to use sandboxing on an unsupported platform.
+ */
+export class SandboxNotAvailableError extends Error {
+	constructor() {
+		super(
+			"Plugin sandboxing is not available on this platform. " +
+				"Sandboxed plugins require Cloudflare Workers with Worker Loader. " +
+				"Use trusted plugins (from config) instead, or deploy to Cloudflare.",
+		);
+		this.name = "SandboxNotAvailableError";
+	}
+}
+
+/**
+ * No-op sandbox runner for platforms without isolation support.
+ *
+ * - `isAvailable()` returns false
+ * - `load()` throws SandboxNotAvailableError
+ * - `terminateAll()` is a no-op
+ *
+ * This is the default runner when no platform adapter is configured.
+ */
+export class NoopSandboxRunner implements SandboxRunner {
+	/**
+	 * Always returns false - sandboxing is not available.
+	 */
+	isAvailable(): boolean {
+		return false;
+	}
+
+	/**
+	 * Always throws - can't load sandboxed plugins without isolation.
+	 */
+	async load(
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		_manifest: PluginManifest,
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		_code: string,
+	): Promise<SandboxedPlugin> {
+		throw new SandboxNotAvailableError();
+	}
+
+	/**
+	 * No-op - sandboxing not available, email callback is irrelevant.
+	 */
+	setEmailSend(): void {
+		// Nothing to do
+	}
+
+	/**
+	 * No-op - nothing to terminate.
+	 */
+	async terminateAll(): Promise<void> {
+		// Nothing to do
+	}
+}
+
+/**
+ * Create a no-op sandbox runner.
+ * This is used as the default when no platform adapter is configured.
+ */
+export function createNoopSandboxRunner(_options?: SandboxOptions): SandboxRunner {
+	return new NoopSandboxRunner();
+}

package/src/plugins/sandbox/types.ts

@@ -0,0 +1,173 @@
+/**
+ * Plugin Sandbox Types
+ *
+ * Defines interfaces for running plugins in sandboxed V8 isolates.
+ * The SandboxRunner interface is implemented by platform adapters
+ * (e.g., Cloudflare Worker Loader) to provide isolation.
+ *
+ */
+
+import type { Kysely } from "kysely";
+
+import type { Database } from "../../database/types.js";
+import type { PluginManifest, RequestMeta } from "../types.js";
+
+/**
+ * Resource limits for sandboxed plugins.
+ * Enforced by the sandbox runtime (e.g., Worker Loader).
+ */
+export interface ResourceLimits {
+	/** CPU time per invocation in milliseconds (default: 50ms) */
+	cpuMs?: number;
+	/** Memory limit in MB (default: 128MB) */
+	memoryMb?: number;
+	/** Maximum subrequests per invocation (default: 10) */
+	subrequests?: number;
+	/** Wall-clock time limit in milliseconds (default: 30000ms) */
+	wallTimeMs?: number;
+}
+
+/**
+ * Storage interface for loading plugin code.
+ * Could be R2, local filesystem, or any other storage backend.
+ */
+export interface PluginCodeStorage {
+	/** Get plugin bundle code by path */
+	get(path: string): Promise<string | null>;
+	/** Check if a bundle exists */
+	exists(path: string): Promise<boolean>;
+}
+
+/**
+ * Serialized email message for sandbox RPC transport.
+ * Matches the core EmailMessage type but uses only serializable fields.
+ */
+export interface SandboxEmailMessage {
+	to: string;
+	subject: string;
+	text: string;
+	html?: string;
+}
+
+/**
+ * Callback for sending email from a sandboxed plugin.
+ * The sandbox runner wires this up from the EmailPipeline.
+ *
+ * @param message - The email message to send
+ * @param pluginId - The sending plugin's ID (used as source)
+ */
+export type SandboxEmailSendCallback = (
+	message: SandboxEmailMessage,
+	pluginId: string,
+) => Promise<void>;
+
+/**
+ * Options for creating a sandbox runner
+ */
+export interface SandboxOptions {
+	/** Storage interface for loading plugin code */
+	storage?: PluginCodeStorage;
+	/** Database for bridge operations */
+	db: Kysely<Database>;
+	/** Default resource limits */
+	limits?: ResourceLimits;
+	/** Site info for plugin context (injected into wrapper at generation time) */
+	siteInfo?: { name: string; url: string; locale: string };
+	/** Email send callback, wired from the EmailPipeline by the runtime */
+	emailSend?: SandboxEmailSendCallback;
+}
+
+/**
+ * A sandboxed plugin instance.
+ * Provides methods to invoke hooks and routes in the isolated environment.
+ */
+export interface SandboxedPlugin {
+	/** Unique identifier: `${manifest.id}:${manifest.version}` */
+	readonly id: string;
+
+	/**
+	 * Invoke a hook in the sandboxed plugin.
+	 *
+	 * @param hookName - Name of the hook (e.g., "content:beforeSave")
+	 * @param event - Event data to pass to the hook
+	 * @returns Hook result (transformed content, void, etc.)
+	 */
+	invokeHook(hookName: string, event: unknown): Promise<unknown>;
+
+	/**
+	 * Invoke an API route in the sandboxed plugin.
+	 *
+	 * @param routeName - Name of the route
+	 * @param input - Validated input data
+	 * @param request - Serialized request info for context
+	 * @returns Route response data
+	 */
+	invokeRoute(routeName: string, input: unknown, request: SerializedRequest): Promise<unknown>;
+
+	/**
+	 * Terminate the sandboxed plugin.
+	 * Releases resources and prevents further invocations.
+	 */
+	terminate(): Promise<void>;
+}
+
+/**
+ * Serialized request for RPC transport.
+ * Worker Loader can't pass Request objects directly.
+ */
+export interface SerializedRequest {
+	url: string;
+	method: string;
+	headers: Record<string, string>;
+	/** Normalized request metadata extracted before RPC serialization */
+	meta: RequestMeta;
+}
+
+/**
+ * Sandbox runner interface.
+ * Platform adapters implement this to provide plugin isolation.
+ */
+export interface SandboxRunner {
+	/**
+	 * Check if sandboxing is available on this platform.
+	 * Returns false for platforms that don't support isolation.
+	 */
+	isAvailable(): boolean;
+
+	/**
+	 * Load a sandboxed plugin from code.
+	 *
+	 * @param manifest - Plugin manifest with metadata and capabilities
+	 * @param code - The bundled plugin JavaScript code
+	 * @returns A sandboxed plugin instance
+	 * @throws If sandboxing is not available or plugin can't be loaded
+	 */
+	load(manifest: PluginManifest, code: string): Promise<SandboxedPlugin>;
+
+	/**
+	 * 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;
+
+	/**
+	 * Terminate all loaded sandboxed plugins.
+	 * Called during shutdown or when reconfiguring.
+	 */
+	terminateAll(): Promise<void>;
+}
+
+/**
+ * Factory function type for creating sandbox runners.
+ * Exported by platform adapters (e.g., @emdash-cms/adapter-cloudflare/sandbox).
+ *
+ * @example
+ * ```typescript
+ * // In @emdash-cms/adapter-cloudflare/sandbox.ts
+ * export const createSandboxRunner: SandboxRunnerFactory = (options) => {
+ *   return new CloudflareSandboxRunner(options);
+ * };
+ * ```
+ */
+export type SandboxRunnerFactory = (options: SandboxOptions) => SandboxRunner;