@kysera/rls 0.5.1

package/src/native/README.md

@@ -0,0 +1,315 @@
+# Native PostgreSQL RLS Generation
+
+This module provides native PostgreSQL Row-Level Security (RLS) policy generation from Kysera RLS schemas.
+
+## Features
+
+- **PostgreSQL RLS Generation**: Convert Kysera RLS schemas to native PostgreSQL `CREATE POLICY` statements
+- **Context Functions**: Generate STABLE PostgreSQL functions for RLS context (optimized for query planner)
+- **Migration Support**: Generate Kysely migration files with up/down support
+- **Session Management**: Utilities to sync RLS context to PostgreSQL session variables
+
+## Usage
+
+### 1. Define RLS Schema with Native PostgreSQL Support
+
+```typescript
+import type { RLSSchema } from '@kysera/rls';
+
+interface Database {
+  users: {
+    id: number;
+    email: string;
+    tenant_id: string;
+  };
+}
+
+const rlsSchema: RLSSchema<Database> = {
+  users: {
+    policies: [
+      {
+        type: 'allow',
+        operation: 'read',
+        name: 'users_read_own',
+        condition: () => true, // ORM-side condition
+        using: 'id = rls_current_user_id()::integer', // Native PostgreSQL
+        role: 'authenticated',
+      },
+    ],
+  },
+};
+```
+
+### 2. Generate PostgreSQL Statements
+
+```typescript
+import { PostgresRLSGenerator } from '@kysera/rls/native';
+
+const generator = new PostgresRLSGenerator();
+
+// Generate RLS policies
+const statements = generator.generateStatements(rlsSchema, {
+  schemaName: 'public',
+  policyPrefix: 'app_rls',
+  force: true, // Force RLS on table owners
+});
+
+// Generate context functions
+const contextFunctions = generator.generateContextFunctions();
+
+// Generate cleanup statements
+const dropStatements = generator.generateDropStatements(rlsSchema, {
+  schemaName: 'public',
+  policyPrefix: 'app_rls',
+});
+```
+
+### 3. Generate Kysely Migration
+
+```typescript
+import { RLSMigrationGenerator } from '@kysera/rls/native';
+
+const migrationGenerator = new RLSMigrationGenerator();
+
+const migrationContent = migrationGenerator.generateMigration(rlsSchema, {
+  name: 'setup_rls',
+  schemaName: 'public',
+  policyPrefix: 'app_rls',
+  includeContextFunctions: true,
+  force: true,
+});
+
+// Get suggested filename with timestamp
+const filename = migrationGenerator.generateFilename('setup_rls');
+// Example: 20231208_123456_setup_rls.ts
+
+// Write to migrations directory
+import fs from 'fs';
+fs.writeFileSync(`migrations/${filename}`, migrationContent);
+```
+
+### 4. Sync Context to PostgreSQL Session
+
+```typescript
+import { syncContextToPostgres, clearPostgresContext } from '@kysera/rls/native';
+import { Kysely } from 'kysely';
+
+const db = new Kysely<Database>({ ... });
+
+// At the start of each request/transaction
+await syncContextToPostgres(db, {
+  userId: 123,
+  tenantId: 'tenant-uuid',
+  roles: ['user', 'admin'],
+  permissions: ['read:posts', 'write:posts'],
+  isSystem: false,
+});
+
+// Execute queries - RLS policies will be enforced
+const users = await db.selectFrom('users').selectAll().execute();
+
+// Clear context when done (optional, resets on connection close)
+await clearPostgresContext(db);
+```
+
+## Policy Definition
+
+### Native RLS Fields
+
+Extend your Kysera policy definitions with native PostgreSQL support:
+
+```typescript
+{
+  type: 'allow' | 'deny',        // 'deny' becomes RESTRICTIVE policy
+  operation: Operation | Operation[],
+  condition: () => true,          // ORM-side evaluation
+
+  // Native PostgreSQL RLS fields:
+  using?: string,                 // USING clause (for SELECT/UPDATE/DELETE)
+  withCheck?: string,             // WITH CHECK clause (for INSERT/UPDATE)
+  role?: string,                  // Target role (default: 'public')
+  name?: string,                  // Policy name
+}
+```
+
+### Policy Types
+
+- **`allow`**: Maps to `AS PERMISSIVE` policy
+- **`deny`**: Maps to `AS RESTRICTIVE` policy (takes precedence)
+- **`filter`**: ORM-only, not generated as native RLS
+- **`validate`**: ORM-only, not generated as native RLS
+
+### Operations
+
+| Kysera | PostgreSQL |
+|--------|------------|
+| `read` | `SELECT` |
+| `create` | `INSERT` |
+| `update` | `UPDATE` |
+| `delete` | `DELETE` |
+| `all` | `ALL` |
+
+## Context Functions
+
+The generator creates these STABLE PostgreSQL functions for optimal performance:
+
+```sql
+-- Get current user ID
+rls_current_user_id() -> text
+
+-- Get current tenant ID
+rls_current_tenant_id() -> uuid
+
+-- Get current user roles
+rls_current_roles() -> text[]
+
+-- Check if user has role
+rls_has_role(role_name text) -> boolean
+
+-- Get current permissions
+rls_current_permissions() -> text[]
+
+-- Check if user has permission
+rls_has_permission(permission_name text) -> boolean
+
+-- Check if this is a system account
+rls_is_system() -> boolean
+```
+
+These functions read from PostgreSQL session variables set by `syncContextToPostgres()`.
+
+## Examples
+
+### Multi-Tenant Application
+
+```typescript
+const rlsSchema: RLSSchema<Database> = {
+  posts: {
+    policies: [
+      {
+        type: 'allow',
+        operation: 'read',
+        name: 'posts_read_tenant',
+        condition: () => true,
+        using: 'tenant_id = rls_current_tenant_id()',
+        role: 'authenticated',
+      },
+      {
+        type: 'allow',
+        operation: 'create',
+        name: 'posts_create_own',
+        condition: () => true,
+        withCheck: 'user_id = rls_current_user_id()::integer AND tenant_id = rls_current_tenant_id()',
+        role: 'authenticated',
+      },
+    ],
+    defaultDeny: true,
+  },
+};
+```
+
+### Role-Based Access Control
+
+```typescript
+const rlsSchema: RLSSchema<Database> = {
+  admin_settings: {
+    policies: [
+      {
+        type: 'allow',
+        operation: 'all',
+        name: 'admin_full_access',
+        condition: () => true,
+        using: 'rls_has_role(\'admin\')',
+        role: 'authenticated',
+      },
+      {
+        type: 'deny',
+        operation: 'all',
+        name: 'deny_non_admin',
+        condition: () => true,
+        using: 'NOT rls_has_role(\'admin\')',
+        role: 'authenticated',
+      },
+    ],
+    defaultDeny: true,
+  },
+};
+```
+
+### System Bypass
+
+```typescript
+{
+  type: 'allow',
+  operation: 'all',
+  name: 'system_bypass',
+  condition: () => true,
+  using: 'rls_is_system()',
+  role: 'authenticated',
+}
+```
+
+## Performance Considerations
+
+1. **STABLE Functions**: All context functions are marked as `STABLE`, allowing PostgreSQL's query planner to optimize policy evaluation.
+
+2. **Session Variables**: Context is stored in PostgreSQL session variables (`set_config`) for fast access without database lookups.
+
+3. **Policy Ordering**: Policies run in order of priority (higher first). Deny policies have default priority 100.
+
+4. **Index Support**: Create indexes on columns used in RLS policies for better performance:
+
+```sql
+CREATE INDEX idx_posts_tenant ON posts(tenant_id);
+CREATE INDEX idx_posts_user ON posts(user_id);
+```
+
+## Migration Workflow
+
+1. **Generate Migration**:
+   ```bash
+   npx tsx -e "import { RLSMigrationGenerator } from './src/native'; ..."
+   ```
+
+2. **Review Generated SQL**: Check migration file before applying
+
+3. **Run Migration**:
+   ```bash
+   npx kysely migrate:latest
+   ```
+
+4. **Test Policies**: Verify RLS policies work as expected
+
+5. **Rollback if Needed**:
+   ```bash
+   npx kysely migrate:down
+   ```
+
+## API Reference
+
+### `PostgresRLSGenerator`
+
+#### Methods
+
+- `generateStatements(schema, options)`: Generate RLS policy statements
+- `generateContextFunctions()`: Generate context function SQL
+- `generateDropStatements(schema, options)`: Generate cleanup statements
+
+### `RLSMigrationGenerator`
+
+#### Methods
+
+- `generateMigration(schema, options)`: Generate Kysely migration file content
+- `generateFilename(name)`: Generate timestamped migration filename
+
+### `syncContextToPostgres(db, context)`
+
+Sync RLS context to PostgreSQL session variables.
+
+### `clearPostgresContext(db)`
+
+Clear RLS context from PostgreSQL session.
+
+## License
+
+MIT

package/src/native/index.ts

@@ -0,0 +1,11 @@
+export {
+  PostgresRLSGenerator,
+  syncContextToPostgres,
+  clearPostgresContext,
+  type PostgresRLSOptions,
+} from './postgres.js';
+
+export {
+  RLSMigrationGenerator,
+  type MigrationOptions,
+} from './migration.js';

package/src/native/migration.ts

@@ -0,0 +1,92 @@
+import type { RLSSchema } from '../policy/types.js';
+import { PostgresRLSGenerator, type PostgresRLSOptions } from './postgres.js';
+
+/**
+ * Options for migration generation
+ */
+export interface MigrationOptions extends PostgresRLSOptions {
+  /** Migration name */
+  name?: string;
+  /** Include context functions in migration */
+  includeContextFunctions?: boolean;
+}
+
+/**
+ * RLS Migration Generator
+ * Generates Kysely migration files for RLS policies
+ */
+export class RLSMigrationGenerator {
+  private generator = new PostgresRLSGenerator();
+
+  /**
+   * Generate migration file content
+   */
+  generateMigration<DB>(
+    schema: RLSSchema<DB>,
+    options: MigrationOptions = {}
+  ): string {
+    const {
+      name = 'rls_policies',
+      includeContextFunctions = true,
+      ...generatorOptions
+    } = options;
+
+    const upStatements = this.generator.generateStatements(schema, generatorOptions);
+    const downStatements = this.generator.generateDropStatements(schema, generatorOptions);
+
+    const contextFunctions = includeContextFunctions
+      ? this.generator.generateContextFunctions()
+      : '';
+
+    return `import { Kysely, sql } from 'kysely';
+
+/**
+ * Migration: ${name}
+ * Generated by @kysera/rls
+ *
+ * This migration sets up Row-Level Security policies for the database.
+ */
+
+export async function up(db: Kysely<any>): Promise<void> {
+${includeContextFunctions ? `  // Create RLS context functions
+  await sql.raw(\`${this.escapeTemplate(contextFunctions)}\`).execute(db);
+
+` : ''}  // Enable RLS and create policies
+${upStatements.map(s => `  await sql.raw(\`${this.escapeTemplate(s)}\`).execute(db);`).join('\n')}
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+${downStatements.map(s => `  await sql.raw(\`${this.escapeTemplate(s)}\`).execute(db);`).join('\n')}
+${includeContextFunctions ? `
+  // Drop RLS context functions
+  await sql.raw(\`
+    DROP FUNCTION IF EXISTS rls_current_user_id();
+    DROP FUNCTION IF EXISTS rls_current_tenant_id();
+    DROP FUNCTION IF EXISTS rls_current_roles();
+    DROP FUNCTION IF EXISTS rls_has_role(text);
+    DROP FUNCTION IF EXISTS rls_current_permissions();
+    DROP FUNCTION IF EXISTS rls_has_permission(text);
+    DROP FUNCTION IF EXISTS rls_is_system();
+  \`).execute(db);` : ''}
+}
+`;
+  }
+
+  /**
+   * Escape template literal for embedding in string
+   */
+  private escapeTemplate(str: string): string {
+    return str.replace(/`/g, '\\`').replace(/\$/g, '\\$');
+  }
+
+  /**
+   * Generate migration filename with timestamp
+   */
+  generateFilename(name: string = 'rls_policies'): string {
+    const timestamp = new Date().toISOString()
+      .replace(/[-:]/g, '')
+      .replace('T', '_')
+      .replace(/\..+/, '');
+    return `${timestamp}_${name}.ts`;
+  }
+}

package/src/native/postgres.ts

@@ -0,0 +1,263 @@
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import type { RLSSchema, TableRLSConfig, PolicyDefinition, Operation } from '../policy/types.js';
+
+/**
+ * Options for PostgreSQL RLS generation
+ */
+export interface PostgresRLSOptions {
+  /** Force RLS on table owners */
+  force?: boolean;
+  /** Schema name (default: public) */
+  schemaName?: string;
+  /** Prefix for generated policy names */
+  policyPrefix?: string;
+}
+
+/**
+ * PostgreSQL RLS Generator
+ * Generates native PostgreSQL RLS statements from Kysera RLS schema
+ */
+export class PostgresRLSGenerator {
+  /**
+   * Generate all PostgreSQL RLS statements from schema
+   */
+  generateStatements<DB>(
+    schema: RLSSchema<DB>,
+    options: PostgresRLSOptions = {}
+  ): string[] {
+    const {
+      force = true,
+      schemaName = 'public',
+      policyPrefix = 'rls',
+    } = options;
+
+    const statements: string[] = [];
+
+    for (const [table, config] of Object.entries(schema)) {
+      if (!config) continue;
+
+      const qualifiedTable = `${schemaName}.${table}`;
+      const tableConfig = config as TableRLSConfig;
+
+      // Enable RLS on table
+      statements.push(`ALTER TABLE ${qualifiedTable} ENABLE ROW LEVEL SECURITY;`);
+
+      if (force) {
+        statements.push(`ALTER TABLE ${qualifiedTable} FORCE ROW LEVEL SECURITY;`);
+      }
+
+      // Generate policies
+      let policyIndex = 0;
+      for (const policy of tableConfig.policies) {
+        const policyName = policy.name ?? `${policyPrefix}_${table}_${policy.type}_${policyIndex++}`;
+        const policySQL = this.generatePolicy(qualifiedTable, policyName, policy);
+        if (policySQL) {
+          statements.push(policySQL);
+        }
+      }
+    }
+
+    return statements;
+  }
+
+  /**
+   * Generate a single policy statement
+   */
+  private generatePolicy(
+    table: string,
+    name: string,
+    policy: PolicyDefinition
+  ): string | null {
+    // Skip filter policies (they're ORM-only)
+    if (policy.type === 'filter' || policy.type === 'validate') {
+      return null;
+    }
+
+    // Need USING or WITH CHECK clause for native RLS
+    if (!policy.using && !policy.withCheck) {
+      return null;
+    }
+
+    const parts: string[] = [
+      `CREATE POLICY "${name}"`,
+      `ON ${table}`,
+    ];
+
+    // Policy type
+    if (policy.type === 'deny') {
+      parts.push('AS RESTRICTIVE');
+    } else {
+      parts.push('AS PERMISSIVE');
+    }
+
+    // Target role
+    parts.push(`TO ${policy.role ?? 'public'}`);
+
+    // Operation
+    parts.push(`FOR ${this.mapOperation(policy.operation)}`);
+
+    // USING clause
+    if (policy.using) {
+      parts.push(`USING (${policy.using})`);
+    }
+
+    // WITH CHECK clause
+    if (policy.withCheck) {
+      parts.push(`WITH CHECK (${policy.withCheck})`);
+    }
+
+    return parts.join('\n  ') + ';';
+  }
+
+  /**
+   * Map Kysera operation to PostgreSQL operation
+   */
+  private mapOperation(operation: Operation | Operation[]): string {
+    if (Array.isArray(operation)) {
+      if (operation.length === 0) {
+        return 'ALL';
+      }
+      if (operation.length === 4 || operation.includes('all')) {
+        return 'ALL';
+      }
+      // PostgreSQL doesn't support multiple operations in one policy
+      // Return first operation
+      return this.mapSingleOperation(operation[0]!);
+    }
+    return this.mapSingleOperation(operation);
+  }
+
+  /**
+   * Map single operation
+   */
+  private mapSingleOperation(op: Operation): string {
+    switch (op) {
+      case 'read': return 'SELECT';
+      case 'create': return 'INSERT';
+      case 'update': return 'UPDATE';
+      case 'delete': return 'DELETE';
+      case 'all': return 'ALL';
+      default: return 'ALL';
+    }
+  }
+
+  /**
+   * Generate context-setting functions for PostgreSQL
+   * These functions should be STABLE for optimal performance
+   */
+  generateContextFunctions(): string {
+    return `
+-- RLS Context Functions (STABLE for query planner optimization)
+-- These functions read session variables set by the application
+
+CREATE OR REPLACE FUNCTION rls_current_user_id()
+RETURNS text
+LANGUAGE SQL STABLE
+AS $$ SELECT current_setting('app.user_id', true) $$;
+
+CREATE OR REPLACE FUNCTION rls_current_tenant_id()
+RETURNS uuid
+LANGUAGE SQL STABLE
+AS $$ SELECT NULLIF(current_setting('app.tenant_id', true), '')::uuid $$;
+
+CREATE OR REPLACE FUNCTION rls_current_roles()
+RETURNS text[]
+LANGUAGE SQL STABLE
+AS $$ SELECT string_to_array(COALESCE(current_setting('app.roles', true), ''), ',') $$;
+
+CREATE OR REPLACE FUNCTION rls_has_role(role_name text)
+RETURNS boolean
+LANGUAGE SQL STABLE
+AS $$ SELECT role_name = ANY(rls_current_roles()) $$;
+
+CREATE OR REPLACE FUNCTION rls_current_permissions()
+RETURNS text[]
+LANGUAGE SQL STABLE
+AS $$ SELECT string_to_array(COALESCE(current_setting('app.permissions', true), ''), ',') $$;
+
+CREATE OR REPLACE FUNCTION rls_has_permission(permission_name text)
+RETURNS boolean
+LANGUAGE SQL STABLE
+AS $$ SELECT permission_name = ANY(rls_current_permissions()) $$;
+
+CREATE OR REPLACE FUNCTION rls_is_system()
+RETURNS boolean
+LANGUAGE SQL STABLE
+AS $$ SELECT COALESCE(current_setting('app.is_system', true), 'false')::boolean $$;
+`;
+  }
+
+  /**
+   * Generate DROP statements for cleaning up
+   */
+  generateDropStatements<DB>(
+    schema: RLSSchema<DB>,
+    options: PostgresRLSOptions = {}
+  ): string[] {
+    const { schemaName = 'public', policyPrefix = 'rls' } = options;
+    const statements: string[] = [];
+
+    for (const table of Object.keys(schema)) {
+      const qualifiedTable = `${schemaName}.${table}`;
+
+      // Drop all policies with prefix
+      statements.push(
+        `DO $$ BEGIN
+  EXECUTE (
+    SELECT string_agg('DROP POLICY IF EXISTS ' || quote_ident(policyname) || ' ON ${qualifiedTable};', E'\\n')
+    FROM pg_policies
+    WHERE tablename = '${table}'
+      AND schemaname = '${schemaName}'
+      AND policyname LIKE '${policyPrefix}_%'
+  );
+END $$;`
+      );
+
+      // Disable RLS
+      statements.push(`ALTER TABLE ${qualifiedTable} DISABLE ROW LEVEL SECURITY;`);
+    }
+
+    return statements;
+  }
+}
+
+/**
+ * Sync RLS context to PostgreSQL session settings
+ * Call this at the start of each request/transaction
+ */
+export async function syncContextToPostgres<DB>(
+  db: Kysely<DB>,
+  context: {
+    userId: string | number;
+    tenantId?: string | number;
+    roles?: string[];
+    permissions?: string[];
+    isSystem?: boolean;
+  }
+): Promise<void> {
+  const { userId, tenantId, roles, permissions, isSystem } = context;
+
+  await sql`
+    SELECT
+      set_config('app.user_id', ${String(userId)}, true),
+      set_config('app.tenant_id', ${tenantId ? String(tenantId) : ''}, true),
+      set_config('app.roles', ${(roles ?? []).join(',')}, true),
+      set_config('app.permissions', ${(permissions ?? []).join(',')}, true),
+      set_config('app.is_system', ${isSystem ? 'true' : 'false'}, true)
+  `.execute(db);
+}
+
+/**
+ * Clear RLS context from PostgreSQL session
+ */
+export async function clearPostgresContext<DB>(db: Kysely<DB>): Promise<void> {
+  await sql`
+    SELECT
+      set_config('app.user_id', '', true),
+      set_config('app.tenant_id', '', true),
+      set_config('app.roles', '', true),
+      set_config('app.permissions', '', true),
+      set_config('app.is_system', 'false', true)
+  `.execute(db);
+}