@qwickapps/server 1.3.0 → 1.4.0

package/src/plugins/auth/types.ts

@@ -127,6 +127,47 @@ export interface BasicAdapterConfig {
   realm?: string;
 }
 
+/**
+ * Supertokens adapter configuration
+ */
+export interface SupertokensAdapterConfig {
+  /** Supertokens connection URI (e.g., 'http://localhost:3567') */
+  connectionUri: string;
+
+  /** Supertokens API key (for managed service) */
+  apiKey?: string;
+
+  /** App name for branding */
+  appName: string;
+
+  /** API domain (e.g., 'http://localhost:3000') */
+  apiDomain: string;
+
+  /** Website domain (e.g., 'http://localhost:3000') */
+  websiteDomain: string;
+
+  /** API base path (default: '/auth') */
+  apiBasePath?: string;
+
+  /** Website base path (default: '/auth') */
+  websiteBasePath?: string;
+
+  /** Enable email/password auth (default: true) */
+  enableEmailPassword?: boolean;
+
+  /** Social login providers */
+  socialProviders?: {
+    google?: { clientId: string; clientSecret: string };
+    apple?: {
+      clientId: string;
+      clientSecret: string;
+      keyId: string;
+      teamId: string;
+    };
+    github?: { clientId: string; clientSecret: string };
+  };
+}
+
 /**
  * Auth plugin configuration
  */
@@ -163,3 +204,180 @@ export interface AuthenticatedRequest extends Request {
 export function isAuthenticatedRequest(req: Request): req is AuthenticatedRequest {
   return 'auth' in req && (req as AuthenticatedRequest).auth?.isAuthenticated === true;
 }
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Environment Configuration Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Auth plugin state
+ */
+export type AuthPluginState = 'disabled' | 'enabled' | 'error';
+
+/**
+ * Options for createAuthPluginFromEnv (overrides only)
+ */
+export interface AuthEnvPluginOptions {
+  /** Paths to exclude from authentication (can also use AUTH_EXCLUDE_PATHS env var) */
+  excludePaths?: string[];
+  /** Whether auth is required (can also use AUTH_REQUIRED env var, default: true) */
+  authRequired?: boolean;
+  /** Enable debug logging (can also use AUTH_DEBUG env var) */
+  debug?: boolean;
+  /** Custom unauthorized handler */
+  onUnauthorized?: (req: Request, res: Response) => void;
+}
+
+/**
+ * Auth configuration status returned by getAuthStatus()
+ */
+export interface AuthConfigStatus {
+  /** Current plugin state */
+  state: AuthPluginState;
+  /** Active adapter name (null if disabled or error) */
+  adapter: string | null;
+  /** Error message if state is 'error' */
+  error?: string;
+  /** List of missing environment variables if state is 'error' */
+  missingVars?: string[];
+  /** Current configuration with secrets masked */
+  config?: Record<string, string>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Runtime Configuration Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Supported adapter types for runtime configuration
+ */
+export type AuthAdapterType = 'auth0' | 'supabase' | 'supertokens' | 'basic';
+
+/**
+ * Runtime auth configuration (persisted to database)
+ */
+export interface RuntimeAuthConfig {
+  /** Which adapter to use */
+  adapter: AuthAdapterType | null;
+
+  /** Adapter-specific configuration */
+  config: {
+    auth0?: Auth0AdapterConfig;
+    supabase?: SupabaseAdapterConfig;
+    supertokens?: SupertokensAdapterConfig;
+    basic?: BasicAdapterConfig;
+  };
+
+  /** General auth settings */
+  settings: {
+    authRequired?: boolean;
+    excludePaths?: string[];
+    debug?: boolean;
+  };
+
+  /** When the config was last updated */
+  updatedAt: string;
+
+  /** Who updated the config (optional) */
+  updatedBy?: string;
+}
+
+/**
+ * Request body for PUT /api/auth/config
+ */
+export interface UpdateAuthConfigRequest {
+  /** Which adapter to use */
+  adapter: AuthAdapterType;
+
+  /** Adapter-specific configuration */
+  config: Record<string, unknown>;
+
+  /** General settings (optional) */
+  settings?: {
+    authRequired?: boolean;
+    excludePaths?: string[];
+  };
+}
+
+/**
+ * Request body for POST /api/auth/test-provider
+ */
+export interface TestProviderRequest {
+  /** Which adapter to test */
+  adapter: AuthAdapterType;
+
+  /** Adapter configuration to test */
+  config: Record<string, unknown>;
+
+  /** For social provider test (optional) */
+  provider?: 'google' | 'github' | 'apple';
+}
+
+/**
+ * Response for POST /api/auth/test-provider
+ */
+export interface TestProviderResponse {
+  /** Whether the test was successful */
+  success: boolean;
+
+  /** Human-readable message */
+  message: string;
+
+  /** Additional details */
+  details?: {
+    latency?: number;
+    version?: string;
+  };
+}
+
+/**
+ * Auth configuration store interface
+ */
+export interface AuthConfigStore {
+  /** Store name for identification */
+  name: string;
+
+  /** Initialize the store (create tables if needed) */
+  initialize(): Promise<void>;
+
+  /** Load configuration from store */
+  load(): Promise<RuntimeAuthConfig | null>;
+
+  /** Save configuration to store */
+  save(config: RuntimeAuthConfig): Promise<void>;
+
+  /** Delete configuration (revert to env vars) */
+  delete(): Promise<boolean>;
+
+  /**
+   * Subscribe to configuration changes
+   * Returns unsubscribe function
+   */
+  onChange(callback: (config: RuntimeAuthConfig | null) => void): () => void;
+
+  /** Shutdown and cleanup */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * PostgreSQL auth config store configuration
+ */
+export interface PostgresAuthConfigStoreConfig {
+  /** PostgreSQL pool instance or factory function for lazy initialization */
+  pool: unknown | (() => unknown);
+
+  /** Table name (default: 'auth_config') */
+  tableName?: string;
+
+  /** Schema name (default: 'public') */
+  schema?: string;
+
+  /** Auto-create table on initialization (default: true) */
+  autoCreateTable?: boolean;
+
+  /** Enable pg_notify for cross-instance config updates (default: true) */
+  enableNotify?: boolean;
+
+  /** Channel name for pg_notify (default: 'auth_config_changed') */
+  notifyChannel?: string;
+}

package/src/plugins/cache-plugin.test.ts

@@ -79,10 +79,13 @@ describe('Cache Plugin', () => {
     addMenuItem: vi.fn(),
     addPage: vi.fn(),
     addWidget: vi.fn(),
+    addConfigComponent: vi.fn(),
     getRoutes: vi.fn().mockReturnValue([]),
     getMenuItems: vi.fn().mockReturnValue([]),
     getPages: vi.fn().mockReturnValue([]),
     getWidgets: vi.fn().mockReturnValue([]),
+    getConfigComponents: vi.fn().mockReturnValue([]),
+    getPluginContributions: vi.fn().mockReturnValue({ routes: [], menuItems: [], pages: [], widgets: [], config: undefined }),
     getConfig: vi.fn().mockReturnValue({}),
     setConfig: vi.fn().mockResolvedValue(undefined),
     subscribe: vi.fn().mockReturnValue(() => {}),

package/src/plugins/index.ts

@@ -28,6 +28,10 @@ export type { CachePluginConfig, CacheInstance } from './cache-plugin.js';
 // Auth plugin
 export {
   createAuthPlugin,
+  createAuthPluginFromEnv,
+  getAuthStatus,
+  setAuthConfigStore,
+  postgresAuthConfigStore,
   isAuthenticated,
   getAuthenticatedUser,
   getAccessToken,
@@ -37,6 +41,7 @@ export {
   auth0Adapter,
   basicAdapter,
   supabaseAdapter,
+  supertokensAdapter,
   isAuthenticatedRequest,
 } from './auth/index.js';
 export type {
@@ -47,6 +52,12 @@ export type {
   Auth0AdapterConfig,
   SupabaseAdapterConfig,
   BasicAdapterConfig,
+  SupertokensAdapterConfig,
+  AuthPluginState,
+  AuthEnvPluginOptions,
+  AuthConfigStatus,
+  AuthConfigStore,
+  PostgresAuthConfigStoreConfig,
 } from './auth/index.js';
 
 // Users plugin
@@ -130,3 +141,67 @@ export type {
   CachedEntitlements,
   EntitlementStats,
 } from './entitlements/index.js';
+
+// Preferences plugin (depends on Users)
+export {
+  createPreferencesPlugin,
+  getPreferencesStore,
+  getPreferences,
+  updatePreferences,
+  deletePreferences,
+  getDefaultPreferences,
+  postgresPreferencesStore,
+  deepMerge,
+} from './preferences/index.js';
+export type {
+  PreferencesPluginConfig,
+  PreferencesStore,
+  UserPreferences,
+  PostgresPreferencesStoreConfig,
+  PreferencesApiConfig,
+} from './preferences/index.js';
+
+// Rate Limit plugin
+export {
+  createRateLimitPlugin,
+  createRateLimitPluginFromEnv,
+  getRateLimitConfigStatus,
+  postgresRateLimitStore,
+  createRateLimitCache,
+  createNoOpCache,
+  createSlidingWindowStrategy,
+  createFixedWindowStrategy,
+  createTokenBucketStrategy,
+  getStrategy,
+  rateLimitMiddleware,
+  rateLimitStatusMiddleware,
+  RateLimitService,
+  getRateLimitService,
+  isLimited,
+  checkLimit,
+  incrementLimit,
+  getRemainingRequests,
+  getLimitStatus,
+  clearLimit,
+  createCleanupJob,
+} from './rate-limit/index.js';
+export type {
+  RateLimitPluginConfig,
+  RateLimitEnvPluginOptions,
+  RateLimitStrategy,
+  LimitStatus,
+  Strategy,
+  StrategyOptions,
+  StrategyContext,
+  StoredLimit,
+  IncrementOptions,
+  RateLimitStore,
+  PostgresRateLimitStoreConfig,
+  CachedLimit,
+  RateLimitCache,
+  RateLimitCacheConfig,
+  RateLimitMiddlewareOptions,
+  CheckLimitOptions,
+  CleanupJob,
+  CleanupJobConfig,
+} from './rate-limit/index.js';

package/src/plugins/postgres-plugin.test.ts

@@ -56,10 +56,13 @@ describe('PostgreSQL Plugin', () => {
     addMenuItem: vi.fn(),
     addPage: vi.fn(),
     addWidget: vi.fn(),
+    addConfigComponent: vi.fn(),
     getRoutes: vi.fn().mockReturnValue([]),
     getMenuItems: vi.fn().mockReturnValue([]),
     getPages: vi.fn().mockReturnValue([]),
     getWidgets: vi.fn().mockReturnValue([]),
+    getConfigComponents: vi.fn().mockReturnValue([]),
+    getPluginContributions: vi.fn().mockReturnValue({ routes: [], menuItems: [], pages: [], widgets: [], config: undefined }),
     getConfig: vi.fn().mockReturnValue({}),
     setConfig: vi.fn().mockResolvedValue(undefined),
     subscribe: vi.fn().mockReturnValue(() => {}),

package/src/plugins/preferences/__tests__/deep-merge.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Deep Merge Utility Tests
+ *
+ * Unit tests for the deep merge function used by the preferences plugin.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { deepMerge } from '../stores/postgres-store.js';
+
+describe('deepMerge', () => {
+  describe('basic merging', () => {
+    it('should merge flat objects', () => {
+      const target = { a: 1 };
+      const source = { b: 2 };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 1, b: 2 });
+    });
+
+    it('should not mutate original objects', () => {
+      const target = { a: 1 };
+      const source = { b: 2 };
+      deepMerge(target, source);
+      expect(target).toEqual({ a: 1 });
+      expect(source).toEqual({ b: 2 });
+    });
+
+    it('should return a new object', () => {
+      const target = { a: 1 };
+      const source = { b: 2 };
+      const result = deepMerge(target, source);
+      expect(result).not.toBe(target);
+      expect(result).not.toBe(source);
+    });
+  });
+
+  describe('nested object merging', () => {
+    it('should merge nested objects recursively', () => {
+      const target = { a: { x: 1 } };
+      const source = { a: { y: 2 } };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: { x: 1, y: 2 } });
+    });
+
+    it('should handle deeply nested objects', () => {
+      const target = { a: { b: { c: { x: 1 } } } };
+      const source = { a: { b: { c: { y: 2 } } } };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: { b: { c: { x: 1, y: 2 } } } });
+    });
+
+    it('should merge multiple nested keys', () => {
+      const target = {
+        theme: 'light',
+        notifications: { email: true, push: true },
+      };
+      const source = {
+        notifications: { email: false },
+      };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({
+        theme: 'light',
+        notifications: { email: false, push: true },
+      });
+    });
+  });
+
+  describe('value overwriting', () => {
+    it('should let source override target for same keys', () => {
+      const target = { a: 1 };
+      const source = { a: 2 };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 2 });
+    });
+
+    it('should let source override target for nested keys', () => {
+      const target = { a: { x: 1 } };
+      const source = { a: { x: 2 } };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: { x: 2 } });
+    });
+  });
+
+  describe('array handling', () => {
+    it('should replace arrays (not merge)', () => {
+      const target = { a: [1, 2] };
+      const source = { a: [3, 4, 5] };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: [3, 4, 5] });
+    });
+
+    it('should replace array with empty array', () => {
+      const target = { a: [1, 2, 3] };
+      const source = { a: [] };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: [] });
+    });
+
+    it('should replace non-array with array', () => {
+      const target = { a: 'string' };
+      const source = { a: [1, 2] };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: [1, 2] });
+    });
+
+    it('should replace array with non-array', () => {
+      const target = { a: [1, 2] };
+      const source = { a: 'string' };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 'string' });
+    });
+  });
+
+  describe('special values', () => {
+    it('should handle null values in source', () => {
+      const target = { a: 1 };
+      const source = { a: null };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: null });
+    });
+
+    it('should skip undefined values in source', () => {
+      const target = { a: 1 };
+      const source = { a: undefined };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 1 });
+    });
+
+    it('should handle null in target', () => {
+      const target = { a: null };
+      const source = { a: { x: 1 } };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: { x: 1 } });
+    });
+
+    it('should replace object with null', () => {
+      const target = { a: { x: 1 } };
+      const source = { a: null };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: null });
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty target', () => {
+      const target = {};
+      const source = { a: 1 };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 1 });
+    });
+
+    it('should handle empty source', () => {
+      const target = { a: 1 };
+      const source = {};
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 1 });
+    });
+
+    it('should handle both empty', () => {
+      const target = {};
+      const source = {};
+      const result = deepMerge(target, source);
+      expect(result).toEqual({});
+    });
+
+    it('should handle primitive values becoming objects', () => {
+      const target = { a: 'string' };
+      const source = { a: { x: 1 } };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: { x: 1 } });
+    });
+
+    it('should handle objects becoming primitive values', () => {
+      const target = { a: { x: 1 } };
+      const source = { a: 'string' };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 'string' });
+    });
+  });
+
+  describe('real-world preference scenarios', () => {
+    it('should merge default preferences with user preferences', () => {
+      const defaults = {
+        theme: 'system',
+        notifications: {
+          email: true,
+          push: true,
+          sms: false,
+        },
+        trading: {
+          defaultSymbol: 'SPY',
+          chartInterval: '5min',
+        },
+      };
+
+      const userPrefs = {
+        theme: 'dark',
+        notifications: {
+          email: false,
+        },
+      };
+
+      const result = deepMerge(defaults, userPrefs);
+      expect(result).toEqual({
+        theme: 'dark',
+        notifications: {
+          email: false,
+          push: true,
+          sms: false,
+        },
+        trading: {
+          defaultSymbol: 'SPY',
+          chartInterval: '5min',
+        },
+      });
+    });
+
+    it('should handle partial updates to preferences', () => {
+      const existing = {
+        theme: 'dark',
+        notifications: {
+          email: false,
+          push: true,
+        },
+      };
+
+      const update = {
+        notifications: {
+          push: false,
+        },
+      };
+
+      const result = deepMerge(existing, update);
+      expect(result).toEqual({
+        theme: 'dark',
+        notifications: {
+          email: false,
+          push: false,
+        },
+      });
+    });
+  });
+});