@kysera/rls 0.5.1

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@kysera/rls",
+  "version": "0.5.1",
+  "description": "Row-Level Security plugin for Kysera ORM - declarative policies, query transformation, native RLS support",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./native": {
+      "types": "./dist/native/index.d.ts",
+      "import": "./dist/native/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "kysely": ">=0.28.8"
+  },
+  "dependencies": {
+    "zod": "^4.1.13",
+    "@kysera/core": "0.5.1",
+    "@kysera/repository": "0.5.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^24.10.1",
+    "@types/pg": "^8.15.6",
+    "@vitest/coverage-v8": "^4.0.15",
+    "better-sqlite3": "^12.5.0",
+    "kysely": "^0.28.8",
+    "mysql2": "^3.15.2",
+    "pg": "^8.16.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "keywords": [
+    "kysely",
+    "orm",
+    "database",
+    "typescript",
+    "sql",
+    "rls",
+    "row-level-security",
+    "authorization",
+    "access-control",
+    "postgres",
+    "mysql",
+    "sqlite"
+  ],
+  "author": "Kysera Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kysera-dev/kysera.git",
+    "directory": "packages/kysera-rls"
+  },
+  "bugs": {
+    "url": "https://github.com/kysera-dev/kysera/issues"
+  },
+  "homepage": "https://github.com/kysera-dev/kysera#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "test:postgres": "TEST_POSTGRES=true vitest run test/integration",
+    "test:mysql": "TEST_MYSQL=true vitest run test/integration",
+    "test:all-dbs": "TEST_POSTGRES=true TEST_MYSQL=true vitest run test/integration",
+    "docker:up": "docker compose -f test/docker/docker-compose.test.yml up -d",
+    "docker:down": "docker compose -f test/docker/docker-compose.test.yml down -v",
+    "docker:logs": "docker compose -f test/docker/docker-compose.test.yml logs -f",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}

package/src/context/index.ts

@@ -0,0 +1,9 @@
+export { rlsStorage } from './storage.js';
+export {
+  rlsContext,
+  createRLSContext,
+  withRLSContext,
+  withRLSContextAsync,
+  type CreateRLSContextOptions,
+} from './manager.js';
+export type { RLSContext, RLSAuthContext, RLSRequestContext } from './types.js';

package/src/context/manager.ts

@@ -0,0 +1,203 @@
+import { rlsStorage } from './storage.js';
+import type { RLSContext, RLSAuthContext, RLSRequestContext } from './types.js';
+import { RLSContextError, RLSContextValidationError } from '../errors.js';
+
+/**
+ * Options for creating RLS context
+ */
+export interface CreateRLSContextOptions<TUser = unknown, TMeta = unknown> {
+  auth: RLSAuthContext<TUser>;
+  request?: Partial<RLSRequestContext>;
+  meta?: TMeta;
+}
+
+/**
+ * Create a new RLS context
+ */
+export function createRLSContext<TUser = unknown, TMeta = unknown>(
+  options: CreateRLSContextOptions<TUser, TMeta>
+): RLSContext<TUser, TMeta> {
+  validateAuthContext(options.auth);
+
+  const context: RLSContext<TUser, TMeta> = {
+    auth: {
+      ...options.auth,
+      isSystem: options.auth.isSystem ?? false, // Default to false if not provided
+    },
+    timestamp: new Date(),
+  };
+
+  if (options.request) {
+    context.request = {
+      ...options.request,
+      timestamp: options.request.timestamp ?? new Date(),
+    } as RLSRequestContext;
+  }
+
+  if (options.meta !== undefined) {
+    context.meta = options.meta;
+  }
+
+  return context;
+}
+
+/**
+ * Validate auth context
+ */
+function validateAuthContext(auth: RLSAuthContext): void {
+  if (auth.userId === undefined || auth.userId === null) {
+    throw new RLSContextValidationError('userId is required in auth context', 'userId');
+  }
+
+  if (!Array.isArray(auth.roles)) {
+    throw new RLSContextValidationError('roles must be an array', 'roles');
+  }
+}
+
+/**
+ * RLS Context Manager
+ * Manages RLS context using AsyncLocalStorage for automatic propagation
+ */
+class RLSContextManager {
+  /**
+   * Run a synchronous function within an RLS context
+   */
+  run<T>(context: RLSContext, fn: () => T): T {
+    return rlsStorage.run(context, fn);
+  }
+
+  /**
+   * Run an async function within an RLS context
+   */
+  async runAsync<T>(context: RLSContext, fn: () => Promise<T>): Promise<T> {
+    return rlsStorage.run(context, fn);
+  }
+
+  /**
+   * Get current RLS context
+   * @throws RLSContextError if no context is set
+   */
+  getContext(): RLSContext {
+    const ctx = rlsStorage.getStore();
+    if (!ctx) {
+      throw new RLSContextError();
+    }
+    return ctx;
+  }
+
+  /**
+   * Get current RLS context or null if not set
+   */
+  getContextOrNull(): RLSContext | null {
+    return rlsStorage.getStore() ?? null;
+  }
+
+  /**
+   * Check if running within RLS context
+   */
+  hasContext(): boolean {
+    return rlsStorage.getStore() !== undefined;
+  }
+
+  /**
+   * Get current auth context
+   * @throws RLSContextError if no context is set
+   */
+  getAuth(): RLSAuthContext {
+    return this.getContext().auth;
+  }
+
+  /**
+   * Get current user ID
+   * @throws RLSContextError if no context is set
+   */
+  getUserId(): string | number {
+    return this.getAuth().userId;
+  }
+
+  /**
+   * Get current tenant ID
+   * @throws RLSContextError if no context is set
+   */
+  getTenantId(): string | number | undefined {
+    return this.getAuth().tenantId;
+  }
+
+  /**
+   * Check if current user has a specific role
+   */
+  hasRole(role: string): boolean {
+    const ctx = this.getContextOrNull();
+    return ctx?.auth.roles.includes(role) ?? false;
+  }
+
+  /**
+   * Check if current user has a specific permission
+   */
+  hasPermission(permission: string): boolean {
+    const ctx = this.getContextOrNull();
+    return ctx?.auth.permissions?.includes(permission) ?? false;
+  }
+
+  /**
+   * Check if current context is a system context (bypasses RLS)
+   */
+  isSystem(): boolean {
+    const ctx = this.getContextOrNull();
+    return ctx?.auth.isSystem ?? false;
+  }
+
+  /**
+   * Create a system context for operations that should bypass RLS
+   */
+  asSystem<T>(fn: () => T): T {
+    const currentCtx = this.getContextOrNull();
+    if (!currentCtx) {
+      throw new RLSContextError('Cannot create system context without existing context');
+    }
+
+    const systemCtx: RLSContext = {
+      ...currentCtx,
+      auth: { ...currentCtx.auth, isSystem: true },
+    };
+
+    return this.run(systemCtx, fn);
+  }
+
+  /**
+   * Create a system context for async operations
+   */
+  async asSystemAsync<T>(fn: () => Promise<T>): Promise<T> {
+    const currentCtx = this.getContextOrNull();
+    if (!currentCtx) {
+      throw new RLSContextError('Cannot create system context without existing context');
+    }
+
+    const systemCtx: RLSContext = {
+      ...currentCtx,
+      auth: { ...currentCtx.auth, isSystem: true },
+    };
+
+    return this.runAsync(systemCtx, fn);
+  }
+}
+
+// Export singleton instance
+export const rlsContext = new RLSContextManager();
+
+/**
+ * Convenience function to run code within RLS context
+ */
+export function withRLSContext<T>(context: RLSContext, fn: () => T): T {
+  return rlsContext.run(context, fn);
+}
+
+/**
+ * Convenience function to run async code within RLS context
+ */
+export async function withRLSContextAsync<T>(
+  context: RLSContext,
+  fn: () => Promise<T>
+): Promise<T> {
+  return rlsContext.runAsync(context, fn);
+}

package/src/context/storage.ts

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { RLSContext } from './types.js';
+
+/**
+ * AsyncLocalStorage instance for RLS context
+ * Provides automatic context propagation across async boundaries
+ */
+export const rlsStorage = new AsyncLocalStorage<RLSContext>();

package/src/context/types.ts

@@ -0,0 +1,5 @@
+export type {
+  RLSContext,
+  RLSAuthContext,
+  RLSRequestContext,
+} from '../policy/types.js';

package/src/errors.ts

@@ -0,0 +1,280 @@
+/**
+ * RLS Error Classes
+ *
+ * This module provides specialized error classes for Row-Level Security operations.
+ * All errors extend the base RLSError class and use unified error codes from @kysera/core
+ * for consistency across the Kysera ecosystem.
+ *
+ * @module @kysera/rls/errors
+ */
+
+import type { ErrorCode } from '@kysera/core';
+
+// ============================================================================
+// RLS Error Codes
+// ============================================================================
+
+/**
+ * RLS-specific error codes
+ *
+ * These codes extend the unified error codes from @kysera/core with
+ * RLS-specific error conditions.
+ */
+export const RLSErrorCodes = {
+  /** RLS context is missing or not set */
+  RLS_CONTEXT_MISSING: 'RLS_CONTEXT_MISSING' as ErrorCode,
+  /** RLS policy violation occurred */
+  RLS_POLICY_VIOLATION: 'RLS_POLICY_VIOLATION' as ErrorCode,
+  /** RLS policy definition is invalid */
+  RLS_POLICY_INVALID: 'RLS_POLICY_INVALID' as ErrorCode,
+  /** RLS schema definition is invalid */
+  RLS_SCHEMA_INVALID: 'RLS_SCHEMA_INVALID' as ErrorCode,
+  /** RLS context validation failed */
+  RLS_CONTEXT_INVALID: 'RLS_CONTEXT_INVALID' as ErrorCode,
+} as const;
+
+/**
+ * Type for RLS error codes
+ */
+export type RLSErrorCode = typeof RLSErrorCodes[keyof typeof RLSErrorCodes];
+
+// ============================================================================
+// Base RLS Error
+// ============================================================================
+
+/**
+ * Base class for all RLS-related errors
+ *
+ * Provides common error functionality including error codes and JSON serialization.
+ *
+ * @example
+ * ```typescript
+ * throw new RLSError('Something went wrong', RLSErrorCodes.RLS_POLICY_INVALID);
+ * ```
+ */
+export class RLSError extends Error {
+  public readonly code: RLSErrorCode;
+
+  /**
+   * Creates a new RLS error
+   *
+   * @param message - Error message
+   * @param code - RLS error code
+   */
+  constructor(message: string, code: RLSErrorCode) {
+    super(message);
+    this.name = 'RLSError';
+    this.code = code;
+  }
+
+  /**
+   * Serializes the error to JSON
+   *
+   * @returns JSON representation of the error
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+    };
+  }
+}
+
+// ============================================================================
+// Context Errors
+// ============================================================================
+
+/**
+ * Error thrown when RLS context is missing
+ *
+ * This error occurs when an operation requiring RLS context is executed
+ * outside of a context scope (i.e., without calling withRLSContext()).
+ *
+ * @example
+ * ```typescript
+ * // This will throw RLSContextError
+ * const result = await db.selectFrom('posts').execute();
+ *
+ * // Correct usage with context
+ * await withRLSContext(rlsContext, async () => {
+ *   const result = await db.selectFrom('posts').execute();
+ * });
+ * ```
+ */
+export class RLSContextError extends RLSError {
+  /**
+   * Creates a new RLS context error
+   *
+   * @param message - Error message (defaults to standard message)
+   */
+  constructor(message: string = 'No RLS context found. Ensure code runs within withRLSContext()') {
+    super(message, RLSErrorCodes.RLS_CONTEXT_MISSING);
+    this.name = 'RLSContextError';
+  }
+}
+
+/**
+ * Error thrown when RLS context validation fails
+ *
+ * This error occurs when the provided RLS context is invalid or missing
+ * required fields.
+ *
+ * @example
+ * ```typescript
+ * // Missing required userId field
+ * const invalidContext = {
+ *   auth: {
+ *     roles: ['user']
+ *     // userId is missing!
+ *   },
+ *   timestamp: new Date()
+ * };
+ *
+ * // This will throw RLSContextValidationError
+ * validateRLSContext(invalidContext);
+ * ```
+ */
+export class RLSContextValidationError extends RLSError {
+  public readonly field: string;
+
+  /**
+   * Creates a new context validation error
+   *
+   * @param message - Error message
+   * @param field - Field that failed validation
+   */
+  constructor(message: string, field: string) {
+    super(message, RLSErrorCodes.RLS_CONTEXT_INVALID);
+    this.name = 'RLSContextValidationError';
+    this.field = field;
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return {
+      ...super.toJSON(),
+      field: this.field,
+    };
+  }
+}
+
+// ============================================================================
+// Policy Errors
+// ============================================================================
+
+/**
+ * Error thrown when an RLS policy violation occurs
+ *
+ * This error is thrown when a database operation is denied by RLS policies.
+ * It provides detailed information about the violation including the operation,
+ * table, and reason for denial.
+ *
+ * @example
+ * ```typescript
+ * // User tries to update a post they don't own
+ * throw new RLSPolicyViolation(
+ *   'update',
+ *   'posts',
+ *   'User does not own this post',
+ *   'ownership_policy'
+ * );
+ * ```
+ */
+export class RLSPolicyViolation extends RLSError {
+  public readonly operation: string;
+  public readonly table: string;
+  public readonly reason: string;
+  public readonly policyName?: string;
+
+  /**
+   * Creates a new policy violation error
+   *
+   * @param operation - Database operation that was denied (read, create, update, delete)
+   * @param table - Table name where violation occurred
+   * @param reason - Reason for the policy violation
+   * @param policyName - Name of the policy that denied access (optional)
+   */
+  constructor(
+    operation: string,
+    table: string,
+    reason: string,
+    policyName?: string
+  ) {
+    super(
+      `RLS policy violation: ${operation} on ${table} - ${reason}`,
+      RLSErrorCodes.RLS_POLICY_VIOLATION
+    );
+    this.name = 'RLSPolicyViolation';
+    this.operation = operation;
+    this.table = table;
+    this.reason = reason;
+    if (policyName !== undefined) {
+      this.policyName = policyName;
+    }
+  }
+
+  override toJSON(): Record<string, unknown> {
+    const json: Record<string, unknown> = {
+      ...super.toJSON(),
+      operation: this.operation,
+      table: this.table,
+      reason: this.reason,
+    };
+    if (this.policyName !== undefined) {
+      json['policyName'] = this.policyName;
+    }
+    return json;
+  }
+}
+
+// ============================================================================
+// Schema Errors
+// ============================================================================
+
+/**
+ * Error thrown when RLS schema validation fails
+ *
+ * This error occurs when the RLS schema definition is invalid or contains
+ * configuration errors.
+ *
+ * @example
+ * ```typescript
+ * // Invalid policy definition
+ * const invalidSchema = {
+ *   posts: {
+ *     policies: [
+ *       {
+ *         type: 'invalid-type', // Invalid policy type!
+ *         operation: 'read',
+ *         condition: (ctx) => true
+ *       }
+ *     ]
+ *   }
+ * };
+ *
+ * // This will throw RLSSchemaError
+ * validateRLSSchema(invalidSchema);
+ * ```
+ */
+export class RLSSchemaError extends RLSError {
+  public readonly details: Record<string, unknown>;
+
+  /**
+   * Creates a new schema validation error
+   *
+   * @param message - Error message
+   * @param details - Additional details about the validation failure
+   */
+  constructor(message: string, details: Record<string, unknown> = {}) {
+    super(message, RLSErrorCodes.RLS_SCHEMA_INVALID);
+    this.name = 'RLSSchemaError';
+    this.details = details;
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return {
+      ...super.toJSON(),
+      details: this.details,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+/**
+ * @kysera/rls - Row-Level Security Plugin for Kysera ORM
+ *
+ * Provides declarative policy definition, automatic query transformation,
+ * and optional native PostgreSQL RLS generation.
+ *
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Policy Definition
+// ============================================================================
+
+// Schema definition
+export { defineRLSSchema, mergeRLSSchemas } from './policy/schema.js';
+
+// Policy builders
+export { allow, deny, filter, validate, type PolicyOptions } from './policy/builder.js';
+
+// Policy registry (for advanced use cases)
+export { PolicyRegistry } from './policy/registry.js';
+
+// ============================================================================
+// Plugin
+// ============================================================================
+
+export { rlsPlugin } from './plugin.js';
+export type { RLSPluginOptions } from './plugin.js';
+
+// ============================================================================
+// Context Management
+// ============================================================================
+
+export {
+  rlsContext,
+  createRLSContext,
+  withRLSContext,
+  withRLSContextAsync,
+  type CreateRLSContextOptions,
+} from './context/index.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type {
+  // Core types
+  Operation,
+  PolicyType,
+  PolicyDefinition,
+  PolicyCondition,
+  FilterCondition,
+  PolicyHints,
+
+  // Schema types
+  RLSSchema,
+  TableRLSConfig,
+
+  // Context types
+  RLSContext,
+  RLSAuthContext,
+  RLSRequestContext,
+
+  // Evaluation types
+  PolicyEvaluationContext,
+  CompiledPolicy,
+  CompiledFilterPolicy,
+} from './policy/types.js';
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+export {
+  RLSError,
+  RLSContextError,
+  RLSPolicyViolation,
+  RLSSchemaError,
+  RLSContextValidationError,
+  RLSErrorCodes,
+  type RLSErrorCode,
+} from './errors.js';
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+export {
+  createEvaluationContext,
+  normalizeOperations,
+  isAsyncFunction,
+  safeEvaluate,
+  deepMerge,
+  hashString,
+} from './utils/index.js';