@classytic/arc 1.0.0

package/dist/policies/index.d.ts

@@ -0,0 +1,398 @@
+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'] },
+ *     };
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
+
+/**
+ * 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>;
+}
+/**
+ * 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;
+}
+/**
+ * Policy Engine Interface
+ *
+ * Implement this interface to create your own authorization strategy.
+ *
+ * Arc provides the interface, apps provide the implementation.
+ * This follows the same pattern as:
+ * - Database drivers (interface: query(), implementation: PostgreSQL, MySQL)
+ * - Storage providers (interface: upload(), implementation: S3, Azure)
+ * - Authentication strategies (interface: verify(), implementation: JWT, OAuth)
+ *
+ * @example E-commerce RBAC + Ownership
+ * ```typescript
+ * class EcommercePolicyEngine implements PolicyEngine {
+ *   constructor(private config: { roles: Record<string, string[]> }) {}
+ *
+ *   can(user, operation, context) {
+ *     // Check RBAC
+ *     const allowedRoles = this.config.roles[operation] || [];
+ *     if (!user.roles.some(r => allowedRoles.includes(r))) {
+ *       return { allowed: false, reason: 'Insufficient permissions' };
+ *     }
+ *
+ *     // Check ownership for update/delete
+ *     if (['update', 'delete'].includes(operation)) {
+ *       if (context.document.userId !== user.id) {
+ *         return { allowed: false, reason: 'Not the owner' };
+ *       }
+ *     }
+ *
+ *     // Multi-tenant filter for list
+ *     if (operation === 'list') {
+ *       return {
+ *         allowed: true,
+ *         filters: { organizationId: user.organizationId },
+ *       };
+ *     }
+ *
+ *     return { allowed: true };
+ *   }
+ *
+ *   toMiddleware(operation) {
+ *     return async (request, reply) => {
+ *       const result = await this.can(request.user, operation, {
+ *         document: request.document,
+ *         body: request.body,
+ *         params: request.params,
+ *         query: request.query,
+ *       });
+ *
+ *       if (!result.allowed) {
+ *         reply.code(403).send({ error: result.reason });
+ *       }
+ *
+ *       // Attach filters/fieldMask to request
+ *       request.policyResult = result;
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @example HIPAA Compliance
+ * ```typescript
+ * class HIPAAPolicyEngine implements PolicyEngine {
+ *   can(user, operation, context) {
+ *     // Check patient consent
+ *     // Verify user certifications
+ *     // Check data sensitivity level
+ *     // Create audit log entry
+ *
+ *     return {
+ *       allowed: this.checkHIPAACompliance(user, operation, context),
+ *       reason: 'HIPAA compliance check failed',
+ *       metadata: {
+ *         auditLog: this.createAuditEntry(user, operation),
+ *       },
+ *     };
+ *   }
+ *
+ *   toMiddleware(operation) {
+ *     // HIPAA-specific middleware with audit logging
+ *   }
+ * }
+ * ```
+ */
+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>;
+}
+/**
+ * Policy factory function signature
+ *
+ * Policies are typically created via factory functions that accept configuration.
+ *
+ * @example
+ * ```typescript
+ * export function definePolicy(config: PolicyConfig): PolicyEngine {
+ *   return new MyPolicyEngine(config);
+ * }
+ *
+ * // Usage
+ * const productPolicy = definePolicy({
+ *   resource: 'product',
+ *   roles: { list: ['user'], create: ['admin'] },
+ *   ownership: { field: 'userId', operations: ['update', 'delete'] },
+ * });
+ * ```
+ */
+type PolicyFactory<TConfig = any> = (config: TConfig) => PolicyEngine;
+/**
+ * Extended Fastify request with policy result
+ */
+declare module 'fastify' {
+    interface FastifyRequest {
+        policyResult?: PolicyResult;
+    }
+}
+
+/**
+ * Policy Helper Utilities
+ *
+ * Common operations for working with PolicyEngine implementations.
+ */
+
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+declare function createPolicyMiddleware(policy: PolicyEngine, operation: string): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+/**
+ * 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'] } }),
+ * );
+ * ```
+ */
+declare function combinePolicies(...policies: PolicyEngine[]): PolicyEngine;
+/**
+ * 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
+ * ```
+ */
+declare function anyPolicy(...policies: PolicyEngine[]): PolicyEngine;
+/**
+ * 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
+ * ```
+ */
+declare function allowAll(): PolicyEngine;
+/**
+ * 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'
+ * ```
+ */
+declare function denyAll(reason?: string): PolicyEngine;
+
+export { type PolicyContext, type PolicyEngine, type PolicyFactory, type PolicyResult, allowAll, anyPolicy, combinePolicies, createPolicyMiddleware, denyAll };

package/dist/policies/index.js

@@ -0,0 +1,196 @@
+// src/policies/helpers.ts
+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.query = request.query || {};
+      request.query._policyFilters = result.filters;
+    }
+    if (result.fieldMask) {
+      request.fieldMask = result.fieldMask;
+    }
+    if (result.metadata) {
+      request.policyMetadata = result.metadata;
+    }
+  };
+}
+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;
+          }
+        }
+      };
+    }
+  };
+}
+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.query = request.query || {};
+              request.query._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"
+        });
+      };
+    }
+  };
+}
+function allowAll() {
+  return {
+    can() {
+      return { allowed: true };
+    },
+    toMiddleware() {
+      return async () => {
+      };
+    }
+  };
+}
+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
+        });
+      };
+    }
+  };
+}
+
+export { allowAll, anyPolicy, combinePolicies, createPolicyMiddleware, denyAll };