@kysera/rls 0.5.1 → 0.6.1

package/src/errors.ts

@@ -31,6 +31,8 @@ export const RLSErrorCodes = {
   RLS_SCHEMA_INVALID: 'RLS_SCHEMA_INVALID' as ErrorCode,
   /** RLS context validation failed */
   RLS_CONTEXT_INVALID: 'RLS_CONTEXT_INVALID' as ErrorCode,
+  /** RLS policy evaluation threw an error */
+  RLS_POLICY_EVALUATION_ERROR: 'RLS_POLICY_EVALUATION_ERROR' as ErrorCode,
 } as const;
 
 /**
@@ -227,6 +229,86 @@ export class RLSPolicyViolation extends RLSError {
   }
 }
 
+// ============================================================================
+// Policy Evaluation Errors
+// ============================================================================
+
+/**
+ * Error thrown when a policy condition throws an error during evaluation
+ *
+ * This error is distinct from RLSPolicyViolation - it indicates a bug in the
+ * policy condition function itself, not a legitimate access denial.
+ *
+ * @example
+ * ```typescript
+ * // A policy with a bug
+ * allow('read', ctx => {
+ *   return ctx.row.someField.value; // Throws if someField is undefined
+ * });
+ *
+ * // This will throw RLSPolicyEvaluationError, not RLSPolicyViolation
+ * ```
+ */
+export class RLSPolicyEvaluationError extends RLSError {
+  public readonly operation: string;
+  public readonly table: string;
+  public readonly policyName?: string;
+  public readonly originalError?: Error;
+
+  /**
+   * Creates a new policy evaluation error
+   *
+   * @param operation - Database operation being performed
+   * @param table - Table name where error occurred
+   * @param message - Error message from the policy
+   * @param policyName - Name of the policy that threw
+   * @param originalError - The original error thrown by the policy
+   */
+  constructor(
+    operation: string,
+    table: string,
+    message: string,
+    policyName?: string,
+    originalError?: Error
+  ) {
+    super(
+      `RLS policy evaluation error during ${operation} on ${table}: ${message}`,
+      RLSErrorCodes.RLS_POLICY_EVALUATION_ERROR
+    );
+    this.name = 'RLSPolicyEvaluationError';
+    this.operation = operation;
+    this.table = table;
+    if (policyName !== undefined) {
+      this.policyName = policyName;
+    }
+    if (originalError !== undefined) {
+      this.originalError = originalError;
+      // Preserve the original stack trace for debugging
+      if (originalError.stack) {
+        this.stack = `${this.stack}\n\nCaused by:\n${originalError.stack}`;
+      }
+    }
+  }
+
+  override toJSON(): Record<string, unknown> {
+    const json: Record<string, unknown> = {
+      ...super.toJSON(),
+      operation: this.operation,
+      table: this.table,
+    };
+    if (this.policyName !== undefined) {
+      json['policyName'] = this.policyName;
+    }
+    if (this.originalError !== undefined) {
+      json['originalError'] = {
+        name: this.originalError.name,
+        message: this.originalError.message,
+      };
+    }
+    return json;
+  }
+}
+
 // ============================================================================
 // Schema Errors
 // ============================================================================

package/src/index.ts

@@ -75,6 +75,7 @@ export {
   RLSError,
   RLSContextError,
   RLSPolicyViolation,
+  RLSPolicyEvaluationError,
   RLSSchemaError,
   RLSContextValidationError,
   RLSErrorCodes,

package/src/plugin.ts

@@ -135,7 +135,7 @@ export function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin {
     /**
      * Initialize plugin - compile policies
      */
-    async onInit<TDB>(executor: Kysely<TDB>): Promise<void> {
+    async onInit<TDB>(_executor: Kysely<TDB>): Promise<void> {
       logger.info?.('[RLS] Initializing RLS plugin', {
         tables: Object.keys(schema).length,
         skipTables: skipTables.length,
@@ -148,7 +148,7 @@ export function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin {
 
       // Create transformers
       selectTransformer = new SelectTransformer<DB>(registry);
-      mutationGuard = new MutationGuard<DB>(registry, executor as unknown as Kysely<DB>);
+      mutationGuard = new MutationGuard<DB>(registry);
 
       logger.info?.('[RLS] RLS plugin initialized successfully');
     },

package/src/policy/types.ts

@@ -299,6 +299,18 @@ export interface PolicyEvaluationContext<
    * Can contain any additional context needed for policy evaluation
    */
   meta?: Record<string, unknown>;
+
+  /**
+   * Table name being accessed (optional)
+   * Available during mutation operations
+   */
+  table?: string;
+
+  /**
+   * Operation being performed (optional)
+   * E.g., 'create', 'update', 'delete'
+   */
+  operation?: string;
 }
 
 // ============================================================================

package/src/transformer/mutation.ts

@@ -3,22 +3,18 @@
  * Validates CREATE, UPDATE, DELETE operations against RLS policies
  */
 
-import type { Kysely } from 'kysely';
 import type { PolicyRegistry } from '../policy/registry.js';
 import type { PolicyEvaluationContext, Operation } from '../policy/types.js';
 import type { RLSContext } from '../context/types.js';
 import { rlsContext } from '../context/manager.js';
-import { RLSPolicyViolation } from '../errors.js';
+import { RLSPolicyViolation, RLSPolicyEvaluationError } from '../errors.js';
 
 /**
  * Mutation guard
  * Validates mutations (CREATE, UPDATE, DELETE) against allow/deny/validate policies
  */
 export class MutationGuard<DB = unknown> {
-  constructor(
-    private registry: PolicyRegistry<DB>,
-    private executor?: Kysely<DB>
-  ) {}
+  constructor(private registry: PolicyRegistry<DB>) {}
 
   /**
    * Check if CREATE operation is allowed
@@ -29,7 +25,7 @@ export class MutationGuard<DB = unknown> {
    *
    * @example
    * ```typescript
-   * const guard = new MutationGuard(registry, db);
+   * const guard = new MutationGuard(registry);
    * await guard.checkCreate('posts', { title: 'Hello', tenant_id: 1 });
    * ```
    */
@@ -50,7 +46,7 @@ export class MutationGuard<DB = unknown> {
    *
    * @example
    * ```typescript
-   * const guard = new MutationGuard(registry, db);
+   * const guard = new MutationGuard(registry);
    * const existingPost = await db.selectFrom('posts').where('id', '=', 1).selectAll().executeTakeFirst();
    * await guard.checkUpdate('posts', existingPost, { title: 'Updated' });
    * ```
@@ -72,7 +68,7 @@ export class MutationGuard<DB = unknown> {
    *
    * @example
    * ```typescript
-   * const guard = new MutationGuard(registry, db);
+   * const guard = new MutationGuard(registry);
    * const existingPost = await db.selectFrom('posts').where('id', '=', 1).selectAll().executeTakeFirst();
    * await guard.checkDelete('posts', existingPost);
    * ```
@@ -93,7 +89,7 @@ export class MutationGuard<DB = unknown> {
    *
    * @example
    * ```typescript
-   * const guard = new MutationGuard(registry, db);
+   * const guard = new MutationGuard(registry);
    * const post = await db.selectFrom('posts').where('id', '=', 1).selectAll().executeTakeFirst();
    * const canRead = await guard.checkRead('posts', post);
    * ```
@@ -106,7 +102,8 @@ export class MutationGuard<DB = unknown> {
       await this.checkMutation(table, 'read', row);
       return true;
     } catch (error) {
-      if (error instanceof RLSPolicyViolation) {
+      // Both policy violations and evaluation errors result in denial
+      if (error instanceof RLSPolicyViolation || error instanceof RLSPolicyEvaluationError) {
         return false;
       }
       throw error;
@@ -132,7 +129,8 @@ export class MutationGuard<DB = unknown> {
       await this.checkMutation(table, operation, row, data);
       return true;
     } catch (error) {
-      if (error instanceof RLSPolicyViolation) {
+      // Both policy violations and evaluation errors result in denial
+      if (error instanceof RLSPolicyViolation || error instanceof RLSPolicyEvaluationError) {
         return false;
       }
       throw error;
@@ -188,7 +186,7 @@ export class MutationGuard<DB = unknown> {
 
     // All validate policies must pass
     for (const validate of validates) {
-      const result = await this.evaluatePolicy(validate.evaluate, evalCtx);
+      const result = await this.evaluatePolicy(validate.evaluate, evalCtx, validate.name);
       if (!result) {
         return false;
       }
@@ -236,7 +234,7 @@ export class MutationGuard<DB = unknown> {
     const denies = this.registry.getDenies(table, operation);
     for (const deny of denies) {
       const evalCtx = this.createEvalContext(ctx, table, operation, row, data);
-      const result = await this.evaluatePolicy(deny.evaluate, evalCtx);
+      const result = await this.evaluatePolicy(deny.evaluate, evalCtx, deny.name);
 
       if (result) {
         throw new RLSPolicyViolation(
@@ -252,7 +250,7 @@ export class MutationGuard<DB = unknown> {
       const validates = this.registry.getValidates(table, operation);
       for (const validate of validates) {
         const evalCtx = this.createEvalContext(ctx, table, operation, row, data);
-        const result = await this.evaluatePolicy(validate.evaluate, evalCtx);
+        const result = await this.evaluatePolicy(validate.evaluate, evalCtx, validate.name);
 
         if (!result) {
           throw new RLSPolicyViolation(
@@ -282,7 +280,7 @@ export class MutationGuard<DB = unknown> {
 
       for (const allow of allows) {
         const evalCtx = this.createEvalContext(ctx, table, operation, row, data);
-        const result = await this.evaluatePolicy(allow.evaluate, evalCtx);
+        const result = await this.evaluatePolicy(allow.evaluate, evalCtx, allow.name);
 
         if (result) {
           allowed = true;
@@ -316,26 +314,37 @@ export class MutationGuard<DB = unknown> {
       data,
       table,
       operation,
-      metadata: ctx.meta,
+      ...(ctx.meta !== undefined && { meta: ctx.meta as Record<string, unknown> }),
     };
   }
 
   /**
    * Evaluate a policy condition
+   *
+   * @param condition - Policy condition function
+   * @param evalCtx - Policy evaluation context
+   * @param policyName - Name of the policy being evaluated (for error reporting)
+   * @returns Boolean result of policy evaluation
+   * @throws RLSPolicyEvaluationError if the policy throws an error
    */
   private async evaluatePolicy(
     condition: (ctx: PolicyEvaluationContext) => boolean | Promise<boolean>,
-    evalCtx: PolicyEvaluationContext
+    evalCtx: PolicyEvaluationContext,
+    policyName?: string
   ): Promise<boolean> {
     try {
       const result = condition(evalCtx);
       return result instanceof Promise ? await result : result;
     } catch (error) {
-      // Policy evaluation errors are treated as denial
-      throw new RLSPolicyViolation(
-        evalCtx.operation,
-        evalCtx.table,
-        `Policy evaluation error: ${error instanceof Error ? error.message : 'Unknown error'}`
+      // Distinguish between policy evaluation errors and policy violations
+      // RLSPolicyEvaluationError indicates a bug in the policy, not a legitimate denial
+      const originalError = error instanceof Error ? error : undefined;
+      throw new RLSPolicyEvaluationError(
+        evalCtx.operation ?? 'unknown',
+        evalCtx.table ?? 'unknown',
+        error instanceof Error ? error.message : 'Unknown error',
+        policyName,
+        originalError
       );
     }
   }
@@ -350,7 +359,7 @@ export class MutationGuard<DB = unknown> {
    *
    * @example
    * ```typescript
-   * const guard = new MutationGuard(registry, db);
+   * const guard = new MutationGuard(registry);
    * const allPosts = await db.selectFrom('posts').selectAll().execute();
    * const accessiblePosts = await guard.filterRows('posts', allPosts);
    * ```

package/src/transformer/select.ts

@@ -4,6 +4,7 @@
  */
 
 import type { SelectQueryBuilder } from 'kysely';
+import { sql } from 'kysely';
 import type { PolicyRegistry } from '../policy/registry.js';
 import type { PolicyEvaluationContext } from '../policy/types.js';
 import type { RLSContext } from '../context/types.js';
@@ -108,6 +109,18 @@ export class SelectTransformer<DB = unknown> {
   /**
    * Apply filter conditions to query builder
    *
+   * NOTE ON TYPE CASTS:
+   * The `as any` casts in this method are intentional architectural boundaries.
+   * Kysely's type system is designed for static query building where column names
+   * are known at compile time. RLS policies work with dynamic column names at runtime.
+   *
+   * Type safety is maintained through:
+   * 1. Policy conditions are validated during schema registration
+   * 2. Column names come from policy definitions (developer-controlled)
+   * 3. Values are type-checked by the policy condition functions
+   *
+   * This is the same pattern used in @kysera/repository/table-operations.ts
+   *
    * @param qb - Query builder to modify
    * @param conditions - WHERE clause conditions
    * @param table - Table name (for qualified column names)
@@ -122,6 +135,7 @@ export class SelectTransformer<DB = unknown> {
 
     for (const [column, value] of Object.entries(conditions)) {
       // Use table-qualified column name to avoid ambiguity in joins
+      // Cast is necessary because Kysely expects compile-time known column names
       const qualifiedColumn = `${table}.${column}` as any;
 
       if (value === null) {
@@ -132,9 +146,10 @@ export class SelectTransformer<DB = unknown> {
         continue;
       } else if (Array.isArray(value)) {
         if (value.length === 0) {
-          // Empty array means no matches - add impossible condition
-          // This ensures the query returns no rows
-          result = result.where(qualifiedColumn, '=', '__RLS_NO_MATCH__' as any);
+          // Empty array means no matches - add impossible condition using SQL FALSE
+          // This ensures the query returns no rows without using magic strings
+          // that could potentially match actual data
+          result = result.where(sql`FALSE` as any);
         } else {
           // IN clause for array values
           result = result.where(qualifiedColumn, 'in', value as any);