emdash 0.28.0 → 0.29.0

package/src/api/schemas/relations.ts

@@ -0,0 +1,109 @@
+import { z } from "zod";
+
+const slugPattern = /^[a-z][a-z0-9_]*$/;
+const collectionSlug = z
+	.string()
+	.min(1)
+	.max(63)
+	.regex(slugPattern, "Invalid collection slug format");
+
+export const createRelationBody = z
+	.object({
+		name: z
+			.string()
+			.min(1)
+			.max(63)
+			.regex(slugPattern, "Name must be lowercase alphanumeric with underscores"),
+		parentCollection: collectionSlug.optional(),
+		childCollection: collectionSlug.optional(),
+		parentLabel: z.string().min(1).max(200),
+		childLabel: z.string().min(1).max(200),
+		locale: z.string().min(1).optional(),
+		translationOf: z.string().min(1).optional(),
+	})
+	// A translation inherits its structural fields (name, parentCollection,
+	// childCollection) from the source relation, so the handler ignores any
+	// collections supplied alongside `translationOf`. Require them only when
+	// minting a base relation, so callers aren't forced to pass discarded values.
+	.refine(
+		(body) =>
+			body.translationOf !== undefined ||
+			(body.parentCollection !== undefined && body.childCollection !== undefined),
+		{ message: "parentCollection and childCollection are required unless translationOf is set" },
+	)
+	.meta({ id: "CreateRelationBody" });
+
+export const updateRelationBody = z
+	.object({
+		parentLabel: z.string().min(1).max(200).optional(),
+		childLabel: z.string().min(1).max(200).optional(),
+	})
+	// Reject empty payloads: an update touching no field is a client mistake, not
+	// a successful no-op. Without this, `{}` validates and the handler returns 200
+	// with the unchanged row, so a typo'd payload looks like it landed.
+	.refine((body) => body.parentLabel !== undefined || body.childLabel !== undefined, {
+		message: "At least one of parentLabel or childLabel is required",
+	})
+	.meta({ id: "UpdateRelationBody" });
+
+export const setReferenceChildrenBody = z
+	.object({ childIds: z.array(z.string().min(1)).max(1000) })
+	.meta({ id: "SetReferenceChildrenBody" });
+
+export const relationDefSchema = z
+	.object({
+		id: z.string(),
+		name: z.string(),
+		parentCollection: z.string(),
+		childCollection: z.string(),
+		parentLabel: z.string(),
+		childLabel: z.string(),
+		locale: z.string(),
+		translationGroup: z.string(),
+	})
+	.meta({ id: "RelationDef" });
+
+export const relationListResponseSchema = z
+	.object({ relations: z.array(relationDefSchema) })
+	.meta({ id: "RelationListResponse" });
+
+export const relationResponseSchema = z
+	.object({ relation: relationDefSchema })
+	.meta({ id: "RelationResponse" });
+
+export const relationTranslationsSchema = z
+	.object({
+		translationGroup: z.string(),
+		translations: z.array(
+			z.object({
+				id: z.string(),
+				name: z.string(),
+				locale: z.string(),
+				parentLabel: z.string(),
+				childLabel: z.string(),
+			}),
+		),
+	})
+	.meta({ id: "RelationTranslations" });
+
+export const entryRefSchema = z
+	.object({
+		id: z.string(),
+		slug: z.string().nullable(),
+		collection: z.string(),
+		// The actual locale of the resolved variant. When no variant matches the
+		// requesting entry's locale, the ref falls back to another locale's row;
+		// this field makes that substitution explicit instead of silently
+		// presenting a wrong-locale entry under the requested context.
+		locale: z.string().nullable(),
+		sortOrder: z.number().int().optional(),
+	})
+	.meta({ id: "ReferenceEntryRef" });
+
+export const referenceChildrenResponseSchema = z
+	.object({ children: z.array(entryRefSchema), nextCursor: z.string().optional() })
+	.meta({ id: "ReferenceChildrenResponse" });
+
+export const referenceParentsResponseSchema = z
+	.object({ parents: z.array(entryRefSchema), nextCursor: z.string().optional() })
+	.meta({ id: "ReferenceParentsResponse" });

package/src/api/schemas/search.ts

@@ -13,6 +13,7 @@ export const searchQuery = z
 		status: z.string().optional(),
 		locale: localeCode.optional(),
 		limit: z.coerce.number().int().min(1).max(100).optional(),
+		cursor: z.string().optional(),
 	})
 	.meta({ id: "SearchQuery" });
 

package/src/astro/integration/index.ts

@@ -350,6 +350,7 @@ export function emdash(config: EmDashConfig = {}): AstroIntegration {
 		trustedProxyHeaders: resolvedConfig.trustedProxyHeaders,
 		maxUploadSize: resolvedConfig.maxUploadSize,
 		admin: resolvedConfig.admin,
+		toolbar: resolvedConfig.toolbar,
 	};
 
 	// Determine auth mode for route injection

package/src/astro/integration/routes.ts

@@ -234,6 +234,11 @@ export function injectCoreRoutes(
 		entrypoint: resolveRoute("api/media/providers/[providerId]/[itemId].ts"),
 	});
 
+	injectRoute({
+		pattern: "/_emdash/api/admin/media-usage/repair",
+		entrypoint: resolveRoute("api/admin/media-usage/repair.ts"),
+	});
+
 	// Import API routes
 	injectRoute({
 		pattern: "/_emdash/api/import/probe",

package/src/astro/integration/runtime.ts

@@ -589,6 +589,30 @@ export interface EmDashConfig {
 		favicon?: string;
 	};
 
+	/**
+	 * Editor toolbar delivery on public pages.
+	 *
+	 * - `"server"` (default): the toolbar is injected server-side into every
+	 *   HTML response rendered for an authenticated editor. Simple and
+	 *   zero-config, but behind a shared cache (Cloudflare Cache Everything /
+	 *   Workers Cache, Fastly, Varnish, …) editors often receive the cached
+	 *   anonymous variant — without the toolbar — whenever an anonymous visitor
+	 *   primed the cache first, so the toolbar appears and disappears with
+	 *   cache state.
+	 * - `"client"`: public HTML is identical for everyone (nothing
+	 *   session-specific is injected server-side, so shared caches stay fully
+	 *   effective). A tiny bootstrap script shows an "Edit" pill for browsers
+	 *   that have logged into the admin (non-secret localStorage flag). Clicking
+	 *   it verifies the session and reloads the page with an `_edit` query
+	 *   param, which is always rendered fresh (never cached) with the full
+	 *   toolbar. Logged-out visitors opening an `_edit` URL are redirected to
+	 *   the canonical URL.
+	 * - `false`: never render the toolbar or bootstrap script.
+	 *
+	 * See the visual-editing docs for the cache-behavior details.
+	 */
+	toolbar?: "server" | "client" | false;
+
 	/**
 	 * Version of Astro the host project is building with. Populated by the
 	 * integration's `astro:config:setup` hook (not authored by the user) and

package/src/astro/middleware/request-context.ts

@@ -8,37 +8,123 @@
  * - Preview tokens: _preview query param with signed HMAC token
  * - Edit mode: emdash-edit-mode cookie (for visual editing)
  * - Toolbar injection: floating pill for authenticated editors
+ * - Client toolbar mode (`toolbar: "client"`): cache-identical HTML with a
+ *   client-side bootstrap pill and an `_edit` query param for fresh editor
+ *   renders (Discussion #1742)
  */
 
+import type { APIContext } from "astro";
 import { defineMiddleware } from "astro:middleware";
+// @ts-ignore - virtual module
+import virtualConfig from "virtual:emdash/config";
 
 import { resolveSecretsCached } from "#config/secrets.js";
 
 import { verifyPreviewToken, parseContentId } from "../../preview/tokens.js";
 import { getRequestContext, runWithContext } from "../../request-context.js";
+import { EDIT_PARAM, renderToolbarBootstrap } from "../../visual-editing/toolbar-bootstrap.js";
 import { renderToolbar } from "../../visual-editing/toolbar.js";
 
+type ToolbarMode = "server" | "client" | false;
+
+const toolbarMode: ToolbarMode = virtualConfig?.toolbar ?? "server";
+
+/** Astro's route-cache handle. EmDash requires Astro 6+, so it's always present. */
+type RouteCache = APIContext["cache"];
+
 /**
- * Inject toolbar HTML into a response if it's an HTML page.
- * Returns the original response if not HTML.
+ * Opt the current request out of Astro's route cache (e.g. Workers Cache on
+ * Cloudflare). `Cache-Control` headers do NOT cover this: the adapter derives
+ * the shared-cache TTL from the route-cache options (on Cloudflare via
+ * `Cloudflare-CDN-Cache-Control`), so session-specific responses must
+ * explicitly disable it or they get stored in the shared cache and served to
+ * anonymous visitors without ever invoking the middleware again. With no cache
+ * provider configured this is a no-op (`NoopAstroCache`/`DisabledAstroCache`).
  */
-async function injectToolbar(response: Response, toolbarHtml: string): Promise<Response> {
+function optOutOfRouteCache(cache: RouteCache): void {
+	cache.set(false);
+}
+
+/**
+ * Inject HTML before `</body>` if the response is an HTML page with a body
+ * end tag. Does not touch cache headers — callers decide whether the result
+ * is still shareable. `injected` tells the caller whether anything changed.
+ */
+async function injectBeforeBodyEnd(
+	response: Response,
+	htmlToInject: string,
+): Promise<{ response: Response; injected: boolean }> {
 	const contentType = response.headers.get("content-type");
-	if (!contentType?.includes("text/html")) return response;
+	if (!contentType?.includes("text/html")) return { response, injected: false };
 
 	const html = await response.text();
-	if (!html.includes("</body>")) return new Response(html, response);
+	if (!html.includes("</body>")) {
+		// Body already consumed — rebuild the response unchanged.
+		return { response: new Response(html, response), injected: false };
+	}
+
+	const injected = html.replace("</body>", `${htmlToInject}</body>`);
+	return {
+		response: new Response(injected, {
+			status: response.status,
+			headers: response.headers,
+		}),
+		injected: true,
+	};
+}
+
+/**
+ * Inject toolbar HTML into a response if it's an HTML page.
+ * Returns the original response if not HTML.
+ */
+async function injectToolbar(
+	response: Response,
+	toolbarHtml: string,
+	routeCache: RouteCache,
+): Promise<Response> {
+	const result = await injectBeforeBodyEnd(response, toolbarHtml);
+	if (result.injected) {
+		// Toolbar-injected HTML is session-specific (its presence reveals an
+		// active editor session); it must never be stored in a shared CDN cache
+		// and served to anonymous visitors. Mirrors the preview branch's guard
+		// (#1398). `Cache-Control` covers browsers/downstream proxies; the
+		// route-cache opt-out covers the shared edge cache, which ignores
+		// `Cache-Control`.
+		result.response.headers.set("Cache-Control", "private, no-store");
+		optOutOfRouteCache(routeCache);
+	}
+	return result.response;
+}
 
-	const injected = html.replace("</body>", `${toolbarHtml}</body>`);
-	const result = new Response(injected, {
-		status: response.status,
-		headers: response.headers,
+/**
+ * Inject the client-toolbar bootstrap script. Identical for every visitor, so
+ * cache headers and route-cache options are left untouched and the response
+ * stays fully shareable.
+ */
+async function injectBootstrap(response: Response): Promise<Response> {
+	const result = await injectBeforeBodyEnd(response, renderToolbarBootstrap());
+	return result.response;
+}
+
+/**
+ * Redirect an `_edit` URL to its canonical form (same URL without the param).
+ * Applied when the requester is not an authenticated editor, so a shared
+ * `?_edit` link degrades gracefully for everyone else (Discussion #1742).
+ */
+function redirectToCanonical(url: URL): Response {
+	const canonical = new URL(url);
+	canonical.searchParams.delete(EDIT_PARAM);
+	return new Response(null, {
+		status: 302,
+		headers: {
+			Location: canonical.pathname + canonical.search + canonical.hash,
+			// Header-following caches (Fastly, Varnish, browsers) must not store
+			// the redirect — a cached 302 would bounce editors back to the
+			// canonical URL. The route-cache opt-out at the call site covers the
+			// Workers Cache, which ignores Cache-Control.
+			"Cache-Control": "private, no-store",
+		},
 	});
-	// Toolbar-injected HTML is session-specific (its presence reveals an active
-	// editor session); it must never be stored in a shared CDN cache and served
-	// to anonymous visitors. Mirrors the preview branch's guard (#1398).
-	result.headers.set("Cache-Control", "private, no-store");
-	return result;
 }
 
 export const onRequest = defineMiddleware(async (context, next) => {
@@ -73,9 +159,30 @@ export const onRequest = defineMiddleware(async (context, next) => {
 	// Fast path: check for CMS signals before doing any work
 	const hasEditCookie = cookies.get("emdash-edit-mode")?.value === "true";
 	const hasPreviewToken = url.searchParams.has("_preview");
+	// `_edit` requests a fresh (never cached) editor render; only meaningful in
+	// client toolbar mode where public HTML is otherwise identical for everyone.
+	const hasEditParam = toolbarMode === "client" && url.searchParams.has(EDIT_PARAM);
+
+	if (hasEditParam) {
+		// `_edit` URLs are their own cache key. Never store them in the route
+		// cache — a cached anonymous redirect would bounce editors back to the
+		// canonical URL, and a cached editor render must never be shared.
+		optOutOfRouteCache(context.cache);
+
+		// A non-editor (anonymous, logged-out, or insufficient role) opening an
+		// `_edit` URL is sent to the canonical URL — shared `?_edit` links
+		// degrade gracefully and never prime a cache entry with page content.
+		if (!isEditor) {
+			return redirectToCanonical(url);
+		}
+	}
 
-	// No CMS signals and not an editor → skip everything (zero overhead)
+	// No CMS signals and not an editor → skip everything (zero overhead in
+	// server mode; client mode injects the identical-for-everyone bootstrap)
 	if (!hasEditCookie && !hasPreviewToken && !isEditor) {
+		if (toolbarMode === "client") {
+			return injectBootstrap(await next());
+		}
 		return next();
 	}
 
@@ -86,6 +193,8 @@ export const onRequest = defineMiddleware(async (context, next) => {
 	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- Astro context includes currentLocale when i18n is configured
 	const locale = (context as { currentLocale?: string }).currentLocale;
 
+	const routeCache = context.cache;
+
 	// Verify preview token if present.
 	// The preview secret is resolved via `resolveSecretsCached`: env wins,
 	// otherwise a DB-stored value is read (or generated on first need).
@@ -122,32 +231,65 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
 			// Preview responses must not be cached -- draft content could leak past token expiry.
 			// Clone the response before modifying headers — the original may be immutable.
+			// `Cache-Control` only governs browsers/downstream proxies; the shared
+			// edge cache follows the route-cache options, so opt out of those too —
+			// otherwise the draft response is stored in the shared cache and served
+			// on cache hits without token verification until TTL/purge. Opt out for
+			// any request carrying a `_preview` param (valid or not): those URLs are
+			// per-token, so cached copies are useless at best and drafts at worst.
+			if (hasPreviewToken) {
+				optOutOfRouteCache(routeCache);
+			}
 			if (preview) {
 				response = new Response(response.body, response);
 				response.headers.set("Cache-Control", "private, no-store");
 			}
 
-			// Inject toolbar for authenticated editors
-			if (isEditor) {
+			// Inject toolbar for authenticated editors. Preview and edit-mode
+			// responses are session-specific (`private, no-store` + route-cache
+			// opt-out) in every toolbar mode, so the server toolbar is safe to
+			// inject here even in client mode.
+			if (isEditor && toolbarMode !== false) {
 				const toolbarHtml = renderToolbar({
 					editMode,
 					isPreview: !!preview,
 				});
-				return injectToolbar(response, toolbarHtml);
+				return injectToolbar(response, toolbarHtml, routeCache);
+			}
+
+			// Stale edit cookie without a session (client mode): still serve the
+			// shareable bootstrap variant.
+			if (toolbarMode === "client" && !isEditor && !preview) {
+				return injectBootstrap(response);
 			}
 
 			return response;
 		});
 	}
 
-	// Editor without CMS signals — no ALS needed, but inject toolbar
+	// Editor without preview/edit-mode signals.
 	if (isEditor) {
+		if (toolbarMode === false) {
+			return next();
+		}
+
+		// Client mode: without the `_edit` param the response must stay
+		// byte-identical to the anonymous variant (plus the same bootstrap
+		// script), so shared caches serve one entry for everyone. The bootstrap
+		// pill is the editor's entry point into the fresh `_edit` render.
+		if (toolbarMode === "client" && !hasEditParam) {
+			return injectBootstrap(await next());
+		}
+
+		// Server mode, or an `_edit` request in client mode: inject the full
+		// toolbar (response becomes `private, no-store` and route-cache
+		// opted out).
 		const response = await next();
 		const toolbarHtml = renderToolbar({
 			editMode: false,
 			isPreview: false,
 		});
-		return injectToolbar(response, toolbarHtml);
+		return injectToolbar(response, toolbarHtml, routeCache);
 	}
 
 	return next();

package/src/astro/middleware.ts

@@ -76,6 +76,17 @@ import type { EmDashHandlers } from "./types.js";
  */
 const RUNTIME_INIT_DEADLINE_MS = DB_INIT_DEADLINE_MS + 15_000;
 
+/**
+ * Throttle for the anonymous-path runtime-init failure log. While a site is
+ * stuck (e.g. a failing migration in its backoff window, #1744) every
+ * anonymous request lands in that catch; one line per interval per isolate
+ * keeps the failure visible without flooding logs on a busy site. Plain
+ * module state (not globalThis): a duplicated SSR chunk just means an extra
+ * log line, which is harmless.
+ */
+const RUNTIME_INIT_ERROR_LOG_INTERVAL_MS = 30_000;
+let lastRuntimeInitErrorLogAt = 0;
+
 /**
  * Whether we've verified the database has been set up.
  * On a fresh deployment the first request may hit a public page, bypassing
@@ -152,8 +163,7 @@ function getConfig(): EmDashConfig | null {
 			}
 		}
 
-		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- virtual module import is untyped (@ts-ignore above)
-		return virtualConfig as EmDashConfig;
+		return virtualConfig;
 	}
 	return null;
 }
@@ -524,11 +534,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 					try {
 						const { getDb } = await import("../loader.js");
 						const db = await getDb();
-						await db
-							.selectFrom("_emdash_migrations" as keyof Database)
-							.selectAll()
-							.limit(1)
-							.execute();
+						await db.selectFrom("_emdash_migrations").selectAll().limit(1).execute();
 						markSetupVerified();
 					} catch (error) {
 						// Only a genuinely-missing migrations table means a fresh,
@@ -571,8 +577,15 @@ export const onRequest = defineMiddleware(async (context, next) => {
 							// requests carry no session.
 							storage: runtime.storage,
 						} as EmDashHandlers;
-					} catch {
-						// Non-fatal — EmDashHead will fall back to base SEO contributions
+					} catch (error) {
+						// Non-fatal — EmDashHead falls back to base SEO contributions —
+						// but log it (throttled): a persistently failing init (e.g. a
+						// failing migration, #1744) is otherwise invisible on the
+						// anonymous path, silently degrading every public page.
+						if (Date.now() - lastRuntimeInitErrorLogAt >= RUNTIME_INIT_ERROR_LOG_INTERVAL_MS) {
+							lastRuntimeInitErrorLogAt = Date.now();
+							console.error("[emdash] runtime init failed (page renders without CMS data):", error);
+						}
 					}
 					timings.push({ name: "rt", dur: performance.now() - t0, desc: "Runtime init" });
 					// Append cold-only sub-phase timings so the breakdown is visible

package/src/astro/routes/api/admin/comments/[id]/status.ts

@@ -14,7 +14,6 @@ import { commentStatusBody } from "#api/schemas.js";
 import { getSiteBaseUrl } from "#api/site-url.js";
 import { lookupContentAuthor, sendCommentNotification } from "#comments/notifications.js";
 import { moderateComment, type CommentHookRunner } from "#comments/service.js";
-import type { CommentStatus } from "#db/repositories/comment.js";
 import type { ModerationDecision } from "#plugins/types.js";
 
 export const prerender = false;
@@ -37,7 +36,7 @@ export const PUT: APIRoute = async ({ params, request, locals }) => {
 		const body = await parseBody(request, commentStatusBody);
 		if (isParseError(body)) return body;
 
-		const newStatus = body.status as CommentStatus;
+		const newStatus = body.status;
 
 		// Build hook runner for the service
 		const hookRunner: CommentHookRunner = {

package/src/astro/routes/api/admin/comments/index.ts

@@ -11,7 +11,6 @@ import { handleError, requireDb, unwrapResult } from "#api/error.js";
 import { handleCommentInbox } from "#api/handlers/comments.js";
 import { isParseError, parseQuery } from "#api/parse.js";
 import { commentListQuery } from "#api/schemas.js";
-import type { CommentStatus } from "#db/repositories/comment.js";
 
 export const prerender = false;
 
@@ -32,7 +31,7 @@ export const GET: APIRoute = async ({ url, locals }) => {
 		if (isParseError(query)) return query;
 
 		const result = await handleCommentInbox(emdash.db, {
-			status: query.status as CommentStatus | undefined,
+			status: query.status,
 			collection: query.collection,
 			search: query.search,
 			limit: query.limit,

package/src/astro/routes/api/admin/media-usage/repair.ts

@@ -0,0 +1,24 @@
+import type { APIRoute } from "astro";
+
+import { requirePerm } from "#api/authorize.js";
+import { requireDb, unwrapResult } from "#api/error.js";
+import { handleMediaUsageRepair } from "#api/handlers/media-usage.js";
+import { isParseError, parseBody } from "#api/parse.js";
+import { mediaUsageRepairBody } from "#api/schemas.js";
+
+export const prerender = false;
+
+export const POST: APIRoute = async ({ request, locals }) => {
+	const { emdash, user } = locals;
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
+
+	const denied = requirePerm(user, "schema:manage");
+	if (denied) return denied;
+
+	const body = await parseBody(request, mediaUsageRepairBody);
+	if (isParseError(body)) return body;
+
+	const result = await handleMediaUsageRepair(emdash.db, body);
+	return unwrapResult(result);
+};

package/src/astro/routes/api/auth/oauth/[provider]/callback.ts

@@ -118,8 +118,7 @@ export const GET: APIRoute = async ({ params, request, locals, session, redirect
 		// Get OAuth providers from environment
 		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- locals.runtime is injected by the Cloudflare adapter at runtime; not declared on App.Locals since the adapter is optional
 		const runtimeLocals = locals as unknown as { runtime?: { env?: Record<string, unknown> } };
-		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- import.meta.env is typed as ImportMetaEnv but we need Record<string, unknown> for getOAuthConfig
-		const env = runtimeLocals.runtime?.env ?? (import.meta.env as Record<string, unknown>);
+		const env = runtimeLocals.runtime?.env ?? import.meta.env;
 		const providers = getOAuthConfig(env);
 
 		if (!providers[provider]) {

package/src/astro/routes/api/auth/oauth/[provider].ts

@@ -97,8 +97,7 @@ export const GET: APIRoute = async ({ params, request, locals, redirect }) => {
 		// Access via locals.runtime for Cloudflare, or import.meta.env for Node
 		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- locals.runtime is injected by the Cloudflare adapter at runtime; not declared on App.Locals since the adapter is optional
 		const runtimeLocals = locals as unknown as { runtime?: { env?: Record<string, unknown> } };
-		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- import.meta.env is typed as ImportMetaEnv but we need Record<string, unknown> for getOAuthConfig
-		const env = runtimeLocals.runtime?.env ?? (import.meta.env as Record<string, unknown>);
+		const env = runtimeLocals.runtime?.env ?? import.meta.env;
 		const providers = getOAuthConfig(env);
 
 		if (!providers[provider]) {

package/src/astro/routes/api/comments/[collection]/[contentId]/index.ts

@@ -14,6 +14,7 @@ import { createCommentBody } from "#api/schemas.js";
 import { getSiteBaseUrl } from "#api/site-url.js";
 import { sendCommentNotification } from "#comments/notifications.js";
 import { createComment, type CommentHookRunner } from "#comments/service.js";
+import { getTurnstileSecretKey, verifyTurnstileToken } from "#comments/turnstile.js";
 import { resolveSecretsCached } from "#config/secrets.js";
 import { CommentRepository } from "#db/repositories/comment.js";
 import { validateIdentifier } from "#db/validate.js";
@@ -163,6 +164,18 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 			return apiError("RATE_LIMITED", "Too many comments. Please try again later.", 429);
 		}
 
+		// Anti-spam: Turnstile — enforced only when the operator configured a
+		// secret key. Runs after the free checks (honeypot, rate limit) so
+		// obvious spam never triggers a siteverify subrequest. Fails closed:
+		// missing token, failed verification, and siteverify errors all reject.
+		const turnstileSecretKey = getTurnstileSecretKey();
+		if (turnstileSecretKey) {
+			const verified = await verifyTurnstileToken(body.turnstileToken, turnstileSecretKey, meta.ip);
+			if (!verified) {
+				return apiError("TURNSTILE_FAILED", "CAPTCHA verification failed", 403);
+			}
+		}
+
 		// Build collection settings
 		const collectionSettings: CollectionCommentSettings = {
 			commentsEnabled: collectionRow.comments_enabled === 1,