@kysera/rls 0.6.0 → 0.7.0

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

@@ -1,5 +1,5 @@
 /**
- * @kysera/rls - Row-Level Security Plugin for Kysera ORM
+ * @kysera/rls - Row-Level Security Plugin for Kysera
  *
  * Provides declarative policy definition, automatic query transformation,
  * and optional native PostgreSQL RLS generation.
@@ -75,6 +75,7 @@ export {
   RLSError,
   RLSContextError,
   RLSPolicyViolation,
+  RLSPolicyEvaluationError,
   RLSSchemaError,
   RLSContextValidationError,
   RLSErrorCodes,

package/src/plugin.ts

@@ -10,7 +10,8 @@
  * @module @kysera/rls
  */
 
-import type { Plugin, QueryBuilderContext, AnyQueryBuilder } from '@kysera/repository';
+import type { Plugin, QueryBuilderContext } from '@kysera/executor';
+import { getRawDb } from '@kysera/executor';
 import type { Kysely } from 'kysely';
 import type { RLSSchema, Operation } from './policy/types.js';
 import { PolicyRegistry } from './policy/registry.js';
@@ -85,7 +86,7 @@ interface BaseRepository {
  *   },
  * });
  *
- * // Create ORM with RLS plugin
+ * // Create repository with RLS plugin
  * const orm = await createORM(db, [
  *   rlsPlugin({ schema }),
  * ]);
@@ -124,7 +125,7 @@ export function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin {
 
   return {
     name: '@kysera/rls',
-    version: '0.5.1',
+    version: '0.7.0',
 
     // Run after soft-delete (priority 0), before audit
     priority: 50,
@@ -135,7 +136,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 +149,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');
     },
@@ -160,7 +161,7 @@ export function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin {
      * it applies filter policies as WHERE conditions. For mutations, it marks
      * that RLS validation is required (performed in extendRepository).
      */
-    interceptQuery<QB extends AnyQueryBuilder>(
+    interceptQuery<QB>(
       qb: QB,
       context: QueryBuilderContext
     ): QB {
@@ -265,6 +266,11 @@ export function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin {
       const originalDelete = baseRepo.delete?.bind(baseRepo);
       const originalFindById = baseRepo.findById?.bind(baseRepo);
 
+      // Get raw db for internal queries that need to bypass RLS
+      // If executor doesn't have __rawDb (e.g., in tests), we'll use originalFindById
+      const rawDb = getRawDb(baseRepo.executor);
+      const hasRawDb = (baseRepo.executor as any).__rawDb !== undefined;
+
       const extendedRepo = {
         ...baseRepo,
 
@@ -309,7 +315,7 @@ export function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin {
          * Wrapped update with RLS check
          */
         async update(id: unknown, data: unknown): Promise<unknown> {
-          if (!originalUpdate || !originalFindById) {
+          if (!originalUpdate) {
             throw new RLSError('Repository does not support update operation', RLSErrorCodes.RLS_POLICY_INVALID);
           }
 
@@ -318,7 +324,23 @@ export function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin {
           if (ctx && !ctx.auth.isSystem &&
               !bypassRoles.some(role => ctx.auth.roles.includes(role))) {
             // Fetch existing row for policy evaluation
-            const existingRow = await originalFindById(id);
+            // Use raw db if available to bypass RLS filtering and prevent self-interception
+            let existingRow: unknown;
+
+            if (hasRawDb) {
+              // Use raw db to bypass RLS filtering
+              existingRow = await rawDb
+                .selectFrom(table as any)
+                .selectAll()
+                .where('id' as any, '=', id as any)
+                .executeTakeFirst();
+            } else if (originalFindById) {
+              // Fallback to originalFindById for tests/mocks
+              existingRow = await originalFindById(id);
+            } else {
+              throw new RLSError('Repository does not support update operation', RLSErrorCodes.RLS_POLICY_INVALID);
+            }
+
             if (!existingRow) {
               // Let the original method handle not found
               return originalUpdate(id, data);
@@ -357,7 +379,7 @@ export function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin {
          * Wrapped delete with RLS check
          */
         async delete(id: unknown): Promise<unknown> {
-          if (!originalDelete || !originalFindById) {
+          if (!originalDelete) {
             throw new RLSError('Repository does not support delete operation', RLSErrorCodes.RLS_POLICY_INVALID);
           }
 
@@ -366,7 +388,23 @@ export function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin {
           if (ctx && !ctx.auth.isSystem &&
               !bypassRoles.some(role => ctx.auth.roles.includes(role))) {
             // Fetch existing row for policy evaluation
-            const existingRow = await originalFindById(id);
+            // Use raw db if available to bypass RLS filtering and prevent self-interception
+            let existingRow: unknown;
+
+            if (hasRawDb) {
+              // Use raw db to bypass RLS filtering
+              existingRow = await rawDb
+                .selectFrom(table as any)
+                .selectAll()
+                .where('id' as any, '=', id as any)
+                .executeTakeFirst();
+            } else if (originalFindById) {
+              // Fallback to originalFindById for tests/mocks
+              existingRow = await originalFindById(id);
+            } else {
+              throw new RLSError('Repository does not support delete operation', RLSErrorCodes.RLS_POLICY_INVALID);
+            }
+
             if (!existingRow) {
               // Let the original method handle not found
               return originalDelete(id);

package/src/transformer/mutation.ts

@@ -3,23 +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> {
-  // executor is kept for future use with database-dependent policies
-  constructor(
-    private registry: PolicyRegistry<DB>,
-    _executor?: Kysely<DB>
-  ) {}
+  constructor(private registry: PolicyRegistry<DB>) {}
 
   /**
    * Check if CREATE operation is allowed
@@ -30,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 });
    * ```
    */
@@ -51,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' });
    * ```
@@ -73,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);
    * ```
@@ -94,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);
    * ```
@@ -107,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;
@@ -133,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;
@@ -189,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;
       }
@@ -237,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(
@@ -253,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(
@@ -283,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;
@@ -323,20 +320,31 @@ export class MutationGuard<DB = 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(
+      // 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',
-        `Policy evaluation error: ${error instanceof Error ? error.message : 'Unknown error'}`
+        error instanceof Error ? error.message : 'Unknown error',
+        policyName,
+        originalError
       );
     }
   }
@@ -351,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);