@kysera/rls 0.5.1

package/dist/index.d.ts

@@ -0,0 +1,705 @@
+import { R as RLSSchema, O as Operation, P as PolicyCondition, a as PolicyHints, b as PolicyDefinition, F as FilterCondition, T as TableRLSConfig, C as CompiledPolicy, c as CompiledFilterPolicy, d as RLSContext, e as RLSAuthContext, f as RLSRequestContext, g as PolicyEvaluationContext } from './types-Dtg6Lt1k.js';
+export { h as PolicyType } from './types-Dtg6Lt1k.js';
+import { KyseraLogger, ErrorCode } from '@kysera/core';
+import { Plugin } from '@kysera/repository';
+import 'kysely';
+
+/**
+ * RLS schema definition and validation
+ *
+ * Provides functions to define, validate, and merge RLS schemas.
+ */
+
+/**
+ * Define RLS schema with full type safety
+ *
+ * @example
+ * ```typescript
+ * interface Database {
+ *   users: { id: number; email: string; tenant_id: number };
+ *   posts: { id: number; user_id: number; tenant_id: number };
+ * }
+ *
+ * const schema = defineRLSSchema<Database>({
+ *   users: {
+ *     policies: [
+ *       // Users can read their own records
+ *       allow('read', ctx => ctx.auth.userId === ctx.row.id),
+ *       // Filter by tenant
+ *       filter('read', ctx => ({ tenant_id: ctx.auth.tenantId })),
+ *       // Admins bypass all checks
+ *       allow('all', ctx => ctx.auth.roles.includes('admin')),
+ *     ],
+ *   },
+ *   posts: {
+ *     policies: [
+ *       // Filter posts by tenant
+ *       filter('read', ctx => ({ tenant_id: ctx.auth.tenantId })),
+ *       // Users can only edit their own posts
+ *       allow(['update', 'delete'], ctx => ctx.auth.userId === ctx.row.user_id),
+ *       // Validate new posts belong to user's tenant
+ *       validate('create', ctx => ctx.data.tenant_id === ctx.auth.tenantId),
+ *     ],
+ *     defaultDeny: true, // Require explicit allow
+ *   },
+ * });
+ * ```
+ */
+declare function defineRLSSchema<DB>(schema: RLSSchema<DB>): RLSSchema<DB>;
+/**
+ * Merge multiple RLS schemas
+ * Later schemas override earlier ones for the same table
+ *
+ * @example
+ * ```typescript
+ * const baseSchema = defineRLSSchema<Database>({
+ *   users: {
+ *     policies: [
+ *       filter('read', ctx => ({ tenant_id: ctx.auth.tenantId })),
+ *     ],
+ *   },
+ * });
+ *
+ * const adminSchema = defineRLSSchema<Database>({
+ *   users: {
+ *     policies: [
+ *       allow('all', ctx => ctx.auth.roles.includes('admin')),
+ *     ],
+ *   },
+ * });
+ *
+ * // Merged schema will have both filters and admin allow
+ * const merged = mergeRLSSchemas(baseSchema, adminSchema);
+ * ```
+ */
+declare function mergeRLSSchemas<DB>(...schemas: RLSSchema<DB>[]): RLSSchema<DB>;
+
+/**
+ * Fluent policy builders for Row-Level Security
+ *
+ * Provides intuitive builder functions for creating RLS policies:
+ * - allow: Grants access when condition is true
+ * - deny: Blocks access when condition is true (overrides allow)
+ * - filter: Adds WHERE conditions to SELECT queries
+ * - validate: Validates mutation data before execution
+ */
+
+/**
+ * Options for policy definitions
+ */
+interface PolicyOptions {
+    /** Policy name for debugging and identification */
+    name?: string;
+    /** Priority (higher runs first, deny policies default to 100) */
+    priority?: number;
+    /** Performance optimization hints */
+    hints?: PolicyHints;
+}
+/**
+ * Create an allow policy
+ * Grants access when condition evaluates to true
+ *
+ * @example
+ * ```typescript
+ * // Allow users to read their own records
+ * allow('read', ctx => ctx.auth.userId === ctx.row.userId)
+ *
+ * // Allow admins to do everything
+ * allow('all', ctx => ctx.auth.roles.includes('admin'))
+ *
+ * // Allow with multiple operations
+ * allow(['read', 'update'], ctx => ctx.auth.userId === ctx.row.userId)
+ *
+ * // Named policy with priority
+ * allow('read', ctx => ctx.auth.roles.includes('verified'), {
+ *   name: 'verified-users-only',
+ *   priority: 10
+ * })
+ * ```
+ */
+declare function allow(operation: Operation | Operation[], condition: PolicyCondition, options?: PolicyOptions): PolicyDefinition;
+/**
+ * Create a deny policy
+ * Blocks access when condition evaluates to true (overrides allow)
+ * If no condition is provided, always denies
+ *
+ * @example
+ * ```typescript
+ * // Deny access to banned users
+ * deny('all', ctx => ctx.auth.attributes?.banned === true)
+ *
+ * // Deny deletions on archived records
+ * deny('delete', ctx => ctx.row.archived === true)
+ *
+ * // Deny all access to sensitive table
+ * deny('all')
+ *
+ * // Named deny with high priority
+ * deny('all', ctx => ctx.auth.attributes?.suspended === true, {
+ *   name: 'block-suspended-users',
+ *   priority: 200
+ * })
+ * ```
+ */
+declare function deny(operation: Operation | Operation[], condition?: PolicyCondition, options?: PolicyOptions): PolicyDefinition;
+/**
+ * Create a filter policy
+ * Adds WHERE conditions to SELECT queries
+ *
+ * @example
+ * ```typescript
+ * // Filter by tenant
+ * filter('read', ctx => ({ tenant_id: ctx.auth.tenantId }))
+ *
+ * // Filter by organization with soft delete
+ * filter('read', ctx => ({
+ *   organization_id: ctx.auth.organizationIds?.[0],
+ *   deleted_at: null
+ * }))
+ *
+ * // Named filter
+ * filter('read', ctx => ({ tenant_id: ctx.auth.tenantId }), {
+ *   name: 'tenant-filter'
+ * })
+ * ```
+ */
+declare function filter(operation: 'read' | 'all', condition: FilterCondition, options?: PolicyOptions): PolicyDefinition;
+/**
+ * Create a validate policy
+ * Validates mutation data before execution
+ *
+ * @example
+ * ```typescript
+ * // Validate user can only set their own user_id
+ * validate('create', ctx => ctx.data.userId === ctx.auth.userId)
+ *
+ * // Validate status transitions
+ * validate('update', ctx => {
+ *   const { status } = ctx.data;
+ *   return !status || ['draft', 'published'].includes(status);
+ * })
+ *
+ * // Apply to both create and update
+ * validate('all', ctx => ctx.data.price >= 0)
+ *
+ * // Named validation
+ * validate('create', ctx => validateEmail(ctx.data.email), {
+ *   name: 'validate-email'
+ * })
+ * ```
+ */
+declare function validate(operation: 'create' | 'update' | 'all', condition: PolicyCondition, options?: PolicyOptions): PolicyDefinition;
+
+/**
+ * Policy Registry
+ * Central registry for managing RLS policies across all tables
+ *
+ * The PolicyRegistry compiles and stores RLS policies for efficient runtime lookup.
+ * It categorizes policies by type (allow/deny/filter/validate) and operation,
+ * and provides methods to query policies for specific tables and operations.
+ */
+
+/**
+ * Policy Registry
+ * Manages and provides access to RLS policies
+ */
+declare class PolicyRegistry<DB = unknown> {
+    private tables;
+    private compiled;
+    private logger;
+    constructor(schema?: RLSSchema<DB>, options?: {
+        logger?: KyseraLogger;
+    });
+    /**
+     * Load and compile policies from schema
+     *
+     * @example
+     * ```typescript
+     * const registry = new PolicyRegistry<Database>();
+     * registry.loadSchema({
+     *   users: {
+     *     policies: [
+     *       allow('read', ctx => ctx.auth.userId === ctx.row.id),
+     *       filter('read', ctx => ({ tenant_id: ctx.auth.tenantId })),
+     *     ],
+     *     defaultDeny: true,
+     *   },
+     * });
+     * ```
+     */
+    loadSchema(schema: RLSSchema<DB>): void;
+    /**
+     * Register policies for a single table
+     *
+     * @param table - Table name
+     * @param config - Table RLS configuration
+     */
+    registerTable(table: string, config: TableRLSConfig): void;
+    /**
+     * Register policies - supports both schema and table-based registration
+     *
+     * @overload Register a full schema
+     * @overload Register policies for a single table (deprecated)
+     */
+    register(schemaOrTable: RLSSchema<DB>): void;
+    register(schemaOrTable: keyof DB & string, policies: PolicyDefinition[], options?: {
+        skipFor?: string[];
+        defaultDeny?: boolean;
+    }): void;
+    /**
+     * Compile a policy definition into an internal compiled policy
+     *
+     * @param policy - Policy definition to compile
+     * @param name - Policy name for debugging
+     * @returns Compiled policy ready for evaluation
+     */
+    private compilePolicy;
+    /**
+     * Compile a filter policy
+     *
+     * @param policy - Filter policy definition
+     * @param name - Policy name for debugging
+     * @returns Compiled filter policy
+     */
+    private compileFilterPolicy;
+    /**
+     * Convert internal compiled policy to public CompiledPolicy
+     */
+    private toCompiledPolicy;
+    /**
+     * Get allow policies for a table and operation
+     */
+    getAllows(table: string, operation: Operation): CompiledPolicy[];
+    /**
+     * Get deny policies for a table and operation
+     */
+    getDenies(table: string, operation: Operation): CompiledPolicy[];
+    /**
+     * Get validate policies for a table and operation
+     */
+    getValidates(table: string, operation: Operation): CompiledPolicy[];
+    /**
+     * Get filter policies for a table
+     */
+    getFilters(table: string): CompiledFilterPolicy[];
+    /**
+     * Get roles that skip RLS for a table
+     */
+    getSkipFor(table: string): string[];
+    /**
+     * Check if table has default deny
+     */
+    hasDefaultDeny(table: string): boolean;
+    /**
+     * Check if a table is registered
+     */
+    hasTable(table: string): boolean;
+    /**
+     * Get all registered table names
+     */
+    getTables(): string[];
+    /**
+     * Check if registry is compiled
+     */
+    isCompiled(): boolean;
+    /**
+     * Validate that all policies are properly defined
+     *
+     * This method checks for common issues:
+     * - Tables with no policies and defaultDeny=false (warns)
+     * - Tables with skipFor operations but no corresponding policies
+     */
+    validate(): void;
+    /**
+     * Clear all policies
+     */
+    clear(): void;
+    /**
+     * Remove policies for a specific table
+     */
+    remove(table: string): void;
+}
+
+/**
+ * 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
+ */
+
+/**
+ * RLS-specific error codes
+ *
+ * These codes extend the unified error codes from @kysera/core with
+ * RLS-specific error conditions.
+ */
+declare const RLSErrorCodes: {
+    /** RLS context is missing or not set */
+    readonly RLS_CONTEXT_MISSING: ErrorCode;
+    /** RLS policy violation occurred */
+    readonly RLS_POLICY_VIOLATION: ErrorCode;
+    /** RLS policy definition is invalid */
+    readonly RLS_POLICY_INVALID: ErrorCode;
+    /** RLS schema definition is invalid */
+    readonly RLS_SCHEMA_INVALID: ErrorCode;
+    /** RLS context validation failed */
+    readonly RLS_CONTEXT_INVALID: ErrorCode;
+};
+/**
+ * Type for RLS error codes
+ */
+type RLSErrorCode = typeof RLSErrorCodes[keyof typeof RLSErrorCodes];
+/**
+ * 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);
+ * ```
+ */
+declare class RLSError extends Error {
+    readonly code: RLSErrorCode;
+    /**
+     * Creates a new RLS error
+     *
+     * @param message - Error message
+     * @param code - RLS error code
+     */
+    constructor(message: string, code: RLSErrorCode);
+    /**
+     * Serializes the error to JSON
+     *
+     * @returns JSON representation of the error
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * 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();
+ * });
+ * ```
+ */
+declare class RLSContextError extends RLSError {
+    /**
+     * Creates a new RLS context error
+     *
+     * @param message - Error message (defaults to standard message)
+     */
+    constructor(message?: string);
+}
+/**
+ * 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);
+ * ```
+ */
+declare class RLSContextValidationError extends RLSError {
+    readonly field: string;
+    /**
+     * Creates a new context validation error
+     *
+     * @param message - Error message
+     * @param field - Field that failed validation
+     */
+    constructor(message: string, field: string);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * 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'
+ * );
+ * ```
+ */
+declare class RLSPolicyViolation extends RLSError {
+    readonly operation: string;
+    readonly table: string;
+    readonly reason: string;
+    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);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * 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);
+ * ```
+ */
+declare class RLSSchemaError extends RLSError {
+    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>);
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * RLS Plugin for Kysera Repository
+ *
+ * Implements Row-Level Security as a Kysera plugin, providing:
+ * - Automatic query filtering for SELECT operations
+ * - Policy enforcement for CREATE, UPDATE, DELETE operations
+ * - Repository method extensions for RLS-aware operations
+ * - System context bypass for privileged operations
+ *
+ * @module @kysera/rls
+ */
+
+/**
+ * RLS Plugin configuration options
+ */
+interface RLSPluginOptions<DB = unknown> {
+    /** RLS policy schema */
+    schema: RLSSchema<DB>;
+    /** Tables to skip RLS for (always bypass policies) */
+    skipTables?: string[];
+    /** Roles that bypass RLS entirely (e.g., ['admin', 'superuser']) */
+    bypassRoles?: string[];
+    /** Logger instance for RLS operations */
+    logger?: KyseraLogger;
+    /** Require RLS context for all operations (throws if missing) */
+    requireContext?: boolean;
+    /** Enable audit logging of policy decisions */
+    auditDecisions?: boolean;
+    /** Custom error handler for policy violations */
+    onViolation?: (violation: RLSPolicyViolation) => void;
+}
+/**
+ * Create RLS plugin for Kysera
+ *
+ * The RLS plugin provides declarative row-level security for your database operations.
+ * It automatically filters SELECT queries and validates mutations (CREATE, UPDATE, DELETE)
+ * against your policy schema.
+ *
+ * @example
+ * ```typescript
+ * import { rlsPlugin, defineRLSSchema, allow, filter } from '@kysera/rls';
+ * import { createORM } from '@kysera/repository';
+ *
+ * // Define your RLS schema
+ * const schema = defineRLSSchema<Database>({
+ *   resources: {
+ *     policies: [
+ *       // Filter reads by tenant
+ *       filter('read', ctx => ({ tenant_id: ctx.auth.tenantId })),
+ *       // Allow updates for resource owners
+ *       allow('update', ctx => ctx.auth.userId === ctx.row.owner_id),
+ *       // Validate creates belong to user's tenant
+ *       validate('create', ctx => ctx.data.tenant_id === ctx.auth.tenantId),
+ *     ],
+ *   },
+ * });
+ *
+ * // Create ORM with RLS plugin
+ * const orm = await createORM(db, [
+ *   rlsPlugin({ schema }),
+ * ]);
+ *
+ * // Use within RLS context
+ * await rlsContext.runAsync(
+ *   {
+ *     auth: { userId: 1, tenantId: 100, roles: ['user'], isSystem: false },
+ *     timestamp: new Date(),
+ *   },
+ *   async () => {
+ *     // All queries automatically filtered by tenant_id
+ *     const resources = await orm.resources.findAll();
+ *   }
+ * );
+ * ```
+ *
+ * @param options - Plugin configuration options
+ * @returns Kysera plugin instance
+ */
+declare function rlsPlugin<DB>(options: RLSPluginOptions<DB>): Plugin;
+
+/**
+ * Options for creating RLS context
+ */
+interface CreateRLSContextOptions<TUser = unknown, TMeta = unknown> {
+    auth: RLSAuthContext<TUser>;
+    request?: Partial<RLSRequestContext>;
+    meta?: TMeta;
+}
+/**
+ * Create a new RLS context
+ */
+declare function createRLSContext<TUser = unknown, TMeta = unknown>(options: CreateRLSContextOptions<TUser, TMeta>): RLSContext<TUser, TMeta>;
+/**
+ * RLS Context Manager
+ * Manages RLS context using AsyncLocalStorage for automatic propagation
+ */
+declare class RLSContextManager {
+    /**
+     * Run a synchronous function within an RLS context
+     */
+    run<T>(context: RLSContext, fn: () => T): T;
+    /**
+     * Run an async function within an RLS context
+     */
+    runAsync<T>(context: RLSContext, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get current RLS context
+     * @throws RLSContextError if no context is set
+     */
+    getContext(): RLSContext;
+    /**
+     * Get current RLS context or null if not set
+     */
+    getContextOrNull(): RLSContext | null;
+    /**
+     * Check if running within RLS context
+     */
+    hasContext(): boolean;
+    /**
+     * Get current auth context
+     * @throws RLSContextError if no context is set
+     */
+    getAuth(): RLSAuthContext;
+    /**
+     * Get current user ID
+     * @throws RLSContextError if no context is set
+     */
+    getUserId(): string | number;
+    /**
+     * Get current tenant ID
+     * @throws RLSContextError if no context is set
+     */
+    getTenantId(): string | number | undefined;
+    /**
+     * Check if current user has a specific role
+     */
+    hasRole(role: string): boolean;
+    /**
+     * Check if current user has a specific permission
+     */
+    hasPermission(permission: string): boolean;
+    /**
+     * Check if current context is a system context (bypasses RLS)
+     */
+    isSystem(): boolean;
+    /**
+     * Create a system context for operations that should bypass RLS
+     */
+    asSystem<T>(fn: () => T): T;
+    /**
+     * Create a system context for async operations
+     */
+    asSystemAsync<T>(fn: () => Promise<T>): Promise<T>;
+}
+declare const rlsContext: RLSContextManager;
+/**
+ * Convenience function to run code within RLS context
+ */
+declare function withRLSContext<T>(context: RLSContext, fn: () => T): T;
+/**
+ * Convenience function to run async code within RLS context
+ */
+declare function withRLSContextAsync<T>(context: RLSContext, fn: () => Promise<T>): Promise<T>;
+
+/**
+ * Utility helper functions for RLS
+ */
+
+/**
+ * Create a policy evaluation context from RLS context
+ */
+declare function createEvaluationContext<TRow = unknown, TData = unknown>(rlsCtx: RLSContext, options?: {
+    row?: TRow;
+    data?: TData;
+}): PolicyEvaluationContext<unknown, TRow, TData>;
+/**
+ * Check if a condition function is async
+ */
+declare function isAsyncFunction(fn: unknown): fn is (...args: unknown[]) => Promise<unknown>;
+/**
+ * Safely evaluate a policy condition
+ */
+declare function safeEvaluate<T>(fn: () => T | Promise<T>, defaultValue: T): Promise<T>;
+/**
+ * Deep merge two objects
+ */
+declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T;
+/**
+ * Create a simple hash for cache keys
+ */
+declare function hashString(str: string): string;
+/**
+ * Normalize operations to array format
+ */
+declare function normalizeOperations(operation: Operation | Operation[]): Operation[];
+
+export { CompiledFilterPolicy, CompiledPolicy, type CreateRLSContextOptions, FilterCondition, Operation, PolicyCondition, PolicyDefinition, PolicyEvaluationContext, PolicyHints, type PolicyOptions, PolicyRegistry, RLSAuthContext, RLSContext, RLSContextError, RLSContextValidationError, RLSError, type RLSErrorCode, RLSErrorCodes, type RLSPluginOptions, RLSPolicyViolation, RLSRequestContext, RLSSchema, RLSSchemaError, TableRLSConfig, allow, createEvaluationContext, createRLSContext, deepMerge, defineRLSSchema, deny, filter, hashString, isAsyncFunction, mergeRLSSchemas, normalizeOperations, rlsContext, rlsPlugin, safeEvaluate, validate, withRLSContext, withRLSContextAsync };