@zeyolabs/kit 2026.11.9 → 2026.11.11

package/cloudflare/d1/testing.ts

@@ -0,0 +1,113 @@
+import type { D1Database } from '@cloudflare/workers-types';
+import type { Miniflare as MiniflareClass } from 'miniflare';
+
+import { drizzle } from 'drizzle-orm/d1';
+import { afterAll, beforeAll, vi } from 'vitest';
+
+// A real D1 for tests, the D1 counterpart of `storage/postgres/testing` (`createPgliteTestDb`):
+// Miniflare runs workerd's own D1, so the limits production has (100 bound parameters per
+// statement, FTS5, batch semantics) hold in tests too. A plain SQLite stand-in would pass queries
+// that fail on D1. Needs `miniflare` (an optional peer dependency), imported lazily so apps that
+// never call these don't load it.
+//
+// Like glasa: this file is the low-level piece. An app wraps it once in its own `tests/db.ts`
+// (its schema, its migrations, its fixtures) and its tests call that wrapper's `mockDb()`.
+
+export type D1TestDb<TSchema extends Record<string, unknown>> = {
+	/** Stops the Miniflare instance (and restores the clock if it was frozen). Call it in `afterAll`. */
+	close(): Promise<void>;
+	/** The raw D1 binding, for tests that need `prepare`, `batch` or `exec`. */
+	d1: D1Database;
+	/** The drizzle client over D1, with `schema` for relational queries. */
+	db: ReturnType<typeof drizzle<TSchema>>;
+};
+
+/**
+ * A fresh, fully-migrated in-memory D1 for one test file, wrapped in drizzle over `schema`. Each
+ * `migrations` entry is one SQL statement or a drizzle migration file's contents
+ * (`--> statement-breakpoint` separates its statements), applied in order. `frozenTime`, if given,
+ * freezes `Date` until `close()` so fixture data computed relative to "now" is stable. The clock
+ * stays frozen for the whole test file, so code that measures elapsed time with `Date.now()` (and
+ * `vi.waitFor`) sees it frozen too.
+ */
+export async function createD1TestDb<TSchema extends Record<string, unknown>>(
+	schema: TSchema,
+	migrations: readonly string[],
+	frozenTime?: Date
+): Promise<D1TestDb<TSchema>> {
+	let Miniflare: typeof MiniflareClass;
+	try {
+		({ Miniflare } = await import('miniflare'));
+	} catch (error) {
+		throw new Error(
+			'createD1TestDb needs the optional peer dependency "miniflare": add it to your devDependencies.',
+			{ cause: error }
+		);
+	}
+	if (frozenTime) {
+		vi.useFakeTimers({ toFake: ['Date'] });
+		vi.setSystemTime(frozenTime);
+	}
+	const miniflare = new Miniflare({
+		d1Databases: { DB: crypto.randomUUID() },
+		modules: true,
+		script: 'export default { fetch() { return new Response(null); } }',
+	});
+	const restoreClock = () => {
+		if (frozenTime) vi.useRealTimers();
+	};
+	try {
+		const d1 = (await miniflare.getD1Database('DB')) as unknown as D1Database;
+		const statements = migrations
+			.flatMap((migration) => migration.split('--> statement-breakpoint'))
+			.map((statement) => statement.trim())
+			.filter((statement) => statement.length > 0);
+		if (statements.length > 0) {
+			await d1.batch(statements.map((statement) => d1.prepare(statement)));
+		}
+		return {
+			close: async () => {
+				await miniflare.dispose();
+				restoreClock();
+			},
+			d1,
+			db: drizzle(d1, { schema }) as D1TestDb<TSchema>['db'],
+		};
+	} catch (error) {
+		// A bad migration must not leave workerd running, or the test run can hang.
+		await miniflare.dispose();
+		restoreClock();
+		throw error;
+	}
+}
+
+/**
+ * Wires `createD1TestDb` into a `describe` block's `beforeAll`/`afterAll`: call once at the top of
+ * the block, then read `.db` / `.d1` inside any `it()`. Every `it()` in the block shares the one
+ * database; use a separate `describe` for anything that needs its own. `seed` runs once after the
+ * migrations (fixtures). An app wraps this in its own `mockDb()` with its schema and migrations.
+ */
+export function mockD1<TSchema extends Record<string, unknown>>(options: {
+	frozenTime?: Date;
+	migrations: readonly string[];
+	schema: TSchema;
+	seed?: (handle: D1TestDb<TSchema>) => Promise<void>;
+}): { d1: D1Database; db: D1TestDb<TSchema>['db'] } {
+	// Populated by beforeAll before any it() in this describe block runs; the cast reflects that
+	// timing guarantee, not the object's real shape at declaration time.
+	const ctx = {} as { d1: D1Database; db: D1TestDb<TSchema>['db'] };
+	let handle: D1TestDb<TSchema>;
+
+	beforeAll(async () => {
+		handle = await createD1TestDb(options.schema, options.migrations, options.frozenTime);
+		ctx.d1 = handle.d1;
+		ctx.db = handle.db;
+		await options.seed?.(handle);
+	}, 60_000);
+
+	afterAll(async () => {
+		await handle?.close();
+	});
+
+	return ctx;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zeyolabs/kit",
-	"version": "2026.11.9",
+	"version": "2026.11.11",
 	"description": "Shared SvelteKit-on-Cloudflare server toolkit: remote-function wrappers, passwordless auth (magic link + passkeys), email over a send_email binding or SMTP, Cloudflare context, monitoring, storage clients, utils and the ESLint config.",
 	"type": "module",
 	"repository": {
@@ -48,6 +48,7 @@
 		"./cloudflare/*": "./cloudflare/*.ts",
 		"./cloudflare/context": "./cloudflare/context.ts",
 		"./cloudflare/amqp": "./cloudflare/amqp/client.ts",
+		"./cloudflare/d1/testing": "./cloudflare/d1/testing.ts",
 		"./cloudflare/dispatch": "./cloudflare/dispatch/client.ts",
 		"./cloudflare/email": "./cloudflare/email/client.ts",
 		"./cloudflare/email/dev": "./cloudflare/email/dev.ts",
@@ -118,6 +119,7 @@
 		"@sveltejs/kit": "^3.1.1",
 		"drizzle-orm": "^0.45.3",
 		"eslint": "^9.39.4",
+		"miniflare": "^4.20260730.0",
 		"vitest": "^4.1.11",
 		"zod": "^4.6.5"
 	},
@@ -131,6 +133,9 @@
 		"eslint": {
 			"optional": true
 		},
+		"miniflare": {
+			"optional": true
+		},
 		"vitest": {
 			"optional": true
 		}
@@ -147,6 +152,7 @@
 		"@types/snappyjs": "0.7.1",
 		"drizzle-orm": "0.45.3",
 		"eslint": "9.39.4",
+		"miniflare": "4.20260730.0",
 		"prettier": "3.9.9",
 		"svelte": "5.57.3",
 		"typescript": "6.0.3",

package/server/turnstile.ts

@@ -1,7 +1,10 @@
+import { FormResult } from '../utils/form';
+
+const SITEVERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+
 /**
  * Server-side verification of a Cloudflare Turnstile token against the siteverify API. Pure
- * `fetch`, no framework or binding dependency. Each app owns how it obtains the secret key and how
- * a rejection surfaces (see `apps/web/src/lib/server/turnstile.ts`).
+ * `fetch`, no framework or binding dependency. Prefer `Turnstile.verify` / `Turnstile.gate`.
  */
 export async function verifyTurnstile(
 	token: string,
@@ -10,10 +13,58 @@ export async function verifyTurnstile(
 ): Promise<boolean> {
 	const params = new URLSearchParams({ response: token, secret: secretKey });
 	if (ip) params.set('remoteip', ip);
-	const response = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
-		body: params,
-		method: 'POST',
-	});
+	const response = await fetch(SITEVERIFY_URL, { body: params, method: 'POST' });
 	const result = (await response.json()) as { success?: boolean };
 	return result.success === true;
 }
+
+/** Where a gate gets the request's secret key and client address. The app supplies both. */
+export type TurnstileGateOptions = {
+	/** Client address per call (SvelteKit's `getRequestEvent().getClientAddress()`); may be null. */
+	ip?: () => null | string | undefined;
+	/** The error shown when the check fails. */
+	message?: string;
+	/** The secret key: a string, or a function called per check (a Secrets Store binding, a loopback test key). */
+	secret: (() => Promise<string> | string) | string;
+};
+
+/**
+ * Turnstile helpers: a library (an object of static functions, no state, no bindings), like
+ * `Schema` and `FormResult`.
+ */
+export const Turnstile = {
+	/**
+	 * Gates a form handler behind Turnstile. The validated input carries `turnstileToken`; the gate
+	 * verifies it and strips it before calling the handler. A missing or rejected token returns
+	 * `FormResult.err(message)` and the handler never runs; a throwing `secret` or `fetch` also
+	 * stops the handler (fails closed).
+	 */
+	gate({
+		ip = () => null,
+		message = 'Bot check failed. Please try again.',
+		secret,
+	}: TurnstileGateOptions) {
+		return function gated<TData extends { turnstileToken: string }, TResult>(
+			handler: (data: Omit<TData, 'turnstileToken'>) => Promise<FormResult<TResult | void>>
+		): (data: TData) => Promise<FormResult<TResult | void>> {
+			return async ({ turnstileToken, ...data }: TData) => {
+				if (!(await Turnstile.verify(turnstileToken, ip(), secret))) return FormResult.err(message);
+				return handler(data as Omit<TData, 'turnstileToken'>);
+			};
+		};
+	},
+
+	/**
+	 * True only when siteverify accepts the token. An empty token is false without a request, and
+	 * `secret` is only resolved when there is a token to check.
+	 */
+	async verify(
+		token: string,
+		ip: null | string | undefined,
+		secret: (() => Promise<string> | string) | string
+	): Promise<boolean> {
+		if (!token) return false;
+		const key = typeof secret === 'function' ? await secret() : secret;
+		return verifyTurnstile(token, ip, key);
+	},
+};