@qwickapps/server 1.2.0 → 1.3.1

package/src/plugins/preferences/preferences-plugin.ts

@@ -0,0 +1,270 @@
+/**
+ * Preferences Plugin
+ *
+ * User preferences management plugin for @qwickapps/server.
+ * Provides per-user preference storage with PostgreSQL RLS for data isolation.
+ *
+ * This plugin depends on the Users Plugin for user identity.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response } from 'express';
+import type { Plugin, PluginConfig, PluginRegistry } from '../../core/plugin-registry.js';
+import type {
+  PreferencesPluginConfig,
+  PreferencesStore,
+} from './types.js';
+import type { AuthenticatedRequest } from '../auth/types.js';
+import { deepMerge } from './stores/postgres-store.js';
+
+// Configuration limits
+const MAX_PREFERENCES_SIZE = 100_000; // 100KB JSON string limit
+const MAX_NESTING_DEPTH = 10;
+
+/**
+ * Check if an object exceeds maximum nesting depth
+ */
+function exceedsMaxDepth(obj: unknown, depth = 0): boolean {
+  if (depth > MAX_NESTING_DEPTH) return true;
+  if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+    return Object.values(obj as Record<string, unknown>).some(v => exceedsMaxDepth(v, depth + 1));
+  }
+  if (Array.isArray(obj)) {
+    return obj.some(v => exceedsMaxDepth(v, depth + 1));
+  }
+  return false;
+}
+
+// Store instance for helper access
+let currentStore: PreferencesStore | null = null;
+let pluginDefaults: Record<string, unknown> = {};
+
+/**
+ * Create the Preferences plugin
+ */
+export function createPreferencesPlugin(config: PreferencesPluginConfig): Plugin {
+  const debug = config.debug || false;
+  // Routes are mounted under /api by the control panel, so don't include /api in prefix
+  const apiPrefix = config.api?.prefix || '/preferences';
+  const apiEnabled = config.api?.enabled !== false;
+
+  function log(message: string, data?: Record<string, unknown>) {
+    if (debug) {
+      console.log(`[PreferencesPlugin] ${message}`, data || '');
+    }
+  }
+
+  return {
+    id: 'preferences',
+    name: 'Preferences',
+    version: '1.0.0',
+
+    async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
+      log('Starting preferences plugin');
+
+      // Check for users plugin dependency
+      if (!registry.hasPlugin('users')) {
+        throw new Error('Preferences plugin requires Users plugin to be loaded first');
+      }
+
+      // Initialize the store (creates tables and RLS policies if needed)
+      await config.store.initialize();
+      log('Preferences plugin migrations complete');
+
+      // Store references for helper access
+      currentStore = config.store;
+      pluginDefaults = config.defaults || {};
+
+      // Register health check
+      registry.registerHealthCheck({
+        name: 'preferences-store',
+        type: 'custom',
+        check: async () => {
+          try {
+            // Simple health check - store is accessible
+            // We can't actually query without a user context due to RLS,
+            // but we can verify the store is initialized
+            return { healthy: currentStore !== null };
+          } catch {
+            return { healthy: false };
+          }
+        },
+      });
+
+      // Add API routes if enabled
+      if (apiEnabled) {
+        // GET /preferences - Get current user's preferences
+        registry.addRoute({
+          method: 'get',
+          path: apiPrefix,
+          pluginId: 'preferences',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const authReq = req as AuthenticatedRequest;
+              const userId = authReq.auth?.user?.id;
+
+              if (!userId) {
+                return res.status(401).json({ error: 'Authentication required' });
+              }
+
+              const stored = await config.store.get(userId);
+
+              // Merge with defaults (defaults as base, stored values override)
+              const preferences = stored
+                ? deepMerge(pluginDefaults, stored)
+                : { ...pluginDefaults };
+
+              res.json({
+                user_id: userId,
+                preferences,
+              });
+            } catch (error) {
+              console.error('[PreferencesPlugin] Get preferences error:', error);
+              res.status(500).json({ error: 'Failed to get preferences' });
+            }
+          },
+        });
+
+        // PUT /preferences - Update current user's preferences
+        registry.addRoute({
+          method: 'put',
+          path: apiPrefix,
+          pluginId: 'preferences',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const authReq = req as AuthenticatedRequest;
+              const userId = authReq.auth?.user?.id;
+
+              if (!userId) {
+                return res.status(401).json({ error: 'Authentication required' });
+              }
+
+              const newPreferences = req.body;
+              if (!newPreferences || typeof newPreferences !== 'object' || Array.isArray(newPreferences)) {
+                return res.status(400).json({ error: 'Request body must be a JSON object' });
+              }
+
+              // Validate payload size
+              const jsonSize = JSON.stringify(newPreferences).length;
+              if (jsonSize > MAX_PREFERENCES_SIZE) {
+                return res.status(413).json({ error: 'Preferences payload too large (max 100KB)' });
+              }
+
+              // Validate nesting depth
+              if (exceedsMaxDepth(newPreferences)) {
+                return res.status(400).json({ error: 'Preferences object too deeply nested (max 10 levels)' });
+              }
+
+              const updated = await config.store.update(userId, newPreferences);
+
+              // Merge with defaults for response
+              const preferences = deepMerge(pluginDefaults, updated);
+
+              res.json({
+                user_id: userId,
+                preferences,
+              });
+            } catch (error) {
+              console.error('[PreferencesPlugin] Update preferences error:', error);
+              res.status(500).json({ error: 'Failed to update preferences' });
+            }
+          },
+        });
+
+        // DELETE /preferences - Reset preferences to defaults
+        registry.addRoute({
+          method: 'delete',
+          path: apiPrefix,
+          pluginId: 'preferences',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const authReq = req as AuthenticatedRequest;
+              const userId = authReq.auth?.user?.id;
+
+              if (!userId) {
+                return res.status(401).json({ error: 'Authentication required' });
+              }
+
+              await config.store.delete(userId);
+
+              // Return 204 No Content (idempotent - success even if no row existed)
+              res.status(204).send();
+            } catch (error) {
+              console.error('[PreferencesPlugin] Delete preferences error:', error);
+              res.status(500).json({ error: 'Failed to delete preferences' });
+            }
+          },
+        });
+      }
+
+      log('Preferences plugin started');
+    },
+
+    async onStop(): Promise<void> {
+      log('Stopping preferences plugin');
+      await config.store.shutdown();
+      currentStore = null;
+      pluginDefaults = {};
+      log('Preferences plugin stopped');
+    },
+  };
+}
+
+// ========================================
+// Helper Functions
+// ========================================
+
+/**
+ * Get the current preferences store instance
+ */
+export function getPreferencesStore(): PreferencesStore | null {
+  return currentStore;
+}
+
+/**
+ * Get preferences for a user (merged with defaults)
+ */
+export async function getPreferences(userId: string): Promise<Record<string, unknown>> {
+  if (!currentStore) {
+    throw new Error('Preferences plugin not initialized');
+  }
+
+  const stored = await currentStore.get(userId);
+  return stored ? deepMerge(pluginDefaults, stored) : { ...pluginDefaults };
+}
+
+/**
+ * Update preferences for a user
+ * Returns the merged preferences (stored + defaults)
+ */
+export async function updatePreferences(
+  userId: string,
+  preferences: Record<string, unknown>
+): Promise<Record<string, unknown>> {
+  if (!currentStore) {
+    throw new Error('Preferences plugin not initialized');
+  }
+
+  const updated = await currentStore.update(userId, preferences);
+  return deepMerge(pluginDefaults, updated);
+}
+
+/**
+ * Delete preferences for a user (reset to defaults)
+ * Returns true if preferences existed and were deleted
+ */
+export async function deletePreferences(userId: string): Promise<boolean> {
+  if (!currentStore) {
+    throw new Error('Preferences plugin not initialized');
+  }
+
+  return currentStore.delete(userId);
+}
+
+/**
+ * Get the configured default preferences
+ */
+export function getDefaultPreferences(): Record<string, unknown> {
+  return { ...pluginDefaults };
+}

package/src/plugins/preferences/stores/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Preferences Stores Index
+ *
+ * Re-exports all available preferences store implementations.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { postgresPreferencesStore, deepMerge } from './postgres-store.js';

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;
+}