emdash 0.32.0 → 0.34.0

package/src/plugin-types.ts

@@ -86,6 +86,7 @@ import type {
 	PluginContext,
 	UninstallEvent,
 	UninstallHandler,
+	UserInfo,
 } from "./plugins/types.js";
 
 /**
@@ -178,6 +179,13 @@ export interface SandboxedRouteContext {
 	input: unknown;
 	request: SandboxedRequest;
 	requestMeta?: unknown;
+	/**
+	 * Authenticated caller, if the route is private. Resolved and
+	 * authorized by the host before dispatch — trust it over any user id
+	 * in the request body. `undefined` for public routes and for machine
+	 * tokens with no bound user.
+	 */
+	user?: UserInfo;
 }
 
 /**

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

@@ -189,13 +189,24 @@ export function adaptSandboxEntry(
 	}
 
 	// 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.
+	// pattern. Standard format (`definePlugin(...)` as the default export)
+	// uses the public (ctx: RouteContext) single-arg pattern where
+	// RouteContext extends PluginContext with { input, request, requestMeta }.
+	//
+	// The two conventions disagree on the FIRST argument (`request` is a
+	// flattened plain object for sandboxed, a real WHATWG `Request` for
+	// standard), so the wrapper must know which contract the handler was
+	// written against. `definePlugin` requires `id`, and sandbox-format
+	// default exports never carry one (identity comes from the manifest's
+	// slug + publisher) — the same "no id" signal definePlugin itself
+	// documents. Calling a single-arg standard handler with the two-arg
+	// convention silently hands it the bare route context (JS drops the
+	// extra argument), so `ctx.storage` / `ctx.email` / etc. are all
+	// undefined at runtime (#2079).
 	//
 	// Route entries can be bare functions or `{ handler, public?, input? }`
 	// config objects; normalise to the config shape inside the loop.
+	const usesPublicRouteContext = "id" in definition && typeof definition.id === "string";
 	const resolvedRoutes: Record<string, PluginRoute> = {};
 	if (definition.routes) {
 		for (const [routeName, rawEntry] of Object.entries(definition.routes)) {
@@ -213,6 +224,13 @@ export function adaptSandboxEntry(
 				permission,
 				cacheControl,
 				handler: async (ctx) => {
+					if (usesPublicRouteContext) {
+						// The incoming ctx already IS the public RouteContext
+						// (full PluginContext + input / real Request /
+						// requestMeta) — pass it through unchanged.
+						// eslint-disable-next-line typescript-eslint/no-unsafe-type-assertion -- standard-format handlers are authored against the public single-arg PluginRoute contract; the sandbox RouteHandler type on `normalized` is the wider authoring union
+						return (handler as unknown as PluginRoute["handler"])(ctx);
+					}
 					// `ctx.request` is a real WHATWG `Request` (this is the
 					// in-process adapter; the worker-sandbox adapter handles
 					// the serialised case). Flatten `Headers` to the plain
@@ -232,8 +250,9 @@ export function adaptSandboxEntry(
 						input: ctx.input,
 						request: requestShape,
 						requestMeta: ctx.requestMeta,
+						user: ctx.user,
 					};
-					const { input: _, request: __, requestMeta: ___, ...pluginCtx } = ctx;
+					const { input: _, request: __, requestMeta: ___, user: ____, ...pluginCtx } = ctx;
 					return handler(routeCtx, pluginCtx);
 				},
 			};

package/src/plugins/context.ts

@@ -17,6 +17,7 @@ import { TaxonomyRepository, type Taxonomy } from "../database/repositories/taxo
 import { UserRepository } from "../database/repositories/user.js";
 import { withTransaction } from "../database/transaction.js";
 import type { Database } from "../database/types.js";
+import { resolveContentCreateLocale } from "../i18n/config.js";
 import {
 	resolveAndValidateExternalUrl,
 	SsrfError,
@@ -46,6 +47,7 @@ import type {
 	UserAccess,
 	UserInfo,
 	ContentItem,
+	ContentCreateOptions,
 	ContentItemSeoInput,
 	ContentWriteInput,
 	MediaItem,
@@ -367,13 +369,22 @@ export function createTaxonomyAccess(db: Kysely<Database>): TaxonomyAccess {
  * the content write. The returned `ContentItem.seo` reflects the resulting
  * SEO state for SEO-enabled collections.
  */
-export function createContentAccessWithWrite(db: Kysely<Database>): ContentAccessWithWrite {
+export function createContentAccessWithWrite(
+	db: Kysely<Database>,
+	beforeContentWrite?: () => Promise<void>,
+): ContentAccessWithWrite {
 	const readAccess = createContentAccess(db);
 
 	return {
 		...readAccess,
 
-		async create(collection: string, data: ContentWriteInput): Promise<ContentItem> {
+		async create(
+			collection: string,
+			data: ContentWriteInput,
+			options?: ContentCreateOptions,
+		): Promise<ContentItem> {
+			const locale = resolveContentCreateLocale(options?.locale);
+			await beforeContentWrite?.();
 			const { fields, seo } = splitSeoFromInput(data);
 			let contentMutated = false;
 
@@ -387,6 +398,7 @@ export function createContentAccessWithWrite(db: Kysely<Database>): ContentAcces
 					const item = await trxContentRepo.create({
 						type: collection,
 						data: fields,
+						locale,
 					});
 					contentMutated = true;
 
@@ -423,6 +435,7 @@ export function createContentAccessWithWrite(db: Kysely<Database>): ContentAcces
 		},
 
 		async update(collection: string, id: string, data: ContentWriteInput): Promise<ContentItem> {
+			await beforeContentWrite?.();
 			const { fields, seo } = splitSeoFromInput(data);
 			const hasFieldUpdates = Object.keys(fields).length > 0;
 			let contentMutated = false;
@@ -434,13 +447,13 @@ export function createContentAccessWithWrite(db: Kysely<Database>): ContentAcces
 
 					const hasSeo = await assertSeoEnabled(trxSeoRepo, collection, seo);
 
-					// Pass the `data` payload to ContentRepository.update only when
+					// Pass the `data` payload to ContentRepository.updateDraftAware only when
 					// there are field updates — passing an empty object would still
 					// bump updated_at/version, but we want a seo-only call to touch
-					// only the SEO table. ContentRepository.update handles the no-op
-					// path by returning the current row.
+					// only the SEO table. updateDraftAware delegates no-op writes to
+					// ContentRepository.update.
 					const item = hasFieldUpdates
-						? await trxContentRepo.update(collection, id, { data: fields })
+						? await trxContentRepo.updateDraftAware(collection, id, { data: fields })
 						: await (async () => {
 								const existing = await trxContentRepo.findById(collection, id);
 								if (!existing) throw new Error("Content not found");
@@ -483,6 +496,7 @@ export function createContentAccessWithWrite(db: Kysely<Database>): ContentAcces
 		},
 
 		async delete(collection: string, id: string): Promise<boolean> {
+			await beforeContentWrite?.();
 			const contentRepo = new ContentRepository(db);
 			const deleted = await contentRepo.delete(collection, id);
 			if (deleted) {
@@ -990,6 +1004,7 @@ export function createUserAccess(db: Kysely<Database>): UserAccess {
 
 export interface PluginContextFactoryOptions {
 	db: Kysely<Database>;
+	beforeContentWrite?: () => Promise<void>;
 	/**
 	 * Resolver for the database connection, preferred over `db` when present.
 	 * Called per `createContext()` so connection-backed adapters (e.g. Postgres
@@ -1044,6 +1059,7 @@ export interface PluginContextFactoryOptions {
  */
 export class PluginContextFactory {
 	private resolveDb: () => Kysely<Database>;
+	private beforeContentWrite?: () => Promise<void>;
 	private storage?: Storage;
 	private getUploadUrl?: (
 		filename: string,
@@ -1063,6 +1079,7 @@ export class PluginContextFactory {
 	constructor(options: PluginContextFactoryOptions) {
 		const fixedDb = options.db;
 		this.resolveDb = options.getDb ?? (() => fixedDb);
+		this.beforeContentWrite = options.beforeContentWrite;
 		this.storage = options.storage;
 		this.getUploadUrl = options.getUploadUrl;
 		this.site = createSiteInfo(options.siteInfo ?? {});
@@ -1095,7 +1112,7 @@ export class PluginContextFactory {
 		// names ("read:content", "write:content") never appear here.
 		let content: ContentAccess | ContentAccessWithWrite | undefined;
 		if (capabilities.has("content:write")) {
-			content = createContentAccessWithWrite(db);
+			content = createContentAccessWithWrite(db, this.beforeContentWrite);
 		} else if (capabilities.has("content:read")) {
 			content = createContentAccess(db);
 		}

package/src/plugins/index.ts

@@ -73,6 +73,10 @@ export {
 	NoopSandboxRunner,
 	SandboxNotAvailableError,
 	SandboxUnavailableError,
+	createSandboxRouteError,
+	createSandboxRouteErrorEnvelope,
+	getSandboxRouteErrorDetails,
+	getSandboxRouteErrorEnvelope,
 	createNoopSandboxRunner,
 } from "./sandbox/index.js";
 export type {
@@ -85,6 +89,9 @@ export type {
 	ResourceLimits,
 	PluginCodeStorage,
 	SerializedRequest,
+	SandboxRouteErrorCode,
+	SandboxRouteErrorDetails,
+	SandboxRouteErrorEnvelope,
 } from "./sandbox/index.js";
 
 // Types
@@ -115,6 +122,8 @@ export type {
 	UserInfo,
 	UserAccess,
 	ContentItem,
+	ContentCreateOptions,
+	ContentWriteInput,
 	MediaItem,
 	ContentListOptions,
 	MediaListOptions,

package/src/plugins/routes.ts

@@ -8,9 +8,10 @@
  *
  */
 
+import { MediaUsageActivationWriteBlockedError } from "../api/media-usage-write-fence.js";
 import { PluginContextFactory, type PluginContextFactoryOptions } from "./context.js";
 import { extractRequestMeta } from "./request-meta.js";
-import type { ResolvedPlugin, RouteContext, PluginRoute } from "./types.js";
+import type { ResolvedPlugin, RouteContext, PluginRoute, UserInfo } from "./types.js";
 
 /**
  * Body-reading methods on `Request`. EmDash parses the request body once before
@@ -82,6 +83,40 @@ export function buildRouteMeta(route: {
 	return meta;
 }
 
+/**
+ * HTTP methods that carry a request body. Everything else (GET, HEAD, DELETE)
+ * takes its route input from the URL query string.
+ */
+const BODY_METHODS = new Set(["POST", "PUT", "PATCH"]);
+
+/**
+ * Parse a plugin route's input from the request, by method.
+ *
+ * Body methods (POST/PUT/PATCH) parse the JSON body as before. Bodyless
+ * methods (GET/HEAD/DELETE) have no body, so `request.json()` resolves to
+ * undefined and fails schema validation (#2146) — parse the query string into
+ * an object instead. Repeated keys (`?tag=a&tag=b`) become an array so array
+ * schemas work; a single key stays a scalar.
+ */
+export async function parseRouteInput(request: Request): Promise<unknown> {
+	if (BODY_METHODS.has(request.method.toUpperCase())) {
+		try {
+			return await request.json();
+		} catch {
+			// No body or not JSON
+			return undefined;
+		}
+	}
+
+	const params = new URL(request.url).searchParams;
+	const input: Record<string, string | string[]> = {};
+	for (const key of new Set(params.keys())) {
+		const values = params.getAll(key);
+		input[key] = values.length > 1 ? values : values[0];
+	}
+	return input;
+}
+
 /**
  * Result from a route invocation
  */
@@ -96,6 +131,34 @@ export interface RouteResult<T = unknown> {
 	status: number;
 }
 
+/**
+ * Host-side user shape accepted when dispatching a plugin route. Structurally
+ * matches `User` from `@emdash-cms/auth` so hosts can pass `locals.user`
+ * directly without the plugin layer depending on the auth package.
+ */
+export interface RouteCallerInput {
+	id: string;
+	email: string;
+	name: string | null;
+	role: number;
+	createdAt: Date | string;
+}
+
+/**
+ * Convert the host's authenticated user into the read-only `UserInfo` shape
+ * exposed to plugins as `ctx.user`. Strips sensitive/irrelevant fields and
+ * keeps the value structured-clone-safe for sandboxed plugins.
+ */
+export function toRouteCallerInfo(user: RouteCallerInput): UserInfo {
+	return {
+		id: user.id,
+		email: user.email,
+		name: user.name,
+		role: user.role,
+		createdAt: typeof user.createdAt === "string" ? user.createdAt : user.createdAt.toISOString(),
+	};
+}
+
 /**
  * Route invocation options
  */
@@ -104,6 +167,11 @@ export interface InvokeRouteOptions {
 	request: Request;
 	/** Request body (already parsed) */
 	body?: unknown;
+	/**
+	 * Authenticated caller resolved by the host, exposed to the handler as
+	 * `ctx.user`. Undefined for public routes and unbound machine tokens.
+	 */
+	user?: UserInfo;
 }
 
 /**
@@ -167,6 +235,7 @@ export class PluginRouteHandler {
 			// (#1293). Metadata extraction uses the original request (headers only).
 			request: guardConsumedRequestBody(options.request),
 			requestMeta: extractRequestMeta(options.request, this.trustedProxyHeaders),
+			user: options.user,
 		};
 
 		// Execute handler
@@ -178,6 +247,13 @@ export class PluginRouteHandler {
 				status: 200,
 			};
 		} catch (error) {
+			if (error instanceof MediaUsageActivationWriteBlockedError) {
+				return {
+					success: false,
+					error: { code: error.code, message: error.message },
+					status: error.status,
+				};
+			}
 			// Handle known error types
 			if (error instanceof PluginRouteError) {
 				return {

package/src/plugins/sandbox/index.ts

@@ -4,7 +4,13 @@
  */
 
 export { NoopSandboxRunner, SandboxNotAvailableError, createNoopSandboxRunner } from "./noop.js";
-export { SandboxUnavailableError } from "./types.js";
+export {
+	SandboxUnavailableError,
+	createSandboxRouteError,
+	createSandboxRouteErrorEnvelope,
+	getSandboxRouteErrorDetails,
+	getSandboxRouteErrorEnvelope,
+} from "./types.js";
 
 export type {
 	SandboxRunner,
@@ -16,4 +22,7 @@ export type {
 	ResourceLimits,
 	PluginCodeStorage,
 	SerializedRequest,
+	SandboxRouteErrorCode,
+	SandboxRouteErrorDetails,
+	SandboxRouteErrorEnvelope,
 } from "./types.js";

package/src/plugins/sandbox/types.ts

@@ -10,7 +10,7 @@
 import type { Kysely } from "kysely";
 
 import type { Database } from "../../database/types.js";
-import type { PluginManifest, RequestMeta } from "../types.js";
+import type { PluginManifest, RequestMeta, UserInfo } from "../types.js";
 
 /**
  * Resource limits for sandboxed plugins.
@@ -69,6 +69,8 @@ export interface SandboxOptions {
 	storage?: PluginCodeStorage;
 	/** Database for bridge operations */
 	db: Kysely<Database>;
+	/** Called immediately before a sandboxed plugin content mutation. */
+	beforeContentWrite?: () => Promise<void>;
 	/** Default resource limits */
 	limits?: ResourceLimits;
 	/** Site info for plugin context (injected into wrapper at generation time) */
@@ -138,6 +140,81 @@ export interface SerializedRequest {
 	headers: Record<string, string>;
 	/** Normalized request metadata extracted before RPC serialization */
 	meta: RequestMeta;
+	/**
+	 * Authenticated caller for private routes, resolved by the host before
+	 * dispatch. Undefined for public routes and unbound machine tokens.
+	 */
+	user?: UserInfo;
+}
+
+const SANDBOX_ROUTE_ERROR_DEFINITIONS = {
+	MEDIA_USAGE_ACTIVATION_IN_PROGRESS: {
+		message: "Media usage activation is in progress",
+		status: 503,
+	},
+	MEDIA_USAGE_ACTIVATION_CHECK_FAILED: {
+		message: "Unable to verify media usage activation state",
+		status: 503,
+	},
+} as const;
+
+export type SandboxRouteErrorCode = keyof typeof SANDBOX_ROUTE_ERROR_DEFINITIONS;
+
+export interface SandboxRouteErrorDetails {
+	code: SandboxRouteErrorCode;
+	message: string;
+	status: 503;
+}
+
+export interface SandboxRouteErrorEnvelope {
+	__emdashSandboxRouteError: true;
+	error: SandboxRouteErrorDetails;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isSandboxRouteErrorCode(value: unknown): value is SandboxRouteErrorCode {
+	return typeof value === "string" && value in SANDBOX_ROUTE_ERROR_DEFINITIONS;
+}
+
+export function getSandboxRouteErrorDetails(error: unknown): SandboxRouteErrorDetails | null {
+	if (!isRecord(error)) return null;
+
+	const propertyCode = isSandboxRouteErrorCode(error.code) ? error.code : null;
+	const nameCode =
+		error instanceof Error && isSandboxRouteErrorCode(error.name) ? error.name : null;
+	if (propertyCode && nameCode && propertyCode !== nameCode) return null;
+
+	const code = propertyCode ?? nameCode;
+	if (!code || (error.status !== undefined && error.status !== 503)) return null;
+
+	return {
+		code,
+		...SANDBOX_ROUTE_ERROR_DEFINITIONS[code],
+	};
+}
+
+export function createSandboxRouteError(
+	code: SandboxRouteErrorCode,
+): Error & SandboxRouteErrorDetails {
+	const details: SandboxRouteErrorDetails = {
+		code,
+		...SANDBOX_ROUTE_ERROR_DEFINITIONS[code],
+	};
+	return Object.assign(new Error(details.message), details, { name: code });
+}
+
+export function createSandboxRouteErrorEnvelope(error: unknown): SandboxRouteErrorEnvelope | null {
+	const details = getSandboxRouteErrorDetails(error);
+	return details ? { __emdashSandboxRouteError: true, error: details } : null;
+}
+
+export function getSandboxRouteErrorEnvelope(value: unknown): SandboxRouteErrorEnvelope | null {
+	if (!isRecord(value) || value.__emdashSandboxRouteError !== true) return null;
+	const details = getSandboxRouteErrorDetails(value.error);
+	return details ? { __emdashSandboxRouteError: true, error: details } : null;
 }
 
 /**

package/src/plugins/scheduler/node.ts

@@ -29,6 +29,7 @@ export class NodeCronScheduler implements CronScheduler {
 	private timer: ReturnType<typeof setTimeout> | null = null;
 	private running = false;
 	private systemCleanup: SystemCleanupFn | null = null;
+	private mediaUsageMaintenance: SystemCleanupFn | null = null;
 
 	constructor(private executor: CronExecutor) {}
 
@@ -36,6 +37,10 @@ export class NodeCronScheduler implements CronScheduler {
 		this.systemCleanup = fn;
 	}
 
+	setMediaUsageMaintenance(fn: SystemCleanupFn): void {
+		this.mediaUsageMaintenance = fn;
+	}
+
 	start(): void {
 		this.running = true;
 		this.arm();
@@ -112,12 +117,19 @@ export class NodeCronScheduler implements CronScheduler {
 		}
 
 		void Promise.allSettled(tasks)
-			.then((results) => {
+			.then(async (results) => {
 				for (const r of results) {
 					if (r.status === "rejected") {
 						console.error("[cron:node] Tick task failed:", r.reason);
 					}
 				}
+				if (this.mediaUsageMaintenance) {
+					try {
+						await this.mediaUsageMaintenance();
+					} catch (error) {
+						console.error("[cron:node] Media Usage maintenance failed:", error);
+					}
+				}
 				return undefined;
 			})
 			.finally(() => {

package/src/plugins/scheduler/types.ts

@@ -18,6 +18,8 @@ export interface CronScheduler {
 	reschedule(): void;
 	/** Register a system cleanup function to run alongside each tick. */
 	setSystemCleanup(fn: SystemCleanupFn): void;
+	/** Register bounded Media Usage maintenance to run after the general tick settles. */
+	setMediaUsageMaintenance?(fn: SystemCleanupFn): void;
 }
 
 /**

package/src/plugins/storage-indexes.ts

@@ -12,9 +12,9 @@ import { sql } from "kysely";
 import { jsonExtractExpr, isPostgres } from "../database/dialect-helpers.js";
 import type { Database } from "../database/types.js";
 import {
-	validateIdentifier,
 	validateJsonFieldName,
 	validatePluginIdentifier,
+	validateStorageCollectionName,
 } from "../database/validate.js";
 
 /**
@@ -36,8 +36,10 @@ export function generateIndexName(
 /**
  * Generate a Kysely sql expression for creating an expression index.
  *
- * Validates all identifiers before interpolation to prevent SQL injection.
- * Plugin ID and collection values are parameterized in the WHERE clause.
+ * Validates all inputs before interpolation. The collection uses the
+ * permissive manifest-key rules rather than SQL-identifier rules — it is
+ * stored as opaque text and only reaches SQL inside the generated index
+ * name — so kebab-case collections index like any other.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any Kysely instance
 export function generateCreateIndexSql(
@@ -47,9 +49,8 @@ export function generateCreateIndexSql(
 	fields: string[],
 	options?: { unique?: boolean },
 ): RawBuilder<unknown> {
-	// Validate all identifiers
 	validatePluginIdentifier(pluginId, "plugin ID");
-	validateIdentifier(collection, "collection name");
+	validateStorageCollectionName(collection, "collection name");
 	for (const field of fields) {
 		validateJsonFieldName(field, "index field name");
 	}
@@ -68,14 +69,15 @@ export function generateCreateIndexSql(
 		})
 		.join(", ");
 
-	// Partial index filtered to this plugin/collection
-	// SQLite prohibits bound parameters in partial index WHERE clauses,
-	// so we use sql.lit() for literal string values. Both pluginId and
-	// collection are validated above, so this is safe.
+	// Composite non-partial index: the leading (plugin_id, collection) columns
+	// scope it per plugin/collection — including unique-index semantics — and
+	// let it serve the repository's bound-parameter WHERE plus the JSON
+	// expression ORDER BY. A partial index (WHERE plugin_id = 'x' AND
+	// collection = 'y') is never chosen by SQLite under bound parameters
+	// unless ANALYZE has run, and D1 never runs ANALYZE.
 	const createKeyword = options?.unique ? "CREATE UNIQUE INDEX" : "CREATE INDEX";
 	return sql`${sql.raw(createKeyword)} IF NOT EXISTS ${sql.ref(indexName)}
-		ON _plugin_storage(${sql.raw(expressions)})
-		WHERE plugin_id = ${sql.lit(pluginId)} AND collection = ${sql.lit(collection)}
+		ON _plugin_storage(plugin_id, collection, ${sql.raw(expressions)})
 	`;
 }
 
@@ -254,6 +256,43 @@ export async function syncStorageIndexes(
 	};
 }
 
+/**
+ * Materialize the storage indexes a set of plugins declare in their
+ * manifests. Failures are logged per collection and never thrown — a missing
+ * index affects query performance, not correctness, so it must not fail an
+ * install or a scheduler tick.
+ */
+export async function syncDeclaredStorageIndexes(
+	db: Kysely<Database>,
+	plugins: Array<{
+		id: string;
+		storage?: Record<
+			string,
+			{ indexes: Array<string | string[]>; uniqueIndexes?: Array<string | string[]> }
+		>;
+	}>,
+): Promise<void> {
+	for (const plugin of plugins) {
+		for (const [collection, config] of Object.entries(plugin.storage ?? {})) {
+			try {
+				const result = await syncStorageIndexes(db, plugin.id, collection, config.indexes, {
+					uniqueIndexes: config.uniqueIndexes,
+				});
+				for (const failure of result.errors) {
+					console.error(
+						`[plugins] Failed to sync storage index ${failure.index} for ${plugin.id}/${collection}: ${failure.error}`,
+					);
+				}
+			} catch (error) {
+				console.error(
+					`[plugins] Failed to sync storage indexes for ${plugin.id}/${collection}:`,
+					error,
+				);
+			}
+		}
+	}
+}
+
 /**
  * Remove all indexes for a plugin
  */