emdash 0.11.1 → 0.13.0

package/src/plugins/adapt-sandbox-entry.ts

@@ -11,12 +11,10 @@
  */
 
 import type { PluginDescriptor } from "../astro/integration/runtime.js";
+import type { SandboxedPlugin } from "../plugin-types.js";
 import { PLUGIN_CAPABILITIES, HOOK_NAMES } from "./manifest-schema.js";
 import { normalizeCapabilities } from "./types.js";
 import type {
-	StandardPluginDefinition,
-	StandardHookEntry,
-	StandardHookHandler,
 	ResolvedPlugin,
 	ResolvedPluginHooks,
 	ResolvedHook,
@@ -26,6 +24,29 @@ import type {
 	PluginAdminConfig,
 } from "./types.js";
 
+/**
+ * Loose per-hook entry shape used inside the adapter's iteration loop.
+ *
+ * `SandboxedPlugin.hooks` is a mapped type keyed by hook name, so each
+ * entry's type depends on the key. When the adapter iterates with
+ * `Object.entries`, the key is `string` (TypeScript can't see the
+ * narrowing), so we need a *union* type that covers every hook entry
+ * shape — bare handler or config form. This is that union, kept local
+ * because it has no use outside the adapter.
+ */
+// eslint-disable-next-line typescript-eslint/no-explicit-any -- must accept handlers with specific event types across all hook names
+type AnyHookHandler = (...args: any[]) => Promise<any>;
+type AnyHookEntry =
+	| AnyHookHandler
+	| {
+			handler: AnyHookHandler;
+			priority?: number;
+			timeout?: number;
+			dependencies?: string[];
+			errorPolicy?: "continue" | "abort";
+			exclusive?: boolean;
+	  };
+
 /**
  * Default hook configuration values
  */
@@ -34,27 +55,23 @@ const DEFAULT_TIMEOUT = 5000;
 const DEFAULT_ERROR_POLICY = "abort" as const;
 
 /**
- * Check if a standard hook entry is a config object (has a `handler` property)
+ * Check if a hook entry is the config form (has a `handler` property).
  */
-function isHookConfig(
-	entry: StandardHookEntry,
-): entry is Exclude<StandardHookEntry, StandardHookHandler> {
+function isHookConfig(entry: AnyHookEntry): entry is Exclude<AnyHookEntry, AnyHookHandler> {
 	return typeof entry === "object" && entry !== null && "handler" in entry;
 }
 
 /**
- * Resolve a single standard hook entry to a ResolvedHook.
+ * Resolve a single hook entry to a ResolvedHook.
  *
- * Standard-format hooks use the sandbox entry convention:
- *   handler(event, ctx) -- two args
+ * Sandboxed-format hooks use the standard two-arg convention:
+ *   handler(event, ctx)
  *
  * The HookPipeline dispatch methods also call handlers with (event, ctx),
- * so the handler is compatible as-is. We just need to wrap it for type safety.
+ * so the handler is compatible as-is — we just normalise the
+ * surrounding config (priority, timeout, etc.) to its defaults.
  */
-function resolveStandardHook(
-	entry: StandardHookEntry,
-	pluginId: string,
-): ResolvedHook<StandardHookHandler> {
+function resolveSandboxedHook(entry: AnyHookEntry, pluginId: string): ResolvedHook<AnyHookHandler> {
 	if (isHookConfig(entry)) {
 		return {
 			priority: entry.priority ?? DEFAULT_PRIORITY,
@@ -84,27 +101,46 @@ const VALID_CAPABILITIES_SET = new Set<string>(PLUGIN_CAPABILITIES);
 const VALID_HOOK_NAMES_SET = new Set<string>(HOOK_NAMES);
 
 /**
- * Adapt a standard-format plugin definition into a ResolvedPlugin.
+ * Adapt a sandboxed plugin's default export into a ResolvedPlugin.
  *
- * This is the core of the unified plugin format. It takes the `{ hooks, routes }`
- * export from a standard plugin and produces a ResolvedPlugin that can enter the
- * HookPipeline alongside native plugins.
+ * This is the in-process side of sandboxed-format plugins: it takes
+ * the `{ hooks, routes }` default export of a sandboxed plugin and
+ * produces a `ResolvedPlugin` that enters the HookPipeline alongside
+ * native plugins. The descriptor supplies identity (id, version) and
+ * the trust contract (capabilities, allowedHosts, storage); the
+ * definition supplies behaviour.
  *
- * @param definition - The standard plugin definition (from definePlugin() or raw export)
+ * @param definition - The plugin's default export (matching `SandboxedPlugin` from `emdash/plugin`).
  * @param descriptor - The plugin descriptor with id, version, capabilities, etc.
- * @returns A ResolvedPlugin compatible with HookPipeline
+ * @returns A ResolvedPlugin compatible with HookPipeline.
  */
 export function adaptSandboxEntry(
-	definition: StandardPluginDefinition,
+	definition: SandboxedPlugin,
 	descriptor: PluginDescriptor,
 ): ResolvedPlugin {
 	const pluginId = descriptor.id;
 	const version = descriptor.version;
 
-	// Resolve hooks
+	// A null / array / non-object `definition` would throw a generic
+	// `TypeError: Cannot read properties of null` further down the
+	// loop without the plugin id; surface a useful error first.
+	if (typeof definition !== "object" || definition === null || Array.isArray(definition)) {
+		throw new Error(
+			`Plugin "${pluginId}" default export must be an object with ` +
+				`\`hooks\` and/or \`routes\` (got ${
+					Array.isArray(definition) ? "array" : typeof definition
+				}). Did you forget \`export default {...} satisfies SandboxedPlugin\`?`,
+		);
+	}
+
+	// Resolve hooks. `SandboxedPlugin.hooks` is keyed by hook name with
+	// per-key entry types; iterating with `Object.entries` collapses
+	// keys to `string`, so we treat each entry as the union `AnyHookEntry`
+	// for the duration of the loop.
 	const resolvedHooks: ResolvedPluginHooks = {};
 	if (definition.hooks) {
-		for (const [hookName, entry] of Object.entries(definition.hooks)) {
+		const hookMap = definition.hooks as Record<string, AnyHookEntry>;
+		for (const [hookName, entry] of Object.entries(hookMap)) {
 			if (!VALID_HOOK_NAMES_SET.has(hookName)) {
 				throw new Error(
 					`Plugin "${pluginId}" declares unknown hook "${hookName}". ` +
@@ -115,33 +151,73 @@ export function adaptSandboxEntry(
 			// We store it as the generic type and let HookPipeline's typed dispatch
 			// methods handle the type narrowing at call time.
 			// eslint-disable-next-line typescript-eslint/no-unsafe-type-assertion -- bridging untyped map to typed interface
-			(resolvedHooks as Record<string, unknown>)[hookName] = resolveStandardHook(entry, pluginId);
+			(resolvedHooks as Record<string, unknown>)[hookName] = resolveSandboxedHook(entry, pluginId);
 		}
 	}
 
-	// Resolve routes: standard format uses (routeCtx, pluginCtx) two-arg pattern.
-	// Native format uses (ctx: RouteContext) single-arg pattern where RouteContext
-	// extends PluginContext with { input, request, requestMeta }.
-	// We wrap standard route handlers to merge the two args into one.
+	// Resolve routes: sandboxed format uses (routeCtx, pluginCtx) two-arg
+	// pattern. Native format uses (ctx: RouteContext) single-arg pattern
+	// where RouteContext extends PluginContext with
+	// { input, request, requestMeta }. We wrap sandboxed route handlers
+	// to merge the two args into one.
+	//
+	// Route entries can be bare functions or `{ handler, public?, input? }`
+	// config objects; normalise to the config shape inside the loop.
 	const resolvedRoutes: Record<string, PluginRoute> = {};
 	if (definition.routes) {
-		for (const [routeName, routeEntry] of Object.entries(definition.routes)) {
-			const standardHandler = routeEntry.handler;
+		for (const [routeName, rawEntry] of Object.entries(definition.routes)) {
+			const isConfig = typeof rawEntry === "object" && rawEntry !== null && "handler" in rawEntry;
+			const handler = isConfig
+				? (rawEntry as { handler: (...args: unknown[]) => Promise<unknown> }).handler
+				: (rawEntry as (...args: unknown[]) => Promise<unknown>);
+			const publicFlag = isConfig ? (rawEntry as { public?: boolean }).public : undefined;
+			const inputSchema = isConfig ? (rawEntry as { input?: unknown }).input : undefined;
 			resolvedRoutes[routeName] = {
-				// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- StandardRouteEntry.input is intentionally loosely typed; callers validate at runtime
-				input: routeEntry.input as PluginRoute["input"],
-				public: routeEntry.public,
+				// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- route entry.input is intentionally loosely typed; callers validate at runtime
+				input: inputSchema as PluginRoute["input"],
+				public: publicFlag,
 				handler: async (ctx) => {
-					// Build the routeCtx shape that standard handlers expect
+					// In-process, `ctx.request` is a real WHATWG `Request`
+					// with a `Headers` object. The author-facing
+					// `SandboxedRequest` type promises a plain
+					// `Record<string, string>` (the shape the sandbox's
+					// serialised form delivers). Normalise so handlers
+					// behave the same in-process and in-isolate.
+					const headers: Record<string, string> = {};
+					if (ctx.request && typeof ctx.request === "object") {
+						const h: unknown = (ctx.request as { headers?: unknown }).headers;
+						if (h && typeof h === "object") {
+							if (typeof (h as Headers).forEach === "function") {
+								(h as Headers).forEach((value, name) => {
+									headers[name] = value;
+								});
+							} else {
+								for (const [name, value] of Object.entries(h as Record<string, string>)) {
+									headers[name] = value;
+								}
+							}
+						}
+					}
+					const requestShape = {
+						url:
+							(ctx.request as { url?: unknown } | undefined)?.url &&
+							typeof (ctx.request as { url: unknown }).url === "string"
+								? (ctx.request as { url: string }).url
+								: "",
+						method:
+							(ctx.request as { method?: unknown } | undefined)?.method &&
+							typeof (ctx.request as { method: unknown }).method === "string"
+								? (ctx.request as { method: string }).method
+								: "GET",
+						headers,
+					};
 					const routeCtx = {
 						input: ctx.input,
-						request: ctx.request,
+						request: requestShape,
 						requestMeta: ctx.requestMeta,
 					};
-					// Pass only the PluginContext portion (without input/request/requestMeta)
-					// to match what sandboxed handlers receive.
 					const { input: _, request: __, requestMeta: ___, ...pluginCtx } = ctx;
-					return standardHandler(routeCtx, pluginCtx);
+					return handler(routeCtx, pluginCtx);
 				},
 			};
 		}

package/src/plugins/context.ts

@@ -21,6 +21,7 @@ import {
 	SsrfError,
 	stripCredentialHeaders,
 } from "../import/ssrf.js";
+import { invalidateSiteSettingsCache } from "../settings/index.js";
 import type { Storage } from "../storage/types.js";
 import { CronAccessImpl } from "./cron.js";
 import type { EmailPipeline } from "./email.js";
@@ -502,7 +503,16 @@ export function createMediaAccessWithWrite(
 		},
 
 		async delete(id: string): Promise<boolean> {
-			return mediaRepo.delete(id);
+			const deleted = await mediaRepo.delete(id);
+			// Plugins can delete media that's referenced by site settings
+			// (`logo`, `favicon`, `seo.defaultOgImage`); the worker-scoped
+			// resolved-URL cache must be dropped or it will keep serving
+			// 404s. Matches the invalidation in
+			// `EmDashRuntime.handleMediaDelete`.
+			if (deleted) {
+				invalidateSiteSettingsCache();
+			}
+			return deleted;
 		},
 	};
 }

package/src/plugins/define-plugin.ts

@@ -1,16 +1,13 @@
 /**
  * definePlugin() Helper
  *
- * Creates a properly typed and normalized plugin definition.
- * Supports two formats:
- *
- * 1. **Native format** -- full PluginDefinition with id, version, capabilities, etc.
- *    Returns a ResolvedPlugin.
- *
- * 2. **Standard format** -- just { hooks, routes }. No id/version/capabilities.
- *    Returns the same object (identity function for type inference).
- *    Metadata comes from the descriptor at config time.
+ * Native plugin authoring entry. Returns a fully-resolved
+ * `ResolvedPlugin` ready for the host integration to mount.
  *
+ * Sandboxed plugins do NOT use this function. They default-export
+ * a bare `{ hooks?, routes? }` object with a `satisfies SandboxedPlugin`
+ * annotation from `emdash/plugin`. See the `emdash` changeset for the
+ * authoring shape.
  */
 
 import { normalizeCapabilities } from "./types.js";
@@ -23,7 +20,6 @@ import type {
 	HookConfig,
 	PluginCapability,
 	PluginStorageConfig,
-	StandardPluginDefinition,
 } from "./types.js";
 
 // Plugin ID validation patterns
@@ -32,33 +28,13 @@ const SCOPED_ID = /^@[a-z0-9-]+\/[a-z0-9-]+$/;
 const SEMVER_PATTERN = /^\d+\.\d+\.\d+/;
 
 /**
- * Define an EmDash plugin.
- *
- * **Standard format** -- the canonical format for plugins that work in both
- * trusted and sandboxed modes. No id/version -- those come from the descriptor.
- *
- * @example
- * ```typescript
- * import { definePlugin } from "emdash";
- *
- * export default definePlugin({
- *   hooks: {
- *     "content:afterSave": {
- *       handler: async (event, ctx) => {
- *         await ctx.kv.set("lastSave", Date.now());
- *       },
- *     },
- *   },
- *   routes: {
- *     status: {
- *       handler: async (routeCtx, ctx) => ({ ok: true }),
- *     },
- *   },
- * });
- * ```
+ * Define a native EmDash plugin.
  *
- * **Native format** -- for plugins that need React admin, direct DB access,
- * or other capabilities not available in the sandbox.
+ * Native plugins ship as regular npm modules, get installed via
+ * `pnpm add` + an `astro.config.mjs` edit, and run in the host
+ * process. They have full access to the runtime — capabilities are
+ * still enforced by `PluginContextFactory`, but there is no isolation
+ * boundary.
  *
  * @example
  * ```typescript
@@ -83,30 +59,32 @@ const SEMVER_PATTERN = /^\d+\.\d+\.\d+/;
  *   }
  * });
  * ```
+ *
+ * Sandboxed-format plugins do not use `definePlugin`. They
+ * default-export a bare `{ hooks?, routes? }` object with a
+ * `satisfies SandboxedPlugin` annotation from `emdash/plugin`. Calling
+ * `definePlugin` with an object that has no `id` throws at runtime
+ * (the type system already rejects it at compile time — this check is
+ * for callers that bypass typechecking).
  */
-// Native overload first -- PluginDefinition (with id+version) is more specific
 export function definePlugin<TStorage extends PluginStorageConfig>(
 	definition: PluginDefinition<TStorage>,
-): ResolvedPlugin<TStorage>;
-// Standard overload second -- catches { hooks, routes } without id/version
-export function definePlugin(definition: StandardPluginDefinition): StandardPluginDefinition;
-export function definePlugin<TStorage extends PluginStorageConfig>(
-	definition: PluginDefinition<TStorage> | StandardPluginDefinition,
-): ResolvedPlugin<TStorage> | StandardPluginDefinition {
-	// Standard format: has hooks/routes but no id/version
-	if (!("id" in definition) || !("version" in definition)) {
-		// Validate that the standard format has at least hooks or routes
-		if (!("hooks" in definition) && !("routes" in definition)) {
-			throw new Error(
-				"Standard plugin format requires at least `hooks` or `routes`. " +
-					"For native format, provide `id` and `version`.",
-			);
-		}
-		// Identity function -- return as-is for type inference.
-		// The adapter (adaptSandboxEntry) will convert this to a ResolvedPlugin at build time.
-		return definition;
+): ResolvedPlugin<TStorage> {
+	// Semantic check, not a structural one: `id` is what makes this a
+	// native definition. Sandboxed plugins (the only other shape that
+	// might land here at runtime) intentionally never have an `id` —
+	// identity comes from the manifest's `slug` + `publisher`, computed
+	// at install time. So "no id" is the unambiguous signal that the
+	// caller meant the sandboxed authoring flow.
+	if (typeof definition.id !== "string" || definition.id.length === 0) {
+		throw new Error(
+			`definePlugin() requires \`id\` (got ${typeof definition.id}). ` +
+				"For native plugins, make sure your definition has both `id` and " +
+				"`version`. For sandboxed plugins, drop `definePlugin()` entirely " +
+				"and `export default { hooks, routes } satisfies SandboxedPlugin` " +
+				'from "emdash/plugin" — identity comes from `emdash-plugin.jsonc`.',
+		);
 	}
-
 	return defineNativePlugin(definition);
 }
 

package/src/plugins/index.ts

@@ -71,7 +71,7 @@ export {
 } from "./sandbox/index.js";
 export type {
 	SandboxRunner,
-	SandboxedPlugin,
+	SandboxedPluginInstance,
 	SandboxRunnerFactory,
 	SandboxOptions,
 	SandboxEmailMessage,
@@ -183,15 +183,7 @@ export type {
 	PluginDefinition,
 	ResolvedPlugin,
 	PluginManifest,
-
-	// Standard plugin format
-	StandardPluginDefinition,
-	StandardHookHandler,
-	StandardHookEntry,
-	StandardRouteHandler,
-	StandardRouteEntry,
 } from "./types.js";
-export { isStandardPluginDefinition } from "./types.js";
 
 // Capability normalization (legacy → canonical alias layer)
 export {

package/src/plugins/marketplace.ts

@@ -376,7 +376,26 @@ class MarketplaceClientImpl implements MarketplaceClient {
  *
  * We use a minimal tar parser since we only need to read a few small files.
  */
-async function extractBundle(tarballBytes: Uint8Array): Promise<PluginBundle> {
+/**
+ * Exported so the experimental registry install handler can reuse the
+ * same parse / validate / hash primitive. Despite the file name, this
+ * function predates the marketplace-vs-registry split and is generic
+ * over plugin bundle tarballs regardless of distribution channel.
+ */
+// Aligns with RFC 0001 §"Bundle size limits" (256 KiB decompressed,
+// 20 files). Matches `MAX_BUNDLE_SIZE` in cli/commands/bundle-utils.ts
+// (the publish-side cap). We don't import that constant to keep this
+// runtime module independent of the CLI; the two values are
+// load-bearing identical and must stay in sync.
+//
+// Tar adds per-file headers (~512 bytes each) plus directory entries,
+// so the entry count cap is set comfortably above RFC's 20-file limit.
+// Going over either is a strong signal the bundle isn't a legitimate
+// sandboxed plugin.
+const MAX_DECOMPRESSED_BUNDLE_BYTES = 256 * 1024;
+const MAX_BUNDLE_TAR_ENTRIES = 32;
+
+export async function extractBundle(tarballBytes: Uint8Array): Promise<PluginBundle> {
 	// Decompress fully into memory first, then parse the tar.
 	// Passing a pipeThrough() stream directly to unpackTar causes a backpressure
 	// deadlock in workerd: the tar decoder's body-stream pull() needs more
@@ -389,9 +408,42 @@ async function extractBundle(tarballBytes: Uint8Array): Promise<PluginBundle> {
 		},
 	}).pipeThrough(createGzipDecoder());
 
-	// Collect decompressed bytes fully before parsing
-	const decompressedBuf = await new Response(decompressedStream).arrayBuffer();
-	const decompressedBytes = new Uint8Array(decompressedBuf);
+	// Collect decompressed bytes with a hard cap. A gzip-bomb -- a small
+	// tarball that decompresses to gigabytes -- otherwise exhausts
+	// worker / Node memory before we know to reject it. The cap matches
+	// RFC 0001's publish-time bundle size limit (MAX_DECOMPRESSED_BUNDLE_BYTES);
+	// anything past that isn't a legitimate sandboxed plugin.
+	const reader = decompressedStream.getReader();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (!value) continue;
+		total += value.byteLength;
+		if (total > MAX_DECOMPRESSED_BUNDLE_BYTES) {
+			try {
+				await reader.cancel();
+			} catch {
+				// nothing to do
+			}
+			throw new MarketplaceError(
+				`Bundle decompressed size exceeds limit (${MAX_DECOMPRESSED_BUNDLE_BYTES} bytes)`,
+				undefined,
+				"INVALID_BUNDLE",
+			);
+		}
+		chunks.push(value);
+	}
+	const decompressedBytes = new Uint8Array(total);
+	{
+		let offset = 0;
+		for (const chunk of chunks) {
+			decompressedBytes.set(chunk, offset);
+			offset += chunk.byteLength;
+		}
+	}
+
 	const decompressed = new ReadableStream<Uint8Array>({
 		start(controller) {
 			controller.enqueue(decompressedBytes);
@@ -400,6 +452,13 @@ async function extractBundle(tarballBytes: Uint8Array): Promise<PluginBundle> {
 	});
 
 	const entries = await unpackTar(decompressed);
+	if (entries.length > MAX_BUNDLE_TAR_ENTRIES) {
+		throw new MarketplaceError(
+			`Bundle has too many tar entries (${entries.length} > ${MAX_BUNDLE_TAR_ENTRIES})`,
+			undefined,
+			"INVALID_BUNDLE",
+		);
+	}
 
 	const decoder = new TextDecoder();
 	const files = new Map<string, string>();

package/src/plugins/sandbox/index.ts

@@ -7,7 +7,7 @@ export { NoopSandboxRunner, SandboxNotAvailableError, createNoopSandboxRunner }
 
 export type {
 	SandboxRunner,
-	SandboxedPlugin,
+	SandboxedPluginInstance,
 	SandboxRunnerFactory,
 	SandboxOptions,
 	SandboxEmailMessage,

package/src/plugins/sandbox/noop.ts

@@ -7,7 +7,7 @@
  */
 
 import type { PluginManifest } from "../types.js";
-import type { SandboxRunner, SandboxedPlugin, SandboxOptions } from "./types.js";
+import type { SandboxRunner, SandboxedPluginInstance, SandboxOptions } from "./types.js";
 
 /**
  * Error thrown when attempting to use sandboxing on an unsupported platform.
@@ -48,7 +48,7 @@ export class NoopSandboxRunner implements SandboxRunner {
 		_manifest: PluginManifest,
 		// eslint-disable-next-line @typescript-eslint/no-unused-vars
 		_code: string,
-	): Promise<SandboxedPlugin> {
+	): Promise<SandboxedPluginInstance> {
 		throw new SandboxNotAvailableError();
 	}
 

package/src/plugins/sandbox/types.ts

@@ -78,10 +78,13 @@ export interface SandboxOptions {
 }
 
 /**
- * A sandboxed plugin instance.
- * Provides methods to invoke hooks and routes in the isolated environment.
+ * Handle to a sandboxed plugin running inside an isolate. Returned
+ * by `SandboxRunner.load` and held by the runtime's cache so hooks /
+ * routes can be invoked across the isolate boundary. Distinct from
+ * the author-facing `SandboxedPlugin` type in `emdash/plugin`, which
+ * describes the source-level shape of a plugin's default export.
  */
-export interface SandboxedPlugin {
+export interface SandboxedPluginInstance {
 	/** Unique identifier: `${manifest.id}:${manifest.version}` */
 	readonly id: string;
 
@@ -142,7 +145,7 @@ export interface SandboxRunner {
 	 * @returns A sandboxed plugin instance
 	 * @throws If sandboxing is not available or plugin can't be loaded
 	 */
-	load(manifest: PluginManifest, code: string): Promise<SandboxedPlugin>;
+	load(manifest: PluginManifest, code: string): Promise<SandboxedPluginInstance>;
 
 	/**
 	 * Set the email send callback for sandboxed plugins.