@dotdo/postgres 0.1.0

package/src/rls/validator.ts

@@ -0,0 +1,895 @@
+/**
+ * RLS Policy Validator
+ *
+ * SECURITY CRITICAL: This module validates Row-Level Security policies to prevent:
+ * - SQL injection attacks via policy names, table names, role names, and expressions
+ * - Privilege escalation through malicious policy expressions
+ * - Denial of service through dangerous function calls
+ * - Information disclosure via system catalog access
+ * - Unicode-based attacks (homoglyphs, zero-width, RTL override)
+ *
+ * All user-provided input MUST be validated through this module before being
+ * used to construct SQL statements for RLS policy creation or modification.
+ *
+ * @module rls/validator
+ */
+
+import type {
+  RLSPolicy,
+  PolicyValidationResult,
+  ValidationOptions,
+  PGliteLike,
+} from './policy'
+
+// =============================================================================
+// SQL RESERVED KEYWORDS
+// =============================================================================
+
+/**
+ * SQL reserved keywords that should be avoided as identifiers.
+ * Using these as unquoted identifiers can cause syntax errors or
+ * unexpected behavior. The validator warns when these are used.
+ */
+const SQL_RESERVED_KEYWORDS = new Set([
+  'select',
+  'insert',
+  'update',
+  'delete',
+  'from',
+  'where',
+  'table',
+  'create',
+  'drop',
+  'alter',
+  'index',
+  'grant',
+  'revoke',
+  'order',
+  'group',
+  'by',
+  'having',
+  'join',
+  'left',
+  'right',
+  'inner',
+  'outer',
+  'on',
+  'as',
+  'and',
+  'or',
+  'not',
+  'null',
+  'true',
+  'false',
+  'primary',
+  'key',
+  'foreign',
+  'references',
+  'constraint',
+  'unique',
+  'check',
+  'default',
+  'cascade',
+  'set',
+  'values',
+  'into',
+  'view',
+  'function',
+  'procedure',
+  'trigger',
+  'sequence',
+  'schema',
+  'database',
+  'user',
+  'role',
+  'policy',
+  'row',
+  'level',
+  'security',
+  'using',
+  'with',
+  'all',
+  'any',
+  'some',
+  'exists',
+  'in',
+  'between',
+  'like',
+  'is',
+  'case',
+  'when',
+  'then',
+  'else',
+  'end',
+  'begin',
+  'commit',
+  'rollback',
+  'transaction',
+])
+
+// =============================================================================
+// DANGEROUS FUNCTION BLOCKLIST
+// =============================================================================
+
+/**
+ * PostgreSQL functions that MUST NOT appear in RLS policy expressions.
+ *
+ * These functions are blocked because they can be exploited for:
+ *
+ * - **Timing attacks (DoS)**:
+ *   - `pg_sleep` - delays execution, enables timing-based attacks
+ *
+ * - **Process termination (DoS)**:
+ *   - `pg_cancel_backend` - cancels queries on other backends
+ *   - `pg_terminate_backend` - forcibly terminates other connections
+ *
+ * - **File system access (Data exfiltration/modification)**:
+ *   - `pg_read_file` - reads arbitrary files from the server filesystem
+ *   - `pg_write_file` - writes arbitrary files to the server filesystem
+ *   - `lo_import` - imports a file into a large object
+ *   - `lo_export` - exports a large object to a file
+ *   - `copy` - bulk data import/export to filesystem
+ *
+ * - **Network access (Remote code execution)**:
+ *   - `dblink` - executes queries on remote PostgreSQL servers
+ */
+const DANGEROUS_FUNCTIONS = [
+  'pg_sleep',
+  'pg_cancel_backend',
+  'pg_terminate_backend',
+  'pg_read_file',
+  'pg_write_file',
+  'lo_import',
+  'lo_export',
+  'dblink',
+  'copy',
+] as const
+
+// =============================================================================
+// DANGEROUS DDL PATTERN DEFINITIONS
+// =============================================================================
+
+/**
+ * DDL statements that MUST NOT appear in RLS policy expressions.
+ *
+ * These patterns detect privilege escalation attempts where an attacker
+ * tries to embed DDL statements within policy expressions to:
+ * - Grant themselves elevated privileges (GRANT)
+ * - Revoke security controls (REVOKE)
+ * - Create new privileged accounts (CREATE USER/ROLE)
+ * - Modify existing account privileges (ALTER USER/ROLE)
+ * - Remove security accounts (DROP USER/ROLE)
+ *
+ * All patterns are case-insensitive to prevent bypass via mixed case.
+ */
+const DANGEROUS_DDL_PATTERNS: readonly RegExp[] = [
+  /** Detects GRANT statements - privilege escalation */
+  /\bGRANT\b/i,
+  /** Detects REVOKE statements - removing security controls */
+  /\bREVOKE\b/i,
+  /** Detects CREATE USER statements - creating privileged accounts */
+  /\bCREATE\s+USER\b/i,
+  /** Detects CREATE ROLE statements - creating privileged roles */
+  /\bCREATE\s+ROLE\b/i,
+  /** Detects ALTER ROLE statements - modifying role privileges */
+  /\bALTER\s+ROLE\b/i,
+  /** Detects ALTER USER statements - modifying user privileges */
+  /\bALTER\s+USER\b/i,
+  /** Detects DROP USER statements - removing security accounts */
+  /\bDROP\s+USER\b/i,
+  /** Detects DROP ROLE statements - removing security roles */
+  /\bDROP\s+ROLE\b/i,
+]
+
+// =============================================================================
+// SECURITY BYPASS PATTERN DEFINITIONS
+// =============================================================================
+
+/**
+ * Patterns that indicate RLS policy bypass attempts.
+ *
+ * These patterns detect common SQL injection techniques that would cause
+ * a policy to return TRUE for all rows, effectively bypassing row-level security:
+ *
+ * - `1=1` - Classic always-true condition
+ * - `OR 'x'='x'` - String comparison bypass (e.g., `user_id = 1 OR 'x'='x'`)
+ *
+ * When detected, the validator issues a warning as these patterns may indicate
+ * either a security issue or an intentionally permissive policy.
+ */
+const BYPASS_PATTERNS: readonly RegExp[] = [
+  /** Detects standalone 1=1 condition - always evaluates to TRUE */
+  /^\s*1\s*=\s*1\s*$/,
+  /** Detects OR with string equality bypass - e.g., OR 'x'='x' */
+  /\bOR\s+['"][^'"]+['"]\s*=\s*['"][^'"]+['"]/i,
+]
+
+// =============================================================================
+// IDENTIFIER VALIDATION PATTERNS
+// =============================================================================
+
+/**
+ * Pattern for valid PostgreSQL role names.
+ * Roles must start with a letter or underscore, followed by letters, digits, or underscores.
+ * This restrictive pattern prevents injection via role names in GRANT TO clauses.
+ */
+const VALID_ROLE_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+/**
+ * Pattern for valid PostgreSQL identifiers (unquoted).
+ * Must start with a letter or underscore, followed by letters, digits, or underscores.
+ * Does not allow hyphens (those require quoting).
+ */
+const VALID_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+/**
+ * Pattern for schema-qualified identifiers (e.g., `public.users`).
+ * Both schema and table name must be valid identifiers separated by a single dot.
+ */
+const SCHEMA_QUALIFIED_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*$/
+
+/**
+ * Pattern for valid table names, allowing optional hyphens (requires quoting in SQL).
+ * More permissive than VALID_IDENTIFIER_PATTERN to support hyphenated names.
+ */
+const VALID_TABLE_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_-]*(\.[a-zA-Z_][a-zA-Z0-9_-]*)?$/
+
+/**
+ * Pattern for valid tenant IDs.
+ * Allows alphanumeric characters, hyphens, and underscores.
+ * Supports UUID format (with hyphens).
+ */
+const VALID_TENANT_ID_PATTERN = /^[a-zA-Z0-9_-]+$/
+
+/** Maximum length for PostgreSQL identifiers */
+const MAX_IDENTIFIER_LENGTH = 63
+
+/** Pattern for valid policy name start (letter, underscore, or quoted) */
+const VALID_POLICY_NAME_START = /^[a-zA-Z_]/
+
+// =============================================================================
+// UNICODE SECURITY PATTERNS
+// =============================================================================
+
+/**
+ * Unicode character patterns that indicate potential security attacks.
+ *
+ * These patterns detect:
+ *
+ * - **Null byte injection** (U+0000):
+ *   Can truncate strings in C-based parsers, potentially bypassing validation
+ *
+ * - **Zero-width characters** (U+200B-U+200F):
+ *   Invisible characters that can hide malicious content or confuse parsers
+ *
+ * - **Bidirectional text controls** (U+202A-U+202E):
+ *   Can reverse text direction, hiding malicious code (Trojan Source attack)
+ *
+ * - **Cyrillic characters** (U+0400-U+04FF):
+ *   Used in homoglyph attacks where visually similar characters from different
+ *   scripts are used to create confusingly similar identifiers
+ *   (e.g., Cyrillic 'a' U+0430 vs Latin 'a' U+0061)
+ */
+const UNSAFE_UNICODE_PATTERNS: readonly RegExp[] = [
+  /** Null byte - can cause string truncation in C parsers */
+  /[\u0000]/,
+  /** Zero-width characters - invisible, can hide malicious content */
+  /[\u200B-\u200F]/,
+  /** Bidirectional text controls - enables Trojan Source attacks */
+  /[\u202A-\u202E]/,
+  /** Cyrillic characters - common source of homoglyph attacks */
+  /[\u0400-\u04FF]/,
+]
+
+// =============================================================================
+// SQL INJECTION DETECTION PATTERNS
+// =============================================================================
+
+/**
+ * Patterns that indicate SQL injection attempts in identifiers.
+ *
+ * These patterns detect common SQL injection techniques:
+ *
+ * - **Semicolon** (;): Statement terminator, enables stacked queries
+ * - **Double dash** (--): Line comment, can comment out security checks
+ * - **Block comment start** (/*): Can comment out or inject code
+ * - **Block comment end** (*\/): Can close injected comments
+ * - **DROP keyword**: Data destruction
+ * - **TRUNCATE keyword**: Data destruction
+ * - **ALTER keyword**: Schema/privilege modification
+ */
+const SQL_INJECTION_PATTERNS: readonly RegExp[] = [
+  /** Semicolon - statement terminator, enables stacked queries */
+  /;/,
+  /** Double dash - line comment, can hide or bypass code */
+  /--/,
+  /** Block comment open - can inject or hide code */
+  /\/\*/,
+  /** Block comment close - ends injected comments */
+  /\*\//,
+  /** DROP keyword - destructive DDL (case-insensitive) */
+  /\bDROP\b/i,
+  /** TRUNCATE keyword - destructive DDL (case-insensitive) */
+  /\bTRUNCATE\b/i,
+  /** ALTER keyword - schema/privilege modification (case-insensitive) */
+  /\bALTER\b/i,
+]
+
+// =============================================================================
+// EXPRESSION ANALYSIS PATTERNS
+// =============================================================================
+
+/**
+ * Pattern to detect subqueries in policy expressions.
+ * Subqueries (SELECT statements) can impact performance and may be used
+ * for information disclosure via side-channel attacks.
+ */
+const SUBQUERY_PATTERN = /\bSELECT\b/i
+
+/**
+ * Patterns to detect arithmetic expressions that clearly don't return boolean.
+ * Used as a secondary check after pg_typeof to catch edge cases.
+ */
+const ARITHMETIC_EXPRESSION_PATTERNS: readonly RegExp[] = [
+  /** Simple binary arithmetic: 1 + 1, 2 * 3, etc. */
+  /^\s*\d+\s*[+\-*/%]\s*\d+\s*$/,
+  /** Just a number - not a boolean expression */
+  /^\s*\d+\s*$/,
+]
+
+// =============================================================================
+// CORE VALIDATION HELPER FUNCTIONS
+// =============================================================================
+
+/**
+ * Tests a string against a collection of security patterns.
+ *
+ * This is the core pattern-matching function used by all security validators.
+ * It returns true if ANY pattern in the collection matches the input string.
+ *
+ * @param str - The string to test
+ * @param patterns - Array of regex patterns to test against
+ * @returns true if any pattern matches, false otherwise
+ *
+ * @internal
+ */
+function matchesAnyPattern(str: string, patterns: readonly RegExp[]): boolean {
+  return patterns.some((pattern) => pattern.test(str))
+}
+
+/**
+ * Checks if a string contains SQL injection patterns.
+ *
+ * SECURITY CRITICAL: This function detects common SQL injection techniques
+ * including statement terminators, comments, and destructive DDL keywords.
+ *
+ * Detected patterns:
+ * - Semicolons (stacked queries)
+ * - Comment syntax (-- and /*)
+ * - DROP, TRUNCATE, ALTER keywords
+ *
+ * @param str - The string to validate
+ * @returns true if injection patterns detected, false if safe
+ */
+function containsUnsafePatterns(str: string): boolean {
+  return matchesAnyPattern(str, SQL_INJECTION_PATTERNS)
+}
+
+/**
+ * Checks if a string contains dangerous Unicode characters.
+ *
+ * SECURITY CRITICAL: This function detects Unicode-based attacks including:
+ * - Null byte injection (string truncation attacks)
+ * - Zero-width characters (hidden content)
+ * - Bidirectional text overrides (Trojan Source attacks)
+ * - Cyrillic characters (homoglyph attacks)
+ *
+ * @param str - The string to validate
+ * @returns true if dangerous Unicode detected, false if safe
+ */
+function containsUnsafeUnicode(str: string): boolean {
+  return matchesAnyPattern(str, UNSAFE_UNICODE_PATTERNS)
+}
+
+/**
+ * Checks if an expression contains dangerous DDL patterns.
+ *
+ * SECURITY CRITICAL: This function detects privilege escalation attempts
+ * where attackers embed DDL statements in policy expressions to:
+ * - Grant themselves privileges (GRANT)
+ * - Create superuser accounts (CREATE USER/ROLE)
+ * - Modify existing privileges (ALTER USER/ROLE)
+ *
+ * @param expr - The SQL expression to validate
+ * @returns true if dangerous DDL detected, false if safe
+ */
+function containsDangerousDDL(expr: string): boolean {
+  return matchesAnyPattern(expr, DANGEROUS_DDL_PATTERNS)
+}
+
+/**
+ * Checks if an expression contains RLS bypass patterns.
+ *
+ * SECURITY WARNING: Detects patterns that would cause a policy to return TRUE
+ * for all rows, effectively bypassing row-level security. This includes:
+ * - Tautologies like `1=1`
+ * - OR-based bypasses like `OR 'x'='x'`
+ *
+ * Returns true for detection; the validator will issue a warning (not error)
+ * since some use cases may legitimately need permissive policies.
+ *
+ * @param expr - The SQL expression to check
+ * @returns true if bypass pattern detected, false otherwise
+ */
+function containsBypassPattern(expr: string): boolean {
+  return matchesAnyPattern(expr, BYPASS_PATTERNS)
+}
+
+/**
+ * Checks if an expression contains a subquery.
+ *
+ * Subqueries in RLS policies can:
+ * - Impact query performance significantly
+ * - Enable information disclosure via side-channel attacks
+ * - Cause unexpected behavior with correlated queries
+ *
+ * @param expr - The SQL expression to check
+ * @returns true if subquery detected, false otherwise
+ */
+function containsSubquery(expr: string): boolean {
+  return SUBQUERY_PATTERN.test(expr)
+}
+
+/**
+ * Checks if an expression is clearly an arithmetic operation (not boolean).
+ *
+ * This provides a secondary validation layer to catch edge cases where
+ * PostgreSQL's pg_typeof might not correctly identify non-boolean expressions.
+ *
+ * @param expr - The expression to check
+ * @returns true if the expression is arithmetic, false otherwise
+ *
+ * @internal
+ */
+function isArithmeticExpression(expr: string): boolean {
+  return matchesAnyPattern(expr, ARITHMETIC_EXPRESSION_PATTERNS)
+}
+
+// =============================================================================
+// STRING VALIDATION FUNCTIONS
+// =============================================================================
+
+/**
+ * Validates a role name for SQL safety.
+ *
+ * SECURITY CRITICAL: Role names are used in GRANT TO clauses and must be
+ * strictly validated to prevent privilege escalation attacks.
+ *
+ * Validation rules:
+ * 1. No SQL injection patterns
+ * 2. No dangerous Unicode characters
+ * 3. Must match PostgreSQL identifier format (letter/underscore start,
+ *    followed by letters, digits, underscores)
+ *
+ * @param role - The role name to validate
+ * @returns true if role name is safe, false otherwise
+ */
+function isValidRoleName(role: string): boolean {
+  if (containsUnsafePatterns(role)) {
+    return false
+  }
+  if (containsUnsafeUnicode(role)) {
+    return false
+  }
+  return VALID_ROLE_PATTERN.test(role)
+}
+
+// =============================================================================
+// IDENTIFIER VALIDATION FUNCTIONS (EXPORTED)
+// =============================================================================
+
+/**
+ * Validates a PostgreSQL identifier for correctness.
+ *
+ * Checks if an identifier follows PostgreSQL naming rules:
+ * - Must start with a letter (a-z, A-Z) or underscore (_)
+ * - Subsequent characters can be letters, digits, or underscores
+ * - Schema-qualified names (schema.table) are allowed
+ *
+ * Note: This validates the format only, not SQL injection safety.
+ * For security validation, use validateTableName() or validatePolicy().
+ *
+ * @param identifier - The identifier to validate
+ * @returns true if the identifier is valid, false otherwise
+ */
+export function isValidIdentifier(identifier: string): boolean {
+  if (SCHEMA_QUALIFIED_PATTERN.test(identifier)) {
+    return true
+  }
+  return VALID_IDENTIFIER_PATTERN.test(identifier)
+}
+
+/**
+ * Determines if an identifier requires double-quoting in SQL.
+ *
+ * PostgreSQL requires quoting for identifiers that:
+ * - Contain characters other than letters, digits, underscores
+ * - Start with a digit
+ * - Are reserved keywords (handled separately)
+ *
+ * @param identifier - The identifier to check
+ * @returns true if quoting is required, false otherwise
+ */
+export function needsQuoting(identifier: string): boolean {
+  return !VALID_IDENTIFIER_PATTERN.test(identifier) && !SCHEMA_QUALIFIED_PATTERN.test(identifier)
+}
+
+/**
+ * Wraps an identifier in double quotes if necessary for SQL safety.
+ *
+ * Use this function when constructing SQL statements with user-provided
+ * identifiers. Already-valid identifiers are returned unchanged.
+ *
+ * WARNING: This function only adds quotes for format compliance, not
+ * security. Always validate identifiers with validateTableName() or
+ * validatePolicy() before using in SQL.
+ *
+ * @param identifier - The identifier to potentially quote
+ * @returns The identifier, quoted if necessary
+ */
+export function quoteIdentifier(identifier: string): string {
+  if (needsQuoting(identifier)) {
+    return '"' + identifier + '"'
+  }
+  return identifier
+}
+
+/**
+ * Validates a table name for SQL safety.
+ *
+ * SECURITY CRITICAL: Table names are directly interpolated into SQL
+ * statements. This function ensures the name is safe from injection.
+ *
+ * Validation rules:
+ * 1. No SQL injection patterns (semicolons, comments, DDL keywords)
+ * 2. Must match valid table name format (letters, digits, underscores,
+ *    optional hyphens, optional schema prefix)
+ *
+ * @param table - The table name to validate
+ * @returns true if the table name is safe, false otherwise
+ */
+export function validateTableName(table: string): boolean {
+  if (containsUnsafePatterns(table)) {
+    return false
+  }
+  return VALID_TABLE_NAME_PATTERN.test(table)
+}
+
+// =============================================================================
+// POLICY CLAUSE VALIDATION HELPERS
+// =============================================================================
+
+/**
+ * Validates a policy name and collects errors/warnings.
+ *
+ * @internal
+ */
+function validatePolicyName(
+  name: string | undefined,
+  errors: string[],
+  warnings: string[]
+): void {
+  if (!name || name.trim() === '') {
+    errors.push('Policy name cannot be empty')
+    return
+  }
+
+  // Check name format (must start with letter/underscore unless quoted)
+  if (!VALID_POLICY_NAME_START.test(name) && !name.startsWith('"')) {
+    errors.push('Policy name must start with a letter or underscore')
+  }
+
+  // Check PostgreSQL identifier length limit
+  if (name.length > MAX_IDENTIFIER_LENGTH) {
+    errors.push('Policy name is too long (max ' + MAX_IDENTIFIER_LENGTH + ' characters)')
+  }
+
+  // Security: Check for SQL injection patterns
+  if (containsUnsafePatterns(name)) {
+    errors.push('Policy name contains unsafe characters')
+  }
+
+  // Security: Check for Unicode attacks
+  if (containsUnsafeUnicode(name)) {
+    errors.push('Policy name contains unsafe Unicode characters')
+  }
+
+  // Warning: Reserved keyword usage
+  if (SQL_RESERVED_KEYWORDS.has(name.toLowerCase())) {
+    warnings.push('Policy name "' + name + '" is a reserved SQL keyword')
+  }
+}
+
+/**
+ * Validates a table name and collects errors/warnings.
+ *
+ * @internal
+ */
+function validatePolicyTableName(
+  table: string | undefined,
+  errors: string[],
+  warnings: string[]
+): void {
+  if (!table || table.trim() === '') {
+    errors.push('Table name cannot be empty')
+    return
+  }
+
+  // Security: Check for SQL injection patterns
+  if (containsUnsafePatterns(table)) {
+    errors.push('Table name contains unsafe characters')
+  }
+
+  // Security: Check for Unicode attacks
+  if (containsUnsafeUnicode(table)) {
+    errors.push('Table name contains unsafe Unicode characters')
+  }
+
+  // Extract base table name (handle schema.table format)
+  const tableName = table.includes('.') ? (table.split('.')[1] ?? table) : table
+
+  // Warning: Reserved keyword usage
+  if (SQL_RESERVED_KEYWORDS.has(tableName.toLowerCase())) {
+    warnings.push('Table name "' + tableName + '" is a reserved SQL keyword')
+  }
+}
+
+/**
+ * Validates policy expression (USING or CHECK clause) for security issues.
+ *
+ * @internal
+ */
+function validatePolicyExpression(
+  expr: string,
+  clauseName: string,
+  errors: string[],
+  warnings: string[]
+): void {
+  // Security: Check for dangerous PostgreSQL functions
+  for (const func of DANGEROUS_FUNCTIONS) {
+    const funcPattern = new RegExp('\\b' + func + '\\b', 'i')
+    if (funcPattern.test(expr)) {
+      errors.push(clauseName + ' clause contains dangerous function: ' + func)
+    }
+  }
+
+  // Security: Check for DDL privilege escalation
+  if (containsDangerousDDL(expr)) {
+    errors.push(clauseName + ' clause contains unsafe DDL statement')
+  }
+
+  // Security: Check for Unicode attacks
+  if (containsUnsafeUnicode(expr)) {
+    errors.push(clauseName + ' clause contains unsafe Unicode characters')
+  }
+
+  // Performance/Security: Check for subqueries
+  if (containsSubquery(expr)) {
+    warnings.push('Policy contains subquery which may impact performance')
+  }
+}
+
+// =============================================================================
+// MAIN POLICY VALIDATION FUNCTION
+// =============================================================================
+
+/**
+ * Validates an RLS policy definition for security and correctness.
+ *
+ * SECURITY CRITICAL: This is the primary entry point for validating RLS policies
+ * before they are applied to the database. All user-provided policy definitions
+ * MUST pass through this function.
+ *
+ * ## Security Checks Performed
+ *
+ * ### On Policy Names:
+ * - SQL injection patterns (semicolons, comments, DDL keywords)
+ * - Unicode attacks (null bytes, zero-width, RTL override, homoglyphs)
+ * - Length limits (PostgreSQL max 63 characters)
+ * - Format validation (must start with letter or underscore)
+ *
+ * ### On Table Names:
+ * - SQL injection patterns
+ * - Unicode attacks
+ * - Reserved keyword warnings
+ *
+ * ### On Role Names:
+ * - SQL injection patterns
+ * - Valid identifier format
+ * - Unicode attacks
+ *
+ * ### On USING/CHECK Expressions:
+ * - Dangerous function blocklist (pg_sleep, pg_read_file, dblink, etc.)
+ * - DDL privilege escalation (GRANT, CREATE USER, etc.)
+ * - Unicode attacks
+ * - Bypass pattern warnings (1=1, OR 'x'='x')
+ * - Subquery performance warnings
+ *
+ * ### Semantic Validation:
+ * - SELECT/DELETE require USING clause
+ * - INSERT requires WITH CHECK clause
+ * - Multi-tenant isolation checks (optional)
+ *
+ * @param policy - The RLS policy definition to validate
+ * @param options - Optional validation configuration
+ * @returns Validation result with valid flag, errors array, and warnings array
+ */
+export function validatePolicy(
+  policy: RLSPolicy,
+  options?: ValidationOptions
+): PolicyValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  // Validate policy name
+  validatePolicyName(policy.name, errors, warnings)
+
+  // Validate table name
+  validatePolicyTableName(policy.table, errors, warnings)
+
+  // Validate role names
+  if (policy.roles && policy.roles.length > 0) {
+    for (const role of policy.roles) {
+      if (!isValidRoleName(role)) {
+        errors.push('Role name "' + role + '" contains unsafe characters')
+      }
+    }
+  }
+
+  // Validate operation-specific clause requirements
+  if (policy.operation === 'SELECT' || policy.operation === 'DELETE') {
+    if (!policy.using) {
+      errors.push(policy.operation + ' policy requires USING clause')
+    }
+  }
+
+  if (policy.operation === 'INSERT') {
+    if (!policy.check) {
+      errors.push('INSERT policy requires WITH CHECK clause')
+    }
+  }
+
+  // Validate USING clause
+  if (policy.using) {
+    validatePolicyExpression(policy.using, 'USING', errors, warnings)
+
+    // Additional USING-specific checks
+    if (policy.using.trim().toLowerCase() === 'true') {
+      warnings.push('USING (true) allows all rows - verify this is intentional')
+    }
+
+    if (containsBypassPattern(policy.using)) {
+      warnings.push('USING clause contains bypass pattern that may allow all rows')
+    }
+  }
+
+  // Validate CHECK clause
+  if (policy.check) {
+    validatePolicyExpression(policy.check, 'WITH CHECK', errors, warnings)
+  }
+
+  // Multi-tenant isolation check
+  if (options?.requireTenantIsolation && options.tenantColumn) {
+    const tenantColumn = options.tenantColumn
+    const hasInUsing = policy.using?.includes(tenantColumn)
+    const hasInCheck = policy.check?.includes(tenantColumn)
+
+    if (!hasInUsing && !hasInCheck) {
+      warnings.push(
+        'Policy does not include ' + tenantColumn + ' column - multi-tenant isolation may be compromised'
+      )
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}
+
+// =============================================================================
+// RUNTIME SYNTAX VALIDATION
+// =============================================================================
+
+/**
+ * Validates SQL expression syntax using the PostgreSQL database.
+ *
+ * This function performs two levels of validation:
+ *
+ * 1. **Syntax Check**: Attempts to parse the expression by wrapping it in a
+ *    SELECT statement. This catches malformed SQL before it reaches production.
+ *
+ * 2. **Type Check**: Verifies the expression returns a boolean type, which is
+ *    required for RLS policy expressions. Non-boolean expressions (like
+ *    arithmetic operations) will cause policies to fail at runtime.
+ *
+ * @param pglite - PGlite-compatible database connection
+ * @param expression - SQL expression to validate
+ * @returns Promise resolving to validation result
+ */
+export async function validatePolicySyntax(
+  pglite: PGliteLike,
+  expression: string
+): Promise<PolicyValidationResult> {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  // Step 1: Syntax validation - wrap expression in SELECT to parse
+  try {
+    await pglite.exec('SELECT ' + expression + ' WHERE FALSE')
+  } catch {
+    errors.push('Invalid SQL syntax')
+    return { valid: false, errors, warnings }
+  }
+
+  // Step 2: Type validation - expression must return boolean
+  try {
+    const result = await pglite.query<{ result: string }>(
+      'SELECT pg_typeof(' + expression + ')::text as result'
+    )
+
+    if (result?.rows?.length > 0) {
+      const typeResult = result.rows[0]?.result
+
+      // pg_typeof returns 'boolean' for boolean expressions
+      if (typeResult !== 'boolean') {
+        errors.push('Policy expression must return boolean type')
+      } else if (isArithmeticExpression(expression)) {
+        // Edge case: some arithmetic expressions might be coerced to boolean
+        // by PostgreSQL, but they're still invalid for RLS policies
+        errors.push('Policy expression must return boolean type')
+      }
+    }
+  } catch {
+    // Type check failed but syntax passed - expression is syntactically valid
+    // but may have runtime issues (e.g., referencing non-existent columns)
+    // We allow this to pass since the caller may be validating before table creation
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}
+
+// =============================================================================
+// TENANT ID VALIDATION
+// =============================================================================
+
+/**
+ * Validates a tenant ID for safe use in multi-tenant RLS policies.
+ *
+ * SECURITY CRITICAL: Tenant IDs are often interpolated into SQL expressions
+ * for multi-tenant row-level security. This function ensures tenant IDs
+ * cannot be exploited for SQL injection.
+ *
+ * ## Allowed Characters
+ * - Letters (a-z, A-Z)
+ * - Digits (0-9)
+ * - Hyphens (-)
+ * - Underscores (_)
+ *
+ * ## Rejected Patterns
+ * - Empty strings
+ * - Whitespace
+ * - SQL special characters (quotes, semicolons, comments)
+ * - Unicode characters (to prevent homoglyph attacks)
+ *
+ * @param tenantId - The tenant ID to validate
+ * @returns true if the tenant ID is safe, false otherwise
+ */
+export function validateTenantId(tenantId: string): boolean {
+  return VALID_TENANT_ID_PATTERN.test(tenantId)
+}