emdash 0.28.1 → 0.30.0

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/content.ts

@@ -5,6 +5,7 @@
 import type { Kysely } from "kysely";
 import { sql } from "kysely";
 
+import { isSqlite } from "../../database/dialect-helpers.js";
 import { BylineRepository } from "../../database/repositories/byline.js";
 import type { ContentBylineInput } from "../../database/repositories/byline.js";
 import { CommentRepository } from "../../database/repositories/comment.js";
@@ -12,6 +13,7 @@ import { ContentRepository } from "../../database/repositories/content.js";
 import { RedirectRepository } from "../../database/repositories/redirect.js";
 import { RevisionRepository } from "../../database/repositories/revision.js";
 import { SeoRepository } from "../../database/repositories/seo.js";
+import { TaxonomyRepository } from "../../database/repositories/taxonomy.js";
 import {
 	EmDashValidationError,
 	ScheduledNotDueError,
@@ -30,7 +32,9 @@ import type { Database } from "../../database/types.js";
 import { validateIdentifier } from "../../database/validate.js";
 import { getI18nConfig, isI18nEnabled } from "../../i18n/config.js";
 import { invalidateRedirectCache } from "../../redirects/cache.js";
-import { isMissingTableError } from "../../utils/db-errors.js";
+import { FTSManager } from "../../search/fts-manager.js";
+import { invalidateTermCache } from "../../taxonomies/index.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";
@@ -327,6 +331,30 @@ async function resolveSearchColumns(db: Kysely<Database>, collection: string): P
 	return columns;
 }
 
+/**
+ * Decide whether the content-list `q` filter can be served from the
+ * collection's FTS5 index instead of a full-scan substring LIKE (#1517).
+ *
+ * Requires SQLite (FTS5 is SQLite-only), search enabled on the collection,
+ * every non-slug display column present in the searchable-field set (or the
+ * index would miss matches the LIKE finds), and the index table actually
+ * existing.
+ */
+async function canUseFtsForListFilter(
+	db: Kysely<Database>,
+	collection: string,
+	searchColumns: string[],
+): Promise<boolean> {
+	if (!isSqlite(db)) return false;
+	const ftsManager = new FTSManager(db);
+	const config = await ftsManager.getSearchConfig(collection);
+	if (!config?.enabled) return false;
+	const searchable = new Set(await ftsManager.getSearchableFields(collection));
+	const covered = searchColumns.every((col) => col === "slug" || searchable.has(col));
+	if (!covered) return false;
+	return ftsManager.ftsTableExists(collection);
+}
+
 /**
  * Create a 301 auto-redirect from an entry's old URL to its new one after a
  * slug change, using the collection's URL pattern. Shared by
@@ -416,6 +444,7 @@ export async function handleContentList(
 		if (q) {
 			where.q = q;
 			where.searchColumns = await resolveSearchColumns(db, collection);
+			where.useFts = await canUseFtsForListFilter(db, collection, where.searchColumns);
 		}
 
 		const result = await repo.findMany(collection, {
@@ -456,6 +485,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 {
@@ -638,6 +676,7 @@ export async function handleContentCreate(
 		locale?: string;
 		translationOf?: string;
 		seo?: ContentSeoInput;
+		taxonomies?: Record<string, string[]>;
 		createdAt?: string | null;
 		publishedAt?: string | null;
 	},
@@ -712,7 +751,6 @@ export async function handleContentCreate(
 			// when the target already has credits, but the cleaner guard
 			// is to skip the call entirely.
 			if (body.translationOf) {
-				const { TaxonomyRepository } = await import("../../database/repositories/taxonomy.js");
 				const taxRepo = new TaxonomyRepository(trx);
 				await taxRepo.copyEntryTerms(collection, body.translationOf, created.id);
 
@@ -737,6 +775,18 @@ export async function handleContentCreate(
 				created.seo = { ...SEO_DEFAULTS };
 			}
 
+			// Attach taxonomy terms in the same transaction. The MCP tool
+			// (and the REST create body) previously accepted a `taxonomies`
+			// field on `content_create` without doing anything with it, so
+			// agents publishing a categorized/tagged entry had to make N
+			// follow-up REST calls per taxonomy. This resolves each slug in
+			// the entry's locale and pipes it through the same
+			// `setTermsForEntry` path the `.../terms/{taxonomy}` REST route
+			// uses, so the two entry points can't drift.
+			if (body.taxonomies) {
+				await assignTaxonomies(trx, collection, created.id, effectiveLocale, body.taxonomies);
+			}
+
 			return created;
 		});
 
@@ -816,6 +866,7 @@ export async function handleContentUpdate(
 		locale?: string;
 		_rev?: string;
 		seo?: ContentSeoInput;
+		taxonomies?: Record<string, string[]>;
 		publishedAt?: string | null;
 	},
 ): Promise<ApiResult<ContentResponse>> {
@@ -922,6 +973,20 @@ export async function handleContentUpdate(
 
 			await hydrateBylines(trx, collection, updated);
 
+			// Replace taxonomy assignments in the same transaction. Uses the
+			// entry's own locale (post-update) to resolve slugs so an update
+			// that also changes locale still lands on the correct term
+			// variants. See handleContentCreate for rationale.
+			if (body.taxonomies) {
+				await assignTaxonomies(
+					trx,
+					collection,
+					resolvedId,
+					updated.locale ?? body.locale,
+					body.taxonomies,
+				);
+			}
+
 			return updated;
 		});
 
@@ -1431,14 +1496,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,
@@ -1769,3 +1859,57 @@ async function syncNonTranslatableFields(
 		AND id != ${updatedItemId}
 	`.execute(trx);
 }
+
+/**
+ * Resolve a `{ taxonomyName: [slug, ...] }` map to term IDs and replace the
+ * entry's assignments for each named taxonomy.
+ *
+ * Shared by handleContentCreate and handleContentUpdate so both MCP entry
+ * points behave identically. Slug resolution is scoped to `locale`; passing
+ * `undefined` lets `findBySlug` fall back to its default (lowest locale code)
+ * so callers on single-locale sites don't need to know the site's default.
+ *
+ * Throws EmDashValidationError on unknown slug or wrong shape; the calling
+ * handler translates that into a VALIDATION_ERROR response.
+ */
+async function assignTaxonomies(
+	trx: Kysely<Database>,
+	collection: string,
+	entryId: string,
+	locale: string | undefined,
+	taxonomies: Record<string, string[]>,
+): Promise<void> {
+	const taxRepo = new TaxonomyRepository(trx);
+	let anyChange = false;
+
+	for (const [taxonomyName, slugs] of Object.entries(taxonomies)) {
+		if (!Array.isArray(slugs)) {
+			throw new EmDashValidationError(`taxonomies.${taxonomyName} must be an array of term slugs`);
+		}
+
+		const termIds: string[] = [];
+		for (const slug of slugs) {
+			if (typeof slug !== "string" || slug.length === 0) {
+				throw new EmDashValidationError(
+					`taxonomies.${taxonomyName} contains a non-string or empty slug`,
+				);
+			}
+			const term = await taxRepo.findBySlug(taxonomyName, slug, locale);
+			if (!term) {
+				throw new EmDashValidationError(
+					`Unknown taxonomy term: ${taxonomyName}='${slug}'${
+						locale ? ` (locale '${locale}')` : ""
+					}`,
+				);
+			}
+			termIds.push(term.id);
+		}
+
+		await taxRepo.setTermsForEntry(collection, entryId, taxonomyName, termIds);
+		anyChange = true;
+	}
+
+	// Match the REST route's behaviour: taxonomy term assignments changed,
+	// so invalidate the taxonomy object cache used during hydration.
+	if (anyChange) invalidateTermCache();
+}

package/src/api/handlers/dashboard.ts

@@ -21,6 +21,7 @@ export interface CollectionStats {
 	total: number;
 	published: number;
 	draft: number;
+	scheduled: number;
 }
 
 export interface RecentItem {
@@ -69,6 +70,7 @@ export async function handleDashboardStats(
 					total: stats.total,
 					published: stats.published,
 					draft: stats.draft,
+					scheduled: stats.scheduled,
 				};
 			}),
 		);

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

@@ -61,6 +61,22 @@ export {
 	type MediaResponse,
 } 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
 export {
 	handleSchemaCollectionList,
@@ -103,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)