@classytic/arc 1.1.0 → 2.1.3

package/dist/policies/index.mjs

@@ -0,0 +1,321 @@
+//#region src/policies/PolicyInterface.ts
+/**
+* Create a PermissionCheck from access control statements.
+*
+* Maps Better Auth's statement-based access control model to Arc's
+* PermissionCheck function, which can be used directly in resource permissions.
+*
+* The returned PermissionCheck:
+* 1. Looks up the resource + action in the statements list
+* 2. If no matching statement exists, denies access
+* 3. If a matching statement exists and `checkPermission` is provided,
+*    calls it for dynamic verification (e.g., check org role)
+* 4. If `checkPermission` is not provided, allows access based on static statements
+*
+* @example Static statements only
+* ```typescript
+* import { createAccessControlPolicy } from '@classytic/arc/policies';
+*
+* const editorPermissions = createAccessControlPolicy({
+*   statements: [
+*     { resource: 'product', action: ['create', 'update'] },
+*     { resource: 'order', action: ['read'] },
+*   ],
+* });
+*
+* // Use in resource config
+* defineResource({
+*   name: 'product',
+*   permissions: {
+*     create: editorPermissions,
+*     update: editorPermissions,
+*   },
+* });
+* ```
+*
+* @example With dynamic permission check (Better Auth org roles)
+* ```typescript
+* const policy = createAccessControlPolicy({
+*   statements: [
+*     { resource: 'product', action: ['create', 'update'] },
+*     { resource: 'order', action: ['read'] },
+*   ],
+*   checkPermission: async (userId, resource, action) => {
+*     return hasOrgPermission(userId, resource, action);
+*   },
+* });
+* ```
+*/
+function createAccessControlPolicy(options) {
+	const statementMap = /* @__PURE__ */ new Map();
+	for (const statement of options.statements) {
+		const existing = statementMap.get(statement.resource);
+		if (existing) for (const action of statement.action) existing.add(action);
+		else statementMap.set(statement.resource, new Set(statement.action));
+	}
+	const permissionCheck = async (context) => {
+		const { user, resource, action } = context;
+		const allowedActions = statementMap.get(resource);
+		if (!allowedActions || !allowedActions.has(action)) return {
+			granted: false,
+			reason: `Action '${action}' is not permitted on resource '${resource}'`
+		};
+		if (options.checkPermission) {
+			const userId = user?.id ?? user?._id;
+			if (!userId) return {
+				granted: false,
+				reason: "Authentication required"
+			};
+			if (!await options.checkPermission(String(userId), resource, action)) return {
+				granted: false,
+				reason: `User does not have '${action}' permission on '${resource}'`
+			};
+		}
+		return { granted: true };
+	};
+	return permissionCheck;
+}
+
+//#endregion
+//#region src/policies/helpers.ts
+/**
+* Helper to create Fastify middleware from any PolicyEngine implementation
+*
+* This is a convenience function that provides a standard middleware pattern.
+* Most policies can use this instead of implementing toMiddleware() manually.
+*
+* @param policy - Policy engine instance
+* @param operation - Operation name (list, get, create, update, delete)
+* @returns Fastify preHandler middleware
+*
+* @example
+* ```typescript
+* class SimplePolicy implements PolicyEngine {
+*   can(user, operation) {
+*     return { allowed: user.isActive };
+*   }
+*
+*   toMiddleware(operation) {
+*     return createPolicyMiddleware(this, operation);
+*   }
+* }
+* ```
+*/
+function createPolicyMiddleware(policy, operation) {
+	return async function policyMiddleware(request, reply) {
+		const context = {
+			document: request.document,
+			body: request.body,
+			params: request.params,
+			query: request.query
+		};
+		const result = await policy.can(request.user, operation, context);
+		if (!result.allowed) return reply.code(403).send({
+			success: false,
+			error: "Access denied",
+			message: result.reason || "You do not have permission to perform this action"
+		});
+		request.policyResult = result;
+		if (result.filters && Object.keys(result.filters).length > 0) request._policyFilters = result.filters;
+		if (result.fieldMask) request.fieldMask = result.fieldMask;
+		if (result.metadata) request.policyMetadata = result.metadata;
+	};
+}
+/**
+* Combine multiple policies with AND logic
+*
+* All policies must allow the operation for it to succeed.
+* First denial stops evaluation and returns the denial reason.
+*
+* @param policies - Array of policy engines to combine
+* @returns Combined policy engine
+*
+* @example
+* ```typescript
+* const combinedPolicy = combinePolicies(
+*   rbacPolicy,        // Must have correct role
+*   ownershipPolicy,   // Must own the resource
+*   auditPolicy,       // Logs access for compliance
+* );
+*
+* // All three policies must pass for the operation to succeed
+* const result = await combinedPolicy.can(user, 'update', context);
+* ```
+*
+* @example Multi-tenant + RBAC
+* ```typescript
+* const policy = combinePolicies(
+*   definePolicy({ tenant: { field: 'organizationId' } }),
+*   definePolicy({ roles: { update: ['admin', 'editor'] } }),
+* );
+* ```
+*/
+function combinePolicies(...policies) {
+	if (policies.length === 0) throw new Error("combinePolicies requires at least one policy");
+	if (policies.length === 1) return policies[0];
+	return {
+		async can(user, operation, context) {
+			const results = [];
+			for (const policy of policies) {
+				const result = await policy.can(user, operation, context);
+				if (!result.allowed) return result;
+				results.push(result);
+			}
+			const mergedResult = {
+				allowed: true,
+				filters: {},
+				metadata: {}
+			};
+			for (const result of results) if (result.filters) Object.assign(mergedResult.filters, result.filters);
+			const allExcludes = /* @__PURE__ */ new Set();
+			const allIncludes = [];
+			for (const result of results) {
+				if (result.fieldMask?.exclude) result.fieldMask.exclude.forEach((field) => allExcludes.add(field));
+				if (result.fieldMask?.include) allIncludes.push(new Set(result.fieldMask.include));
+			}
+			if (allExcludes.size > 0 || allIncludes.length > 0) {
+				mergedResult.fieldMask = {};
+				if (allExcludes.size > 0) mergedResult.fieldMask.exclude = Array.from(allExcludes);
+				if (allIncludes.length > 0) {
+					const intersection = allIncludes.reduce((acc, set) => {
+						return new Set([...acc].filter((x) => set.has(x)));
+					});
+					if (intersection.size > 0) mergedResult.fieldMask.include = Array.from(intersection);
+				}
+			}
+			for (const result of results) if (result.metadata) Object.assign(mergedResult.metadata, result.metadata);
+			if (Object.keys(mergedResult.filters).length === 0) delete mergedResult.filters;
+			if (Object.keys(mergedResult.metadata).length === 0) delete mergedResult.metadata;
+			return mergedResult;
+		},
+		toMiddleware(operation) {
+			const middlewares = policies.map((p) => p.toMiddleware(operation));
+			return async (request, reply) => {
+				for (const middleware of middlewares) {
+					await middleware(request, reply);
+					if (reply.sent) return;
+				}
+			};
+		}
+	};
+}
+/**
+* Combine multiple policies with OR logic
+*
+* At least one policy must allow the operation for it to succeed.
+* If all policies deny, returns the first denial reason.
+*
+* @param policies - Array of policy engines to combine
+* @returns Combined policy engine
+*
+* @example
+* ```typescript
+* const policy = anyPolicy(
+*   ownerPolicy,    // User owns the resource
+*   adminPolicy,    // OR user is admin
+*   publicPolicy,   // OR resource is public
+* );
+*
+* // Any one of these policies passing allows the operation
+* ```
+*/
+function anyPolicy(...policies) {
+	if (policies.length === 0) throw new Error("anyPolicy requires at least one policy");
+	if (policies.length === 1) return policies[0];
+	return {
+		async can(user, operation, context) {
+			let firstDenial = null;
+			for (const policy of policies) {
+				const result = await policy.can(user, operation, context);
+				if (result.allowed) return result;
+				if (!firstDenial) firstDenial = result;
+			}
+			return firstDenial;
+		},
+		toMiddleware(operation) {
+			return async (request, reply) => {
+				const results = [];
+				for (const policy of policies) {
+					const result = await policy.can(request.user, operation, {
+						document: request.document,
+						body: request.body,
+						params: request.params,
+						query: request.query
+					});
+					if (result.allowed) {
+						request.policyResult = result;
+						if (result.filters) request._policyFilters = result.filters;
+						if (result.fieldMask) request.fieldMask = result.fieldMask;
+						if (result.metadata) request.policyMetadata = result.metadata;
+						return;
+					}
+					results.push(result);
+				}
+				return reply.code(403).send({
+					success: false,
+					error: "Access denied",
+					message: results[0]?.reason || "You do not have permission to perform this action"
+				});
+			};
+		}
+	};
+}
+/**
+* Create a pass-through policy that always allows
+*
+* Useful for testing or for routes that don't need authorization.
+*
+* @example
+* ```typescript
+* const policy = allowAll();
+* const result = await policy.can(user, 'any-operation');
+* // result.allowed === true
+* ```
+*/
+function allowAll() {
+	return {
+		can() {
+			return { allowed: true };
+		},
+		toMiddleware() {
+			return async () => {};
+		}
+	};
+}
+/**
+* Create a policy that always denies
+*
+* Useful for explicitly blocking operations or for testing.
+*
+* @param reason - Denial reason
+*
+* @example
+* ```typescript
+* const policy = denyAll('This resource is deprecated');
+* const result = await policy.can(user, 'any-operation');
+* // result.allowed === false
+* // result.reason === 'This resource is deprecated'
+* ```
+*/
+function denyAll(reason = "Operation not allowed") {
+	return {
+		can() {
+			return {
+				allowed: false,
+				reason
+			};
+		},
+		toMiddleware() {
+			return async (request, reply) => {
+				return reply.code(403).send({
+					success: false,
+					error: "Access denied",
+					message: reason
+				});
+			};
+		}
+	};
+}
+
+//#endregion
+export { allowAll, anyPolicy, combinePolicies, createAccessControlPolicy, createPolicyMiddleware, denyAll };

package/dist/presets/{index.d.ts → index.d.mts}

@@ -1,115 +1,43 @@
-import { MultiTenantOptions } from './multiTenant.js';
-export { default as multiTenantPreset } from './multiTenant.js';
-import { f as PresetResult, a as IRequestContext, c as IControllerResponse, P as PaginatedResult, A as AnyRecord, l as ResourceConfig } from '../index-B4t03KQ0.js';
-import 'mongoose';
-import 'fastify';
-import '../types-B99TBmFV.js';
-
-/**
- * Soft Delete Preset
- *
- * Adds routes for listing deleted items and restoring them.
- */
-
-interface SoftDeleteOptions {
-    deletedField?: string;
-}
-declare function softDeletePreset(options?: SoftDeleteOptions): PresetResult;
-
-/**
- * Slug Lookup Preset
- *
- * Adds a route to get resource by slug.
- */
+import "../elevation-DGo5shaX.mjs";
+import { b as IControllerResponse, k as PaginatedResult, x as IRequestContext } from "../interface-e9XfSsUV.mjs";
+import "../types-RLkFVgaw.mjs";
+import { AnyRecord, PresetResult, ResourceConfig } from "../types/index.mjs";
+import multiTenantPreset, { MultiTenantOptions } from "./multiTenant.mjs";
 
+//#region src/presets/softDelete.d.ts
+declare function softDeletePreset(): PresetResult;
+//#endregion
+//#region src/presets/slugLookup.d.ts
 interface SlugLookupOptions {
-    slugField?: string;
+  slugField?: string;
 }
 declare function slugLookupPreset(options?: SlugLookupOptions): PresetResult;
-
-/**
- * Owned By User Preset
- *
- * Adds ownership validation for update/delete operations.
- *
- * BEHAVIOR:
- * - On update/remove, sets _ownershipCheck on request
- * - BaseController enforces ownership before mutation
- * - Users can only modify resources where ownerField matches their ID
- *
- * BYPASS:
- * - Users with bypassRoles (default: ['admin', 'superadmin']) skip check
- * - Resources without the ownerField are not checked
- *
- * @example
- * defineResource({
- *   name: 'post',
- *   presets: [{ name: 'ownedByUser', ownerField: 'authorId' }],
- * });
- *
- * // User A cannot update/delete User B's posts
- * // Admins can modify any post
- */
-
+//#endregion
+//#region src/presets/ownedByUser.d.ts
 interface OwnedByUserOptions {
-    ownerField?: string;
-    bypassRoles?: string[];
+  ownerField?: string;
 }
 declare function ownedByUserPreset(options?: OwnedByUserOptions): PresetResult;
-
-/**
- * Tree Preset
- *
- * Adds routes for hierarchical tree structures.
- */
-
+//#endregion
+//#region src/presets/tree.d.ts
 interface TreeOptions {
-    parentField?: string;
+  parentField?: string;
 }
 declare function treePreset(options?: TreeOptions): PresetResult;
-
-/**
- * Audited Preset
- *
- * Adds createdBy/updatedBy tracking to resources.
- * Works with the audit plugin for full change tracking.
- *
- * @example
- * defineResource({
- *   name: 'product',
- *   presets: ['audited'],
- *   // Fields createdBy, updatedBy auto-populated from user context
- * });
- */
-
+//#endregion
+//#region src/presets/audited.d.ts
 interface AuditedPresetOptions {
-    /** Field name for creator (default: 'createdBy') */
-    createdByField?: string;
-    /** Field name for updater (default: 'updatedBy') */
-    updatedByField?: string;
+  /** Field name for creator (default: 'createdBy') */
+  createdByField?: string;
+  /** Field name for updater (default: 'updatedBy') */
+  updatedByField?: string;
 }
 /**
  * Audited preset - adds createdBy/updatedBy tracking
  */
 declare function auditedPreset(options?: AuditedPresetOptions): PresetResult;
-
-/**
- * Preset Type Interfaces
- *
- * TypeScript interfaces that document the controller methods required by each preset.
- * These interfaces help with type safety when using presets.
- *
- * @example Using with custom controllers
- * ```typescript
- * import { BaseController } from '@classytic/arc';
- * import type { ISoftDeleteController } from '@classytic/arc/presets';
- *
- * class ProductController extends BaseController<Product> implements ISoftDeleteController {
- *   // TypeScript now ensures you have getDeleted() and restore() methods
- * }
- * ```
- */
-
+//#endregion
+//#region src/presets/types.d.ts
 /**
  * Soft Delete Preset Interface
  *
@@ -138,16 +66,16 @@ declare function auditedPreset(options?: AuditedPresetOptions): PresetResult;
  * ```
  */
 interface ISoftDeleteController<TDoc = unknown> {
-    /**
-     * Get all soft-deleted items
-     * Called by: GET /deleted
-     */
-    getDeleted(req: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
-    /**
-     * Restore a soft-deleted item by ID
-     * Called by: POST /:id/restore
-     */
-    restore(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  /**
+   * Get all soft-deleted items
+   * Called by: GET /deleted
+   */
+  getDeleted(req: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
+  /**
+   * Restore a soft-deleted item by ID
+   * Called by: POST /:id/restore
+   */
+  restore(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
 }
 /**
  * Slug Lookup Preset Interface
@@ -175,11 +103,11 @@ interface ISoftDeleteController<TDoc = unknown> {
  * ```
  */
 interface ISlugLookupController<TDoc = unknown> {
-    /**
-     * Get a resource by its slug
-     * Called by: GET /slug/:slug
-     */
-    getBySlug(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  /**
+   * Get a resource by its slug
+   * Called by: GET /slug/:slug
+   */
+  getBySlug(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
 }
 /**
  * Tree Preset Interface
@@ -209,16 +137,16 @@ interface ISlugLookupController<TDoc = unknown> {
  * ```
  */
 interface ITreeController<TDoc = unknown> {
-    /**
-     * Get the full hierarchical tree
-     * Called by: GET /tree
-     */
-    getTree(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
-    /**
-     * Get direct children of a parent node
-     * Called by: GET /:parent/children
-     */
-    getChildren(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+  /**
+   * Get the full hierarchical tree
+   * Called by: GET /tree
+   */
+  getTree(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+  /**
+   * Get direct children of a parent node
+   * Called by: GET /:parent/children
+   */
+  getChildren(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
 }
 /**
  * Owned By User Preset
@@ -301,36 +229,39 @@ type IAuditedPreset = never;
  * ```
  */
 type IPresetController<TDoc = unknown, TPresets extends 'softDelete' | 'slugLookup' | 'tree' | never = never> = TPresets extends 'softDelete' ? ISoftDeleteController<TDoc> : TPresets extends 'slugLookup' ? ISlugLookupController<TDoc> : TPresets extends 'tree' ? ITreeController<TDoc> : unknown;
-
+//#endregion
+//#region src/presets/index.d.ts
 /**
  * Convenience alias for multiTenantPreset with public list/get routes
  * Equivalent to: multiTenantPreset({ allowPublic: ['list', 'get'] })
  */
 declare const flexibleMultiTenantPreset: (options?: Omit<MultiTenantOptions, "allowPublic">) => PresetResult;
-
 type PresetFactory = (options?: AnyRecord) => PresetResult;
 /**
  * Get preset by name with options
  */
 declare function getPreset(nameOrConfig: string | {
-    name: string;
-    [key: string]: unknown;
+  name: string;
+  [key: string]: unknown;
 }): PresetResult;
 /**
  * Register a custom preset
  */
-declare function registerPreset(name: string, factory: PresetFactory): void;
+declare function registerPreset(name: string, factory: PresetFactory, options?: {
+  override?: boolean;
+}): void;
 /**
  * Get all available preset names
  */
 declare function getAvailablePresets(): string[];
 type PresetInput = string | PresetResult | {
-    name: string;
-    [key: string]: unknown;
+  name: string;
+  [key: string]: unknown;
 };
 /**
- * Apply presets to resource config
+ * Apply presets to resource config.
+ * Validates preset combinations for conflicts before merging.
  */
 declare function applyPresets<TDoc = AnyRecord>(config: ResourceConfig<TDoc>, presets?: PresetInput[]): ResourceConfig<TDoc>;
-
-export { type AuditedPresetOptions, type IAuditedPreset, type IMultiTenantPreset, type IOwnedByUserPreset, type IPresetController, type ISlugLookupController, type ISoftDeleteController, type ITreeController, MultiTenantOptions, type OwnedByUserOptions, type SlugLookupOptions, type SoftDeleteOptions, type TreeOptions, applyPresets, auditedPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, ownedByUserPreset, registerPreset, slugLookupPreset, softDeletePreset, treePreset };
+//#endregion
+export { type AuditedPresetOptions, type IAuditedPreset, type IMultiTenantPreset, type IOwnedByUserPreset, type IPresetController, type ISlugLookupController, type ISoftDeleteController, type ITreeController, type MultiTenantOptions, type OwnedByUserOptions, type SlugLookupOptions, type TreeOptions, applyPresets, auditedPreset, flexibleMultiTenantPreset, getAvailablePresets, getPreset, multiTenantPreset, ownedByUserPreset, registerPreset, slugLookupPreset, softDeletePreset, treePreset };