@usequark/quark-core 2.5.4

package/src/errors.test.js

@@ -0,0 +1,128 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import {
+	AppError,
+	ConflictError,
+	DatabaseError,
+	ForbiddenError,
+	getErrorMessage,
+	getStatusCode,
+	logError,
+	NotFoundError,
+	normalizeError,
+	RateLimitError,
+	ServiceError,
+	UnauthorizedError,
+	ValidationError,
+} from "../src/errors.js";
+
+test("Error Module", async (t) => {
+	await t.test("AppError has correct properties", () => {
+		const error = new AppError("Test error", 500, "TEST_ERROR");
+		assert(error.message === "Test error");
+		assert(error.statusCode === 500);
+		assert(error.code === "TEST_ERROR");
+		assert(error.name === "AppError");
+	});
+
+	await t.test("AppError.toJSON() serializes correctly", () => {
+		const error = new AppError("Test", 500, "TEST");
+		const json = error.toJSON();
+		assert(json.message === "Test");
+		assert(json.statusCode === 500);
+		assert(json.code === "TEST");
+		assert(json.timestamp);
+	});
+
+	await t.test("ValidationError has status 400", () => {
+		const error = new ValidationError("Invalid input");
+		assert(error.statusCode === 400);
+		assert(error.code === "VALIDATION_ERROR");
+	});
+
+	await t.test("UnauthorizedError has status 401", () => {
+		const error = new UnauthorizedError();
+		assert(error.statusCode === 401);
+		assert(error.code === "UNAUTHORIZED");
+	});
+
+	await t.test("ForbiddenError has status 403", () => {
+		const error = new ForbiddenError();
+		assert(error.statusCode === 403);
+		assert(error.code === "FORBIDDEN");
+	});
+
+	await t.test("NotFoundError has status 404", () => {
+		const error = new NotFoundError();
+		assert(error.statusCode === 404);
+		assert(error.code === "NOT_FOUND");
+	});
+
+	await t.test("ConflictError has status 409", () => {
+		const error = new ConflictError();
+		assert(error.statusCode === 409);
+		assert(error.code === "CONFLICT");
+	});
+
+	await t.test("RateLimitError has status 429", () => {
+		const error = new RateLimitError("Too many requests", 60);
+		assert(error.statusCode === 429);
+		assert(error.code === "RATE_LIMIT");
+		assert(error.retryAfter === 60);
+	});
+
+	await t.test("DatabaseError wraps database errors", () => {
+		const originalError = new Error("Connection failed");
+		const error = new DatabaseError("DB error", originalError);
+		assert(error.statusCode === 500);
+		assert(error.originalError === originalError);
+	});
+
+	await t.test("ServiceError includes service name", () => {
+		const error = new ServiceError("PaymentAPI", "Payment failed");
+		assert(error.serviceName === "PaymentAPI");
+		assert(error.statusCode === 502);
+		const json = error.toJSON();
+		assert(json.serviceName === "PaymentAPI");
+	});
+
+	await t.test("getErrorMessage extracts from various types", () => {
+		assert(getErrorMessage("string error") === "string error");
+		assert(getErrorMessage(new Error("error message")) === "error message");
+		assert(getErrorMessage({ message: "obj error" }) === "obj error");
+		assert(getErrorMessage({}).includes("unknown")); // Changed from null to empty object
+	});
+
+	await t.test("getStatusCode returns correct code", () => {
+		assert(getStatusCode(new ValidationError("")) === 400);
+		assert(getStatusCode(new UnauthorizedError()) === 401);
+		assert(getStatusCode(new NotFoundError()) === 404);
+		assert(getStatusCode(new Error()) === 500);
+	});
+
+	await t.test("normalizeError converts to AppError", () => {
+		const error = normalizeError(new Error("test"));
+		assert(error instanceof AppError);
+		assert(error.message === "test");
+		assert(error.statusCode === 500);
+	});
+
+	await t.test("normalizeError handles string errors", () => {
+		const error = normalizeError("string error");
+		assert(error instanceof AppError);
+		assert(error.message === "string error");
+	});
+
+	await t.test("normalizeError handles non-Error objects", () => {
+		const error = normalizeError({ some: "object" });
+		assert(error instanceof AppError);
+		assert(error.message.includes("unknown"));
+	});
+
+	await t.test("logError handles errors with context", () => {
+		// This should not throw
+		const error = new ValidationError("test");
+		logError(error, { userId: "123", action: "test" });
+		assert(true);
+	});
+});

package/src/exports.test.js

@@ -0,0 +1,154 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+import * as core from "@techstream/quark-core";
+import * as admin from "@techstream/quark-core/admin";
+import * as auth from "@techstream/quark-core/auth";
+import * as authMiddleware from "@techstream/quark-core/auth/middleware";
+import * as coreLight from "@techstream/quark-core/core";
+import * as db from "@techstream/quark-core/db";
+import * as email from "@techstream/quark-core/email";
+import * as errors from "@techstream/quark-core/errors";
+import * as locale from "@techstream/quark-core/locale";
+import * as logger from "@techstream/quark-core/logger";
+import * as metrics from "@techstream/quark-core/metrics";
+import * as queue from "@techstream/quark-core/queue";
+import * as sms from "@techstream/quark-core/sms";
+import * as storage from "@techstream/quark-core/storage";
+import * as storageS3 from "@techstream/quark-core/storage/s3";
+import * as stripe from "@techstream/quark-core/stripe";
+import * as testing from "@techstream/quark-core/testing";
+
+const packageJson = JSON.parse(
+	readFileSync(new URL("../package.json", import.meta.url), "utf-8"),
+);
+
+// Guard against accidental subpath removals: every entry in the exports map
+// must resolve. apps/web imports `@techstream/quark-core/logger`, and the
+// scaffolded i18n/payment skills document `./locale` and `./stripe`.
+test("every subpath in package.json exports resolves", async () => {
+	for (const subpath of Object.keys(packageJson.exports)) {
+		const specifier = `@techstream/quark-core${
+			subpath === "." ? "" : subpath.slice(1)
+		}`;
+		await assert.doesNotReject(
+			() => import(specifier),
+			`failed to import ${specifier}`,
+		);
+	}
+});
+
+test("subpath '.' (full barrel) exports all key utilities", () => {
+	assert.equal(typeof core.createAuthConfig, "function");
+	assert.equal(typeof core.createStorage, "function");
+	assert.equal(typeof core.AppError, "function");
+	assert.equal(typeof core.createLogger, "function");
+	assert.equal(typeof core.createS3Storage, "function");
+	assert.equal(typeof core.createPrismaClient, "function");
+	assert.equal(typeof core.pingDatabase, "function");
+	assert.equal(typeof core.parseSchema, "function");
+	assert.equal(typeof core.requireSession, "function");
+	assert.equal(typeof core.requireSessionRole, "function");
+	assert.equal(typeof core.createAuthMiddleware, "function");
+});
+
+test("subpath './core' exports lightweight utilities", () => {
+	assert.equal(typeof coreLight.AppError, "function");
+	assert.equal(typeof coreLight.ValidationError, "function");
+	assert.equal(typeof coreLight.createLogger, "function");
+	assert.equal(typeof coreLight.validateBody, "function");
+	assert.equal(typeof coreLight.retryAsync, "function");
+	assert.equal(typeof coreLight.parsePagination, "function");
+	assert.equal(typeof coreLight.generateCsrfToken, "function");
+	assert.equal(typeof coreLight.createRateLimiter, "function");
+	assert.equal(typeof coreLight.validateFile, "function");
+	assert.equal(typeof coreLight.createPrismaClient, "function");
+	assert.equal(typeof coreLight.pingDatabase, "function");
+	// Should NOT export heavier modules
+	assert.equal(coreLight.createStorage, undefined);
+	assert.equal(coreLight.createEmailService, undefined);
+});
+
+test("subpath './auth' exports config + middleware", () => {
+	assert.equal(typeof auth.createAuthConfig, "function");
+	assert.equal(typeof auth.requireSession, "function");
+	assert.equal(typeof auth.requireSessionRole, "function");
+	assert.equal(typeof auth.createAuthMiddleware, "function");
+});
+
+test("subpath './auth/middleware' exports middleware only", () => {
+	assert.equal(typeof authMiddleware.requireSession, "function");
+	assert.equal(typeof authMiddleware.requireSessionRole, "function");
+	assert.equal(typeof authMiddleware.createAuthMiddleware, "function");
+});
+
+test("subpath './errors' exports error classes", () => {
+	assert.equal(typeof errors.AppError, "function");
+	assert.equal(typeof errors.ValidationError, "function");
+	assert.equal(typeof errors.UnauthorizedError, "function");
+	assert.equal(typeof errors.ForbiddenError, "function");
+});
+
+test("subpath './logger' exports the browser-safe logger", () => {
+	assert.equal(typeof logger.createLogger, "function");
+});
+
+test("subpath './locale' exports locale utilities", () => {
+	assert.equal(typeof locale.getDefaultLocale, "function");
+	assert.equal(typeof locale.getSupportedLocales, "function");
+	assert.equal(typeof locale.isLocaleSupported, "function");
+});
+
+test("subpath './stripe' exports payment utilities", () => {
+	assert.equal(typeof stripe.createStripeClient, "function");
+	assert.equal(typeof stripe.getStripeWebhookEvent, "function");
+});
+
+test("subpath './storage' exports storage utilities", () => {
+	assert.equal(typeof storage.createStorage, "function");
+	assert.equal(typeof storage.createLocalStorage, "function");
+	assert.equal(typeof storage.createS3Storage, "function");
+	assert.equal(typeof storage.generateStorageKey, "function");
+	assert.equal(typeof storage.getAssetUrl, "function");
+});
+
+test("subpath './storage/s3' exports S3 adapter only", () => {
+	assert.equal(typeof storageS3.createS3Storage, "function");
+});
+
+test("subpath './db' exports database utilities", () => {
+	assert.equal(typeof db.getConnectionString, "function");
+	assert.equal(typeof db.getPoolConfig, "function");
+	assert.equal(typeof db.createPrismaClient, "function");
+	assert.equal(typeof db.pingDatabase, "function");
+});
+
+test("subpath './admin' exports introspection utilities", () => {
+	assert.equal(typeof admin.parseSchema, "function");
+	assert.equal(typeof admin.getModelByName, "function");
+	assert.equal(typeof admin.detectIdField, "function");
+	assert.equal(typeof admin.coerceId, "function");
+	assert.equal(typeof admin.getModels, "function");
+	assert.equal(typeof admin.getEnums, "function");
+});
+
+test("subpath './queue' exports queue utilities", () => {
+	assert.equal(typeof queue.createQueue, "function");
+});
+
+test("subpath './email' exports email utilities", () => {
+	assert.equal(typeof email.createEmailService, "function");
+});
+
+test("subpath './sms' exports SMS utilities", () => {
+	assert.equal(typeof sms.createSmsService, "function");
+});
+
+test("subpath './metrics' exports metrics utilities", () => {
+	assert.equal(typeof metrics.createMetrics, "function");
+});
+
+test("subpath './testing' exports test utilities", () => {
+	assert.equal(typeof testing.createTestUser, "function");
+});

package/src/file-validation.js

@@ -0,0 +1,249 @@
+/**
+ * @techstream/quark-core - File Validation
+ *
+ * Validates uploaded files: size limits, MIME type allow-lists,
+ * and magic-byte verification to prevent MIME spoofing.
+ */
+
+// ---------------------------------------------------------------------------
+// Magic bytes for common file types
+// ---------------------------------------------------------------------------
+
+const MAGIC_BYTES = [
+	// Images
+	{ mime: "image/jpeg", bytes: [0xff, 0xd8, 0xff] },
+	{ mime: "image/png", bytes: [0x89, 0x50, 0x4e, 0x47] },
+	{ mime: "image/gif", bytes: [0x47, 0x49, 0x46, 0x38] },
+	{
+		mime: "image/webp",
+		bytes: [0x52, 0x49, 0x46, 0x46],
+		offset: 0,
+		extra: { offset: 8, bytes: [0x57, 0x45, 0x42, 0x50] },
+	},
+	{
+		mime: "image/svg+xml",
+		bytes: null,
+		detect: (buf) => {
+			const head = buf.subarray(0, 256).toString("utf8").trimStart();
+			return head.startsWith("<svg") || head.startsWith("<?xml");
+		},
+	},
+	{
+		mime: "image/avif",
+		bytes: null,
+		detect: (buf) => {
+			// ftyp box with "avif" or "avis" brand
+			if (buf.length < 12) return false;
+			const ftyp = buf.subarray(4, 8).toString("ascii");
+			if (ftyp !== "ftyp") return false;
+			const brand = buf.subarray(8, 12).toString("ascii");
+			return brand === "avif" || brand === "avis";
+		},
+	},
+
+	// Documents
+	{ mime: "application/pdf", bytes: [0x25, 0x50, 0x44, 0x46] }, // %PDF
+	{ mime: "application/zip", bytes: [0x50, 0x4b, 0x03, 0x04] },
+
+	// Video - MP4 uses ftyp box like AVIF, but with different brands (isom, mp41, mp42, etc.)
+	{
+		mime: "video/mp4",
+		bytes: null,
+		detect: (buf) => {
+			if (buf.length < 12) return false;
+			const ftyp = buf.subarray(4, 8).toString("ascii");
+			if (ftyp !== "ftyp") return false;
+			// Exclude AVIF brands already handled above
+			const brand = buf.subarray(8, 12).toString("ascii");
+			if (brand === "avif" || brand === "avis") return false;
+			return true;
+		},
+	},
+	{ mime: "video/webm", bytes: [0x1a, 0x45, 0xdf, 0xa3] },
+];
+
+/**
+ * Detect MIME type from file buffer using magic bytes.
+ * Returns null if no match found.
+ * @param {Buffer} buffer - At least the first 256 bytes of the file
+ * @returns {string | null}
+ */
+export function detectMimeType(buffer) {
+	for (const entry of MAGIC_BYTES) {
+		if (entry.detect) {
+			if (entry.detect(buffer)) return entry.mime;
+			continue;
+		}
+
+		if (!entry.bytes) continue;
+
+		const offset = entry.offset || 0;
+		let match = true;
+		for (let i = 0; i < entry.bytes.length; i++) {
+			if (buffer[offset + i] !== entry.bytes[i]) {
+				match = false;
+				break;
+			}
+		}
+
+		if (match && entry.extra) {
+			for (let i = 0; i < entry.extra.bytes.length; i++) {
+				if (buffer[entry.extra.offset + i] !== entry.extra.bytes[i]) {
+					match = false;
+					break;
+				}
+			}
+		}
+
+		if (match) return entry.mime;
+	}
+
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_SIZE = 10 * 1024 * 1024; // 10 MB
+
+const DEFAULT_ALLOWED_TYPES = [
+	"image/jpeg",
+	"image/png",
+	"image/gif",
+	"image/webp",
+	"image/avif",
+	"image/svg+xml",
+	"application/pdf",
+];
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} FileValidationOptions
+ * @property {number} [maxSize] - Max file size in bytes (default: 10MB)
+ * @property {string[]} [allowedTypes] - Allowed MIME types. Supports wildcards like "image/*"
+ * @property {boolean} [verifyMagicBytes=true] - Check magic bytes match declared MIME type
+ */
+
+/**
+ * @typedef {Object} FileValidationResult
+ * @property {boolean} valid
+ * @property {string} [error] - Human-readable error message (when invalid)
+ * @property {string} [detectedType] - MIME type detected from magic bytes
+ */
+
+/**
+ * Validate a file against size, type and magic-byte rules.
+ *
+ * @param {Object} file
+ * @param {string} file.filename - Original filename
+ * @param {string} file.mimeType - Declared MIME type (from Content-Type)
+ * @param {number} file.size - File size in bytes
+ * @param {Buffer} [file.buffer] - File content (required if verifyMagicBytes is true)
+ * @param {FileValidationOptions} [options]
+ * @returns {FileValidationResult}
+ */
+export function validateFile(file, options = {}) {
+	const {
+		maxSize = parseMaxSize(),
+		allowedTypes = parseAllowedTypes(),
+		verifyMagicBytes = true,
+	} = options;
+
+	// Size check
+	if (file.size > maxSize) {
+		return {
+			valid: false,
+			error: `File exceeds maximum size of ${formatBytes(maxSize)} (got ${formatBytes(file.size)})`,
+		};
+	}
+
+	// MIME type allow-list
+	if (!isTypeAllowed(file.mimeType, allowedTypes)) {
+		return {
+			valid: false,
+			error: `File type "${file.mimeType}" is not allowed. Allowed: ${allowedTypes.join(", ")}`,
+		};
+	}
+
+	// Magic byte verification
+	if (verifyMagicBytes && file.buffer) {
+		const detected = detectMimeType(file.buffer);
+		if (detected && !isSameCategory(detected, file.mimeType)) {
+			return {
+				valid: false,
+				error: `File content does not match declared type. Declared: ${file.mimeType}, detected: ${detected}`,
+				detectedType: detected,
+			};
+		}
+		return { valid: true, detectedType: detected };
+	}
+
+	return { valid: true };
+}
+
+/**
+ * Check if a MIME type matches an allow list (supports wildcards like "image/*").
+ * @param {string} mimeType
+ * @param {string[]} allowedTypes
+ * @returns {boolean}
+ */
+export function isTypeAllowed(mimeType, allowedTypes) {
+	if (!mimeType) return false;
+	const normalized = mimeType.toLowerCase().trim();
+
+	for (const pattern of allowedTypes) {
+		const p = pattern.toLowerCase().trim();
+		if (p === normalized) return true;
+		if (p === "*/*") return true;
+		if (p.endsWith("/*")) {
+			const category = p.slice(0, p.indexOf("/"));
+			if (normalized.startsWith(`${category}/`)) return true;
+		}
+	}
+
+	return false;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function parseMaxSize() {
+	const env = process.env.UPLOAD_MAX_SIZE;
+	if (!env) return DEFAULT_MAX_SIZE;
+	const n = Number(env);
+	return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_SIZE;
+}
+
+function parseAllowedTypes() {
+	const env = process.env.UPLOAD_ALLOWED_TYPES;
+	if (!env) return DEFAULT_ALLOWED_TYPES;
+	return env
+		.split(",")
+		.map((t) => t.trim())
+		.filter(Boolean);
+}
+
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Check if two MIME types belong to the same top-level category.
+ * e.g. "image/jpeg" and "image/png" → true
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function isSameCategory(a, b) {
+	if (!a || !b) return true; // lenient when one side is unknown
+	const catA = a.split("/")[0];
+	const catB = b.split("/")[0];
+	return catA === catB;
+}