@usequark/quark-core 2.6.1 → 2.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-core",
-  "version": "2.6.1",
+  "version": "2.6.3",
   "description": "Core utilities for Quark apps: auth, BullMQ queues, Redis, email, storage, rate limiting, logging, and error handling",
   "keywords": [
     "quark",
@@ -32,14 +32,18 @@
     "./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",
+    "./email-templates": "./src/email-templates.js",
     "./errors": "./src/errors.js",
     "./health": "./src/health.js",
     "./locale": "./src/locale.js",
     "./logger": "./src/logger.js",
     "./metrics": "./src/metrics.js",
+    "./multipart": "./src/multipart.js",
     "./queue": "./src/queue/index.js",
+    "./redis": "./src/redis.js",
     "./sms": "./src/sms.js",
     "./storage": "./src/storage.js",
     "./storage/s3": "./src/storage-s3.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;

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",

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");