@usequark/quark-core 2.5.4

package/src/file-validation.test.js

@@ -0,0 +1,207 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import {
+	detectMimeType,
+	isTypeAllowed,
+	validateFile,
+} from "../src/file-validation.js";
+
+// ---------------------------------------------------------------------------
+// detectMimeType
+// ---------------------------------------------------------------------------
+
+test("FileValidation - detectMimeType identifies JPEG", () => {
+	const buf = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0, 0]);
+	assert.strictEqual(detectMimeType(buf), "image/jpeg");
+});
+
+test("FileValidation - detectMimeType identifies PNG", () => {
+	const buf = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+	assert.strictEqual(detectMimeType(buf), "image/png");
+});
+
+test("FileValidation - detectMimeType identifies GIF", () => {
+	const buf = Buffer.from([0x47, 0x49, 0x46, 0x38, 0x39, 0x61]);
+	assert.strictEqual(detectMimeType(buf), "image/gif");
+});
+
+test("FileValidation - detectMimeType identifies WebP", () => {
+	const buf = Buffer.alloc(16);
+	// RIFF....WEBP
+	buf.writeUInt8(0x52, 0); // R
+	buf.writeUInt8(0x49, 1); // I
+	buf.writeUInt8(0x46, 2); // F
+	buf.writeUInt8(0x46, 3); // F
+	buf.writeUInt8(0x57, 8); // W
+	buf.writeUInt8(0x45, 9); // E
+	buf.writeUInt8(0x42, 10); // B
+	buf.writeUInt8(0x50, 11); // P
+	assert.strictEqual(detectMimeType(buf), "image/webp");
+});
+
+test("FileValidation - detectMimeType identifies PDF", () => {
+	const buf = Buffer.from("%PDF-1.5", "ascii");
+	assert.strictEqual(detectMimeType(buf), "application/pdf");
+});
+
+test("FileValidation - detectMimeType identifies SVG", () => {
+	const buf = Buffer.from('<svg xmlns="http://www.w3.org/2000/svg"></svg>');
+	assert.strictEqual(detectMimeType(buf), "image/svg+xml");
+});
+
+test("FileValidation - detectMimeType identifies SVG with XML declaration", () => {
+	const buf = Buffer.from('<?xml version="1.0"?><svg></svg>');
+	assert.strictEqual(detectMimeType(buf), "image/svg+xml");
+});
+
+test("FileValidation - detectMimeType identifies ZIP", () => {
+	const buf = Buffer.from([0x50, 0x4b, 0x03, 0x04, 0, 0]);
+	assert.strictEqual(detectMimeType(buf), "application/zip");
+});
+
+test("FileValidation - detectMimeType identifies WebM", () => {
+	const buf = Buffer.from([0x1a, 0x45, 0xdf, 0xa3, 0, 0]);
+	assert.strictEqual(detectMimeType(buf), "video/webm");
+});
+
+test("FileValidation - detectMimeType returns null for unknown bytes", () => {
+	const buf = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+	assert.strictEqual(detectMimeType(buf), null);
+});
+
+// ---------------------------------------------------------------------------
+// isTypeAllowed
+// ---------------------------------------------------------------------------
+
+test("FileValidation - isTypeAllowed exact match", () => {
+	assert.strictEqual(
+		isTypeAllowed("image/jpeg", ["image/jpeg", "image/png"]),
+		true,
+	);
+	assert.strictEqual(
+		isTypeAllowed("image/gif", ["image/jpeg", "image/png"]),
+		false,
+	);
+});
+
+test("FileValidation - isTypeAllowed wildcard category match", () => {
+	assert.strictEqual(isTypeAllowed("image/jpeg", ["image/*"]), true);
+	assert.strictEqual(isTypeAllowed("image/png", ["image/*"]), true);
+	assert.strictEqual(isTypeAllowed("application/pdf", ["image/*"]), false);
+});
+
+test("FileValidation - isTypeAllowed universal wildcard", () => {
+	assert.strictEqual(isTypeAllowed("video/mp4", ["*/*"]), true);
+});
+
+test("FileValidation - isTypeAllowed is case insensitive", () => {
+	assert.strictEqual(isTypeAllowed("Image/JPEG", ["image/jpeg"]), true);
+});
+
+test("FileValidation - isTypeAllowed returns false for null/empty mime", () => {
+	assert.strictEqual(isTypeAllowed(null, ["image/jpeg"]), false);
+	assert.strictEqual(isTypeAllowed("", ["image/jpeg"]), false);
+});
+
+// ---------------------------------------------------------------------------
+// validateFile
+// ---------------------------------------------------------------------------
+
+test("FileValidation - validateFile accepts valid file", () => {
+	const pngMagic = Buffer.from([
+		0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+	]);
+	const result = validateFile(
+		{
+			filename: "test.png",
+			mimeType: "image/png",
+			size: 1024,
+			buffer: pngMagic,
+		},
+		{ allowedTypes: ["image/*"] },
+	);
+	assert.strictEqual(result.valid, true);
+	assert.strictEqual(result.detectedType, "image/png");
+});
+
+test("FileValidation - validateFile rejects oversized file", () => {
+	const result = validateFile(
+		{ filename: "big.jpg", mimeType: "image/jpeg", size: 20 * 1024 * 1024 },
+		{ maxSize: 10 * 1024 * 1024 },
+	);
+	assert.strictEqual(result.valid, false);
+	assert.match(result.error, /exceeds maximum size/);
+});
+
+test("FileValidation - validateFile rejects disallowed MIME type", () => {
+	const result = validateFile(
+		{ filename: "virus.exe", mimeType: "application/x-msdownload", size: 100 },
+		{ allowedTypes: ["image/*"] },
+	);
+	assert.strictEqual(result.valid, false);
+	assert.match(result.error, /not allowed/);
+});
+
+test("FileValidation - validateFile detects MIME spoofing", () => {
+	// Claim it's an image/jpeg but magic bytes say PDF
+	const pdfMagic = Buffer.from("%PDF-1.5", "ascii");
+	const result = validateFile(
+		{
+			filename: "fake.jpg",
+			mimeType: "image/jpeg",
+			size: 100,
+			buffer: pdfMagic,
+		},
+		{ allowedTypes: ["image/jpeg", "application/pdf"] },
+	);
+	assert.strictEqual(result.valid, false);
+	assert.match(result.error, /does not match declared type/);
+	assert.strictEqual(result.detectedType, "application/pdf");
+});
+
+test("FileValidation - validateFile skips magic bytes when disabled", () => {
+	const pdfMagic = Buffer.from("%PDF-1.5", "ascii");
+	const result = validateFile(
+		{
+			filename: "file.jpg",
+			mimeType: "image/jpeg",
+			size: 100,
+			buffer: pdfMagic,
+		},
+		{ allowedTypes: ["image/jpeg"], verifyMagicBytes: false },
+	);
+	assert.strictEqual(result.valid, true);
+});
+
+test("FileValidation - validateFile passes when magic bytes unknown", () => {
+	// Unknown magic bytes should not block the file
+	const buf = Buffer.from([0xde, 0xad, 0xbe, 0xef]);
+	const result = validateFile(
+		{
+			filename: "data.bin",
+			mimeType: "application/pdf",
+			size: 100,
+			buffer: buf,
+		},
+		{ allowedTypes: ["application/pdf"] },
+	);
+	assert.strictEqual(result.valid, true);
+});
+
+test("FileValidation - validateFile works without buffer", () => {
+	const result = validateFile(
+		{ filename: "file.png", mimeType: "image/png", size: 100 },
+		{ allowedTypes: ["image/*"] },
+	);
+	assert.strictEqual(result.valid, true);
+});
+
+test("FileValidation - validateFile uses env defaults gracefully", () => {
+	// No options → uses module defaults
+	const result = validateFile({
+		filename: "test.jpg",
+		mimeType: "image/jpeg",
+		size: 1024,
+	});
+	assert.strictEqual(result.valid, true);
+});

package/src/index.js

@@ -0,0 +1,58 @@
+// Authorization exports
+
+// Admin exports
+export * from "./admin.js";
+// Admin auth exports
+export * from "./admin-auth.js";
+// Auth exports
+export * from "./auth/index.js";
+export * from "./authorization.js";
+// Cache exports
+export * from "./cache.js";
+// CSRF protection exports
+export * from "./csrf.js";
+// Database exports
+export * from "./db.js";
+// Database instrumentation exports
+export * from "./db-instrumentation.js";
+// Email service exports
+export * from "./email.js";
+// Email template exports
+export * from "./email-templates.js";
+// Error Reporter exports
+export * from "./error-reporter.js";
+// Error exports
+export * from "./errors.js";
+// File validation exports
+export * from "./file-validation.js";
+// Logger exports
+export * from "./logger.js";
+// Mail exports
+export * from "./mail.js";
+// Metrics exports
+export * from "./metrics.js";
+// Multipart parsing exports
+export * from "./multipart.js";
+// Pagination exports
+export * from "./pagination.js";
+// Query builder exports
+export * from "./query-builder.js";
+// Queue exports
+export * from "./queue/index.js";
+// Rate limiting exports
+export * from "./rate-limiter.js";
+// Redis exports
+export * from "./redis.js";
+// Request logger exports
+export * from "./request-logger.js";
+// SMS service exports
+export * from "./sms.js";
+// Storage exports
+export * from "./storage.js";
+
+// Utility exports
+export * from "./utils.js";
+export * from "./validation.js";
+
+// Testing utilities (import from "@techstream/quark-core/testing" in test files)
+// Not re-exported from main to avoid polluting production imports

package/src/locale.js

@@ -0,0 +1,21 @@
+const DEFAULT_LOCALE_FALLBACK = "en";
+const SUPPORTED_LOCALES_FALLBACK = ["en"];
+
+export function getDefaultLocale() {
+	const env = process.env.DEFAULT_LOCALE;
+	return env?.trim() ? env.trim() : DEFAULT_LOCALE_FALLBACK;
+}
+
+export function getSupportedLocales() {
+	const env = process.env.SUPPORTED_LOCALES;
+	if (!env?.trim()) return SUPPORTED_LOCALES_FALLBACK;
+	return env
+		.split(",")
+		.map((l) => l.trim())
+		.filter(Boolean);
+}
+
+export function isLocaleSupported(locale) {
+	if (!locale || typeof locale !== "string") return false;
+	return getSupportedLocales().includes(locale.trim());
+}

package/src/logger.js

@@ -0,0 +1,182 @@
+/**
+ * @techstream/quark-core - Logger Module
+ * Lightweight structured logger with zero external dependencies
+ */
+
+/** @enum {number} */
+const LOG_LEVELS = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40,
+	fatal: 50,
+};
+
+const LEVEL_NAMES = /** @type {const} */ ({
+	10: "debug",
+	20: "info",
+	30: "warn",
+	40: "error",
+	50: "fatal",
+});
+
+/** @type {Record<string, string>} */
+const LEVEL_COLORS = {
+	debug: "\x1b[36m", // cyan
+	info: "\x1b[32m", // green
+	warn: "\x1b[33m", // yellow
+	error: "\x1b[31m", // red
+	fatal: "\x1b[35m", // magenta
+};
+
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+
+const isProduction = () => process.env.NODE_ENV === "production";
+
+/**
+ * Resolves the minimum log level from options and environment
+ * @param {string} [optionLevel] - Level from options
+ * @returns {number}
+ */
+const resolveLevel = (optionLevel) => {
+	const level =
+		optionLevel || process.env.LOG_LEVEL || (isProduction() ? "info" : "debug");
+	return LOG_LEVELS[level] ?? LOG_LEVELS.info;
+};
+
+/**
+ * Formats a log entry for dev (colorized, human-readable)
+ * @param {object} entry - The log entry
+ * @returns {string}
+ */
+const formatDev = (entry) => {
+	const { timestamp, level, name, msg, ...rest } = entry;
+	const color = LEVEL_COLORS[level] || "";
+	const time = timestamp.slice(11, 23); // HH:mm:ss.SSS
+	const contextStr =
+		Object.keys(rest).length > 0
+			? ` ${DIM}${JSON.stringify(rest)}${RESET}`
+			: "";
+	return `${DIM}${time}${RESET} ${color}${level.toUpperCase().padEnd(5)}${RESET} ${DIM}[${name}]${RESET} ${msg}${contextStr}`;
+};
+
+/**
+ * Formats a log entry for production (single-line JSON)
+ * @param {object} entry - The log entry
+ * @returns {string}
+ */
+const formatProd = (entry) => {
+	return JSON.stringify(entry);
+};
+
+/**
+ * Returns the console method for a given level
+ * @param {string} level - The log level name
+ * @returns {Function}
+ */
+const getTransport = (level) => {
+	if (level === "error" || level === "fatal") return console.error;
+	if (level === "warn") return console.warn;
+	return console.log;
+};
+
+/**
+ * @typedef {Object} LoggerOptions
+ * @property {string} [name] - Logger name (e.g. "web", "worker", "db")
+ * @property {string} [level] - Minimum log level (default: "info" in production, "debug" in dev)
+ * @property {Object} [context] - Default context merged into every log entry
+ */
+
+/**
+ * @typedef {Object} Logger
+ * @property {(msg: string, data?: Object) => void} debug - Log at debug level
+ * @property {(msg: string, data?: Object) => void} info - Log at info level
+ * @property {(msg: string, data?: Object) => void} warn - Log at warn level
+ * @property {(msg: string, data?: Object) => void} error - Log at error level
+ * @property {(msg: string, data?: Object) => void} fatal - Log at fatal level
+ * @property {(context: Object) => Logger} child - Create a child logger with merged context
+ */
+
+/**
+ * Creates a structured logger instance
+ * @param {LoggerOptions} [options] - Logger configuration
+ * @returns {Logger}
+ */
+export const createLogger = (options = {}) => {
+	const {
+		name = "app",
+		level: optionLevel,
+		context: defaultContext = {},
+	} = options;
+	const minLevel = resolveLevel(optionLevel);
+	const format = isProduction() ? formatProd : formatDev;
+
+	/**
+	 * Writes a log entry if the level is at or above the minimum
+	 * @param {string} levelName - The level name
+	 * @param {string} msg - The log message
+	 * @param {Object} [data] - Additional data
+	 */
+	const write = (levelName, msg, data = {}) => {
+		const numeric = LOG_LEVELS[levelName];
+		if (numeric < minLevel) return;
+
+		const entry = {
+			timestamp: new Date().toISOString(),
+			level: levelName,
+			name,
+			msg,
+			...defaultContext,
+			...data,
+		};
+
+		const transport = getTransport(levelName);
+		transport(format(entry));
+	};
+
+	return {
+		debug: (msg, data) => write("debug", msg, data),
+		info: (msg, data) => write("info", msg, data),
+		warn: (msg, data) => write("warn", msg, data),
+		error: (msg, data) => write("error", msg, data),
+		fatal: (msg, data) => write("fatal", msg, data),
+
+		/**
+		 * Creates a child logger with merged context
+		 * @param {Object} childContext - Additional context for the child logger
+		 * @returns {Logger}
+		 */
+		child: (childContext = {}) => {
+			return createLogger({
+				name,
+				level: LEVEL_NAMES[minLevel],
+				context: { ...defaultContext, ...childContext },
+			});
+		},
+	};
+};
+
+/**
+ * Creates a request logger middleware helper.
+ * Returns a function that accepts a request object and produces
+ * a child logger enriched with request-specific fields.
+ * @param {Logger} parentLogger - The parent logger instance
+ * @returns {(request: { method?: string, url?: string, headers?: Object }) => Logger}
+ */
+export const requestLogger = (parentLogger) => {
+	return (request) => {
+		const requestId = request.headers?.["x-request-id"] || crypto.randomUUID();
+		const method = request.method || "UNKNOWN";
+		const path = request.url
+			? new URL(request.url, "http://localhost").pathname
+			: "/";
+
+		const child = parentLogger.child({ requestId, method, path });
+		child.info("request started");
+		return child;
+	};
+};
+
+/** Default logger instance */
+export const logger = createLogger({ name: "quark" });