@kysera/rls 0.5.1

package/src/transformer/index.ts

@@ -0,0 +1,2 @@
+export { SelectTransformer } from './select.js';
+export { MutationGuard } from './mutation.js';

package/src/transformer/mutation.ts

@@ -0,0 +1,372 @@
+/**
+ * Mutation Guard
+ * 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';
+
+/**
+ * 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>
+  ) {}
+
+  /**
+   * Check if CREATE operation is allowed
+   *
+   * @param table - Table name
+   * @param data - Data being inserted
+   * @throws RLSPolicyViolation if access is denied
+   *
+   * @example
+   * ```typescript
+   * const guard = new MutationGuard(registry, db);
+   * await guard.checkCreate('posts', { title: 'Hello', tenant_id: 1 });
+   * ```
+   */
+  async checkCreate(
+    table: string,
+    data: Record<string, unknown>
+  ): Promise<void> {
+    await this.checkMutation(table, 'create', undefined, data);
+  }
+
+  /**
+   * Check if UPDATE operation is allowed
+   *
+   * @param table - Table name
+   * @param existingRow - Current row data
+   * @param data - Data being updated
+   * @throws RLSPolicyViolation if access is denied
+   *
+   * @example
+   * ```typescript
+   * const guard = new MutationGuard(registry, db);
+   * const existingPost = await db.selectFrom('posts').where('id', '=', 1).selectAll().executeTakeFirst();
+   * await guard.checkUpdate('posts', existingPost, { title: 'Updated' });
+   * ```
+   */
+  async checkUpdate(
+    table: string,
+    existingRow: Record<string, unknown>,
+    data: Record<string, unknown>
+  ): Promise<void> {
+    await this.checkMutation(table, 'update', existingRow, data);
+  }
+
+  /**
+   * Check if DELETE operation is allowed
+   *
+   * @param table - Table name
+   * @param existingRow - Row to be deleted
+   * @throws RLSPolicyViolation if access is denied
+   *
+   * @example
+   * ```typescript
+   * const guard = new MutationGuard(registry, db);
+   * const existingPost = await db.selectFrom('posts').where('id', '=', 1).selectAll().executeTakeFirst();
+   * await guard.checkDelete('posts', existingPost);
+   * ```
+   */
+  async checkDelete(
+    table: string,
+    existingRow: Record<string, unknown>
+  ): Promise<void> {
+    await this.checkMutation(table, 'delete', existingRow);
+  }
+
+  /**
+   * Check if READ operation is allowed on a specific row
+   *
+   * @param table - Table name
+   * @param row - Row to check access for
+   * @returns true if access is allowed
+   *
+   * @example
+   * ```typescript
+   * const guard = new MutationGuard(registry, db);
+   * const post = await db.selectFrom('posts').where('id', '=', 1).selectAll().executeTakeFirst();
+   * const canRead = await guard.checkRead('posts', post);
+   * ```
+   */
+  async checkRead(
+    table: string,
+    row: Record<string, unknown>
+  ): Promise<boolean> {
+    try {
+      await this.checkMutation(table, 'read', row);
+      return true;
+    } catch (error) {
+      if (error instanceof RLSPolicyViolation) {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Generic check for any operation (helper for testing)
+   *
+   * @param operation - Operation type
+   * @param table - Table name
+   * @param row - Existing row (for UPDATE/DELETE/READ)
+   * @param data - New data (for CREATE/UPDATE)
+   * @returns true if access is allowed, false otherwise
+   */
+  async canMutate(
+    operation: Operation,
+    table: string,
+    row?: Record<string, unknown>,
+    data?: Record<string, unknown>
+  ): Promise<boolean> {
+    try {
+      await this.checkMutation(table, operation, row, data);
+      return true;
+    } catch (error) {
+      if (error instanceof RLSPolicyViolation) {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Validate mutation data (for validate policies)
+   *
+   * @param operation - Operation type
+   * @param table - Table name
+   * @param data - New data (for CREATE/UPDATE)
+   * @param row - Existing row (for UPDATE)
+   * @returns true if valid, false otherwise
+   */
+  async validateMutation(
+    operation: Operation,
+    table: string,
+    data: Record<string, unknown>,
+    row?: Record<string, unknown>
+  ): Promise<boolean> {
+    const ctx = rlsContext.getContextOrNull();
+    if (!ctx) {
+      return false;
+    }
+
+    // System users bypass validation
+    if (ctx.auth.isSystem) {
+      return true;
+    }
+
+    // Check skipFor roles
+    const skipFor = this.registry.getSkipFor(table);
+    if (skipFor.some(role => ctx.auth.roles.includes(role))) {
+      return true;
+    }
+
+    // Get validate policies for this operation
+    const validates = this.registry.getValidates(table, operation);
+    if (validates.length === 0) {
+      return true;
+    }
+
+    // Build evaluation context
+    const evalCtx: PolicyEvaluationContext = {
+      auth: ctx.auth,
+      row: row,
+      data: data,
+      table: table,
+      operation: operation,
+      ...(ctx.meta !== undefined && { meta: ctx.meta as Record<string, unknown> }),
+    };
+
+    // All validate policies must pass
+    for (const validate of validates) {
+      const result = await this.evaluatePolicy(validate.evaluate, evalCtx);
+      if (!result) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Check mutation against RLS policies
+   *
+   * @param table - Table name
+   * @param operation - Operation type
+   * @param row - Existing row (for UPDATE/DELETE/READ)
+   * @param data - New data (for CREATE/UPDATE)
+   * @throws RLSPolicyViolation if access is denied
+   */
+  private async checkMutation(
+    table: string,
+    operation: Operation,
+    row?: Record<string, unknown>,
+    data?: Record<string, unknown>
+  ): Promise<void> {
+    const ctx = rlsContext.getContextOrNull();
+    if (!ctx) {
+      throw new RLSPolicyViolation(
+        operation,
+        table,
+        'No RLS context available'
+      );
+    }
+
+    // System users bypass all checks
+    if (ctx.auth.isSystem) {
+      return;
+    }
+
+    // Check if user role should skip RLS
+    const skipFor = this.registry.getSkipFor(table);
+    if (skipFor.some(role => ctx.auth.roles.includes(role))) {
+      return;
+    }
+
+    // Evaluate deny policies first (they override allows)
+    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);
+
+      if (result) {
+        throw new RLSPolicyViolation(
+          operation,
+          table,
+          `Denied by policy: ${deny.name}`
+        );
+      }
+    }
+
+    // Evaluate validate policies (for CREATE/UPDATE)
+    if ((operation === 'create' || operation === 'update') && data) {
+      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);
+
+        if (!result) {
+          throw new RLSPolicyViolation(
+            operation,
+            table,
+            `Validation failed: ${validate.name}`
+          );
+        }
+      }
+    }
+
+    // Evaluate allow policies
+    const allows = this.registry.getAllows(table, operation);
+    const defaultDeny = this.registry.hasDefaultDeny(table);
+
+    if (defaultDeny && allows.length === 0) {
+      throw new RLSPolicyViolation(
+        operation,
+        table,
+        'No allow policies defined (default deny)'
+      );
+    }
+
+    if (allows.length > 0) {
+      // At least one allow policy must pass
+      let allowed = false;
+
+      for (const allow of allows) {
+        const evalCtx = this.createEvalContext(ctx, table, operation, row, data);
+        const result = await this.evaluatePolicy(allow.evaluate, evalCtx);
+
+        if (result) {
+          allowed = true;
+          break;
+        }
+      }
+
+      if (!allowed) {
+        throw new RLSPolicyViolation(
+          operation,
+          table,
+          'No allow policies matched'
+        );
+      }
+    }
+  }
+
+  /**
+   * Create policy evaluation context
+   */
+  private createEvalContext(
+    ctx: RLSContext,
+    table: string,
+    operation: Operation,
+    row?: Record<string, unknown>,
+    data?: Record<string, unknown>
+  ): PolicyEvaluationContext {
+    return {
+      auth: ctx.auth,
+      row,
+      data,
+      table,
+      operation,
+      metadata: ctx.meta,
+    };
+  }
+
+  /**
+   * Evaluate a policy condition
+   */
+  private async evaluatePolicy(
+    condition: (ctx: PolicyEvaluationContext) => boolean | Promise<boolean>,
+    evalCtx: PolicyEvaluationContext
+  ): 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'}`
+      );
+    }
+  }
+
+  /**
+   * Filter an array of rows, keeping only accessible ones
+   * Useful for post-query filtering when query-level filtering is not possible
+   *
+   * @param table - Table name
+   * @param rows - Array of rows to filter
+   * @returns Filtered array containing only accessible rows
+   *
+   * @example
+   * ```typescript
+   * const guard = new MutationGuard(registry, db);
+   * const allPosts = await db.selectFrom('posts').selectAll().execute();
+   * const accessiblePosts = await guard.filterRows('posts', allPosts);
+   * ```
+   */
+  async filterRows<T extends Record<string, unknown>>(
+    table: string,
+    rows: T[]
+  ): Promise<T[]> {
+    const results: T[] = [];
+
+    for (const row of rows) {
+      if (await this.checkRead(table, row)) {
+        results.push(row);
+      }
+    }
+
+    return results;
+  }
+}

package/src/transformer/select.ts

@@ -0,0 +1,150 @@
+/**
+ * SELECT Query Transformer
+ * Applies filter policies to SELECT queries by adding WHERE conditions
+ */
+
+import type { SelectQueryBuilder } from 'kysely';
+import type { PolicyRegistry } from '../policy/registry.js';
+import type { PolicyEvaluationContext } from '../policy/types.js';
+import type { RLSContext } from '../context/types.js';
+import { rlsContext } from '../context/manager.js';
+import { RLSError, RLSErrorCodes } from '../errors.js';
+
+/**
+ * SELECT query transformer
+ * Applies filter policies to SELECT queries by adding WHERE conditions
+ */
+export class SelectTransformer<DB = unknown> {
+  constructor(private registry: PolicyRegistry<DB>) {}
+
+  /**
+   * Transform a SELECT query by applying filter policies
+   *
+   * @param qb - The query builder to transform
+   * @param table - Table name being queried
+   * @returns Transformed query builder with RLS filters applied
+   *
+   * @example
+   * ```typescript
+   * const transformer = new SelectTransformer(registry);
+   * let query = db.selectFrom('posts').selectAll();
+   * query = transformer.transform(query, 'posts');
+   * // Query now includes WHERE conditions from RLS policies
+   * ```
+   */
+  transform<TB extends keyof DB & string, O>(
+    qb: SelectQueryBuilder<DB, TB, O>,
+    table: string
+  ): SelectQueryBuilder<DB, TB, O> {
+    // Check for context
+    const ctx = rlsContext.getContextOrNull();
+    if (!ctx) {
+      // No context - return original query
+      // In production, you might want to throw an error here
+      return qb;
+    }
+
+    // Check if system user (bypass RLS)
+    if (ctx.auth.isSystem) {
+      return qb;
+    }
+
+    // Check if user role should skip RLS
+    const skipFor = this.registry.getSkipFor(table);
+    if (skipFor.some(role => ctx.auth.roles.includes(role))) {
+      return qb;
+    }
+
+    // Get filter policies for this table
+    const filters = this.registry.getFilters(table);
+    if (filters.length === 0) {
+      return qb;
+    }
+
+    // Apply each filter as WHERE condition
+    let result = qb;
+    for (const filter of filters) {
+      const conditions = this.evaluateFilter(filter, ctx, table);
+      result = this.applyConditions(result, conditions, table);
+    }
+
+    return result;
+  }
+
+  /**
+   * Evaluate a filter policy to get WHERE conditions
+   *
+   * @param filter - The filter policy to evaluate
+   * @param ctx - RLS context
+   * @param table - Table name
+   * @returns WHERE clause conditions as key-value pairs
+   */
+  private evaluateFilter(
+    filter: { name: string; getConditions: (ctx: PolicyEvaluationContext) => Record<string, unknown> | Promise<Record<string, unknown>> },
+    ctx: RLSContext,
+    table: string
+  ): Record<string, unknown> {
+    const evalCtx: PolicyEvaluationContext = {
+      auth: ctx.auth,
+      ...(ctx.meta !== undefined && { meta: ctx.meta as Record<string, unknown> }),
+    };
+
+    const result = filter.getConditions(evalCtx);
+
+    // Note: If async filters are needed, this method signature would need to change
+    // For now, we assume synchronous filter evaluation
+    if (result instanceof Promise) {
+      throw new RLSError(
+        `Async filter policies are not supported in SELECT transformers. ` +
+        `Filter '${filter.name}' on table '${table}' returned a Promise. ` +
+        `Use synchronous conditions for filter policies.`,
+        RLSErrorCodes.RLS_POLICY_INVALID
+      );
+    }
+
+    return result;
+  }
+
+  /**
+   * Apply filter conditions to query builder
+   *
+   * @param qb - Query builder to modify
+   * @param conditions - WHERE clause conditions
+   * @param table - Table name (for qualified column names)
+   * @returns Modified query builder
+   */
+  private applyConditions<TB extends keyof DB & string, O>(
+    qb: SelectQueryBuilder<DB, TB, O>,
+    conditions: Record<string, unknown>,
+    table: string
+  ): SelectQueryBuilder<DB, TB, O> {
+    let result = qb;
+
+    for (const [column, value] of Object.entries(conditions)) {
+      // Use table-qualified column name to avoid ambiguity in joins
+      const qualifiedColumn = `${table}.${column}` as any;
+
+      if (value === null) {
+        // NULL check
+        result = result.where(qualifiedColumn, 'is', null);
+      } else if (value === undefined) {
+        // Skip undefined values
+        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);
+        } else {
+          // IN clause for array values
+          result = result.where(qualifiedColumn, 'in', value as any);
+        }
+      } else {
+        // Equality check
+        result = result.where(qualifiedColumn, '=', value as any);
+      }
+    }
+
+    return result;
+  }
+}

package/src/utils/helpers.ts

@@ -0,0 +1,139 @@
+/**
+ * Utility helper functions for RLS
+ */
+
+import type {
+  RLSContext,
+  PolicyEvaluationContext,
+  Operation,
+} from '../policy/types.js';
+
+/**
+ * Create a policy evaluation context from RLS context
+ */
+export function createEvaluationContext<
+  TRow = unknown,
+  TData = unknown
+>(
+  rlsCtx: RLSContext,
+  options?: {
+    row?: TRow;
+    data?: TData;
+  }
+): PolicyEvaluationContext<unknown, TRow, TData> {
+  const ctx: PolicyEvaluationContext<unknown, TRow, TData> = {
+    auth: rlsCtx.auth,
+  };
+
+  if (options?.row !== undefined) {
+    ctx.row = options.row;
+  }
+
+  if (options?.data !== undefined) {
+    ctx.data = options.data;
+  }
+
+  if (rlsCtx.request !== undefined) {
+    ctx.request = rlsCtx.request;
+  }
+
+  if (rlsCtx.meta !== undefined) {
+    ctx.meta = rlsCtx.meta as Record<string, unknown>;
+  }
+
+  return ctx;
+}
+
+/**
+ * Check if a condition function is async
+ */
+export function isAsyncFunction(fn: unknown): fn is (...args: unknown[]) => Promise<unknown> {
+  return fn instanceof Function && fn.constructor.name === 'AsyncFunction';
+}
+
+/**
+ * Safely evaluate a policy condition
+ */
+export async function safeEvaluate<T>(
+  fn: () => T | Promise<T>,
+  defaultValue: T
+): Promise<T> {
+  try {
+    const result = fn();
+    if (result instanceof Promise) {
+      return await result;
+    }
+    return result;
+  } catch (error) {
+    // Expected failure during policy evaluation - return default value
+    // Logger not available in this utility function, error is handled gracefully
+    return defaultValue;
+  }
+}
+
+/**
+ * Deep merge two objects
+ */
+export function deepMerge<T extends Record<string, unknown>>(
+  target: T,
+  source: Partial<T>
+): T {
+  const result = { ...target };
+
+  for (const key of Object.keys(source) as (keyof T)[]) {
+    const sourceValue = source[key];
+    const targetValue = result[key];
+
+    if (
+      sourceValue !== undefined &&
+      typeof sourceValue === 'object' &&
+      sourceValue !== null &&
+      !Array.isArray(sourceValue) &&
+      typeof targetValue === 'object' &&
+      targetValue !== null &&
+      !Array.isArray(targetValue)
+    ) {
+      result[key] = deepMerge(
+        targetValue as Record<string, unknown>,
+        sourceValue as Record<string, unknown>
+      ) as T[keyof T];
+    } else if (sourceValue !== undefined) {
+      result[key] = sourceValue as T[keyof T];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Create a simple hash for cache keys
+ */
+export function hashString(str: string): string {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash; // Convert to 32bit integer
+  }
+  return hash.toString(36);
+}
+
+/**
+ * Normalize operations to array format
+ */
+export function normalizeOperations(
+  operation: Operation | Operation[]
+): Operation[] {
+  if (Array.isArray(operation)) {
+    if (operation.includes('all')) {
+      return ['read', 'create', 'update', 'delete'];
+    }
+    return operation;
+  }
+
+  if (operation === 'all') {
+    return ['read', 'create', 'update', 'delete'];
+  }
+
+  return [operation];
+}

package/src/utils/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility functions for RLS
+ */
+
+export {
+  createEvaluationContext,
+  isAsyncFunction,
+  safeEvaluate,
+  deepMerge,
+  hashString,
+  normalizeOperations,
+} from './helpers.js';