@usequark/quark-core 2.5.4

package/src/authorization.test.js

@@ -0,0 +1,314 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+import {
+	authorization,
+	createAuthorization,
+	defaultPolicy,
+	requireRole,
+	withAuthorization,
+} from "./authorization.js";
+import { ForbiddenError } from "./errors.js";
+
+describe("authorization", () => {
+	/** @type {ReturnType<typeof createAuthorization>} */
+	let auth;
+
+	beforeEach(() => {
+		auth = createAuthorization();
+	});
+
+	describe("can()", () => {
+		it("returns true for admin with wildcard permissions", () => {
+			const user = { id: "u1", role: "admin" };
+			assert.equal(auth.can(user, "create", "post"), true);
+			assert.equal(auth.can(user, "delete", "user"), true);
+			assert.equal(auth.can(user, "anything", "anywhere"), true);
+		});
+
+		it("returns true for editor with post actions", () => {
+			const user = { id: "u2", role: "editor" };
+			assert.equal(auth.can(user, "create", "post"), true);
+			assert.equal(auth.can(user, "update", "post"), true);
+			assert.equal(auth.can(user, "delete", "post"), true);
+			assert.equal(auth.can(user, "read", "post"), true);
+		});
+
+		it("returns true for editor reading users", () => {
+			const user = { id: "u2", role: "editor" };
+			assert.equal(auth.can(user, "read", "user"), true);
+		});
+
+		it("returns false for editor trying to delete users", () => {
+			const user = { id: "u2", role: "editor" };
+			assert.equal(auth.can(user, "delete", "user"), false);
+		});
+
+		it("returns false for viewer trying to write", () => {
+			const user = { id: "u3", role: "viewer" };
+			assert.equal(auth.can(user, "create", "post"), false);
+			assert.equal(auth.can(user, "update", "post"), false);
+			assert.equal(auth.can(user, "delete", "post"), false);
+		});
+
+		it("returns true for viewer reading posts and users", () => {
+			const user = { id: "u3", role: "viewer" };
+			assert.equal(auth.can(user, "read", "post"), true);
+			assert.equal(auth.can(user, "read", "user"), true);
+		});
+
+		it("owner can update their own resource", () => {
+			const user = { id: "u3", role: "viewer" };
+			const context = { ownerId: "u3" };
+			assert.equal(auth.can(user, "update", "post", context), true);
+		});
+
+		it("owner can delete their own resource", () => {
+			const user = { id: "u3", role: "viewer" };
+			const context = { ownerId: "u3" };
+			assert.equal(auth.can(user, "delete", "post", context), true);
+		});
+
+		it("non-owner cannot update another user's resource", () => {
+			const user = { id: "u3", role: "viewer" };
+			const context = { ownerId: "u999" };
+			assert.equal(auth.can(user, "update", "post", context), false);
+		});
+
+		it("ownership does not apply for non-owner actions", () => {
+			const user = { id: "u3", role: "viewer" };
+			const context = { ownerId: "u3" };
+			// "create" is not in ownerActions by default
+			assert.equal(auth.can(user, "create", "post", context), false);
+		});
+
+		it("applies defaultRole when user has no role", () => {
+			const user = { id: "u4" };
+			// defaultRole is "viewer" - can read but not create
+			assert.equal(auth.can(user, "read", "post"), true);
+			assert.equal(auth.can(user, "create", "post"), false);
+		});
+	});
+
+	describe("authorize()", () => {
+		it("throws ForbiddenError when denied", () => {
+			const user = { id: "u3", role: "viewer" };
+			assert.throws(
+				() => auth.authorize(user, "create", "post"),
+				(err) => err instanceof ForbiddenError,
+			);
+		});
+
+		it("does not throw when allowed", () => {
+			const user = { id: "u1", role: "admin" };
+			assert.doesNotThrow(() => auth.authorize(user, "create", "post"));
+		});
+
+		it("includes user and action information in error message", () => {
+			const user = { id: "u3", role: "viewer" };
+			assert.throws(() => auth.authorize(user, "create", "post"), {
+				message: "User u3 is not allowed to create post",
+			});
+		});
+	});
+
+	describe("hasPermission()", () => {
+		it("returns true for exact match", () => {
+			assert.equal(auth.hasPermission("viewer", "read", "post"), true);
+			assert.equal(auth.hasPermission("viewer", "read", "user"), true);
+		});
+
+		it("returns false for no match", () => {
+			assert.equal(auth.hasPermission("viewer", "create", "post"), false);
+		});
+
+		it("returns true with resource wildcard", () => {
+			assert.equal(auth.hasPermission("admin", "create", "anything"), true);
+		});
+
+		it("returns true with action wildcard", () => {
+			assert.equal(auth.hasPermission("editor", "delete", "post"), true);
+		});
+
+		it("returns false for unknown role", () => {
+			assert.equal(auth.hasPermission("unknown", "read", "post"), false);
+		});
+	});
+
+	describe("getRolePermissions()", () => {
+		it("returns permissions for a valid role", () => {
+			const perms = auth.getRolePermissions("viewer");
+			assert.deepStrictEqual(perms, [
+				{ resource: "post", action: "read" },
+				{ resource: "user", action: "read" },
+			]);
+		});
+
+		it("returns empty array for unknown role", () => {
+			const perms = auth.getRolePermissions("nonexistent");
+			assert.deepStrictEqual(perms, []);
+		});
+	});
+
+	describe("addRole() and removeRole()", () => {
+		it("addRole() makes new role available", () => {
+			auth.addRole("moderator", [
+				{ resource: "post", action: "update" },
+				{ resource: "post", action: "delete" },
+			]);
+			const user = { id: "u5", role: "moderator" };
+			assert.equal(auth.can(user, "update", "post"), true);
+			assert.equal(auth.can(user, "delete", "post"), true);
+			assert.equal(auth.can(user, "create", "post"), false);
+		});
+
+		it("removeRole() removes a role", () => {
+			auth.removeRole("editor");
+			assert.deepStrictEqual(auth.getRolePermissions("editor"), []);
+			assert.equal(auth.hasPermission("editor", "read", "post"), false);
+		});
+	});
+
+	describe("extendPolicy()", () => {
+		it("merges new roles into existing policy", () => {
+			auth.extendPolicy({
+				roles: {
+					supermod: {
+						permissions: [{ resource: "*", action: "delete" }],
+					},
+				},
+			});
+
+			const user = { id: "u6", role: "supermod" };
+			assert.equal(auth.can(user, "delete", "post"), true);
+			assert.equal(auth.can(user, "delete", "user"), true);
+			assert.equal(auth.can(user, "create", "post"), false);
+		});
+
+		it("preserves existing roles when extending", () => {
+			auth.extendPolicy({
+				roles: {
+					custom: {
+						permissions: [{ resource: "report", action: "read" }],
+					},
+				},
+			});
+			// Original roles still work
+			assert.equal(auth.hasPermission("admin", "create", "post"), true);
+			assert.equal(auth.hasPermission("viewer", "read", "post"), true);
+		});
+
+		it("can override defaultRole", () => {
+			auth.extendPolicy({ defaultRole: "editor" });
+			const user = { id: "u7" };
+			assert.equal(auth.can(user, "create", "post"), true);
+		});
+	});
+
+	describe("requireRole()", () => {
+		it("does not throw when session user has an allowed role", () => {
+			const guard = requireRole("admin", "editor");
+			const session = { user: { id: "u1", role: "admin" } };
+			assert.doesNotThrow(() => guard(session));
+		});
+
+		it("throws ForbiddenError when session user role is not allowed", () => {
+			const guard = requireRole("admin");
+			const session = { user: { id: "u2", role: "viewer" } };
+			assert.throws(
+				() => guard(session),
+				(err) => err instanceof ForbiddenError,
+			);
+		});
+
+		it("throws ForbiddenError when session has no role", () => {
+			const guard = requireRole("admin");
+			const session = { user: { id: "u2" } };
+			assert.throws(
+				() => guard(session),
+				(err) => err instanceof ForbiddenError,
+			);
+		});
+
+		it("throws ForbiddenError when session has no user", () => {
+			const guard = requireRole("admin");
+			assert.throws(
+				() => guard({}),
+				(err) => err instanceof ForbiddenError,
+			);
+		});
+	});
+
+	describe("withAuthorization()", () => {
+		it("calls handler when authorized", async () => {
+			let called = false;
+			const handler = (_req, _session) => {
+				called = true;
+				return "ok";
+			};
+			const wrapped = withAuthorization(handler, {
+				action: "read",
+				resource: "post",
+			});
+			const session = { user: { id: "u1", role: "admin" } };
+			const result = await wrapped({}, session);
+			assert.equal(called, true);
+			assert.equal(result, "ok");
+		});
+
+		it("throws ForbiddenError when not authorized", async () => {
+			const handler = () => "ok";
+			const wrapped = withAuthorization(handler, {
+				action: "create",
+				resource: "post",
+			});
+			const session = { user: { id: "u3", role: "viewer" } };
+			await assert.rejects(() => wrapped({}, session), ForbiddenError);
+		});
+
+		it("throws ForbiddenError when no user in session", async () => {
+			const handler = () => "ok";
+			const wrapped = withAuthorization(handler, {
+				action: "read",
+				resource: "post",
+			});
+			await assert.rejects(() => wrapped({}, {}), ForbiddenError);
+		});
+
+		it("passes context from getContext to authorization", async () => {
+			const handler = () => "ok";
+			const wrapped = withAuthorization(handler, {
+				action: "update",
+				resource: "post",
+				getContext: () => ({ ownerId: "owner1" }),
+			});
+			// viewer can update own resource via ownership
+			const session = { user: { id: "owner1", role: "viewer" } };
+			const result = await wrapped({}, session);
+			assert.equal(result, "ok");
+		});
+	});
+
+	describe("default instance", () => {
+		it("exports a working default authorization instance", () => {
+			assert.equal(
+				authorization.can({ id: "u1", role: "admin" }, "create", "post"),
+				true,
+			);
+			assert.equal(
+				authorization.can({ id: "u1", role: "viewer" }, "create", "post"),
+				false,
+			);
+		});
+	});
+
+	describe("defaultPolicy", () => {
+		it("is exported and has expected structure", () => {
+			assert.ok(defaultPolicy.roles.admin);
+			assert.ok(defaultPolicy.roles.editor);
+			assert.ok(defaultPolicy.roles.viewer);
+			assert.equal(defaultPolicy.defaultRole, "viewer");
+			assert.equal(defaultPolicy.ownershipField, "ownerId");
+			assert.deepStrictEqual(defaultPolicy.ownerActions, ["update", "delete"]);
+		});
+	});
+});

package/src/cache.js

@@ -0,0 +1,137 @@
+/**
+ * Cache utility for Redis-based caching with TTL and invalidation.
+ * Designed to be used with any Redis client (ioredis, redis, etc.)
+ *
+ * @example
+ * ```js
+ * import Redis from "ioredis";
+ * import { createCache } from "@quark/core";
+ *
+ * const redis = new Redis();
+ * const cache = createCache(redis, { prefix: "app:", defaultTTL: 600 });
+ *
+ * await cache.set("user:1", { name: "Alice" });
+ * const user = await cache.get("user:1");
+ * ```
+ */
+
+/**
+ * Creates a cache instance backed by a Redis client.
+ *
+ * @param {import("ioredis").Redis} redisClient - any Redis client with get/set/del/keys/expire methods
+ * @param {Object} [options]
+ * @param {string} [options.prefix="cache:"] - key prefix for namespacing
+ * @param {number} [options.defaultTTL=300] - default TTL in seconds (5 minutes)
+ * @returns {ReturnType<typeof createCache>}
+ */
+export function createCache(redisClient, options = {}) {
+	const { prefix = "cache:", defaultTTL = 300 } = options;
+
+	return {
+		/**
+		 * Get a cached value.
+		 *
+		 * @param {string} key
+		 * @returns {Promise<any|null>} Parsed value or null if not found
+		 */
+		async get(key) {
+			const raw = await redisClient.get(`${prefix}${key}`);
+			if (raw === null || raw === undefined) return null;
+			try {
+				return JSON.parse(raw);
+			} catch {
+				return null;
+			}
+		},
+
+		/**
+		 * Set a cached value with optional TTL (atomic SET + EX).
+		 *
+		 * @param {string} key
+		 * @param {any} value - will be JSON.stringified
+		 * @param {number} [ttl] - TTL in seconds, defaults to defaultTTL
+		 */
+		async set(key, value, ttl) {
+			const prefixedKey = `${prefix}${key}`;
+			const serialized = JSON.stringify(value);
+			await redisClient.set(prefixedKey, serialized, "EX", ttl ?? defaultTTL);
+		},
+
+		/**
+		 * Delete a cached key.
+		 *
+		 * @param {string} key
+		 */
+		async del(key) {
+			await redisClient.del(`${prefix}${key}`);
+		},
+
+		/**
+		 * Delete all keys matching a pattern using SCAN (non-blocking, production-safe).
+		 *
+		 * @param {string} pattern - e.g., "user:*"
+		 */
+		async invalidate(pattern) {
+			const matchPattern = `${prefix}${pattern}`;
+			let cursor = "0";
+			do {
+				const [nextCursor, keys] = await redisClient.scan(
+					cursor,
+					"MATCH",
+					matchPattern,
+					"COUNT",
+					100,
+				);
+				cursor = nextCursor;
+				if (keys.length > 0) {
+					await Promise.all(keys.map((k) => redisClient.del(k)));
+				}
+			} while (cursor !== "0");
+		},
+
+		/**
+		 * Get-or-set pattern: returns cached value if it exists,
+		 * otherwise calls factory, caches the result, and returns it.
+		 *
+		 * @param {string} key
+		 * @param {Function} factory - async function that produces the value
+		 * @param {number} [ttl] - TTL in seconds, defaults to defaultTTL
+		 * @returns {Promise<any>}
+		 */
+		async getOrSet(key, factory, ttl) {
+			const cached = await this.get(key);
+			if (cached !== null) return cached;
+
+			const value = await factory();
+			await this.set(key, value, ttl);
+			return value;
+		},
+
+		/**
+		 * Wrap a function with caching. Returns a new function that
+		 * caches results based on argument serialisation.
+		 *
+		 * @param {Function} fn - the function to wrap
+		 * @param {Object} [wrapOptions]
+		 * @param {string} [wrapOptions.keyPrefix] - prefix for generated cache keys
+		 * @param {number} [wrapOptions.ttl] - TTL in seconds
+		 * @param {Function} [wrapOptions.keyGenerator] - custom key generator `(...args) => string`
+		 * @returns {Function}
+		 */
+		wrap(fn, wrapOptions = {}) {
+			const {
+				keyPrefix = fn.name || "wrapped",
+				ttl,
+				keyGenerator,
+			} = wrapOptions;
+
+			return async (...args) => {
+				const cacheKey = keyGenerator
+					? `${keyPrefix}:${keyGenerator(...args)}`
+					: `${keyPrefix}:${JSON.stringify(args)}`;
+
+				return this.getOrSet(cacheKey, () => fn(...args), ttl);
+			};
+		},
+	};
+}

package/src/cache.test.js

@@ -0,0 +1,217 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+import { createCache } from "./cache.js";
+
+/**
+ * Creates a mock Redis client backed by a Map.
+ * Provides get, set, del, keys, and expire methods.
+ */
+function createMockRedis() {
+	const store = new Map();
+	const expires = new Map();
+
+	return {
+		store,
+		expires,
+
+		async get(key) {
+			return store.has(key) ? store.get(key) : null;
+		},
+
+		async set(key, value, ...args) {
+			store.set(key, value);
+			// Support atomic SET key value EX seconds
+			if (args[0] === "EX" && args[1] != null) {
+				expires.set(key, args[1]);
+			}
+		},
+
+		async del(key) {
+			store.delete(key);
+			expires.delete(key);
+		},
+
+		async scan(_cursor, ...args) {
+			// Simple mock: return all matching keys in one batch
+			const matchIdx = args.indexOf("MATCH");
+			const pattern = matchIdx !== -1 ? args[matchIdx + 1] : "*";
+			const regex = new RegExp(
+				`^${pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\*/g, ".*")}$`,
+			);
+			const keys = [...store.keys()].filter((k) => regex.test(k));
+			return ["0", keys];
+		},
+
+		async expire(key, seconds) {
+			expires.set(key, seconds);
+		},
+	};
+}
+
+describe("createCache", () => {
+	let redis;
+	let cache;
+
+	beforeEach(() => {
+		redis = createMockRedis();
+		cache = createCache(redis, { prefix: "test:", defaultTTL: 60 });
+	});
+
+	describe("get", () => {
+		it("returns null for a missing key", async () => {
+			const result = await cache.get("nonexistent");
+			assert.equal(result, null);
+		});
+
+		it("returns parsed JSON for an existing key", async () => {
+			redis.store.set("test:hello", JSON.stringify({ a: 1 }));
+			const result = await cache.get("hello");
+			assert.deepEqual(result, { a: 1 });
+		});
+
+		it("returns null for invalid JSON", async () => {
+			redis.store.set("test:bad", "not-json{");
+			const result = await cache.get("bad");
+			assert.equal(result, null);
+		});
+	});
+
+	describe("set", () => {
+		it("round-trips JSON values through set/get", async () => {
+			const data = { users: [1, 2, 3], active: true };
+			await cache.set("data", data);
+			const result = await cache.get("data");
+			assert.deepEqual(result, data);
+		});
+
+		it("passes TTL to Redis expire", async () => {
+			await cache.set("key", "value", 120);
+			assert.equal(redis.expires.get("test:key"), 120);
+		});
+
+		it("uses defaultTTL when no TTL is provided", async () => {
+			await cache.set("key", "value");
+			assert.equal(redis.expires.get("test:key"), 60);
+		});
+	});
+
+	describe("del", () => {
+		it("removes a key", async () => {
+			await cache.set("gone", "bye");
+			await cache.del("gone");
+			const result = await cache.get("gone");
+			assert.equal(result, null);
+		});
+	});
+
+	describe("invalidate", () => {
+		it("deletes all keys matching a pattern", async () => {
+			await cache.set("user:1", "alice");
+			await cache.set("user:2", "bob");
+			await cache.set("post:1", "hello");
+
+			await cache.invalidate("user:*");
+
+			assert.equal(await cache.get("user:1"), null);
+			assert.equal(await cache.get("user:2"), null);
+			assert.notEqual(await cache.get("post:1"), null);
+		});
+
+		it("does nothing when no keys match", async () => {
+			await cache.set("a", 1);
+			await cache.invalidate("zzz:*");
+			assert.deepEqual(await cache.get("a"), 1);
+		});
+	});
+
+	describe("getOrSet", () => {
+		it("calls factory on cache miss and caches the result", async () => {
+			let called = 0;
+			const factory = async () => {
+				called++;
+				return { fresh: true };
+			};
+
+			const result = await cache.getOrSet("miss", factory);
+			assert.deepEqual(result, { fresh: true });
+			assert.equal(called, 1);
+
+			// Value should now be cached
+			const cached = await cache.get("miss");
+			assert.deepEqual(cached, { fresh: true });
+		});
+
+		it("returns cached value without calling factory on hit", async () => {
+			await cache.set("hit", { cached: true });
+
+			let called = 0;
+			const factory = async () => {
+				called++;
+				return { fresh: true };
+			};
+
+			const result = await cache.getOrSet("hit", factory);
+			assert.deepEqual(result, { cached: true });
+			assert.equal(called, 0);
+		});
+	});
+
+	describe("wrap", () => {
+		it("creates a cached function", async () => {
+			let calls = 0;
+			const expensive = async (x) => {
+				calls++;
+				return x * 2;
+			};
+
+			const cachedFn = cache.wrap(expensive, { keyPrefix: "double" });
+
+			const first = await cachedFn(5);
+			assert.equal(first, 10);
+			assert.equal(calls, 1);
+
+			const second = await cachedFn(5);
+			assert.equal(second, 10);
+			assert.equal(calls, 1); // Cache hit - factory not called again
+		});
+
+		it("uses keyGenerator when provided", async () => {
+			let _calls = 0;
+			const fn = async (a, b) => {
+				_calls++;
+				return a + b;
+			};
+
+			const cachedFn = cache.wrap(fn, {
+				keyPrefix: "sum",
+				keyGenerator: (a, b) => `${a}+${b}`,
+			});
+
+			const result = await cachedFn(2, 3);
+			assert.equal(result, 5);
+
+			// Verify the custom key was used
+			const storedKey = "test:sum:2+3";
+			assert.ok(redis.store.has(storedKey));
+		});
+
+		it("caches different args separately", async () => {
+			let calls = 0;
+			const fn = async (x) => {
+				calls++;
+				return x * 3;
+			};
+
+			const cachedFn = cache.wrap(fn, { keyPrefix: "triple" });
+
+			assert.equal(await cachedFn(1), 3);
+			assert.equal(await cachedFn(2), 6);
+			assert.equal(calls, 2);
+
+			// Both should now be cached
+			assert.equal(await cachedFn(1), 3);
+			assert.equal(await cachedFn(2), 6);
+			assert.equal(calls, 2);
+		});
+	});
+});

package/src/core.js

@@ -0,0 +1,32 @@
+/**
+ * @techstream/quark-core - Core Barrel (Lightweight Utilities)
+ *
+ * A smaller entry-point that exposes only the modules with zero or
+ * minimal transitive dependencies: errors, logger, validation, utils,
+ * pagination, csrf, rate-limiter, file-validation, and db.
+ *
+ * Downstream projects that only need these utilities can import from
+ * "@techstream/quark-core/core" to avoid pulling in heavier modules
+ * like email, storage, queue, or metrics.
+ */
+
+// CSRF — depends on node:crypto + errors
+export * from "./csrf.js";
+// Database utilities — depends on the optional `pg` peer (loaded lazily by
+// pingDatabase); createPrismaClient takes the app's Prisma client class.
+export * from "./db.js";
+// Errors — zero external deps
+export * from "./errors.js";
+// File validation — zero external deps
+export * from "./file-validation.js";
+// Logger — zero external deps
+export * from "./logger.js";
+// Pagination — depends on zod + errors
+export * from "./pagination.js";
+
+// Rate limiter — zero external deps (Redis optional at runtime)
+export * from "./rate-limiter.js";
+// Utilities — zero external deps
+export * from "./utils.js";
+// Validation — depends on zod
+export * from "./validation.js";