emdash 0.33.0 → 0.35.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
@@ -130,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
  */
@@ -138,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;
 }
 
 /**
@@ -201,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
@@ -212,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/types.ts

@@ -42,8 +42,17 @@ import type { z } from "astro/zod";
 // Core Types
 // =============================================================================
 
+import type { ContentFieldFilters } from "../content-list-query.js";
 import type { FieldType } from "../schema/types.js";
 
+export type {
+	ContentFieldFilterScalar,
+	ContentFieldFilterValue,
+	ContentFieldFilters,
+	ContentFieldInFilter,
+	ContentFieldRangeFilter,
+} from "../content-list-query.js";
+
 export {
 	CAPABILITY_RENAMES,
 	capabilitiesToDeclaredAccess,
@@ -227,6 +236,8 @@ export interface ContentListWhere {
 	status?: string;
 	/** Exact match on `locale` (e.g. `"en"`, `"fr-CA"`). */
 	locale?: string;
+	/** AND-combined filters over custom fields explicitly marked as indexed. */
+	fieldFilters?: ContentFieldFilters;
 }
 
 /**
@@ -251,6 +262,12 @@ export type ContentWriteInput = Record<string, unknown> & {
 	seo?: ContentItemSeoInput;
 };
 
+/** Options accepted by `content.create`. */
+export interface ContentCreateOptions {
+	/** Locale for the new content row. Defaults to the configured site locale, then `en`. */
+	locale?: string;
+}
+
 /**
  * Taxonomy definition returned from the taxonomy API (e.g. "category", "tag").
  */
@@ -299,7 +316,11 @@ export interface ContentAccess {
 	list(collection: string, options?: ContentListOptions): Promise<PaginatedResult<ContentItem>>;
 
 	// Write operations (requires write:content) - optional on interface
-	create?(collection: string, data: ContentWriteInput): Promise<ContentItem>;
+	create?(
+		collection: string,
+		data: ContentWriteInput,
+		options?: ContentCreateOptions,
+	): Promise<ContentItem>;
 	update?(collection: string, id: string, data: ContentWriteInput): Promise<ContentItem>;
 	delete?(collection: string, id: string): Promise<boolean>;
 }
@@ -325,7 +346,11 @@ export interface TaxonomyAccess {
  * Full content access with write operations
  */
 export interface ContentAccessWithWrite extends ContentAccess {
-	create(collection: string, data: ContentWriteInput): Promise<ContentItem>;
+	create(
+		collection: string,
+		data: ContentWriteInput,
+		options?: ContentCreateOptions,
+	): Promise<ContentItem>;
 	update(collection: string, id: string, data: ContentWriteInput): Promise<ContentItem>;
 	delete(collection: string, id: string): Promise<boolean>;
 }
@@ -1175,6 +1200,18 @@ export interface RouteContext<TInput = unknown> extends PluginContext {
 	request: Request;
 	/** Normalized request metadata (IP, user agent, geo) */
 	requestMeta: RequestMeta;
+	/**
+	 * Authenticated caller, if the route is private. The host has already
+	 * authenticated and authorized this user before dispatch, so the value
+	 * is trustworthy — unlike a user id read from the request body.
+	 *
+	 * `undefined` for public routes (which skip auth entirely) and for
+	 * token-authed requests where no user is bound to the token.
+	 *
+	 * Not gated by the `users:read` capability: this is the caller's own
+	 * identity for the current request, not a user directory lookup.
+	 */
+	user?: UserInfo;
 }
 
 /**