@zeyolabs/kit 0.0.0-stage → 2026.11.5

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @zeyolabs/kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared server toolkit for SvelteKit 3 on Cloudflare Workers: remote-function wrappers
+(`Remote.Query/Cmd/Form`), errors and results, the per-request Cloudflare context
+(`runWithContext`, `workersEnv`), rate limiting, Turnstile, logging and monitoring, storage
+clients, utils, and the shared ESLint config.
+
+Published as source (TypeScript, no build step): the consuming SvelteKit app compiles it.
+
+## Install
+
+```
+pnpm add -E @zeyolabs/kit
+```
+
+Peer dependencies: `@sveltejs/kit` 3, `drizzle-orm`, `zod`, `@sentry/sveltekit`; `eslint`,
+`vitest`, `@electric-sql/pglite` and `@cloudflare/workers-types` only for the parts that use them.
+
+## Versions
+
+Date versions: `YYYY.M.D` (the release day in London; semver forbids leading zeros, so
+`2026.11.5`). One release per day.
+
+```
+pnpm release                     # sets the version, commits, tags vYYYY.M.D
+git push origin HEAD vYYYY.M.D   # the tag publishes to npm (publish.yaml)
+```
+
+Publishing uses npm trusted publishing: the package's npmjs.com settings trust this repo's
+`publish.yaml`, so no npm token is stored anywhere.
+
+## Developing against an app
+
+`pnpm link ../kit` in the app while working on both; publish, then pin the new version.
+
+## Checks
+
+`pnpm check`: prettier, eslint, `tsc` (source, not tests), vitest.

package/cloudflare/access.ts

@@ -0,0 +1,134 @@
+// Cloudflare Access: verify the signed `Cf-Access-Jwt-Assertion` header an Access-protected
+// Worker receives. Access already blocks unauthenticated requests at the edge; this is the
+// defence in depth the docs ask for, so the app still fails closed if the Access policy is ever
+// removed, or the Worker is reached some other way than through the protected hostname.
+// https://developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/validating-json/
+
+export type AccessConfig = {
+	/** The AUD tag of the Access application (a 64-char hex string, not a secret). */
+	aud: string;
+	/** e.g. `my-team.cloudflareaccess.com` */
+	teamDomain: string;
+};
+
+export type AccessIdentity = { email: string; sub: string };
+
+type Jwk = JsonWebKey & { kid?: string };
+
+export const ACCESS_JWT_HEADER = 'Cf-Access-Jwt-Assertion';
+
+const KEY_TTL_MS = 60 * 60 * 1000;
+const keyCache = new Map<string, { fetchedAt: number; keys: Jwk[] }>();
+
+export class AccessError extends Error {
+	override name = 'AccessError';
+}
+
+function decodePart<T>(part: string): T {
+	const base64 = part.replaceAll('-', '+').replaceAll('_', '/');
+	const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+	return JSON.parse(
+		new TextDecoder().decode(Uint8Array.from(atob(padded), (c) => c.charCodeAt(0)))
+	);
+}
+
+function decodeBytes(part: string): Uint8Array<ArrayBuffer> {
+	const base64 = part.replaceAll('-', '+').replaceAll('_', '/');
+	const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+	return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
+}
+
+async function fetchAccessKeys(teamDomain: string): Promise<Jwk[]> {
+	const response = await fetch(`https://${teamDomain}/cdn-cgi/access/certs`);
+	if (!response.ok)
+		throw new AccessError(`Could not load Access signing keys (${response.status})`);
+	const body = (await response.json()) as { keys?: Jwk[] };
+	return body.keys ?? [];
+}
+
+async function keyFor(
+	kid: string,
+	teamDomain: string,
+	loadKeys: (teamDomain: string) => Promise<Jwk[]>,
+	now: number
+): Promise<Jwk> {
+	const cached = keyCache.get(teamDomain);
+	const fresh = cached && now - cached.fetchedAt < KEY_TTL_MS;
+	let keys = fresh ? cached.keys : undefined;
+	let found = keys?.find((k) => k.kid === kid);
+	if (!found) {
+		// Unknown kid (or stale cache): Access rotates keys, so refetch once before giving up.
+		keys = await loadKeys(teamDomain);
+		keyCache.set(teamDomain, { fetchedAt: now, keys });
+		found = keys.find((k) => k.kid === kid);
+	}
+	if (!found) throw new AccessError('Unknown signing key');
+	return found;
+}
+
+/**
+ * Verifies an Access JWT (RS256 signature, issuer, audience, expiry) and returns who it is for.
+ * Throws `AccessError` for anything that is not a valid token for this application.
+ * `loadKeys` and `now` exist for tests.
+ */
+export async function verifyAccessJwt(
+	token: string,
+	config: AccessConfig,
+	{
+		loadKeys = fetchAccessKeys,
+		now = Date.now(),
+	}: { loadKeys?: (teamDomain: string) => Promise<Jwk[]>; now?: number } = {}
+): Promise<AccessIdentity> {
+	const parts = token.split('.');
+	if (parts.length !== 3) throw new AccessError('Malformed token');
+	const [rawHeader, rawPayload, rawSignature] = parts;
+
+	let header: { alg?: string; kid?: string };
+	let payload: {
+		aud?: string | string[];
+		email?: string;
+		exp?: number;
+		iss?: string;
+		nbf?: number;
+		sub?: string;
+	};
+	try {
+		header = decodePart(rawHeader);
+		payload = decodePart(rawPayload);
+	} catch {
+		throw new AccessError('Malformed token');
+	}
+	if (header.alg !== 'RS256' || !header.kid) throw new AccessError('Unsupported token');
+
+	const jwk = await keyFor(header.kid, config.teamDomain, loadKeys, now);
+	const key = await crypto.subtle.importKey(
+		'jwk',
+		jwk,
+		{ hash: 'SHA-256', name: 'RSASSA-PKCS1-v1_5' },
+		false,
+		['verify']
+	);
+	const valid = await crypto.subtle.verify(
+		'RSASSA-PKCS1-v1_5',
+		key,
+		decodeBytes(rawSignature),
+		new TextEncoder().encode(`${rawHeader}.${rawPayload}`)
+	);
+	if (!valid) throw new AccessError('Bad signature');
+
+	if (payload.iss !== `https://${config.teamDomain}`) throw new AccessError('Wrong issuer');
+	const audiences = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+	if (!audiences.includes(config.aud)) throw new AccessError('Wrong audience');
+	const seconds = Math.floor(now / 1000);
+	if (typeof payload.exp !== 'number' || payload.exp <= seconds) throw new AccessError('Expired');
+	if (typeof payload.nbf === 'number' && payload.nbf > seconds)
+		throw new AccessError('Not yet valid');
+	if (!payload.email || !payload.sub) throw new AccessError('Not a user token');
+
+	return { email: payload.email, sub: payload.sub };
+}
+
+/** Test helper: forget cached signing keys. */
+export function resetAccessKeyCache(): void {
+	keyCache.clear();
+}

package/cloudflare/amqp/client.ts

@@ -0,0 +1,276 @@
+const PROTOCOL_HEADER = new Uint8Array([0x41, 0x4d, 0x51, 0x50, 0, 0, 9, 1]);
+const FRAME_END = 0xce;
+const FRAME_TYPE_METHOD = 1;
+const FRAME_TYPE_HEADER = 2;
+const FRAME_TYPE_BODY = 3;
+
+const CLASS_CONNECTION = 10;
+const CLASS_CHANNEL = 20;
+const CLASS_BASIC = 60;
+
+type MethodFrame = { args: Uint8Array; channelId: number; classId: number; methodId: number };
+
+class ByteWriter {
+	private chunks: number[] = [];
+
+	build(): Uint8Array {
+		return new Uint8Array(this.chunks);
+	}
+
+	bytes(b: Uint8Array): this {
+		for (const byte of b) this.chunks.push(byte);
+		return this;
+	}
+
+	emptyTable(): this {
+		this.long(0);
+		return this;
+	}
+
+	long(v: number): this {
+		this.chunks.push((v >>> 24) & 0xff, (v >>> 16) & 0xff, (v >>> 8) & 0xff, v & 0xff);
+		return this;
+	}
+
+	longlong(v: number): this {
+		this.long(0);
+		this.long(v);
+		return this;
+	}
+
+	longstr(bytes: Uint8Array): this {
+		this.long(bytes.length);
+		this.bytes(bytes);
+		return this;
+	}
+
+	octet(v: number): this {
+		this.chunks.push(v & 0xff);
+		return this;
+	}
+
+	short(v: number): this {
+		this.chunks.push((v >>> 8) & 0xff, v & 0xff);
+		return this;
+	}
+
+	shortstr(s: string): this {
+		const bytes = new TextEncoder().encode(s);
+		this.octet(bytes.length);
+		this.bytes(bytes);
+		return this;
+	}
+}
+
+class ByteReader {
+	private buf = new Uint8Array(0);
+
+	constructor(private reader: ReadableStreamDefaultReader<Uint8Array>) {}
+
+	async readExact(n: number): Promise<Uint8Array> {
+		while (this.buf.length < n) {
+			const { done, value } = await this.reader.read();
+			if (done) throw new Error(`AMQP: connection closed while expecting ${n} bytes`);
+			const merged = new Uint8Array(this.buf.length + value.length);
+			merged.set(this.buf, 0);
+			merged.set(value, this.buf.length);
+			this.buf = merged;
+		}
+		const out = this.buf.slice(0, n);
+		this.buf = this.buf.slice(n);
+		return out;
+	}
+}
+
+function u16(b: Uint8Array, offset: number): number {
+	return (b[offset] << 8) | b[offset + 1];
+}
+
+function u32(b: Uint8Array, offset: number): number {
+	return ((b[offset] << 24) | (b[offset + 1] << 16) | (b[offset + 2] << 8) | b[offset + 3]) >>> 0;
+}
+
+async function writeFrame(
+	writer: WritableStreamDefaultWriter<Uint8Array>,
+	type: number,
+	channelId: number,
+	payload: Uint8Array
+): Promise<void> {
+	const header = new ByteWriter().octet(type).short(channelId).long(payload.length).build();
+	await writer.write(header);
+	await writer.write(payload);
+	await writer.write(new Uint8Array([FRAME_END]));
+}
+
+async function readFrame(
+	reader: ByteReader
+): Promise<{ channelId: number; payload: Uint8Array; type: number }> {
+	const header = await reader.readExact(7);
+	const type = header[0];
+	const channelId = u16(header, 1);
+	const size = u32(header, 3);
+	const payload = await reader.readExact(size);
+	const trailer = await reader.readExact(1);
+	if (trailer[0] !== FRAME_END) {
+		throw new Error(
+			`AMQP: malformed frame (expected 0xCE trailer, got 0x${trailer[0].toString(16)})`
+		);
+	}
+	return { channelId, payload, type };
+}
+
+async function readMethodFrame(reader: ByteReader): Promise<MethodFrame> {
+	const frame = await readFrame(reader);
+	if (frame.type !== FRAME_TYPE_METHOD) {
+		throw new Error(`AMQP: expected a method frame, got frame type ${frame.type}`);
+	}
+	return {
+		args: frame.payload.slice(4),
+		channelId: frame.channelId,
+		classId: u16(frame.payload, 0),
+		methodId: u16(frame.payload, 2),
+	};
+}
+
+function parseConnectionClose(args: Uint8Array): { replyCode: number; replyText: string } {
+	const replyCode = u16(args, 0);
+	const textLen = args[2];
+	const replyText = new TextDecoder().decode(args.slice(3, 3 + textLen));
+	return { replyCode, replyText };
+}
+
+export type AmqpSocket = {
+	readable: ReadableStream<Uint8Array>;
+	writable: WritableStream<Uint8Array>;
+};
+
+export type AmqpConfig = {
+	password: string;
+	username: string;
+	vpc: { connect(address: string): AmqpSocket };
+};
+
+export interface IAmqpClient {
+	publishJson(queue: string, body: unknown): Promise<void>;
+}
+
+export class AmqpClient implements IAmqpClient {
+	constructor(private readonly config: AmqpConfig) {}
+
+	async publishJson(queue: string, body: unknown): Promise<void> {
+		const { password, username, vpc } = this.config;
+		const socket = vpc.connect('127.0.0.1:5672');
+		const writer = socket.writable.getWriter();
+		const reader = new ByteReader(socket.readable.getReader());
+
+		try {
+			await writer.write(PROTOCOL_HEADER);
+
+			const start = await readMethodFrame(reader);
+			if (start.classId !== CLASS_CONNECTION || start.methodId !== 10) {
+				throw new Error(
+					`AMQP: expected Connection.Start, got class ${start.classId} method ${start.methodId}`
+				);
+			}
+
+			const saslResponse = new TextEncoder().encode(`\0${username}\0${password}`);
+			const startOk = new ByteWriter()
+				.short(CLASS_CONNECTION)
+				.short(11)
+				.emptyTable()
+				.shortstr('PLAIN')
+				.longstr(saslResponse)
+				.shortstr('en_US')
+				.build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 0, startOk);
+
+			const tune = await readMethodFrame(reader);
+			if (tune.classId !== CLASS_CONNECTION || tune.methodId !== 30) {
+				throw new Error(
+					`AMQP: expected Connection.Tune, got class ${tune.classId} method ${tune.methodId}`
+				);
+			}
+			const channelMax = u16(tune.args, 0);
+			const frameMax = u32(tune.args, 2);
+
+			const tuneOk = new ByteWriter()
+				.short(CLASS_CONNECTION)
+				.short(31)
+				.short(channelMax)
+				.long(frameMax)
+				.short(0)
+				.build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 0, tuneOk);
+
+			const open = new ByteWriter()
+				.short(CLASS_CONNECTION)
+				.short(40)
+				.shortstr('/')
+				.shortstr('')
+				.octet(0)
+				.build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 0, open);
+
+			const openOk = await readMethodFrame(reader);
+			if (openOk.classId !== CLASS_CONNECTION || openOk.methodId !== 41) {
+				if (openOk.classId === CLASS_CONNECTION && openOk.methodId === 50) {
+					const { replyCode, replyText } = parseConnectionClose(openOk.args);
+					throw new Error(`AMQP: connection rejected (${replyCode}): ${replyText}`);
+				}
+				throw new Error(
+					`AMQP: expected Connection.OpenOk, got class ${openOk.classId} method ${openOk.methodId}`
+				);
+			}
+
+			const channelOpen = new ByteWriter().short(CLASS_CHANNEL).short(10).shortstr('').build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 1, channelOpen);
+			const channelOpenOk = await readMethodFrame(reader);
+			if (channelOpenOk.classId !== CLASS_CHANNEL || channelOpenOk.methodId !== 11) {
+				throw new Error(
+					`AMQP: expected Channel.OpenOk, got class ${channelOpenOk.classId} method ${channelOpenOk.methodId}`
+				);
+			}
+
+			const publish = new ByteWriter()
+				.short(CLASS_BASIC)
+				.short(40)
+				.short(0)
+				.shortstr('')
+				.shortstr(queue)
+				.octet(0)
+				.build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 1, publish);
+
+			const bodyBytes = new TextEncoder().encode(JSON.stringify(body));
+			const header = new ByteWriter()
+				.short(CLASS_BASIC)
+				.short(0)
+				.longlong(bodyBytes.length)
+				.short(0x9000)
+				.shortstr('application/json')
+				.octet(2)
+				.build();
+			await writeFrame(writer, FRAME_TYPE_HEADER, 1, header);
+
+			await writeFrame(writer, FRAME_TYPE_BODY, 1, bodyBytes);
+
+			const close = new ByteWriter()
+				.short(CLASS_CONNECTION)
+				.short(50)
+				.short(200)
+				.shortstr('')
+				.short(0)
+				.short(0)
+				.build();
+			await writeFrame(writer, FRAME_TYPE_METHOD, 0, close);
+			const closeOk = await readMethodFrame(reader);
+			if (closeOk.classId !== CLASS_CONNECTION || closeOk.methodId !== 51) {
+				throw new Error(
+					`AMQP: expected Connection.CloseOk, got class ${closeOk.classId} method ${closeOk.methodId}`
+				);
+			}
+		} finally {
+			await writer.close().catch(() => {});
+		}
+	}
+}

package/cloudflare/amqp/testing.ts

@@ -0,0 +1,9 @@
+import type { IAmqpClient } from './client';
+
+export class FakeAmqpClient implements IAmqpClient {
+	readonly published: { body: unknown; queue: string }[] = [];
+
+	async publishJson(queue: string, body: unknown): Promise<void> {
+		this.published.push({ body, queue });
+	}
+}

package/cloudflare/context.ts

@@ -0,0 +1,66 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import { EnvStore } from '../utils/env';
+
+/** Per-request/invocation cache with teardown tracking, holding the raw runtime `env`. */
+export class ContextStore {
+	private cache = new Map<string, unknown>();
+	private closers: Array<() => Promise<void>> = [];
+
+	constructor(readonly env: object) {}
+
+	async closeAll(): Promise<void> {
+		await Promise.allSettled(this.closers.map((c) => c()));
+	}
+
+	once<T>(key: string, build: () => T, close?: (v: T) => Promise<void>): T {
+		if (!this.cache.has(key)) {
+			const v = build();
+			this.cache.set(key, v);
+			if (close) this.closers.push(() => close(v));
+		}
+		return this.cache.get(key) as T;
+	}
+
+	/** For a binding whose construction is app-specific and can't be built generically here. */
+	provide<T>(key: string, value: T): void {
+		this.cache.set(key, value);
+	}
+
+	require<T>(key: string): T {
+		if (!this.cache.has(key)) {
+			throw new Error(
+				`Context key "${key}" was never provided — call store.provide("${key}", …) first`
+			);
+		}
+		return this.cache.get(key) as T;
+	}
+}
+
+const als = new AsyncLocalStorage<ContextStore>();
+
+/** Wrap one request/invocation in this — whatever gets built during the call is closed
+ *  automatically when it returns. `secretNames`: the app's list of Secrets Store binding names. */
+export async function runWithContext<T>(
+	env: object,
+	secretNames: ReadonlySet<string>,
+	fn: () => Promise<T>
+): Promise<T> {
+	await EnvStore.resolve(env, secretNames);
+	const store = new ContextStore(env);
+	try {
+		return await als.run(store, fn);
+	} finally {
+		await store.closeAll();
+	}
+}
+
+export function currentContext(): ContextStore {
+	const store = als.getStore();
+	if (!store) {
+		throw new Error(
+			'No context — call runWithContext(env, fn) at the top of the request/invocation'
+		);
+	}
+	return store;
+}

package/cloudflare/dispatch/client.ts

@@ -0,0 +1,30 @@
+/** Structural shape of the dispatch queue binding — kept minimal so kit doesn't pull in a
+ *  Cloudflare Workers type it doesn't already depend on. */
+export type DispatchQueueBinding = { send(body: unknown): Promise<void> };
+
+export interface IDispatchClient<M> {
+	send(message: M): Promise<void>;
+}
+
+/**
+ * Hands a message to the `dispatch` queue, generic over the caller's own message union `M` — kit
+ * has no notion of what a dispatch type is called. Stamps `enqueuedAt` (unix seconds) on the way
+ * out, which is the one envelope field every consumer relies on and no producer should have to
+ * remember.
+ */
+export class DispatchClient<M extends { type: string }> implements IDispatchClient<M> {
+	constructor(private readonly queue: DispatchQueueBinding) {}
+
+	async send(message: M): Promise<void> {
+		await this.queue.send({ ...message, enqueuedAt: Math.floor(Date.now() / 1000) });
+	}
+}
+
+/** Used when no `DISPATCH_QUEUE` binding exists (local dev) — logs instead of delivering, so a
+ *  missing binding degrades the same way `DevPrometheusClient` does rather than throwing. */
+export class DevDispatchClient<M extends { type: string }> implements IDispatchClient<M> {
+	async send(message: M): Promise<void> {
+		console.info('[dispatch] no DISPATCH_QUEUE binding — dropping message', { type: message.type });
+		return Promise.resolve();
+	}
+}

package/cloudflare/email/client.ts

@@ -0,0 +1,77 @@
+import { createMimeMessage } from 'mimetext/browser';
+
+import { logger as defaultLogger, type LoggerClient } from '../../monitoring/logger/client';
+
+export type EmailAttachment = { base64Data: string; contentType: string; filename: string };
+
+export type EmailInput = {
+	attachments?: EmailAttachment[];
+	html: string;
+	subject: string;
+	to: string;
+};
+
+/** The shape of a Workers `send_email` binding. */
+export type EmailBinding = { send(message: unknown): Promise<unknown> };
+
+export interface IEmailClient {
+	/** Sends one message. Logs and returns `false` on failure instead of throwing. */
+	send(input: EmailInput): Promise<boolean>;
+}
+
+function buildRawEmail(
+	from: string,
+	fromName: string | undefined,
+	{ attachments, html, subject, to }: EmailInput
+): string {
+	const msg = createMimeMessage();
+	msg.setSender(fromName ? { addr: from, name: fromName } : { addr: from });
+	msg.setRecipient(to);
+	msg.setSubject(subject);
+	msg.addMessage({ contentType: 'text/html', data: html });
+	for (const attachment of attachments ?? []) {
+		msg.addAttachment({
+			contentType: attachment.contentType,
+			data: attachment.base64Data,
+			filename: attachment.filename,
+		});
+	}
+	return msg.asRaw();
+}
+
+/** Sends transactional email over a Workers `send_email` binding (Cloudflare Email Routing).
+ *  Use `DevEmailClient` where there's no binding. */
+export class EmailClient implements IEmailClient {
+	constructor(
+		private readonly config: {
+			binding: EmailBinding;
+			/** Envelope and header sender. */
+			from: string;
+			/** Display name next to `from`. */
+			fromName?: string;
+			logger?: LoggerClient;
+		}
+	) {}
+
+	/** Like `send`, but throws on failure — for callers that retry (queue consumers). */
+	async deliver(input: EmailInput): Promise<void> {
+		const { binding, from, fromName } = this.config;
+		// Dynamic: `cloudflare:email` only resolves inside the Workers runtime.
+		const { EmailMessage } = await import('cloudflare:email');
+		await binding.send(new EmailMessage(from, input.to, buildRawEmail(from, fromName, input)));
+	}
+
+	async send(input: EmailInput): Promise<boolean> {
+		try {
+			await this.deliver(input);
+			return true;
+		} catch (err) {
+			await (this.config.logger ?? defaultLogger).error(err, {
+				from: this.config.from,
+				subject: input.subject,
+				to: input.to,
+			});
+			return false;
+		}
+	}
+}

package/cloudflare/email/dev.ts

@@ -0,0 +1,10 @@
+import type { EmailInput, IEmailClient } from './client';
+
+/** Stands in for `EmailClient` where there's no `send_email` binding (local dev) — logs instead of
+ *  sending, so the message is still visible. */
+export class DevEmailClient implements IEmailClient {
+	async send({ subject, to }: EmailInput): Promise<boolean> {
+		console.log(`[email:dev] to=${to} subject=${subject}`);
+		return true;
+	}
+}

package/cloudflare/email/testing.ts

@@ -0,0 +1,13 @@
+import type { EmailInput, IEmailClient } from './client';
+
+/** Records every message passed to `send` instead of sending anything — for asserting what a
+ *  service emailed, without a mock binding. Set `succeeds = false` to simulate a delivery failure. */
+export class FakeEmailClient implements IEmailClient {
+	readonly sent: EmailInput[] = [];
+	succeeds = true;
+
+	async send(input: EmailInput): Promise<boolean> {
+		this.sent.push(input);
+		return this.succeeds;
+	}
+}