emdash 0.37.0 → 0.39.0

package/src/plugins/sandbox/types.ts

@@ -7,10 +7,22 @@
  *
  */
 
+import type { PluginUiContext } from "@emdash-cms/blocks/server";
 import type { Kysely } from "kysely";
 
 import type { Database } from "../../database/types.js";
-import type { PluginManifest, RequestMeta, UserInfo } from "../types.js";
+import type { ContentActionCallbacks } from "../context.js";
+import type {
+	ContentCreateOptions,
+	ContentItem,
+	ContentWriteInput,
+	PluginComment,
+	PluginCommentStatus,
+	PluginManifest,
+	RequestMeta,
+	TaxonomyAccessWithWrite,
+	UserInfo,
+} from "../types.js";
 
 /**
  * Resource limits for sandboxed plugins.
@@ -61,6 +73,25 @@ export type SandboxEmailSendCallback = (
 	pluginId: string,
 ) => Promise<void>;
 
+export type SandboxCommentModerateCallback = (
+	pluginId: string,
+	id: string,
+	status: PluginCommentStatus,
+	expectedStatus: PluginCommentStatus,
+) => Promise<PluginComment>;
+
+export type SandboxContentCreateCallback = (
+	pluginId: string,
+	collection: string,
+	data: ContentWriteInput,
+	options?: ContentCreateOptions & {
+		originHook?: "content:beforeSave" | "content:afterSave";
+		sandboxOrigin?: true;
+	},
+) => Promise<ContentItem>;
+
+export type SandboxHttpFetchCallback = typeof fetch;
+
 /**
  * Options for creating a sandbox runner
  */
@@ -71,6 +102,11 @@ export interface SandboxOptions {
 	db: Kysely<Database>;
 	/** Called immediately before a sandboxed plugin content mutation. */
 	beforeContentWrite?: () => Promise<void>;
+	/** Runtime-owned taxonomy mutation surface used by sandbox bridges. */
+	taxonomyWrite?: TaxonomyAccessWithWrite;
+	contentActions?: ContentActionCallbacks;
+	/** Clock used to calculate recurring plugin task schedules. */
+	now?: () => Date;
 	/** Default resource limits */
 	limits?: ResourceLimits;
 	/** Site info for plugin context (injected into wrapper at generation time) */
@@ -82,15 +118,24 @@ export interface SandboxOptions {
 	};
 	/** Email send callback, wired from the EmailPipeline by the runtime */
 	emailSend?: SandboxEmailSendCallback;
+	commentModerate?: SandboxCommentModerateCallback;
+	/** Optional host HTTP transport used by test hosts and custom runtimes. */
+	httpFetch?: SandboxHttpFetchCallback;
 	/**
-	 * Media storage adapter for sandboxed plugin uploads and deletes.
-	 * When provided, plugins with write:media can upload and delete files
-	 * via ctx.media.upload() and ctx.media.delete().
+	 * Media storage adapter for sandboxed plugin byte reads, uploads, and deletes.
+	 * Each operation remains gated by its own media capability.
 	 */
 	mediaStorage?: {
 		upload(options: { key: string; body: Uint8Array; contentType: string }): Promise<unknown>;
+		download(key: string): Promise<{
+			body: ReadableStream<Uint8Array>;
+			contentType: string;
+			size: number;
+		}>;
 		delete(key: string): Promise<unknown>;
 	};
+	/** Worker Loader name suffix. The plugin's logical ID remains unchanged. */
+	isolateKey?: string;
 }
 
 /**
@@ -121,7 +166,12 @@ export interface SandboxedPluginInstance {
 	 * @param request - Serialized request info for context
 	 * @returns Route response data
 	 */
-	invokeRoute(routeName: string, input: unknown, request: SerializedRequest): Promise<unknown>;
+	invokeRoute(
+		routeName: string,
+		input: unknown,
+		request: SerializedRequest,
+		options?: SandboxInvocationOptions,
+	): Promise<unknown>;
 
 	/**
 	 * Terminate the sandboxed plugin.
@@ -130,6 +180,10 @@ export interface SandboxedPluginInstance {
 	terminate(): Promise<void>;
 }
 
+export interface SandboxInvocationOptions {
+	invalidateContentCache?: (tags: string[]) => Promise<void>;
+}
+
 /**
  * Serialized request for RPC transport.
  * Worker Loader can't pass Request objects directly.
@@ -140,6 +194,8 @@ export interface SerializedRequest {
 	headers: Record<string, string>;
 	/** Normalized request metadata extracted before RPC serialization */
 	meta: RequestMeta;
+	/** Host-attested context for a validated Block Kit request. */
+	ui?: PluginUiContext;
 	/**
 	 * Authenticated caller for private routes, resolved by the host before
 	 * dispatch. Undefined for public routes and unbound machine tokens.
@@ -236,6 +292,15 @@ export interface SandboxRunner {
 	 */
 	isHealthy(): boolean;
 
+	/**
+	 * Why the runner cannot run plugins, once isAvailable() or isHealthy()
+	 * has returned false. A lowercase clause without a final period: callers
+	 * append it to their own message after a colon.
+	 *
+	 * Making this required breaks runners implemented outside this repository.
+	 */
+	unavailableReason?(): string;
+
 	/**
 	 * Load a sandboxed plugin from code.
 	 *
@@ -252,6 +317,12 @@ export interface SandboxRunner {
 	 * doesn't exist when the sandbox runner is constructed.
 	 */
 	setEmailSend(callback: SandboxEmailSendCallback | null): void;
+	setCommentModerate?(callback: SandboxCommentModerateCallback | null): void;
+	setContentCreate?(callback: SandboxContentCreateCallback | null): void;
+	setContentActions?(callback: ContentActionCallbacks | null): void;
+
+	/** Wake a long-lived scheduler after a sandboxed plugin changes its tasks. */
+	setCronReschedule?(callback: (() => void) | null): void;
 
 	/**
 	 * Terminate all loaded sandboxed plugins.
@@ -260,6 +331,11 @@ export interface SandboxRunner {
 	terminateAll(): Promise<void>;
 }
 
+export function withUnavailableReason(message: string, runner: SandboxRunner | null): string {
+	const reason = runner?.unavailableReason?.();
+	return reason ? `${message}: ${reason}` : message;
+}
+
 /**
  * Error thrown when the sandbox runtime is unavailable.
  * This happens when the sidecar process has crashed or hasn't started.
@@ -273,11 +349,11 @@ export class SandboxUnavailableError extends Error {
 
 /**
  * Factory function type for creating sandbox runners.
- * Exported by platform adapters (e.g., @emdash-cms/adapter-cloudflare/sandbox).
+ * Exported by platform adapters (e.g., @emdash-cms/cloudflare/sandbox).
  *
  * @example
  * ```typescript
- * // In @emdash-cms/adapter-cloudflare/sandbox.ts
+ * // In @emdash-cms/cloudflare/sandbox
  * export const createSandboxRunner: SandboxRunnerFactory = (options) => {
  *   return new CloudflareSandboxRunner(options);
  * };

package/src/plugins/secret-redactor.ts

@@ -0,0 +1,65 @@
+export interface PluginSecretRedactor {
+	add(key: string, value: string): void;
+	redact<T>(value: T): T;
+}
+
+export function createPluginSecretRedactor(): PluginSecretRedactor {
+	const secretsByKey = new Map<string, [string, string?]>();
+	const secretValues = (): string[] =>
+		[
+			...new Set(
+				[...secretsByKey.values()].flat().filter((value): value is string => value !== undefined),
+			),
+		].toSorted((a, b) => b.length - a.length);
+	const redactString = (value: string): string => {
+		let redacted = value;
+		for (const secret of secretValues()) {
+			redacted = redacted.replaceAll(secret, "[REDACTED]");
+		}
+		return redacted;
+	};
+	const redactValue = (value: unknown, seen: WeakMap<object, unknown>): unknown => {
+		if (typeof value === "string") return redactString(value);
+		if (typeof value !== "object" || value === null) return value;
+		const existing = seen.get(value);
+		if (existing !== undefined) return existing;
+		if (value instanceof Error) {
+			const redacted = new Error(redactString(value.message));
+			redacted.name = value.name;
+			redacted.stack = value.stack ? redactString(value.stack) : undefined;
+			seen.set(value, redacted);
+			return redacted;
+		}
+		if (Array.isArray(value)) {
+			const redacted: unknown[] = [];
+			seen.set(value, redacted);
+			for (const entry of value) redacted.push(redactValue(entry, seen));
+			return redacted;
+		}
+		if (
+			Object.getPrototypeOf(value) === Object.prototype ||
+			Object.getPrototypeOf(value) === null
+		) {
+			const redacted: Record<string, unknown> = {};
+			seen.set(value, redacted);
+			for (const [key, entry] of Object.entries(value)) {
+				redacted[redactString(key)] = redactValue(entry, seen);
+			}
+			return redacted;
+		}
+		return "[NonPlainObject]";
+	};
+
+	return {
+		add(key, value) {
+			if (value.length === 0) return;
+			const current = secretsByKey.get(key)?.[0];
+			if (current === value) return;
+			secretsByKey.set(key, current ? [value, current] : [value]);
+		},
+		redact<T>(value: T): T {
+			// eslint-disable-next-line typescript/no-unsafe-type-assertion -- redaction preserves the logged value's outer API shape
+			return redactValue(value, new WeakMap()) as T;
+		},
+	};
+}

package/src/plugins/settings.ts

@@ -0,0 +1,303 @@
+import { resolvePluginEncryptionKeys, type ParsedEncryptionKey } from "../config/secrets.js";
+import type { OptionsRepository } from "../database/repositories/options.js";
+import { decodeBase64url, encodeBase64url } from "../utils/base64.js";
+import { assertStorageKey } from "./conditional-storage.js";
+export { createPluginSecretRedactor } from "./secret-redactor.js";
+export type { PluginSecretRedactor } from "./secret-redactor.js";
+import type {
+	ConditionalDeleteResult,
+	ConditionalWriteResult,
+	SettingField,
+	SettingsAccess,
+	VersionedValue,
+} from "./types.js";
+
+const ENVELOPE_VERSION = 1;
+const ENVELOPE_MARKER = "plugin-setting";
+const IV_BYTES = 12;
+const KEY_ID_PATTERN = /^[0-9a-f]{8}$/;
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+
+export interface EncryptedPluginSetting {
+	$emdash: "plugin-setting";
+	v: 1;
+	kid: string;
+	iv: string;
+	ciphertext: string;
+}
+
+export class PluginSettingEncryptionError extends Error {
+	override readonly name = "PluginSettingEncryptionError";
+	readonly code:
+		| "PLUGIN_SETTING_ENCRYPTION_KEY_MISSING"
+		| "PLUGIN_SETTING_ENCRYPTION_KEY_UNKNOWN"
+		| "PLUGIN_SETTING_ENCRYPTION_FAILED"
+		| "PLUGIN_SETTING_DECRYPTION_FAILED";
+
+	constructor(code: PluginSettingEncryptionError["code"], message: string) {
+		super(message);
+		this.code = code;
+	}
+}
+
+export function isEncryptedPluginSetting(value: unknown): value is EncryptedPluginSetting {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	return (
+		Object.keys(value).length === 5 &&
+		"$emdash" in value &&
+		value.$emdash === ENVELOPE_MARKER &&
+		"v" in value &&
+		value.v === ENVELOPE_VERSION &&
+		"kid" in value &&
+		typeof value.kid === "string" &&
+		KEY_ID_PATTERN.test(value.kid) &&
+		"iv" in value &&
+		typeof value.iv === "string" &&
+		BASE64URL_PATTERN.test(value.iv) &&
+		"ciphertext" in value &&
+		typeof value.ciphertext === "string" &&
+		BASE64URL_PATTERN.test(value.ciphertext)
+	);
+}
+
+function additionalData(pluginId: string, key: string): Uint8Array {
+	return textEncoder.encode(
+		JSON.stringify(["emdash-plugin-setting", ENVELOPE_VERSION, pluginId, key]),
+	);
+}
+
+function exactBuffer(bytes: Uint8Array): ArrayBuffer {
+	return bytes.slice().buffer;
+}
+
+async function importEncryptionKey(key: ParsedEncryptionKey, usage: KeyUsage): Promise<CryptoKey> {
+	return crypto.subtle.importKey("raw", exactBuffer(key.key), "AES-GCM", false, [usage]);
+}
+
+async function keysOrDefault(
+	keys: ParsedEncryptionKey[] | null | undefined,
+): Promise<ParsedEncryptionKey[] | null> {
+	return keys === undefined ? resolvePluginEncryptionKeys() : keys;
+}
+
+export async function encryptPluginSetting(
+	pluginId: string,
+	key: string,
+	value: string,
+	keys?: ParsedEncryptionKey[] | null,
+): Promise<EncryptedPluginSetting> {
+	const resolved = await keysOrDefault(keys);
+	const primary = resolved?.[0];
+	if (!primary) {
+		throw new PluginSettingEncryptionError(
+			"PLUGIN_SETTING_ENCRYPTION_KEY_MISSING",
+			"Plugin secret settings require EMDASH_ENCRYPTION_KEY",
+		);
+	}
+
+	try {
+		const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+		const cryptoKey = await importEncryptionKey(primary, "encrypt");
+		const ciphertext = await crypto.subtle.encrypt(
+			{
+				name: "AES-GCM",
+				iv: exactBuffer(iv),
+				additionalData: exactBuffer(additionalData(pluginId, key)),
+			},
+			cryptoKey,
+			exactBuffer(textEncoder.encode(value)),
+		);
+		return {
+			$emdash: ENVELOPE_MARKER,
+			v: ENVELOPE_VERSION,
+			kid: primary.kid,
+			iv: encodeBase64url(iv),
+			ciphertext: encodeBase64url(new Uint8Array(ciphertext)),
+		};
+	} catch (error) {
+		if (error instanceof PluginSettingEncryptionError) throw error;
+		throw new PluginSettingEncryptionError(
+			"PLUGIN_SETTING_ENCRYPTION_FAILED",
+			"Plugin secret setting could not be encrypted",
+		);
+	}
+}
+
+export async function decryptPluginSetting(
+	pluginId: string,
+	key: string,
+	envelope: EncryptedPluginSetting,
+	keys?: ParsedEncryptionKey[] | null,
+): Promise<string> {
+	const resolved = await keysOrDefault(keys);
+	if (!resolved?.length) {
+		throw new PluginSettingEncryptionError(
+			"PLUGIN_SETTING_ENCRYPTION_KEY_MISSING",
+			"Plugin secret setting cannot be decrypted because its encryption key is unavailable",
+		);
+	}
+	const matched = resolved.find((candidate) => candidate.kid === envelope.kid);
+	if (!matched) {
+		throw new PluginSettingEncryptionError(
+			"PLUGIN_SETTING_ENCRYPTION_KEY_UNKNOWN",
+			"Plugin secret setting was encrypted with an unavailable key",
+		);
+	}
+
+	try {
+		const iv = decodeBase64url(envelope.iv);
+		const ciphertext = decodeBase64url(envelope.ciphertext);
+		if (iv.byteLength !== IV_BYTES || ciphertext.byteLength < 16)
+			throw new Error("invalid envelope");
+		const cryptoKey = await importEncryptionKey(matched, "decrypt");
+		const plaintext = await crypto.subtle.decrypt(
+			{
+				name: "AES-GCM",
+				iv: exactBuffer(iv),
+				additionalData: exactBuffer(additionalData(pluginId, key)),
+			},
+			cryptoKey,
+			exactBuffer(ciphertext),
+		);
+		return textDecoder.decode(plaintext);
+	} catch {
+		throw new PluginSettingEncryptionError(
+			"PLUGIN_SETTING_DECRYPTION_FAILED",
+			"Plugin secret setting could not be decrypted",
+		);
+	}
+}
+
+function isSecretField(schema: Record<string, SettingField>, key: string): boolean {
+	return schema[key]?.type === "secret";
+}
+
+export async function encodePluginSettingValue(
+	pluginId: string,
+	key: string,
+	value: unknown,
+	schema: Record<string, SettingField>,
+	keys?: ParsedEncryptionKey[] | null,
+	onSecret?: (key: string, value: string) => void,
+): Promise<unknown> {
+	if (!isSecretField(schema, key)) return value;
+	if (typeof value !== "string") {
+		throw new PluginSettingEncryptionError(
+			"PLUGIN_SETTING_ENCRYPTION_FAILED",
+			"Plugin secret settings must be strings",
+		);
+	}
+	onSecret?.(key, value);
+	return encryptPluginSetting(pluginId, key, value, keys);
+}
+
+export async function decodePluginSettingValue<T = unknown>(
+	pluginId: string,
+	key: string,
+	value: unknown,
+	schema: Record<string, SettingField>,
+	keys?: ParsedEncryptionKey[] | null,
+	onSecret?: (key: string, value: string) => void,
+): Promise<T> {
+	if (!isSecretField(schema, key)) {
+		if (isEncryptedPluginSetting(value)) {
+			throw new PluginSettingEncryptionError(
+				"PLUGIN_SETTING_DECRYPTION_FAILED",
+				"Encrypted plugin setting is not declared as a secret",
+			);
+		}
+		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- caller supplies the expected non-secret setting type
+		return value as T;
+	}
+	if (typeof value === "string") {
+		onSecret?.(key, value);
+		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- secret schema guarantees a string and caller supplies its compatible type
+		return value as T;
+	}
+	if (!isEncryptedPluginSetting(value)) {
+		throw new PluginSettingEncryptionError(
+			"PLUGIN_SETTING_DECRYPTION_FAILED",
+			"Plugin secret setting has an invalid encrypted envelope",
+		);
+	}
+	const decrypted = await decryptPluginSetting(pluginId, key, value, keys);
+	onSecret?.(key, decrypted);
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- secret schema guarantees a string and caller supplies its compatible type
+	return decrypted as T;
+}
+
+export function createSettingsAccess(
+	optionsRepo: OptionsRepository,
+	pluginId: string,
+	schema: Record<string, SettingField> = {},
+	keys?: ParsedEncryptionKey[] | null,
+	onSecret?: (key: string, value: string) => void,
+): SettingsAccess {
+	const prefix = `plugin:${pluginId}:settings:`;
+	const optionKey = (key: string) => {
+		assertStorageKey(key);
+		return `${prefix}${key}`;
+	};
+
+	return {
+		async get<T>(key: string): Promise<T | null> {
+			const value = await optionsRepo.get(optionKey(key));
+			return value === null
+				? null
+				: decodePluginSettingValue<T>(pluginId, key, value, schema, keys, onSecret);
+		},
+		async getVersioned<T>(key: string): Promise<VersionedValue<T> | null> {
+			const value = await optionsRepo.getVersioned(optionKey(key));
+			if (!value) return null;
+			return {
+				value: await decodePluginSettingValue<T>(
+					pluginId,
+					key,
+					value.value,
+					schema,
+					keys,
+					onSecret,
+				),
+				revision: value.revision,
+			};
+		},
+		async compareAndSet(
+			key: string,
+			expectedRevision: string | null,
+			value: unknown,
+		): Promise<ConditionalWriteResult> {
+			return optionsRepo.compareAndSet(
+				optionKey(key),
+				expectedRevision,
+				await encodePluginSettingValue(pluginId, key, value, schema, keys, onSecret),
+			);
+		},
+		compareAndDelete(key: string, expectedRevision: string): Promise<ConditionalDeleteResult> {
+			return optionsRepo.compareAndDelete(optionKey(key), expectedRevision);
+		},
+		async set(key: string, value: unknown): Promise<void> {
+			await optionsRepo.set(
+				optionKey(key),
+				await encodePluginSettingValue(pluginId, key, value, schema, keys, onSecret),
+			);
+		},
+		delete(key: string): Promise<boolean> {
+			return optionsRepo.delete(optionKey(key));
+		},
+		async list(keyPrefix = ""): Promise<Array<{ key: string; value: unknown }>> {
+			assertStorageKey(keyPrefix || "_");
+			const values = await optionsRepo.getByPrefix(`${prefix}${keyPrefix}`);
+			const result: Array<{ key: string; value: unknown }> = [];
+			for (const [fullKey, value] of values) {
+				const key = fullKey.slice(prefix.length);
+				result.push({
+					key,
+					value: await decodePluginSettingValue(pluginId, key, value, schema, keys, onSecret),
+				});
+			}
+			return result;
+		},
+	};
+}

package/src/plugins/state.ts

@@ -208,6 +208,32 @@ export class PluginStateRepository {
 		return (await this.get(pluginId))!;
 	}
 
+	async restoreIfVersion(expectedVersion: string, state: PluginState): Promise<boolean> {
+		const result = await this.db
+			.updateTable("_plugin_state")
+			.set({
+				version: state.version,
+				status: state.status,
+				installed_at: state.installedAt.toISOString(),
+				activated_at: state.activatedAt?.toISOString() ?? null,
+				deactivated_at: state.deactivatedAt?.toISOString() ?? null,
+				source: state.source,
+				marketplace_version: state.marketplaceVersion,
+				display_name: state.displayName,
+				description: state.description,
+				registry_publisher_did: state.registryPublisherDid,
+				registry_slug: state.registrySlug,
+				mcp_tools_enabled: state.mcpToolsEnabled ? 1 : 0,
+				mcp_tools_consent: state.mcpToolsConsent,
+			})
+			.where("plugin_id", "=", state.pluginId)
+			.where("version", "=", expectedVersion)
+			.where("source", "=", state.source)
+			.executeTakeFirst();
+
+		return (result.numUpdatedRows ?? 0n) > 0n;
+	}
+
 	/**
 	 * Enable a plugin
 	 */

package/src/plugins/storage-query.ts

@@ -25,6 +25,38 @@ export class StorageQueryError extends Error {
 	}
 }
 
+/**
+ * Error thrown when a guarded `updateIf` loses a concurrent race by aborting
+ * rather than resolving to `{ applied: false }`.
+ *
+ * `updateIf`'s `{ applied: false }` contract (row absent OR guard failed)
+ * assumes READ COMMITTED — the default. There, a losing concurrent writer
+ * re-evaluates the guard against the winner's freshly committed row and
+ * cleanly resolves to `{ applied: false }`. Two aborts escape that contract:
+ *
+ * - `40001` (serialization_failure), only above READ COMMITTED, where the
+ *   loser cannot re-read against a newer snapshot.
+ * - `40P01` (deadlock_detected), at any isolation level, when transactions
+ *   take row locks in opposite order.
+ *
+ * This error surfaces either abort so the caller can retry the write.
+ *
+ * The no-oversell SAFETY invariant holds either way: a losing writer NEVER
+ * applies its update — it either sees `{ applied: false }` or throws here.
+ */
+export class StorageSerializationError extends Error {
+	readonly code = "STORAGE_SERIALIZATION_FAILURE";
+	readonly retryable = true;
+	/** The Postgres SQLSTATE that triggered this error (`40001` / `40P01`). */
+	readonly sqlState?: string;
+
+	constructor(message: string, options?: { cause?: unknown; sqlState?: string }) {
+		super(message, { cause: options?.cause });
+		this.name = "StorageSerializationError";
+		this.sqlState = options?.sqlState;
+	}
+}
+
 /**
  * Check if a value is a range filter
  */
@@ -213,6 +245,17 @@ export function buildCondition(
 		if (value.lt !== undefined) pushBound("<", value.lt);
 		if (value.lte !== undefined) pushBound("<=", value.lte);
 
+		// A filter with no defined bound contributes no SQL. Returning it would
+		// widen the caller's predicate to "match everything" — survivable in a
+		// read, but it strips the guard off a conditional write.
+		if (conditions.length === 0) {
+			throw new StorageQueryError(
+				`Range filter for field '${field}' has no defined bound`,
+				field,
+				"Provide at least one of gt, gte, lt, or lte, or omit the field.",
+			);
+		}
+
 		return {
 			sql: conditions.join(" AND "),
 			params,
@@ -238,6 +281,8 @@ export function buildWhereClause(
 
 	for (const [field, value] of Object.entries(where)) {
 		const condition = buildCondition(db, field, value);
+		// An empty slot in the join would emit `<cond> AND ` and fail to parse.
+		if (!condition.sql) continue;
 		conditions.push(condition.sql);
 		params.push(...condition.params);
 	}