@usequark/quark-core 2.6.0 → 2.6.1

package/README.md

@@ -4,15 +4,21 @@ Shared infrastructure for the Quark platform - authentication, job queues, error
 
 ## 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`
+- **Authentication** - Auth.js-compatible config helpers (`createAuthConfig`, `requireAuth`, password hashing) plus framework-agnostic session guards (`requireSession`, `requireSessionRole`, `createAuthMiddleware`), and role checks (`authorization.js`)
+- **Database** - `createPrismaClient(ClientClass)` builds a client from your generated Prisma class, plus connection-string/pool helpers, `pingDatabase()`, and `db-instrumentation`
+- **Job Queue** - BullMQ integration (`createQueue`, `createWorker`, `addJob`, queue definitions)
+- **Email** - Provider registry (`EmailProvider`, `registerEmailProvider`), `createEmailService`, and built-in templates
+- **Storage** - Local filesystem built in; S3 and any S3-compatible endpoint (R2, MinIO) via optional AWS SDK install in the app
+- **Metrics** - Prometheus-style registry (`createMetrics`, `metrics`, `httpRequestsTotal`, `jobQueueDepth`, `jobDuration`, and more)
+- **Health** - `runHealthChecks`, `createDefaultProbes`, `checkStorage`, `checkQueues`, `logHealthReport`
+- **Security** - CSRF tokens, rate limiting (in-memory with Redis fallback), file and multipart validation, request logging, error reporting
+- **Errors** - Standardized error types (`ValidationError`, `NotFoundError`, `UnauthorizedError`, `AppError`, and others)
+- **Utilities** - `retryAsync`, `deepMerge`, `randomString`, `sanitizeId`, `measureTime`, `memoize`, query builder, pagination, cache, locale helpers
 - **Validation** - Zod-based request body validation
+- **Payments and messaging** - Stripe client and webhook helpers, SMS provider
+- **Schema introspection** - `parseSchema`, `getModels`, `getEnums`, `getModelByName`, `coerceId`, `resetSchemaCache`
 - **Redis / Mail** - Connection helpers for Redis and local mail (Mailpit)
+- **Testing** - factories, mocks, and helpers under `@usequark/quark-core/testing`
 
 ## Usage
 
@@ -34,18 +40,30 @@ All modules are re-exported from the package root. See JSDoc comments on each fu
 
 Prefer a subpath when you want a smaller import graph or the browser-safe logger:
 
+Every subpath in `packages/core/package.json` `exports`, verified against the file:
+
 | Subpath | Contents |
 |---|---|
+| `@usequark/quark-core` | everything below, re-exported from the root |
 | `@usequark/quark-core/core` | errors, logger, validation, utils, pagination, csrf, rate limiter, file validation, db |
-| `@usequark/quark-core/db` | Prisma singleton, connection string, pool config, `pingDatabase()` |
-| `@usequark/quark-core/admin` | Prisma schema introspection helpers |
 | `@usequark/quark-core/auth` | auth config helpers + session guards |
 | `@usequark/quark-core/auth/middleware` | session guards only |
+| `@usequark/quark-core/db` | `createPrismaClient`, connection string, pool config, `pingDatabase()` |
+| `@usequark/quark-core/queue` | BullMQ queue and worker helpers |
+| `@usequark/quark-core/email` | `EmailProvider`, `registerEmailProvider`, `createEmailService` |
+| `@usequark/quark-core/errors` | error classes only |
+| `@usequark/quark-core/health` | health check runners and default probes |
+| `@usequark/quark-core/metrics` | metrics registry and default instruments |
 | `@usequark/quark-core/storage` | local adapter, storage factory, key/URL helpers, `createS3Storage` |
 | `@usequark/quark-core/storage/s3` | S3 adapter only |
-| `@usequark/quark-core/logger` | browser-safe logger |
-| `@usequark/quark-core/locale` | locale helpers |
+| `@usequark/quark-core/sms` | SMS provider |
 | `@usequark/quark-core/stripe` | Stripe client + webhook helpers |
+| `@usequark/quark-core/admin` | Prisma schema introspection helpers |
+| `@usequark/quark-core/locale` | locale helpers |
+| `@usequark/quark-core/logger` | browser-safe logger |
+| `@usequark/quark-core/testing` | test factories, mocks, helpers |
+
+`createPrismaClient` is a factory, not a singleton: it takes your generated Prisma `Client` class as its argument so core never depends on your generated client path.
 
 `@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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-core",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "Core utilities for Quark apps: auth, BullMQ queues, Redis, email, storage, rate limiting, logging, and error handling",
   "keywords": [
     "quark",

package/src/csrf.js

@@ -96,12 +96,29 @@ export function requireCsrfToken(request) {
 /**
  * Creates a CSRF-protected API route handler.
  * Wraps your handler and automatically validates CSRF tokens.
+ *
+ * A failed check produces a `401` Response rather than a thrown error. The check
+ * runs in this wrapper, outside the route handler's own try/catch, so a throw here
+ * escapes `handleError` entirely: the client got an unhandled rejection instead of
+ * the status code its fetch handling expects. Returning the Response here keeps the
+ * rejection path reserved for genuine faults.
+ *
  * @param {Function} handler - Your API route handler
  * @returns {Function} Wrapped handler with CSRF protection
  */
 export function withCsrfProtection(handler) {
 	return async (request, ...args) => {
-		requireCsrfToken(request);
+		try {
+			requireCsrfToken(request);
+		} catch (error) {
+			if (error instanceof UnauthorizedError) {
+				return Response.json(error.toJSON(), {
+					status: error.statusCode,
+					headers: { "Cache-Control": "no-store" },
+				});
+			}
+			throw error;
+		}
 		return handler(request, ...args);
 	};
 }

package/src/csrf.test.js

@@ -166,4 +166,80 @@ test("CSRF Module", async (t) => {
 		assert.strictEqual(result.body, "success");
 		assert.strictEqual(result.request, request);
 	});
+
+	await t.test(
+		"withCsrfProtection returns 401 instead of throwing",
+		async () => {
+			// The check runs in the wrapper, outside the route handler's own
+			// try/catch, so a throw here escapes `handleError` and reaches the client
+			// as an unhandled rejection. The status code is what fetch handling expects.
+			const request = mockRequest({
+				method: "POST",
+				url: "http://localhost/api/posts",
+				headers: { "x-csrf-token": generateCsrfToken() },
+			});
+
+			let handlerCalled = false;
+			const protectedHandler = withCsrfProtection(async () => {
+				handlerCalled = true;
+				return { unreachable: true };
+			});
+
+			const response = await protectedHandler(request);
+
+			assert(response instanceof Response);
+			assert.strictEqual(response.status, 401);
+			assert.strictEqual(response.headers.get("Cache-Control"), "no-store");
+
+			const body = await response.json();
+			assert.strictEqual(body.code, "UNAUTHORIZED");
+			assert.strictEqual(body.statusCode, 401);
+			// The handler must not run on a rejected token.
+			assert.strictEqual(handlerCalled, false);
+		},
+	);
+
+	await t.test(
+		"withCsrfProtection returns 401 for a mismatched token",
+		async () => {
+			const token = generateCsrfToken();
+			const request = mockRequest({
+				method: "POST",
+				url: "http://localhost/api/posts",
+				headers: {
+					"x-csrf-token": "wrong-token-of-same-len",
+					cookie: `csrf_token=${encodeURIComponent(token)}`,
+				},
+			});
+
+			const protectedHandler = withCsrfProtection(async () => ({
+				unreachable: true,
+			}));
+			const response = await protectedHandler(request);
+
+			assert.strictEqual(response.status, 401);
+		},
+	);
+
+	await t.test(
+		"withCsrfProtection still rejects for a non-CSRF error",
+		async () => {
+			// Only UnauthorizedError is converted. Anything else from the check is a
+			// genuine fault and must keep propagating rather than being reported to the
+			// client as an authentication problem.
+			const request = mockRequest({ method: "POST" });
+			request.headers.get = () => {
+				throw new TypeError("headers.get exploded");
+			};
+
+			const protectedHandler = withCsrfProtection(async () => ({
+				unreachable: true,
+			}));
+
+			await assert.rejects(
+				() => protectedHandler(request),
+				/headers.get exploded/,
+			);
+		},
+	);
 });

package/src/db.js

@@ -3,7 +3,7 @@
  *
  * Shared Prisma client singleton, connection-string builder, pool config,
  * and a lightweight health-check ping.  These replace the per-project
- * re-implementations in Regina / Pawdora / Trenchmate.
+ * re-implementations that every app ends up writing by hand.
  *
  * Usage:
  *   import { createPrismaClient, getConnectionString, pingDatabase } from "@usequark/quark-core/db";