@kysera/rls 0.7.3 → 0.8.0

package/src/policy/builder.ts

@@ -13,19 +13,19 @@ import type {
   PolicyDefinition,
   PolicyCondition,
   FilterCondition,
-  PolicyHints,
-} from './types.js';
+  PolicyHints
+} from './types.js'
 
 /**
  * Options for policy definitions
  */
 export interface PolicyOptions {
   /** Policy name for debugging and identification */
-  name?: string;
+  name?: string
   /** Priority (higher runs first, deny policies default to 100) */
-  priority?: number;
+  priority?: number
   /** Performance optimization hints */
-  hints?: PolicyHints;
+  hints?: PolicyHints
 }
 
 /**
@@ -58,19 +58,19 @@ export function allow(
   const policy: PolicyDefinition = {
     type: 'allow',
     operation,
-    condition: condition as PolicyCondition,
-    priority: options?.priority ?? 0,
-  };
+    condition: condition,
+    priority: options?.priority ?? 0
+  }
 
   if (options?.name !== undefined) {
-    policy.name = options.name;
+    policy.name = options.name
   }
 
   if (options?.hints !== undefined) {
-    policy.hints = options.hints;
+    policy.hints = options.hints
   }
 
-  return policy;
+  return policy
 }
 
 /**
@@ -104,36 +104,51 @@ export function deny(
   const policy: PolicyDefinition = {
     type: 'deny',
     operation,
-    condition: (condition ?? (() => true)) as PolicyCondition,
-    priority: options?.priority ?? 100, // Deny policies run first by default
-  };
+    condition: condition ?? (() => true),
+    priority: options?.priority ?? 100 // Deny policies run first by default
+  }
 
   if (options?.name !== undefined) {
-    policy.name = options.name;
+    policy.name = options.name
   }
 
   if (options?.hints !== undefined) {
-    policy.hints = options.hints;
+    policy.hints = options.hints
   }
 
-  return policy;
+  return policy
 }
 
 /**
  * Create a filter policy
  * Adds WHERE conditions to SELECT queries
  *
+ * **IMPORTANT**: Filter conditions must be synchronous functions.
+ * Async filter policies are not currently supported because filters are applied
+ * directly to query builders at query construction time.
+ *
  * @example
  * ```typescript
- * // Filter by tenant
+ * // ✅ CORRECT: Filter by tenant (synchronous)
  * filter('read', ctx => ({ tenant_id: ctx.auth.tenantId }))
  *
- * // Filter by organization with soft delete
+ * // ✅ CORRECT: Filter by organization with soft delete
  * filter('read', ctx => ({
  *   organization_id: ctx.auth.organizationIds?.[0],
  *   deleted_at: null
  * }))
  *
+ * // ❌ WRONG: Async filter (not supported)
+ * // filter('read', async ctx => {
+ * //   const tenantId = await fetchTenantId(ctx.auth.userId)
+ * //   return { tenant_id: tenantId }
+ * // })
+ *
+ * // ✅ WORKAROUND: Fetch data before creating context
+ * // const tenantId = await fetchTenantId(userId)
+ * // const ctx = createRLSContext({ auth: { userId, tenantId, roles: [] } })
+ * // filter('read', ctx => ({ tenant_id: ctx.auth.tenantId }))
+ *
  * // Named filter
  * filter('read', ctx => ({ tenant_id: ctx.auth.tenantId }), {
  *   name: 'tenant-filter'
@@ -149,18 +164,18 @@ export function filter(
     type: 'filter',
     operation: operation === 'all' ? 'read' : operation,
     condition: condition as unknown as PolicyCondition,
-    priority: options?.priority ?? 0,
-  };
+    priority: options?.priority ?? 0
+  }
 
   if (options?.name !== undefined) {
-    policy.name = options.name;
+    policy.name = options.name
   }
 
   if (options?.hints !== undefined) {
-    policy.hints = options.hints;
+    policy.hints = options.hints
   }
 
-  return policy;
+  return policy
 }
 
 /**
@@ -192,24 +207,22 @@ export function validate(
   condition: PolicyCondition,
   options?: PolicyOptions
 ): PolicyDefinition {
-  const ops: Operation[] = operation === 'all'
-    ? ['create', 'update']
-    : [operation];
+  const ops: Operation[] = operation === 'all' ? ['create', 'update'] : [operation]
 
   const policy: PolicyDefinition = {
     type: 'validate',
     operation: ops,
-    condition: condition as PolicyCondition,
-    priority: options?.priority ?? 0,
-  };
+    condition: condition,
+    priority: options?.priority ?? 0
+  }
 
   if (options?.name !== undefined) {
-    policy.name = options.name;
+    policy.name = options.name
   }
 
   if (options?.hints !== undefined) {
-    policy.hints = options.hints;
+    policy.hints = options.hints
   }
 
-  return policy;
+  return policy
 }

package/src/policy/index.ts

@@ -4,7 +4,7 @@
  * Exports all policy-related types, builders, and schema functions.
  */
 
-export * from './types.js';
-export { allow, deny, filter, validate, type PolicyOptions } from './builder.js';
-export { defineRLSSchema, mergeRLSSchemas } from './schema.js';
-export { PolicyRegistry } from './registry.js';
+export type * from './types.js'
+export { allow, deny, filter, validate, type PolicyOptions } from './builder.js'
+export { defineRLSSchema, mergeRLSSchemas } from './schema.js'
+export { PolicyRegistry } from './registry.js'

package/src/policy/registry.ts

@@ -15,31 +15,32 @@ import type {
   TableRLSConfig,
   CompiledPolicy,
   CompiledFilterPolicy,
-} from './types.js';
-import { RLSSchemaError } from '../errors.js';
-import { silentLogger, type KyseraLogger } from '@kysera/core';
+  PolicyEvaluationContext
+} from './types.js'
+import { RLSSchemaError } from '../errors.js'
+import { silentLogger, type KyseraLogger } from '@kysera/core'
 
 /**
  * Internal compiled policy with operations as Set for efficient lookup
  */
 interface InternalCompiledPolicy {
-  name: string;
-  operations: Set<Operation>;
-  type: 'allow' | 'deny' | 'validate';
-  evaluate: (ctx: any) => boolean | Promise<boolean>;
-  priority: number;
+  name: string
+  operations: Set<Operation>
+  type: 'allow' | 'deny' | 'validate'
+  evaluate: (ctx: PolicyEvaluationContext) => boolean | Promise<boolean>
+  priority: number
 }
 
 /**
  * Table policy configuration
  */
 interface TablePolicyConfig {
-  allows: InternalCompiledPolicy[];
-  denies: InternalCompiledPolicy[];
-  filters: CompiledFilterPolicy[];
-  validates: InternalCompiledPolicy[];
-  skipFor: string[]; // Role names that bypass RLS
-  defaultDeny: boolean;
+  allows: InternalCompiledPolicy[]
+  denies: InternalCompiledPolicy[]
+  filters: CompiledFilterPolicy[]
+  validates: InternalCompiledPolicy[]
+  skipFor: string[] // Role names that bypass RLS
+  defaultDeny: boolean
 }
 
 /**
@@ -47,14 +48,14 @@ interface TablePolicyConfig {
  * Manages and provides access to RLS policies
  */
 export class PolicyRegistry<DB = unknown> {
-  private tables = new Map<string, TablePolicyConfig>();
-  private compiled = false;
-  private logger: KyseraLogger;
+  private tables = new Map<string, TablePolicyConfig>()
+  private compiled = false
+  private logger: KyseraLogger
 
   constructor(schema?: RLSSchema<DB>, options?: { logger?: KyseraLogger }) {
-    this.logger = options?.logger ?? silentLogger;
+    this.logger = options?.logger ?? silentLogger
     if (schema) {
-      this.loadSchema(schema);
+      this.loadSchema(schema)
     }
   }
 
@@ -77,10 +78,10 @@ export class PolicyRegistry<DB = unknown> {
    */
   loadSchema(schema: RLSSchema<DB>): void {
     for (const [table, config] of Object.entries(schema)) {
-      if (!config) continue;
-      this.registerTable(table, config as TableRLSConfig);
+      if (!config) continue
+      this.registerTable(table, config as TableRLSConfig)
     }
-    this.compiled = true;
+    this.compiled = true
   }
 
   /**
@@ -96,49 +97,49 @@ export class PolicyRegistry<DB = unknown> {
       filters: [],
       validates: [],
       skipFor: config.skipFor ?? [],
-      defaultDeny: config.defaultDeny ?? true,
-    };
+      defaultDeny: config.defaultDeny ?? true
+    }
 
     // Compile and categorize policies
     for (let i = 0; i < config.policies.length; i++) {
-      const policy = config.policies[i];
-      if (!policy) continue;
+      const policy = config.policies[i]
+      if (!policy) continue
 
-      const policyName = policy.name ?? `${table}_policy_${i}`;
+      const policyName = policy.name ?? `${table}_policy_${i}`
 
       try {
         if (policy.type === 'filter') {
-          const compiled = this.compileFilterPolicy(policy, policyName);
-          tableConfig.filters.push(compiled);
+          const compiled = this.compileFilterPolicy(policy, policyName)
+          tableConfig.filters.push(compiled)
         } else {
-          const compiled = this.compilePolicy(policy, policyName);
+          const compiled = this.compilePolicy(policy, policyName)
 
           switch (policy.type) {
             case 'allow':
-              tableConfig.allows.push(compiled);
-              break;
+              tableConfig.allows.push(compiled)
+              break
             case 'deny':
-              tableConfig.denies.push(compiled);
-              break;
+              tableConfig.denies.push(compiled)
+              break
             case 'validate':
-              tableConfig.validates.push(compiled);
-              break;
+              tableConfig.validates.push(compiled)
+              break
           }
         }
       } catch (error) {
         throw new RLSSchemaError(
           `Failed to compile policy "${policyName}" for table "${table}": ${error instanceof Error ? error.message : String(error)}`,
           { table, policy: policyName }
-        );
+        )
       }
     }
 
     // Sort by priority (higher priority first)
-    tableConfig.allows.sort((a, b) => b.priority - a.priority);
-    tableConfig.denies.sort((a, b) => b.priority - a.priority);
-    tableConfig.validates.sort((a, b) => b.priority - a.priority);
+    tableConfig.allows.sort((a, b) => b.priority - a.priority)
+    tableConfig.denies.sort((a, b) => b.priority - a.priority)
+    tableConfig.validates.sort((a, b) => b.priority - a.priority)
 
-    this.tables.set(table, tableConfig);
+    this.tables.set(table, tableConfig)
   }
 
   /**
@@ -147,48 +148,48 @@ export class PolicyRegistry<DB = unknown> {
    * @overload Register a full schema
    * @overload Register policies for a single table (deprecated)
    */
-  register(schemaOrTable: RLSSchema<DB>): void;
+  register(schemaOrTable: RLSSchema<DB>): void
   register(
     schemaOrTable: keyof DB & string,
     policies: PolicyDefinition[],
     options?: {
-      skipFor?: string[];
-      defaultDeny?: boolean;
+      skipFor?: string[]
+      defaultDeny?: boolean
     }
-  ): void;
+  ): void
   register(
     schemaOrTable: RLSSchema<DB> | (keyof DB & string),
     policies?: PolicyDefinition[],
     options?: {
-      skipFor?: string[]; // Role names that bypass RLS
-      defaultDeny?: boolean;
+      skipFor?: string[] // Role names that bypass RLS
+      defaultDeny?: boolean
     }
   ): void {
     // If first argument is an object with policies, treat as schema
     if (typeof schemaOrTable === 'object' && schemaOrTable !== null) {
-      this.loadSchema(schemaOrTable);
-      return;
+      this.loadSchema(schemaOrTable)
+      return
     }
 
     // Otherwise, treat as table-based registration
-    const table = schemaOrTable as keyof DB & string;
+    const table = schemaOrTable
     if (!policies) {
-      throw new RLSSchemaError('Policies are required when registering by table name', { table });
+      throw new RLSSchemaError('Policies are required when registering by table name', { table })
     }
 
     const config: TableRLSConfig = {
-      policies,
-    };
+      policies
+    }
 
     if (options?.skipFor !== undefined) {
-      config.skipFor = options.skipFor;
+      config.skipFor = options.skipFor
     }
 
     if (options?.defaultDeny !== undefined) {
-      config.defaultDeny = options.defaultDeny;
+      config.defaultDeny = options.defaultDeny
     }
 
-    this.registerTable(table, config);
+    this.registerTable(table, config)
   }
 
   /**
@@ -199,22 +200,20 @@ export class PolicyRegistry<DB = unknown> {
    * @returns Compiled policy ready for evaluation
    */
   private compilePolicy(policy: PolicyDefinition, name: string): InternalCompiledPolicy {
-    const operations = Array.isArray(policy.operation)
-      ? policy.operation
-      : [policy.operation];
+    const operations = Array.isArray(policy.operation) ? policy.operation : [policy.operation]
 
     // Expand 'all' to all operations
     const expandedOps = operations.flatMap(op =>
       op === 'all' ? (['read', 'create', 'update', 'delete'] as const) : [op]
-    ) as Operation[];
+    ) as Operation[]
 
     return {
       name,
       operations: new Set(expandedOps),
       type: policy.type as 'allow' | 'deny' | 'validate',
-      evaluate: policy.condition as (ctx: any) => boolean | Promise<boolean>,
-      priority: policy.priority ?? (policy.type === 'deny' ? 100 : 0),
-    };
+      evaluate: policy.condition as (ctx: PolicyEvaluationContext) => boolean | Promise<boolean>,
+      priority: policy.priority ?? (policy.type === 'deny' ? 100 : 0)
+    }
   }
 
   /**
@@ -225,13 +224,13 @@ export class PolicyRegistry<DB = unknown> {
    * @returns Compiled filter policy
    */
   private compileFilterPolicy(policy: PolicyDefinition, name: string): CompiledFilterPolicy {
-    const condition = policy.condition as unknown as FilterCondition;
+    const condition = policy.condition as unknown as FilterCondition
 
     return {
       operation: 'read',
-      getConditions: condition as (ctx: any) => Record<string, unknown>,
-      name,
-    };
+      getConditions: condition as (ctx: PolicyEvaluationContext) => Record<string, unknown>,
+      name
+    }
   }
 
   /**
@@ -243,89 +242,85 @@ export class PolicyRegistry<DB = unknown> {
       type: internal.type,
       operation: Array.from(internal.operations),
       evaluate: internal.evaluate,
-      priority: internal.priority,
-    };
+      priority: internal.priority
+    }
   }
 
   /**
    * Get allow policies for a table and operation
    */
   getAllows(table: string, operation: Operation): CompiledPolicy[] {
-    const config = this.tables.get(table);
-    if (!config) return [];
+    const config = this.tables.get(table)
+    if (!config) return []
 
-    return config.allows
-      .filter(p => p.operations.has(operation))
-      .map(p => this.toCompiledPolicy(p));
+    return config.allows.filter(p => p.operations.has(operation)).map(p => this.toCompiledPolicy(p))
   }
 
   /**
    * Get deny policies for a table and operation
    */
   getDenies(table: string, operation: Operation): CompiledPolicy[] {
-    const config = this.tables.get(table);
-    if (!config) return [];
+    const config = this.tables.get(table)
+    if (!config) return []
 
-    return config.denies
-      .filter(p => p.operations.has(operation))
-      .map(p => this.toCompiledPolicy(p));
+    return config.denies.filter(p => p.operations.has(operation)).map(p => this.toCompiledPolicy(p))
   }
 
   /**
    * Get validate policies for a table and operation
    */
   getValidates(table: string, operation: Operation): CompiledPolicy[] {
-    const config = this.tables.get(table);
-    if (!config) return [];
+    const config = this.tables.get(table)
+    if (!config) return []
 
     return config.validates
       .filter(p => p.operations.has(operation))
-      .map(p => this.toCompiledPolicy(p));
+      .map(p => this.toCompiledPolicy(p))
   }
 
   /**
    * Get filter policies for a table
    */
   getFilters(table: string): CompiledFilterPolicy[] {
-    const config = this.tables.get(table);
-    return config?.filters ?? [];
+    const config = this.tables.get(table)
+    return config?.filters ?? []
   }
 
   /**
    * Get roles that skip RLS for a table
    */
   getSkipFor(table: string): string[] {
-    const config = this.tables.get(table);
-    return config?.skipFor ?? [];
+    const config = this.tables.get(table)
+    return config?.skipFor ?? []
   }
 
   /**
    * Check if table has default deny
    */
   hasDefaultDeny(table: string): boolean {
-    const config = this.tables.get(table);
-    return config?.defaultDeny ?? true;
+    const config = this.tables.get(table)
+    return config?.defaultDeny ?? true
   }
 
   /**
    * Check if a table is registered
    */
   hasTable(table: string): boolean {
-    return this.tables.has(table);
+    return this.tables.has(table)
   }
 
   /**
    * Get all registered table names
    */
   getTables(): string[] {
-    return Array.from(this.tables.keys());
+    return Array.from(this.tables.keys())
   }
 
   /**
    * Check if registry is compiled
    */
   isCompiled(): boolean {
-    return this.compiled;
+    return this.compiled
   }
 
   /**
@@ -342,45 +337,45 @@ export class PolicyRegistry<DB = unknown> {
         config.allows.length > 0 ||
         config.denies.length > 0 ||
         config.filters.length > 0 ||
-        config.validates.length > 0;
+        config.validates.length > 0
 
       if (!hasPolicy && !config.defaultDeny) {
         // Warning: table has no policies and defaultDeny is false
         this.logger.warn?.(
           `[RLS] Table "${table}" has no policies and defaultDeny is false. ` +
             `All operations will be allowed.`
-        );
+        )
       }
 
       // Warn if skipFor includes operations that have policies
       if (config.skipFor.length > 0) {
-        const opsWithPolicies = new Set<Operation>();
+        const opsWithPolicies = new Set<Operation>()
 
         for (const allow of config.allows) {
-          allow.operations.forEach(op => opsWithPolicies.add(op));
+          allow.operations.forEach(op => opsWithPolicies.add(op))
         }
         for (const deny of config.denies) {
-          deny.operations.forEach(op => opsWithPolicies.add(op));
+          deny.operations.forEach(op => opsWithPolicies.add(op))
         }
         for (const validate of config.validates) {
-          validate.operations.forEach(op => opsWithPolicies.add(op));
+          validate.operations.forEach(op => opsWithPolicies.add(op))
         }
         if (config.filters.length > 0) {
-          opsWithPolicies.add('read');
+          opsWithPolicies.add('read')
         }
 
         const skippedOpsWithPolicies = config.skipFor.filter(op => {
           // 'all' means skip all operations
-          if (op === 'all') return opsWithPolicies.size > 0;
+          if (op === 'all') return opsWithPolicies.size > 0
           // Check if this is an operation name (for backwards compatibility)
-          return opsWithPolicies.has(op as Operation);
-        });
+          return opsWithPolicies.has(op as Operation)
+        })
 
         if (skippedOpsWithPolicies.length > 0) {
           this.logger.warn?.(
             `[RLS] Table "${table}" has skipFor operations that also have policies: ${skippedOpsWithPolicies.join(', ')}. ` +
               `The policies will be ignored for these operations.`
-          );
+          )
         }
       }
     }
@@ -390,14 +385,14 @@ export class PolicyRegistry<DB = unknown> {
    * Clear all policies
    */
   clear(): void {
-    this.tables.clear();
-    this.compiled = false;
+    this.tables.clear()
+    this.compiled = false
   }
 
   /**
    * Remove policies for a specific table
    */
   remove(table: string): void {
-    this.tables.delete(table);
+    this.tables.delete(table)
   }
 }