@usequark/quark-core 2.5.4

package/src/admin.test.js

@@ -0,0 +1,257 @@
+import assert from "node:assert/strict";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+	coerceId,
+	detectIdField,
+	getEnums,
+	getModelByName,
+	getModels,
+	parseSchema,
+	resetSchemaCache,
+} from "./admin.js";
+
+// ---------------------------------------------------------------------------
+// Fixture: a minimal Prisma schema
+// ---------------------------------------------------------------------------
+
+const SCHEMA = `
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+enum Role {
+  ADMIN
+  EDITOR
+  VIEWER
+}
+
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique
+  name      String?
+  role      Role     @default(VIEWER)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  posts Post[]
+}
+
+model Post {
+  id        Int      @id @default(autoincrement())
+  title     String
+  body      String?
+  published Boolean  @default(false)
+  author    User     @relation(fields: [authorId], references: [id])
+  authorId  Int
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+`;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+let schemaDir;
+
+async function setup() {
+	schemaDir = await mkdir(join(tmpdir(), "admin-test"), { recursive: true });
+	await writeFile(join(schemaDir, "schema.prisma"), SCHEMA);
+	resetSchemaCache();
+}
+
+async function teardown() {
+	await rm(schemaDir, { recursive: true, force: true });
+	resetSchemaCache();
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+test("admin - parseSchema returns models and enums", async () => {
+	await setup();
+	try {
+		const result = parseSchema(join(schemaDir, "schema.prisma"));
+		assert.ok(result.models.length > 0, "should have models");
+		assert.ok(result.enums.length > 0, "should have enums");
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - getModels returns User and Post", async () => {
+	await setup();
+	try {
+		const models = getModels(join(schemaDir, "schema.prisma"));
+		const names = models.map((m) => m.name);
+		assert.ok(names.includes("User"));
+		assert.ok(names.includes("Post"));
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - getEnums returns Role", async () => {
+	await setup();
+	try {
+		const enums = getEnums(join(schemaDir, "schema.prisma"));
+		const roleEnum = enums.find((e) => e.name === "Role");
+		assert.ok(roleEnum, "should find Role enum");
+		assert.deepEqual(roleEnum.values, ["ADMIN", "EDITOR", "VIEWER"]);
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - getModelByName is case-insensitive", async () => {
+	await setup();
+	try {
+		const user = getModelByName("user", join(schemaDir, "schema.prisma"));
+		assert.ok(user);
+		assert.equal(user.name, "User");
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - getModelByName returns undefined for unknown model", async () => {
+	await setup();
+	try {
+		const result = getModelByName("Comment", join(schemaDir, "schema.prisma"));
+		assert.equal(result, undefined);
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - detectIdField returns the @id field", async () => {
+	await setup();
+	try {
+		const user = getModelByName("User", join(schemaDir, "schema.prisma"));
+		const idField = detectIdField(user);
+		assert.ok(idField);
+		assert.equal(idField.name, "id");
+		assert.equal(idField.type, "Int");
+		assert.equal(idField.isId, true);
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - detectIdField returns null for model without @id", async () => {
+	const fakeModel = {
+		name: "NoId",
+		fields: [{ name: "name", type: "String", isId: false }],
+	};
+	assert.equal(detectIdField(fakeModel), null);
+});
+
+test("admin - coerceId converts string to number for Int @id", async () => {
+	await setup();
+	try {
+		const user = getModelByName("User", join(schemaDir, "schema.prisma"));
+		assert.equal(coerceId(user, "42"), 42);
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - coerceId returns string for String @id", async () => {
+	const stringIdModel = {
+		name: "Thing",
+		fields: [{ name: "id", type: "String", isId: true }],
+	};
+	assert.equal(coerceId(stringIdModel, "abc-123"), "abc-123");
+});
+
+test("admin - User model has expected fields", async () => {
+	await setup();
+	try {
+		const user = getModelByName("User", join(schemaDir, "schema.prisma"));
+		const fieldNames = user.fields.map((f) => f.name);
+		assert.ok(fieldNames.includes("id"));
+		assert.ok(fieldNames.includes("email"));
+		assert.ok(fieldNames.includes("name"));
+		assert.ok(fieldNames.includes("role"));
+		assert.ok(fieldNames.includes("createdAt"));
+		assert.ok(fieldNames.includes("updatedAt"));
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - User.email is marked @unique", async () => {
+	await setup();
+	try {
+		const user = getModelByName("User", join(schemaDir, "schema.prisma"));
+		const email = user.fields.find((f) => f.name === "email");
+		assert.ok(email.isUnique);
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - Post.author is an object relation", async () => {
+	await setup();
+	try {
+		const post = getModelByName("Post", join(schemaDir, "schema.prisma"));
+		const author = post.fields.find((f) => f.name === "author");
+		assert.equal(author.kind, "object");
+		assert.equal(author.type, "User");
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - Post.role field resolves enum kind", async () => {
+	await setup();
+	try {
+		const user = getModelByName("User", join(schemaDir, "schema.prisma"));
+		const role = user.fields.find((f) => f.name === "role");
+		assert.equal(role.kind, "enum");
+		assert.equal(role.type, "Role");
+		assert.deepEqual(role.enumValues, ["ADMIN", "EDITOR", "VIEWER"]);
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - resetSchemaCache clears the cache", async () => {
+	await setup();
+	try {
+		parseSchema(join(schemaDir, "schema.prisma"));
+		resetSchemaCache();
+		// After reset, next call re-parses from disk — no error should occur
+		const result = parseSchema(join(schemaDir, "schema.prisma"));
+		assert.ok(result.models.length > 0);
+	} finally {
+		await teardown();
+	}
+});
+
+test("admin - parseSchema returns empty models/enums when no schema found at default paths", () => {
+	// Override cwd to a path with no schema.prisma and no env var
+	const origCwd = process.cwd;
+	const origEnv = process.env.PRISMA_SCHEMA_PATH;
+	try {
+		process.cwd = () => "/nonexistent";
+		delete process.env.PRISMA_SCHEMA_PATH;
+		resetSchemaCache();
+		const result = parseSchema();
+		assert.ok(Array.isArray(result.models));
+		assert.ok(Array.isArray(result.enums));
+	} finally {
+		process.cwd = origCwd;
+		if (origEnv !== undefined) process.env.PRISMA_SCHEMA_PATH = origEnv;
+	}
+});

package/src/auth/index.js

@@ -0,0 +1,160 @@
+/**
+ * @techstream/quark-core - Authentication Module
+ * Provides next-auth initialization and session management helpers
+ */
+
+import { UnauthorizedError } from "../errors.js";
+import { createLogger } from "../logger.js";
+
+export * from "./middleware.js";
+export * from "./password.js";
+
+const logger = createLogger({ name: "auth" });
+
+/**
+ * Resolves the auth secret from the supported environment variables.
+ * Prefers NEXTAUTH_SECRET for compatibility, but also accepts AUTH_SECRET.
+ * @returns {string|null}
+ */
+export const getAuthSecret = () => {
+	return process.env.NEXTAUTH_SECRET || process.env.AUTH_SECRET || null;
+};
+
+/**
+ * Detects whether the app is running on a deployed (non-local) environment.
+ * @returns {boolean}
+ */
+function isDeployed() {
+	const url = process.env.AUTH_URL || process.env.NEXTAUTH_URL;
+	if (url && !/localhost|127\.0\.0\.1|0\.0\.0\.0/.test(url)) return true;
+	return !!(
+		process.env.VERCEL ||
+		process.env.CF_PAGES ||
+		process.env.RAILWAY_SERVICE_ID ||
+		process.env.AUTH_TRUST_HOST === "true" ||
+		process.env.NODE_ENV !== "production"
+	);
+}
+
+/**
+ * Creates a next-auth configuration object with sensible defaults.
+ * Designed to be extended by applications.
+ * @param {Object} options - Configuration options
+ * @param {Array} options.providers - Next-auth providers (GitHub, Google, etc.)
+ * @param {Object} options.callbacks - next-auth callbacks (jwt, session, etc.)
+ * @param {Object} options.session - Session configuration
+ * @param {string} options.secret - NEXTAUTH_SECRET (defaults to env var)
+ * @param {string} options.trustHost - When false, next-auth rejects requests from unknown hosts
+ * @returns {Object} Complete next-auth configuration
+ */
+export const createAuthConfig = (options = {}) => {
+	const {
+		providers = [],
+		callbacks = {},
+		session = {},
+		secret = getAuthSecret(),
+		...rest
+	} = options;
+
+	if (!secret) {
+		throw new Error(
+			"NEXTAUTH_SECRET or AUTH_SECRET must be set (env var or options.secret)",
+		);
+	}
+
+	const trustHost = rest.trustHost ?? isDeployed();
+
+	return {
+		secret,
+		providers,
+		session: {
+			strategy: "jwt",
+			maxAge: 30 * 24 * 60 * 60, // 30 days
+			updateAge: 24 * 60 * 60, // 24 hours
+			...session,
+		},
+		callbacks: {
+			async jwt({ token, user }) {
+				if (user) {
+					token.id = user.id;
+					token.email = user.email;
+					token.name = user.name;
+					token.role = user.role || "viewer";
+				}
+				return token;
+			},
+			async session({ session, token }) {
+				if (session.user) {
+					session.user.id = token.id;
+					session.user.role = token.role;
+				}
+				return session;
+			},
+			...callbacks,
+		},
+		pages: {
+			signIn: "/auth/signin",
+			error: "/auth/error",
+		},
+		trustHost,
+		...rest,
+	};
+};
+
+/**
+ * Utility to safely get the current session (works in both server & edge)
+ * @param {Function} getSession - The next-auth getSession function
+ * @returns {Promise<Object|null>} Session object or null if not authenticated
+ */
+export const getCurrentSession = async (getSession) => {
+	try {
+		return await getSession();
+	} catch (error) {
+		logger.error("Failed to get session", {
+			message: error?.message ?? String(error),
+		});
+		return null;
+	}
+};
+
+/**
+ * Checks if a user is authenticated
+ * @param {Object} session - Session object from next-auth
+ * @returns {boolean} True if user is authenticated
+ */
+export const isAuthenticated = (session) => {
+	return session?.user?.email;
+};
+
+/**
+ * Gets user ID from session
+ * @param {Object} session - Session object from next-auth
+ * @returns {string|null} User ID or null
+ */
+export const getUserId = (session) => {
+	return session?.user?.id || null;
+};
+
+/**
+ * Gets user email from session
+ * @param {Object} session - Session object from next-auth
+ * @returns {string|null} User email or null
+ */
+export const getUserEmail = (session) => {
+	return session?.user?.email || null;
+};
+
+/**
+ * Validates that a request has a valid session
+ * Throws UnauthorizedError if not authenticated
+ * @param {Object} session - Session object from next-auth
+ * @throws {UnauthorizedError} If session is invalid
+ * @returns {string} User ID
+ */
+export const requireAuth = (session) => {
+	const userId = getUserId(session);
+	if (!userId) {
+		throw new UnauthorizedError("Authentication required");
+	}
+	return userId;
+};

package/src/auth/middleware.js

@@ -0,0 +1,106 @@
+/**
+ * @techstream/quark-core - Auth Middleware
+ *
+ * Lightweight, framework-agnostic authentication middleware for Server
+ * Actions and API routes.  The caller supplies a `getSession` function
+ * (e.g. NextAuth's `auth()`) — this module adds the guard logic.
+ *
+ * Usage:
+ *   import { requireSession, requireSessionRole, createAuthMiddleware } from "@techstream/quark-core/auth/middleware";
+ *
+ *   // In a Server Action:
+ *   const session = await requireSession(() => auth());
+ *   // session is guaranteed non-null; UnauthorizedError thrown otherwise.
+ */
+
+import { ForbiddenError, UnauthorizedError } from "../errors.js";
+
+/**
+ * Requires a valid session.  Throws `UnauthorizedError` if the session
+ * is missing or has no user.
+ *
+ * @template T
+ * @param {() => Promise<T | null>} getSession - Async function that returns the session (or null)
+ * @returns {Promise<T>} The session, guaranteed non-null
+ * @throws {UnauthorizedError}
+ */
+export async function requireSession(getSession) {
+	const session = await getSession();
+	if (!session) {
+		throw new UnauthorizedError("Authentication required");
+	}
+	return session;
+}
+
+/**
+ * Requires a valid session **and** that the user has the specified role.
+ *
+ * @template {{ user?: { role?: string } | null }} S
+ * @param {string} role - Required role (case-insensitive comparison)
+ * @param {() => Promise<S | null>} getSession - Async function that returns the session (or null)
+ * @returns {Promise<S>} The session, guaranteed non-null with the correct role
+ * @throws {UnauthorizedError} When the session is missing
+ * @throws {ForbiddenError}   When the user's role does not match
+ */
+export async function requireSessionRole(role, getSession) {
+	const session = await requireSession(getSession);
+	const userRole = session?.user?.role;
+
+	if (!userRole || userRole.toLowerCase() !== role.toLowerCase()) {
+		throw new ForbiddenError(
+			`Role "${role}" required — you have "${userRole || "none"}"`,
+		);
+	}
+
+	return session;
+}
+
+/**
+ * Creates a reusable auth middleware from a configuration object.
+ *
+ * @param {Object} options
+ * @param {() => Promise<any | null>} options.getSession - Async function returning the session
+ * @param {string} [options.roleField="role"] - Field on `session.user` that holds the role
+ * @returns {{
+ *   requireSession: () => Promise<any>,
+ *   requireSessionRole: (role: string) => Promise<any>
+ * }}
+ */
+export function createAuthMiddleware({ getSession, roleField = "role" }) {
+	/**
+	 * @returns {Promise<any>} The session
+	 */
+	async function resolveSession() {
+		const session = await getSession();
+		if (!session) {
+			throw new UnauthorizedError("Authentication required");
+		}
+		return session;
+	}
+
+	return {
+		/**
+		 * @returns {Promise<any>} The session
+		 */
+		async requireSession() {
+			return resolveSession();
+		},
+
+		/**
+		 * @param {string} role - Required role
+		 * @returns {Promise<any>} The session
+		 */
+		async requireSessionRole(role) {
+			const session = await resolveSession();
+			const userRole = session?.user?.[roleField];
+
+			if (!userRole || userRole.toLowerCase() !== role.toLowerCase()) {
+				throw new ForbiddenError(
+					`Role "${role}" required — you have "${userRole || "none"}"`,
+				);
+			}
+
+			return session;
+		},
+	};
+}

package/src/auth/middleware.test.js

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ForbiddenError, UnauthorizedError } from "../errors.js";
+import {
+	createAuthMiddleware,
+	requireSession,
+	requireSessionRole,
+} from "./middleware.js";
+
+// ---------------------------------------------------------------------------
+// requireSession
+// ---------------------------------------------------------------------------
+
+test("auth/middleware - requireSession returns session when valid", async () => {
+	const session = { user: { id: "1", email: "a@b.com" } };
+	const result = await requireSession(async () => session);
+	assert.deepEqual(result, session);
+});
+
+test("auth/middleware - requireSession throws UnauthorizedError when session is null", async () => {
+	await assert.rejects(
+		() => requireSession(async () => null),
+		(err) => err instanceof UnauthorizedError,
+	);
+});
+
+test("auth/middleware - requireSession throws UnauthorizedError when session is undefined", async () => {
+	await assert.rejects(
+		() => requireSession(async () => undefined),
+		(err) => err instanceof UnauthorizedError,
+	);
+});
+
+// ---------------------------------------------------------------------------
+// requireSessionRole
+// ---------------------------------------------------------------------------
+
+test("auth/middleware - requireSessionRole returns session when role matches", async () => {
+	const session = { user: { id: "1", role: "admin" } };
+	const result = await requireSessionRole("admin", async () => session);
+	assert.deepEqual(result, session);
+});
+
+test("auth/middleware - requireSessionRole is case-insensitive", async () => {
+	const session = { user: { id: "1", role: "Admin" } };
+	const result = await requireSessionRole("admin", async () => session);
+	assert.deepEqual(result, session);
+});
+
+test("auth/middleware - requireSessionRole throws ForbiddenError when role does not match", async () => {
+	const session = { user: { id: "1", role: "viewer" } };
+	await assert.rejects(
+		() => requireSessionRole("admin", async () => session),
+		(err) => err instanceof ForbiddenError,
+	);
+});
+
+test("auth/middleware - requireSessionRole throws UnauthorizedError when session is null", async () => {
+	await assert.rejects(
+		() => requireSessionRole("admin", async () => null),
+		(err) => err instanceof UnauthorizedError,
+	);
+});
+
+test("auth/middleware - requireSessionRole throws ForbiddenError when user has no role", async () => {
+	const session = { user: { id: "1" } };
+	await assert.rejects(
+		() => requireSessionRole("admin", async () => session),
+		(err) => err instanceof ForbiddenError,
+	);
+});
+
+// ---------------------------------------------------------------------------
+// createAuthMiddleware
+// ---------------------------------------------------------------------------
+
+test("auth/middleware - createAuthMiddleware requireSession works", async () => {
+	const session = { user: { id: "42", role: "editor" } };
+	const mw = createAuthMiddleware({ getSession: async () => session });
+	const result = await mw.requireSession();
+	assert.deepEqual(result, session);
+});
+
+test("auth/middleware - createAuthMiddleware requireSession throws on null session", async () => {
+	const mw = createAuthMiddleware({ getSession: async () => null });
+	await assert.rejects(
+		() => mw.requireSession(),
+		(err) => err instanceof UnauthorizedError,
+	);
+});
+
+test("auth/middleware - createAuthMiddleware requireSessionRole works", async () => {
+	const session = { user: { id: "42", role: "admin" } };
+	const mw = createAuthMiddleware({ getSession: async () => session });
+	const result = await mw.requireSessionRole("admin");
+	assert.deepEqual(result, session);
+});
+
+test("auth/middleware - createAuthMiddleware requireSessionRole throws ForbiddenError", async () => {
+	const session = { user: { id: "42", role: "viewer" } };
+	const mw = createAuthMiddleware({ getSession: async () => session });
+	await assert.rejects(
+		() => mw.requireSessionRole("admin"),
+		(err) => err instanceof ForbiddenError,
+	);
+});
+
+test("auth/middleware - createAuthMiddleware uses custom roleField", async () => {
+	const flatSession = { user: { id: "42", accessLevel: "admin" } };
+	const mw = createAuthMiddleware({
+		getSession: async () => flatSession,
+		roleField: "accessLevel",
+	});
+	const result = await mw.requireSessionRole("admin");
+	assert.deepEqual(result, flatSession);
+});

package/src/auth/password.js

@@ -0,0 +1,9 @@
+import bcrypt from "bcryptjs";
+
+export async function hashPassword(password) {
+	return bcrypt.hash(password, 12);
+}
+
+export async function verifyPassword(password, hashedPassword) {
+	return bcrypt.compare(password, hashedPassword);
+}