@classytic/arc 2.9.1 → 2.10.3

package/dist/policies/index.d.mts

@@ -1,425 +0,0 @@
-import { t as PermissionCheck } from "../types-DZi1aYhm.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).
-   *
-   * Values are `unknown` because filter dialects differ (MongoDB operator
-   * objects, SQL WHERE AST, structured DSLs) — adapters narrow at the edge.
-   *
-   * @example
-   * ```typescript
-   * // Multi-tenant filter
-   * { organizationId: user.organizationId }
-   *
-   * // Complex filter
-   * { $or: [{ public: true }, { createdBy: user.id }] }
-   * ```
-   */
-  filters?: Record<string, unknown>;
-  /**
-   * 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, unknown>;
-}
-/**
- * Policy context provided to `can()`.
- *
- * Fields are `unknown` by design: the shape depends on the adapter and the
- * operation (e.g. `document` is the repository's row type, `body` is the
- * wire DTO). Implementations narrow at the call site with a type guard or
- * generic — this is the only honest contract across adapters.
- */
-interface PolicyContext {
-  /** The document being accessed (for update/delete/get). Populated by fetchDocument middleware. */
-  document?: unknown;
-  /** Request body (for create/update). */
-  body?: unknown;
-  /** Request params (e.g., `:id` from route). */
-  params?: unknown;
-  /** Request query parameters. */
-  query?: unknown;
-  /** Additional app-specific context keyed by policy-defined names. */
-  [key: string]: unknown;
-}
-/**
- * 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 (!getUserRoles(user).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: unknown, 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 = unknown> = (config: TConfig) => PolicyEngine;
-/**
- * Extended Fastify request with policy result
- */
-/**
- * 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[];
-}
-/**
- * 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';
- *
- * 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
- *
- * 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;
-//#endregion
-export { type AccessControlPolicyOptions, type AccessControlStatement, type PolicyContext, type PolicyEngine, type PolicyFactory, type PolicyResult, allowAll, anyPolicy, combinePolicies, createAccessControlPolicy, createPolicyMiddleware, denyAll };