@usequark/quark-core 2.5.4

package/src/csrf.js

@@ -0,0 +1,122 @@
+/**
+ * @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)
+	// - 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;
+	}
+
+	// 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,169 @@
+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 skips Bearer-authenticated requests", () => {
+		const request = mockRequest({
+			method: "POST",
+			url: "http://localhost/api/device/register",
+			headers: { authorization: "Bearer some-jwt-token" },
+		});
+
+		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/db-instrumentation.js

@@ -0,0 +1,281 @@
+/**
+ * @techstream/quark-core — Database Instrumentation Module
+ *
+ * Schema-agnostic Prisma $extends middleware that monitors query execution
+ * times and logs slow queries. All query arguments are automatically masked
+ * to prevent sensitive data (passwords, tokens, hashes) from reaching logs.
+ *
+ * Agnostic by design: no project-specific thresholds or resource limits are
+ * hardcoded. All configuration comes from environment variables.
+ *
+ * Usage in client.js:
+ *
+ *   import { createDbInstrumentation } from "@techstream/quark-core";
+ *   const base = new PrismaClient({ ... });
+ *   const ext = createDbInstrumentation();
+ *   if (ext) prisma = base.$extends(ext);
+ */
+
+import { createLogger } from "./logger.js";
+
+const log = createLogger("db:instrumentation");
+
+// ── Sensitive field patterns — anything matching is redacted ────────
+const SENSITIVE_FIELD_PATTERNS = [
+	/^passw(?:or)?d$/i,
+	/^secret$/i,
+	/^token$/i,
+	/^api[_-]?key/i,
+	/^auth[_-]?token/i,
+	/^refresh[_-]?token/i,
+	/^access[_-]?token/i,
+	/^session[_-]?token/i,
+	/^reset[_-]?token/i,
+	/^verify[_-]?token/i,
+	/^csrf[_-]?token/i,
+	/^hash(?:ed)?$/i,
+	/^pin$/i,
+	/^otp$/i,
+	/^otp[_-]?secret$/i,
+	/^totp[_-]?secret$/i,
+	/^recovery[_-]?code/i,
+	/^private[_-]?key/i,
+	/^ssh[_-]?key/i,
+	/^pem$/i,
+	/^certificate$/i,
+	/^id[_-]?token/i,
+	/^code[_-]?verifier$/i,
+	/^code[_-]?challenge$/i,
+	/^nonce$/i,
+	/^signature$/i,
+	/^bearer$/i,
+	/^authorization$/i,
+	/^cookie$/i,
+	/^set[_-]?cookie/i,
+	/^x[_-]?csrf[_-]?token/i,
+	/^x[_-]?xsrf[_-]?token/i,
+	/^stripe[_-]?secret/i,
+	/^stripe[_-]?key/i,
+];
+
+/** Value that appears in logs in place of a redacted field. */
+const REDACTED_PLACEHOLDER = "[REDACTED]";
+
+/** Default slow-query threshold in milliseconds. */
+const DEFAULT_SLOW_THRESHOLD_MS = 500;
+
+/**
+ * Returns the slow-query threshold from env, falling back to the default.
+ * @returns {number}
+ */
+function getSlowThreshold() {
+	const fromEnv = Number(process.env.DB_SLOW_QUERY_THRESHOLD);
+	return Number.isFinite(fromEnv) && fromEnv > 0
+		? fromEnv
+		: DEFAULT_SLOW_THRESHOLD_MS;
+}
+
+/**
+ * Returns true if instrumentation is enabled via environment variable.
+ * @returns {boolean}
+ */
+function isInstrumentationEnabled() {
+	const setting = process.env.DB_INSTRUMENTATION;
+	if (setting === "0" || setting === "false" || setting === "off") return false;
+	return true;
+}
+
+// ── Argument masking ───────────────────────────────────────────────
+
+/**
+ * Recursively walks a value and replaces any key that matches a
+ * sensitive-field pattern with a placeholder.  Handles nested objects,
+ * arrays, and primitive values safely.
+ *
+ * @param {unknown} value — The value to mask.
+ * @returns {unknown} — The masked copy (shallow clone for non-objects).
+ */
+function maskSensitiveValues(value) {
+	// Primitives pass through as-is (leaf values that happen to be strings
+	// are not masked — we only mask *keys* named like sensitive fields).
+	if (value === null || value === undefined || typeof value !== "object") {
+		return value;
+	}
+
+	// Arrays — recurse into each element.
+	if (Array.isArray(value)) {
+		return value.map(maskSensitiveValues);
+	}
+
+	// Plain object — clone and mask matching keys.
+	const masked = /** @type {Record<string, unknown>} */ ({});
+	for (const [key, val] of Object.entries(
+		/** @type {Record<string, unknown>} */ (value),
+	)) {
+		if (isSensitiveKey(key)) {
+			masked[key] = REDACTED_PLACEHOLDER;
+		} else {
+			masked[key] = maskSensitiveValues(val);
+		}
+	}
+	return masked;
+}
+
+/**
+ * Checks whether a key name matches any sensitive-field pattern.
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isSensitiveKey(key) {
+	return SENSITIVE_FIELD_PATTERNS.some((re) => re.test(key));
+}
+
+// ── Query-log argument summarisation ───────────────────────────────
+
+/**
+ * Produces a safe, compact summary of query arguments suitable for
+ * debug-level logging.  Masks sensitive fields and truncates large
+ * structures.
+ *
+ * @param {unknown} args — The raw Prisma query args.
+ * @returns {Record<string, unknown>}
+ */
+function summarizeArgs(args) {
+	if (!args || typeof args !== "object") return {};
+
+	const masked = maskSensitiveValues(args);
+
+	// Truncate "data" and "where" large blocks to avoid log spam.
+	if (masked.data && typeof masked.data === "object") {
+		masked.data = truncateDeep(masked.data, 3);
+	}
+	if (masked.where && typeof masked.where === "object") {
+		masked.where = truncateDeep(masked.where, 3);
+	}
+	return /** @type {Record<string, unknown>} */ (masked);
+}
+
+/**
+ * Deep-truncates an object: keeps at most `maxKeys` keys per level.
+ * Beyond the limit, a `[+N more]` marker is added.
+ *
+ * @param {Record<string, unknown>} obj
+ * @param {number} maxKeys
+ * @returns {Record<string, unknown>}
+ */
+function truncateDeep(obj, maxKeys) {
+	if (!obj || typeof obj !== "object" || Array.isArray(obj)) return obj;
+
+	const keys = Object.keys(obj);
+	if (keys.length <= maxKeys) {
+		const result = /** @type {Record<string, unknown>} */ ({});
+		for (const key of keys) {
+			result[key] =
+				typeof obj[key] === "object" && obj[key] !== null
+					? truncateDeep(
+							/** @type {Record<string, unknown>} */ (obj[key]),
+							maxKeys,
+						)
+					: obj[key];
+		}
+		return result;
+	}
+
+	const result = /** @type {Record<string, unknown>} */ ({});
+	const kept = keys.slice(0, maxKeys);
+	for (const key of kept) {
+		result[key] =
+			typeof obj[key] === "object" && obj[key] !== null
+				? truncateDeep(
+						/** @type {Record<string, unknown>} */ (obj[key]),
+						maxKeys,
+					)
+				: obj[key];
+	}
+	result[`[+${keys.length - maxKeys} more]`] = true;
+	return result;
+}
+
+// ── Public API ─────────────────────────────────────────────────────
+
+/**
+ * Creates a Prisma client extension object that instruments all queries.
+ *
+ * The extension wraps every Prisma operation to:
+ *  1. Measure execution duration.
+ *  2. Log slow queries (configurable via DB_SLOW_QUERY_THRESHOLD).
+ *  3. Mask sensitive fields in all log output.
+ *  4. Increment Prometheus metrics for query counts and durations.
+ *
+ * Returns `null` when DB_INSTRUMENTATION is explicitly disabled, so the
+ * caller can skip the $extends call entirely (zero overhead).
+ *
+ * @returns {import("@prisma/client").PrismaClientExtended | null}
+ */
+export function createDbInstrumentation() {
+	if (!isInstrumentationEnabled()) return null;
+
+	const slowThreshold = getSlowThreshold();
+
+	return {
+		name: "quark-db-instrumentation",
+		query: {
+			/**
+			 * Middleware invoked for every Prisma operation.
+			 * @param {Object} params
+			 * @param {string} params.model — Model name (e.g. "User", "Account")
+			 * @param {string} params.operation — Operation name (e.g. "findUnique", "create")
+			 * @param {unknown} params.args — Query arguments (masked before logging)
+			 * @param {Function} params.query — The inner query function to call
+			 * @returns {Promise<unknown>}
+			 */
+			async $allOperations({ model, operation, args, query }) {
+				const start = performance.now();
+
+				try {
+					const result = await query(args);
+					return result;
+				} finally {
+					const durationMs = performance.now() - start;
+
+					// Emit Prometheus metrics (best-effort, no throw)
+					try {
+						const { dbQueriesTotal, dbQueryDuration } = await import(
+							"./db-metrics.js"
+						);
+						dbQueriesTotal.inc({ model, operation });
+						dbQueryDuration.observe({ model, operation }, durationMs / 1000);
+					} catch {
+						// Metrics registry not registered — skip silently.
+					}
+
+					// Slow-query warning (masked args, no sensitive data)
+					if (durationMs > slowThreshold) {
+						log.warn("Slow query detected", {
+							model,
+							operation,
+							durationMs: Math.round(durationMs),
+							args: summarizeArgs(args),
+						});
+					} else if (process.env.LOG_LEVEL === "debug") {
+						log.debug("Query executed", {
+							model,
+							operation,
+							durationMs: Math.round(durationMs),
+							args: summarizeArgs(args),
+						});
+					}
+				}
+			},
+		},
+	};
+}
+
+// Re-export for testing
+export {
+	getSlowThreshold,
+	isSensitiveKey,
+	maskSensitiveValues,
+	REDACTED_PLACEHOLDER,
+	summarizeArgs,
+};