emdash 0.29.0 → 0.31.0

package/src/media/image-endpoint.ts

@@ -20,6 +20,17 @@ export const ALLOWED_TRANSFORM_FORMATS = ["webp", "avif", "jpeg", "png"] as cons
 /** Default output format -- broad support, strong compression. */
 export const DEFAULT_TRANSFORM_FORMAT: ImageTransformFormat = "webp";
 
+/**
+ * Default output quality for lossy formats (WebP/AVIF/JPEG) when the request
+ * doesn't specify one. Matches the default Cloudflare applies to URL-based
+ * image transformations. The Images *binding* applies no default of its own
+ * and encodes near-losslessly when quality is omitted (a 2048px WebP comes
+ * out ~900 KB instead of ~100 KB), so the endpoint sends an explicit quality
+ * for lossy output. PNG is exempt: an explicit PNG quality switches the
+ * binding to lossy PNG8, which is not a safe default for a lossless format.
+ */
+export const DEFAULT_TRANSFORM_QUALITY = 85;
+
 /** Upper bound for a requested dimension; caps the work a single request asks for. */
 export const MAX_TRANSFORM_DIMENSION = 4000;
 
@@ -31,6 +42,11 @@ export interface ImageTransformOptions {
 	width?: number;
 	height?: number;
 	format: ImageTransformFormat;
+	/**
+	 * Explicitly-requested quality (1-100), or `undefined` when the request
+	 * carried no `q`. Callers apply their own default per format (see
+	 * {@link DEFAULT_TRANSFORM_QUALITY}); lossless PNG deliberately gets none.
+	 */
 	quality?: number;
 }
 
@@ -117,10 +133,30 @@ export type ParsedTransformParams =
 	| { ok: true; options: ImageTransformOptions }
 	| { ok: false; message: string };
 
+/**
+ * Resolve the quality to send to the image binding for a transform. An
+ * explicitly-requested quality always wins. Otherwise lossy formats
+ * (WebP/AVIF/JPEG) get {@link DEFAULT_TRANSFORM_QUALITY} because the Images
+ * binding encodes near-losslessly when quality is omitted; lossless PNG gets
+ * `undefined` because an explicit PNG quality switches the binding to lossy
+ * PNG8, which is not a safe default for a lossless format.
+ */
+export function resolveTransformQuality(
+	format: ImageTransformFormat,
+	requested: number | undefined,
+): number | undefined {
+	if (requested !== undefined) return requested;
+	return format === "png" ? undefined : DEFAULT_TRANSFORM_QUALITY;
+}
+
 /**
  * Parse and validate `?w=&h=&f=&q=` query params. Width is required (it sizes
  * the rendition); dimensions are bounded so a request can't ask for an
- * unbounded or nonsensical transform.
+ * unbounded or nonsensical transform. Format falls back to
+ * {@link DEFAULT_TRANSFORM_FORMAT} when not requested. `q` is validated when
+ * present but otherwise left `undefined` so the caller can apply a per-format
+ * default (lossy formats get one, lossless PNG does not — see
+ * {@link DEFAULT_TRANSFORM_QUALITY}).
  */
 export function parseTransformParams(params: URLSearchParams): ParsedTransformParams {
 	const width = parseDimension(params.get("w"));
@@ -139,8 +175,8 @@ export function parseTransformParams(params: URLSearchParams): ParsedTransformPa
 		format = formatRaw;
 	}
 
-	const qualityRaw = params.get("q");
 	let quality: number | undefined;
+	const qualityRaw = params.get("q");
 	if (qualityRaw !== null) {
 		const q = Number(qualityRaw);
 		if (!Number.isInteger(q) || q < 1 || q > 100) {

package/src/page/metadata.ts

@@ -80,6 +80,33 @@ export async function createSha256CspHash(value: string): Promise<string> {
 	return `sha256-${btoa(binary)}`;
 }
 
+interface CspScriptHashSink {
+	insertScriptHash(hash: string): void;
+}
+
+/**
+ * Register JSON-LD hashes with Astro's CSP runtime when CSP is enabled.
+ *
+ * The getter stays lazy because Astro warns when `Astro.csp` is accessed on a
+ * project that has not enabled its built-in CSP support.
+ */
+export async function registerJsonLdCspHashes(
+	enabled: boolean,
+	getCsp: () => CspScriptHashSink | undefined,
+	scripts: ReadonlyArray<{ json: string }>,
+): Promise<void> {
+	if (!enabled || scripts.length === 0) return;
+
+	const csp = getCsp();
+	if (!csp) return;
+
+	await Promise.all(
+		scripts.map(async ({ json }) => {
+			csp.insertScriptHash(await createSha256CspHash(json));
+		}),
+	);
+}
+
 // ── Merge / dedupe ──────────────────────────────────────────────
 
 /**

package/src/plugin-types.ts

@@ -38,6 +38,9 @@
  * per-hook return contracts so misuse fails at compile time.
  */
 
+import type { Permission } from "@emdash-cms/auth";
+import type { ZodType } from "zod";
+
 import type {
 	CommentAfterCreateEvent,
 	CommentAfterCreateHandler,
@@ -200,9 +203,24 @@ export type RouteEntry =
 	| {
 			handler: RouteHandler;
 			public?: boolean;
+			/**
+			 * Cache-Control value for successful GET responses. Only honored on
+			 * routes that are also `public: true` — authenticated responses
+			 * always keep `private, no-store`.
+			 */
+			cacheControl?: string;
 			input?: unknown;
+			permission?: Permission;
 	  };
 
+export interface SandboxedMcpTool {
+	description: string;
+	route: string;
+	input: ZodType;
+	output?: ZodType;
+	destructive?: boolean;
+}
+
 /**
  * The shape of a sandboxed plugin's default export.
  *
@@ -217,6 +235,7 @@ export interface SandboxedPlugin {
 		[K in keyof HookHandlers]?: HookEntry<K>;
 	};
 	routes?: Record<string, RouteEntry>;
+	mcp?: { tools: Record<string, SandboxedMcpTool> };
 }
 
 /**

package/src/plugin-utils.ts

@@ -44,13 +44,14 @@ export function getPublicPluginApiRouteHandler(
 }
 
 /**
- * Parse an API response, unwrapping the `{ data: T }` envelope.
+ * Parse an API response, unwrapping the `{ success, data: T }` envelope.
  *
- * All plugin API routes return success responses wrapped in `{ data: ... }`
- * by `apiSuccess()`. This helper unwraps that envelope and handles errors.
+ * All plugin API routes return success responses wrapped in
+ * `{ success: true, data: ... }` by `apiSuccess()`. This helper unwraps that
+ * envelope and handles errors.
  *
  * On error responses (non-2xx), throws an Error with the server's message
- * (from `{ error: { message } }`) or the fallback message.
+ * (from `{ success: false, error: { message } }`) or the fallback message.
  *
  * @example
  * ```ts
@@ -72,8 +73,9 @@ export async function parseApiResponse<T>(
 /**
  * Extract the error message from a failed API response.
  *
- * Error responses use the shape `{ error: { code, message } }`. This helper
- * parses that body and returns the message, falling back to the provided default.
+ * Error responses use the shape `{ success: false, error: { code, message } }`.
+ * This helper parses that body and returns the message, falling back to the
+ * provided default.
  * Swallows JSON parse failures gracefully.
  *
  * @example

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

@@ -108,7 +108,9 @@ function resolveSandboxedHook(entry: AnyHookEntry, pluginId: string): ResolvedHo
 function normalizeRouteEntry(entry: RouteEntry): {
 	handler: RouteHandler;
 	public?: boolean;
+	cacheControl?: string;
 	input?: PluginRoute["input"];
+	permission?: PluginRoute["permission"];
 } {
 	if (typeof entry === "function") {
 		return { handler: entry };
@@ -116,6 +118,8 @@ function normalizeRouteEntry(entry: RouteEntry): {
 	return {
 		handler: entry.handler,
 		public: entry.public,
+		permission: entry.permission,
+		cacheControl: entry.cacheControl,
 		// eslint-disable-next-line typescript-eslint/no-unsafe-type-assertion -- RouteEntry.input is intentionally `unknown` (sandboxed plugins) and validated by the runtime at invocation time
 		input: entry.input as PluginRoute["input"],
 	};
@@ -196,10 +200,18 @@ export function adaptSandboxEntry(
 	if (definition.routes) {
 		for (const [routeName, rawEntry] of Object.entries(definition.routes)) {
 			const normalized = normalizeRouteEntry(rawEntry);
-			const { handler, public: publicFlag, input: inputSchema } = normalized;
+			const {
+				handler,
+				public: publicFlag,
+				cacheControl,
+				input: inputSchema,
+				permission,
+			} = normalized;
 			resolvedRoutes[routeName] = {
 				input: inputSchema,
 				public: publicFlag,
+				permission,
+				cacheControl,
 				handler: async (ctx) => {
 					// `ctx.request` is a real WHATWG `Request` (this is the
 					// in-process adapter; the worker-sandbox adapter handles
@@ -290,6 +302,9 @@ export function adaptSandboxEntry(
 	if (descriptor.adminWidgets) {
 		admin.widgets = descriptor.adminWidgets;
 	}
+	if (descriptor.settingsSchema) {
+		admin.settingsSchema = descriptor.settingsSchema;
+	}
 	if (descriptor.portableTextBlocks) {
 		admin.portableTextBlocks = descriptor.portableTextBlocks;
 	}
@@ -305,6 +320,20 @@ export function adaptSandboxEntry(
 		storage,
 		hooks: resolvedHooks,
 		routes: resolvedRoutes,
+		mcp: {
+			tools: Object.fromEntries(
+				Object.entries(definition.mcp?.tools ?? {}).map(([name, tool]) => [
+					name,
+					{
+						description: tool.description,
+						route: tool.route,
+						input: tool.input,
+						output: tool.output,
+						destructive: tool.destructive,
+					},
+				]),
+			),
+		},
 		admin,
 	};
 }

package/src/plugins/context.ts

@@ -252,6 +252,7 @@ export function createContentAccess(db: Kysely<Database>): ContentAccess {
 				updatedAt: item.updatedAt,
 				locale: item.locale,
 				publishedAt: item.publishedAt,
+				scheduledAt: item.scheduledAt,
 			};
 
 			if (await seoRepo.isEnabled(collection)) {
@@ -292,6 +293,7 @@ export function createContentAccess(db: Kysely<Database>): ContentAccess {
 				updatedAt: item.updatedAt,
 				locale: item.locale,
 				publishedAt: item.publishedAt,
+				scheduledAt: item.scheduledAt,
 			}));
 
 			if (items.length > 0 && (await seoRepo.isEnabled(collection))) {
@@ -398,6 +400,7 @@ export function createContentAccessWithWrite(db: Kysely<Database>): ContentAcces
 						updatedAt: item.updatedAt,
 						locale: item.locale,
 						publishedAt: item.publishedAt,
+						scheduledAt: item.scheduledAt,
 					};
 
 					if (hasSeo) {
@@ -455,6 +458,7 @@ export function createContentAccessWithWrite(db: Kysely<Database>): ContentAcces
 						updatedAt: item.updatedAt,
 						locale: item.locale,
 						publishedAt: item.publishedAt,
+						scheduledAt: item.scheduledAt,
 					};
 
 					if (hasSeo) {
@@ -878,6 +882,8 @@ export interface SiteInfoOptions {
 	siteUrl?: string;
 	/** Site locale from options table */
 	locale?: string;
+	/** Astro's `trailingSlash` config (from `virtual:emdash/config`). */
+	trailingSlash?: "always" | "never" | "ignore";
 }
 
 /**
@@ -893,6 +899,7 @@ export function createSiteInfo(options: SiteInfoOptions): SiteInfo {
 		name: options.siteName ?? "",
 		url: (options.siteUrl ?? "").replace(TRAILING_SLASH_RE, ""), // strip trailing slash
 		locale: options.locale ?? "en",
+		trailingSlash: options.trailingSlash ?? "ignore", // Astro's default
 	};
 }
 

package/src/plugins/define-plugin.ts

@@ -22,6 +22,8 @@ import type {
 	PluginStorageConfig,
 } from "./types.js";
 
+const MCP_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+
 /**
  * Define a native EmDash plugin.
  *
@@ -110,6 +112,7 @@ function defineNativePlugin<TStorage extends PluginStorageConfig>(
 		allowedHosts = [],
 		hooks = {},
 		routes = {},
+		mcp = { tools: {} },
 		admin = {},
 	} = definition;
 
@@ -132,6 +135,18 @@ function defineNativePlugin<TStorage extends PluginStorageConfig>(
 		throw new Error(`Invalid plugin version "${version}". Must be semver format (e.g., "1.0.0").`);
 	}
 
+	for (const [name, tool] of Object.entries(mcp.tools)) {
+		if (!MCP_TOOL_NAME_PATTERN.test(name)) {
+			throw new Error(`Invalid MCP tool name "${name}" in plugin "${id}".`);
+		}
+		const route = routes[tool.route];
+		if (!route) throw new Error(`MCP tool "${name}" references unknown route "${tool.route}".`);
+		if (route.public) throw new Error(`MCP tool "${name}" cannot reference a public route.`);
+		if (!route.permission) {
+			throw new Error(`MCP route "${tool.route}" must declare a permission.`);
+		}
+	}
+
 	// Validate capabilities. Both current names and deprecated aliases are
 	// accepted; aliases are silently rewritten to current names below so the
 	// runtime only ever sees the canonical form. Authors are warned at
@@ -202,6 +217,7 @@ function defineNativePlugin<TStorage extends PluginStorageConfig>(
 		storage,
 		hooks: resolvedHooks,
 		routes,
+		mcp,
 		admin,
 	};
 }

package/src/plugins/manifest-schema.ts

@@ -8,6 +8,7 @@
  * - Marketplace ingest extends this with publishing-specific fields
  */
 
+import { Permissions } from "@emdash-cms/auth";
 import {
 	capabilitiesToDeclaredAccess,
 	declaredAccessToCapabilities,
@@ -137,6 +138,27 @@ const routeNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9_\-/]*$/;
 const manifestRouteEntrySchema = z.object({
 	name: z.string().min(1).regex(routeNamePattern, "Route name must be a safe path segment"),
 	public: z.boolean().optional(),
+	permission: z
+		.string()
+		.refine((permission) => permission in Permissions)
+		.optional(),
+	cacheControl: z.string().min(1).optional(),
+});
+
+const pluginJsonSchema = z.record(z.string(), z.unknown());
+const mcpToolNamePattern = /^[a-zA-Z0-9_-]+$/;
+const pluginMcpConfigSchema = z.object({
+	tools: z.array(
+		z.object({
+			name: z.string().min(1).max(64).regex(mcpToolNamePattern, "Invalid MCP tool name"),
+			description: z.string().min(1),
+			route: z.string().min(1).regex(routeNamePattern, "Route name must be a safe path segment"),
+			permission: z.string().refine((permission) => permission in Permissions),
+			destructive: z.boolean(),
+			inputSchema: pluginJsonSchema,
+			outputSchema: pluginJsonSchema.optional(),
+		}),
+	),
 });
 
 // ── Sub-schemas ─────────────────────────────────────────────────
@@ -307,6 +329,7 @@ export const pluginManifestSchema = z.object({
 			manifestRouteEntrySchema,
 		]),
 	),
+	mcp: pluginMcpConfigSchema.optional(),
 	admin: pluginAdminConfigSchema,
 });
 
@@ -349,9 +372,13 @@ export function normalizeManifestHook(
 /**
  * Normalize a manifest route entry — plain strings become `{ name }` objects.
  */
-export function normalizeManifestRoute(entry: string | { name: string; public?: boolean }): {
+export function normalizeManifestRoute(
+	entry: string | { name: string; public?: boolean; permission?: string; cacheControl?: string },
+): {
 	name: string;
 	public?: boolean;
+	permission?: string;
+	cacheControl?: string;
 } {
 	if (typeof entry === "string") {
 		return { name: entry };

package/src/plugins/routes.ts

@@ -54,6 +54,32 @@ function guardConsumedRequestBody(request: Request): Request {
  */
 export interface RouteMeta {
 	public: boolean;
+	permission?: string;
+	/**
+	 * Cache-Control value for successful GET responses. Only ever set for
+	 * public routes — authenticated responses must stay `private, no-store`.
+	 */
+	cacheControl?: string;
+}
+
+/**
+ * Build RouteMeta from a route's `public`/`cacheControl` flags. Single source
+ * of truth for the "cacheControl is only ever exposed on public routes"
+ * invariant — used for trusted routes and manifest-declared sandboxed routes.
+ */
+export function buildRouteMeta(route: {
+	public?: boolean;
+	permission?: string;
+	cacheControl?: string;
+}): RouteMeta {
+	const meta: RouteMeta = { public: route.public === true };
+	if (route.permission !== undefined) meta.permission = route.permission;
+	// Private responses are per-user and must never become cacheable, even if
+	// a route sets both flags.
+	if (meta.public && typeof route.cacheControl === "string" && route.cacheControl.length > 0) {
+		meta.cacheControl = route.cacheControl;
+	}
+	return meta;
 }
 
 /**
@@ -199,7 +225,7 @@ export class PluginRouteHandler {
 	getRouteMeta(name: string): RouteMeta | null {
 		const route: PluginRoute | undefined = this.plugin.routes[name];
 		if (!route) return null;
-		return { public: route.public === true };
+		return buildRouteMeta(route);
 	}
 }
 

package/src/plugins/sandbox/runner-options.ts

@@ -0,0 +1,16 @@
+import { createSiteInfo, type SiteInfoOptions } from "../context.js";
+import type { SandboxOptions } from "./types.js";
+
+/**
+ * Build platform sandbox options with the same normalized site context used
+ * by trusted plugin hooks and routes.
+ */
+export function createSandboxRunnerOptions(
+	options: Omit<SandboxOptions, "siteInfo">,
+	siteInfo?: SiteInfoOptions,
+): SandboxOptions {
+	return {
+		...options,
+		siteInfo: createSiteInfo(siteInfo ?? {}),
+	};
+}

package/src/plugins/sandbox/types.ts

@@ -72,7 +72,12 @@ export interface SandboxOptions {
 	/** Default resource limits */
 	limits?: ResourceLimits;
 	/** Site info for plugin context (injected into wrapper at generation time) */
-	siteInfo?: { name: string; url: string; locale: string };
+	siteInfo?: {
+		name: string;
+		url: string;
+		locale: string;
+		trailingSlash?: "always" | "never" | "ignore";
+	};
 	/** Email send callback, wired from the EmailPipeline by the runtime */
 	emailSend?: SandboxEmailSendCallback;
 	/**

package/src/plugins/state.ts

@@ -49,6 +49,8 @@ export interface PluginState {
 	 * `packages/core/src/registry/plugin-id.ts`.
 	 */
 	registrySlug: string | null;
+	mcpToolsEnabled: boolean;
+	mcpToolsConsent: string | null;
 }
 
 /**
@@ -121,6 +123,8 @@ export class PluginStateRepository {
 			description?: string;
 			registryPublisherDid?: string;
 			registrySlug?: string;
+			mcpToolsEnabled?: boolean;
+			mcpToolsConsent?: string | null;
 		},
 	): Promise<PluginState> {
 		const now = new Date().toISOString();
@@ -128,7 +132,7 @@ export class PluginStateRepository {
 
 		if (existing) {
 			// Update existing state
-			const updates: Record<string, string | null> = {
+			const updates: Record<string, string | number | null> = {
 				status,
 				version,
 			};
@@ -155,6 +159,12 @@ export class PluginStateRepository {
 			if (opts?.registrySlug !== undefined) {
 				updates.registry_slug = opts.registrySlug;
 			}
+			if (opts?.mcpToolsEnabled !== undefined) {
+				updates.mcp_tools_enabled = opts.mcpToolsEnabled ? 1 : 0;
+			}
+			if (opts?.mcpToolsConsent !== undefined) {
+				updates.mcp_tools_consent = opts.mcpToolsConsent;
+			}
 
 			await this.db
 				.updateTable("_plugin_state")
@@ -179,6 +189,8 @@ export class PluginStateRepository {
 					description: opts?.description ?? null,
 					registry_publisher_did: opts?.registryPublisherDid ?? null,
 					registry_slug: opts?.registrySlug ?? null,
+					mcp_tools_enabled: opts?.mcpToolsEnabled ? 1 : 0,
+					mcp_tools_consent: opts?.mcpToolsConsent ?? null,
 				})
 				.execute();
 		}
@@ -234,6 +246,8 @@ interface PluginStateRow {
 	description: string | null;
 	registry_publisher_did: string | null;
 	registry_slug: string | null;
+	mcp_tools_enabled: number;
+	mcp_tools_consent: string | null;
 }
 
 function rowToPluginState(row: PluginStateRow): PluginState {
@@ -250,5 +264,7 @@ function rowToPluginState(row: PluginStateRow): PluginState {
 		description: row.description ?? null,
 		registryPublisherDid: row.registry_publisher_did ?? null,
 		registrySlug: row.registry_slug ?? null,
+		mcpToolsEnabled: row.mcp_tools_enabled === 1,
+		mcpToolsConsent: row.mcp_tools_consent ?? null,
 	};
 }