@dotdo/postgres 0.1.0

package/src/rls/auth-integration.ts

@@ -0,0 +1,533 @@
+/**
+ * RLS Auth Integration Module
+ *
+ * This module integrates Row-Level Security (RLS) with the authentication system,
+ * providing:
+ * - Automatic RLS context setup from auth tokens
+ * - Admin bypass capabilities for privileged operations
+ * - Session-scoped tenant isolation
+ *
+ * @module rls/auth-integration
+ */
+
+import type { PGliteLike, SetTenantContextOptions } from './policy'
+import { setTenantContext, clearTenantContext } from './index'
+import { validateTenantId } from './validator'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * User information extracted from authentication context
+ */
+export interface RLSUser {
+  /** User's unique identifier */
+  id: string
+  /** User's email address */
+  email?: string
+  /** User's roles/permissions */
+  roles?: string[]
+  /** Organization/tenant the user belongs to */
+  tenantId?: string
+  /** Whether user has admin privileges */
+  isAdmin?: boolean
+}
+
+/**
+ * RLS context that tracks the current security state
+ */
+export interface RLSContext {
+  /** Current authenticated user */
+  user: RLSUser | null
+  /** Current tenant ID if set */
+  tenantId: string | null
+  /** Whether RLS is currently bypassed */
+  isBypassed: boolean
+  /** Reason for current bypass if any */
+  bypassReason?: string
+}
+
+/**
+ * Options for setting up RLS from auth context
+ */
+export interface SetupRLSFromAuthOptions {
+  /** Session variable for user ID (default: 'app.user_id') */
+  userIdVariable?: string
+  /** Session variable for tenant ID (default: 'app.tenant_id') */
+  tenantIdVariable?: string
+  /** Session variable for roles (default: 'app.roles') */
+  rolesVariable?: string
+  /** Whether to set context as LOCAL (transaction-scoped) */
+  local?: boolean
+  /** Extract tenant ID from user if not explicitly provided */
+  autoExtractTenant?: boolean
+}
+
+/**
+ * Options for admin bypass
+ */
+export interface AdminBypassOptions {
+  /** Reason for the bypass (for audit logging) */
+  reason: string
+  /** Maximum duration of bypass in milliseconds (default: 30000 = 30 seconds) */
+  maxDuration?: number
+  /** Callback when bypass is activated */
+  onBypassStart?: (context: RLSContext) => void
+  /** Callback when bypass is deactivated */
+  onBypassEnd?: (context: RLSContext) => void
+}
+
+/**
+ * Result of an admin operation with bypass
+ */
+export interface AdminOperationResult<T> {
+  /** Whether the operation succeeded */
+  success: boolean
+  /** Result data if successful */
+  data?: T
+  /** Error if operation failed */
+  error?: Error
+  /** Duration of the bypass in milliseconds */
+  bypassDuration: number
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Default session variable for user ID */
+const DEFAULT_USER_ID_VARIABLE = 'app.user_id'
+
+/** Default session variable for tenant ID */
+const DEFAULT_TENANT_ID_VARIABLE = 'app.tenant_id'
+
+/** Default session variable for roles */
+const DEFAULT_ROLES_VARIABLE = 'app.roles'
+
+/** Maximum bypass duration (5 minutes) */
+const MAX_BYPASS_DURATION = 5 * 60 * 1000
+
+/** Default bypass duration (30 seconds) */
+const DEFAULT_BYPASS_DURATION = 30 * 1000
+
+/** Admin role identifier */
+const ADMIN_ROLE = 'admin'
+
+/** Super admin role identifier */
+const SUPER_ADMIN_ROLE = 'super_admin'
+
+// ============================================================================
+// RLS Context Manager
+// ============================================================================
+
+/**
+ * Manages RLS context for a database connection.
+ *
+ * This class provides methods to:
+ * - Set up RLS context from authentication
+ * - Manage admin bypass for privileged operations
+ * - Track current security state
+ *
+ * @example
+ * ```typescript
+ * const manager = new RLSContextManager(pglite)
+ *
+ * // Set up context from authenticated user
+ * await manager.setupFromAuth({
+ *   id: 'user-123',
+ *   tenantId: 'tenant-456',
+ *   roles: ['user']
+ * })
+ *
+ * // Now queries will be filtered by RLS policies
+ * const results = await pglite.query('SELECT * FROM orders')
+ *
+ * // Admin can bypass RLS for specific operations
+ * await manager.withAdminBypass(
+ *   { reason: 'Support ticket #789' },
+ *   async () => {
+ *     // This operation sees all rows
+ *     return await pglite.query('SELECT * FROM orders')
+ *   }
+ * )
+ * ```
+ */
+export class RLSContextManager {
+  private pglite: PGliteLike
+  private context: RLSContext
+  private bypassTimeout: ReturnType<typeof setTimeout> | null = null
+
+  constructor(pglite: PGliteLike) {
+    this.pglite = pglite
+    this.context = {
+      user: null,
+      tenantId: null,
+      isBypassed: false,
+    }
+  }
+
+  /**
+   * Get the current RLS context state
+   */
+  getContext(): Readonly<RLSContext> {
+    return { ...this.context }
+  }
+
+  /**
+   * Check if the current user has admin privileges
+   */
+  isAdmin(): boolean {
+    if (!this.context.user) return false
+    if (this.context.user.isAdmin) return true
+    const roles = this.context.user.roles || []
+    return roles.includes(ADMIN_ROLE) || roles.includes(SUPER_ADMIN_ROLE)
+  }
+
+  /**
+   * Check if RLS is currently bypassed
+   */
+  isBypassed(): boolean {
+    return this.context.isBypassed
+  }
+
+  /**
+   * Set up RLS context from an authenticated user.
+   *
+   * This sets PostgreSQL session variables that RLS policies can reference
+   * to filter data based on the current user's identity and permissions.
+   *
+   * @param user - Authenticated user information
+   * @param options - Configuration options
+   *
+   * @throws {Error} If user ID or tenant ID contains invalid characters
+   *
+   * @example
+   * ```typescript
+   * await manager.setupFromAuth({
+   *   id: 'user-123',
+   *   email: 'user@example.com',
+   *   tenantId: 'tenant-456',
+   *   roles: ['user', 'editor']
+   * })
+   * ```
+   */
+  async setupFromAuth(user: RLSUser, options?: SetupRLSFromAuthOptions): Promise<void> {
+    const {
+      userIdVariable = DEFAULT_USER_ID_VARIABLE,
+      tenantIdVariable = DEFAULT_TENANT_ID_VARIABLE,
+      rolesVariable = DEFAULT_ROLES_VARIABLE,
+      local = false,
+      autoExtractTenant = true,
+    } = options || {}
+
+    // Validate user ID
+    if (!validateTenantId(user.id)) {
+      throw new Error('Invalid user ID - contains unsafe characters')
+    }
+
+    // Set user ID
+    const localKeyword = local ? 'LOCAL ' : ''
+    await this.pglite.exec(`SET ${localKeyword}${userIdVariable} = '${user.id}'`)
+
+    // Determine tenant ID
+    let tenantId = user.tenantId
+    if (!tenantId && autoExtractTenant && user.id) {
+      // Some systems encode tenant in user ID (e.g., "tenant_user" format)
+      // Default: use user ID as tenant ID for single-tenant scenarios
+      tenantId = user.id
+    }
+
+    // Set tenant ID if available
+    if (tenantId) {
+      if (!validateTenantId(tenantId)) {
+        throw new Error('Invalid tenant ID - contains unsafe characters')
+      }
+      await setTenantContext(this.pglite, tenantId, {
+        sessionVariable: tenantIdVariable,
+        local,
+      })
+      this.context.tenantId = tenantId
+    }
+
+    // Set roles if available
+    if (user.roles && user.roles.length > 0) {
+      // Validate each role
+      for (const role of user.roles) {
+        if (!validateTenantId(role)) {
+          throw new Error(`Invalid role "${role}" - contains unsafe characters`)
+        }
+      }
+      const rolesArray = `{${user.roles.join(',')}}`
+      await this.pglite.exec(`SET ${localKeyword}${rolesVariable} = '${rolesArray}'`)
+    }
+
+    // Update context
+    this.context.user = user
+    this.context.isBypassed = false
+    delete this.context.bypassReason
+  }
+
+  /**
+   * Clear the current RLS context.
+   *
+   * Resets all session variables to their defaults, removing any
+   * user-specific filtering from subsequent queries.
+   *
+   * @param options - Configuration options
+   */
+  async clearContext(options?: SetTenantContextOptions): Promise<void> {
+    const userIdVariable = options?.sessionVariable || DEFAULT_USER_ID_VARIABLE
+    const tenantIdVariable = DEFAULT_TENANT_ID_VARIABLE
+    const rolesVariable = DEFAULT_ROLES_VARIABLE
+
+    await this.pglite.exec(`RESET ${userIdVariable}`)
+    await clearTenantContext(this.pglite, { sessionVariable: tenantIdVariable })
+    await this.pglite.exec(`RESET ${rolesVariable}`)
+
+    this.context = {
+      user: null,
+      tenantId: null,
+      isBypassed: false,
+    }
+  }
+
+  /**
+   * Execute an operation with RLS bypassed (admin only).
+   *
+   * This temporarily disables RLS filtering for privileged operations
+   * like admin dashboards, support tools, or data migrations.
+   *
+   * @security This method enforces several safeguards:
+   * - Only users with admin privileges can bypass RLS
+   * - Bypass has a maximum duration (default: 30 seconds)
+   * - Bypass reason is required for audit logging
+   * - Bypass is automatically cleared after operation completes
+   *
+   * @param options - Bypass configuration
+   * @param operation - Async function to execute with bypass
+   * @returns Result of the operation including bypass duration
+   *
+   * @throws {Error} If user is not an admin
+   * @throws {Error} If bypass duration exceeds maximum
+   *
+   * @example
+   * ```typescript
+   * const result = await manager.withAdminBypass(
+   *   { reason: 'Support ticket #12345' },
+   *   async () => {
+   *     // This query bypasses RLS and sees all data
+   *     const allOrders = await pglite.query('SELECT * FROM orders')
+   *     return allOrders.rows
+   *   }
+   * )
+   *
+   * if (result.success) {
+   *   console.log('Found', result.data.length, 'orders')
+   *   console.log('Bypass duration:', result.bypassDuration, 'ms')
+   * }
+   * ```
+   */
+  async withAdminBypass<T>(
+    options: AdminBypassOptions,
+    operation: () => Promise<T>
+  ): Promise<AdminOperationResult<T>> {
+    // Security: Verify admin privileges
+    if (!this.isAdmin()) {
+      return {
+        success: false,
+        error: new Error('Admin privileges required for RLS bypass'),
+        bypassDuration: 0,
+      }
+    }
+
+    // Security: Validate and cap bypass duration
+    const maxDuration = Math.min(
+      options.maxDuration || DEFAULT_BYPASS_DURATION,
+      MAX_BYPASS_DURATION
+    )
+
+    // Record start time
+    const startTime = Date.now()
+
+    // Activate bypass
+    this.context.isBypassed = true
+    this.context.bypassReason = options.reason
+
+    // Set up safety timeout to auto-clear bypass
+    this.bypassTimeout = setTimeout(() => {
+      this.deactivateBypass()
+    }, maxDuration)
+
+    // Notify bypass start
+    if (options.onBypassStart) {
+      options.onBypassStart(this.getContext())
+    }
+
+    try {
+      // Set PostgreSQL session to bypass RLS
+      // Using a special "admin mode" session variable
+      await this.pglite.exec(`SET app.rls_bypass = 'true'`)
+      await this.pglite.exec(`SET app.bypass_reason = '${options.reason.replace(/'/g, "''")}'`)
+
+      // Execute the operation
+      const data = await operation()
+
+      return {
+        success: true,
+        data,
+        bypassDuration: Date.now() - startTime,
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(String(error)),
+        bypassDuration: Date.now() - startTime,
+      }
+    } finally {
+      // Always deactivate bypass
+      await this.deactivateBypass()
+
+      // Notify bypass end
+      if (options.onBypassEnd) {
+        options.onBypassEnd(this.getContext())
+      }
+    }
+  }
+
+  /**
+   * Deactivate RLS bypass
+   */
+  private async deactivateBypass(): Promise<void> {
+    // Clear safety timeout
+    if (this.bypassTimeout) {
+      clearTimeout(this.bypassTimeout)
+      this.bypassTimeout = null
+    }
+
+    // Reset bypass session variables
+    try {
+      await this.pglite.exec(`RESET app.rls_bypass`)
+      await this.pglite.exec(`RESET app.bypass_reason`)
+    } catch {
+      // Ignore errors during cleanup
+    }
+
+    // Update context
+    this.context.isBypassed = false
+    delete this.context.bypassReason
+  }
+
+  /**
+   * Dispose of the context manager
+   */
+  dispose(): void {
+    if (this.bypassTimeout) {
+      clearTimeout(this.bypassTimeout)
+      this.bypassTimeout = null
+    }
+  }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Create an RLS policy expression that checks for admin bypass.
+ *
+ * Use this in your policy USING clauses to allow admins to bypass RLS:
+ *
+ * @example
+ * ```sql
+ * CREATE POLICY tenant_isolation ON orders
+ *   AS PERMISSIVE
+ *   FOR ALL
+ *   TO public
+ *   USING (
+ *     current_setting('app.rls_bypass', true) = 'true'
+ *     OR tenant_id = current_setting('app.tenant_id')::uuid
+ *   );
+ * ```
+ *
+ * @returns SQL expression for admin bypass check
+ */
+export function createAdminBypassCheck(): string {
+  return `current_setting('app.rls_bypass', true) = 'true'`
+}
+
+/**
+ * Create an RLS policy expression with admin bypass and tenant isolation.
+ *
+ * @param tenantColumn - Name of the tenant column
+ * @param sessionVariable - Session variable containing tenant ID (default: 'app.tenant_id')
+ * @returns SQL expression for policy USING clause
+ *
+ * @example
+ * ```typescript
+ * const using = createTenantPolicyWithBypass('tenant_id')
+ * // Returns: "current_setting('app.rls_bypass', true) = 'true' OR tenant_id = current_setting('app.tenant_id')::text"
+ * ```
+ */
+export function createTenantPolicyWithBypass(
+  tenantColumn: string,
+  sessionVariable = 'app.tenant_id'
+): string {
+  return `${createAdminBypassCheck()} OR ${tenantColumn} = current_setting('${sessionVariable}')::text`
+}
+
+/**
+ * Create an RLS policy expression for owner-based access with admin bypass.
+ *
+ * @param ownerColumn - Name of the owner/user column
+ * @param sessionVariable - Session variable containing user ID (default: 'app.user_id')
+ * @returns SQL expression for policy USING clause
+ *
+ * @example
+ * ```typescript
+ * const using = createOwnerPolicyWithBypass('user_id')
+ * // Returns: "current_setting('app.rls_bypass', true) = 'true' OR user_id = current_setting('app.user_id')::text"
+ * ```
+ */
+export function createOwnerPolicyWithBypass(
+  ownerColumn: string,
+  sessionVariable = 'app.user_id'
+): string {
+  return `${createAdminBypassCheck()} OR ${ownerColumn} = current_setting('${sessionVariable}')::text`
+}
+
+/**
+ * Validate that a user has the required role.
+ *
+ * @param user - User to check
+ * @param requiredRole - Role that must be present
+ * @returns true if user has the required role
+ */
+export function hasRole(user: RLSUser, requiredRole: string): boolean {
+  if (!user.roles) return false
+  return user.roles.includes(requiredRole)
+}
+
+/**
+ * Validate that a user has any of the required roles.
+ *
+ * @param user - User to check
+ * @param requiredRoles - Array of acceptable roles
+ * @returns true if user has any of the required roles
+ */
+export function hasAnyRole(user: RLSUser, requiredRoles: string[]): boolean {
+  if (!user.roles) return false
+  return requiredRoles.some((role) => user.roles?.includes(role))
+}
+
+/**
+ * Validate that a user has all of the required roles.
+ *
+ * @param user - User to check
+ * @param requiredRoles - Array of required roles
+ * @returns true if user has all required roles
+ */
+export function hasAllRoles(user: RLSUser, requiredRoles: string[]): boolean {
+  if (!user.roles) return false
+  return requiredRoles.every((role) => user.roles?.includes(role))
+}