@kysera/rls 0.8.1 → 0.8.2

package/src/policy/builder.ts

@@ -10,10 +10,11 @@
 
 import type {
   Operation,
-  PolicyDefinition,
   PolicyCondition,
   FilterCondition,
-  PolicyHints
+  PolicyHints,
+  PolicyActivationCondition,
+  ConditionalPolicyDefinition
 } from './types.js'
 
 /**
@@ -26,6 +27,24 @@ export interface PolicyOptions {
   priority?: number
   /** Performance optimization hints */
   hints?: PolicyHints
+  /**
+   * Condition that determines if this policy is active
+   * The policy will only be evaluated if this returns true
+   *
+   * @example
+   * ```typescript
+   * // Only apply in production
+   * allow('read', () => true, {
+   *   condition: ctx => ctx.meta?.environment === 'production'
+   * })
+   *
+   * // Feature-gated policy
+   * filter('read', ctx => ({ strict: true }), {
+   *   condition: ctx => ctx.meta?.features?.strictMode
+   * })
+   * ```
+   */
+  condition?: PolicyActivationCondition
 }
 
 /**
@@ -54,8 +73,8 @@ export function allow(
   operation: Operation | Operation[],
   condition: PolicyCondition,
   options?: PolicyOptions
-): PolicyDefinition {
-  const policy: PolicyDefinition = {
+): ConditionalPolicyDefinition {
+  const policy: ConditionalPolicyDefinition = {
     type: 'allow',
     operation,
     condition: condition,
@@ -70,6 +89,10 @@ export function allow(
     policy.hints = options.hints
   }
 
+  if (options?.condition !== undefined) {
+    policy.activationCondition = options.condition
+  }
+
   return policy
 }
 
@@ -100,8 +123,8 @@ export function deny(
   operation: Operation | Operation[],
   condition?: PolicyCondition,
   options?: PolicyOptions
-): PolicyDefinition {
-  const policy: PolicyDefinition = {
+): ConditionalPolicyDefinition {
+  const policy: ConditionalPolicyDefinition = {
     type: 'deny',
     operation,
     condition: condition ?? (() => true),
@@ -116,6 +139,10 @@ export function deny(
     policy.hints = options.hints
   }
 
+  if (options?.condition !== undefined) {
+    policy.activationCondition = options.condition
+  }
+
   return policy
 }
 
@@ -159,8 +186,8 @@ export function filter(
   operation: 'read' | 'all',
   condition: FilterCondition,
   options?: PolicyOptions
-): PolicyDefinition {
-  const policy: PolicyDefinition = {
+): ConditionalPolicyDefinition {
+  const policy: ConditionalPolicyDefinition = {
     type: 'filter',
     operation: operation === 'all' ? 'read' : operation,
     condition: condition as unknown as PolicyCondition,
@@ -175,6 +202,10 @@ export function filter(
     policy.hints = options.hints
   }
 
+  if (options?.condition !== undefined) {
+    policy.activationCondition = options.condition
+  }
+
   return policy
 }
 
@@ -206,10 +237,10 @@ export function validate(
   operation: 'create' | 'update' | 'all',
   condition: PolicyCondition,
   options?: PolicyOptions
-): PolicyDefinition {
+): ConditionalPolicyDefinition {
   const ops: Operation[] = operation === 'all' ? ['create', 'update'] : [operation]
 
-  const policy: PolicyDefinition = {
+  const policy: ConditionalPolicyDefinition = {
     type: 'validate',
     operation: ops,
     condition: condition,
@@ -224,5 +255,151 @@ export function validate(
     policy.hints = options.hints
   }
 
+  if (options?.condition !== undefined) {
+    policy.activationCondition = options.condition
+  }
+
+  return policy
+}
+
+// ============================================================================
+// Conditional Policy Helpers
+// ============================================================================
+
+/**
+ * Create a policy that is only active in specific environments
+ *
+ * @param environments - Environments where the policy is active
+ * @param policyFn - Function that creates the policy
+ * @returns Policy with environment condition
+ *
+ * @example
+ * ```typescript
+ * // Policy only active in production
+ * const prodPolicy = whenEnvironment(['production'], () =>
+ *   allow('read', () => true, { name: 'prod-read' })
+ * );
+ *
+ * // Policy active in staging and production
+ * const nonDevPolicy = whenEnvironment(['staging', 'production'], () =>
+ *   filter('read', ctx => ({ tenant_id: ctx.auth.tenantId }))
+ * );
+ * ```
+ */
+export function whenEnvironment(
+  environments: string[],
+  policyFn: () => ConditionalPolicyDefinition
+): ConditionalPolicyDefinition {
+  const policy = policyFn()
+  const existingCondition = policy.activationCondition
+  policy.activationCondition = ctx => {
+    const envMatch = environments.includes(ctx.environment ?? '')
+    if (!envMatch) return false
+    // If there was an existing condition (from inner wrapper), it must also pass
+    return existingCondition ? existingCondition(ctx) : true
+  }
+  return policy
+}
+
+/**
+ * Create a policy that is only active when a feature flag is enabled
+ *
+ * @param feature - Feature flag name
+ * @param policyFn - Function that creates the policy
+ * @returns Policy with feature flag condition
+ *
+ * @example
+ * ```typescript
+ * // Policy only active when 'strict_rls' feature is enabled
+ * const strictPolicy = whenFeature('strict_rls', () =>
+ *   deny('delete', () => true, { name: 'strict-no-delete' })
+ * );
+ * ```
+ */
+export function whenFeature(
+  feature: string,
+  policyFn: () => ConditionalPolicyDefinition
+): ConditionalPolicyDefinition {
+  const policy = policyFn()
+  const existingCondition = policy.activationCondition
+  policy.activationCondition = ctx => {
+    let featureEnabled = false
+    if (Array.isArray(ctx.features)) {
+      featureEnabled = ctx.features.includes(feature)
+    } else if (ctx.features && typeof ctx.features === 'object' && 'has' in ctx.features) {
+      // Support Set<string>
+      featureEnabled = (ctx.features as Set<string>).has(feature)
+    } else if (ctx.features && typeof ctx.features === 'object') {
+      // Support object-style features: { feature_name: boolean }
+      featureEnabled = !!(ctx.features as Record<string, unknown>)[feature]
+    }
+    if (!featureEnabled) return false
+    // If there was an existing condition (from inner wrapper), it must also pass
+    return existingCondition ? existingCondition(ctx) : true
+  }
+  return policy
+}
+
+/**
+ * Create a policy that is only active during specific hours
+ *
+ * @param startHour - Start hour (0-23)
+ * @param endHour - End hour (0-23)
+ * @param policyFn - Function that creates the policy
+ * @returns Policy with time-based condition
+ *
+ * @example
+ * ```typescript
+ * // Policy only active during business hours (9 AM - 5 PM)
+ * const businessHoursPolicy = whenTimeRange(9, 17, () =>
+ *   allow('update', () => true, { name: 'business-hours-update' })
+ * );
+ * ```
+ */
+export function whenTimeRange(
+  startHour: number,
+  endHour: number,
+  policyFn: () => ConditionalPolicyDefinition
+): ConditionalPolicyDefinition {
+  const policy = policyFn()
+  const existingCondition = policy.activationCondition
+  policy.activationCondition = ctx => {
+    const hour = (ctx.timestamp ?? new Date()).getHours()
+    let inRange: boolean
+    // Handle midnight crossing (e.g., 22:00 to 06:00)
+    if (startHour > endHour) {
+      inRange = hour >= startHour || hour < endHour
+    } else {
+      inRange = hour >= startHour && hour < endHour
+    }
+    if (!inRange) return false
+    // If there was an existing condition (from inner wrapper), it must also pass
+    return existingCondition ? existingCondition(ctx) : true
+  }
+  return policy
+}
+
+/**
+ * Create a policy that is only active when a custom condition is met
+ *
+ * @param condition - Custom activation condition
+ * @param policyFn - Function that creates the policy
+ * @returns Policy with custom condition
+ *
+ * @example
+ * ```typescript
+ * // Policy only active when user is in beta program
+ * const betaPolicy = whenCondition(
+ *   ctx => ctx.meta?.betaUser === true,
+ *   () => allow('read', () => true, { name: 'beta-read' })
+ * );
+ * ```
+ */
+export function whenCondition(
+  condition: PolicyActivationCondition,
+  policyFn: () => ConditionalPolicyDefinition
+): ConditionalPolicyDefinition {
+  const policy = policyFn()
+  policy.activationCondition = condition
   return policy
 }

package/src/policy/types.ts

@@ -751,4 +751,88 @@ export interface PolicyHints {
    * Stable policies can be cached during a query execution
    */
   stable?: boolean
+
+  /**
+   * Whether the policy condition can be async
+   * @internal Used by validation and allow/deny policies
+   */
+  async?: boolean
+
+  /**
+   * Whether the policy result is cacheable
+   */
+  cacheable?: boolean
+
+  /**
+   * Cache TTL in seconds if cacheable
+   */
+  cacheTTL?: number
+}
+
+// ============================================================================
+// Conditional Policy Activation
+// ============================================================================
+
+/**
+ * Context for evaluating policy activation conditions
+ *
+ * Contains metadata about the current environment that determines
+ * whether a policy should be active.
+ */
+export interface PolicyActivationContext {
+  /**
+   * Current environment (development, staging, production)
+   */
+  environment?: string
+
+  /**
+   * Feature flags that are enabled
+   * Can be a Set, array, or object with boolean/truthy values
+   */
+  features?: Set<string> | string[] | Record<string, unknown>
+
+  /**
+   * Current timestamp (for time-based policies)
+   */
+  timestamp?: Date
+
+  /**
+   * Custom metadata for activation decisions
+   */
+  meta?: Record<string, unknown>
+}
+
+/**
+ * Condition function for policy activation
+ *
+ * Returns true if the policy should be active, false otherwise.
+ *
+ * @example
+ * ```typescript
+ * // Only active in production
+ * const productionOnly: PolicyActivationCondition = ctx =>
+ *   ctx.environment === 'production';
+ *
+ * // Only active when feature flag is enabled
+ * const featureGated: PolicyActivationCondition = ctx =>
+ *   ctx.features?.includes('new_security_policy') ?? false;
+ *
+ * // Time-based activation (active during business hours)
+ * const businessHours: PolicyActivationCondition = ctx => {
+ *   const hour = (ctx.timestamp ?? new Date()).getHours();
+ *   return hour >= 9 && hour < 17;
+ * };
+ * ```
+ */
+export type PolicyActivationCondition = (ctx: PolicyActivationContext) => boolean
+
+/**
+ * Extended policy definition with activation condition
+ */
+export interface ConditionalPolicyDefinition extends PolicyDefinition {
+  /**
+   * Condition that determines if this policy is active
+   * If undefined, the policy is always active
+   */
+  activationCondition?: PolicyActivationCondition
 }

package/src/rebac/index.ts

@@ -0,0 +1,30 @@
+/**
+ * ReBAC (Relationship-Based Access Control) Module
+ *
+ * Provides relationship-based filtering for RLS policies.
+ *
+ * @module @kysera/rls/rebac
+ */
+
+// Types
+export type {
+  RelationshipStep,
+  RelationshipPath,
+  RelationshipCondition,
+  ReBAcPolicyDefinition,
+  TableReBAcConfig,
+  ReBAcSchema,
+  CompiledRelationshipPath,
+  CompiledReBAcPolicy,
+  ReBAcSubquery,
+  ReBAcQueryOptions
+} from './types.js'
+
+// Predefined path patterns
+export { orgMembershipPath, shopOrgMembershipPath, teamHierarchyPath } from './types.js'
+
+// Registry
+export { ReBAcRegistry, createReBAcRegistry } from './registry.js'
+
+// Transformer
+export { ReBAcTransformer, createReBAcTransformer, allowRelation, denyRelation } from './transformer.js'

package/src/rebac/registry.ts

@@ -0,0 +1,303 @@
+/**
+ * ReBAC Policy Registry
+ *
+ * Manages relationship definitions and ReBAC policies for RLS.
+ *
+ * @module @kysera/rls/rebac/registry
+ */
+
+import type {
+  RelationshipPath,
+  RelationshipStep,
+  ReBAcPolicyDefinition,
+  ReBAcSchema,
+  TableReBAcConfig,
+  CompiledRelationshipPath,
+  CompiledReBAcPolicy
+} from './types.js'
+import type { PolicyEvaluationContext, Operation } from '../policy/types.js'
+import { RLSSchemaError } from '../errors.js'
+import { silentLogger, type KyseraLogger } from '@kysera/core'
+
+// ============================================================================
+// ReBAC Registry
+// ============================================================================
+
+/**
+ * Internal compiled table configuration
+ */
+interface TableReBAcCompiled {
+  relationships: Map<string, CompiledRelationshipPath>
+  policies: CompiledReBAcPolicy[]
+}
+
+/**
+ * ReBAC Registry
+ *
+ * Manages relationship paths and ReBAC policies across tables.
+ *
+ * @example
+ * ```typescript
+ * const registry = new ReBAcRegistry();
+ *
+ * // Register relationship paths and policies
+ * registry.loadSchema({
+ *   products: {
+ *     relationships: [
+ *       shopOrgMembershipPath('products', 'shop_id')
+ *     ],
+ *     policies: [
+ *       {
+ *         type: 'filter',
+ *         operation: 'read',
+ *         relationshipPath: 'products_shop_org_membership',
+ *         endCondition: ctx => ({
+ *           user_id: ctx.auth.userId,
+ *           status: 'active'
+ *         })
+ *       }
+ *     ]
+ *   }
+ * });
+ *
+ * // Get policies for a table
+ * const policies = registry.getPolicies('products', 'read');
+ * ```
+ */
+export class ReBAcRegistry<DB = unknown> {
+  private tables = new Map<string, TableReBAcCompiled>()
+  private globalRelationships = new Map<string, CompiledRelationshipPath>()
+  private logger: KyseraLogger
+
+  constructor(schema?: ReBAcSchema<DB>, options?: { logger?: KyseraLogger }) {
+    this.logger = options?.logger ?? silentLogger
+    if (schema) {
+      this.loadSchema(schema)
+    }
+  }
+
+  /**
+   * Load ReBAC schema
+   */
+  loadSchema(schema: ReBAcSchema<DB>): void {
+    for (const [table, config] of Object.entries(schema)) {
+      if (!config) continue
+      this.registerTable(table, config as TableReBAcConfig)
+    }
+  }
+
+  /**
+   * Register ReBAC configuration for a single table
+   */
+  registerTable(table: string, config: TableReBAcConfig): void {
+    const compiled: TableReBAcCompiled = {
+      relationships: new Map(),
+      policies: []
+    }
+
+    // Compile relationships
+    for (const rel of config.relationships) {
+      const compiledPath = this.compileRelationshipPath(rel, table)
+      compiled.relationships.set(rel.name, compiledPath)
+      // Also register globally for cross-table references
+      this.globalRelationships.set(rel.name, compiledPath)
+    }
+
+    // Compile policies
+    for (let i = 0; i < config.policies.length; i++) {
+      const policy = config.policies[i]
+      if (!policy) continue
+
+      const policyName = policy.name ?? `${table}_rebac_policy_${i}`
+      const compiledPolicy = this.compilePolicy(policy, policyName, table, compiled.relationships)
+      compiled.policies.push(compiledPolicy)
+    }
+
+    // Sort by priority
+    compiled.policies.sort((a, b) => b.priority - a.priority)
+
+    this.tables.set(table, compiled)
+    this.logger.info?.(`[ReBAC] Registered table: ${table}`, {
+      relationships: config.relationships.length,
+      policies: config.policies.length
+    })
+  }
+
+  /**
+   * Register a global relationship path (available to all tables)
+   */
+  registerRelationship(path: RelationshipPath): void {
+    if (!path.steps.length) {
+      throw new RLSSchemaError(`Relationship path "${path.name}" has no steps`, {
+        path: path.name
+      })
+    }
+
+    const compiled = this.compileRelationshipPath(path, path.steps[0]!.from)
+    this.globalRelationships.set(path.name, compiled)
+  }
+
+  /**
+   * Get ReBAC policies for a table and operation
+   */
+  getPolicies(table: string, operation: Operation): CompiledReBAcPolicy[] {
+    const config = this.tables.get(table)
+    if (!config) return []
+
+    return config.policies.filter(p => p.operations.has(operation) || p.operations.has('all'))
+  }
+
+  /**
+   * Get a specific relationship path
+   */
+  getRelationship(name: string, table?: string): CompiledRelationshipPath | undefined {
+    // Check table-specific first
+    if (table) {
+      const tableConfig = this.tables.get(table)
+      const tablePath = tableConfig?.relationships.get(name)
+      if (tablePath) return tablePath
+    }
+
+    // Fall back to global
+    return this.globalRelationships.get(name)
+  }
+
+  /**
+   * Check if table has ReBAC configuration
+   */
+  hasTable(table: string): boolean {
+    return this.tables.has(table)
+  }
+
+  /**
+   * Get all registered table names
+   */
+  getTables(): string[] {
+    return Array.from(this.tables.keys())
+  }
+
+  /**
+   * Clear all registrations
+   */
+  clear(): void {
+    this.tables.clear()
+    this.globalRelationships.clear()
+  }
+
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+
+  /**
+   * Compile a relationship path definition
+   */
+  private compileRelationshipPath(path: RelationshipPath, sourceTable: string): CompiledRelationshipPath {
+    if (path.steps.length === 0) {
+      throw new RLSSchemaError(`Relationship path "${path.name}" must have at least one step`, {
+        path: path.name
+      })
+    }
+
+    const compiledSteps: Required<RelationshipStep>[] = path.steps.map((step, index) => {
+      // Validate step
+      if (!step.from || !step.to) {
+        throw new RLSSchemaError(
+          `Relationship step ${index} in "${path.name}" must have 'from' and 'to' tables`,
+          { path: path.name, step: index }
+        )
+      }
+
+      // Fill defaults
+      return {
+        from: step.from,
+        to: step.to,
+        fromColumn: step.fromColumn ?? `${step.to}_id`,
+        toColumn: step.toColumn ?? 'id',
+        alias: step.alias ?? step.to,
+        joinType: step.joinType ?? 'inner',
+        additionalConditions: step.additionalConditions ?? {}
+      }
+    })
+
+    // Validate chain continuity
+    for (let i = 1; i < compiledSteps.length; i++) {
+      const prevStep = compiledSteps[i - 1]!
+      const currentStep = compiledSteps[i]!
+
+      // Each step's 'from' should match previous step's 'to'
+      if (currentStep.from !== prevStep.to && currentStep.from !== prevStep.alias) {
+        throw new RLSSchemaError(
+          `Relationship path "${path.name}" has broken chain at step ${i}: ` +
+            `expected '${prevStep.to}' but got '${currentStep.from}'`,
+          { path: path.name, step: i }
+        )
+      }
+    }
+
+    const lastStep = compiledSteps[compiledSteps.length - 1]!
+
+    return {
+      name: path.name,
+      steps: compiledSteps,
+      sourceTable,
+      targetTable: lastStep.to
+    }
+  }
+
+  /**
+   * Compile a ReBAC policy definition
+   */
+  private compilePolicy(
+    policy: ReBAcPolicyDefinition,
+    name: string,
+    table: string,
+    tableRelationships: Map<string, CompiledRelationshipPath>
+  ): CompiledReBAcPolicy {
+    // Get relationship path
+    const relationshipPath =
+      tableRelationships.get(policy.relationshipPath) ??
+      this.globalRelationships.get(policy.relationshipPath)
+
+    if (!relationshipPath) {
+      throw new RLSSchemaError(
+        `ReBAC policy "${name}" references unknown relationship path "${policy.relationshipPath}"`,
+        { policy: name, table, relationshipPath: policy.relationshipPath }
+      )
+    }
+
+    // Normalize operations
+    const ops = Array.isArray(policy.operation) ? policy.operation : [policy.operation]
+    const expandedOps = ops.flatMap(op =>
+      op === 'all' ? ['read', 'create', 'update', 'delete'] : [op]
+    )
+
+    // Compile end condition
+    const getEndConditions =
+      typeof policy.endCondition === 'function'
+        ? policy.endCondition
+        : () => policy.endCondition as Record<string, unknown>
+
+    return {
+      name,
+      type: policy.policyType ?? 'allow',
+      operations: new Set(expandedOps),
+      relationshipPath,
+      getEndConditions: getEndConditions as (ctx: PolicyEvaluationContext) => Record<string, unknown>,
+      priority: policy.priority ?? 0
+    }
+  }
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/**
+ * Create a ReBAC registry
+ */
+export function createReBAcRegistry<DB = unknown>(
+  schema?: ReBAcSchema<DB>,
+  options?: { logger?: KyseraLogger }
+): ReBAcRegistry<DB> {
+  return new ReBAcRegistry<DB>(schema, options)
+}