@emdash-cms/cloudflare 0.0.1

package/src/db/do-class.ts

@@ -0,0 +1,275 @@
+/**
+ * EmDashPreviewDB — Durable Object for preview databases
+ *
+ * Each preview session gets its own DO with isolated SQLite storage.
+ * The DO is populated from a snapshot of the source EmDash site
+ * and serves read-only queries until its TTL expires.
+ *
+ * Not used in production — preview only.
+ */
+
+import { DurableObject } from "cloudflare:workers";
+
+/** Default TTL for preview data (1 hour) */
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+
+/** Valid identifier pattern for snapshot table/column names */
+const SAFE_IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+
+/** SQL command prefixes that indicate read-only statements */
+const READ_PREFIXES = ["SELECT", "PRAGMA", "EXPLAIN", "WITH"];
+
+/** Result shape returned by query() */
+export interface QueryResult {
+	rows: Record<string, unknown>[];
+	/** Number of rows written. Undefined for read-only queries. */
+	changes?: number;
+}
+
+/** A single statement for batch execution */
+export interface BatchStatement {
+	sql: string;
+	params?: unknown[];
+}
+
+/** Snapshot shape received from the source site */
+interface Snapshot {
+	tables: Record<string, Record<string, unknown>[]>;
+	schema?: Record<
+		string,
+		{
+			columns: string[];
+			types?: Record<string, string>;
+		}
+	>;
+	generatedAt: string;
+}
+
+export class EmDashPreviewDB extends DurableObject {
+	/**
+	 * Execute a single SQL statement.
+	 *
+	 * Called via RPC from the Kysely driver connection.
+	 */
+	query(sql: string, params?: unknown[]): QueryResult {
+		const cursor = params?.length
+			? this.ctx.storage.sql.exec(sql, ...params)
+			: this.ctx.storage.sql.exec(sql);
+
+		const rows: Record<string, unknown>[] = [];
+		for (const row of cursor) {
+			// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- SqlStorageCursor yields record-like objects
+			rows.push(row as Record<string, unknown>);
+		}
+
+		const isRead = READ_PREFIXES.some((p) => sql.trimStart().toUpperCase().startsWith(p));
+
+		return {
+			rows,
+			changes: isRead ? undefined : cursor.rowsWritten,
+		};
+	}
+
+	/**
+	 * Execute multiple statements in a single synchronous transaction.
+	 *
+	 * Used for snapshot import.
+	 */
+	batch(statements: BatchStatement[]): void {
+		this.ctx.storage.transactionSync(() => {
+			for (const stmt of statements) {
+				if (stmt.params?.length) {
+					this.ctx.storage.sql.exec(stmt.sql, ...stmt.params);
+				} else {
+					this.ctx.storage.sql.exec(stmt.sql);
+				}
+			}
+		});
+	}
+
+	/**
+	 * Invalidate the cached snapshot so the next populateFromSnapshot call
+	 * re-fetches from the source site.
+	 */
+	invalidateSnapshot(): void {
+		try {
+			this.ctx.storage.sql.exec("DELETE FROM _emdash_do_meta WHERE key = 'snapshot_fetched_at'");
+		} catch {
+			// Table doesn't exist — nothing to invalidate
+		}
+	}
+
+	/**
+	 * Get snapshot metadata (generated-at timestamp).
+	 * Returns null if the DO has no snapshot loaded.
+	 */
+	getSnapshotMeta(): { generatedAt: string } | null {
+		try {
+			const row = this.ctx.storage.sql
+				.exec("SELECT value FROM _emdash_do_meta WHERE key = 'snapshot_generated_at'")
+				.one();
+			const value = row.value;
+			if (typeof value !== "string") return null;
+			return { generatedAt: value };
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Populate from a snapshot (preview mode).
+	 *
+	 * Fetches content from a source EmDash site and loads it into
+	 * this DO's SQLite. Sets a TTL alarm for cleanup.
+	 */
+	async populateFromSnapshot(
+		sourceUrl: string,
+		signature: string,
+		options?: { drafts?: boolean; ttl?: number },
+	): Promise<{ generatedAt: string }> {
+		const ttlMs = (options?.ttl ?? DEFAULT_TTL_MS / 1000) * 1000;
+
+		// Check if already populated and fresh
+		try {
+			const meta = this.ctx.storage.sql
+				.exec("SELECT value FROM _emdash_do_meta WHERE key = 'snapshot_fetched_at'")
+				.one();
+			const fetchedAt = Number(meta.value);
+			if (Date.now() - fetchedAt < ttlMs) {
+				// Refresh alarm so active sessions aren't killed
+				void this.ctx.storage.setAlarm(Date.now() + ttlMs);
+				const gen = this.ctx.storage.sql
+					.exec("SELECT value FROM _emdash_do_meta WHERE key = 'snapshot_generated_at'")
+					.one();
+				// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- SqlStorageCursor yields loosely-typed rows
+				return { generatedAt: String(gen.value as string | number) };
+			}
+		} catch (error) {
+			// Only swallow "no such table" — surface all other errors
+			if (!(error instanceof Error) || !error.message.includes("no such table")) {
+				throw error;
+			}
+			// _emdash_do_meta doesn't exist yet — first population
+		}
+
+		// Fetch snapshot with timeout
+		const url = `${sourceUrl}/_emdash/api/snapshot${options?.drafts ? "?drafts=true" : ""}`;
+		const response = await fetch(url, {
+			headers: { "X-Preview-Signature": signature },
+			signal: AbortSignal.timeout(10_000),
+		});
+		if (!response.ok) {
+			const body = await response.text().catch(() => "");
+			throw new Error(
+				`Snapshot fetch failed: ${response.status} ${response.statusText}${body ? ` — ${body}` : ""}`,
+			);
+		}
+		const snapshot: Snapshot = await response.json();
+
+		// Wipe and repopulate in a single transaction so partial applies
+		// can't leave the database in an inconsistent state.
+		// ctx.storage.deleteAll() only clears KV storage, not SQLite.
+		this.ctx.storage.transactionSync(() => {
+			this.dropAllTables();
+			this.applySnapshot(snapshot);
+		});
+
+		// Set cleanup alarm
+		void this.ctx.storage.setAlarm(Date.now() + ttlMs);
+
+		return { generatedAt: snapshot.generatedAt };
+	}
+
+	/**
+	 * Set a cleanup alarm after the given number of seconds.
+	 *
+	 * Used by the playground middleware to set TTL after initialization
+	 * is complete (initialization runs on the Worker side via RPC).
+	 */
+	setTtlAlarm(ttlSeconds: number): void {
+		void this.ctx.storage.setAlarm(Date.now() + ttlSeconds * 1000);
+	}
+
+	/**
+	 * Alarm handler — clean up expired preview/playground data.
+	 *
+	 * Drops all user tables to reclaim storage.
+	 */
+	override alarm(): void {
+		this.dropAllTables();
+	}
+
+	/**
+	 * Drop all user tables in the DO's SQLite database.
+	 * Preserves SQLite and Cloudflare internal tables.
+	 */
+	private dropAllTables(): void {
+		const tables = [
+			...this.ctx.storage.sql.exec(
+				"SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '_cf_%'",
+			),
+		];
+		for (const row of tables) {
+			// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- SqlStorageCursor yields loosely-typed rows
+			const name = String(row.name as string);
+			if (!SAFE_IDENTIFIER.test(name)) {
+				// Skip tables with unsafe names rather than interpolating them
+				continue;
+			}
+			this.ctx.storage.sql.exec(`DROP TABLE IF EXISTS "${name}"`);
+		}
+	}
+
+	private applySnapshot(snapshot: Snapshot): void {
+		const validateSnapshotIdentifier = (name: string, context: string) => {
+			if (!SAFE_IDENTIFIER.test(name)) {
+				throw new Error(`Invalid ${context} in snapshot: ${JSON.stringify(name)}`);
+			}
+		};
+
+		// Create meta table
+		this.ctx.storage.sql.exec(`
+			CREATE TABLE IF NOT EXISTS _emdash_do_meta (key TEXT PRIMARY KEY, value TEXT)
+		`);
+
+		// Create tables and insert data from snapshot
+		for (const [tableName, rows] of Object.entries(snapshot.tables)) {
+			if (tableName === "_emdash_do_meta") continue;
+			if (!rows.length) continue;
+
+			validateSnapshotIdentifier(tableName, "table name");
+
+			const schemaInfo = snapshot.schema?.[tableName];
+			const columns = schemaInfo?.columns ?? Object.keys(rows[0]!);
+			columns.forEach((c) => validateSnapshotIdentifier(c, `column name in ${tableName}`));
+
+			const colDefs = columns
+				.map((c) => {
+					const colType = schemaInfo?.types?.[c] ?? "TEXT";
+					const safeType = ["TEXT", "INTEGER", "REAL", "BLOB", "JSON"].includes(
+						colType.toUpperCase(),
+					)
+						? colType.toUpperCase()
+						: "TEXT";
+					return `"${c}" ${safeType}`;
+				})
+				.join(", ");
+			this.ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS "${tableName}" (${colDefs})`);
+
+			// Batch insert
+			const placeholders = columns.map(() => "?").join(", ");
+			const insertSql = `INSERT INTO "${tableName}" (${columns.map((c) => `"${c}"`).join(", ")}) VALUES (${placeholders})`;
+			for (const row of rows) {
+				const values = columns.map((c) => row[c] ?? null);
+				this.ctx.storage.sql.exec(insertSql, ...values);
+			}
+		}
+
+		// Record metadata
+		this.ctx.storage.sql.exec(
+			`INSERT OR REPLACE INTO _emdash_do_meta VALUES ('snapshot_fetched_at', ?), ('snapshot_generated_at', ?)`,
+			String(Date.now()),
+			snapshot.generatedAt,
+		);
+	}
+}

package/src/db/do-dialect.ts

@@ -0,0 +1,125 @@
+/**
+ * Kysely dialect for Durable Object preview databases
+ *
+ * Proxies all queries to an EmDashPreviewDB DO instance via RPC.
+ * Preview mode is read-only — no transaction support needed.
+ */
+
+import type {
+	CompiledQuery,
+	DatabaseConnection,
+	DatabaseIntrospector,
+	Dialect,
+	Driver,
+	Kysely,
+	QueryResult,
+} from "kysely";
+import { SqliteAdapter, SqliteQueryCompiler } from "kysely";
+
+import { D1Introspector } from "./d1-introspector.js";
+import type { QueryResult as DOQueryResult } from "./do-class.js";
+
+/**
+ * Minimal interface for the DO stub's RPC methods.
+ *
+ * We define this instead of using DurableObjectStub<EmDashPreviewDB> directly
+ * because Rpc.Result<T> resolves to `never` when the return type contains
+ * `unknown` (Record<string, unknown> in QueryResult.rows). This interface
+ * gives us clean typing without fighting the Rpc type system.
+ */
+export interface PreviewDBStub {
+	query(sql: string, params?: unknown[]): Promise<DOQueryResult>;
+}
+
+export interface PreviewDODialectConfig {
+	/**
+	 * Factory that returns a fresh DO stub on each call.
+	 *
+	 * DO stubs are bound to the request context that created them.
+	 * Since the Kysely instance may be cached across requests, we can't
+	 * hold a single stub — each connection must get a fresh one via
+	 * namespace.get(id), which is cheap (no RPC, just a local ref).
+	 */
+	getStub: () => PreviewDBStub;
+}
+
+export class PreviewDODialect implements Dialect {
+	readonly #config: PreviewDODialectConfig;
+
+	constructor(config: PreviewDODialectConfig) {
+		this.#config = config;
+	}
+
+	createAdapter(): SqliteAdapter {
+		return new SqliteAdapter();
+	}
+
+	createDriver(): Driver {
+		return new PreviewDODriver(this.#config);
+	}
+
+	createQueryCompiler(): SqliteQueryCompiler {
+		return new SqliteQueryCompiler();
+	}
+
+	createIntrospector(db: Kysely<any>): DatabaseIntrospector {
+		return new D1Introspector(db);
+	}
+}
+
+class PreviewDODriver implements Driver {
+	readonly #config: PreviewDODialectConfig;
+
+	constructor(config: PreviewDODialectConfig) {
+		this.#config = config;
+	}
+
+	async init(): Promise<void> {}
+
+	async acquireConnection(): Promise<DatabaseConnection> {
+		return new PreviewDOConnection(this.#config.getStub());
+	}
+
+	async beginTransaction(): Promise<void> {
+		// No-op. Preview is read-only.
+	}
+
+	async commitTransaction(): Promise<void> {
+		// No-op.
+	}
+
+	async rollbackTransaction(): Promise<void> {
+		// No-op.
+	}
+
+	async releaseConnection(): Promise<void> {}
+
+	async destroy(): Promise<void> {}
+}
+
+class PreviewDOConnection implements DatabaseConnection {
+	readonly #stub: PreviewDBStub;
+
+	constructor(stub: PreviewDBStub) {
+		this.#stub = stub;
+	}
+
+	async executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>> {
+		const sqlText = compiledQuery.sql;
+		// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- CompiledQuery.parameters is ReadonlyArray<unknown>, stub expects unknown[]
+		const params = compiledQuery.parameters as unknown[];
+
+		const result = await this.#stub.query(sqlText, params);
+
+		return {
+			// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Kysely generic O is the caller's row type; we trust the DB returned matching rows
+			rows: result.rows as O[],
+			numAffectedRows: result.changes !== undefined ? BigInt(result.changes) : undefined,
+		};
+	}
+
+	// eslint-disable-next-line require-yield -- interface requires AsyncIterableIterator but DO doesn't support streaming
+	async *streamQuery<O>(): AsyncIterableIterator<QueryResult<O>> {
+		throw new Error("Preview DO dialect does not support streaming");
+	}
+}

package/src/db/do-playground-routes.ts

@@ -0,0 +1,65 @@
+/**
+ * Playground mode route gating.
+ *
+ * Unlike preview mode (which blocks everything except read-only API routes),
+ * playground mode allows most routes including the admin UI and write APIs.
+ * Only auth, setup, and abuse-prone routes are blocked.
+ *
+ * Pure function -- no Worker or Cloudflare dependencies.
+ */
+
+/**
+ * Routes blocked in playground mode.
+ *
+ * These are either security-sensitive (auth, setup, tokens, OAuth),
+ * abuse-prone (media upload, plugin install), or pointless in a
+ * temporary playground (snapshot export, user management).
+ */
+/**
+ * Auth routes that ARE allowed in playground mode.
+ * /auth/me is needed by the admin UI to identify the current user.
+ */
+const AUTH_ALLOWLIST = new Set(["/_emdash/api/auth/me"]);
+
+const BLOCKED_PREFIXES = [
+	// Auth -- playground has no real auth (except /auth/me for admin UI)
+	"/_emdash/api/auth/",
+	// Setup -- playground is pre-configured
+	"/_emdash/api/setup/",
+	// OAuth provider routes
+	"/_emdash/api/oauth/",
+	// API token management
+	"/_emdash/api/tokens/",
+	// User management (can't invite/create real users)
+	"/_emdash/api/users/invite",
+	// Plugin installation (security boundary)
+	"/_emdash/api/plugins/install",
+	"/_emdash/api/plugins/marketplace",
+	// Media uploads (abuse vector -- no storage in playground)
+	"/_emdash/api/media/upload",
+	// Snapshot export (no point exporting a playground)
+	"/_emdash/api/snapshot",
+];
+
+/**
+ * Check whether a request should be blocked in playground mode.
+ *
+ * Playground allows most CMS functionality: content CRUD, schema editing,
+ * taxonomies, menus, widgets, search, settings, and the full admin UI.
+ * Only auth, setup, user management, media uploads, and plugin
+ * installation are blocked.
+ */
+export function isBlockedInPlayground(pathname: string): boolean {
+	// Check allowlist first -- specific routes that must work despite
+	// their parent prefix being blocked (e.g. /auth/me for admin UI)
+	if (AUTH_ALLOWLIST.has(pathname)) {
+		return false;
+	}
+
+	for (const prefix of BLOCKED_PREFIXES) {
+		if (pathname === prefix || pathname.startsWith(prefix)) {
+			return true;
+		}
+	}
+	return false;
+}

package/src/db/do-preview-routes.ts

@@ -0,0 +1,48 @@
+/**
+ * Preview mode route gating.
+ *
+ * Pure function — no Worker or Cloudflare dependencies.
+ * Extracted so it can be tested without mocking cloudflare:workers.
+ */
+
+/**
+ * API route prefixes allowed in preview mode (read-only).
+ * Everything else under /_emdash/ is blocked.
+ */
+const ALLOWED_API_PREFIXES = [
+	"/_emdash/api/content/",
+	"/_emdash/api/schema",
+	"/_emdash/api/manifest",
+	"/_emdash/api/dashboard",
+	"/_emdash/api/search",
+	"/_emdash/api/media",
+	"/_emdash/api/taxonomies",
+	"/_emdash/api/menus",
+	"/_emdash/api/snapshot",
+];
+
+/**
+ * Check whether a request should be blocked in preview mode.
+ *
+ * Preview is read-only with no authenticated user. All /_emdash/
+ * routes are blocked by default (admin UI, auth, setup, write APIs).
+ * Only specific read-only API prefixes are allowlisted.
+ *
+ * Non-emdash routes (site pages, assets) are always allowed.
+ */
+export function isBlockedInPreview(pathname: string): boolean {
+	// Non-emdash routes are always allowed (site pages, assets, etc.)
+	if (!pathname.startsWith("/_emdash/")) {
+		return false;
+	}
+
+	// Check allowlist for API routes
+	for (const prefix of ALLOWED_API_PREFIXES) {
+		if (pathname === prefix || pathname.startsWith(prefix)) {
+			return false;
+		}
+	}
+
+	// Everything else under /_emdash/ is blocked
+	return true;
+}

package/src/db/do-preview-sign.ts

@@ -0,0 +1,100 @@
+/**
+ * Preview URL signing utilities.
+ *
+ * Pure functions using Web Crypto — no Worker or Cloudflare dependencies.
+ * Used by the source site to generate signed preview URLs and by the
+ * preview service to verify them.
+ */
+
+/** Matches a lowercase hex string */
+const HEX_PATTERN = /^[0-9a-f]+$/;
+
+/**
+ * Compute HMAC-SHA256 over a message and return the hex-encoded signature.
+ */
+async function hmacSign(message: string, secret: string): Promise<string> {
+	const encoder = new TextEncoder();
+
+	const key = await crypto.subtle.importKey(
+		"raw",
+		encoder.encode(secret),
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		["sign"],
+	);
+
+	const buffer = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+	return Array.from(new Uint8Array(buffer), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Generate a signed preview URL.
+ *
+ * The source site calls this to create a link that opens the preview service.
+ * The preview service validates the signature and populates the DO from a
+ * snapshot of the source site.
+ *
+ * @param previewBase - Base URL of the preview service (e.g. "https://theme-x.preview.emdashcms.com")
+ * @param source - URL of the source site providing the snapshot (e.g. "https://mysite.com")
+ * @param secret - Shared HMAC secret (same value configured on both sides)
+ * @param ttl - Link validity in seconds (default: 3600 = 1 hour)
+ * @returns Fully signed preview URL
+ *
+ * @example
+ * ```ts
+ * const url = await signPreviewUrl(
+ *   "https://theme-x.preview.emdashcms.com",
+ *   "https://mysite.com",
+ *   import.meta.env.PREVIEW_SECRET,
+ * );
+ * // => "https://theme-x.preview.emdashcms.com/?source=https%3A%2F%2Fmysite.com&exp=1709164800&sig=abc123..."
+ * ```
+ */
+export async function signPreviewUrl(
+	previewBase: string,
+	source: string,
+	secret: string,
+	ttl = 3600,
+): Promise<string> {
+	const exp = Math.floor(Date.now() / 1000) + ttl;
+	const sig = await hmacSign(`${source}:${exp}`, secret);
+
+	const url = new URL(previewBase);
+	url.searchParams.set("source", source);
+	url.searchParams.set("exp", String(exp));
+	url.searchParams.set("sig", sig);
+
+	return url.toString();
+}
+
+/**
+ * Verify an HMAC-SHA256 signature on a preview URL.
+ *
+ * Uses crypto.subtle.verify for constant-time comparison.
+ *
+ * @returns true if the signature is valid
+ */
+export async function verifyPreviewSignature(
+	source: string,
+	exp: number,
+	sig: string,
+	secret: string,
+): Promise<boolean> {
+	// Decode hex signature to ArrayBuffer
+	if (sig.length !== 64 || !HEX_PATTERN.test(sig)) return false;
+	const sigBytes = new Uint8Array(32);
+	for (let i = 0; i < 64; i += 2) {
+		sigBytes[i / 2] = parseInt(sig.substring(i, i + 2), 16);
+	}
+
+	const encoder = new TextEncoder();
+	const key = await crypto.subtle.importKey(
+		"raw",
+		encoder.encode(secret),
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		["verify"],
+	);
+
+	return crypto.subtle.verify("HMAC", key, sigBytes, encoder.encode(`${source}:${exp}`));
+}