@classytic/arc 1.1.0 → 2.1.3

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

@@ -1,130 +1,91 @@
-import { FastifyRequest, FastifyReply } from 'fastify';
-
-/**
- * Policy Interface
- *
- * Pluggable authorization interface for Arc.
- * Apps implement this interface to define custom authorization strategies.
- *
- * @example RBAC Policy
- * ```typescript
- * class RBACPolicy implements PolicyEngine {
- *   can(user, operation, context) {
- *     return {
- *       allowed: user.roles.includes('admin'),
- *       reason: 'Admin role required',
- *     };
- *   }
- *   toMiddleware(operation) {
- *     return async (request, reply) => {
- *       const result = await this.can(request.user, operation);
- *       if (!result.allowed) {
- *         reply.code(403).send({ error: result.reason });
- *       }
- *     };
- *   }
- * }
- * ```
- *
- * @example ABAC (Attribute-Based) Policy
- * ```typescript
- * class ABACPolicy implements PolicyEngine {
- *   can(user, operation, context) {
- *     return {
- *       allowed: this.evaluateAttributes(user, operation, context),
- *       filters: { department: user.department },
- *       fieldMask: { exclude: ['salary', 'ssn'] },
- *     };
- *   }
- *   // ...
- * }
- * ```
- */
+import { t as PermissionCheck } from "../types-RLkFVgaw.mjs";
+import { FastifyReply, FastifyRequest } from "fastify";
 
+//#region src/policies/PolicyInterface.d.ts
 /**
  * Policy result returned by can() method
  */
 interface PolicyResult {
-    /**
-     * Whether the operation is allowed
-     */
-    allowed: boolean;
-    /**
-     * Human-readable reason if denied
-     * Returned in 403 error responses
-     */
-    reason?: string;
-    /**
-     * Query filters to apply (for list operations)
-     *
-     * @example
-     * ```typescript
-     * // Multi-tenant filter
-     * { organizationId: user.organizationId }
-     *
-     * // Ownership filter
-     * { userId: user.id }
-     *
-     * // Complex filter
-     * { $or: [{ public: true }, { createdBy: user.id }] }
-     * ```
-     */
-    filters?: Record<string, any>;
-    /**
-     * Fields to include/exclude in response
-     *
-     * @example
-     * ```typescript
-     * // Hide sensitive fields from non-admins
-     * { exclude: ['password', 'ssn', 'salary'] }
-     *
-     * // Only show specific fields
-     * { include: ['name', 'email', 'role'] }
-     * ```
-     */
-    fieldMask?: {
-        include?: string[];
-        exclude?: string[];
-    };
-    /**
-     * Additional context for downstream middleware
-     *
-     * @example
-     * ```typescript
-     * {
-     *   auditLog: { action: 'read', resource: 'patient', userId: user.id },
-     *   rateLimit: { tier: user.subscriptionTier },
-     * }
-     * ```
-     */
-    metadata?: Record<string, any>;
+  /**
+   * Whether the operation is allowed
+   */
+  allowed: boolean;
+  /**
+   * Human-readable reason if denied
+   * Returned in 403 error responses
+   */
+  reason?: string;
+  /**
+   * Query filters to apply (for list operations)
+   *
+   * @example
+   * ```typescript
+   * // Multi-tenant filter
+   * { organizationId: user.organizationId }
+   *
+   * // Ownership filter
+   * { userId: user.id }
+   *
+   * // Complex filter
+   * { $or: [{ public: true }, { createdBy: user.id }] }
+   * ```
+   */
+  filters?: Record<string, any>;
+  /**
+   * Fields to include/exclude in response
+   *
+   * @example
+   * ```typescript
+   * // Hide sensitive fields from non-admins
+   * { exclude: ['password', 'ssn', 'salary'] }
+   *
+   * // Only show specific fields
+   * { include: ['name', 'email', 'role'] }
+   * ```
+   */
+  fieldMask?: {
+    include?: string[];
+    exclude?: string[];
+  };
+  /**
+   * Additional context for downstream middleware
+   *
+   * @example
+   * ```typescript
+   * {
+   *   auditLog: { action: 'read', resource: 'patient', userId: user.id },
+   *   rateLimit: { tier: user.subscriptionTier },
+   * }
+   * ```
+   */
+  metadata?: Record<string, any>;
 }
 /**
  * Policy context provided to can() method
  */
 interface PolicyContext {
-    /**
-     * The document being accessed (for update/delete/get)
-     * Populated by fetchDocument middleware
-     */
-    document?: any;
-    /**
-     * Request body (for create/update)
-     */
-    body?: any;
-    /**
-     * Request params (e.g., :id from route)
-     */
-    params?: any;
-    /**
-     * Request query parameters
-     */
-    query?: any;
-    /**
-     * Additional app-specific context
-     * Can include anything your policy needs to make decisions
-     */
-    [key: string]: any;
+  /**
+   * The document being accessed (for update/delete/get)
+   * Populated by fetchDocument middleware
+   */
+  document?: any;
+  /**
+   * Request body (for create/update)
+   */
+  body?: any;
+  /**
+   * Request params (e.g., :id from route)
+   */
+  params?: any;
+  /**
+   * Request query parameters
+   */
+  query?: any;
+  /**
+   * Additional app-specific context
+   * Can include anything your policy needs to make decisions
+   */
+  [key: string]: any;
 }
 /**
  * Policy Engine Interface
@@ -145,7 +106,7 @@ interface PolicyContext {
  *   can(user, operation, context) {
  *     // Check RBAC
  *     const allowedRoles = this.config.roles[operation] || [];
- *     if (!user.roles.some(r => allowedRoles.includes(r))) {
+ *     if (!getUserRoles(user).some(r => allowedRoles.includes(r))) {
  *       return { allowed: false, reason: 'Insufficient permissions' };
  *     }
  *
@@ -212,48 +173,48 @@ interface PolicyContext {
  * ```
  */
 interface PolicyEngine {
-    /**
-     * Check if user can perform operation
-     *
-     * @param user - User object from request (request.user)
-     * @param operation - Operation name (list, get, create, update, delete, custom)
-     * @param context - Additional context (document, body, params, query, etc.)
-     * @returns Policy result with allowed/denied and optional filters/fieldMask
-     *
-     * @example
-     * ```typescript
-     * const result = await policy.can(request.user, 'update', {
-     *   document: existingDocument,
-     *   body: request.body,
-     * });
-     *
-     * if (!result.allowed) {
-     *   throw new Error(result.reason);
-     * }
-     * ```
-     */
-    can(user: any, operation: string, context?: PolicyContext): PolicyResult | Promise<PolicyResult>;
-    /**
-     * Generate Fastify middleware for this policy
-     *
-     * Called during route registration to create preHandler middleware.
-     * Middleware should:
-     * 1. Call can() with request context
-     * 2. Return 403 if denied
-     * 3. Attach result to request for downstream use
-     *
-     * @param operation - Operation name (list, get, create, update, delete)
-     * @returns Fastify preHandler middleware
-     *
-     * @example
-     * ```typescript
-     * const middleware = policy.toMiddleware('update');
-     * fastify.put('/products/:id', {
-     *   preHandler: [authenticate, middleware],
-     * }, handler);
-     * ```
-     */
-    toMiddleware(operation: string): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  /**
+   * Check if user can perform operation
+   *
+   * @param user - User object from request (request.user)
+   * @param operation - Operation name (list, get, create, update, delete, custom)
+   * @param context - Additional context (document, body, params, query, etc.)
+   * @returns Policy result with allowed/denied and optional filters/fieldMask
+   *
+   * @example
+   * ```typescript
+   * const result = await policy.can(request.user, 'update', {
+   *   document: existingDocument,
+   *   body: request.body,
+   * });
+   *
+   * if (!result.allowed) {
+   *   throw new Error(result.reason);
+   * }
+   * ```
+   */
+  can(user: any, operation: string, context?: PolicyContext): PolicyResult | Promise<PolicyResult>;
+  /**
+   * Generate Fastify middleware for this policy
+   *
+   * Called during route registration to create preHandler middleware.
+   * Middleware should:
+   * 1. Call can() with request context
+   * 2. Return 403 if denied
+   * 3. Attach result to request for downstream use
+   *
+   * @param operation - Operation name (list, get, create, update, delete)
+   * @returns Fastify preHandler middleware
+   *
+   * @example
+   * ```typescript
+   * const middleware = policy.toMiddleware('update');
+   * fastify.put('/products/:id', {
+   *   preHandler: [authenticate, middleware],
+   * }, handler);
+   * ```
+   */
+  toMiddleware(operation: string): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
 }
 /**
  * Policy factory function signature
@@ -278,18 +239,91 @@ type PolicyFactory<TConfig = any> = (config: TConfig) => PolicyEngine;
 /**
  * Extended Fastify request with policy result
  */
-declare module 'fastify' {
-    interface FastifyRequest {
-        policyResult?: PolicyResult;
-    }
+/**
+ * Access control statement
+ *
+ * Maps to Better Auth's organization permission model
+ * where permissions are defined as resource + action pairs.
+ */
+interface AccessControlStatement {
+  /** Resource name (e.g., 'product', 'order') */
+  resource: string;
+  /** Allowed actions on this resource */
+  action: string[];
 }
-
 /**
- * Policy Helper Utilities
+ * Options for createAccessControlPolicy
+ */
+interface AccessControlPolicyOptions {
+  /** Permission statements defining resource-action pairs */
+  statements: AccessControlStatement[];
+  /**
+   * Optional async permission check against external source (e.g., org role permissions).
+   * Called when the static statements allow the action — use this for dynamic checks
+   * like verifying the user's org role actually grants the permission.
+   *
+   * @param userId - ID of the user
+   * @param resource - Resource being accessed
+   * @param action - Action being performed
+   * @returns Whether the user has the permission
+   */
+  checkPermission?: (userId: string, resource: string, action: string) => Promise<boolean>;
+}
+/**
+ * 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';
  *
- * Common operations for working with PolicyEngine implementations.
+ * 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);
+ *   },
+ * });
+ * ```
  */
-
+declare function createAccessControlPolicy(options: AccessControlPolicyOptions): PermissionCheck;
+declare module 'fastify' {
+  interface FastifyRequest {
+    policyResult?: PolicyResult;
+  }
+}
+//#endregion
+//#region src/policies/helpers.d.ts
 /**
  * Helper to create Fastify middleware from any PolicyEngine implementation
  *
@@ -394,5 +428,5 @@ declare function allowAll(): PolicyEngine;
  * ```
  */
 declare function denyAll(reason?: string): PolicyEngine;
-
-export { type PolicyContext, type PolicyEngine, type PolicyFactory, type PolicyResult, allowAll, anyPolicy, combinePolicies, createPolicyMiddleware, denyAll };
+//#endregion
+export { type AccessControlPolicyOptions, type AccessControlStatement, type PolicyContext, type PolicyEngine, type PolicyFactory, type PolicyResult, allowAll, anyPolicy, combinePolicies, createAccessControlPolicy, createPolicyMiddleware, denyAll };