@techstream/quark-core 1.1.0

package/src/cache.test.js

@@ -0,0 +1,217 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+import { createCache } from "./cache.js";
+
+/**
+ * Creates a mock Redis client backed by a Map.
+ * Provides get, set, del, keys, and expire methods.
+ */
+function createMockRedis() {
+	const store = new Map();
+	const expires = new Map();
+
+	return {
+		store,
+		expires,
+
+		async get(key) {
+			return store.has(key) ? store.get(key) : null;
+		},
+
+		async set(key, value, ...args) {
+			store.set(key, value);
+			// Support atomic SET key value EX seconds
+			if (args[0] === "EX" && args[1] != null) {
+				expires.set(key, args[1]);
+			}
+		},
+
+		async del(key) {
+			store.delete(key);
+			expires.delete(key);
+		},
+
+		async scan(cursor, ...args) {
+			// Simple mock: return all matching keys in one batch
+			const matchIdx = args.indexOf("MATCH");
+			const pattern = matchIdx !== -1 ? args[matchIdx + 1] : "*";
+			const regex = new RegExp(
+				`^${pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\*/g, ".*")}$`,
+			);
+			const keys = [...store.keys()].filter((k) => regex.test(k));
+			return ["0", keys];
+		},
+
+		async expire(key, seconds) {
+			expires.set(key, seconds);
+		},
+	};
+}
+
+describe("createCache", () => {
+	let redis;
+	let cache;
+
+	beforeEach(() => {
+		redis = createMockRedis();
+		cache = createCache(redis, { prefix: "test:", defaultTTL: 60 });
+	});
+
+	describe("get", () => {
+		it("returns null for a missing key", async () => {
+			const result = await cache.get("nonexistent");
+			assert.equal(result, null);
+		});
+
+		it("returns parsed JSON for an existing key", async () => {
+			redis.store.set("test:hello", JSON.stringify({ a: 1 }));
+			const result = await cache.get("hello");
+			assert.deepEqual(result, { a: 1 });
+		});
+
+		it("returns null for invalid JSON", async () => {
+			redis.store.set("test:bad", "not-json{");
+			const result = await cache.get("bad");
+			assert.equal(result, null);
+		});
+	});
+
+	describe("set", () => {
+		it("round-trips JSON values through set/get", async () => {
+			const data = { users: [1, 2, 3], active: true };
+			await cache.set("data", data);
+			const result = await cache.get("data");
+			assert.deepEqual(result, data);
+		});
+
+		it("passes TTL to Redis expire", async () => {
+			await cache.set("key", "value", 120);
+			assert.equal(redis.expires.get("test:key"), 120);
+		});
+
+		it("uses defaultTTL when no TTL is provided", async () => {
+			await cache.set("key", "value");
+			assert.equal(redis.expires.get("test:key"), 60);
+		});
+	});
+
+	describe("del", () => {
+		it("removes a key", async () => {
+			await cache.set("gone", "bye");
+			await cache.del("gone");
+			const result = await cache.get("gone");
+			assert.equal(result, null);
+		});
+	});
+
+	describe("invalidate", () => {
+		it("deletes all keys matching a pattern", async () => {
+			await cache.set("user:1", "alice");
+			await cache.set("user:2", "bob");
+			await cache.set("post:1", "hello");
+
+			await cache.invalidate("user:*");
+
+			assert.equal(await cache.get("user:1"), null);
+			assert.equal(await cache.get("user:2"), null);
+			assert.notEqual(await cache.get("post:1"), null);
+		});
+
+		it("does nothing when no keys match", async () => {
+			await cache.set("a", 1);
+			await cache.invalidate("zzz:*");
+			assert.deepEqual(await cache.get("a"), 1);
+		});
+	});
+
+	describe("getOrSet", () => {
+		it("calls factory on cache miss and caches the result", async () => {
+			let called = 0;
+			const factory = async () => {
+				called++;
+				return { fresh: true };
+			};
+
+			const result = await cache.getOrSet("miss", factory);
+			assert.deepEqual(result, { fresh: true });
+			assert.equal(called, 1);
+
+			// Value should now be cached
+			const cached = await cache.get("miss");
+			assert.deepEqual(cached, { fresh: true });
+		});
+
+		it("returns cached value without calling factory on hit", async () => {
+			await cache.set("hit", { cached: true });
+
+			let called = 0;
+			const factory = async () => {
+				called++;
+				return { fresh: true };
+			};
+
+			const result = await cache.getOrSet("hit", factory);
+			assert.deepEqual(result, { cached: true });
+			assert.equal(called, 0);
+		});
+	});
+
+	describe("wrap", () => {
+		it("creates a cached function", async () => {
+			let calls = 0;
+			const expensive = async (x) => {
+				calls++;
+				return x * 2;
+			};
+
+			const cachedFn = cache.wrap(expensive, { keyPrefix: "double" });
+
+			const first = await cachedFn(5);
+			assert.equal(first, 10);
+			assert.equal(calls, 1);
+
+			const second = await cachedFn(5);
+			assert.equal(second, 10);
+			assert.equal(calls, 1); // Cache hit — factory not called again
+		});
+
+		it("uses keyGenerator when provided", async () => {
+			let _calls = 0;
+			const fn = async (a, b) => {
+				_calls++;
+				return a + b;
+			};
+
+			const cachedFn = cache.wrap(fn, {
+				keyPrefix: "sum",
+				keyGenerator: (a, b) => `${a}+${b}`,
+			});
+
+			const result = await cachedFn(2, 3);
+			assert.equal(result, 5);
+
+			// Verify the custom key was used
+			const storedKey = "test:sum:2+3";
+			assert.ok(redis.store.has(storedKey));
+		});
+
+		it("caches different args separately", async () => {
+			let calls = 0;
+			const fn = async (x) => {
+				calls++;
+				return x * 3;
+			};
+
+			const cachedFn = cache.wrap(fn, { keyPrefix: "triple" });
+
+			assert.equal(await cachedFn(1), 3);
+			assert.equal(await cachedFn(2), 6);
+			assert.equal(calls, 2);
+
+			// Both should now be cached
+			assert.equal(await cachedFn(1), 3);
+			assert.equal(await cachedFn(2), 6);
+			assert.equal(calls, 2);
+		});
+	});
+});

package/src/csrf.js

@@ -0,0 +1,118 @@
+/**
+ * @techstream/quark-core - CSRF Protection Module
+ * Provides CSRF token generation and validation for API routes
+ */
+
+import crypto from "node:crypto";
+import { UnauthorizedError } from "./errors.js";
+
+/**
+ * Generates a cryptographically secure CSRF token
+ * @returns {string} CSRF token
+ */
+export function generateCsrfToken() {
+	return crypto.randomBytes(32).toString("base64");
+}
+
+/**
+ * Validates CSRF token from request headers
+ * @param {Request} request - Next.js Request object
+ * @param {string} sessionToken - Expected CSRF token from session/cookie
+ * @throws {UnauthorizedError} If CSRF token is missing or invalid
+ * @returns {boolean} True if valid
+ */
+export function validateCsrfToken(request, sessionToken) {
+	const headerToken =
+		request.headers.get("x-csrf-token") || request.headers.get("csrf-token");
+
+	if (!headerToken) {
+		throw new UnauthorizedError("CSRF token missing");
+	}
+
+	if (!sessionToken) {
+		throw new UnauthorizedError("No CSRF token in session");
+	}
+
+	// Constant-time comparison to prevent timing attacks
+	const headerBuf = Buffer.from(headerToken);
+	const sessionBuf = Buffer.from(sessionToken);
+
+	if (
+		headerBuf.length !== sessionBuf.length ||
+		!crypto.timingSafeEqual(headerBuf, sessionBuf)
+	) {
+		throw new UnauthorizedError("Invalid CSRF token");
+	}
+
+	return true;
+}
+
+/**
+ * Middleware to require CSRF token for state-changing methods.
+ *
+ * Validation flow:
+ *   1. Read the expected token from the `csrf_token` HTTP-only cookie
+ *      (set by the `/api/csrf` endpoint).
+ *   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.
+ *
+ * @param {Request} request - Next.js Request object
+ * @returns {void}
+ * @throws {UnauthorizedError} If CSRF validation fails
+ */
+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)
+	if (
+		["GET", "HEAD", "OPTIONS"].includes(method) ||
+		path.startsWith("/api/auth/")
+	) {
+		return;
+	}
+
+	// Read the expected token from the HTTP-only cookie
+	const cookieHeader = request.headers.get("cookie") || "";
+	const cookieToken = parseCookieValue(cookieHeader, "csrf_token");
+
+	if (!cookieToken) {
+		throw new UnauthorizedError(
+			"CSRF token not found — call GET /api/csrf first",
+		);
+	}
+
+	validateCsrfToken(request, cookieToken);
+}
+
+/**
+ * Creates a CSRF-protected API route handler.
+ * Wraps your handler and automatically validates CSRF tokens.
+ * @param {Function} handler - Your API route handler
+ * @returns {Function} Wrapped handler with CSRF protection
+ */
+export function withCsrfProtection(handler) {
+	return async (request, ...args) => {
+		requireCsrfToken(request);
+		return handler(request, ...args);
+	};
+}
+
+/**
+ * Parse a single cookie value from a raw Cookie header string.
+ * @param {string} cookieHeader - Raw `Cookie` header value
+ * @param {string} name - Cookie name to look up
+ * @returns {string|undefined}
+ */
+function parseCookieValue(cookieHeader, name) {
+	const match = cookieHeader
+		.split(";")
+		.map((c) => c.trim())
+		.find((c) => c.startsWith(`${name}=`));
+
+	return match ? decodeURIComponent(match.slice(name.length + 1)) : undefined;
+}

package/src/csrf.test.js

@@ -0,0 +1,157 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import {
+	generateCsrfToken,
+	requireCsrfToken,
+	validateCsrfToken,
+	withCsrfProtection,
+} from "../src/csrf.js";
+
+/**
+ * Creates a mock Request-like object for testing.
+ * @param {Object} opts
+ * @param {string} [opts.method="GET"]
+ * @param {string} [opts.url="http://localhost/api/test"]
+ * @param {Record<string, string>} [opts.headers={}] — lowercase header names
+ */
+function mockRequest({
+	method = "GET",
+	url = "http://localhost/api/test",
+	headers = {},
+} = {}) {
+	const map = new Map(Object.entries(headers));
+	return {
+		method,
+		url,
+		headers: {
+			get(key) {
+				return map.get(key) ?? null;
+			},
+		},
+	};
+}
+
+test("CSRF Module", async (t) => {
+	await t.test("generateCsrfToken creates a secure token", () => {
+		const token1 = generateCsrfToken();
+		const token2 = generateCsrfToken();
+
+		assert(token1.length > 0);
+		assert(token2.length > 0);
+		assert(token1 !== token2, "Tokens should be unique");
+	});
+
+	await t.test("validateCsrfToken accepts valid token", () => {
+		const token = generateCsrfToken();
+		const request = mockRequest({ headers: { "x-csrf-token": token } });
+
+		assert.doesNotThrow(() => {
+			validateCsrfToken(request, token);
+		});
+	});
+
+	await t.test("validateCsrfToken rejects missing header token", () => {
+		const token = generateCsrfToken();
+		const request = mockRequest();
+
+		assert.throws(
+			() => validateCsrfToken(request, token),
+			/CSRF token missing/,
+		);
+	});
+
+	await t.test("validateCsrfToken rejects missing session token", () => {
+		const request = mockRequest({ headers: { "x-csrf-token": "some-token" } });
+
+		assert.throws(
+			() => validateCsrfToken(request, null),
+			/No CSRF token in session/,
+		);
+	});
+
+	await t.test("validateCsrfToken rejects mismatched tokens", () => {
+		const token = generateCsrfToken();
+		const request = mockRequest({
+			headers: { "x-csrf-token": "wrong-token-of-same-len" },
+		});
+
+		assert.throws(
+			() => validateCsrfToken(request, token),
+			/Invalid CSRF token/,
+		);
+	});
+
+	await t.test("validateCsrfToken rejects tokens of different lengths", () => {
+		const request = mockRequest({ headers: { "x-csrf-token": "short" } });
+
+		assert.throws(
+			() => validateCsrfToken(request, "a-much-longer-session-token"),
+			/Invalid CSRF token/,
+		);
+	});
+
+	await t.test("requireCsrfToken skips GET requests", () => {
+		const request = mockRequest({ method: "GET" });
+
+		assert.doesNotThrow(() => {
+			requireCsrfToken(request);
+		});
+	});
+
+	await t.test("requireCsrfToken skips NextAuth routes", () => {
+		const request = mockRequest({
+			method: "POST",
+			url: "http://localhost/api/auth/signin",
+		});
+
+		assert.doesNotThrow(() => {
+			requireCsrfToken(request);
+		});
+	});
+
+	await t.test("requireCsrfToken validates POST with cookie token", () => {
+		const token = generateCsrfToken();
+		const request = mockRequest({
+			method: "POST",
+			url: "http://localhost/api/posts",
+			headers: {
+				"x-csrf-token": token,
+				cookie: `csrf_token=${encodeURIComponent(token)}; other=value`,
+			},
+		});
+
+		assert.doesNotThrow(() => {
+			requireCsrfToken(request);
+		});
+	});
+
+	await t.test("requireCsrfToken throws when cookie is missing", () => {
+		const token = generateCsrfToken();
+		const request = mockRequest({
+			method: "POST",
+			url: "http://localhost/api/posts",
+			headers: { "x-csrf-token": token },
+		});
+
+		assert.throws(() => requireCsrfToken(request), /CSRF token not found/);
+	});
+
+	await t.test("withCsrfProtection wraps handler", async () => {
+		const token = generateCsrfToken();
+		const request = mockRequest({
+			method: "POST",
+			url: "http://localhost/api/posts",
+			headers: {
+				"x-csrf-token": token,
+				cookie: `csrf_token=${encodeURIComponent(token)}`,
+			},
+		});
+
+		const handler = async (req) => ({ body: "success", request: req });
+		const protectedHandler = withCsrfProtection(handler);
+		const result = await protectedHandler(request);
+
+		assert.strictEqual(result.body, "success");
+		assert.strictEqual(result.request, request);
+	});
+});

package/src/email.js

@@ -0,0 +1,140 @@
+/**
+ * @techstream/quark-core - Email Service
+ * Supports SMTP (Nodemailer) and Resend providers
+ */
+
+import { getMailhogSmtpConfig } from "./mailhog.js";
+
+/**
+ * Create an SMTP-based email sender using Nodemailer
+ */
+async function createSmtpTransport() {
+	const nodemailer = await import("nodemailer");
+
+	// Use explicit SMTP config if provided, otherwise fall back to Mailhog
+	const host = process.env.SMTP_HOST;
+	const port = process.env.SMTP_PORT;
+
+	let transportConfig;
+
+	if (host && port) {
+		// Production SMTP configuration
+		transportConfig = {
+			host,
+			port: parseInt(port, 10),
+			secure: process.env.SMTP_SECURE === "true",
+			connectionTimeout: 10_000,
+			greetingTimeout: 10_000,
+			socketTimeout: 10_000,
+			...(process.env.SMTP_USER && {
+				auth: {
+					user: process.env.SMTP_USER,
+					pass: process.env.SMTP_PASSWORD,
+				},
+			}),
+		};
+	} else {
+		// Development: use Mailhog
+		const mailhogConfig = getMailhogSmtpConfig();
+		transportConfig = {
+			host: mailhogConfig.host,
+			port: mailhogConfig.port,
+			secure: false,
+			connectionTimeout: 10_000,
+			greetingTimeout: 10_000,
+			socketTimeout: 10_000,
+		};
+	}
+
+	return nodemailer.default.createTransport(transportConfig);
+}
+
+/**
+ * Send email via Resend HTTP API
+ */
+async function sendViaResend(from, to, subject, html, text) {
+	const apiKey = process.env.RESEND_API_KEY;
+	if (!apiKey) {
+		throw new Error("RESEND_API_KEY environment variable is required when EMAIL_PROVIDER=resend");
+	}
+
+	const response = await fetch("https://api.resend.com/emails", {
+		method: "POST",
+		headers: {
+			"Authorization": `Bearer ${apiKey}`,
+			"Content-Type": "application/json",
+		},
+		body: JSON.stringify({
+			from,
+			to: Array.isArray(to) ? to : [to],
+			subject,
+			html,
+			...(text && { text }),
+		}),
+		signal: AbortSignal.timeout(10_000),
+	});
+
+	if (!response.ok) {
+		const error = await response.json().catch(() => ({ message: response.statusText }));
+		throw new Error(`Resend API error: ${error.message || response.statusText}`);
+	}
+
+	return response.json();
+}
+
+/**
+ * Create an email service instance
+ * 
+ * @param {Object} [options]
+ * @param {string} [options.provider] - "smtp" or "resend" (defaults to EMAIL_PROVIDER env var or "smtp")
+ * @param {string} [options.from] - Sender address (defaults to EMAIL_FROM env var)
+ * @returns {{ sendEmail: (to: string|string[], subject: string, html: string, text?: string) => Promise<Object> }}
+ */
+export function createEmailService(options = {}) {
+	const provider = options.provider || process.env.EMAIL_PROVIDER || "smtp";
+	const from = options.from || process.env.EMAIL_FROM || "Quark <noreply@localhost>";
+
+	let smtpTransport = null;
+
+	return {
+		/**
+		 * Send an email
+		 * @param {string|string[]} to - Recipient email(s)
+		 * @param {string} subject - Email subject
+		 * @param {string} html - HTML body
+		 * @param {string} [text] - Plain text body (optional)
+		 * @returns {Promise<Object>} Send result
+		 */
+		async sendEmail(to, subject, html, text) {
+			// Input validation
+			if (!to || (typeof to === "string" && !to.trim())) {
+				throw new Error("Email 'to' address is required");
+			}
+			if (!subject || typeof subject !== "string" || !subject.trim()) {
+				throw new Error("Email 'subject' is required");
+			}
+			if (!html || typeof html !== "string" || !html.trim()) {
+				throw new Error("Email 'html' body is required");
+			}
+
+			if (provider === "resend") {
+				return sendViaResend(from, to, subject, html, text);
+			}
+
+			// SMTP (Nodemailer) — default
+			if (!smtpTransport) {
+				smtpTransport = await createSmtpTransport();
+			}
+
+			const result = await smtpTransport.sendMail({
+				from,
+				to: Array.isArray(to) ? to.join(", ") : to,
+				subject,
+				html,
+				...(text && { text }),
+			});
+
+			return { id: result.messageId, ...result };
+		},
+	};
+}