@kysera/rls 0.6.0 → 0.6.1

package/README.md

@@ -921,6 +921,7 @@ import {
   RLSError,
   RLSContextError,
   RLSPolicyViolation,
+  RLSPolicyEvaluationError,
   RLSSchemaError,
   RLSContextValidationError,
   RLSErrorCodes,
@@ -945,7 +946,7 @@ try {
 
 #### `RLSPolicyViolation`
 
-Thrown when a database operation is denied by RLS policies.
+Thrown when a database operation is denied by RLS policies (legitimate access denial).
 
 ```typescript
 try {
@@ -963,6 +964,30 @@ try {
 }
 ```
 
+#### `RLSPolicyEvaluationError`
+
+Thrown when a policy fails to evaluate due to an error in the policy code itself (bug in policy implementation). This is distinct from `RLSPolicyViolation`, which represents legitimate access denial.
+
+```typescript
+try {
+  // Policy throws an error during evaluation
+  await orm.posts.findAll();
+} catch (error) {
+  if (error instanceof RLSPolicyEvaluationError) {
+    console.error('Policy evaluation failed:', {
+      operation: error.operation, // 'read'
+      table: error.table, // 'posts'
+      policyName: error.policyName, // 'tenant_filter'
+      originalError: error.originalError, // The underlying error
+      message: error.message, // Error message with context
+    });
+
+    // Original stack trace is preserved for debugging
+    console.error('Stack trace:', error.stack);
+  }
+}
+```
+
 ### Handling Violations
 
 ```typescript
@@ -1152,6 +1177,7 @@ export {
   RLSError,
   RLSContextError,
   RLSPolicyViolation,
+  RLSPolicyEvaluationError,
   RLSSchemaError,
   RLSContextValidationError,
   RLSErrorCodes,

package/dist/index.d.ts

@@ -347,6 +347,8 @@ declare const RLSErrorCodes: {
     readonly RLS_SCHEMA_INVALID: ErrorCode;
     /** RLS context validation failed */
     readonly RLS_CONTEXT_INVALID: ErrorCode;
+    /** RLS policy evaluation threw an error */
+    readonly RLS_POLICY_EVALUATION_ERROR: ErrorCode;
 };
 /**
  * Type for RLS error codes
@@ -469,6 +471,39 @@ declare class RLSPolicyViolation extends RLSError {
     constructor(operation: string, table: string, reason: string, policyName?: string);
     toJSON(): Record<string, unknown>;
 }
+/**
+ * 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
+ * ```
+ */
+declare class RLSPolicyEvaluationError extends RLSError {
+    readonly operation: string;
+    readonly table: string;
+    readonly policyName?: string;
+    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);
+    toJSON(): Record<string, unknown>;
+}
 /**
  * Error thrown when RLS schema validation fails
  *
@@ -702,4 +737,4 @@ declare function hashString(str: string): string;
  */
 declare function normalizeOperations(operation: Operation | Operation[]): Operation[];
 
-export { CompiledFilterPolicy, CompiledPolicy, type CreateRLSContextOptions, FilterCondition, Operation, PolicyCondition, PolicyDefinition, PolicyEvaluationContext, PolicyHints, type PolicyOptions, PolicyRegistry, RLSAuthContext, RLSContext, RLSContextError, RLSContextValidationError, RLSError, type RLSErrorCode, RLSErrorCodes, type RLSPluginOptions, RLSPolicyViolation, RLSRequestContext, RLSSchema, RLSSchemaError, TableRLSConfig, allow, createEvaluationContext, createRLSContext, deepMerge, defineRLSSchema, deny, filter, hashString, isAsyncFunction, mergeRLSSchemas, normalizeOperations, rlsContext, rlsPlugin, safeEvaluate, validate, withRLSContext, withRLSContextAsync };
+export { CompiledFilterPolicy, CompiledPolicy, type CreateRLSContextOptions, FilterCondition, Operation, PolicyCondition, PolicyDefinition, PolicyEvaluationContext, PolicyHints, type PolicyOptions, PolicyRegistry, RLSAuthContext, RLSContext, RLSContextError, RLSContextValidationError, RLSError, type RLSErrorCode, RLSErrorCodes, type RLSPluginOptions, RLSPolicyEvaluationError, RLSPolicyViolation, RLSRequestContext, RLSSchema, RLSSchemaError, TableRLSConfig, allow, createEvaluationContext, createRLSContext, deepMerge, defineRLSSchema, deny, filter, hashString, isAsyncFunction, mergeRLSSchemas, normalizeOperations, rlsContext, rlsPlugin, safeEvaluate, validate, withRLSContext, withRLSContextAsync };

package/dist/index.js

@@ -1,4 +1,5 @@
 import { silentLogger } from '@kysera/core';
+import { sql } from 'kysely';
 import { AsyncLocalStorage } from 'async_hooks';
 
 // src/errors.ts
@@ -12,7 +13,9 @@ var RLSErrorCodes = {
   /** RLS schema definition is invalid */
   RLS_SCHEMA_INVALID: "RLS_SCHEMA_INVALID",
   /** RLS context validation failed */
-  RLS_CONTEXT_INVALID: "RLS_CONTEXT_INVALID"
+  RLS_CONTEXT_INVALID: "RLS_CONTEXT_INVALID",
+  /** RLS policy evaluation threw an error */
+  RLS_POLICY_EVALUATION_ERROR: "RLS_POLICY_EVALUATION_ERROR"
 };
 var RLSError = class extends Error {
   code;
@@ -110,6 +113,59 @@ var RLSPolicyViolation = class extends RLSError {
     return json;
   }
 };
+var RLSPolicyEvaluationError = class extends RLSError {
+  operation;
+  table;
+  policyName;
+  originalError;
+  /**
+   * 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, table, message, policyName, originalError) {
+    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 !== void 0) {
+      this.policyName = policyName;
+    }
+    if (originalError !== void 0) {
+      this.originalError = originalError;
+      if (originalError.stack) {
+        this.stack = `${this.stack}
+
+Caused by:
+${originalError.stack}`;
+      }
+    }
+  }
+  toJSON() {
+    const json = {
+      ...super.toJSON(),
+      operation: this.operation,
+      table: this.table
+    };
+    if (this.policyName !== void 0) {
+      json["policyName"] = this.policyName;
+    }
+    if (this.originalError !== void 0) {
+      json["originalError"] = {
+        name: this.originalError.name,
+        message: this.originalError.message
+      };
+    }
+    return json;
+  }
+};
 var RLSSchemaError = class extends RLSError {
   details;
   /**
@@ -810,6 +866,18 @@ var SelectTransformer = class {
   /**
    * 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)
@@ -825,7 +893,7 @@ var SelectTransformer = class {
         continue;
       } else if (Array.isArray(value)) {
         if (value.length === 0) {
-          result = result.where(qualifiedColumn, "=", "__RLS_NO_MATCH__");
+          result = result.where(sql`FALSE`);
         } else {
           result = result.where(qualifiedColumn, "in", value);
         }
@@ -839,8 +907,7 @@ var SelectTransformer = class {
 
 // src/transformer/mutation.ts
 var MutationGuard = class {
-  // executor is kept for future use with database-dependent policies
-  constructor(registry, _executor) {
+  constructor(registry) {
     this.registry = registry;
   }
   /**
@@ -852,7 +919,7 @@ var MutationGuard = class {
    *
    * @example
    * ```typescript
-   * const guard = new MutationGuard(registry, db);
+   * const guard = new MutationGuard(registry);
    * await guard.checkCreate('posts', { title: 'Hello', tenant_id: 1 });
    * ```
    */
@@ -869,7 +936,7 @@ var MutationGuard = class {
    *
    * @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' });
    * ```
@@ -886,7 +953,7 @@ var MutationGuard = class {
    *
    * @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);
    * ```
@@ -903,7 +970,7 @@ var MutationGuard = class {
    *
    * @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);
    * ```
@@ -913,7 +980,7 @@ var MutationGuard = class {
       await this.checkMutation(table, "read", row);
       return true;
     } catch (error) {
-      if (error instanceof RLSPolicyViolation) {
+      if (error instanceof RLSPolicyViolation || error instanceof RLSPolicyEvaluationError) {
         return false;
       }
       throw error;
@@ -933,7 +1000,7 @@ var MutationGuard = class {
       await this.checkMutation(table, operation, row, data);
       return true;
     } catch (error) {
-      if (error instanceof RLSPolicyViolation) {
+      if (error instanceof RLSPolicyViolation || error instanceof RLSPolicyEvaluationError) {
         return false;
       }
       throw error;
@@ -973,7 +1040,7 @@ var MutationGuard = class {
       ...ctx.meta !== void 0 && { meta: ctx.meta }
     };
     for (const validate2 of validates) {
-      const result = await this.evaluatePolicy(validate2.evaluate, evalCtx);
+      const result = await this.evaluatePolicy(validate2.evaluate, evalCtx, validate2.name);
       if (!result) {
         return false;
       }
@@ -1008,7 +1075,7 @@ var MutationGuard = class {
     const denies = this.registry.getDenies(table, operation);
     for (const deny2 of denies) {
       const evalCtx = this.createEvalContext(ctx, table, operation, row, data);
-      const result = await this.evaluatePolicy(deny2.evaluate, evalCtx);
+      const result = await this.evaluatePolicy(deny2.evaluate, evalCtx, deny2.name);
       if (result) {
         throw new RLSPolicyViolation(
           operation,
@@ -1021,7 +1088,7 @@ var MutationGuard = class {
       const validates = this.registry.getValidates(table, operation);
       for (const validate2 of validates) {
         const evalCtx = this.createEvalContext(ctx, table, operation, row, data);
-        const result = await this.evaluatePolicy(validate2.evaluate, evalCtx);
+        const result = await this.evaluatePolicy(validate2.evaluate, evalCtx, validate2.name);
         if (!result) {
           throw new RLSPolicyViolation(
             operation,
@@ -1044,7 +1111,7 @@ var MutationGuard = class {
       let allowed = false;
       for (const allow2 of allows) {
         const evalCtx = this.createEvalContext(ctx, table, operation, row, data);
-        const result = await this.evaluatePolicy(allow2.evaluate, evalCtx);
+        const result = await this.evaluatePolicy(allow2.evaluate, evalCtx, allow2.name);
         if (result) {
           allowed = true;
           break;
@@ -1074,16 +1141,25 @@ var MutationGuard = class {
   }
   /**
    * 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
    */
-  async evaluatePolicy(condition, evalCtx) {
+  async evaluatePolicy(condition, evalCtx, policyName) {
     try {
       const result = condition(evalCtx);
       return result instanceof Promise ? await result : result;
     } catch (error) {
-      throw new RLSPolicyViolation(
+      const originalError = error instanceof Error ? error : void 0;
+      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
       );
     }
   }
@@ -1097,7 +1173,7 @@ var MutationGuard = class {
    *
    * @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);
    * ```
@@ -1135,7 +1211,7 @@ function rlsPlugin(options) {
     /**
      * Initialize plugin - compile policies
      */
-    async onInit(executor) {
+    async onInit(_executor) {
       logger.info?.("[RLS] Initializing RLS plugin", {
         tables: Object.keys(schema).length,
         skipTables: skipTables.length,
@@ -1144,7 +1220,7 @@ function rlsPlugin(options) {
       registry = new PolicyRegistry(schema);
       registry.validate();
       selectTransformer = new SelectTransformer(registry);
-      mutationGuard = new MutationGuard(registry, executor);
+      mutationGuard = new MutationGuard(registry);
       logger.info?.("[RLS] RLS plugin initialized successfully");
     },
     /**
@@ -1466,6 +1542,6 @@ function normalizeOperations(operation) {
   return [operation];
 }
 
-export { PolicyRegistry, RLSContextError, RLSContextValidationError, RLSError, RLSErrorCodes, RLSPolicyViolation, RLSSchemaError, allow, createEvaluationContext, createRLSContext, deepMerge, defineRLSSchema, deny, filter, hashString, isAsyncFunction, mergeRLSSchemas, normalizeOperations, rlsContext, rlsPlugin, safeEvaluate, validate, withRLSContext, withRLSContextAsync };
+export { PolicyRegistry, RLSContextError, RLSContextValidationError, RLSError, RLSErrorCodes, RLSPolicyEvaluationError, RLSPolicyViolation, RLSSchemaError, allow, createEvaluationContext, createRLSContext, deepMerge, defineRLSSchema, deny, filter, hashString, isAsyncFunction, mergeRLSSchemas, normalizeOperations, rlsContext, rlsPlugin, safeEvaluate, validate, withRLSContext, withRLSContextAsync };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map