@usequark/quark-core 2.6.4 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-core",
-  "version": "2.6.4",
+  "version": "2.8.0",
   "description": "Core utilities for Quark apps: auth, BullMQ queues, Redis, email, storage, rate limiting, logging, and error handling",
   "keywords": [
     "quark",

package/src/auth/index.js

@@ -8,6 +8,7 @@ import { createLogger } from "../logger.js";
 
 export * from "./middleware.js";
 export * from "./password.js";
+export * from "./tokens.js";
 
 const logger = createLogger({ name: "auth" });
 

package/src/auth/tokens.js

@@ -0,0 +1,49 @@
+import crypto from "node:crypto";
+
+/**
+ * @usequark/quark-core - Verification Token Helpers
+ *
+ * The primitives behind email-verification and password-reset links, kept in
+ * one place so both flows agree on how a token is minted and how it is stored.
+ */
+
+/** 32 bytes of entropy, rendered as 64 hex characters. */
+export const DEFAULT_TOKEN_BYTES = 32;
+
+/**
+ * Generates a cryptographically random token for a one-time link.
+ *
+ * `randomBytes` is CSPRNG-backed — unlike `Math.random` or a timestamp, its
+ * output cannot be predicted from a sample. The token is the entire bearer
+ * credential in the emailed URL, so predictability is the whole attack.
+ *
+ * Hex rather than base64url because the token is both placed in a URL query
+ * string and stored in a database column; hex needs no percent-encoding and
+ * survives a copy/paste through an email client without case surprises.
+ *
+ * @param {number} [bytes=DEFAULT_TOKEN_BYTES] - Entropy in bytes
+ * @returns {string} Hex-encoded token
+ */
+export function generateToken(bytes = DEFAULT_TOKEN_BYTES) {
+	return crypto.randomBytes(bytes).toString("hex");
+}
+
+/**
+ * Hashes a token for storage.
+ *
+ * The database is not the place to keep a credential that grants account
+ * access: a leaked dump, a backup, or a read-only reporting replica would hand
+ * an attacker a working reset link for every pending request. What is stored is
+ * the SHA-256 digest, so a leaked row cannot be redeemed. The emailed, raw
+ * token is the only copy that can be.
+ *
+ * A plain SHA-256 is sufficient here, unlike for passwords: the input is 256
+ * bits of uniform randomness, so brute-forcing the preimage is infeasible and
+ * there is nothing for a slow, salted KDF to defend against.
+ *
+ * @param {string} token - Raw token
+ * @returns {string} Hex-encoded SHA-256 digest
+ */
+export function hashToken(token) {
+	return crypto.createHash("sha256").update(String(token)).digest("hex");
+}

package/src/auth/tokens.test.js

@@ -0,0 +1,42 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { DEFAULT_TOKEN_BYTES, generateToken, hashToken } from "./tokens.js";
+
+describe("generateToken", () => {
+	test("returns a hex string of 2 characters per byte", () => {
+		const token = generateToken();
+		assert.match(token, /^[0-9a-f]+$/);
+		assert.strictEqual(token.length, DEFAULT_TOKEN_BYTES * 2);
+	});
+
+	test("honours a custom byte length", () => {
+		assert.strictEqual(generateToken(16).length, 32);
+	});
+
+	test("does not repeat across calls", () => {
+		// A token used as a one-time link must not collide with another. 32 bytes
+		// makes a repeat effectively impossible; a regression to a counter, a
+		// timestamp, or a constant would surface here immediately.
+		const tokens = new Set(Array.from({ length: 100 }, () => generateToken()));
+		assert.strictEqual(tokens.size, 100);
+	});
+});
+
+describe("hashToken", () => {
+	test("is deterministic", () => {
+		assert.strictEqual(hashToken("abc"), hashToken("abc"));
+	});
+
+	test("produces a 64-character hex digest", () => {
+		assert.match(hashToken("abc"), /^[0-9a-f]{64}$/);
+	});
+
+	test("separates different inputs", () => {
+		assert.notStrictEqual(hashToken("abc"), hashToken("abd"));
+	});
+
+	test("does not embed the raw token", () => {
+		const token = "super-secret-reset-token";
+		assert.ok(!hashToken(token).includes(token));
+	});
+});

package/src/email-templates.js

@@ -132,3 +132,51 @@ export function passwordResetEmail(data) {
 
 	return { subject: `Reset your ${appName} password`, html, text };
 }
+
+/**
+ * Email verification email - sent to confirm ownership of an address
+ *
+ * @param {{ name?: string, verifyUrl: string, appName?: string, expiresIn?: string }} data
+ * @returns {{ subject: string, html: string, text: string }}
+ */
+export function emailVerificationEmail(data) {
+	if (!data?.verifyUrl) {
+		throw new Error("verifyUrl is required for email verification email");
+	}
+
+	const name = data.name ? escapeHtml(data.name) : "there";
+	const appName = data.appName || "Quark";
+	const expiresIn = data.expiresIn || "24 hours";
+
+	const html = layout(`
+    <h1 style="margin:0 0 16px;font-size:24px;color:#18181b">Confirm your email</h1>
+    <p style="color:#3f3f46;line-height:1.6;margin:0 0 16px">
+      Hi ${name}, confirm this address to finish setting up your ${escapeHtml(appName)} account.
+    </p>
+    <p style="text-align:center;margin:24px 0">
+      <a href="${escapeHtml(data.verifyUrl)}" style="display:inline-block;padding:12px 24px;background:#18181b;color:#fff;text-decoration:none;border-radius:6px;font-weight:500">
+        Verify email
+      </a>
+    </p>
+    <p style="color:#71717a;font-size:14px;margin:0 0 8px">
+      This link will expire in ${escapeHtml(expiresIn)}.
+    </p>
+    <p style="color:#71717a;font-size:14px;margin:0">
+      If you didn't create this account, you can safely ignore this email — no one can sign in as you until the address is confirmed.
+    </p>
+  `);
+
+	const text = [
+		`Confirm your email`,
+		"",
+		`Hi ${data.name || "there"}, confirm this address to finish setting up your ${appName} account.`,
+		"",
+		`Verify email: ${data.verifyUrl}`,
+		"",
+		`This link will expire in ${expiresIn}.`,
+		"",
+		"If you didn't create this account, you can safely ignore this email — no one can sign in as you until the address is confirmed.",
+	].join("\n");
+
+	return { subject: `Confirm your ${appName} email`, html, text };
+}

package/src/email-templates.test.js

@@ -1,6 +1,10 @@
 import assert from "node:assert";
 import { test } from "node:test";
-import { passwordResetEmail, welcomeEmail } from "./email-templates.js";
+import {
+	emailVerificationEmail,
+	passwordResetEmail,
+	welcomeEmail,
+} from "./email-templates.js";
 
 test("welcomeEmail", async (t) => {
 	await t.test("returns subject, html, and text", () => {
@@ -122,3 +126,63 @@ test("passwordResetEmail", async (t) => {
 		assert.ok(result.html.includes("</html>"));
 	});
 });
+
+test("emailVerificationEmail", async (t) => {
+	const validArgs = {
+		verifyUrl: "https://app.test/api/auth/verify-email?token=abc123",
+	};
+
+	await t.test("returns subject, html, and text", () => {
+		const result = emailVerificationEmail(validArgs);
+		assert.ok(result.subject);
+		assert.ok(result.html);
+		assert.ok(result.text);
+	});
+
+	await t.test("throws when verifyUrl is missing", () => {
+		assert.throws(() => emailVerificationEmail({}), /verifyUrl is required/);
+	});
+
+	await t.test("includes verify URL in html and text", () => {
+		const result = emailVerificationEmail(validArgs);
+		assert.ok(result.html.includes(validArgs.verifyUrl));
+		assert.ok(result.text.includes(validArgs.verifyUrl));
+	});
+
+	await t.test("uses default app name", () => {
+		const result = emailVerificationEmail(validArgs);
+		assert.ok(result.subject.includes("Quark"));
+	});
+
+	await t.test("uses custom app name", () => {
+		const result = emailVerificationEmail({ ...validArgs, appName: "MyApp" });
+		assert.ok(result.subject.includes("MyApp"));
+	});
+
+	await t.test("includes user name when provided", () => {
+		const result = emailVerificationEmail({ ...validArgs, name: "Bob" });
+		assert.ok(result.html.includes("Bob"));
+		assert.ok(result.text.includes("Bob"));
+	});
+
+	await t.test("uses default expiry time", () => {
+		const result = emailVerificationEmail(validArgs);
+		assert.ok(result.html.includes("24 hours"));
+		assert.ok(result.text.includes("24 hours"));
+	});
+
+	await t.test("escapes HTML in user name", () => {
+		const result = emailVerificationEmail({
+			...validArgs,
+			name: '<img src=x onerror="alert(1)">',
+		});
+		assert.ok(!result.html.includes("<img"));
+		assert.ok(result.html.includes("&lt;img"));
+	});
+
+	await t.test("wraps content in html layout", () => {
+		const result = emailVerificationEmail(validArgs);
+		assert.ok(result.html.includes("<!DOCTYPE html>"));
+		assert.ok(result.html.includes("</html>"));
+	});
+});

package/src/rate-limiter.js

@@ -99,7 +99,13 @@ class MemoryRateLimiter {
 class RedisRateLimiter {
 	constructor(redisClient, options = {}) {
 		this.redis = redisClient;
-		this.failOpen = options.failOpen ?? true;
+		// Fails CLOSED by default: if Redis errors mid-request, the request is
+		// treated as rate-limited rather than allowed through. A limiter that
+		// disables itself precisely when it is being hammered (the classic
+		// fail-open) is worst exactly when it matters. Opt back in with
+		// `failOpen: true` only if an outage-driven 429 is worse for you than
+		// an attacker-driven flood.
+		this.failOpen = options.failOpen ?? false;
 	}
 
 	/**

package/src/rate-limiter.test.js

@@ -127,4 +127,48 @@ test("Rate Limiter Module", async (t) => {
 		limiter.stopCleanup();
 		assert(limiter.cleanupInterval === null);
 	});
+
+	// A Redis-backed limiter that fails OPEN disables itself precisely when it
+	// is being hammered — Redis erroring under load is the moment an attacker
+	// most needs the limiter to hold. Default must be fail-CLOSED.
+	await t.test(
+		"Redis limiter fails CLOSED by default when Redis errors",
+		async () => {
+			const limiter = createRateLimiter({
+				type: "redis",
+				redisClient: {
+					eval: async () => {
+						throw new Error("redis down");
+					},
+				},
+			});
+
+			const result = await limiter.checkLimit("k", 100, 60000);
+			assert.strictEqual(
+				result.limited,
+				true,
+				"must block, not allow, on error",
+			);
+			assert.strictEqual(result.remaining, 0);
+		},
+	);
+
+	await t.test(
+		"Redis limiter can opt back into fail-open explicitly",
+		async () => {
+			const limiter = createRateLimiter({
+				type: "redis",
+				failOpen: true,
+				redisClient: {
+					eval: async () => {
+						throw new Error("redis down");
+					},
+				},
+			});
+
+			const result = await limiter.checkLimit("k", 100, 60000);
+			assert.strictEqual(result.limited, false);
+			assert.strictEqual(result.remaining, 100);
+		},
+	);
 });