@dotdo/postgres 0.1.0

package/dist/rls/auth-integration.d.ts

@@ -0,0 +1,280 @@
+/**
+ * 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';
+/**
+ * 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;
+}
+/**
+ * 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 declare class RLSContextManager {
+    private pglite;
+    private context;
+    private bypassTimeout;
+    constructor(pglite: PGliteLike);
+    /**
+     * Get the current RLS context state
+     */
+    getContext(): Readonly<RLSContext>;
+    /**
+     * Check if the current user has admin privileges
+     */
+    isAdmin(): boolean;
+    /**
+     * Check if RLS is currently bypassed
+     */
+    isBypassed(): boolean;
+    /**
+     * 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']
+     * })
+     * ```
+     */
+    setupFromAuth(user: RLSUser, options?: SetupRLSFromAuthOptions): Promise<void>;
+    /**
+     * Clear the current RLS context.
+     *
+     * Resets all session variables to their defaults, removing any
+     * user-specific filtering from subsequent queries.
+     *
+     * @param options - Configuration options
+     */
+    clearContext(options?: SetTenantContextOptions): Promise<void>;
+    /**
+     * 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')
+     * }
+     * ```
+     */
+    withAdminBypass<T>(options: AdminBypassOptions, operation: () => Promise<T>): Promise<AdminOperationResult<T>>;
+    /**
+     * Deactivate RLS bypass
+     */
+    private deactivateBypass;
+    /**
+     * Dispose of the context manager
+     */
+    dispose(): void;
+}
+/**
+ * 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 declare function createAdminBypassCheck(): string;
+/**
+ * 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 declare function createTenantPolicyWithBypass(tenantColumn: string, sessionVariable?: string): string;
+/**
+ * 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 declare function createOwnerPolicyWithBypass(ownerColumn: string, sessionVariable?: string): string;
+/**
+ * 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 declare function hasRole(user: RLSUser, requiredRole: string): boolean;
+/**
+ * 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 declare function hasAnyRole(user: RLSUser, requiredRoles: string[]): boolean;
+/**
+ * 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 declare function hasAllRoles(user: RLSUser, requiredRoles: string[]): boolean;
+//# sourceMappingURL=auth-integration.d.ts.map

package/dist/rls/auth-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-integration.d.ts","sourceRoot":"","sources":["../../src/rls/auth-integration.ts"],"names":[],"mappings":"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"}

package/dist/rls/auth-integration.js

@@ -0,0 +1,399 @@
+/**
+ * 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 { setTenantContext, clearTenantContext } from './index';
+import { validateTenantId } from './validator';
+// ============================================================================
+// 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 {
+    pglite;
+    context;
+    bypassTimeout = null;
+    constructor(pglite) {
+        this.pglite = pglite;
+        this.context = {
+            user: null,
+            tenantId: null,
+            isBypassed: false,
+        };
+    }
+    /**
+     * Get the current RLS context state
+     */
+    getContext() {
+        return { ...this.context };
+    }
+    /**
+     * Check if the current user has admin privileges
+     */
+    isAdmin() {
+        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() {
+        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, options) {
+        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) {
+        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(options, operation) {
+        // 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
+     */
+    async deactivateBypass() {
+        // 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() {
+        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() {
+    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, sessionVariable = 'app.tenant_id') {
+    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, sessionVariable = 'app.user_id') {
+    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, requiredRole) {
+    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, requiredRoles) {
+    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, requiredRoles) {
+    if (!user.roles)
+        return false;
+    return requiredRoles.every((role) => user.roles?.includes(role));
+}
+//# sourceMappingURL=auth-integration.js.map

package/dist/rls/auth-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-integration.js","sourceRoot":"","sources":["../../src/rls/auth-integration.ts"],"names":[],"mappings":"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"}