emdash 0.29.0 → 0.31.0

package/src/astro/routes/api/content/[collection]/[id]/references/[relation]/children.ts

@@ -21,6 +21,8 @@ export const GET: APIRoute = async ({ params, request, locals }) => {
 	const { emdash, user } = locals;
 	const { collection, id, relation } = params;
 
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
 	const denied = requirePerm(user, "content:read");
 	if (denied) return denied;
 
@@ -28,9 +30,6 @@ export const GET: APIRoute = async ({ params, request, locals }) => {
 		return apiError("VALIDATION_ERROR", "Collection, id, and relation required", 400);
 	}
 
-	const dbErr = requireDb(emdash?.db);
-	if (dbErr) return dbErr;
-
 	const query = parseQuery(new URL(request.url), cursorPaginationQuery);
 	if (isParseError(query)) return query;
 
@@ -57,6 +56,8 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 		return apiError("VALIDATION_ERROR", "Collection, id, and relation required", 400);
 	}
 
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
 	// Gate on the base edit capability BEFORE the existence lookup. Resolving the
 	// entry first would let a user with no edit permission distinguish real ids
 	// (403) from missing ids (404) — an existence oracle. Mirrors the taxonomy
@@ -64,9 +65,6 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 	const denied = requirePerm(user, "content:edit_own");
 	if (denied) return denied;
 
-	const dbErr = requireDb(emdash?.db);
-	if (dbErr) return dbErr;
-
 	// Resolve the parent entry to gate on its author (ownership-aware write).
 	const parent = await new ContentRepository(emdash.db).findByIdOrSlug(collection, id);
 	if (!parent) return apiError("NOT_FOUND", "Content not found", 404);

package/src/astro/routes/api/content/[collection]/[id]/references/[relation]/parents.ts

@@ -19,6 +19,8 @@ export const GET: APIRoute = async ({ params, request, locals }) => {
 	const { emdash, user } = locals;
 	const { collection, id, relation } = params;
 
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
 	const denied = requirePerm(user, "content:read");
 	if (denied) return denied;
 
@@ -26,9 +28,6 @@ export const GET: APIRoute = async ({ params, request, locals }) => {
 		return apiError("VALIDATION_ERROR", "Collection, id, and relation required", 400);
 	}
 
-	const dbErr = requireDb(emdash?.db);
-	if (dbErr) return dbErr;
-
 	const query = parseQuery(new URL(request.url), cursorPaginationQuery);
 	if (isParseError(query)) return query;
 

package/src/astro/routes/api/content/[collection]/[id]/revisions.ts

@@ -13,15 +13,14 @@ export const prerender = false;
 
 export const GET: APIRoute = async ({ params, url, locals }) => {
 	const { emdash, user } = locals;
+	if (!emdash?.handleRevisionList) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
 	const denied = requirePerm(user, "content:read_drafts");
 	if (denied) return denied;
 	const collection = params.collection!;
 	const id = params.id!;
 
-	if (!emdash?.handleRevisionList) {
-		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
-	}
-
 	const limitParam = url.searchParams.get("limit");
 	const parsedLimit = limitParam ? parseInt(limitParam, 10) : undefined;
 	const result = await emdash.handleRevisionList(collection, id, {

package/src/astro/routes/api/content/[collection]/[id]/terms/[taxonomy].ts

@@ -24,6 +24,8 @@ export const GET: APIRoute = async ({ params, locals }) => {
 	const { emdash, user } = locals;
 	const { collection, id, taxonomy } = params;
 
+	const dbErr = requireDb(emdash?.db);
+	if (dbErr) return dbErr;
 	const denied = requirePerm(user, "content:read");
 	if (denied) return denied;
 
@@ -31,9 +33,6 @@ export const GET: APIRoute = async ({ params, locals }) => {
 		return apiError("VALIDATION_ERROR", "Collection, id, and taxonomy required", 400);
 	}
 
-	const dbErr = requireDb(emdash?.db);
-	if (dbErr) return dbErr;
-
 	try {
 		// Terms are stored against the per-locale entry row but their
 		// translation_group spans every locale. Resolve the entry's own locale
@@ -71,11 +70,10 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 		return apiError("VALIDATION_ERROR", "Collection, id, and taxonomy required", 400);
 	}
 
-	const denied = requirePerm(user, "content:edit_own");
-	if (denied) return denied;
-
 	const dbErr = requireDb(emdash?.db);
 	if (dbErr) return dbErr;
+	const denied = requirePerm(user, "content:edit_own");
+	if (denied) return denied;
 
 	if (!emdash.handleContentGet) {
 		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);

package/src/astro/routes/api/content/[collection]/[id]/translations.ts

@@ -25,15 +25,14 @@ function isPublished(t: unknown): boolean {
 
 export const GET: APIRoute = async ({ params, locals }) => {
 	const { emdash, user } = locals;
+	if (!emdash?.handleContentTranslations) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
 	const denied = requirePerm(user, "content:read");
 	if (denied) return denied;
 	const collection = params.collection!;
 	const id = params.id!;
 
-	if (!emdash?.handleContentTranslations) {
-		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
-	}
-
 	const result = await emdash.handleContentTranslations(collection, id);
 
 	// Filter out non-published translations for users without read_drafts so a

package/src/astro/routes/api/content/[collection]/[id].ts

@@ -18,16 +18,15 @@ export const prerender = false;
 
 export const GET: APIRoute = async ({ params, url, locals }) => {
 	const { emdash, user } = locals;
+	if (!emdash?.handleContentGet) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
 	const denied = requirePerm(user, "content:read");
 	if (denied) return denied;
 	const collection = params.collection!;
 	const id = params.id!;
 	const locale = url.searchParams.get("locale") || undefined;
 
-	if (!emdash?.handleContentGet) {
-		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
-	}
-
 	const result = await emdash.handleContentGet(collection, id, locale);
 
 	// Hide non-published items from users without content:read_drafts. Return

package/src/astro/routes/api/content/[collection]/authors.ts

@@ -21,12 +21,11 @@ export const GET: APIRoute = async ({ params, locals }) => {
 	// not be reachable by subscribers (content:read). content:read_drafts is
 	// the same tier the list route requires before it stops forcing
 	// status=published, so the visibility surfaces line up.
-	const denied = requirePerm(user, "content:read_drafts");
-	if (denied) return denied;
-
 	if (!emdash?.handleContentAuthors) {
 		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
 	}
+	const denied = requirePerm(user, "content:read_drafts");
+	if (denied) return denied;
 
 	const result = await emdash.handleContentAuthors(collection);
 

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

@@ -17,16 +17,15 @@ export const prerender = false;
 
 export const GET: APIRoute = async ({ params, url, locals }) => {
 	const { emdash, user } = locals;
+	if (!emdash?.handleContentList) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
 	const denied = requirePerm(user, "content:read");
 	if (denied) return denied;
 	const collection = params.collection!;
 	const query = parseQuery(url, contentListQuery);
 	if (isParseError(query)) return query;
 
-	if (!emdash?.handleContentList) {
-		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
-	}
-
 	// Subscribers must only see published content; force the status filter
 	// regardless of caller-supplied value. Any user with content:read_drafts
 	// (CONTRIBUTOR+) keeps the requested filter.
@@ -41,16 +40,15 @@ export const GET: APIRoute = async ({ params, url, locals }) => {
 
 export const POST: APIRoute = async ({ params, request, locals, cache }) => {
 	const { emdash, user } = locals;
+	if (!emdash?.handleContentCreate || !emdash?.handleContentGet) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
 	const denied = requirePerm(user, "content:create");
 	if (denied) return denied;
 	const collection = params.collection!;
 	const body = await parseBody(request, contentCreateBody);
 	if (isParseError(body)) return body;
 
-	if (!emdash?.handleContentCreate || !emdash?.handleContentGet) {
-		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
-	}
-
 	// Creating a translation requires edit permission on the source item
 	if (body.translationOf) {
 		const source = await emdash.handleContentGet(collection, body.translationOf);

package/src/astro/routes/api/content/[collection]/trash.ts

@@ -17,12 +17,11 @@ export const GET: APIRoute = async ({ params, url, locals }) => {
 	const { emdash, user } = locals;
 	const collection = params.collection!;
 
-	const denied = requirePerm(user, "content:read_drafts");
-	if (denied) return denied;
-
 	if (!emdash?.handleContentListTrashed) {
 		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
 	}
+	const denied = requirePerm(user, "content:read_drafts");
+	if (denied) return denied;
 
 	const query = parseQuery(url, contentTrashQuery);
 	if (isParseError(query)) return query;

package/src/astro/routes/api/manifest.ts

@@ -9,7 +9,7 @@
 
 import type { APIRoute } from "astro";
 
-import { handleError } from "#api/error.js";
+import { apiSuccess, handleError } from "#api/error.js";
 import { getAuthMode } from "#auth/mode.js";
 import { OptionsRepository } from "#db/repositories/options.js";
 
@@ -94,14 +94,7 @@ export const GET: APIRoute = async ({ locals }) => {
 					admin: adminBranding,
 				};
 
-		return Response.json(
-			{ data: manifest },
-			{
-				headers: {
-					"Cache-Control": "private, no-store",
-				},
-			},
-		);
+		return apiSuccess(manifest);
 	} catch (error) {
 		return handleError(error, "Failed to build manifest", "MANIFEST_BUILD_ERROR");
 	}

package/src/astro/routes/api/mcp.ts

@@ -30,7 +30,8 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		return apiError("UNAUTHORIZED", "Authentication required", 401);
 	}
 
-	const server = createMcpServer();
+	const pluginTools = await emdash.getEnabledPluginMcpTools();
+	const server = createMcpServer(pluginTools, request);
 
 	try {
 		const transport = new WebStandardStreamableHTTPServerTransport({

package/src/astro/routes/api/media/[id]/usage.ts

@@ -0,0 +1,30 @@
+import type { APIRoute } from "astro";
+
+import { requirePerm } from "#api/authorize.js";
+import { apiError, unwrapResult } from "#api/error.js";
+import { handleMediaUsageDetails } from "#api/handlers/media-usage.js";
+import { isParseError, parseQuery } from "#api/parse.js";
+import { mediaUsageDetailsQuery } from "#api/schemas.js";
+import { requireScope } from "#auth/scopes.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ params, request, locals }) => {
+	const { emdash, user } = locals;
+
+	const mediaDenied = requirePerm(user, "media:read");
+	if (mediaDenied) return mediaDenied;
+	const contentDenied = requirePerm(user, "content:read_drafts");
+	if (contentDenied) return contentDenied;
+	const scopeDenied = requireScope(locals, "admin");
+	if (scopeDenied) return scopeDenied;
+
+	const { id } = params;
+	if (!id) return apiError("INVALID_REQUEST", "Media ID required", 400);
+	if (!emdash?.db) return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+
+	const query = parseQuery(new URL(request.url), mediaUsageDetailsQuery);
+	if (isParseError(query)) return query;
+
+	return unwrapResult(await handleMediaUsageDetails(emdash.db, id, query));
+};

package/src/astro/routes/api/media/[id].ts

@@ -8,17 +8,18 @@
 
 import type { APIRoute } from "astro";
 
-import { requireOwnerPerm, requirePerm } from "#api/authorize.js";
-import { apiError, handleError, unwrapResult } from "#api/error.js";
-import { isParseError, parseBody } from "#api/parse.js";
-import { mediaUpdateBody } from "#api/schemas.js";
+import { canReadMediaUsageCount, requireOwnerPerm, requirePerm } from "#api/authorize.js";
+import { apiError, apiSuccess, handleError, unwrapResult } from "#api/error.js";
+import { handleMediaUsageSummaries } from "#api/handlers/media-usage.js";
+import { isParseError, parseBody, parseQuery } from "#api/parse.js";
+import { mediaGetQuery, mediaUpdateBody } from "#api/schemas.js";
 
 export const prerender = false;
 
 /**
  * Get media item
  */
-export const GET: APIRoute = async ({ params, locals }) => {
+export const GET: APIRoute = async ({ params, request, locals }) => {
 	const { emdash, user } = locals;
 	const { id } = params;
 
@@ -32,9 +33,19 @@ export const GET: APIRoute = async ({ params, locals }) => {
 	if (!emdash?.handleMediaGet) {
 		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
 	}
+	const query = parseQuery(new URL(request.url), mediaGetQuery);
+	if (isParseError(query)) return query;
 
 	const result = await emdash.handleMediaGet(id);
-	return unwrapResult(result);
+	if (!result.success || query.includeUsage !== "1") return unwrapResult(result);
+
+	const includeCount = canReadMediaUsageCount(user, locals.tokenScopes);
+	const usageResult = await handleMediaUsageSummaries(emdash.db, [id], { includeCount });
+	if (!usageResult.success) return unwrapResult(usageResult);
+	const usage = usageResult.data[id];
+	if (!usage) return apiError("MEDIA_USAGE_READ_ERROR", "Failed to read media usage", 500);
+
+	return apiSuccess({ item: { ...result.data.item, usage } });
 };
 
 /**

package/src/astro/routes/api/media/file/[...key].ts

@@ -36,6 +36,14 @@ export const GET: APIRoute = async ({ params, locals }) => {
 		return apiError("NOT_FOUND", "File not found", 404);
 	}
 
+	// Backup archives share the storage bucket but hold the site's full
+	// content export — they must never be reachable through the public,
+	// unauthenticated media route. Admins download them via the
+	// authenticated backups API.
+	if (key.startsWith("backups/")) {
+		return apiError("NOT_FOUND", "File not found", 404);
+	}
+
 	if (!emdash?.storage) {
 		return apiError("NOT_CONFIGURED", "Storage not configured", 500);
 	}

package/src/astro/routes/api/media.ts

@@ -10,9 +10,10 @@ import * as path from "node:path";
 import type { APIRoute } from "astro";
 import { ulid } from "ulidx";
 
-import { requirePerm } from "#api/authorize.js";
+import { canReadMediaUsageCount, requirePerm } from "#api/authorize.js";
 import { apiError, apiSuccess, handleError, unwrapResult } from "#api/error.js";
 import { GLOBAL_UPLOAD_ALLOWLIST, resolveFieldAllowlist } from "#api/handlers/media-allowlist.js";
+import { handleMediaUsageSummaries } from "#api/handlers/media-usage.js";
 import { isParseError, parseQuery } from "#api/parse.js";
 import { DEFAULT_MAX_UPLOAD_SIZE, formatFileSize, mediaListQuery } from "#api/schemas.js";
 import { MediaRepository } from "#db/repositories/media.js";
@@ -65,8 +66,26 @@ export const GET: APIRoute = async ({ request, locals }) => {
 
 	// Add URL to each media item (relative URLs for portability)
 	const itemsWithUrl = result.data.items.map((item) => addUrlToMedia(item));
+	if (query.includeUsage !== "1") {
+		return apiSuccess({ items: itemsWithUrl, nextCursor: result.data.nextCursor });
+	}
+
+	const includeCount = canReadMediaUsageCount(user, locals.tokenScopes);
+	const usageResult = await handleMediaUsageSummaries(
+		emdash.db,
+		itemsWithUrl.map((item) => item.id),
+		{ includeCount },
+	);
+	if (!usageResult.success) return unwrapResult(usageResult);
+
+	const itemsWithUsage = [];
+	for (const item of itemsWithUrl) {
+		const usage = usageResult.data[item.id];
+		if (!usage) return apiError("MEDIA_USAGE_READ_ERROR", "Failed to read media usage", 500);
+		itemsWithUsage.push({ ...item, usage });
+	}
 
-	return apiSuccess({ items: itemsWithUrl, nextCursor: result.data.nextCursor });
+	return apiSuccess({ items: itemsWithUsage, nextCursor: result.data.nextCursor });
 };
 
 /**

package/src/astro/routes/api/oauth/authorize.ts

@@ -23,7 +23,7 @@ import {
 } from "#api/handlers/oauth-authorization.js";
 import { lookupOAuthClient, validateClientRedirectUri } from "#api/handlers/oauth-clients.js";
 import { getPublicOrigin } from "#api/public-url.js";
-import { VALID_SCOPES } from "#auth/api-tokens.js";
+import { isValidScope } from "#auth/api-tokens.js";
 
 export const prerender = false;
 
@@ -69,11 +69,16 @@ function getCsrfCookie(request: Request): string | null {
 
 const SCOPE_LABELS: Record<string, string> = {
 	"content:read": "Read content (posts, pages, etc.)",
-	"content:write": "Create, edit, and delete content",
+	"content:write": "Create, edit, and delete content; manage menus and taxonomies",
 	"media:read": "View media files",
 	"media:write": "Upload and manage media files",
 	"schema:read": "View collection schemas",
 	"schema:write": "Create and modify collection schemas",
+	"taxonomies:manage": "Manage taxonomies",
+	"menus:manage": "Manage navigation menus",
+	"settings:read": "View site settings",
+	"settings:manage": "Modify site settings",
+	"mcp:tools": "Use MCP tools from all enabled plugins",
 	admin: "Full administrative access",
 };
 
@@ -141,11 +146,9 @@ export const GET: APIRoute = async ({ url, request, locals }) => {
 	}
 
 	// Parse and validate scopes
-	const validSet = new Set<string>(VALID_SCOPES);
-	const requestedScopes = (scope ?? "")
-		.split(" ")
-		.filter(Boolean)
-		.filter((s) => validSet.has(s));
+	const requestedScopes = [
+		...new Set((scope ?? "").split(" ").filter(Boolean).filter(isValidScope)),
+	];
 
 	if (requestedScopes.length === 0) {
 		return new Response(renderErrorPage("No valid scopes requested."), {
@@ -205,6 +208,21 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		const v = formData.get(name);
 		return typeof v === "string" ? v : fallback;
 	};
+	const requestedScopes = new Set(
+		(new URL(request.url).searchParams.get("scope") ?? "")
+			.split(" ")
+			.filter(Boolean)
+			.filter(isValidScope),
+	);
+	const selectedScopes = [
+		...new Set(
+			formData
+				.getAll("scope")
+				.filter((value): value is string => typeof value === "string")
+				.filter(isValidScope)
+				.filter((scope) => requestedScopes.has(scope)),
+		),
+	];
 
 	// SEC-18: Validate CSRF token (double-submit cookie pattern).
 	// The form includes a hidden csrf_token field; the cookie has the same value.
@@ -289,7 +307,7 @@ export const POST: APIRoute = async ({ request, locals }) => {
 		response_type: field("response_type", "code"),
 		client_id: field("client_id"),
 		redirect_uri: redirectUri,
-		scope: field("scope"),
+		scope: selectedScopes.join(" "),
 		state,
 		code_challenge: field("code_challenge"),
 		code_challenge_method: field("code_challenge_method", "S256"),
@@ -298,12 +316,16 @@ export const POST: APIRoute = async ({ request, locals }) => {
 
 	if (!result.success) {
 		const errMsg = result.error?.message ?? "Authorization failed";
+		const invalidScope = result.error?.code === "INVALID_SCOPE";
 		// On error, redirect back with error params — use generic description to avoid
 		// leaking internal error details to the (already-validated) redirect target
 		try {
 			const errorUrl = new URL(redirectUri);
-			errorUrl.searchParams.set("error", "server_error");
-			errorUrl.searchParams.set("error_description", "Authorization failed");
+			errorUrl.searchParams.set("error", invalidScope ? "invalid_scope" : "server_error");
+			errorUrl.searchParams.set(
+				"error_description",
+				invalidScope ? "No selected permission can be granted" : "Authorization failed",
+			);
 			if (state) errorUrl.searchParams.set("state", state);
 			return Response.redirect(errorUrl.toString(), 302);
 		} catch {
@@ -335,8 +357,8 @@ function renderConsentPage(params: {
 }): string {
 	const scopeList = params.scopes
 		.map((s) => {
-			const label = SCOPE_LABELS[s] ?? s;
-			return `<li>${escapeHtml(label)}</li>`;
+			const label = SCOPE_LABELS[s] ?? getPluginScopeLabel(s) ?? s;
+			return `<li><label><input type="checkbox" name="scope" value="${escapeHtml(s)}" checked><span>${escapeHtml(label)}</span></label></li>`;
 		})
 		.join("\n");
 
@@ -357,6 +379,8 @@ function renderConsentPage(params: {
   ul { list-style: none; margin-bottom: 1.5rem; }
   li { padding: 0.5rem 0; border-bottom: 1px solid #262626; font-size: 0.875rem; }
   li:last-child { border-bottom: none; }
+  label { display: flex; align-items: flex-start; gap: 0.625rem; cursor: pointer; }
+  input[type="checkbox"] { margin-top: 0.125rem; accent-color: #2563eb; }
   .actions { display: flex; gap: 0.75rem; }
   button { flex: 1; padding: 0.625rem 1rem; border-radius: 8px; border: none; font-size: 0.875rem; font-weight: 500; cursor: pointer; }
   .approve { background: #2563eb; color: white; }
@@ -370,14 +394,13 @@ function renderConsentPage(params: {
   <h1>Authorize Application</h1>
   <p class="client-id">${escapeHtml(params.clientId)}</p>
   <p class="user">Signed in as <strong>${escapeHtml(params.userName)}</strong></p>
-  <h2>Permissions requested</h2>
-  <ul>${scopeList}</ul>
   <form method="POST">
+    <h2>Permissions requested</h2>
+    <ul>${scopeList}</ul>
     <input type="hidden" name="csrf_token" value="${escapeHtml(params.csrfToken)}">
     <input type="hidden" name="response_type" value="${escapeHtml(params.responseType)}">
     <input type="hidden" name="client_id" value="${escapeHtml(params.clientId)}">
     <input type="hidden" name="redirect_uri" value="${escapeHtml(params.redirectUri)}">
-    <input type="hidden" name="scope" value="${escapeHtml(params.scopes.join(" "))}">
     <input type="hidden" name="state" value="${escapeHtml(params.state)}">
     <input type="hidden" name="code_challenge" value="${escapeHtml(params.codeChallenge)}">
     <input type="hidden" name="code_challenge_method" value="${escapeHtml(params.codeChallengeMethod)}">
@@ -392,6 +415,11 @@ function renderConsentPage(params: {
 </html>`;
 }
 
+function getPluginScopeLabel(scope: string): string | null {
+	const pluginId = scope.startsWith("mcp:tools:") ? scope.slice("mcp:tools:".length) : "";
+	return pluginId ? `Use MCP tools from ${pluginId}` : null;
+}
+
 function renderErrorPage(message: string): string {
 	return `<!DOCTYPE html>
 <html lang="en">

package/src/astro/routes/api/plugins/[pluginId]/[...path].ts

@@ -9,6 +9,7 @@
  * Private routes (the default) require authentication and appropriate permissions.
  */
 
+import { Permissions, type Permission } from "@emdash-cms/auth";
 import type { APIRoute } from "astro";
 
 import { requirePerm } from "#api/authorize.js";
@@ -47,8 +48,13 @@ const handleRequest: APIRoute = async ({ params, request, locals }) => {
 		// since HEAD is CORS-safe) invoke a mutating admin route by choosing the
 		// method (#1853). Astro also dispatches HEAD to the GET export, so no
 		// explicit HEAD handler is needed to reach a "GET" route. Gate every
-		// private invocation on `plugins:manage` + CSRF regardless of method.
-		const denied = requirePerm(user, "plugins:manage");
+		// private invocation on the route's declared permission (defaulting to
+		// `plugins:manage`) + CSRF regardless of method.
+		const permission = routeMeta.permission ?? "plugins:manage";
+		if (!(permission in Permissions)) {
+			return apiError("INVALID_PLUGIN_ROUTE", "Plugin route declares an invalid permission", 500);
+		}
+		const denied = requirePerm(user, permission as Permission);
 		if (denied) return denied;
 
 		// Token scope enforcement — plugin routes require "admin" scope.
@@ -83,7 +89,15 @@ const handleRequest: APIRoute = async ({ params, request, locals }) => {
 		return apiError(code, message, status);
 	}
 
-	return apiSuccess(result.data);
+	const response = apiSuccess(result.data);
+	// Public routes may opt in to CDN/browser caching for GET responses.
+	// getRouteMeta only ever exposes cacheControl on public routes, and errors
+	// above keep the default private, no-store. Astro serves HEAD via this GET
+	// export, which is fine: same headers, no body.
+	if (routeMeta.cacheControl && (method === "GET" || method === "HEAD")) {
+		response.headers.set("Cache-Control", routeMeta.cacheControl);
+	}
+	return response;
 };
 
 // Export handlers for all HTTP methods

package/src/astro/routes/api/settings/backups/archives/[name].ts

@@ -0,0 +1,78 @@
+/**
+ * Backup archives — download / delete
+ *
+ * GET    /_emdash/api/settings/backups/archives/:name — download an archive.
+ * DELETE /_emdash/api/settings/backups/archives/:name — delete an archive.
+ *
+ * `name` is validated against the strict archive-filename pattern before it
+ * touches a storage key, so path traversal into other prefixes is impossible.
+ */
+
+import type { APIRoute } from "astro";
+
+import { requirePerm } from "#api/authorize.js";
+import { apiError, handleError, unwrapResult } from "#api/error.js";
+import { ErrorCode } from "#api/errors.js";
+import {
+	BACKUP_STORAGE_PREFIX,
+	deleteBackupArchive,
+	isValidArchiveName,
+} from "#api/handlers/backup.js";
+
+export const prerender = false;
+
+export const GET: APIRoute = async ({ params, locals }) => {
+	const { emdash, user } = locals;
+	const name = params.name ?? "";
+
+	if (!emdash?.db) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
+
+	const denied = requirePerm(user, "backups:manage");
+	if (denied) return denied;
+
+	if (!emdash.storage) {
+		return apiError("STORAGE_NOT_CONFIGURED", "No storage backend is configured", 503);
+	}
+
+	if (!isValidArchiveName(name)) {
+		return apiError("VALIDATION_ERROR", "Invalid archive name", 400);
+	}
+
+	try {
+		const result = await emdash.storage.download(`${BACKUP_STORAGE_PREFIX}${name}`);
+		return new Response(result.body, {
+			status: 200,
+			headers: {
+				"Content-Type": "application/json",
+				"Content-Disposition": `attachment; filename="${name}"`,
+				"Cache-Control": "private, no-store",
+				"X-Content-Type-Options": "nosniff",
+			},
+		});
+	} catch (error) {
+		if (error instanceof Error && error.message.toLowerCase().includes("not found")) {
+			return apiError("NOT_FOUND", "Archive not found", 404);
+		}
+		return handleError(error, "Failed to download archive", ErrorCode.BACKUP_DOWNLOAD_ERROR);
+	}
+};
+
+export const DELETE: APIRoute = async ({ params, locals }) => {
+	const { emdash, user } = locals;
+	const name = params.name ?? "";
+
+	if (!emdash?.db) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
+
+	const denied = requirePerm(user, "backups:manage");
+	if (denied) return denied;
+
+	if (!emdash.storage) {
+		return apiError("STORAGE_NOT_CONFIGURED", "No storage backend is configured", 503);
+	}
+
+	return unwrapResult(await deleteBackupArchive(emdash.storage, name));
+};