emdash 0.36.0 → 0.37.0

package/src/astro/image-endpoint.ts

@@ -15,8 +15,8 @@ import { GET as genericGET } from "astro/assets/endpoint/generic";
 import { getConfiguredImageService, imageConfig } from "astro:assets";
 
 import {
-	IMMUTABLE_IMAGE_CACHE,
 	matchInternalMediaKey,
+	MUTABLE_MEDIA_CACHE_CONTROL,
 	originalMediaHeaders,
 } from "../media/image-endpoint.js";
 
@@ -72,7 +72,7 @@ export const GET: APIRoute = async (ctx) => {
 			status: 200,
 			headers: {
 				"Content-Type": FORMAT_MIME[format] ?? source.contentType,
-				"Cache-Control": IMMUTABLE_IMAGE_CACHE,
+				"Cache-Control": MUTABLE_MEDIA_CACHE_CONTROL,
 				"X-Content-Type-Options": "nosniff",
 			},
 		});

package/src/astro/integration/dev-typegen.ts

@@ -0,0 +1,91 @@
+import type { AstroIntegrationLogger } from "astro";
+
+/**
+ * Create a debounced refresh function that fetches the generated types from
+ * the dev server and writes them to `emdash-env.d.ts` in the project root.
+ *
+ * This runs in the Astro integration (Node) and is registered for schema
+ * mutations to call back into. It never runs in production builds or in
+ * workerd SSR isolates, because only the integration registers it.
+ */
+export function createDebouncedTypegenRefresh(
+	port: number,
+	logger: AstroIntegrationLogger,
+): () => void {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let inFlight: Promise<unknown> | undefined;
+
+	function refresh(): void {
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(() => {
+			timer = undefined;
+			if (inFlight) return;
+			inFlight = writeDevTypes(port, logger).finally(() => {
+				inFlight = undefined;
+			});
+		}, 200);
+	}
+
+	return refresh;
+}
+
+async function writeDevTypes(port: number, logger: AstroIntegrationLogger): Promise<void> {
+	const typegenUrl = `http://localhost:${port}/_emdash/api/typegen`;
+
+	try {
+		const { writeFile, readFile } = await import("node:fs/promises");
+		const { resolve } = await import("node:path");
+		const outputPath = resolve(process.cwd(), "emdash-env.d.ts");
+
+		const response = await fetch(typegenUrl, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+		});
+
+		if (!response.ok) {
+			const body = await response.text().catch(() => "");
+			logger.warn(`Typegen failed: ${response.status} ${body.slice(0, 200)}`);
+			return;
+		}
+
+		const json = await response.json();
+		if (typeof json !== "object" || json === null || !("data" in json)) {
+			logger.warn("Typegen returned an unexpected response shape");
+			return;
+		}
+
+		const result = json.data;
+		if (
+			typeof result !== "object" ||
+			result === null ||
+			!("types" in result) ||
+			!("collections" in result)
+		) {
+			logger.warn("Typegen returned an unexpected response shape");
+			return;
+		}
+
+		const types = result.types;
+		const collections = result.collections;
+		if (typeof types !== "string" || typeof collections !== "number") {
+			logger.warn("Typegen returned an unexpected response shape");
+			return;
+		}
+
+		let needsWrite = true;
+		try {
+			const existing = await readFile(outputPath, "utf-8");
+			if (existing === types) needsWrite = false;
+		} catch {
+			// File doesn't exist yet
+		}
+
+		if (needsWrite) {
+			await writeFile(outputPath, types, "utf-8");
+			logger.info(`Generated emdash-env.d.ts (${collections} collections)`);
+		}
+	} catch (error) {
+		const msg = error instanceof Error ? error.message : String(error);
+		logger.warn(`Typegen failed: ${msg}`);
+	}
+}

package/src/astro/integration/index.ts

@@ -28,7 +28,9 @@ import { buildMigrationManifest } from "../../migrations/manifest-builder.js";
 import { writeMigrationManifest } from "../../migrations/manifest-writer.js";
 import type { ResolvedPlugin } from "../../plugins/types.js";
 import { VERSION } from "../../version.js";
+import { setDevTypegenRefresh } from "../dev-typegen.js";
 import { local } from "../storage/adapters.js";
+import { createDebouncedTypegenRefresh } from "./dev-typegen.js";
 import { notoSans } from "./font-provider.js";
 import {
 	injectCoreRoutes,
@@ -651,57 +653,20 @@ export function emdash(config: EmDashConfig = {}): AstroIntegration {
 					});
 				}
 
-				// Generate types once the server is listening.
+				// Generate types once the server is listening, and register the
+				// refresh hook so schema mutations in dev update the file too.
 				// The endpoint returns the types content; we write the file here
 				// (in Node) because workerd has no real filesystem access.
-				server.httpServer?.once("listening", async () => {
-					const { writeFile, readFile } = await import("node:fs/promises");
-					const { resolve } = await import("node:path");
-
+				server.httpServer?.once("listening", () => {
 					const address = server.httpServer?.address();
 					if (!address || typeof address === "string") return;
 
 					const port = address.port;
-					const typegenUrl = `http://localhost:${port}/_emdash/api/typegen`;
-					const outputPath = resolve(process.cwd(), "emdash-env.d.ts");
-
-					try {
-						const response = await fetch(typegenUrl, {
-							method: "POST",
-							headers: { "Content-Type": "application/json" },
-						});
-
-						if (!response.ok) {
-							const body = await response.text().catch(() => "");
-							logger.warn(`Typegen failed: ${response.status} ${body.slice(0, 200)}`);
-							return;
-						}
+					const refreshDevTypes = createDebouncedTypegenRefresh(port, logger);
+					setDevTypegenRefresh(refreshDevTypes);
 
-						const { data: result } = (await response.json()) as {
-							data: {
-								types: string;
-								hash: string;
-								collections: number;
-							};
-						};
-
-						// Only write if content changed
-						let needsWrite = true;
-						try {
-							const existing = await readFile(outputPath, "utf-8");
-							if (existing === result.types) needsWrite = false;
-						} catch {
-							// File doesn't exist yet
-						}
-
-						if (needsWrite) {
-							await writeFile(outputPath, result.types, "utf-8");
-							logger.info(`Generated emdash-env.d.ts (${result.collections} collections)`);
-						}
-					} catch (error) {
-						const msg = error instanceof Error ? error.message : String(error);
-						logger.warn(`Typegen failed: ${msg}`);
-					}
+					// Initial generation now that the server is up.
+					refreshDevTypes();
 				});
 			},
 			"astro:build:done": ({ logger }) => {

package/src/astro/integration/routes.ts

@@ -238,6 +238,11 @@ export function injectCoreRoutes(
 		entrypoint: resolveRoute("api/media/[id]/upload.ts"),
 	});
 
+	injectRoute({
+		pattern: "/_emdash/api/media/[id]/replace",
+		entrypoint: resolveRoute("api/media/[id]/replace.ts"),
+	});
+
 	// Media provider routes
 	injectRoute({
 		pattern: "/_emdash/api/media/providers",

package/src/astro/integration/vite-config.ts

@@ -372,6 +372,15 @@ function isCloudflareAdapter(astroConfig: AstroConfig): boolean {
 	return astroConfig.adapter?.name === "@astrojs/cloudflare";
 }
 
+function canResolveProjectDependency(projectRoot: string, specifier: string): boolean {
+	try {
+		createRequire(resolve(projectRoot, "package.json")).resolve(specifier);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 /**
  * Creates the Vite config update for EmDash.
  */
@@ -383,6 +392,7 @@ export function createViteConfig(
 	const cloudflare = isCloudflareAdapter(options.astroConfig);
 	const isDev = command === "dev";
 	const projectRoot = fileURLToPath(options.astroConfig.root);
+	const hasAstroConsoleLogger = canResolveProjectDependency(projectRoot, "astro/logger/console");
 
 	const adminSourcePath = isDev ? resolveAdminSource(projectRoot) : undefined;
 	const useSource = adminSourcePath !== undefined;
@@ -541,6 +551,7 @@ export function createViteConfig(
 							"@emdash-cms/cloudflare > kysely-d1",
 							// Astro internal deps not covered by @astrojs/cloudflare adapter
 							"astro/app/manifest",
+							...(hasAstroConsoleLogger ? ["astro/logger/console"] : []),
 							"astro/virtual-modules/middleware.js",
 							"astro/virtual-modules/live-config",
 							"astro/content/runtime",
@@ -561,9 +572,17 @@ export function createViteConfig(
 		optimizeDeps: {
 			// When using source, don't pre-bundle JS — let Vite transform on the fly for HMR.
 			// When using dist, pre-bundle to avoid re-optimization on first hydration.
+			// lowlight pulls in a CommonJS highlight.js entry, so the inline Portable
+			// Text editor requires these to be pre-bundled with ESM interop in dev.
 			include: useSource
-				? ["@astrojs/react/client.js"]
-				: ["@emdash-cms/admin", "@astrojs/react/client.js"],
+				? ["@astrojs/react/client.js", "lowlight", "highlight.js", "highlight.js/lib/core"]
+				: [
+						"@emdash-cms/admin",
+						"@astrojs/react/client.js",
+						"lowlight",
+						"highlight.js",
+						"highlight.js/lib/core",
+					],
 			exclude: cloudflare ? ["virtual:emdash"] : [...NODE_NATIVE_EXTERNALS, "virtual:emdash"],
 		},
 	};

package/src/astro/middleware.ts

@@ -909,6 +909,11 @@ export const onRequest = defineMiddleware(async (context, next) => {
 					handleMediaGet: runtime.handleMediaGet.bind(runtime),
 					handleMediaCreate: runtime.handleMediaCreate.bind(runtime),
 					handleMediaUpdate: runtime.handleMediaUpdate.bind(runtime),
+					...(runtime.handleMediaReplaceMetadata
+						? {
+								handleMediaReplaceMetadata: runtime.handleMediaReplaceMetadata.bind(runtime),
+							}
+						: {}),
 					handleMediaDelete: runtime.handleMediaDelete.bind(runtime),
 
 					// Revision handlers

package/src/astro/routes/api/admin/api-tokens/index.ts

@@ -19,7 +19,10 @@ export const prerender = false;
 const createTokenSchema = z.object({
 	name: z.string().min(1).max(100),
 	scopes: z.array(z.string().refine(isValidScope)).min(1),
-	expiresAt: z.string().datetime().optional(),
+	expiresAt: z.iso
+		.datetime()
+		.or(z.iso.datetime({ precision: -1 }))
+		.optional(),
 });
 
 /**

package/src/astro/routes/api/admin/oauth-clients/[id].ts

@@ -23,7 +23,7 @@ export const prerender = false;
 const updateClientSchema = z.object({
 	name: z.string().min(1).max(255).optional(),
 	redirectUris: z
-		.array(z.string().url("Each redirect URI must be a valid URL"))
+		.array(z.url("Each redirect URI must be a valid URL"))
 		.min(1, "At least one redirect URI is required")
 		.optional(),
 	scopes: z.array(z.string()).nullable().optional(),

package/src/astro/routes/api/admin/oauth-clients/index.ts

@@ -22,7 +22,7 @@ const createClientSchema = z.object({
 		.max(255, "Client ID must be at most 255 characters"),
 	name: z.string().min(1, "Name is required").max(255, "Name must be at most 255 characters"),
 	redirectUris: z
-		.array(z.string().url("Each redirect URI must be a valid URL"))
+		.array(z.url("Each redirect URI must be a valid URL"))
 		.min(1, "At least one redirect URI is required"),
 	scopes: z.array(z.string()).optional(),
 });

package/src/astro/routes/api/admin/plugins/registry/[id]/update.ts

@@ -38,6 +38,8 @@ const updateBodySchema = z.object({
 	 */
 	confirmRouteVisibilityChanges: z.boolean().optional(),
 	confirmMcpTools: z.boolean().optional(),
+	acknowledgedProfileCid: z.string().min(1).max(256).optional(),
+	acknowledgedReleaseCid: z.string().min(1).max(256).optional(),
 });
 
 export const POST: APIRoute = async ({ params, request, locals }) => {
@@ -73,6 +75,8 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 				confirmCapabilityChanges: body.confirmCapabilityChanges,
 				confirmRouteVisibilityChanges: body.confirmRouteVisibilityChanges,
 				confirmMcpTools: body.confirmMcpTools,
+				acknowledgedProfileCid: body.acknowledgedProfileCid,
+				acknowledgedReleaseCid: body.acknowledgedReleaseCid,
 				hostEnv: hostEnvFromVersions(VERSION, emdash.config.astroVersion),
 			},
 		);

package/src/astro/routes/api/admin/plugins/registry/artifact.ts

@@ -35,8 +35,8 @@ import type { APIRoute } from "astro";
 
 import { requirePerm } from "#api/authorize.js";
 import { apiError } from "#api/error.js";
-import { verifyChecksum } from "#api/handlers/registry.js";
 
+import { verifyRegistryArtifactChecksum } from "../../../../../../registry/artifact-checksum.js";
 import { fetchRegistryArtifactUrl } from "../../../../../../registry/artifact-fetch.js";
 import { coerceRegistryConfig, validateAggregatorUrl } from "../../../../../../registry/config.js";
 import { resolveAndValidateExternalUrlTarget } from "../../../../../../security/ssrf.js";
@@ -453,11 +453,7 @@ function recordScopedCacheEndpoint(value: unknown): string | null {
 	return typeof endpoint === "string" ? endpoint : null;
 }
 
-/**
- * Read a response body into memory, aborting once it exceeds `limit`. Returns
- * `null` when the cap is breached (the streamed body lied about / omitted
- * Content-Length). The cap is the real defence against an unbounded body.
- */
+/** Build bounded, SSRF-validated fetch options for cache, PDS, and URL sources. */
 function proxyFetchOptions(signal: AbortSignal) {
 	return {
 		fetch: async (url: URL, init: RequestInit) =>
@@ -504,7 +500,7 @@ async function fetchRawArtifact(
 			lastCode = fetched.error.code;
 			continue;
 		}
-		if (!(await verifyChecksum(fetched.value.bytes, resolved.artifact.checksum))) {
+		if (!(await verifyRegistryArtifactChecksum(fetched.value.bytes, resolved.artifact.checksum))) {
 			lastCode = "CHECKSUM_MISMATCH";
 			checksumMismatch = { bytes: fetched.value.bytes, headers: fetched.value.headers };
 			continue;

package/src/astro/routes/api/admin/plugins/registry/install.ts

@@ -59,6 +59,8 @@ const installBodySchema = z.object({
 	 */
 	acknowledgedDeclaredAccess: z.unknown().optional(),
 	acknowledgedMcpTools: z.unknown().optional(),
+	acknowledgedProfileCid: z.string().min(1).max(256).optional(),
+	acknowledgedReleaseCid: z.string().min(1).max(256).optional(),
 });
 
 export const POST: APIRoute = async ({ request, locals }) => {
@@ -99,6 +101,8 @@ export const POST: APIRoute = async ({ request, locals }) => {
 				version: body.version,
 				acknowledgedDeclaredAccess: body.acknowledgedDeclaredAccess,
 				acknowledgedMcpTools: body.acknowledgedMcpTools,
+				acknowledgedProfileCid: body.acknowledgedProfileCid,
+				acknowledgedReleaseCid: body.acknowledgedReleaseCid,
 			},
 			{
 				configuredPluginIds: reservedPluginIds,

package/src/astro/routes/api/admin/plugins/registry/verify.ts

@@ -0,0 +1,60 @@
+import { hostEnvFromVersions } from "@emdash-cms/registry-client/env";
+import type { APIRoute } from "astro";
+import { z } from "zod";
+
+import { requirePerm } from "#api/authorize.js";
+import { apiError, handleError, unwrapResult } from "#api/error.js";
+import { handleRegistryInstall } from "#api/index.js";
+import { isParseError, parseBody } from "#api/parse.js";
+
+import { VERSION } from "../../../../../../version.js";
+
+export const prerender = false;
+
+const verifyBodySchema = z.object({
+	did: z
+		.string()
+		.min(1)
+		.max(2048)
+		.regex(/^did:[a-z]+:/, "Invalid DID"),
+	slug: z
+		.string()
+		.min(1)
+		.max(64)
+		.regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/, "Invalid slug"),
+	version: z.string().min(1).max(64).optional(),
+});
+
+export const POST: APIRoute = async ({ request, locals }) => {
+	try {
+		const { emdash, user } = locals;
+		if (!emdash?.db) {
+			return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+		}
+		const denied = requirePerm(user, "plugins:manage");
+		if (denied) return denied;
+		const body = await parseBody(request, verifyBodySchema);
+		if (isParseError(body)) return body;
+
+		const reservedPluginIds = new Set<string>([
+			...emdash.configuredPlugins.map((plugin: { id: string }) => plugin.id),
+			...(emdash.config.sandboxed ?? []).map((plugin: { id: string }) => plugin.id),
+		]);
+		const result = await handleRegistryInstall(
+			emdash.db,
+			emdash.storage,
+			emdash.getSandboxRunner(),
+			emdash.config.experimental?.registry,
+			body,
+			{
+				configuredPluginIds: reservedPluginIds,
+				hostEnv: hostEnvFromVersions(VERSION, emdash.config.astroVersion),
+				verifyOnly: true,
+			},
+		);
+		return unwrapResult(result);
+	} catch (error) {
+		console.error("[registry-verify] Unhandled error:", error);
+		return handleError(error, "Failed to verify registry plugin", "VERIFICATION_FAILED");
+	}
+};

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

@@ -8,10 +8,12 @@ import type { APIRoute } from "astro";
 
 import { requireOwnerPerm } from "#api/authorize.js";
 import { apiError, mapErrorStatus, unwrapResult } from "#api/error.js";
+import { isParseError, parseOptionalBody } from "#api/parse.js";
+import { contentRevisionConditionBody } from "#api/schemas.js";
 
 export const prerender = false;
 
-export const POST: APIRoute = async ({ params, locals, url, cache }) => {
+export const POST: APIRoute = async ({ params, request, locals, url, cache }) => {
 	const { emdash, user } = locals;
 	const collection = params.collection!;
 	const id = params.id!;
@@ -19,6 +21,8 @@ export const POST: APIRoute = async ({ params, locals, url, cache }) => {
 	if (!emdash?.handleContentDiscardDraft || !emdash?.handleContentGet) {
 		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
 	}
+	const body = await parseOptionalBody(request, contentRevisionConditionBody, {});
+	if (isParseError(body)) return body;
 
 	const locale = url.searchParams.get("locale") || undefined;
 
@@ -48,7 +52,9 @@ export const POST: APIRoute = async ({ params, locals, url, cache }) => {
 
 	const resolvedId = typeof existingItem?.id === "string" ? existingItem.id : id;
 
-	const result = await emdash.handleContentDiscardDraft(collection, resolvedId);
+	const result = await emdash.handleContentDiscardDraft(collection, resolvedId, {
+		_rev: body?._rev,
+	});
 
 	if (!result.success) return unwrapResult(result);
 

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

@@ -3,7 +3,7 @@
  *
  * POST /_emdash/api/content/{collection}/{id}/publish
  *
- * Optional JSON body: { publishedAt?: string }
+ * Optional JSON body: { publishedAt?: string, _rev?: string }
  *   publishedAt — ISO 8601 datetime to backdate the publish (e.g. when
  *   migrating content). Writing publishedAt requires content:publish_any.
  *   Without it, the existing published_at is preserved on re-publish and
@@ -78,6 +78,7 @@ export const POST: APIRoute = async ({ params, request, locals, url, cache }) =>
 
 	const result = await emdash.handleContentPublish(collection, resolvedId, {
 		publishedAt,
+		_rev: body?._rev,
 	});
 
 	if (!result.success) return unwrapResult(result);

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

@@ -8,10 +8,12 @@ import type { APIRoute } from "astro";
 
 import { requireOwnerPerm } from "#api/authorize.js";
 import { apiError, mapErrorStatus, unwrapResult } from "#api/error.js";
+import { isParseError, parseOptionalBody } from "#api/parse.js";
+import { contentRevisionConditionBody } from "#api/schemas.js";
 
 export const prerender = false;
 
-export const POST: APIRoute = async ({ params, locals, url, cache }) => {
+export const POST: APIRoute = async ({ params, request, locals, url, cache }) => {
 	const { emdash, user } = locals;
 	const collection = params.collection!;
 	const id = params.id!;
@@ -19,6 +21,8 @@ export const POST: APIRoute = async ({ params, locals, url, cache }) => {
 	if (!emdash?.handleContentUnpublish || !emdash?.handleContentGet) {
 		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
 	}
+	const body = await parseOptionalBody(request, contentRevisionConditionBody, {});
+	if (isParseError(body)) return body;
 
 	const locale = url.searchParams.get("locale") || undefined;
 
@@ -48,7 +52,7 @@ export const POST: APIRoute = async ({ params, locals, url, cache }) => {
 
 	const resolvedId = typeof existingItem?.id === "string" ? existingItem.id : id;
 
-	const result = await emdash.handleContentUnpublish(collection, resolvedId);
+	const result = await emdash.handleContentUnpublish(collection, resolvedId, { _rev: body?._rev });
 
 	if (!result.success) return unwrapResult(result);
 

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

@@ -4,7 +4,7 @@
  * GET /_emdash/api/manifest
  *
  * Returns the admin manifest with collection definitions and plugin info.
- * The manifest is generated from the user's live.config.ts at runtime.
+ * The manifest is generated from live database schema plus runtime plugin state.
  */
 
 import type { APIRoute } from "astro";

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

@@ -0,0 +1,114 @@
+import type { APIRoute } from "astro";
+
+import { requireOwnerPerm, requirePerm } from "#api/authorize.js";
+import { apiError, apiSuccess, handleError, unwrapResult } from "#api/error.js";
+import { DEFAULT_MAX_UPLOAD_SIZE, mediaReplaceMetadataForm } from "#api/schemas.js";
+import { MUTABLE_MEDIA_CACHE_CONTROL } from "#media/image-endpoint.js";
+import { normalizeMime } from "#media/mime.js";
+import { computeContentHash } from "#utils/hash.js";
+
+export const prerender = false;
+
+const REPLACEABLE_IMAGE_TYPES = new Set(["image/jpeg", "image/png", "image/webp"]);
+
+export const PUT: APIRoute = async ({ params, request, locals }) => {
+	const { emdash, user } = locals;
+	const { id } = params;
+
+	const editDenied = requirePerm(user, "media:edit_own");
+	if (editDenied) return editDenied;
+	if (!id) return apiError("INVALID_REQUEST", "Media ID required", 400);
+	if (!emdash?.handleMediaGet || !emdash?.handleMediaReplaceMetadata) {
+		return apiError("NOT_CONFIGURED", "EmDash is not initialized", 500);
+	}
+	if (!emdash.storage) return apiError("NO_STORAGE", "Storage not configured", 500);
+
+	const getResult = await emdash.handleMediaGet(id);
+	if (!getResult.success) return unwrapResult(getResult);
+	const media = getResult.data.item;
+	const ownerDenied = requireOwnerPerm(
+		user,
+		media.authorId ?? "",
+		"media:edit_own",
+		"media:edit_any",
+	);
+	if (ownerDenied) return ownerDenied;
+	if (media.status !== "ready") {
+		return apiError("INVALID_STATE", "Only ready media can be replaced", 400);
+	}
+
+	const sourceMime = normalizeMime(media.mimeType);
+	if (!REPLACEABLE_IMAGE_TYPES.has(sourceMime)) {
+		return apiError("INVALID_TYPE", "Media type cannot be replaced", 400);
+	}
+
+	const rawMax = emdash.config.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE;
+	if (!Number.isFinite(rawMax) || rawMax <= 0) {
+		return apiError("CONFIGURATION_ERROR", "Invalid maxUploadSize configuration", 500);
+	}
+	const maxUploadSize = rawMax;
+	const contentLength = request.headers.get("Content-Length");
+	if (contentLength && parseInt(contentLength, 10) > maxUploadSize) {
+		return apiError("PAYLOAD_TOO_LARGE", "Upload too large", 413);
+	}
+
+	try {
+		const formData = await request.formData();
+		const fileEntry = formData.get("file");
+		const file = fileEntry instanceof File ? fileEntry : null;
+		if (!file) return apiError("NO_FILE", "No file provided", 400);
+		if (file.size === 0) return apiError("VALIDATION_ERROR", "Replacement file is empty", 400);
+		if (file.size > maxUploadSize) {
+			return apiError("PAYLOAD_TOO_LARGE", "Upload too large", 413);
+		}
+
+		const replacementMime = normalizeMime(file.type);
+		if (!REPLACEABLE_IMAGE_TYPES.has(replacementMime) || replacementMime !== sourceMime) {
+			return apiError("INVALID_TYPE", "Replacement file type must match the media item", 400);
+		}
+
+		const metadataResult = mediaReplaceMetadataForm.safeParse({
+			width: formData.get("width"),
+			height: formData.get("height"),
+		});
+		if (!metadataResult.success) {
+			return apiError("VALIDATION_ERROR", "Invalid request data", 400, {
+				issues: metadataResult.error.issues.map((issue) => ({
+					path: issue.path.join("."),
+					message: issue.message,
+				})),
+			});
+		}
+		const { width, height } = metadataResult.data;
+
+		const bytes = new Uint8Array(await file.arrayBuffer());
+		const contentHash = await computeContentHash(bytes);
+		try {
+			await emdash.storage.upload({
+				key: media.storageKey,
+				body: bytes,
+				contentType: sourceMime,
+				cacheControl: MUTABLE_MEDIA_CACHE_CONTROL,
+			});
+		} catch (error) {
+			return handleError(error, "Failed to replace media", "MEDIA_REPLACE_ERROR");
+		}
+
+		const result = await emdash.handleMediaReplaceMetadata(id, media.storageKey, {
+			size: file.size,
+			width,
+			height,
+			contentHash,
+		});
+		if (!result.success) return unwrapResult(result);
+
+		return apiSuccess({
+			item: {
+				...result.data.item,
+				url: `/_emdash/api/media/file/${result.data.item.storageKey}`,
+			},
+		});
+	} catch (error) {
+		return handleError(error, "Failed to replace media", "MEDIA_REPLACE_ERROR");
+	}
+};

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

@@ -7,6 +7,7 @@
 import type { APIRoute } from "astro";
 
 import { apiError, handleError } from "#api/error.js";
+import { IMMUTABLE_IMAGE_CACHE, MUTABLE_MEDIA_CACHE_CONTROL } from "#media/image-endpoint.js";
 
 export const prerender = false;
 
@@ -53,7 +54,9 @@ export const GET: APIRoute = async ({ params, locals }) => {
 
 		const headers: Record<string, string> = {
 			"Content-Type": result.contentType,
-			"Cache-Control": "public, max-age=31536000, immutable",
+			"Cache-Control": result.contentType.startsWith("image/")
+				? MUTABLE_MEDIA_CACHE_CONTROL
+				: IMMUTABLE_IMAGE_CACHE,
 			"X-Content-Type-Options": "nosniff",
 			// Sandbox CSP on all user-uploaded content — prevents script execution
 			// even for SVGs navigated to directly or content types that support scripting.