@techstream/quark-core 1.1.0

package/src/authorization.js

@@ -0,0 +1,235 @@
+/**
+ * @techstream/quark-core - Authorization Module
+ * Policy-based, schema-agnostic RBAC engine
+ */
+
+import { ForbiddenError } from "./errors.js";
+
+/**
+ * @typedef {{ resource: string, action: string }} Permission
+ * @typedef {{ permissions: Permission[] }} RoleDefinition
+ * @typedef {{
+ *   roles: Record<string, RoleDefinition>,
+ *   defaultRole: string,
+ *   ownershipField: string,
+ *   ownerActions: string[]
+ * }} Policy
+ * @typedef {{ id: string, role?: string }} AuthUser
+ */
+
+/**
+ * Default policy shipped with Quark — easily overridable by downstream projects.
+ * @type {Policy}
+ */
+export const defaultPolicy = {
+	roles: {
+		admin: {
+			permissions: [{ resource: "*", action: "*" }],
+		},
+		editor: {
+			permissions: [
+				{ resource: "post", action: "*" },
+				{ resource: "user", action: "read" },
+			],
+		},
+		viewer: {
+			permissions: [
+				{ resource: "post", action: "read" },
+				{ resource: "user", action: "read" },
+			],
+		},
+	},
+	defaultRole: "viewer",
+	ownershipField: "ownerId",
+	ownerActions: ["update", "delete"],
+};
+
+/**
+ * Creates an authorization instance from a policy configuration.
+ * @param {Policy} [policy] - The policy to use (defaults to `defaultPolicy`)
+ * @returns {{
+ *   can: (user: AuthUser, action: string, resource: string, context?: Record<string, unknown>) => boolean,
+ *   authorize: (user: AuthUser, action: string, resource: string, context?: Record<string, unknown>) => void,
+ *   hasPermission: (role: string, action: string, resource: string) => boolean,
+ *   getRolePermissions: (role: string) => Permission[],
+ *   addRole: (name: string, permissions: Permission[]) => void,
+ *   removeRole: (name: string) => void,
+ *   extendPolicy: (policyExtension: Partial<Policy>) => void
+ * }}
+ */
+export const createAuthorization = (policy = defaultPolicy) => {
+	const _policy = structuredClone(policy);
+
+	/**
+	 * Checks whether a role has a specific permission, respecting wildcards.
+	 * @param {string} role - Role name
+	 * @param {string} action - Action to check (e.g. "read", "update")
+	 * @param {string} resource - Resource to check (e.g. "post", "user")
+	 * @returns {boolean}
+	 */
+	const hasPermission = (role, action, resource) => {
+		const roleDef = _policy.roles[role];
+		if (!roleDef) return false;
+
+		return roleDef.permissions.some((perm) => {
+			const resourceMatch = perm.resource === "*" || perm.resource === resource;
+			const actionMatch = perm.action === "*" || perm.action === action;
+			return resourceMatch && actionMatch;
+		});
+	};
+
+	/**
+	 * Returns the permissions array for a given role.
+	 * @param {string} role - Role name
+	 * @returns {Permission[]} Array of permissions, or empty array if role not found
+	 */
+	const getRolePermissions = (role) => {
+		const roleDef = _policy.roles[role];
+		return roleDef ? [...roleDef.permissions] : [];
+	};
+
+	/**
+	 * Checks whether a user is allowed to perform an action on a resource.
+	 * Supports role-based permissions and ownership checks.
+	 * @param {AuthUser} user - User object with `id` and optional `role`
+	 * @param {string} action - Action to perform
+	 * @param {string} resource - Target resource
+	 * @param {Record<string, unknown>} [context] - Optional context for ownership checks
+	 * @returns {boolean}
+	 */
+	const can = (user, action, resource, context) => {
+		const role = user.role || _policy.defaultRole;
+
+		if (hasPermission(role, action, resource)) {
+			return true;
+		}
+
+		// Ownership check
+		if (
+			context &&
+			_policy.ownerActions.includes(action) &&
+			context[_policy.ownershipField] != null &&
+			context[_policy.ownershipField] === user.id
+		) {
+			return true;
+		}
+
+		return false;
+	};
+
+	/**
+	 * Same as `can()` but throws `ForbiddenError` when access is denied.
+	 * @param {AuthUser} user - User object with `id` and optional `role`
+	 * @param {string} action - Action to perform
+	 * @param {string} resource - Target resource
+	 * @param {Record<string, unknown>} [context] - Optional context for ownership checks
+	 * @throws {ForbiddenError}
+	 */
+	const authorize = (user, action, resource, context) => {
+		if (!can(user, action, resource, context)) {
+			throw new ForbiddenError(
+				`User ${user.id} is not allowed to ${action} ${resource}`,
+			);
+		}
+	};
+
+	/**
+	 * Dynamically adds a role to the current policy.
+	 * @param {string} name - Role name
+	 * @param {Permission[]} permissions - Permissions for the role
+	 */
+	const addRole = (name, permissions) => {
+		_policy.roles[name] = { permissions: [...permissions] };
+	};
+
+	/**
+	 * Removes a role from the current policy.
+	 * @param {string} name - Role name to remove
+	 */
+	const removeRole = (name) => {
+		delete _policy.roles[name];
+	};
+
+	/**
+	 * Merges additional roles and settings into the current policy.
+	 * @param {Partial<Policy>} policyExtension - Partial policy to merge
+	 */
+	const extendPolicy = (policyExtension) => {
+		if (policyExtension.roles) {
+			for (const [name, roleDef] of Object.entries(policyExtension.roles)) {
+				_policy.roles[name] = structuredClone(roleDef);
+			}
+		}
+		if (policyExtension.defaultRole !== undefined) {
+			_policy.defaultRole = policyExtension.defaultRole;
+		}
+		if (policyExtension.ownershipField !== undefined) {
+			_policy.ownershipField = policyExtension.ownershipField;
+		}
+		if (policyExtension.ownerActions !== undefined) {
+			_policy.ownerActions = [...policyExtension.ownerActions];
+		}
+	};
+
+	return {
+		can,
+		authorize,
+		hasPermission,
+		getRolePermissions,
+		addRole,
+		removeRole,
+		extendPolicy,
+	};
+};
+
+/** Default authorization instance using the default policy. */
+export const authorization = createAuthorization();
+
+/**
+ * Higher-order function that returns a guard checking if the session user
+ * has one of the specified roles. Throws `ForbiddenError` if not.
+ * @param {...string} roles - Allowed role names
+ * @returns {(session: { user: AuthUser }) => void}
+ */
+export const requireRole = (...roles) => {
+	/**
+	 * @param {{ user: AuthUser }} session
+	 * @throws {ForbiddenError}
+	 */
+	return (session) => {
+		const userRole = session?.user?.role;
+		if (!userRole || !roles.includes(userRole)) {
+			throw new ForbiddenError(
+				`Role ${userRole || "none"} is not allowed. Required: ${roles.join(", ")}`,
+			);
+		}
+	};
+};
+
+/**
+ * Higher-order wrapper for API route handlers that enforces authorization
+ * before invoking the handler.
+ * @param {Function} handler - The route handler to wrap
+ * @param {{
+ *   action: string,
+ *   resource: string,
+ *   getContext?: (req: unknown, session: { user: AuthUser }) => Record<string, unknown> | Promise<Record<string, unknown>>
+ * }} options - Authorization options
+ * @returns {Function} Wrapped handler
+ */
+export const withAuthorization = (
+	handler,
+	{ action, resource, getContext },
+) => {
+	return async (req, session) => {
+		const user = session?.user;
+		if (!user) {
+			throw new ForbiddenError("No user in session");
+		}
+
+		const context = getContext ? await getContext(req, session) : undefined;
+		authorization.authorize(user, action, resource, context);
+
+		return handler(req, session);
+	};
+};

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);
+			};
+		},
+	};
+}