@usequark/quark-core 2.5.4

package/README.md

@@ -0,0 +1,63 @@
+# @techstream/quark-core
+
+Shared infrastructure for the Quark platform - authentication, job queues, error handling, and utilities.
+
+## What's Included
+
+- **Authentication** - Auth.js-compatible config helpers (`createAuthConfig`, `requireAuth`, password hashing) plus framework-agnostic session guards (`requireSession`, `requireSessionRole`, `createAuthMiddleware`)
+- **Database** - Prisma client singleton (`createPrismaClient`), connection-string/pool helpers, and a `pingDatabase()` health check
+- **Admin** - Prisma schema introspection (`parseSchema`, `getModels`, `getEnums`, `coerceId`) for auto-generated admin UIs
+- **Job Queue** - BullMQ integration (`createQueue`, `createWorker`, `addJob`)
+- **Storage** - Local filesystem built in; S3/R2/MinIO via optional AWS SDK install in the app
+- **Errors** - Standardized error types (`ValidationError`, `NotFoundError`, `UnauthorizedError`, etc.)
+- **Utilities** - `retryAsync`, `deepMerge`, `randomString`, `sanitizeId`, `measureTime`, `memoize`
+- **Validation** - Zod-based request body validation
+- **Redis / Mail** - Connection helpers for Redis and local mail (Mailpit)
+
+## Usage
+
+```javascript
+import {
+  createAuthConfig,
+  requireAuth,
+  createQueue,
+  createWorker,
+  addJob,
+  ValidationError,
+  retryAsync,
+} from "@techstream/quark-core";
+```
+
+All modules are re-exported from the package root. See JSDoc comments on each function for options and usage details.
+
+### Subpath exports
+
+Prefer a subpath when you want a smaller import graph or the browser-safe logger:
+
+| Subpath | Contents |
+|---|---|
+| `@techstream/quark-core/core` | errors, logger, validation, utils, pagination, csrf, rate limiter, file validation, db |
+| `@techstream/quark-core/db` | Prisma singleton, connection string, pool config, `pingDatabase()` |
+| `@techstream/quark-core/admin` | Prisma schema introspection helpers |
+| `@techstream/quark-core/auth` | auth config helpers + session guards |
+| `@techstream/quark-core/auth/middleware` | session guards only |
+| `@techstream/quark-core/storage` | local adapter, storage factory, key/URL helpers, `createS3Storage` |
+| `@techstream/quark-core/storage/s3` | S3 adapter only |
+| `@techstream/quark-core/logger` | browser-safe logger |
+| `@techstream/quark-core/locale` | locale helpers |
+| `@techstream/quark-core/stripe` | Stripe client + webhook helpers |
+
+`@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`, `pg`, and `stripe` are optional peer dependencies. They are only loaded when the matching feature is used, so apps that do not use S3, `pingDatabase()`, or payments do not need them installed.
+
+## Testing
+
+```bash
+cd packages/core
+pnpm test
+```
+
+## Support
+
+For issues, questions, and discussions:
+- 🐛 [Issue Tracker](https://github.com/usequark/quark/issues)
+- 💬 [Discussions](https://github.com/usequark/quark/discussions)

package/package.json

@@ -0,0 +1,80 @@
+{
+	"name": "@usequark/quark-core",
+	"version": "2.5.4",
+	"description": "Core utilities for Quark apps: auth, BullMQ queues, Redis, email, storage, rate limiting, logging, and error handling",
+	"type": "module",
+	"main": "src/index.js",
+	"homepage": "https://github.com/usequark/quark#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/usequark/quark.git",
+		"directory": "packages/core"
+	},
+	"bugs": {
+		"url": "https://github.com/usequark/quark/issues"
+	},
+	"author": "Quark Contributors",
+	"exports": {
+		".": "./src/index.js",
+		"./core": "./src/core.js",
+		"./admin": "./src/admin.js",
+		"./auth": "./src/auth/index.js",
+		"./auth/middleware": "./src/auth/middleware.js",
+		"./db": "./src/db.js",
+		"./email": "./src/email.js",
+		"./errors": "./src/errors.js",
+		"./locale": "./src/locale.js",
+		"./logger": "./src/logger.js",
+		"./metrics": "./src/metrics.js",
+		"./queue": "./src/queue/index.js",
+		"./sms": "./src/sms.js",
+		"./storage": "./src/storage.js",
+		"./storage/s3": "./src/storage-s3.js",
+		"./stripe": "./src/stripe.js",
+		"./testing": "./src/testing/index.js"
+	},
+	"dependencies": {
+		"bcryptjs": "^3.0.3",
+		"busboy": "^1.6.0",
+		"bullmq": "^6.3.8",
+		"ioredis": "^6.0.0",
+		"nodemailer": "^10.0.10",
+		"zod": "^4.6.5"
+	},
+	"peerDependencies": {
+		"@aws-sdk/client-s3": "^3.1004.0",
+		"@aws-sdk/s3-request-presigner": "^3.1004.0",
+		"pg": "^8.20.0",
+		"stripe": "^17.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@aws-sdk/client-s3": {
+			"optional": true
+		},
+		"@aws-sdk/s3-request-presigner": {
+			"optional": true
+		},
+		"pg": {
+			"optional": true
+		},
+		"stripe": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@types/node": "^26.6.2"
+	},
+	"scripts": {
+		"test": "node ../../scripts/run-tests.mjs src",
+		"lint": "biome format --write && biome check --write"
+	},
+	"files": [
+		"src",
+		"README.md"
+	],
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"license": "MIT"
+}

package/src/admin-auth.js

@@ -0,0 +1,121 @@
+/**
+ * @techstream/quark-core — Admin Authorization Module
+ *
+ * Lightweight, stateless admin-token authorization for drop-in internal
+ * endpoints (health checks, metrics, admin APIs).
+ *
+ * Agnostic by design: the admin token is read from the environment variable
+ * ADMIN_API_TOKEN. No project-specific user database or session is required.
+ * When no ADMIN_API_TOKEN is set, the endpoint is effectively open and the
+ * guard is a no-op (appropriate for local development).
+ *
+ * Security properties:
+ *  - Constant-time comparison to prevent timing attacks.
+ *  - Token never appears in logs (masked by default).
+ *  - Returns a generic 401 response that does not reveal whether the
+ *    token was missing or incorrect.
+ */
+
+import { createLogger } from "./logger.js";
+
+const log = createLogger("admin-auth");
+
+/**
+ * Checks whether the given token matches the configured ADMIN_API_TOKEN.
+ *
+ * Uses timing-safe comparison when both values are present.  When no
+ * ADMIN_API_TOKEN is configured, the check always passes (development
+ * convenience — log a warning on first call).
+ *
+ * @param {string | null | undefined} providedToken — Token from the request.
+ * @returns {{ authorized: boolean, reason?: string }}
+ */
+export function verifyAdminToken(providedToken) {
+	const configuredToken = process.env.ADMIN_API_TOKEN;
+
+	// No token configured — dev mode, allow access with a warning.
+	if (!configuredToken) {
+		log.warn(
+			"ADMIN_API_TOKEN is not set — admin endpoints are unprotected. " +
+				"Set ADMIN_API_TOKEN in production.",
+		);
+		return { authorized: true };
+	}
+
+	if (!providedToken) {
+		return { authorized: false, reason: "Missing authorization token" };
+	}
+
+	// Constant-time comparison.
+	const normalized = providedToken.trim();
+	if (normalized.length !== configuredToken.length) {
+		return { authorized: false, reason: "Invalid authorization token" };
+	}
+
+	let mismatch = 0;
+	for (let i = 0; i < normalized.length; i++) {
+		mismatch |= normalized.charCodeAt(i) ^ configuredToken.charCodeAt(i);
+	}
+
+	if (mismatch !== 0) {
+		return { authorized: false, reason: "Invalid authorization token" };
+	}
+
+	return { authorized: true };
+}
+
+/**
+ * Express/Next.js middleware-style guard for API routes.
+ *
+ * Extracts the token from the `Authorization: Bearer <token>` header and
+ * validates it.  Returns a 401 JSON response when unauthorized.
+ *
+ * Usage in an API route:
+ *
+ *   import { requireAdminToken } from "@techstream/quark-core";
+ *   import { NextResponse } from "next/server";
+ *
+ *   export async function GET(request) {
+ *     const auth = requireAdminToken(request);
+ *     if (!auth.authorized) {
+ *       return NextResponse.json(
+ *         { error: auth.reason },
+ *         { status: 401 },
+ *       );
+ *     }
+ *     // ... handle request
+ *   }
+ *
+ * @param {Request} request — The incoming Next.js/Web API Request object.
+ * @returns {{ authorized: true } | { authorized: false, reason: string, response: Response }}
+ */
+export function requireAdminToken(request) {
+	const authHeader = request.headers.get("authorization") || "";
+	let token = null;
+
+	// Support both "Bearer <token>" and raw token in header.
+	const bearerMatch = authHeader.match(/^Bearer\s+(.+)$/i);
+	if (bearerMatch) {
+		token = bearerMatch[1];
+	} else if (authHeader) {
+		// Allow token directly in header (for tools that don't support Bearer).
+		token = authHeader;
+	}
+
+	// Also check x-admin-token header as a secondary option.
+	if (!token) {
+		token = request.headers.get("x-admin-token");
+	}
+
+	const result = verifyAdminToken(token);
+
+	if (!result.authorized) {
+		log.warn("Admin endpoint rejected", { reason: result.reason });
+		return {
+			authorized: false,
+			reason: result.reason,
+		};
+	}
+
+	return { authorized: true };
+}

package/src/admin.js

@@ -0,0 +1,352 @@
+/**
+ * @techstream/quark-core - Prisma Schema Introspection
+ *
+ * Hand-rolled Prisma schema parser that reads `.prisma` files and
+ * extracts model and enum definitions.  Used by the admin CRUD layer
+ * to auto-generate admin interfaces.
+ *
+ * The parser is deliberately self-contained — no dependency on Prisma
+ * CLI or `@prisma/internals` — so it works in serverless / edge runtimes
+ * where those packages are unavailable.
+ *
+ * Usage:
+ *   import { parseSchema, getModelByName, detectIdField, coerceId } from "@techstream/quark-core/admin";
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_SCHEMA_RELATIVE_PATHS = [
+	"schema.prisma",
+	"packages/db/prisma/schema.prisma",
+	"../../packages/db/prisma/schema.prisma",
+	// In Next.js standalone, cwd = .next/standalone/<app>
+	"../../../../../../packages/db/prisma/schema.prisma",
+];
+
+const SCALAR_TYPES = new Set([
+	"String",
+	"Int",
+	"Float",
+	"Decimal",
+	"BigInt",
+	"Boolean",
+	"DateTime",
+	"Json",
+	"Bytes",
+]);
+
+const NUMERIC_TYPES = new Set(["Int", "Float", "Decimal", "BigInt"]);
+
+const CACHE_TTL_MS = 5_000;
+
+// ---------------------------------------------------------------------------
+// Cache
+// ---------------------------------------------------------------------------
+
+/** @type {{ models: Model[], enums: EnumDef[] } | null} */
+let _parsed = null;
+let _parsedAt = 0;
+
+/**
+ * Reset the schema cache. Useful for testing.
+ */
+export function resetSchemaCache() {
+	_parsed = null;
+	_parsedAt = 0;
+}
+
+// ---------------------------------------------------------------------------
+// Schema file resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Reads the Prisma schema text from disk, resolving the file path from
+ * environment variables, explicit override, or default relative paths.
+ *
+ * @param {string} [schemaPath] - Explicit path override
+ * @returns {string | null} Schema text, or null if not found
+ */
+function readSchemaText(schemaPath) {
+	if (schemaPath) {
+		const resolved = path.resolve(schemaPath);
+		if (existsSync(resolved)) return readFileSync(resolved, "utf-8");
+		throw new Error(
+			`Prisma schema file not found at override path: ${schemaPath}`,
+		);
+	}
+
+	const envPath = process.env.PRISMA_SCHEMA_PATH;
+	if (envPath) {
+		const resolved = path.resolve(envPath);
+		if (existsSync(resolved)) return readFileSync(resolved, "utf-8");
+	}
+
+	const candidates = [
+		...new Set(
+			DEFAULT_SCHEMA_RELATIVE_PATHS.map((rp) =>
+				path.resolve(process.cwd(), rp),
+			),
+		),
+	];
+
+	for (const candidate of candidates) {
+		if (existsSync(candidate)) {
+			return readFileSync(candidate, "utf-8");
+		}
+	}
+
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the Prisma schema and return models + enums.
+ * Result is cached with a 5-second TTL so schema changes are picked up
+ * without requiring a full process restart.
+ *
+ * @param {string} [schemaPath] - Explicit path override
+ * @returns {{ models: Model[], enums: EnumDef[] }}
+ */
+export function parseSchema(schemaPath) {
+	const now = Date.now();
+	if (_parsed && now - _parsedAt < CACHE_TTL_MS) return _parsed;
+
+	const text = readSchemaText(schemaPath);
+	if (text === null) {
+		_parsed = { models: [], enums: [] };
+		_parsedAt = now;
+		return _parsed;
+	}
+
+	_parsed = parseSchemaText(text);
+	_parsedAt = now;
+	return _parsed;
+}
+
+/**
+ * Returns all model definitions from the Prisma schema.
+ * @param {string} [schemaPath]
+ * @returns {Model[]}
+ */
+export function getModels(schemaPath) {
+	return parseSchema(schemaPath).models;
+}
+
+/**
+ * Returns all enum definitions from the Prisma schema.
+ * @param {string} [schemaPath]
+ * @returns {EnumDef[]}
+ */
+export function getEnums(schemaPath) {
+	return parseSchema(schemaPath).enums;
+}
+
+/**
+ * Returns a single model definition by name (case-insensitive).
+ * @param {string} name
+ * @param {string} [schemaPath]
+ * @returns {Model | undefined}
+ */
+export function getModelByName(name, schemaPath) {
+	const lower = name.toLowerCase();
+	return parseSchema(schemaPath).models.find(
+		(m) => m.name.toLowerCase() === lower,
+	);
+}
+
+/**
+ * Returns the @id field for a model, or null if none exists.
+ * @param {Model} model
+ * @returns {Field | null}
+ */
+export function detectIdField(model) {
+	return model.fields.find((f) => f.isId) ?? null;
+}
+
+/**
+ * Coerce a raw string ID to the correct type for a model's @id field.
+ * @param {Model} model
+ * @param {string} rawId
+ * @returns {string | number}
+ */
+export function coerceId(model, rawId) {
+	const field = detectIdField(model);
+	if (field && NUMERIC_TYPES.has(field.type)) return Number(rawId);
+	return rawId;
+}
+
+// ---------------------------------------------------------------------------
+// Internal parser
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} text
+ * @returns {{ models: Model[], enums: EnumDef[] }}
+ */
+function parseSchemaText(text) {
+	const lines = text.split("\n");
+
+	// --- Enums (first pass) ---
+	const enums = [];
+	let inEnum = null;
+
+	for (const line of lines) {
+		const stripped = stripComment(line).trim();
+
+		if (inEnum) {
+			if (stripped === "}") {
+				inEnum = null;
+			} else if (stripped) {
+				const val = stripped.split(/\s+/)[0];
+				if (val && !val.startsWith("@") && !val.startsWith("//")) {
+					enums[enums.length - 1].values.push(val);
+				}
+			}
+		} else {
+			const m = stripped.match(/^enum\s+(\w+)\s*\{/);
+			if (m) {
+				inEnum = m[1];
+				enums.push({ name: m[1], values: [] });
+			}
+		}
+	}
+
+	const enumNames = new Set(enums.map((e) => e.name));
+	const enumByName = Object.fromEntries(enums.map((e) => [e.name, e.values]));
+
+	// --- Models (second pass) ---
+	const models = [];
+	let inModel = null;
+
+	for (const line of lines) {
+		const stripped = stripComment(line).trim();
+
+		if (inModel) {
+			if (stripped === "}") {
+				inModel = null;
+			} else if (stripped && !stripped.startsWith("@@")) {
+				const field = parseField(stripped, enumNames, enumByName);
+				if (field) models[models.length - 1].fields.push(field);
+			}
+		} else {
+			const m = stripped.match(/^model\s+(\w+)\s*\{/);
+			if (m) {
+				inModel = m[1];
+				models.push({ name: m[1], fields: [], dbName: null });
+			}
+		}
+	}
+
+	return { models, enums };
+}
+
+/**
+ * @param {string} line
+ * @returns {string}
+ */
+function stripComment(line) {
+	const idx = line.indexOf("//");
+	return idx >= 0 ? line.substring(0, idx) : line;
+}
+
+/**
+ * @param {string} line
+ * @param {Set<string>} enumNames
+ * @param {Record<string, string[]>} enumByName
+ * @returns {Field | null}
+ */
+function parseField(line, enumNames, enumByName) {
+	const tokens = line.split(/\s+/);
+	if (tokens.length < 2) return null;
+
+	const name = tokens[0];
+	if (name.startsWith("@") || name.startsWith("//")) return null;
+
+	let typeStr = tokens[1];
+
+	const isList = typeStr.endsWith("[]");
+	if (isList) typeStr = typeStr.slice(0, -2);
+
+	const isOptional = typeStr.endsWith("?");
+	if (isOptional) typeStr = typeStr.slice(0, -1);
+
+	const isRequired = !isOptional && !isList;
+
+	const restStr = tokens.slice(2).join(" ");
+
+	let kind;
+	if (SCALAR_TYPES.has(typeStr)) {
+		kind = "scalar";
+	} else if (enumNames.has(typeStr)) {
+		kind = "enum";
+	} else {
+		kind = "object";
+	}
+
+	const isId = /(?:^|\s)@id(?:\s|$)/.test(restStr);
+	const isUnique = /(?:^|\s)@unique(?:\s|$)/.test(restStr);
+	const hasDefaultValue = /(?:^|\s)@default\(/.test(restStr);
+	const isReadOnly = /(?:^|\s)@updatedAt(?:\s|$)/.test(restStr);
+
+	let relationName = null;
+	if (kind === "object") {
+		const namedMatch = restStr.match(/@relation\(\s*name:\s*"([^"]+)"/);
+		relationName = namedMatch ? namedMatch[1] : `${typeStr}To${name}`;
+	}
+
+	return {
+		name,
+		type: typeStr,
+		kind,
+		isList,
+		isRequired,
+		isId,
+		isReadOnly,
+		hasDefaultValue,
+		isUnique,
+		relationName,
+		enumValues: kind === "enum" ? (enumByName[typeStr] ?? null) : null,
+		documentation: null,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} Field
+ * @property {string} name
+ * @property {string} type
+ * @property {"scalar" | "enum" | "object"} kind
+ * @property {boolean} isList
+ * @property {boolean} isRequired
+ * @property {boolean} isId
+ * @property {boolean} isReadOnly
+ * @property {boolean} hasDefaultValue
+ * @property {boolean} isUnique
+ * @property {string | null} relationName
+ * @property {string[] | null} enumValues
+ * @property {string | null} documentation
+ */
+
+/**
+ * @typedef {Object} Model
+ * @property {string} name
+ * @property {Field[]} fields
+ * @property {string | null} dbName
+ */
+
+/**
+ * @typedef {Object} EnumDef
+ * @property {string} name
+ * @property {string[]} values
+ */