@classytic/arc 2.3.0 → 2.4.2

package/dist/permissions-CA5zg0yK.mjs

@@ -0,0 +1,751 @@
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+import { a as getTeamId, d as isMember, n as PUBLIC_SCOPE, o as getUserId, u as isElevated } from "./types-C6TQjtdi.mjs";
+import { t as getUserRoles } from "./types-ZUu_h0jp.mjs";
+import { t as MemoryCacheStore } from "./memory-Cb_7iy9e.mjs";
+import { randomUUID } from "node:crypto";
+//#region src/permissions/roleHierarchy.ts
+/**
+* Create a role hierarchy from a parent → children map.
+*
+* Each key is a parent role, each value is the array of roles it inherits.
+* Inheritance is transitive: if A → B and B → C, then A expands to [A, B, C].
+* Circular references are handled safely (visited set).
+*/
+function createRoleHierarchy(map) {
+	const cache = /* @__PURE__ */ new Map();
+	function resolveRole(role, visited) {
+		if (visited.has(role)) return [];
+		visited.add(role);
+		const cached = cache.get(role);
+		if (cached) return cached;
+		const children = map[role];
+		if (!children || children.length === 0) {
+			cache.set(role, [role]);
+			return [role];
+		}
+		const result = [role];
+		for (const child of children) result.push(...resolveRole(child, visited));
+		const deduped = [...new Set(result)];
+		cache.set(role, deduped);
+		return deduped;
+	}
+	return {
+		expand(roles) {
+			if (roles.length === 0) return [];
+			const all = /* @__PURE__ */ new Set();
+			for (const role of roles) for (const expanded of resolveRole(role, /* @__PURE__ */ new Set())) all.add(expanded);
+			return [...all];
+		},
+		includes(userRoles, requiredRole) {
+			if (userRoles.length === 0) return false;
+			return this.expand(userRoles).includes(requiredRole);
+		}
+	};
+}
+//#endregion
+//#region src/permissions/presets.ts
+/**
+* Permission Presets — Common permission patterns in one call.
+*
+* Reduces 5 lines of permission declarations to 1.
+* Each preset returns a ResourcePermissions object that can be
+* spread or overridden per-operation.
+*
+* @example
+* ```typescript
+* import { permissions } from '@classytic/arc';
+*
+* // Public read, authenticated write
+* defineResource({ name: 'product', permissions: permissions.publicRead() });
+*
+* // Override specific operations
+* defineResource({
+*   name: 'product',
+*   permissions: permissions.publicRead({ delete: requireRoles(['superadmin']) }),
+* });
+* ```
+*/
+var presets_exports = /* @__PURE__ */ __exportAll({
+	adminOnly: () => adminOnly,
+	authenticated: () => authenticated,
+	fullPublic: () => fullPublic,
+	ownerWithAdminBypass: () => ownerWithAdminBypass,
+	publicRead: () => publicRead,
+	publicReadAdminWrite: () => publicReadAdminWrite,
+	readOnly: () => readOnly
+});
+/**
+* Merge a base preset with user overrides.
+* Overrides replace individual operations — undefined values don't clear them.
+*/
+function withOverrides(base, overrides) {
+	if (!overrides) return base;
+	const filtered = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== void 0));
+	return {
+		...base,
+		...filtered
+	};
+}
+/**
+* Public read, authenticated write.
+* list + get = allowPublic(), create + update + delete = requireAuth()
+*/
+function publicRead(overrides) {
+	return withOverrides({
+		list: allowPublic(),
+		get: allowPublic(),
+		create: requireAuth(),
+		update: requireAuth(),
+		delete: requireAuth()
+	}, overrides);
+}
+/**
+* Public read, admin write.
+* list + get = allowPublic(), create + update + delete = requireRoles(['admin'])
+*/
+function publicReadAdminWrite(roles = ["admin"], overrides) {
+	return withOverrides({
+		list: allowPublic(),
+		get: allowPublic(),
+		create: requireRoles(roles),
+		update: requireRoles(roles),
+		delete: requireRoles(roles)
+	}, overrides);
+}
+/**
+* All operations require authentication.
+*/
+function authenticated(overrides) {
+	return withOverrides({
+		list: requireAuth(),
+		get: requireAuth(),
+		create: requireAuth(),
+		update: requireAuth(),
+		delete: requireAuth()
+	}, overrides);
+}
+/**
+* All operations require specific roles.
+* @param roles - Required roles (user needs at least one). Default: ['admin']
+*/
+function adminOnly(roles = ["admin"], overrides) {
+	return withOverrides({
+		list: requireRoles(roles),
+		get: requireRoles(roles),
+		create: requireRoles(roles),
+		update: requireRoles(roles),
+		delete: requireRoles(roles)
+	}, overrides);
+}
+/**
+* Owner-scoped with admin bypass.
+* list = auth (scoped to owner), get = auth, create = auth,
+* update + delete = ownership check with admin bypass.
+*
+* @param ownerField - Field containing owner ID (default: 'userId')
+* @param bypassRoles - Roles that bypass ownership check (default: ['admin'])
+*/
+function ownerWithAdminBypass(ownerField = "userId", bypassRoles = ["admin"], overrides) {
+	return withOverrides({
+		list: requireAuth(),
+		get: requireAuth(),
+		create: requireAuth(),
+		update: anyOf(requireRoles(bypassRoles), requireOwnership(ownerField)),
+		delete: anyOf(requireRoles(bypassRoles), requireOwnership(ownerField))
+	}, overrides);
+}
+/**
+* Full public access — no auth required for any operation.
+* Use sparingly (dev/testing, truly public APIs).
+*/
+function fullPublic(overrides) {
+	return withOverrides({
+		list: allowPublic(),
+		get: allowPublic(),
+		create: allowPublic(),
+		update: allowPublic(),
+		delete: allowPublic()
+	}, overrides);
+}
+/**
+* Read-only: list + get authenticated, write operations denied.
+* Useful for computed/derived resources.
+*/
+function readOnly(overrides) {
+	return withOverrides({
+		list: requireAuth(),
+		get: requireAuth()
+	}, overrides);
+}
+//#endregion
+//#region src/permissions/index.ts
+/**
+* Allow public access (no authentication required)
+*
+* @example
+* ```typescript
+* permissions: {
+*   list: allowPublic(),
+*   get: allowPublic(),
+* }
+* ```
+*/
+function allowPublic() {
+	const check = () => true;
+	check._isPublic = true;
+	return check;
+}
+/**
+* Require authentication (any authenticated user)
+*
+* @example
+* ```typescript
+* permissions: {
+*   create: requireAuth(),
+*   update: requireAuth(),
+* }
+* ```
+*/
+function requireAuth() {
+	const check = (ctx) => {
+		if (!ctx.user) return {
+			granted: false,
+			reason: "Authentication required"
+		};
+		return true;
+	};
+	return check;
+}
+/**
+* Require specific roles
+*
+* @param roles - Required roles (user needs at least one)
+* @param options - Optional bypass roles
+*
+* @example
+* ```typescript
+* permissions: {
+*   create: requireRoles(['admin', 'editor']),
+*   delete: requireRoles(['admin']),
+* }
+*
+* // With bypass roles
+* permissions: {
+*   update: requireRoles(['owner'], { bypassRoles: ['admin', 'superadmin'] }),
+* }
+* ```
+*/
+function requireRoles(roles, options) {
+	const check = (ctx) => {
+		if (!ctx.user) return {
+			granted: false,
+			reason: "Authentication required"
+		};
+		const userRoles = getUserRoles(ctx.user);
+		if (options?.bypassRoles?.some((r) => userRoles.includes(r))) return true;
+		if (roles.some((r) => userRoles.includes(r))) return true;
+		return {
+			granted: false,
+			reason: `Required roles: ${roles.join(", ")}`
+		};
+	};
+	check._roles = roles;
+	return check;
+}
+/**
+* Require resource ownership
+*
+* Returns filters to scope queries to user's owned resources.
+*
+* @param ownerField - Field containing owner ID (default: 'userId')
+* @param options - Optional bypass roles
+*
+* @example
+* ```typescript
+* permissions: {
+*   update: requireOwnership('userId'),
+*   delete: requireOwnership('createdBy', { bypassRoles: ['admin'] }),
+* }
+* ```
+*/
+function requireOwnership(ownerField = "userId", options) {
+	return (ctx) => {
+		if (!ctx.user) return {
+			granted: false,
+			reason: "Authentication required"
+		};
+		const userRoles = getUserRoles(ctx.user);
+		if (options?.bypassRoles?.some((r) => userRoles.includes(r))) return true;
+		const userId = getUserId(getScope(ctx.request)) ?? ctx.user.id ?? ctx.user._id;
+		if (!userId) return {
+			granted: false,
+			reason: "User identity missing (no id or _id)"
+		};
+		return {
+			granted: true,
+			filters: { [ownerField]: userId }
+		};
+	};
+}
+/**
+* Combine multiple checks - ALL must pass (AND logic)
+*
+* @example
+* ```typescript
+* permissions: {
+*   update: allOf(
+*     requireAuth(),
+*     requireRoles(['editor']),
+*     requireOwnership('createdBy')
+*   ),
+* }
+* ```
+*/
+function allOf(...checks) {
+	return async (ctx) => {
+		let mergedFilters = {};
+		for (const check of checks) {
+			const result = await check(ctx);
+			const normalized = typeof result === "boolean" ? { granted: result } : result;
+			if (!normalized.granted) return normalized;
+			if (normalized.filters) mergedFilters = {
+				...mergedFilters,
+				...normalized.filters
+			};
+		}
+		return {
+			granted: true,
+			filters: Object.keys(mergedFilters).length > 0 ? mergedFilters : void 0
+		};
+	};
+}
+/**
+* Combine multiple checks - ANY must pass (OR logic)
+*
+* @example
+* ```typescript
+* permissions: {
+*   update: anyOf(
+*     requireRoles(['admin']),
+*     requireOwnership('createdBy')
+*   ),
+* }
+* ```
+*/
+function anyOf(...checks) {
+	return async (ctx) => {
+		const reasons = [];
+		for (const check of checks) {
+			const result = await check(ctx);
+			const normalized = typeof result === "boolean" ? { granted: result } : result;
+			if (normalized.granted) return normalized;
+			if (normalized.reason) reasons.push(normalized.reason);
+		}
+		return {
+			granted: false,
+			reason: reasons.join("; ")
+		};
+	};
+}
+/**
+* Deny all access
+*
+* @example
+* ```typescript
+* permissions: {
+*   delete: denyAll('Deletion not allowed'),
+* }
+* ```
+*/
+function denyAll(reason = "Access denied") {
+	return () => ({
+		granted: false,
+		reason
+	});
+}
+/**
+* Dynamic permission based on context
+*
+* @example
+* ```typescript
+* permissions: {
+*   update: when((ctx) => ctx.data?.status === 'draft'),
+* }
+* ```
+*/
+function when(condition) {
+	return async (ctx) => {
+		const result = await condition(ctx);
+		return {
+			granted: result,
+			reason: result ? void 0 : "Condition not met"
+		};
+	};
+}
+/** Read request.scope safely */
+function getScope(request) {
+	return request.scope ?? PUBLIC_SCOPE;
+}
+/**
+* Require membership in the active organization.
+* User must be authenticated AND have an active org (member or elevated scope).
+*
+* Reads `request.scope` set by auth adapters.
+*
+* @example
+* ```typescript
+* permissions: {
+*   list: requireOrgMembership(),
+*   get: requireOrgMembership(),
+* }
+* ```
+*/
+function requireOrgMembership() {
+	const check = (ctx) => {
+		if (!ctx.user) return {
+			granted: false,
+			reason: "Authentication required"
+		};
+		const scope = getScope(ctx.request);
+		if (isElevated(scope)) return true;
+		if (isMember(scope)) return true;
+		return {
+			granted: false,
+			reason: "Organization membership required"
+		};
+	};
+	check._orgPermission = "membership";
+	return check;
+}
+/**
+* Require specific org-level roles.
+* Reads `request.scope.orgRoles` (set by auth adapters).
+* Elevated scope always passes (platform admin bypass).
+*
+* @param roles - Required org roles (user needs at least one)
+*
+* @example
+* ```typescript
+* permissions: {
+*   create: requireOrgRole('admin', 'owner'),
+*   delete: requireOrgRole('owner'),
+* }
+* ```
+*/
+function requireOrgRole(...args) {
+	const roles = Array.isArray(args[0]) ? args[0] : args;
+	const check = (ctx) => {
+		if (!ctx.user) return {
+			granted: false,
+			reason: "Authentication required"
+		};
+		const scope = getScope(ctx.request);
+		if (isElevated(scope)) return true;
+		if (!isMember(scope)) return {
+			granted: false,
+			reason: "Organization membership required"
+		};
+		if (roles.some((r) => scope.orgRoles.includes(r))) return true;
+		return {
+			granted: false,
+			reason: `Required org roles: ${roles.join(", ")}`
+		};
+	};
+	check._orgRoles = roles;
+	return check;
+}
+/**
+* Create a scoped permission system for resource-action patterns.
+* Maps org roles to fine-grained permissions without external API calls.
+*
+* @example
+* ```typescript
+* const perms = createOrgPermissions({
+*   statements: {
+*     product: ['create', 'update', 'delete'],
+*     order: ['create', 'approve'],
+*   },
+*   roles: {
+*     owner: { product: ['create', 'update', 'delete'], order: ['create', 'approve'] },
+*     admin: { product: ['create', 'update'], order: ['create'] },
+*     member: { product: [], order: [] },
+*   },
+* });
+*
+* defineResource({
+*   permissions: {
+*     create: perms.can({ product: ['create'] }),
+*     delete: perms.can({ product: ['delete'] }),
+*   }
+* });
+* ```
+*/
+function createOrgPermissions(config) {
+	const { roles: roleMap } = config;
+	function hasPermissions(orgRoles, required) {
+		for (const [resource, actions] of Object.entries(required)) for (const action of actions) if (!orgRoles.some((role) => {
+			return (roleMap[role]?.[resource])?.includes(action);
+		})) return false;
+		return true;
+	}
+	return {
+		can(permissions) {
+			return (ctx) => {
+				if (!ctx.user) return {
+					granted: false,
+					reason: "Authentication required"
+				};
+				const scope = getScope(ctx.request);
+				if (isElevated(scope)) return true;
+				if (!isMember(scope)) return {
+					granted: false,
+					reason: "Organization membership required"
+				};
+				if (hasPermissions(scope.orgRoles, permissions)) return true;
+				return {
+					granted: false,
+					reason: `Missing permissions: ${Object.entries(permissions).map(([r, a]) => `${r}:[${a.join(",")}]`).join(", ")}`
+				};
+			};
+		},
+		requireRole(...roles) {
+			return requireOrgRole(roles);
+		},
+		requireMembership() {
+			return requireOrgMembership();
+		},
+		requireTeamMembership() {
+			return requireTeamMembership();
+		}
+	};
+}
+/**
+* Create a dynamic role-based permission matrix.
+*
+* Use this when role/action mappings are managed outside code
+* (e.g., admin UI matrix, DB-stored ACLs, remote policy service).
+*
+* Supports:
+* - org role union (any assigned org role can grant)
+* - global bypass roles
+* - wildcard resource/action (`*`)
+* - optional in-memory cache
+*/
+function createDynamicPermissionMatrix(config) {
+	const logger = config.logger ?? console;
+	const legacyTtlMs = config.cache?.ttlMs ?? 0;
+	const hasExternalStore = !!config.cacheStore;
+	const cacheTtlMs = legacyTtlMs > 0 ? legacyTtlMs : hasExternalStore ? 3e5 : 0;
+	const internalStore = !config.cacheStore && cacheTtlMs > 0 ? new MemoryCacheStore({
+		defaultTtlMs: cacheTtlMs,
+		maxEntries: config.cache?.maxEntries ?? 1e3
+	}) : void 0;
+	const cacheStore = config.cacheStore ?? internalStore;
+	const trackedKeys = /* @__PURE__ */ new Set();
+	const nodeId = randomUUID().slice(0, 8);
+	const DEFAULT_EVENT_TYPE = "arc.permissions.invalidated";
+	let eventBridge = null;
+	/** Clear local cache for an org without publishing events (avoids infinite loops). */
+	async function localInvalidateByOrg(orgId) {
+		if (!cacheStore) return;
+		const prefix = `${orgId}::`;
+		const toDelete = [];
+		for (const key of trackedKeys) if (key.startsWith(prefix)) toDelete.push(key);
+		for (const key of toDelete) try {
+			await cacheStore.delete(key);
+			trackedKeys.delete(key);
+		} catch (error) {
+			logger.warn(`[DynamicPermissionMatrix] invalidateByOrg delete failed for '${key}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	function isActionAllowed(actions, action) {
+		if (!actions || actions.length === 0) return false;
+		return actions.includes("*") || actions.includes(action);
+	}
+	function roleAllows(matrix, role, resource, action) {
+		const rolePermissions = matrix[role];
+		if (!rolePermissions) return false;
+		const resourceActions = rolePermissions[resource];
+		const wildcardResourceActions = rolePermissions["*"];
+		return isActionAllowed(resourceActions, action) || isActionAllowed(wildcardResourceActions, action);
+	}
+	function buildDefaultCacheKey(ctx, orgId, orgRoles) {
+		const userId = String(ctx.user?.id ?? ctx.user?._id ?? "anon");
+		const roles = (orgRoles ?? []).slice().sort().join(",");
+		return `${orgId ?? "no-org"}::${roles}::${userId}`;
+	}
+	async function resolveMatrix(ctx, orgId, orgRoles) {
+		if (!cacheStore) return config.resolveRolePermissions(ctx);
+		const cacheKey = config.cache?.key?.(ctx) ?? buildDefaultCacheKey(ctx, orgId, orgRoles);
+		if (!cacheKey) return config.resolveRolePermissions(ctx);
+		try {
+			const hit = await cacheStore.get(cacheKey);
+			if (hit) return hit;
+		} catch (error) {
+			logger.warn(`[DynamicPermissionMatrix] Cache get failed for '${cacheKey}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const value = await config.resolveRolePermissions(ctx);
+		try {
+			await cacheStore.set(cacheKey, value, { ttlMs: cacheTtlMs });
+			trackedKeys.add(cacheKey);
+			const maxTracked = config.cache?.maxEntries ?? 1e4;
+			if (trackedKeys.size > maxTracked) {
+				const overflow = trackedKeys.size - maxTracked;
+				const iter = trackedKeys.values();
+				for (let i = 0; i < overflow; i++) {
+					const oldest = iter.next().value;
+					if (oldest) trackedKeys.delete(oldest);
+				}
+			}
+		} catch (error) {
+			logger.warn(`[DynamicPermissionMatrix] Cache set failed for '${cacheKey}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+		return value;
+	}
+	function can(required) {
+		return async (ctx) => {
+			if (!ctx.user) return {
+				granted: false,
+				reason: "Authentication required"
+			};
+			const scope = getScope(ctx.request);
+			if (isElevated(scope)) return true;
+			if (!isMember(scope)) return {
+				granted: false,
+				reason: "Organization membership required"
+			};
+			const orgRoles = scope.orgRoles;
+			if (orgRoles.length === 0) return {
+				granted: false,
+				reason: "Not a member of this organization"
+			};
+			let matrix;
+			try {
+				matrix = await resolveMatrix(ctx, scope.organizationId, orgRoles);
+			} catch (error) {
+				return {
+					granted: false,
+					reason: `Permission matrix resolution failed: ${error instanceof Error ? error.message : String(error)}`
+				};
+			}
+			for (const [resource, actions] of Object.entries(required)) for (const action of actions) if (!orgRoles.some((role) => roleAllows(matrix, role, resource, action))) return {
+				granted: false,
+				reason: `Missing permission: ${resource}:${action}`
+			};
+			return true;
+		};
+	}
+	return {
+		can,
+		canAction(resource, action) {
+			return can({ [resource]: [action] });
+		},
+		requireRole(...roles) {
+			return requireOrgRole(roles);
+		},
+		requireMembership() {
+			return requireOrgMembership();
+		},
+		requireTeamMembership() {
+			return requireTeamMembership();
+		},
+		async invalidateByOrg(orgId) {
+			await localInvalidateByOrg(orgId);
+			if (eventBridge) try {
+				await eventBridge.publish(eventBridge.eventType, {
+					orgId,
+					nodeId
+				});
+			} catch (error) {
+				logger.warn(`[DynamicPermissionMatrix] Failed to publish invalidation event for org '${orgId}': ${error instanceof Error ? error.message : String(error)}`);
+			}
+		},
+		async clearCache() {
+			if (!cacheStore) return;
+			if (cacheStore.clear) try {
+				await cacheStore.clear();
+				trackedKeys.clear();
+				return;
+			} catch (error) {
+				logger.warn(`[DynamicPermissionMatrix] cacheStore.clear failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			for (const key of trackedKeys) try {
+				await cacheStore.delete(key);
+			} catch (error) {
+				logger.warn(`[DynamicPermissionMatrix] Cache delete failed for '${key}': ${error instanceof Error ? error.message : String(error)}`);
+			}
+			trackedKeys.clear();
+		},
+		async connectEvents(events, options) {
+			if (eventBridge) await this.disconnectEvents();
+			const eventType = options?.eventType ?? DEFAULT_EVENT_TYPE;
+			const unsubscribeFn = await events.subscribe(eventType, async (event) => {
+				const payload = event.payload;
+				if (!payload?.orgId) return;
+				if (payload.nodeId === nodeId) return;
+				await localInvalidateByOrg(payload.orgId);
+				if (options?.onRemoteInvalidation) try {
+					await options.onRemoteInvalidation(payload.orgId);
+				} catch (error) {
+					logger.warn(`[DynamicPermissionMatrix] onRemoteInvalidation callback failed for org '${payload.orgId}': ${error instanceof Error ? error.message : String(error)}`);
+				}
+			});
+			eventBridge = {
+				publish: events.publish,
+				unsubscribe: typeof unsubscribeFn === "function" ? unsubscribeFn : null,
+				eventType,
+				onRemoteInvalidation: options?.onRemoteInvalidation
+			};
+		},
+		async disconnectEvents() {
+			if (!eventBridge) return;
+			try {
+				eventBridge.unsubscribe?.();
+			} catch (error) {
+				logger.warn(`[DynamicPermissionMatrix] disconnectEvents unsubscribe failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			eventBridge = null;
+		},
+		get eventsConnected() {
+			return eventBridge !== null;
+		}
+	};
+}
+/**
+* Require membership in the active team.
+* User must be authenticated, a member of the active org, AND have an active team.
+*
+* Better Auth teams are flat member groups (no team-level roles).
+* Reads `request.scope.teamId` set by the Better Auth adapter.
+*
+* @example
+* ```typescript
+* permissions: {
+*   list: requireTeamMembership(),
+*   create: requireTeamMembership(),
+* }
+* ```
+*/
+function requireTeamMembership() {
+	const check = (ctx) => {
+		if (!ctx.user) return {
+			granted: false,
+			reason: "Authentication required"
+		};
+		const scope = getScope(ctx.request);
+		if (isElevated(scope)) return true;
+		if (!isMember(scope)) return {
+			granted: false,
+			reason: "Organization membership required"
+		};
+		if (!getTeamId(scope)) return {
+			granted: false,
+			reason: "No active team"
+		};
+		return true;
+	};
+	check._teamPermission = "membership";
+	return check;
+}
+//#endregion
+export { createRoleHierarchy as S, ownerWithAdminBypass as _, createOrgPermissions as a, publicReadAdminWrite as b, requireOrgMembership as c, requireRoles as d, requireTeamMembership as f, fullPublic as g, authenticated as h, createDynamicPermissionMatrix as i, requireOrgRole as l, adminOnly as m, allowPublic as n, denyAll as o, when as p, anyOf as r, requireAuth as s, allOf as t, requireOwnership as u, presets_exports as v, readOnly as x, publicRead as y };