feat(media): binding-based image transforms for same-origin media (Access-safe)

.changeset/image-transform-binding.md

@@ -0,0 +1,21 @@
+---
+"emdash": minor
+"@emdash-cms/cloudflare": minor
+---
+
+Adds a binding-based image transform service so responsive images work behind Cloudflare Access.
+
+Previously, resizing R2/local media routed through Astro's `/_image` endpoint, which made the server fetch the media's own URL to load the source bytes — a self-referential request that fails when the site is behind Cloudflare Access or has loopback fetches disabled, surfacing as 404s on transformed images. EmDash now serves transforms from `/_emdash/api/media/transform/{key}`, reading bytes straight from the storage adapter and resizing them with a configured transformer, so no server-side fetch of the media URL is made.
+
+To enable it on Cloudflare, add an `IMAGES` binding to your wrangler config and wire it up:
+
+```ts
+import { imageBinding } from "@emdash-cms/cloudflare";
+
+emdash({
+	storage: r2({ binding: "MEDIA" }),
+	images: imageBinding({ binding: "IMAGES" }),
+});
+```
+
+When `images` is not configured, behavior is unchanged.

packages/cloudflare/package.json

@@ -57,6 +57,10 @@
       "types": "./dist/media/stream-runtime.d.mts",
       "default": "./dist/media/stream-runtime.mjs"
     },
+    "./media/transform-runtime": {
+      "types": "./dist/media/transform-runtime.d.mts",
+      "default": "./dist/media/transform-runtime.mjs"
+    },
     "./cache": {
       "types": "./dist/cache/runtime.d.mts",
       "default": "./dist/cache/runtime.mjs"

packages/cloudflare/src/index.ts

@@ -33,7 +33,12 @@
  * ```
  */
 
-import type { AuthDescriptor, DatabaseDescriptor, StorageDescriptor } from "emdash";
+import type {
+	AuthDescriptor,
+	DatabaseDescriptor,
+	ImageServiceDescriptor,
+	StorageDescriptor,
+} from "emdash";
 
 import type { PreviewDOConfig } from "./db/do-types.js";
 
@@ -290,6 +295,48 @@ export function access(config: AccessConfig): AuthDescriptor {
 	};
 }
 
+/**
+ * Cloudflare Images binding configuration.
+ */
+export interface ImageBindingConfig {
+	/**
+	 * Name of the Images binding in wrangler config.
+	 * @default "IMAGES"
+	 */
+	binding?: string;
+}
+
+/**
+ * Cloudflare Images binding adapter for request-time media transforms.
+ *
+ * Wires EmDash's transform route (`/_emdash/api/media/transform/{key}`) to the
+ * Cloudflare `IMAGES` binding. The route reads source bytes straight from the
+ * storage adapter (R2) and resizes them with the binding — there is no
+ * server-side fetch of the media URL, so responsive images work even when the
+ * site is behind Cloudflare Access or loopback fetches are disabled.
+ *
+ * Requires an Images binding in wrangler config:
+ * ```jsonc
+ * { "images": { "binding": "IMAGES" } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { imageBinding } from "@emdash-cms/cloudflare";
+ *
+ * emdash({
+ *   storage: r2({ binding: "MEDIA" }),
+ *   images: imageBinding({ binding: "IMAGES" }),
+ * })
+ * ```
+ */
+export function imageBinding(config: ImageBindingConfig = {}): ImageServiceDescriptor {
+	return {
+		entrypoint: "@emdash-cms/cloudflare/media/transform-runtime",
+		config: { binding: config.binding ?? "IMAGES" },
+	};
+}
+
 /**
  * Cloudflare Worker Loader sandbox adapter
  *

packages/cloudflare/src/media/transform-runtime.ts

@@ -0,0 +1,68 @@
+/**
+ * Cloudflare Images binding — image transformer RUNTIME ENTRY.
+ *
+ * Resizes media source bytes with the Cloudflare `IMAGES` binding. Imported at
+ * runtime via the `images` descriptor (see `imageBinding()`); the EmDash
+ * transform route reads bytes from storage and passes them here, so no public
+ * fetch of the media URL is required.
+ *
+ * This module imports from `cloudflare:workers` to access the binding. Do NOT
+ * import it at config time — use `imageBinding()` from `@emdash-cms/cloudflare`.
+ */
+
+import { env } from "cloudflare:workers";
+import type { CreateImageTransformerFn, ImageTransformFormat, TransformedImage } from "emdash";
+
+/** Map EmDash's short format names to the MIME types the binding expects. */
+const FORMAT_MIME: Record<ImageTransformFormat, ImageOutputOptions["format"]> = {
+	webp: "image/webp",
+	avif: "image/avif",
+	jpeg: "image/jpeg",
+	png: "image/png",
+};
+
+/**
+ * Create the Cloudflare Images binding transformer.
+ *
+ * Resolves the binding by name from the Worker env at request time.
+ */
+export const createImageTransformer: CreateImageTransformerFn = (config) => {
+	const bindingName =
+		typeof config.binding === "string" && config.binding ? config.binding : "IMAGES";
+
+	// env from cloudflare:workers has no index signature, so a cast is needed.
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- Images binding accessed from untyped env object
+	const images = (env as Record<string, unknown>)[bindingName] as ImagesBinding | undefined;
+
+	if (!images) {
+		throw new Error(
+			`Cloudflare Images binding "${bindingName}" not found. ` +
+				`Add it to wrangler.jsonc:\n` +
+				`{\n  "images": {\n    "binding": "${bindingName}"\n  }\n}`,
+		);
+	}
+
+	return {
+		async transform(input, options): Promise<TransformedImage> {
+			const mime = FORMAT_MIME[options.format ?? "webp"] ?? "image/webp";
+
+			const transform: ImageTransform = {};
+			if (options.width) transform.width = options.width;
+			if (options.height) transform.height = options.height;
+
+			const output: ImageOutputOptions = { format: mime };
+			if (options.quality) output.quality = options.quality;
+
+			const result = await images.input(input).transform(transform).output(output);
+			const response = result.response();
+			if (!response.body) {
+				throw new Error("Cloudflare Images transform produced an empty body");
+			}
+
+			return {
+				body: response.body,
+				contentType: response.headers.get("Content-Type") ?? mime,
+			};
+		},
+	};
+};

packages/cloudflare/tsdown.config.ts

@@ -15,6 +15,8 @@ export default defineConfig({
 		// Media provider runtimes
 		"src/media/images-runtime.ts",
 		"src/media/stream-runtime.ts",
+		// Image transform binding runtime
+		"src/media/transform-runtime.ts",
 		// Cache provider
 		"src/cache/runtime.ts",
 		"src/cache/config.ts",

packages/core/src/astro/integration/index.ts

@@ -284,6 +284,7 @@ export function emdash(config: EmDashConfig = {}): AstroIntegration {
 	const serializableConfig: Record<string, unknown> = {
 		database: resolvedConfig.database,
 		storage: resolvedConfig.storage,
+		images: resolvedConfig.images,
 		auth: resolvedConfig.auth,
 		authProviders: resolvedConfig.authProviders,
 		marketplace: resolvedConfig.marketplace,

packages/core/src/astro/integration/routes.ts

@@ -175,6 +175,11 @@ export function injectCoreRoutes(injectRoute: InjectRoute): void {
 		entrypoint: resolveRoute("api/media/file/[...key].ts"),
 	});
 
+	injectRoute({
+		pattern: "/_emdash/api/media/transform/[...key]",
+		entrypoint: resolveRoute("api/media/transform/[...key].ts"),
+	});
+
 	injectRoute({
 		pattern: "/_emdash/api/media/[id]",
 		entrypoint: resolveRoute("api/media/[id].ts"),

packages/core/src/astro/integration/runtime.ts

@@ -9,6 +9,7 @@
 
 import type { AuthDescriptor, AuthProviderDescriptor } from "../../auth/types.js";
 import type { DatabaseDescriptor } from "../../db/adapters.js";
+import type { ImageServiceDescriptor } from "../../media/image-transform.js";
 import type { MediaProviderDescriptor } from "../../media/types.js";
 import type { ResolvedPlugin } from "../../plugins/types.js";
 import type { ExperimentalConfig } from "../../registry/types.js";
@@ -151,6 +152,24 @@ export interface EmDashConfig {
 	 * Storage configuration (for media)
 	 */
 	storage?: StorageDescriptor;
+	/**
+	 * Image transform service (for resizing same-origin media at request time).
+	 *
+	 * Serves binding-based transforms from `/_emdash/api/media/transform/{key}`,
+	 * reading source bytes straight from the storage adapter — no server-side
+	 * fetch of the media URL, so it works behind Cloudflare Access and with
+	 * loopback fetches disabled.
+	 *
+	 * @example
+	 * ```ts
+	 * import { imageBinding } from "@emdash-cms/cloudflare";
+	 *
+	 * emdash({
+	 *   images: imageBinding({ binding: "IMAGES" }),
+	 * })
+	 * ```
+	 */
+	images?: ImageServiceDescriptor;
 	/**
 	 * Trusted plugins to load (run in main isolate)
 	 *

packages/core/src/astro/integration/virtual-modules.ts

@@ -33,6 +33,9 @@ export const RESOLVED_VIRTUAL_DIALECT_ID = "\0" + VIRTUAL_DIALECT_ID;
 export const VIRTUAL_STORAGE_ID = "virtual:emdash/storage";
 export const RESOLVED_VIRTUAL_STORAGE_ID = "\0" + VIRTUAL_STORAGE_ID;
 
+export const VIRTUAL_IMAGES_ID = "virtual:emdash/images";
+export const RESOLVED_VIRTUAL_IMAGES_ID = "\0" + VIRTUAL_IMAGES_ID;
+
 export const VIRTUAL_ADMIN_REGISTRY_ID = "virtual:emdash/admin-registry";
 export const RESOLVED_VIRTUAL_ADMIN_REGISTRY_ID = "\0" + VIRTUAL_ADMIN_REGISTRY_ID;
 
@@ -128,6 +131,22 @@ export const createStorage = _createStorage;
 `;
 }
 
+/**
+ * Generates the image-transformer virtual module.
+ * Statically imports the configured image service (e.g. the Cloudflare IMAGES
+ * binding). Exports `undefined` when no image service is configured, in which
+ * case the transform route streams the original bytes through unchanged.
+ */
+export function generateImagesModule(imagesEntrypoint?: string): string {
+	if (!imagesEntrypoint) {
+		return `export const createImageTransformer = undefined;`;
+	}
+	return `
+import { createImageTransformer as _createImageTransformer } from "${imagesEntrypoint}";
+export const createImageTransformer = _createImageTransformer;
+`;
+}
+
 /**
  * Generates the auth virtual module.
  * Statically imports the configured auth provider.

packages/core/src/astro/integration/vite-config.ts

@@ -22,6 +22,8 @@ import {
 	RESOLVED_VIRTUAL_DIALECT_ID,
 	VIRTUAL_STORAGE_ID,
 	RESOLVED_VIRTUAL_STORAGE_ID,
+	VIRTUAL_IMAGES_ID,
+	RESOLVED_VIRTUAL_IMAGES_ID,
 	VIRTUAL_ADMIN_REGISTRY_ID,
 	RESOLVED_VIRTUAL_ADMIN_REGISTRY_ID,
 	VIRTUAL_PLUGINS_ID,
@@ -50,6 +52,7 @@ import {
 	generateConfigModule,
 	generateDialectModule,
 	generateStorageModule,
+	generateImagesModule,
 	generateAuthModule,
 	generateAuthProvidersModule,
 	generatePluginsModule,
@@ -176,6 +179,9 @@ export function createVirtualModulesPlugin(options: VitePluginOptions): Plugin {
 			if (id === VIRTUAL_STORAGE_ID) {
 				return RESOLVED_VIRTUAL_STORAGE_ID;
 			}
+			if (id === VIRTUAL_IMAGES_ID) {
+				return RESOLVED_VIRTUAL_IMAGES_ID;
+			}
 			if (id === VIRTUAL_ADMIN_REGISTRY_ID) {
 				return RESOLVED_VIRTUAL_ADMIN_REGISTRY_ID;
 			}
@@ -227,6 +233,13 @@ export function createVirtualModulesPlugin(options: VitePluginOptions): Plugin {
 			if (id === RESOLVED_VIRTUAL_STORAGE_ID) {
 				return generateStorageModule(resolvedConfig.storage?.entrypoint);
 			}
+
+			// Generate a module that statically imports the configured image
+			// transformer (e.g. the Cloudflare IMAGES binding), or exports
+			// undefined when none is configured.
+			if (id === RESOLVED_VIRTUAL_IMAGES_ID) {
+				return generateImagesModule(resolvedConfig.images?.entrypoint);
+			}
 			// Generate plugins module that imports and instantiates all plugins
 			if (id === RESOLVED_VIRTUAL_PLUGINS_ID) {
 				return generatePluginsModule(pluginDescriptors);

packages/core/src/astro/middleware.ts

@@ -17,6 +17,8 @@ import {
 } from "virtual:emdash/dialect";
 import type { RequestScopedDbOpts } from "virtual:emdash/dialect";
 // @ts-ignore - virtual module
+import { createImageTransformer as virtualCreateImageTransformer } from "virtual:emdash/images";
+// @ts-ignore - virtual module
 import { mediaProviders as virtualMediaProviders } from "virtual:emdash/media-providers";
 // @ts-ignore - virtual module
 import { plugins as virtualPlugins } from "virtual:emdash/plugins";
@@ -45,6 +47,7 @@ import {
 } from "../emdash-runtime.js";
 import { setI18nConfig } from "../i18n/config.js";
 import type { Database, Storage } from "../index.js";
+import type { CreateImageTransformerFn, TransformImageFn } from "../media/image-transform.js";
 import { createPublicMediaUrlResolver } from "../media/url.js";
 import type { SandboxRunner } from "../plugins/sandbox/types.js";
 import type { ResolvedPlugin } from "../plugins/types.js";
@@ -162,6 +165,38 @@ function getPlugins(): ResolvedPlugin[] {
 	return (virtualPlugins as ResolvedPlugin[]) || [];
 }
 
+// Image transformer is stateless and configured once per deployment; build it
+// lazily on first use and reuse it. `null` records "tried and unavailable" so
+// a missing binding doesn't re-throw and re-log on every request.
+let _transformImage: TransformImageFn | null | undefined;
+
+/**
+ * Resolve the request-time image transform function from the virtual module and
+ * config. Returns `undefined` when no image service is configured or the
+ * adapter fails to initialize (e.g. a missing binding), in which case the
+ * transform route streams the original bytes through unchanged.
+ */
+function getTransformImage(config: EmDashConfig): TransformImageFn | undefined {
+	if (_transformImage !== undefined) return _transformImage ?? undefined;
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- virtual module import is untyped (@ts-ignore above)
+	const create = virtualCreateImageTransformer as CreateImageTransformerFn | undefined;
+	const descriptor = config.images;
+	if (!create || !descriptor) {
+		_transformImage = null;
+		return undefined;
+	}
+	try {
+		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- descriptor.config is a serialized `unknown`; the adapter validates its own shape
+		const transformer = create((descriptor.config ?? {}) as Record<string, unknown>);
+		_transformImage = transformer.transform.bind(transformer);
+		return _transformImage;
+	} catch (error) {
+		console.error("[emdash] image transformer init failed:", error);
+		_transformImage = null;
+		return undefined;
+	}
+}
+
 /**
  * Build runtime dependencies from virtual modules
  */
@@ -472,6 +507,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 							collectPageMetadata: runtime.collectPageMetadata.bind(runtime),
 							collectPageFragments: runtime.collectPageFragments.bind(runtime),
 							getPublicMediaUrl: createPublicMediaUrlResolver(runtime.storage),
+							transformImage: getTransformImage(config),
 						} as EmDashHandlers;
 					} catch {
 						// Non-fatal — EmDashHead will fall back to base SEO contributions
@@ -618,6 +654,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 					storage: runtime.storage,
 					db: runtime.db,
 					getPublicMediaUrl: createPublicMediaUrlResolver(runtime.storage),
+					transformImage: getTransformImage(config),
 					hooks: runtime.hooks,
 					email: runtime.email,
 					configuredPlugins: runtime.configuredPlugins,