@usequark/quark-core 2.6.0 → 2.6.2

package/README.md

@@ -4,15 +4,21 @@ Shared infrastructure for the Quark platform - authentication, job queues, error
 
 ## What's Included
 
-- **Authentication** - Auth.js-compatible config helpers (`createAuthConfig`, `requireAuth`, password hashing) plus framework-agnostic session guards (`requireSession`, `requireSessionRole`, `createAuthMiddleware`)
-- **Database** - Prisma client singleton (`createPrismaClient`), connection-string/pool helpers, and a `pingDatabase()` health check
-- **Admin** - Prisma schema introspection (`parseSchema`, `getModels`, `getEnums`, `coerceId`) for auto-generated admin UIs
-- **Job Queue** - BullMQ integration (`createQueue`, `createWorker`, `addJob`)
-- **Storage** - Local filesystem built in; S3/R2/MinIO via optional AWS SDK install in the app
-- **Errors** - Standardized error types (`ValidationError`, `NotFoundError`, `UnauthorizedError`, etc.)
-- **Utilities** - `retryAsync`, `deepMerge`, `randomString`, `sanitizeId`, `measureTime`, `memoize`
+- **Authentication** - Auth.js-compatible config helpers (`createAuthConfig`, `requireAuth`, password hashing) plus framework-agnostic session guards (`requireSession`, `requireSessionRole`, `createAuthMiddleware`), and role checks (`authorization.js`)
+- **Database** - `createPrismaClient(ClientClass)` builds a client from your generated Prisma class, plus connection-string/pool helpers, `pingDatabase()`, and `db-instrumentation`
+- **Job Queue** - BullMQ integration (`createQueue`, `createWorker`, `addJob`, queue definitions)
+- **Email** - Provider registry (`EmailProvider`, `registerEmailProvider`), `createEmailService`, and built-in templates
+- **Storage** - Local filesystem built in; S3 and any S3-compatible endpoint (R2, MinIO) via optional AWS SDK install in the app
+- **Metrics** - Prometheus-style registry (`createMetrics`, `metrics`, `httpRequestsTotal`, `jobQueueDepth`, `jobDuration`, and more)
+- **Health** - `runHealthChecks`, `createDefaultProbes`, `checkStorage`, `checkQueues`, `logHealthReport`
+- **Security** - CSRF tokens, rate limiting (in-memory with Redis fallback), file and multipart validation, request logging, error reporting
+- **Errors** - Standardized error types (`ValidationError`, `NotFoundError`, `UnauthorizedError`, `AppError`, and others)
+- **Utilities** - `retryAsync`, `deepMerge`, `randomString`, `sanitizeId`, `measureTime`, `memoize`, query builder, pagination, cache, locale helpers
 - **Validation** - Zod-based request body validation
+- **Payments and messaging** - Stripe client and webhook helpers, SMS provider
+- **Schema introspection** - `parseSchema`, `getModels`, `getEnums`, `getModelByName`, `coerceId`, `resetSchemaCache`
 - **Redis / Mail** - Connection helpers for Redis and local mail (Mailpit)
+- **Testing** - factories, mocks, and helpers under `@usequark/quark-core/testing`
 
 ## Usage
 
@@ -34,18 +40,30 @@ All modules are re-exported from the package root. See JSDoc comments on each fu
 
 Prefer a subpath when you want a smaller import graph or the browser-safe logger:
 
+Every subpath in `packages/core/package.json` `exports`, verified against the file:
+
 | Subpath | Contents |
 |---|---|
+| `@usequark/quark-core` | everything below, re-exported from the root |
 | `@usequark/quark-core/core` | errors, logger, validation, utils, pagination, csrf, rate limiter, file validation, db |
-| `@usequark/quark-core/db` | Prisma singleton, connection string, pool config, `pingDatabase()` |
-| `@usequark/quark-core/admin` | Prisma schema introspection helpers |
 | `@usequark/quark-core/auth` | auth config helpers + session guards |
 | `@usequark/quark-core/auth/middleware` | session guards only |
+| `@usequark/quark-core/db` | `createPrismaClient`, connection string, pool config, `pingDatabase()` |
+| `@usequark/quark-core/queue` | BullMQ queue and worker helpers |
+| `@usequark/quark-core/email` | `EmailProvider`, `registerEmailProvider`, `createEmailService` |
+| `@usequark/quark-core/errors` | error classes only |
+| `@usequark/quark-core/health` | health check runners and default probes |
+| `@usequark/quark-core/metrics` | metrics registry and default instruments |
 | `@usequark/quark-core/storage` | local adapter, storage factory, key/URL helpers, `createS3Storage` |
 | `@usequark/quark-core/storage/s3` | S3 adapter only |
-| `@usequark/quark-core/logger` | browser-safe logger |
-| `@usequark/quark-core/locale` | locale helpers |
+| `@usequark/quark-core/sms` | SMS provider |
 | `@usequark/quark-core/stripe` | Stripe client + webhook helpers |
+| `@usequark/quark-core/admin` | Prisma schema introspection helpers |
+| `@usequark/quark-core/locale` | locale helpers |
+| `@usequark/quark-core/logger` | browser-safe logger |
+| `@usequark/quark-core/testing` | test factories, mocks, helpers |
+
+`createPrismaClient` is a factory, not a singleton: it takes your generated Prisma `Client` class as its argument so core never depends on your generated client path.
 
 `@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`, `pg`, and `stripe` are optional peer dependencies. They are only loaded when the matching feature is used, so apps that do not use S3, `pingDatabase()`, or payments do not need them installed.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-core",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "description": "Core utilities for Quark apps: auth, BullMQ queues, Redis, email, storage, rate limiting, logging, and error handling",
   "keywords": [
     "quark",
@@ -32,6 +32,7 @@
     "./admin": "./src/admin.js",
     "./auth": "./src/auth/index.js",
     "./auth/middleware": "./src/auth/middleware.js",
+    "./csrf-client": "./src/csrf-client.js",
     "./db": "./src/db.js",
     "./email": "./src/email.js",
     "./errors": "./src/errors.js",

package/src/csrf-client.js

@@ -0,0 +1,130 @@
+/**
+ * @usequark/quark-core - CSRF Client Helpers
+ * Browser-safe companion to `csrf.js`, for the "use client" side of the
+ * double-submit handshake.
+ *
+ * ## Why this is a separate module
+ *
+ * `csrf.js` imports `node:crypto`. A client component cannot reach this module
+ * through the `@usequark/quark-core` barrel without dragging that Node builtin
+ * into the browser bundle, which fails the build. This file therefore imports
+ * nothing at all, and is published as its own subpath export:
+ *
+ * ```js
+ * import { getCsrfToken } from "@usequark/quark-core/csrf-client";
+ * ```
+ */
+
+/** Endpoint that mints a token and sets the matching cookie. */
+const DEFAULT_ENDPOINT = "/api/csrf";
+
+/**
+ * Cached tokens are treated as expired after this long.
+ *
+ * `/api/csrf` writes the cookie with a one-hour `maxAge`. A token cached past
+ * that point outlives the cookie it has to match, and the next write fails
+ * with "CSRF token not found" — a confusing message for what is really a stale
+ * token. Refetching ahead of the cookie's own expiry keeps the two in step.
+ */
+const TOKEN_TTL_MS = 50 * 60 * 1000;
+
+/** The cached token, and the timestamp at which it stops being usable. */
+let cachedToken = null;
+let cachedUntil = 0;
+
+/**
+ * The in-flight request, shared so that N callers racing on a cold cache make
+ * one HTTP request rather than N. Reset when it settles.
+ */
+let inflight = null;
+
+/**
+ * Bumped by `clearCsrfToken`. A request that started before the clear must not
+ * repopulate the cache with the token the caller just threw away.
+ */
+let generation = 0;
+
+/**
+ * Drops any cached token, forcing the next `getCsrfToken` to hit the endpoint.
+ *
+ * Only needed when the server has rotated the cookie underneath the client — a
+ * sign-out that clears cookies, or a 401 from a write that suggests the cached
+ * token and the cookie no longer agree. Ordinary expiry needs no call: the
+ * cache refetches itself.
+ *
+ * @returns {void}
+ */
+export function clearCsrfToken() {
+	generation++;
+	cachedToken = null;
+	cachedUntil = 0;
+	inflight = null;
+}
+
+/**
+ * Returns a CSRF token, fetching one if the cache is cold or stale.
+ *
+ * The caller must send the token in the `x-csrf-token` header of a mutating
+ * request; `/api/csrf` has also set the matching `httpOnly` cookie, and the
+ * server compares the two. Because that cookie is `SameSite=Strict`, a
+ * cross-site request never carries it and is rejected before the handler runs —
+ * which is why this token has to be obtainable *before* authentication.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.endpoint] - Token endpoint (default `/api/csrf`)
+ * @param {() => number} [options.now] - Clock override, for tests
+ * @returns {Promise<string>} The token to send as `x-csrf-token`
+ * @throws {Error} If the endpoint fails or returns no token
+ */
+export async function getCsrfToken(options = {}) {
+	const { endpoint = DEFAULT_ENDPOINT, now = Date.now } = options;
+
+	if (cachedToken && now() < cachedUntil) {
+		return cachedToken;
+	}
+
+	if (inflight) {
+		return inflight;
+	}
+
+	const startedAt = generation;
+
+	const request = (async () => {
+		const response = await fetch(endpoint, {
+			credentials: "same-origin",
+			headers: { accept: "application/json" },
+			cache: "no-store",
+		});
+
+		if (!response.ok) {
+			throw new Error(
+				`Could not fetch a CSRF token from ${endpoint}: ${response.status}`,
+			);
+		}
+
+		const body = await response.json();
+		if (!body?.csrfToken) {
+			throw new Error(`${endpoint} did not return a csrfToken`);
+		}
+
+		if (startedAt === generation) {
+			cachedToken = body.csrfToken;
+			cachedUntil = now() + TOKEN_TTL_MS;
+		}
+
+		return body.csrfToken;
+	})();
+
+	inflight = request;
+
+	// Both settle paths release the slot. `then(cleanup, cleanup)` rather than
+	// `finally`, which would leave the returned promise's rejection unhandled.
+	const cleanup = () => {
+		if (inflight === request) {
+			inflight = null;
+		}
+	};
+	request.then(cleanup, cleanup);
+
+	return request;
+}

package/src/csrf-client.test.js

@@ -0,0 +1,200 @@
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, mock, test } from "node:test";
+
+import { clearCsrfToken, getCsrfToken } from "./csrf-client.js";
+
+// The module reads the global `fetch` at call time and caches in module scope,
+// so every test drives both: a stubbed transport and an explicit clock.
+
+// Advances freely; `getCsrfToken` only ever compares against this.
+let clock;
+/** Every request the client made, as `{ endpoint, init }`. */
+let requests;
+/** Queue of responses/errors to hand back, one per fetch. */
+let responses;
+
+/** A JSON response shaped like `/api/csrf`. */
+function jsonResponse(body, status = 200) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" },
+	});
+}
+
+beforeEach(() => {
+	clock = 1_000_000;
+	requests = [];
+	responses = [];
+
+	mock.method(globalThis, "fetch", async (endpoint, init) => {
+		requests.push({ endpoint, init });
+		const next = responses.shift();
+		if (!next) {
+			throw new Error("test made an unscheduled fetch");
+		}
+		if (next instanceof Error) throw next;
+		return next;
+	});
+
+	clearCsrfToken();
+});
+
+afterEach(() => {
+	clearCsrfToken();
+	mock.restoreAll();
+});
+
+test("returns the token the endpoint issued", async () => {
+	responses.push(jsonResponse({ csrfToken: "token-abc" }));
+
+	const token = await getCsrfToken({ now: () => clock });
+
+	assert.equal(token, "token-abc");
+	assert.equal(requests.length, 1);
+	assert.equal(requests[0].endpoint, "/api/csrf");
+});
+
+test("asks for the cookie alongside the token", async () => {
+	// The whole scheme is double-submit: the server compares the header against
+	// the `csrf_token` cookie. A request that skipped credentials would leave
+	// the browser without the cookie and every later write would fail.
+	responses.push(jsonResponse({ csrfToken: "token-abc" }));
+
+	await getCsrfToken({ now: () => clock });
+
+	assert.equal(requests[0].init.credentials, "same-origin");
+	assert.equal(requests[0].init.cache, "no-store");
+});
+
+test("a second call reuses the cached token instead of refetching", async () => {
+	responses.push(jsonResponse({ csrfToken: "token-abc" }));
+
+	const first = await getCsrfToken({ now: () => clock });
+	const second = await getCsrfToken({ now: () => clock });
+
+	assert.equal(second, first);
+	assert.equal(requests.length, 1);
+});
+
+test("concurrent callers share one request", async () => {
+	// Three components mounting at once on a cold cache must not each mint a
+	// token; a burst of `/api/csrf` hits is also what a rate limiter would see.
+	responses.push(jsonResponse({ csrfToken: "token-abc" }));
+
+	const tokens = await Promise.all([
+		getCsrfToken({ now: () => clock }),
+		getCsrfToken({ now: () => clock }),
+		getCsrfToken({ now: () => clock }),
+	]);
+
+	assert.deepEqual(tokens, ["token-abc", "token-abc", "token-abc"]);
+	assert.equal(requests.length, 1);
+});
+
+test("refetches once the cached token has aged out", async () => {
+	responses.push(jsonResponse({ csrfToken: "first" }));
+	assert.equal(await getCsrfToken({ now: () => clock }), "first");
+
+	// The cookie this token must match is written with a one-hour maxAge, so a
+	// token still being served at that point is a token with no cookie behind it.
+	clock += 51 * 60 * 1000;
+	responses.push(jsonResponse({ csrfToken: "second" }));
+
+	assert.equal(await getCsrfToken({ now: () => clock }), "second");
+	assert.equal(requests.length, 2);
+});
+
+test("keeps serving the cached token right up to its expiry", async () => {
+	responses.push(jsonResponse({ csrfToken: "token-abc" }));
+	await getCsrfToken({ now: () => clock });
+
+	clock += 49 * 60 * 1000;
+	assert.equal(await getCsrfToken({ now: () => clock }), "token-abc");
+	assert.equal(requests.length, 1, "refetched well before the cache expired");
+});
+
+test("clearCsrfToken forces the next call back to the endpoint", async () => {
+	responses.push(jsonResponse({ csrfToken: "first" }));
+	await getCsrfToken({ now: () => clock });
+
+	clearCsrfToken();
+	responses.push(jsonResponse({ csrfToken: "second" }));
+
+	assert.equal(await getCsrfToken({ now: () => clock }), "second");
+	assert.equal(requests.length, 2);
+});
+
+test("a request already in flight does not resurrect a cleared token", async () => {
+	// The clear happens while the fetch is outstanding. Caching its response
+	// anyway would hand back the very token the caller discarded — and leave the
+	// cache holding a token whose cookie may since have been rotated away.
+	let release;
+	responses.push(
+		new Promise((resolve) => {
+			release = () => resolve(jsonResponse({ csrfToken: "stale" }));
+		}),
+	);
+
+	const pending = getCsrfToken({ now: () => clock });
+	clearCsrfToken();
+	release();
+	await pending;
+
+	responses.push(jsonResponse({ csrfToken: "fresh" }));
+	assert.equal(await getCsrfToken({ now: () => clock }), "fresh");
+});
+
+test("reports the status when the endpoint fails", async () => {
+	responses.push(jsonResponse({ error: "Unauthorized" }, 401));
+
+	await assert.rejects(
+		() => getCsrfToken({ now: () => clock }),
+		/Could not fetch a CSRF token from \/api\/csrf: 401/,
+	);
+});
+
+test("rejects a 200 that carries no token", async () => {
+	// A proxy that answers 200 with an error page, or a route that changed shape,
+	// would otherwise cache `undefined` and fail every later write with a
+	// confusing mismatch instead of here.
+	responses.push(jsonResponse({ error: "nope" }));
+
+	await assert.rejects(
+		() => getCsrfToken({ now: () => clock }),
+		/did not return a csrfToken/,
+	);
+});
+
+test("a failed fetch does not poison the cache", async () => {
+	responses.push(new Error("network down"));
+	await assert.rejects(() => getCsrfToken({ now: () => clock }));
+
+	responses.push(jsonResponse({ csrfToken: "recovered" }));
+	assert.equal(await getCsrfToken({ now: () => clock }), "recovered");
+	assert.equal(requests.length, 2);
+});
+
+test("a failed shared request rejects every waiter, once", async () => {
+	responses.push(jsonResponse({ error: "Unauthorized" }, 500));
+
+	const results = await Promise.allSettled([
+		getCsrfToken({ now: () => clock }),
+		getCsrfToken({ now: () => clock }),
+	]);
+
+	assert.deepEqual(
+		results.map((r) => r.status),
+		["rejected", "rejected"],
+	);
+	// The rejection has to be handled on the shared promise's own branch too, or
+	// it surfaces as an unhandled rejection rather than at the await site.
+	assert.equal(requests.length, 1);
+});
+
+test("honours a custom endpoint", async () => {
+	responses.push(jsonResponse({ csrfToken: "token-abc" }));
+
+	await getCsrfToken({ endpoint: "/api/csrf-token", now: () => clock });
+
+	assert.equal(requests[0].endpoint, "/api/csrf-token");
+});

package/src/csrf.js

@@ -56,7 +56,14 @@ export function validateCsrfToken(request, sessionToken) {
  *   2. Compare it against the `X-CSRF-Token` (or `CSRF-Token`) request header
  *      that the client attaches to every mutating request.
  *
- * NextAuth already handles CSRF for /api/auth/* routes, so those are skipped.
+ * NextAuth needs no exemption here. It validates its own CSRF token inside
+ * `handlers.POST`, and `app/api/auth/[...nextauth]/route.js` exports that
+ * handler directly — it is never wrapped in `withCsrfProtection`, so a request
+ * to `/api/auth/signin` or `/api/auth/callback/credentials` never reaches this
+ * function. The blanket `/api/auth/` skip that used to sit here was therefore
+ * protecting nothing, while silently disarming every hand-written route filed
+ * under that prefix — `/api/auth/register` included, whose wrapper had never
+ * run a check in its life.
  *
  * @param {Request} request - Next.js Request object
  * @returns {void}
@@ -64,17 +71,14 @@ export function validateCsrfToken(request, sessionToken) {
  */
 export function requireCsrfToken(request) {
 	const method = request.method;
-	const path = new URL(request.url).pathname;
 
 	// Skip CSRF check for:
 	// - Safe methods (GET, HEAD, OPTIONS)
-	// - NextAuth routes (they have their own CSRF protection)
 	// - Bearer-authenticated requests (e.g. mobile app) - CSRF exploits ambient
 	//   cookie credentials; an Authorization header is not sent automatically
 	//   by browsers, so cross-site forgery is not possible.
 	if (
 		["GET", "HEAD", "OPTIONS"].includes(method) ||
-		path.startsWith("/api/auth/") ||
 		request.headers.get("authorization")?.startsWith("Bearer ")
 	) {
 		return;
@@ -96,12 +100,29 @@ export function requireCsrfToken(request) {
 /**
  * Creates a CSRF-protected API route handler.
  * Wraps your handler and automatically validates CSRF tokens.
+ *
+ * A failed check produces a `401` Response rather than a thrown error. The check
+ * runs in this wrapper, outside the route handler's own try/catch, so a throw here
+ * escapes `handleError` entirely: the client got an unhandled rejection instead of
+ * the status code its fetch handling expects. Returning the Response here keeps the
+ * rejection path reserved for genuine faults.
+ *
  * @param {Function} handler - Your API route handler
  * @returns {Function} Wrapped handler with CSRF protection
  */
 export function withCsrfProtection(handler) {
 	return async (request, ...args) => {
-		requireCsrfToken(request);
+		try {
+			requireCsrfToken(request);
+		} catch (error) {
+			if (error instanceof UnauthorizedError) {
+				return Response.json(error.toJSON(), {
+					status: error.statusCode,
+					headers: { "Cache-Control": "no-store" },
+				});
+			}
+			throw error;
+		}
 		return handler(request, ...args);
 	};
 }

package/src/csrf.test.js

@@ -98,17 +98,58 @@ test("CSRF Module", async (t) => {
 		});
 	});
 
-	await t.test("requireCsrfToken skips NextAuth routes", () => {
+	await t.test(
+		"requireCsrfToken no longer skips /api/auth/ paths",
+		async () => {
+			// The exemption existed for NextAuth, and it was costing more than it
+			// bought: every hand-written route filed under that prefix inherited it.
+			// `/api/auth/register` is the one that mattered — its wrapper was inert.
+			// NextAuth itself is unaffected because `app/api/auth/[...nextauth]/route.js`
+			// exports `handlers.POST` directly and never calls `withCsrfProtection`,
+			// so no request to `/api/auth/signin` reaches this function at all.
+			const request = mockRequest({
+				method: "POST",
+				url: "http://localhost/api/auth/register",
+			});
+
+			assert.throws(() => requireCsrfToken(request), /CSRF token not found/);
+		},
+	);
+
+	await t.test("a NextAuth callback path is not exempted either", async () => {
+		// Guards the reasoning above: if a NextAuth request ever did reach this
+		// function, it would be rejected. That is correct, because it cannot
+		// happen - and if it ever starts happening, this fails loudly instead of
+		// silently relying on an exemption that no longer exists.
 		const request = mockRequest({
 			method: "POST",
-			url: "http://localhost/api/auth/signin",
+			url: "http://localhost/api/auth/callback/credentials",
 		});
 
-		assert.doesNotThrow(() => {
-			requireCsrfToken(request);
-		});
+		assert.throws(() => requireCsrfToken(request), /CSRF token not found/);
 	});
 
+	await t.test(
+		"a hand-written /api/auth/ route with a valid token passes",
+		async () => {
+			// The fix must narrow the exemption, not break the route. A matching
+			// cookie/header pair is all `/api/auth/register` ever needed.
+			const token = generateCsrfToken();
+			const request = mockRequest({
+				method: "POST",
+				url: "http://localhost/api/auth/register",
+				headers: {
+					"x-csrf-token": token,
+					cookie: `csrf_token=${encodeURIComponent(token)}`,
+				},
+			});
+
+			assert.doesNotThrow(() => {
+				requireCsrfToken(request);
+			});
+		},
+	);
+
 	await t.test("requireCsrfToken skips Bearer-authenticated requests", () => {
 		const request = mockRequest({
 			method: "POST",
@@ -166,4 +207,80 @@ test("CSRF Module", async (t) => {
 		assert.strictEqual(result.body, "success");
 		assert.strictEqual(result.request, request);
 	});
+
+	await t.test(
+		"withCsrfProtection returns 401 instead of throwing",
+		async () => {
+			// The check runs in the wrapper, outside the route handler's own
+			// try/catch, so a throw here escapes `handleError` and reaches the client
+			// as an unhandled rejection. The status code is what fetch handling expects.
+			const request = mockRequest({
+				method: "POST",
+				url: "http://localhost/api/posts",
+				headers: { "x-csrf-token": generateCsrfToken() },
+			});
+
+			let handlerCalled = false;
+			const protectedHandler = withCsrfProtection(async () => {
+				handlerCalled = true;
+				return { unreachable: true };
+			});
+
+			const response = await protectedHandler(request);
+
+			assert(response instanceof Response);
+			assert.strictEqual(response.status, 401);
+			assert.strictEqual(response.headers.get("Cache-Control"), "no-store");
+
+			const body = await response.json();
+			assert.strictEqual(body.code, "UNAUTHORIZED");
+			assert.strictEqual(body.statusCode, 401);
+			// The handler must not run on a rejected token.
+			assert.strictEqual(handlerCalled, false);
+		},
+	);
+
+	await t.test(
+		"withCsrfProtection returns 401 for a mismatched token",
+		async () => {
+			const token = generateCsrfToken();
+			const request = mockRequest({
+				method: "POST",
+				url: "http://localhost/api/posts",
+				headers: {
+					"x-csrf-token": "wrong-token-of-same-len",
+					cookie: `csrf_token=${encodeURIComponent(token)}`,
+				},
+			});
+
+			const protectedHandler = withCsrfProtection(async () => ({
+				unreachable: true,
+			}));
+			const response = await protectedHandler(request);
+
+			assert.strictEqual(response.status, 401);
+		},
+	);
+
+	await t.test(
+		"withCsrfProtection still rejects for a non-CSRF error",
+		async () => {
+			// Only UnauthorizedError is converted. Anything else from the check is a
+			// genuine fault and must keep propagating rather than being reported to the
+			// client as an authentication problem.
+			const request = mockRequest({ method: "POST" });
+			request.headers.get = () => {
+				throw new TypeError("headers.get exploded");
+			};
+
+			const protectedHandler = withCsrfProtection(async () => ({
+				unreachable: true,
+			}));
+
+			await assert.rejects(
+				() => protectedHandler(request),
+				/headers.get exploded/,
+			);
+		},
+	);
 });

package/src/db.js

@@ -3,7 +3,7 @@
  *
  * Shared Prisma client singleton, connection-string builder, pool config,
  * and a lightweight health-check ping.  These replace the per-project
- * re-implementations in Regina / Pawdora / Trenchmate.
+ * re-implementations that every app ends up writing by hand.
  *
  * Usage:
  *   import { createPrismaClient, getConnectionString, pingDatabase } from "@usequark/quark-core/db";

package/src/exports.test.js

@@ -7,6 +7,7 @@ import * as admin from "@usequark/quark-core/admin";
 import * as auth from "@usequark/quark-core/auth";
 import * as authMiddleware from "@usequark/quark-core/auth/middleware";
 import * as coreLight from "@usequark/quark-core/core";
+import * as csrfClient from "@usequark/quark-core/csrf-client";
 import * as db from "@usequark/quark-core/db";
 import * as email from "@usequark/quark-core/email";
 import * as errors from "@usequark/quark-core/errors";
@@ -111,6 +112,42 @@ test("subpath './logger' exports the browser-safe logger", () => {
 	assert.equal(typeof logger.createLogger, "function");
 });
 
+test("subpath './csrf-client' exports the browser-safe CSRF client", () => {
+	// Importable from a `"use client"` component. It must stay off the barrels
+	// (`.` and `./core`) because those re-export `csrf.js`, which imports
+	// `node:crypto` — reaching the client helper through either of them would
+	// put a Node builtin in the browser bundle and fail the build.
+	assert.equal(typeof csrfClient.getCsrfToken, "function");
+	assert.equal(typeof csrfClient.clearCsrfToken, "function");
+	assert.equal(core.getCsrfToken, undefined);
+	assert.equal(coreLight.getCsrfToken, undefined);
+});
+
+test("subpath './csrf-client' pulls in no Node builtins", async () => {
+	// The hazard is transitive, so checking this module's own source is not
+	// enough: assert the whole graph it loads stays free of `node:` imports.
+	const loaded = new Set();
+	const pending = ["./csrf-client.js"];
+
+	while (pending.length > 0) {
+		const relative = pending.pop();
+		const url = new URL(relative, import.meta.url);
+		if (loaded.has(url.href)) continue;
+		loaded.add(url.href);
+
+		const source = readFileSync(url, "utf-8");
+		assert.doesNotMatch(
+			source,
+			/from\s+["']node:/,
+			`${relative} imports a Node builtin`,
+		);
+
+		for (const match of source.matchAll(/from\s+["'](\.[^"']+)["']/g)) {
+			pending.push(new URL(match[1], url).href);
+		}
+	}
+});
+
 test("subpath './locale' exports locale utilities", () => {
 	assert.equal(typeof locale.getDefaultLocale, "function");
 	assert.equal(typeof locale.getSupportedLocales, "function");