@emdash-cms/cloudflare 0.0.1

package/src/index.ts

@@ -0,0 +1,285 @@
+/**
+ * @emdash-cms/cloudflare
+ *
+ * Cloudflare adapters for EmDash:
+ * - D1 database adapter
+ * - R2 storage adapter
+ * - Cloudflare Access authentication
+ * - Worker Loader sandbox for plugins
+ *
+ * This is the CONFIG-TIME entry point. It does NOT import cloudflare:workers
+ * and is safe to use in astro.config.mjs.
+ *
+ * For runtime exports (PluginBridge, authenticate), import from the specific
+ * runtime entrypoints:
+ * - @emdash-cms/cloudflare/sandbox (PluginBridge, createSandboxRunner)
+ * - @emdash-cms/cloudflare/auth (authenticate)
+ *
+ * @example
+ * ```ts
+ * import emdash from "emdash/astro";
+ * import { d1, r2, access, sandbox } from "@emdash-cms/cloudflare";
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     emdash({
+ *       database: d1({ binding: "DB" }),
+ *       storage: r2({ binding: "MEDIA" }),
+ *       auth: access({ teamDomain: "myteam.cloudflareaccess.com" }),
+ *       sandboxRunner: sandbox(),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+import type { AuthDescriptor, DatabaseDescriptor, StorageDescriptor } from "emdash";
+
+import type { PreviewDOConfig } from "./db/do-types.js";
+
+/**
+ * D1 configuration
+ */
+export interface D1Config {
+	/**
+	 * Name of the D1 binding in wrangler.toml
+	 */
+	binding: string;
+
+	/**
+	 * Read replication session mode.
+	 *
+	 * - `"disabled"` — No sessions. All queries go to primary. (default)
+	 * - `"auto"` — Automatic session management. Anonymous requests use
+	 *   `"first-unconstrained"` (nearest replica). Authenticated requests
+	 *   use bookmark cookies for read-your-writes consistency.
+	 * - `"primary-first"` — Like `"auto"`, but the first query in every
+	 *   session goes to the primary. Use this if your site has very
+	 *   frequent writes and you need stronger consistency guarantees
+	 *   at the cost of higher read latency.
+	 *
+	 * Read replication must also be enabled on the D1 database itself
+	 * (via dashboard or REST API).
+	 */
+	session?: "disabled" | "auto" | "primary-first";
+
+	/**
+	 * Cookie name for storing the session bookmark.
+	 * Only used when session is `"auto"` or `"primary-first"`.
+	 *
+	 * @default "__ec_d1_bookmark"
+	 */
+	bookmarkCookie?: string;
+}
+
+/**
+ * R2 storage configuration
+ */
+export interface R2StorageConfig {
+	/**
+	 * Name of the R2 binding in wrangler.toml
+	 */
+	binding: string;
+	/**
+	 * Public URL for accessing files (optional CDN)
+	 */
+	publicUrl?: string;
+}
+
+/**
+ * Configuration for Cloudflare Access authentication
+ */
+export interface AccessConfig {
+	/**
+	 * Your Cloudflare Access team domain
+	 * @example "myteam.cloudflareaccess.com"
+	 */
+	teamDomain: string;
+
+	/**
+	 * Application Audience (AUD) tag from Access application settings.
+	 * For Cloudflare Workers, use `audienceEnvVar` instead to read at runtime.
+	 */
+	audience?: string;
+
+	/**
+	 * Environment variable name containing the audience tag.
+	 * Read at runtime from environment.
+	 * @default "CF_ACCESS_AUDIENCE"
+	 */
+	audienceEnvVar?: string;
+
+	/**
+	 * Automatically create EmDash users on first login
+	 * @default true
+	 */
+	autoProvision?: boolean;
+
+	/**
+	 * Role level for users not matching any group in roleMapping
+	 * @default 30 (Editor)
+	 */
+	defaultRole?: number;
+
+	/**
+	 * Update user's role on each login based on current IdP groups
+	 * When false, role is only set on first provisioning
+	 * @default false
+	 */
+	syncRoles?: boolean;
+
+	/**
+	 * Map IdP group names to EmDash role levels
+	 * First match wins if user is in multiple groups
+	 *
+	 * @example
+	 * ```ts
+	 * roleMapping: {
+	 *   "Admins": 50,        // Admin
+	 *   "Developers": 40,    // Developer
+	 *   "Content Team": 30,  // Editor
+	 * }
+	 * ```
+	 */
+	roleMapping?: Record<string, number>;
+}
+
+/**
+ * Cloudflare D1 database adapter
+ *
+ * For Cloudflare Workers with D1 binding.
+ * Migrations run automatically at setup time - no need for manual SQL files.
+ *
+ * Uses a custom introspector that works around D1's restriction on
+ * cross-joins with pragma_table_info().
+ *
+ * @example
+ * ```ts
+ * database: d1({ binding: "DB" })
+ * ```
+ */
+export function d1(config: D1Config): DatabaseDescriptor {
+	return {
+		entrypoint: "@emdash-cms/cloudflare/db/d1",
+		config,
+		type: "sqlite",
+	};
+}
+
+export type { PreviewDOConfig } from "./db/do-types.js";
+
+/**
+ * Durable Object preview database adapter
+ *
+ * Each preview session gets an isolated SQLite database inside a DO,
+ * populated from a snapshot of the source EmDash site.
+ *
+ * Not for production use — preview only.
+ *
+ * @example
+ * ```ts
+ * database: previewDatabase({ binding: "PREVIEW_DB" })
+ * ```
+ */
+export function previewDatabase(config: PreviewDOConfig): DatabaseDescriptor {
+	return {
+		entrypoint: "@emdash-cms/cloudflare/db/do",
+		config,
+		type: "sqlite",
+	};
+}
+
+/**
+ * Durable Object playground database adapter
+ *
+ * Each playground session gets an isolated SQLite database inside a DO,
+ * populated from a seed file with migrations run at init time.
+ * Unlike preview, playground is writable and has admin access.
+ *
+ * Not for production use -- playground/demo only.
+ *
+ * @example
+ * ```ts
+ * database: playgroundDatabase({ binding: "PLAYGROUND_DB" })
+ * ```
+ */
+export function playgroundDatabase(config: PreviewDOConfig): DatabaseDescriptor {
+	return {
+		entrypoint: "@emdash-cms/cloudflare/db/playground",
+		config,
+		type: "sqlite",
+	};
+}
+
+/**
+ * Cloudflare R2 binding adapter
+ *
+ * Uses R2 bindings directly when running on Cloudflare Workers.
+ * Does NOT support signed upload URLs (use s3() with R2 credentials instead).
+ *
+ * Requires R2 binding in wrangler.toml:
+ * ```toml
+ * [[r2_buckets]]
+ * binding = "MEDIA"
+ * bucket_name = "my-media-bucket"
+ * ```
+ *
+ * @example
+ * ```ts
+ * storage: r2({ binding: "MEDIA" })
+ * ```
+ */
+export function r2(config: R2StorageConfig): StorageDescriptor {
+	return {
+		entrypoint: "@emdash-cms/cloudflare/storage/r2",
+		config: { binding: config.binding, publicUrl: config.publicUrl },
+	};
+}
+
+/**
+ * Cloudflare Access authentication adapter
+ *
+ * Use this to configure EmDash to authenticate via Cloudflare Access.
+ * When Access is configured, passkey auth is disabled.
+ *
+ * @example
+ * ```ts
+ * auth: access({
+ *   teamDomain: "myteam.cloudflareaccess.com",
+ *   audience: "abc123...",
+ *   roleMapping: {
+ *     "Admins": 50,
+ *     "Editors": 30,
+ *   },
+ * })
+ * ```
+ */
+export function access(config: AccessConfig): AuthDescriptor {
+	return {
+		type: "cloudflare-access",
+		entrypoint: "@emdash-cms/cloudflare/auth",
+		config,
+	};
+}
+
+/**
+ * Cloudflare Worker Loader sandbox adapter
+ *
+ * Returns the module path for the Cloudflare sandbox runner.
+ * Use this in the `sandboxRunner` config option.
+ *
+ * @example
+ * ```ts
+ * sandboxRunner: sandbox()
+ * ```
+ */
+export function sandbox(): string {
+	return "@emdash-cms/cloudflare/sandbox";
+}
+
+// Re-export media providers (config-time)
+export { cloudflareImages, type CloudflareImagesConfig } from "./media/images.js";
+export { cloudflareStream, type CloudflareStreamConfig } from "./media/stream.js";
+
+// Re-export cache provider config helper (config-time)
+export { cloudflareCache, type CloudflareCacheConfig } from "./cache/config.js";

package/src/media/images-runtime.ts

@@ -0,0 +1,353 @@
+/**
+ * Cloudflare Images Runtime Module
+ *
+ * This module is imported at runtime by the media provider system.
+ * It contains the actual provider implementation that interacts with the Cloudflare API.
+ */
+
+import { env } from "cloudflare:workers";
+import type {
+	MediaProvider,
+	MediaListOptions,
+	MediaValue,
+	EmbedOptions,
+	EmbedResult,
+	CreateMediaProviderFn,
+} from "emdash/media";
+
+import type { CloudflareImagesConfig } from "./images.js";
+
+/** Safely extract a number from an unknown value */
+function toNumber(value: unknown): number | undefined {
+	return typeof value === "number" ? value : undefined;
+}
+
+/**
+ * Resolve a config value, checking env var if direct value not provided
+ */
+function resolveEnvValue(
+	directValue: string | undefined,
+	envVarName: string | undefined,
+	defaultEnvVar: string,
+	serviceName: string,
+): string {
+	if (directValue) return directValue;
+	const envVar = envVarName || defaultEnvVar;
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Worker binding accessed from untyped env object
+	const value = (env as Record<string, string | undefined>)[envVar];
+	if (!value) {
+		throw new Error(
+			`${serviceName}: Missing ${envVar}. Set it as an environment variable or provide it directly in config.`,
+		);
+	}
+	return value;
+}
+
+/**
+ * Runtime implementation for Cloudflare Images provider
+ */
+export const createMediaProvider: CreateMediaProviderFn<CloudflareImagesConfig> = (config) => {
+	const { deliveryDomain, defaultVariant = "public" } = config;
+
+	// Lazy getters - resolve env vars at request time, not module init time
+	const getAccountId = () =>
+		resolveEnvValue(config.accountId, config.accountIdEnvVar, "CF_ACCOUNT_ID", "Cloudflare Images");
+	const getAccountHash = () =>
+		resolveEnvValue(
+			config.accountHash,
+			config.accountHashEnvVar,
+			"CF_IMAGES_ACCOUNT_HASH",
+			"Cloudflare Images",
+		);
+	const getApiToken = () =>
+		resolveEnvValue(config.apiToken, config.apiTokenEnvVar, "CF_IMAGES_TOKEN", "Cloudflare Images");
+	const getApiBase = () =>
+		`https://api.cloudflare.com/client/v4/accounts/${getAccountId()}/images/v1`;
+	const getHeaders = () => ({ Authorization: `Bearer ${getApiToken()}` });
+	const getDeliveryBase = () =>
+		deliveryDomain ? `https://${deliveryDomain}` : "https://imagedelivery.net";
+
+	// Build a delivery URL with flexible variant transforms
+	const buildUrl = (imageId: string, transforms?: { w?: number; h?: number; fit?: string }) => {
+		const base = `${getDeliveryBase()}/${getAccountHash()}/${imageId}`;
+		if (!transforms || Object.keys(transforms).length === 0) {
+			return `${base}/${defaultVariant}`;
+		}
+		const parts: string[] = [];
+		if (transforms.w) parts.push(`w=${transforms.w}`);
+		if (transforms.h) parts.push(`h=${transforms.h}`);
+		if (transforms.fit) parts.push(`fit=${transforms.fit}`);
+		return `${base}/${parts.join(",")}`;
+	};
+
+	// Fetch image dimensions via the format=json delivery endpoint
+	// This is a public endpoint that doesn't require authentication
+	const fetchDimensions = async (
+		imageId: string,
+	): Promise<{ width: number; height: number } | null> => {
+		const url = `${getDeliveryBase()}/${getAccountHash()}/${imageId}/format=json`;
+		try {
+			const response = await fetch(url);
+			if (!response.ok) return null;
+			const data: ImageJsonResponse = await response.json();
+			return { width: data.width, height: data.height };
+		} catch {
+			return null;
+		}
+	};
+
+	const provider: MediaProvider = {
+		async list(options: MediaListOptions) {
+			const apiBase = getApiBase();
+			const headers = getHeaders();
+
+			const params = new URLSearchParams();
+			if (options.cursor) {
+				params.set("continuation_token", options.cursor);
+			}
+			if (options.limit) {
+				params.set("per_page", String(options.limit));
+			}
+
+			const url = `${apiBase}?${params}`;
+			const response = await fetch(url, { headers });
+
+			if (!response.ok) {
+				throw new Error(`Cloudflare Images API error: ${response.status}`);
+			}
+
+			const data: CloudflareImagesListResponse = await response.json();
+
+			if (!data.success) {
+				throw new Error(
+					`Cloudflare Images API error: ${data.errors?.[0]?.message || "Unknown error"}`,
+				);
+			}
+
+			// Filter out images that require signed URLs (not supported yet)
+			const publicImages = data.result.images.filter((img) => !img.requireSignedURLs);
+
+			// Fetch dimensions for all images in parallel
+			const dimensionsMap = new Map<string, { width: number; height: number }>();
+			const dimensionResults = await Promise.all(
+				publicImages.map(async (img) => {
+					const dims = await fetchDimensions(img.id);
+					return { id: img.id, dims };
+				}),
+			);
+			for (const { id, dims } of dimensionResults) {
+				if (dims) dimensionsMap.set(id, dims);
+			}
+
+			return {
+				items: publicImages.map((img) => {
+					const dims = dimensionsMap.get(img.id);
+					return {
+						id: img.id,
+						filename: img.filename || img.id,
+						mimeType: "image/jpeg", // CF Images doesn't expose original mime type
+						width: dims?.width ?? toNumber(img.meta?.width),
+						height: dims?.height ?? toNumber(img.meta?.height),
+						// Use 400px wide preview for grid thumbnails (good for 2x retina on ~200px grid)
+						previewUrl: buildUrl(img.id, { w: 400, fit: "scale-down" }),
+						meta: {
+							variants: img.variants,
+							uploaded: img.uploaded,
+						},
+					};
+				}),
+				nextCursor: data.result.continuation_token || undefined,
+			};
+		},
+
+		async get(id: string) {
+			const apiBase = getApiBase();
+			const headers = getHeaders();
+
+			const url = `${apiBase}/${id}`;
+			const response = await fetch(url, { headers });
+
+			if (!response.ok) {
+				if (response.status === 404) return null;
+				throw new Error(`Cloudflare Images API error: ${response.status}`);
+			}
+
+			const data: CloudflareImageResponse = await response.json();
+
+			if (!data.success) {
+				return null;
+			}
+
+			const img = data.result;
+
+			// Don't return images that require signed URLs (not supported yet)
+			if (img.requireSignedURLs) {
+				return null;
+			}
+
+			// Fetch dimensions via format=json endpoint
+			const dims = await fetchDimensions(img.id);
+
+			return {
+				id: img.id,
+				filename: img.filename || img.id,
+				mimeType: "image/jpeg",
+				width: dims?.width ?? toNumber(img.meta?.width),
+				height: dims?.height ?? toNumber(img.meta?.height),
+				// Use larger preview for detail view
+				previewUrl: buildUrl(img.id, { w: 800, fit: "scale-down" }),
+				meta: {
+					variants: img.variants,
+					uploaded: img.uploaded,
+				},
+			};
+		},
+
+		async upload(input) {
+			const apiBase = getApiBase();
+			const apiToken = getApiToken();
+
+			const formData = new FormData();
+			formData.append("file", input.file, input.filename);
+
+			// Ensure uploaded images are public (don't require signed URLs)
+			formData.append("requireSignedURLs", "false");
+
+			// Add metadata if provided
+			const metadata: Record<string, string> = {};
+			if (input.alt) {
+				metadata.alt = input.alt;
+			}
+			if (Object.keys(metadata).length > 0) {
+				formData.append("metadata", JSON.stringify(metadata));
+			}
+
+			const response = await fetch(apiBase, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${apiToken}`,
+					// Don't set Content-Type - let browser set it with boundary
+				},
+				body: formData,
+			});
+
+			if (!response.ok) {
+				const error = await response.text();
+				throw new Error(`Cloudflare Images upload failed: ${error}`);
+			}
+
+			const data: CloudflareImageResponse = await response.json();
+
+			if (!data.success) {
+				throw new Error(
+					`Cloudflare Images upload failed: ${data.errors?.[0]?.message || "Unknown error"}`,
+				);
+			}
+
+			const img = data.result;
+			return {
+				id: img.id,
+				filename: img.filename || input.filename,
+				mimeType: "image/jpeg",
+				width: toNumber(img.meta?.width),
+				height: toNumber(img.meta?.height),
+				previewUrl: buildUrl(img.id, { w: 400, fit: "scale-down" }),
+				meta: {
+					variants: img.variants,
+					uploaded: img.uploaded,
+				},
+			};
+		},
+
+		async delete(id: string) {
+			const apiBase = getApiBase();
+			const headers = getHeaders();
+
+			const response = await fetch(`${apiBase}/${id}`, {
+				method: "DELETE",
+				headers,
+			});
+
+			if (!response.ok && response.status !== 404) {
+				throw new Error(`Cloudflare Images delete failed: ${response.status}`);
+			}
+		},
+
+		getEmbed(value: MediaValue, options?: EmbedOptions): EmbedResult {
+			const accountHash = getAccountHash();
+			const deliveryBase = getDeliveryBase();
+			const baseUrl = `${deliveryBase}/${accountHash}/${value.id}`;
+
+			// Helper to build URL with transforms
+			const buildSrc = (opts: { width?: number; height?: number; format?: string }) => {
+				const t: string[] = [];
+				if (opts.width) t.push(`w=${opts.width}`);
+				if (opts.height) t.push(`h=${opts.height}`);
+				if (opts.format) t.push(`f=${opts.format}`);
+				t.push("fit=scale-down");
+				return `${baseUrl}/${t.join(",")}`;
+			};
+
+			// Build src URL - always include transforms (CF Images requires a variant)
+			const width = options?.width ?? value.width ?? 1200;
+			const height = options?.height ?? value.height;
+			const src = buildSrc({ width, height, format: options?.format });
+
+			return {
+				type: "image",
+				src,
+				width: options?.width ?? value.width,
+				height: options?.height ?? value.height,
+				alt: value.alt,
+				// Provide getSrc for dynamic resizing (e.g., responsive images)
+				getSrc: buildSrc,
+			};
+		},
+
+		getThumbnailUrl(id: string, _mimeType?: string, options?: { width?: number; height?: number }) {
+			// For images, return a sized delivery URL
+			const width = options?.width || 400;
+			const height = options?.height;
+			return buildUrl(id, { w: width, h: height, fit: "scale-down" });
+		},
+	};
+
+	return provider;
+};
+
+// Cloudflare API response types
+interface CloudflareImagesListResponse {
+	success: boolean;
+	errors?: Array<{ message: string }>;
+	result: {
+		images: CloudflareImage[];
+		continuation_token?: string;
+	};
+}
+
+interface CloudflareImageResponse {
+	success: boolean;
+	errors?: Array<{ message: string }>;
+	result: CloudflareImage;
+}
+
+interface CloudflareImage {
+	id: string;
+	filename?: string;
+	uploaded: string;
+	requireSignedURLs: boolean;
+	variants: string[];
+	meta?: Record<string, unknown>;
+}
+
+// Response from format=json delivery endpoint
+interface ImageJsonResponse {
+	width: number;
+	height: number;
+	original: {
+		file_size: number;
+		width: number;
+		height: number;
+		format: string;
+	};
+}