@qwickapps/server 1.3.0 → 1.4.0

package/src/plugins/preferences/stores/postgres-store.ts

@@ -0,0 +1,252 @@
+/**
+ * PostgreSQL Preferences Store
+ *
+ * Preferences storage implementation using PostgreSQL with Row-Level Security (RLS).
+ * Requires the 'pg' package and the Users plugin to be installed.
+ *
+ * RLS Context Pattern:
+ * Each operation uses an explicit transaction and sets `app.current_user_id`
+ * as a transaction-local configuration variable. The RLS policy checks this
+ * variable to enforce that users can only access their own preferences.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  PreferencesStore,
+  PostgresPreferencesStoreConfig,
+} from '../types.js';
+
+// Pool interface (from pg package)
+interface PgPool {
+  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+  connect(): Promise<PgPoolClient>;
+}
+
+interface PgPoolClient {
+  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+  release(): void;
+}
+
+/**
+ * Deep merge two objects
+ * - Objects are recursively merged
+ * - Arrays are replaced (not merged)
+ * - Source values override target values
+ */
+export function deepMerge(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>
+): Record<string, unknown> {
+  const output = { ...target };
+
+  for (const key of Object.keys(source)) {
+    const sourceValue = source[key];
+    const targetValue = target[key];
+
+    // Skip undefined values in source
+    if (sourceValue === undefined) {
+      continue;
+    }
+
+    // If both are plain objects, merge recursively
+    if (
+      sourceValue !== null &&
+      typeof sourceValue === 'object' &&
+      !Array.isArray(sourceValue) &&
+      targetValue !== null &&
+      typeof targetValue === 'object' &&
+      !Array.isArray(targetValue)
+    ) {
+      output[key] = deepMerge(
+        targetValue as Record<string, unknown>,
+        sourceValue as Record<string, unknown>
+      );
+    } else {
+      // Otherwise, source overwrites target
+      output[key] = sourceValue;
+    }
+  }
+
+  return output;
+}
+
+/**
+ * Execute a function within an RLS-protected transaction
+ *
+ * This helper ensures that:
+ * 1. All queries run within the same transaction
+ * 2. The RLS context is set before any data access
+ * 3. The transaction is properly committed or rolled back
+ *
+ * @param pool PostgreSQL pool
+ * @param userId User ID to set as the RLS context
+ * @param callback Function to execute within the transaction
+ */
+async function withRLSContext<T>(
+  pool: PgPool,
+  userId: string,
+  callback: (client: PgPoolClient) => Promise<T>
+): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    // Set transaction-local user context for RLS
+    await client.query(
+      "SELECT set_config('app.current_user_id', $1, true)",
+      [userId]
+    );
+    const result = await callback(client);
+    await client.query('COMMIT');
+    return result;
+  } catch (error) {
+    await client.query('ROLLBACK');
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+/**
+ * Create a PostgreSQL preferences store with RLS
+ *
+ * @param config Configuration including a pg Pool instance
+ * @returns PreferencesStore implementation
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { postgresPreferencesStore } from '@qwickapps/server';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = postgresPreferencesStore({ pool });
+ *
+ * // Or with lazy initialization:
+ * const store = postgresPreferencesStore({ pool: () => getPostgres().getPool() });
+ * ```
+ */
+export function postgresPreferencesStore(config: PostgresPreferencesStoreConfig): PreferencesStore {
+  const {
+    pool: poolOrFn,
+    tableName = 'user_preferences',
+    schema = 'public',
+    autoCreateTables = true,
+    enableRLS = true,
+  } = config;
+
+  // Helper to get pool (supports lazy initialization via function)
+  const getPool = (): PgPool => {
+    const pool = typeof poolOrFn === 'function' ? poolOrFn() : poolOrFn;
+    if (!pool || typeof (pool as PgPool).query !== 'function') {
+      throw new Error('Invalid pool: must have query method');
+    }
+    return pool as PgPool;
+  };
+
+  const tableFullName = `"${schema}"."${tableName}"`;
+
+  return {
+    name: 'postgres',
+
+    async initialize(): Promise<void> {
+      if (!autoCreateTables) return;
+
+      const pool = getPool();
+
+      // Create table with foreign key to users
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS ${tableFullName} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id UUID NOT NULL REFERENCES "public"."users"(id) ON DELETE CASCADE,
+          preferences JSONB NOT NULL DEFAULT '{}',
+          created_at TIMESTAMPTZ DEFAULT NOW(),
+          updated_at TIMESTAMPTZ DEFAULT NOW(),
+          UNIQUE(user_id)
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_user_id ON ${tableFullName}(user_id);
+      `);
+
+      // Enable RLS if configured
+      if (enableRLS) {
+        await pool.query(`
+          ALTER TABLE ${tableFullName} ENABLE ROW LEVEL SECURITY;
+          ALTER TABLE ${tableFullName} FORCE ROW LEVEL SECURITY;
+        `);
+
+        // Create or replace the RLS policy
+        // Drop existing policy first to avoid errors on re-initialization
+        await pool.query(`
+          DROP POLICY IF EXISTS "${tableName}_owner" ON ${tableFullName};
+        `);
+
+        // RLS policy with both USING (for SELECT/UPDATE/DELETE reads)
+        // and WITH CHECK (for INSERT/UPDATE writes) clauses
+        await pool.query(`
+          CREATE POLICY "${tableName}_owner" ON ${tableFullName}
+            FOR ALL
+            USING (user_id::text = current_setting('app.current_user_id', true))
+            WITH CHECK (user_id::text = current_setting('app.current_user_id', true));
+        `);
+      }
+    },
+
+    async get(userId: string): Promise<Record<string, unknown> | null> {
+      return withRLSContext(getPool(), userId, async (client) => {
+        const result = await client.query(
+          `SELECT preferences FROM ${tableFullName} WHERE user_id = $1`,
+          [userId]
+        );
+
+        if (result.rows.length === 0) {
+          return null;
+        }
+
+        return (result.rows[0] as { preferences: Record<string, unknown> }).preferences;
+      });
+    },
+
+    async update(userId: string, preferences: Record<string, unknown>): Promise<Record<string, unknown>> {
+      return withRLSContext(getPool(), userId, async (client) => {
+        // Get existing preferences within the same transaction
+        const existingResult = await client.query(
+          `SELECT preferences FROM ${tableFullName} WHERE user_id = $1`,
+          [userId]
+        );
+
+        const existing = existingResult.rows.length > 0
+          ? (existingResult.rows[0] as { preferences: Record<string, unknown> }).preferences
+          : null;
+
+        const merged = existing ? deepMerge(existing, preferences) : preferences;
+
+        // Upsert the merged preferences
+        await client.query(
+          `INSERT INTO ${tableFullName} (user_id, preferences, updated_at)
+           VALUES ($1, $2, NOW())
+           ON CONFLICT (user_id) DO UPDATE SET
+             preferences = $2,
+             updated_at = NOW()`,
+          [userId, JSON.stringify(merged)]
+        );
+
+        return merged;
+      });
+    },
+
+    async delete(userId: string): Promise<boolean> {
+      return withRLSContext(getPool(), userId, async (client) => {
+        const result = await client.query(
+          `DELETE FROM ${tableFullName} WHERE user_id = $1`,
+          [userId]
+        );
+
+        return (result.rowCount ?? 0) > 0;
+      });
+    },
+
+    async shutdown(): Promise<void> {
+      // Pool is managed externally, nothing to do here
+    },
+  };
+}

package/src/plugins/preferences/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Preferences Plugin Types
+ *
+ * Type definitions for user preferences management.
+ * Supports PostgreSQL with Row-Level Security (RLS) for data isolation.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+/**
+ * User preferences record in the database
+ */
+export interface UserPreferences {
+  /** Primary key - UUID */
+  id: string;
+  /** User ID (foreign key to users table) */
+  user_id: string;
+  /** Preferences as JSON object */
+  preferences: Record<string, unknown>;
+  /** When the preferences were created */
+  created_at: Date;
+  /** When the preferences were last updated */
+  updated_at: Date;
+}
+
+/**
+ * Preferences store interface - all storage backends must implement this
+ */
+export interface PreferencesStore {
+  /** Store name (e.g., 'postgres', 'memory') */
+  name: string;
+
+  /**
+   * Initialize the store (create tables, RLS policies, etc.)
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Get preferences for a user
+   * Returns null if no preferences exist for the user
+   */
+  get(userId: string): Promise<Record<string, unknown> | null>;
+
+  /**
+   * Update preferences for a user (upsert with deep merge)
+   * Returns the merged preferences
+   */
+  update(userId: string, preferences: Record<string, unknown>): Promise<Record<string, unknown>>;
+
+  /**
+   * Delete preferences for a user
+   * Returns true if preferences were deleted, false if none existed
+   */
+  delete(userId: string): Promise<boolean>;
+
+  /**
+   * Shutdown the store
+   */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * PostgreSQL preferences store configuration
+ */
+export interface PostgresPreferencesStoreConfig {
+  /** PostgreSQL pool instance or a function that returns one (for lazy initialization) */
+  pool: unknown | (() => unknown);
+  /** Table name (default: 'user_preferences') */
+  tableName?: string;
+  /** Schema name (default: 'public') */
+  schema?: string;
+  /** Auto-create tables on init (default: true) */
+  autoCreateTables?: boolean;
+  /** Enable RLS (default: true) */
+  enableRLS?: boolean;
+}
+
+/**
+ * Preferences API configuration
+ */
+export interface PreferencesApiConfig {
+  /** API route prefix (default: '/preferences') */
+  prefix?: string;
+  /** Enable API endpoints (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * Preferences plugin configuration
+ */
+export interface PreferencesPluginConfig {
+  /** Preferences storage backend */
+  store: PreferencesStore;
+  /** Default preferences to merge with stored preferences on read */
+  defaults?: Record<string, unknown>;
+  /** API configuration */
+  api?: PreferencesApiConfig;
+  /** Enable debug logging */
+  debug?: boolean;
+}

package/src/plugins/rate-limit/__tests__/rate-limit-plugin.test.ts

@@ -0,0 +1,259 @@
+/**
+ * Rate Limit Plugin Tests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { RateLimitStore, RateLimitCache, CachedLimit, StoredLimit, IncrementOptions } from '../types.js';
+import { RateLimitService } from '../rate-limit-service.js';
+import { createSlidingWindowStrategy } from '../strategies/sliding-window.js';
+import { createFixedWindowStrategy } from '../strategies/fixed-window.js';
+import { createTokenBucketStrategy } from '../strategies/token-bucket.js';
+
+// Mock store implementation
+function createMockStore(): RateLimitStore {
+  const records = new Map<string, StoredLimit>();
+
+  return {
+    name: 'mock',
+
+    async initialize(): Promise<void> {
+      // No-op
+    },
+
+    async get(key: string): Promise<StoredLimit | null> {
+      return records.get(key) || null;
+    },
+
+    async increment(key: string, options: IncrementOptions): Promise<StoredLimit> {
+      const now = new Date();
+      const windowMs = options.windowMs;
+      const windowStart = new Date(now.getTime() - (now.getTime() % windowMs));
+      const windowEnd = new Date(windowStart.getTime() + windowMs);
+
+      const existing = records.get(key);
+      if (existing && existing.windowStart.getTime() === windowStart.getTime()) {
+        existing.count += options.amount || 1;
+        existing.updatedAt = now;
+        return existing;
+      }
+
+      const newRecord: StoredLimit = {
+        id: `mock-${Date.now()}`,
+        key,
+        count: options.amount || 1,
+        maxRequests: options.maxRequests,
+        windowMs: options.windowMs,
+        windowStart,
+        windowEnd,
+        strategy: options.strategy,
+        userId: options.userId,
+        tenantId: options.tenantId,
+        ipAddress: options.ipAddress,
+        createdAt: now,
+        updatedAt: now,
+      };
+      records.set(key, newRecord);
+      return newRecord;
+    },
+
+    async clear(key: string): Promise<boolean> {
+      return records.delete(key);
+    },
+
+    async cleanup(): Promise<number> {
+      const now = Date.now();
+      let deleted = 0;
+      for (const [key, record] of records) {
+        if (record.windowEnd.getTime() < now) {
+          records.delete(key);
+          deleted++;
+        }
+      }
+      return deleted;
+    },
+
+    async shutdown(): Promise<void> {
+      records.clear();
+    },
+  };
+}
+
+// Mock cache implementation
+function createMockCache(): RateLimitCache {
+  const cache = new Map<string, { value: CachedLimit; expiresAt: number }>();
+
+  return {
+    name: 'mock',
+
+    async get(key: string): Promise<CachedLimit | null> {
+      const entry = cache.get(key);
+      if (!entry) return null;
+      if (entry.expiresAt <= Date.now()) {
+        cache.delete(key);
+        return null;
+      }
+      return entry.value;
+    },
+
+    async set(key: string, value: CachedLimit, ttlMs: number): Promise<void> {
+      cache.set(key, { value, expiresAt: Date.now() + ttlMs });
+    },
+
+    async increment(key: string, amount = 1): Promise<number | null> {
+      const entry = cache.get(key);
+      if (!entry || entry.expiresAt <= Date.now()) return null;
+      entry.value.count += amount;
+      return entry.value.count;
+    },
+
+    async delete(key: string): Promise<boolean> {
+      return cache.delete(key);
+    },
+
+    isAvailable(): boolean {
+      return true;
+    },
+
+    async shutdown(): Promise<void> {
+      cache.clear();
+    },
+  };
+}
+
+describe('RateLimitService', () => {
+  let store: RateLimitStore;
+  let cache: RateLimitCache;
+  let service: RateLimitService;
+
+  beforeEach(() => {
+    store = createMockStore();
+    cache = createMockCache();
+    service = new RateLimitService({
+      store,
+      cache,
+      defaults: {
+        windowMs: 60000,
+        maxRequests: 100,
+        strategy: 'sliding-window',
+      },
+    });
+  });
+
+  afterEach(async () => {
+    await store.shutdown();
+    await cache.shutdown();
+  });
+
+  describe('checkLimit', () => {
+    it('should return not limited for first request', async () => {
+      const status = await service.checkLimit('test:key', { increment: false });
+
+      expect(status.limited).toBe(false);
+      expect(status.current).toBe(0);
+      expect(status.limit).toBe(100);
+      expect(status.remaining).toBe(100);
+    });
+
+    it('should use provided options over defaults', async () => {
+      const status = await service.checkLimit('test:key', {
+        maxRequests: 50,
+        windowMs: 30000,
+        increment: false,
+      });
+
+      expect(status.limit).toBe(50);
+    });
+  });
+
+  describe('incrementLimit', () => {
+    it('should increment the counter', async () => {
+      const status1 = await service.incrementLimit('test:key');
+      expect(status1.current).toBe(1);
+      expect(status1.remaining).toBe(99);
+
+      const status2 = await service.incrementLimit('test:key');
+      expect(status2.current).toBe(2);
+      expect(status2.remaining).toBe(98);
+    });
+
+    it('should return limited when max reached', async () => {
+      // Set low limit for testing
+      for (let i = 0; i < 5; i++) {
+        await service.incrementLimit('test:key', { maxRequests: 5 });
+      }
+
+      const status = await service.incrementLimit('test:key', { maxRequests: 5 });
+      expect(status.limited).toBe(true);
+      expect(status.remaining).toBe(0);
+    });
+  });
+
+  describe('isLimited', () => {
+    it('should return false when not limited', async () => {
+      const limited = await service.isLimited('test:key');
+      expect(limited).toBe(false);
+    });
+
+    it('should return true when limited', async () => {
+      // Exhaust the limit
+      for (let i = 0; i < 5; i++) {
+        await service.incrementLimit('test:key', { maxRequests: 5 });
+      }
+
+      const limited = await service.isLimited('test:key', { maxRequests: 5 });
+      expect(limited).toBe(true);
+    });
+  });
+
+  describe('clearLimit', () => {
+    it('should clear the limit', async () => {
+      // Create some limits
+      await service.incrementLimit('test:key');
+      await service.incrementLimit('test:key');
+
+      // Verify exists
+      const beforeStatus = await service.checkLimit('test:key', { increment: false });
+      expect(beforeStatus.current).toBeGreaterThan(0);
+
+      // Clear
+      await service.clearLimit('test:key');
+
+      // Verify cleared
+      const afterStatus = await service.checkLimit('test:key', { increment: false });
+      expect(afterStatus.current).toBe(0);
+    });
+  });
+});
+
+describe('Strategies', () => {
+  describe('Sliding Window', () => {
+    it('should create strategy with correct name', () => {
+      const strategy = createSlidingWindowStrategy();
+      expect(strategy.name).toBe('sliding-window');
+    });
+  });
+
+  describe('Fixed Window', () => {
+    it('should create strategy with correct name', () => {
+      const strategy = createFixedWindowStrategy();
+      expect(strategy.name).toBe('fixed-window');
+    });
+  });
+
+  describe('Token Bucket', () => {
+    it('should create strategy with correct name', () => {
+      const strategy = createTokenBucketStrategy();
+      expect(strategy.name).toBe('token-bucket');
+    });
+  });
+});
+
+describe('Types', () => {
+  it('should export all required types', async () => {
+    // This test verifies that the types module compiles correctly
+    const types = await import('../types.js');
+    expect(types).toBeDefined();
+  });
+});