emdash 0.29.0 → 0.31.0

package/src/api/errors.ts

@@ -70,6 +70,7 @@ export const ErrorCode = {
 	ORPHAN_REGISTER_ERROR: "ORPHAN_REGISTER_ERROR",
 	COLLECTION_EXISTS: "COLLECTION_EXISTS",
 	COLLECTION_NOT_FOUND: "COLLECTION_NOT_FOUND",
+	COLLECTION_SCHEMA_MISMATCH: "COLLECTION_SCHEMA_MISMATCH",
 	TABLE_NOT_FOUND: "TABLE_NOT_FOUND",
 	FIELD_EXISTS: "FIELD_EXISTS",
 	FIELD_TYPE_COLUMN_CHANGE: "FIELD_TYPE_COLUMN_CHANGE",
@@ -85,6 +86,7 @@ export const ErrorCode = {
 	MEDIA_CREATE_ERROR: "MEDIA_CREATE_ERROR",
 	MEDIA_UPDATE_ERROR: "MEDIA_UPDATE_ERROR",
 	MEDIA_DELETE_ERROR: "MEDIA_DELETE_ERROR",
+	MEDIA_USAGE_READ_ERROR: "MEDIA_USAGE_READ_ERROR",
 	MEDIA_USAGE_REPAIR_ERROR: "MEDIA_USAGE_REPAIR_ERROR",
 	NO_STORAGE: "NO_STORAGE",
 	NO_FILE: "NO_FILE",
@@ -189,6 +191,8 @@ export const ErrorCode = {
 	PLUGIN_ENABLE_ERROR: "PLUGIN_ENABLE_ERROR",
 	PLUGIN_DISABLE_ERROR: "PLUGIN_DISABLE_ERROR",
 	PLUGIN_ID_CONFLICT: "PLUGIN_ID_CONFLICT",
+	PLUGIN_SETTINGS_READ_ERROR: "PLUGIN_SETTINGS_READ_ERROR",
+	PLUGIN_SETTINGS_UPDATE_ERROR: "PLUGIN_SETTINGS_UPDATE_ERROR",
 	MARKETPLACE_NOT_CONFIGURED: "MARKETPLACE_NOT_CONFIGURED",
 	MARKETPLACE_UNAVAILABLE: "MARKETPLACE_UNAVAILABLE",
 	MARKETPLACE_ERROR: "MARKETPLACE_ERROR",
@@ -303,6 +307,15 @@ export const ErrorCode = {
 	EMAIL_SETTINGS_READ_ERROR: "EMAIL_SETTINGS_READ_ERROR",
 	EMAIL_TEST_ERROR: "EMAIL_TEST_ERROR",
 
+	// Backups
+	BACKUP_SETTINGS_READ_ERROR: "BACKUP_SETTINGS_READ_ERROR",
+	BACKUP_SETTINGS_ERROR: "BACKUP_SETTINGS_ERROR",
+	BACKUP_EXPORT_ERROR: "BACKUP_EXPORT_ERROR",
+	BACKUP_LIST_ERROR: "BACKUP_LIST_ERROR",
+	BACKUP_CREATE_ERROR: "BACKUP_CREATE_ERROR",
+	BACKUP_DELETE_ERROR: "BACKUP_DELETE_ERROR",
+	BACKUP_DOWNLOAD_ERROR: "BACKUP_DOWNLOAD_ERROR",
+
 	// Search
 	SEARCH_ERROR: "SEARCH_ERROR",
 	STATS_ERROR: "STATS_ERROR",
@@ -457,6 +470,7 @@ export function mapErrorStatus(code: string | undefined): number {
 		case ErrorCode.NO_DB:
 		case ErrorCode.STORAGE_NOT_CONFIGURED:
 		case ErrorCode.EMAIL_NOT_CONFIGURED:
+		case ErrorCode.COLLECTION_SCHEMA_MISMATCH:
 			return 500;
 
 		// 501 Not Implemented

package/src/api/handlers/backup.ts

@@ -0,0 +1,312 @@
+/**
+ * Backup handlers — portable content backups, on demand and scheduled.
+ *
+ * A backup is the snapshot format (see `snapshot.ts`) wrapped in a small
+ * envelope: all content (including drafts, scheduled, and trashed entries),
+ * schema definitions, taxonomies, menus, widgets, revisions, media metadata,
+ * and site settings.
+ *
+ * Deliberately NOT included:
+ * - Users, sessions, credentials, API/OAuth tokens (auth data is neither
+ *   portable nor safe in a user-downloadable file)
+ * - Secrets (`emdash:preview_secret`, plugin config, passkey challenges)
+ * - Media binaries (metadata only — the files live in the same bucket the
+ *   scheduled archives are written to)
+ *
+ * For full point-in-time database recovery on Cloudflare, D1 Time Travel
+ * covers the last 30 days out of the box; these backups complement it with
+ * user-holdable, longer-lived archives.
+ */
+
+import type { Kysely } from "kysely";
+
+import { OptionsRepository } from "../../database/repositories/options.js";
+import type { Database } from "../../database/types.js";
+import type { Storage } from "../../storage/types.js";
+import { VERSION } from "../../version.js";
+import { ErrorCode } from "../errors.js";
+import type { ApiResult } from "../types.js";
+import { generateSnapshot } from "./snapshot.js";
+
+// ── Constants ───────────────────────────────────────────────────
+
+/** Storage key prefix for scheduled/manual archives. */
+export const BACKUP_STORAGE_PREFIX = "backups/";
+
+/**
+ * Filename prefix within the backups/ folder. Included in the list() prefix
+ * so LocalStorage (which matches directory + filename prefix, not flat keys
+ * like S3/R2) finds the archives too.
+ */
+const BACKUP_FILE_PREFIX = "emdash-backup-";
+
+/** Options key holding the scheduled-backup settings. */
+export const BACKUP_SETTINGS_KEY = "emdash:backups";
+
+/** Options key holding the ISO timestamp of the last scheduled run. */
+const BACKUP_LAST_RUN_KEY = "emdash:backups_last_run";
+
+/** Minimum interval between scheduled backups (23h — daily with cron jitter). */
+const SCHEDULED_BACKUP_INTERVAL_MS = 23 * 60 * 60 * 1000;
+
+/** Retention bounds for stored archives. */
+export const BACKUP_RETENTION_MIN = 1;
+export const BACKUP_RETENTION_MAX = 30;
+const BACKUP_RETENTION_DEFAULT = 7;
+
+/**
+ * Options-table key prefixes included in backups. Site settings plus the
+ * site-identity keys (`emdash:site_title`, `emdash:site_tagline`,
+ * `emdash:site_url`). Never widen this to a prefix that can match secrets
+ * (`emdash:preview_secret`, `plugin:`, `emdash:passkey_pending:`).
+ */
+const BACKUP_OPTION_PREFIXES = ["site:", "emdash:site_", "emdash:locale"];
+
+/**
+ * Archive filename shape. Strict allowlist — the download/delete routes
+ * interpolate this into a storage key, so it must never contain `/` or `..`.
+ * The random suffix makes names unguessable (defense in depth on top of the
+ * media route's backups/ deny) and avoids same-second collisions.
+ */
+const ARCHIVE_NAME_PATTERN =
+	/^emdash-backup-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-[0-9a-f]{8}\.json$/;
+
+export function isValidArchiveName(name: string): boolean {
+	return ARCHIVE_NAME_PATTERN.test(name);
+}
+
+// ── Types ───────────────────────────────────────────────────────
+
+export interface BackupSettings {
+	/** Whether daily scheduled backups to storage are enabled. */
+	enabled: boolean;
+	/** How many archives to keep in storage (oldest pruned first). */
+	retention: number;
+}
+
+export interface BackupArchive {
+	/** Filename within the backups/ prefix (no path separators). */
+	name: string;
+	/** Size in bytes. */
+	size: number;
+	/** Last-modified timestamp (ISO). */
+	lastModified: string;
+}
+
+const DEFAULT_SETTINGS: BackupSettings = {
+	enabled: false,
+	retention: BACKUP_RETENTION_DEFAULT,
+};
+
+function clampRetention(value: number): number {
+	if (!Number.isFinite(value)) return BACKUP_RETENTION_DEFAULT;
+	return Math.min(BACKUP_RETENTION_MAX, Math.max(BACKUP_RETENTION_MIN, Math.trunc(value)));
+}
+
+// ── Export ──────────────────────────────────────────────────────
+
+/**
+ * Generate a full content backup as a JSON string.
+ *
+ * ponytail: the whole backup is materialized in memory. Fine for the sites
+ * EmDash targets today; truly huge databases should use `wrangler d1 export`
+ * (documented on the backups docs page). Upgrade path: stream table-by-table.
+ */
+export async function generateBackupJson(db: Kysely<Database>): Promise<string> {
+	const snapshot = await generateSnapshot(db, {
+		includeDrafts: true,
+		includeTrashed: true,
+		optionPrefixes: BACKUP_OPTION_PREFIXES,
+	});
+
+	return JSON.stringify({
+		format: "emdash-backup",
+		formatVersion: 1,
+		emdashVersion: VERSION,
+		generatedAt: snapshot.generatedAt,
+		schema: snapshot.schema,
+		tables: snapshot.tables,
+	});
+}
+
+/** Derive the archive filename for a given date (plus a random suffix). */
+export function archiveNameForDate(date: Date): string {
+	// 2026-07-09T08:45:12.345Z → emdash-backup-2026-07-09T08-45-12-1a2b3c4d.json
+	const stamp = date.toISOString().slice(0, 19).replaceAll(":", "-");
+	const suffix = crypto.randomUUID().replaceAll("-", "").slice(0, 8);
+	return `emdash-backup-${stamp}-${suffix}.json`;
+}
+
+// ── Settings ────────────────────────────────────────────────────
+
+export async function getBackupSettings(db: Kysely<Database>): Promise<BackupSettings> {
+	const options = new OptionsRepository(db);
+	const stored = await options.get<Partial<BackupSettings>>(BACKUP_SETTINGS_KEY);
+	if (!stored) return { ...DEFAULT_SETTINGS };
+	return {
+		enabled: stored.enabled === true,
+		retention: clampRetention(stored.retention ?? BACKUP_RETENTION_DEFAULT),
+	};
+}
+
+export async function updateBackupSettings(
+	db: Kysely<Database>,
+	input: { enabled: boolean; retention: number },
+): Promise<ApiResult<BackupSettings>> {
+	try {
+		const settings: BackupSettings = {
+			enabled: input.enabled,
+			retention: clampRetention(input.retention),
+		};
+		const options = new OptionsRepository(db);
+		await options.set(BACKUP_SETTINGS_KEY, settings);
+		return { success: true, data: settings };
+	} catch (error) {
+		console.error("[backup] Failed to update settings:", error);
+		return {
+			success: false,
+			error: { code: ErrorCode.BACKUP_SETTINGS_ERROR, message: "Failed to update backup settings" },
+		};
+	}
+}
+
+// ── Archives in storage ─────────────────────────────────────────
+
+/**
+ * List stored archives, newest first.
+ *
+ * ponytail: single unpaginated list. The retention cap (max 30) bounds the
+ * archive count, so one page always suffices.
+ */
+export async function listBackupArchives(storage: Storage): Promise<ApiResult<BackupArchive[]>> {
+	try {
+		const result = await storage.list({
+			prefix: `${BACKUP_STORAGE_PREFIX}${BACKUP_FILE_PREFIX}`,
+			limit: 100,
+		});
+		const archives = result.files
+			.map((file) => ({
+				name: file.key.slice(BACKUP_STORAGE_PREFIX.length),
+				size: file.size,
+				lastModified: file.lastModified.toISOString(),
+			}))
+			.filter((archive) => isValidArchiveName(archive.name))
+			.toSorted((a, b) => (a.name < b.name ? 1 : -1));
+		return { success: true, data: archives };
+	} catch (error) {
+		console.error("[backup] Failed to list archives:", error);
+		return {
+			success: false,
+			error: { code: ErrorCode.BACKUP_LIST_ERROR, message: "Failed to list backup archives" },
+		};
+	}
+}
+
+/**
+ * Create a backup and store it as an archive, then prune old archives
+ * beyond `retention`.
+ */
+export async function runBackupToStorage(
+	db: Kysely<Database>,
+	storage: Storage,
+	retention: number,
+): Promise<ApiResult<BackupArchive>> {
+	try {
+		const json = await generateBackupJson(db);
+		const name = archiveNameForDate(new Date());
+		const body = new TextEncoder().encode(json);
+
+		await storage.upload({
+			key: `${BACKUP_STORAGE_PREFIX}${name}`,
+			body,
+			contentType: "application/json",
+		});
+
+		await pruneArchives(storage, clampRetention(retention));
+
+		return {
+			success: true,
+			data: { name, size: body.byteLength, lastModified: new Date().toISOString() },
+		};
+	} catch (error) {
+		console.error("[backup] Failed to create archive:", error);
+		return {
+			success: false,
+			error: { code: ErrorCode.BACKUP_CREATE_ERROR, message: "Failed to create backup archive" },
+		};
+	}
+}
+
+/** Delete archives beyond the newest `keep`. Failures are logged, not fatal. */
+async function pruneArchives(storage: Storage, keep: number): Promise<void> {
+	const listed = await listBackupArchives(storage);
+	if (!listed.success) return;
+
+	for (const archive of listed.data.slice(keep)) {
+		try {
+			await storage.delete(`${BACKUP_STORAGE_PREFIX}${archive.name}`);
+		} catch (error) {
+			console.error(`[backup] Failed to prune archive ${archive.name}:`, error);
+		}
+	}
+}
+
+export async function deleteBackupArchive(
+	storage: Storage,
+	name: string,
+): Promise<ApiResult<{ deleted: true }>> {
+	if (!isValidArchiveName(name)) {
+		return {
+			success: false,
+			error: { code: ErrorCode.VALIDATION_ERROR, message: "Invalid archive name" },
+		};
+	}
+	try {
+		await storage.delete(`${BACKUP_STORAGE_PREFIX}${name}`);
+		return { success: true, data: { deleted: true } };
+	} catch (error) {
+		console.error(`[backup] Failed to delete archive ${name}:`, error);
+		return {
+			success: false,
+			error: { code: ErrorCode.BACKUP_DELETE_ERROR, message: "Failed to delete backup archive" },
+		};
+	}
+}
+
+// ── Scheduled runs ──────────────────────────────────────────────
+
+/**
+ * Run a scheduled backup if enabled and due. Called from the maintenance
+ * tick alongside scheduled publishing and system cleanup — never from a
+ * request. Never throws.
+ *
+ * ponytail: last-run bookkeeping is a plain read-then-write, so two isolates
+ * ticking simultaneously could both back up. Worst case is a duplicate
+ * archive that retention prunes; not worth a lock.
+ */
+export async function maybeRunScheduledBackup(
+	db: Kysely<Database>,
+	storage: Storage | undefined,
+): Promise<void> {
+	try {
+		if (!storage) return;
+
+		const settings = await getBackupSettings(db);
+		if (!settings.enabled) return;
+
+		const options = new OptionsRepository(db);
+		const lastRun = await options.get<string>(BACKUP_LAST_RUN_KEY);
+		if (lastRun) {
+			const elapsed = Date.now() - Date.parse(lastRun);
+			if (Number.isFinite(elapsed) && elapsed < SCHEDULED_BACKUP_INTERVAL_MS) return;
+		}
+
+		const result = await runBackupToStorage(db, storage, settings.retention);
+		if (result.success) {
+			await options.set(BACKUP_LAST_RUN_KEY, new Date().toISOString());
+			console.log(`[backup] Scheduled backup stored: ${result.data.name}`);
+		}
+	} catch (error) {
+		console.error("[backup] Scheduled backup failed:", error);
+	}
+}

package/src/api/handlers/bylines.ts

@@ -7,7 +7,7 @@ import {
 } from "../../database/repositories/byline.js";
 import { EmDashValidationError, type BylineSummary } from "../../database/repositories/types.js";
 import type { Database } from "../../database/types.js";
-import { getI18nConfig } from "../../i18n/config.js";
+import { getI18nConfig, resolveConfiguredLocale } from "../../i18n/config.js";
 import type { ApiResult } from "../types.js";
 
 // `undefined → null` so a missing field in the create payload matches the
@@ -138,7 +138,8 @@ export async function handleBylineCreate(
 			};
 		}
 
-		const localeErr = rejectUnknownLocale(input.locale);
+		const locale = input.locale ? resolveConfiguredLocale(input.locale) : undefined;
+		const localeErr = rejectUnknownLocale(locale);
 		if (localeErr) return localeErr;
 
 		const repo = new BylineRepository(db);
@@ -160,7 +161,7 @@ export async function handleBylineCreate(
 			sourceGroup = source.translationGroup ?? source.id;
 		}
 
-		const effectiveLocale = input.locale ?? getI18nConfig()?.defaultLocale ?? "en";
+		const effectiveLocale = locale ?? getI18nConfig()?.defaultLocale ?? "en";
 
 		// Translation-group guard: the row-per-locale model (PR #916)
 		// allows exactly one row per (translation_group, locale). Reject
@@ -216,7 +217,7 @@ export async function handleBylineCreate(
 			};
 		}
 
-		const byline = await repo.create(input);
+		const byline = await repo.create({ ...input, locale: effectiveLocale });
 		return { success: true, data: byline };
 	} catch (error) {
 		// Mirror handleBylineUpdate: surface customFields validation

package/src/api/handlers/content.ts

@@ -30,11 +30,11 @@ import { UserRepository } from "../../database/repositories/user.js";
 import { withTransaction } from "../../database/transaction.js";
 import type { Database } from "../../database/types.js";
 import { validateIdentifier } from "../../database/validate.js";
-import { getI18nConfig, isI18nEnabled } from "../../i18n/config.js";
+import { getI18nConfig, isI18nEnabled, resolveConfiguredLocale } from "../../i18n/config.js";
 import { invalidateRedirectCache } from "../../redirects/cache.js";
 import { FTSManager } from "../../search/fts-manager.js";
 import { invalidateTermCache } from "../../taxonomies/index.js";
-import { isMissingTableError } from "../../utils/db-errors.js";
+import { isMissingColumnError, isMissingTableError } from "../../utils/db-errors.js";
 import { encodeRev, validateRev } from "../rev.js";
 import type { ApiResult, ContentListResponse, ContentResponse } from "../types.js";
 import { validateMediaFields } from "./validate-media-fields.js";
@@ -269,7 +269,11 @@ async function resolveId(
 	identifier: string,
 	locale?: string,
 ): Promise<string | null> {
-	const item = await repo.findByIdOrSlug(collection, identifier, locale);
+	const item = await repo.findByIdOrSlug(
+		collection,
+		identifier,
+		locale ? resolveConfiguredLocale(locale) : undefined,
+	);
 	return item?.id ?? null;
 }
 
@@ -283,7 +287,11 @@ async function resolveIdIncludingTrashed(
 	identifier: string,
 	locale?: string,
 ): Promise<string | null> {
-	const item = await repo.findByIdOrSlugIncludingTrashed(collection, identifier, locale);
+	const item = await repo.findByIdOrSlugIncludingTrashed(
+		collection,
+		identifier,
+		locale ? resolveConfiguredLocale(locale) : undefined,
+	);
 	return item?.id ?? null;
 }
 
@@ -427,7 +435,7 @@ export async function handleContentList(
 		const repo = new ContentRepository(db);
 		const where: FindManyOptions["where"] = {};
 		if (params.status) where.status = params.status;
-		if (params.locale) where.locale = params.locale;
+		if (params.locale) where.locale = resolveConfiguredLocale(params.locale);
 		if (params.authorId) where.authorId = params.authorId;
 
 		// A date range requires a target column; ignore stray from/to without
@@ -485,6 +493,15 @@ export async function handleContentList(
 				},
 			};
 		}
+		if (isMissingColumnError(error, "deleted_at")) {
+			return {
+				success: false,
+				error: {
+					code: "COLLECTION_SCHEMA_MISMATCH",
+					message: `Collection '${collection}' backing table is missing the 'deleted_at' column`,
+				},
+			};
+		}
 		if (error instanceof EmDashValidationError) {
 			// e.g. invalid orderBy field
 			return {
@@ -570,7 +587,11 @@ export async function handleContentGet(
 ): Promise<ApiResult<ContentResponse>> {
 	try {
 		const repo = new ContentRepository(db);
-		const item = await repo.findByIdOrSlug(collection, id, locale);
+		const item = await repo.findByIdOrSlug(
+			collection,
+			id,
+			locale ? resolveConfiguredLocale(locale) : undefined,
+		);
 
 		if (!item) {
 			return {
@@ -615,7 +636,11 @@ export async function handleContentGetIncludingTrashed(
 ): Promise<ApiResult<ContentResponse>> {
 	try {
 		const repo = new ContentRepository(db);
-		const item = await repo.findByIdOrSlugIncludingTrashed(collection, id, locale);
+		const item = await repo.findByIdOrSlugIncludingTrashed(
+			collection,
+			id,
+			locale ? resolveConfiguredLocale(locale) : undefined,
+		);
 
 		if (!item) {
 			return {
@@ -697,7 +722,9 @@ export async function handleContentCreate(
 			// Default to the configured site locale rather than the repo's
 			// hard-coded "en" — otherwise non-English default-locale sites
 			// silently create entries in a locale the editor never chose.
-			const effectiveLocale = body.locale ?? getI18nConfig()?.defaultLocale;
+			const effectiveLocale = body.locale
+				? resolveConfiguredLocale(body.locale)
+				: getI18nConfig()?.defaultLocale;
 
 			let slug: string | null | undefined = body.slug;
 			if (!slug) {
@@ -1487,14 +1514,39 @@ export async function handleContentPublish(
 			};
 		}
 		if (error instanceof EmDashValidationError) {
+			// The staged-slug pre-check tags its error so it maps to the same
+			// 409 SLUG_CONFLICT as direct slug edits in create/update.
+			const details: unknown = error.details;
+			const isSlugConflict =
+				typeof details === "object" &&
+				details !== null &&
+				"code" in details &&
+				details.code === "SLUG_CONFLICT";
 			return {
 				success: false,
 				error: {
-					code: "VALIDATION_ERROR",
+					code: isSlugConflict ? "SLUG_CONFLICT" : "VALIDATION_ERROR",
 					message: error.message,
 				},
 			};
 		}
+		// Backstop for the pre-check inside repo.publish(): a concurrent write
+		// can still take the slug between the check and the UPDATE, in which
+		// case the `(slug, locale)` unique constraint fires. Same fingerprint
+		// mapping as create/update — never a raw SQLite error to the client.
+		const message = error instanceof Error ? error.message.toLowerCase() : "";
+		if (
+			(message.includes("unique constraint failed") || message.includes("duplicate key")) &&
+			message.includes("slug")
+		) {
+			return {
+				success: false,
+				error: {
+					code: "SLUG_CONFLICT",
+					message: `The staged slug is already used by another entry in collection '${collection}'`,
+				},
+			};
+		}
 		console.error("Content publish error:", error);
 		return {
 			success: false,

package/src/api/handlers/device-flow.ts

@@ -17,8 +17,8 @@ import type { Kysely } from "kysely";
 import {
 	generatePrefixedToken,
 	hashApiToken,
+	isValidScope,
 	TOKEN_PREFIXES,
-	VALID_SCOPES,
 } from "../../auth/api-tokens.js";
 import { withTransaction } from "../../database/transaction.js";
 import type { Database } from "../../database/types.js";
@@ -112,8 +112,7 @@ function normalizeScopes(requested?: string[]): string[] {
 	if (!requested || requested.length === 0) {
 		return [...DEFAULT_SCOPES];
 	}
-	const validSet = new Set<string>(VALID_SCOPES);
-	return requested.filter((s) => validSet.has(s));
+	return requested.filter(isValidScope);
 }
 
 // ---------------------------------------------------------------------------

package/src/api/handlers/index.ts

@@ -62,9 +62,19 @@ export {
 } from "./media.js";
 
 export {
+	aggregateMediaUsageCoverageStatus,
+	handleMediaUsageDetails,
+	handleMediaUsageSummaries,
 	handleMediaUsageRepair,
 	toMediaUsageRepairResponse,
+	type MediaUsageCoverage,
+	type MediaUsageCoverageStatus,
+	type MediaUsageDetailsResponse,
+	type MediaUsageEntryDetail,
+	type MediaUsageOccurrenceDetail,
 	type MediaUsageRepairResponse,
+	type MediaUsageSourceDetail,
+	type MediaUsageSummary,
 } from "./media-usage.js";
 
 // Schema handlers
@@ -109,6 +119,12 @@ export {
 	type PluginListResponse,
 	type PluginResponse,
 } from "./plugins.js";
+export {
+	handlePluginSettingsGet,
+	handlePluginSettingsUpdate,
+	getPluginSettingsSchema,
+	type PluginSettingsResponse,
+} from "./plugin-settings.js";
 
 // Menu handlers
 export {

package/src/api/handlers/marketplace.ts

@@ -328,6 +328,7 @@ export async function handleMarketplaceInstall(
 		 * Skip the SANDBOX_NOT_AVAILABLE gate so the install can proceed.
 		 */
 		sandboxBypassed?: boolean;
+		confirmMcpTools?: boolean;
 	},
 ): Promise<ApiResult<MarketplaceInstallResult>> {
 	const client = getClient(marketplaceUrl, opts?.siteOrigin);
@@ -448,6 +449,21 @@ export async function handleMarketplaceInstall(
 		const bundleIdentityError = validateBundleIdentity(bundle, pluginId, version);
 		if (bundleIdentityError) return bundleIdentityError;
 
+		if ((bundle.manifest.mcp?.tools.length ?? 0) > 0 && !opts?.confirmMcpTools) {
+			return {
+				success: false,
+				error: {
+					code: "MCP_TOOL_CONSENT_REQUIRED",
+					message: "Plugin MCP tools require explicit consent",
+					details: {
+						mcpTools: bundle.manifest.mcp?.tools.map(
+							({ inputSchema: _, outputSchema: __, ...tool }) => tool,
+						),
+					},
+				},
+			};
+		}
+
 		// Store bundle in site-local R2
 		await storeBundleInR2(storage, pluginId, version, bundle);
 
@@ -534,6 +550,7 @@ export async function handleMarketplaceUpdate(
 		version?: string;
 		confirmCapabilityChanges?: boolean;
 		confirmRouteVisibilityChanges?: boolean;
+		confirmMcpTools?: boolean;
 		/**
 		 * When true, sandbox: false bypass mode is active. The sandbox runner
 		 * is the noop runner (isAvailable() === false) but the runtime will
@@ -664,6 +681,25 @@ export async function handleMarketplaceUpdate(
 			};
 		}
 
+		const oldMcpTools = [...(oldBundle?.manifest.mcp?.tools ?? [])].toSorted((a, b) =>
+			a.name.localeCompare(b.name),
+		);
+		const newMcpTools = [...(bundle.manifest.mcp?.tools ?? [])].toSorted((a, b) =>
+			a.name.localeCompare(b.name),
+		);
+		if (JSON.stringify(oldMcpTools) !== JSON.stringify(newMcpTools) && !opts?.confirmMcpTools) {
+			return {
+				success: false,
+				error: {
+					code: "MCP_TOOL_CONSENT_REQUIRED",
+					message: "Plugin update changes its MCP tools",
+					details: {
+						mcpTools: newMcpTools.map(({ inputSchema: _, outputSchema: __, ...tool }) => tool),
+					},
+				},
+			};
+		}
+
 		// Store new bundle
 		await storeBundleInR2(storage, pluginId, newVersion, bundle);
 
@@ -673,6 +709,8 @@ export async function handleMarketplaceUpdate(
 			marketplaceVersion: newVersion,
 			displayName: pluginDetail.name,
 			description: pluginDetail.description ?? undefined,
+			mcpToolsEnabled: false,
+			mcpToolsConsent: null,
 		});
 
 		// Clean up old bundle from R2 (best-effort)