@qwickapps/server 1.0.0 → 1.1.7

package/src/core/guards.ts

@@ -0,0 +1,190 @@
+/**
+ * Route Guards for @qwickapps/server
+ *
+ * Provides authentication middleware for protecting routes.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
+import type {
+  RouteGuardConfig,
+  BasicAuthGuardConfig,
+  SupabaseAuthGuardConfig,
+  Auth0GuardConfig,
+} from './types.js';
+
+/**
+ * Create a route guard middleware from configuration
+ */
+export function createRouteGuard(config: RouteGuardConfig): RequestHandler {
+  switch (config.type) {
+    case 'none':
+      return (_req, _res, next) => next();
+    case 'basic':
+      return createBasicAuthGuard(config);
+    case 'supabase':
+      return createSupabaseGuard(config);
+    case 'auth0':
+      return createAuth0Guard(config);
+    default:
+      throw new Error(`Unknown guard type: ${(config as any).type}`);
+  }
+}
+
+/**
+ * Create basic auth guard middleware
+ */
+function createBasicAuthGuard(config: BasicAuthGuardConfig): RequestHandler {
+  const expectedAuth = `Basic ${Buffer.from(`${config.username}:${config.password}`).toString('base64')}`;
+  const realm = config.realm || 'Protected';
+  const excludePaths = config.excludePaths || [];
+
+  return (req: Request, res: Response, next: NextFunction) => {
+    // Check if path is excluded
+    if (excludePaths.some(path => req.path.startsWith(path))) {
+      return next();
+    }
+
+    const authHeader = req.headers.authorization;
+    if (authHeader === expectedAuth) {
+      return next();
+    }
+
+    res.setHeader('WWW-Authenticate', `Basic realm="${realm}"`);
+    res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Authentication required.',
+    });
+  };
+}
+
+/**
+ * Create Supabase auth guard middleware
+ *
+ * Validates JWT tokens from Supabase Auth
+ */
+function createSupabaseGuard(config: SupabaseAuthGuardConfig): RequestHandler {
+  const excludePaths = config.excludePaths || [];
+
+  return async (req: Request, res: Response, next: NextFunction) => {
+    // Check if path is excluded
+    if (excludePaths.some(path => req.path.startsWith(path))) {
+      return next();
+    }
+
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Missing or invalid authorization header. Expected: Bearer <token>',
+      });
+    }
+
+    const token = authHeader.substring(7);
+
+    try {
+      // Validate the JWT with Supabase
+      const response = await fetch(`${config.supabaseUrl}/auth/v1/user`, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          apikey: config.supabaseAnonKey,
+        },
+      });
+
+      if (!response.ok) {
+        return res.status(401).json({
+          error: 'Unauthorized',
+          message: 'Invalid or expired token.',
+        });
+      }
+
+      const user = await response.json();
+      (req as any).user = user;
+      next();
+    } catch (error) {
+      return res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Failed to validate token.',
+      });
+    }
+  };
+}
+
+/**
+ * Create Auth0 guard middleware
+ *
+ * Uses express-openid-connect for Auth0 authentication
+ */
+function createAuth0Guard(config: Auth0GuardConfig): RequestHandler {
+  // Lazy-load express-openid-connect to avoid requiring it when not used
+  let authMiddleware: RequestHandler | null = null;
+
+  return async (req: Request, res: Response, next: NextFunction) => {
+    // Lazy initialize the middleware
+    if (!authMiddleware) {
+      try {
+        const { auth } = await import('express-openid-connect');
+        authMiddleware = auth({
+          authRequired: true,
+          auth0Logout: true,
+          secret: config.secret,
+          baseURL: config.baseUrl,
+          clientID: config.clientId,
+          issuerBaseURL: `https://${config.domain}`,
+          clientSecret: config.clientSecret,
+          idpLogout: true,
+          routes: {
+            login: config.routes?.login || '/login',
+            logout: config.routes?.logout || '/logout',
+            callback: config.routes?.callback || '/callback',
+          },
+        });
+      } catch (error) {
+        return res.status(500).json({
+          error: 'Configuration Error',
+          message: 'Auth0 is not properly configured. Install express-openid-connect package.',
+        });
+      }
+    }
+
+    // Check if path is excluded
+    const excludePaths = config.excludePaths || [];
+    if (excludePaths.some(path => req.path.startsWith(path))) {
+      return next();
+    }
+
+    // Apply Auth0 middleware
+    authMiddleware!(req, res, next);
+  };
+}
+
+/**
+ * Helper to check if a request is authenticated (for use in handlers)
+ */
+export function isAuthenticated(req: Request): boolean {
+  // Check for Auth0 session
+  if ((req as any).oidc?.isAuthenticated?.()) {
+    return true;
+  }
+  // Check for Supabase user
+  if ((req as any).user) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Get the authenticated user from the request
+ */
+export function getAuthenticatedUser(req: Request): any | null {
+  // Check for Auth0 user
+  if ((req as any).oidc?.user) {
+    return (req as any).oidc.user;
+  }
+  // Check for Supabase user
+  if ((req as any).user) {
+    return (req as any).user;
+  }
+  return null;
+}

package/src/core/health-manager.ts

@@ -40,10 +40,7 @@ export class HealthManager {
 
     this.intervals.set(check.name, timer);
 
-    this.logger.info(`[HealthManager] Registered health check: ${check.name}`, {
-      type: check.type,
-      interval,
-    });
+    this.logger.debug(`Health check registered: ${check.name} (${check.type}, ${interval}ms)`)
   }
 
   /**
@@ -101,10 +98,7 @@ export class HealthManager {
         lastChecked: new Date(),
       });
 
-      this.logger.warn(`[HealthManager] Health check failed: ${name}`, {
-        error: message,
-        latency,
-      });
+      this.logger.warn(`Health check failed: ${name} - ${message}`);
     }
   }
 
@@ -222,6 +216,6 @@ export class HealthManager {
       clearInterval(timer);
     }
     this.intervals.clear();
-    this.logger.info('[HealthManager] Shutdown complete');
+    this.logger.debug('Health manager shutdown complete');
   }
 }

package/src/core/logging.ts

@@ -135,12 +135,8 @@ class LoggingSubsystem {
     }
 
     this.initialized = true;
-    this.rootLogger.info('Logging subsystem initialized', {
-      logDir: this.config.logDir,
+    this.rootLogger.debug('Logging initialized', {
       level: this.config.level,
-      fileLogging: this.config.fileLogging,
-      consoleOutput: this.config.consoleOutput,
-      usingPino: this.rootLogger.isUsingPino(),
     });
   }
 

package/src/core/types.ts

@@ -4,7 +4,110 @@
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
-import type { Application, RequestHandler, Router } from 'express';
+import type { Application, RequestHandler, Router, Request, Response, NextFunction } from 'express';
+
+/**
+ * Route guard types for protecting routes
+ */
+export type RouteGuardType = 'none' | 'basic' | 'supabase' | 'auth0';
+
+/**
+ * Basic auth guard configuration
+ */
+export interface BasicAuthGuardConfig {
+  type: 'basic';
+  /** Username for basic auth */
+  username: string;
+  /** Password for basic auth */
+  password: string;
+  /** Realm name for the WWW-Authenticate header */
+  realm?: string;
+  /** Paths to exclude from authentication (e.g., ['/health']) */
+  excludePaths?: string[];
+}
+
+/**
+ * Supabase auth guard configuration
+ */
+export interface SupabaseAuthGuardConfig {
+  type: 'supabase';
+  /** Supabase project URL */
+  supabaseUrl: string;
+  /** Supabase anon key */
+  supabaseAnonKey: string;
+  /** Paths to exclude from authentication */
+  excludePaths?: string[];
+}
+
+/**
+ * Auth0 guard configuration
+ */
+export interface Auth0GuardConfig {
+  type: 'auth0';
+  /** Auth0 domain (e.g., 'myapp.auth0.com') */
+  domain: string;
+  /** Auth0 client ID */
+  clientId: string;
+  /** Auth0 client secret */
+  clientSecret: string;
+  /** Base URL of the application */
+  baseUrl: string;
+  /** Session secret for cookie encryption */
+  secret: string;
+  /** Auth routes configuration */
+  routes?: {
+    login?: string;
+    logout?: string;
+    callback?: string;
+  };
+  /** Paths to exclude from authentication */
+  excludePaths?: string[];
+}
+
+/**
+ * No authentication guard
+ */
+export interface NoAuthGuardConfig {
+  type: 'none';
+}
+
+/**
+ * Union type for all guard configurations
+ */
+export type RouteGuardConfig =
+  | NoAuthGuardConfig
+  | BasicAuthGuardConfig
+  | SupabaseAuthGuardConfig
+  | Auth0GuardConfig;
+
+/**
+ * Mount path configuration for applications
+ */
+export interface MountConfig {
+  /** Path where this app is mounted (e.g., '/', '/cpanel', '/app') */
+  path: string;
+  /** Route guard configuration for this mount point */
+  guard?: RouteGuardConfig;
+}
+
+/**
+ * Frontend app configuration
+ */
+export interface FrontendAppConfig {
+  /** Mount configuration */
+  mount: MountConfig;
+  /** Redirect to another URL instead of serving content */
+  redirectUrl?: string;
+  /** Path to static files to serve */
+  staticPath?: string;
+  /** Landing page HTML (used if no staticPath or redirectUrl) */
+  landingPage?: {
+    title: string;
+    heading?: string;
+    description?: string;
+    links?: Array<{ label: string; url: string }>;
+  };
+}
 
 /**
  * Control Panel Configuration
@@ -26,14 +129,17 @@ export interface ControlPanelConfig {
     favicon?: string;
   };
 
-  /** Optional: Authentication configuration */
-  auth?: {
-    enabled: boolean;
-    provider: 'basic' | 'jwt' | 'custom';
-    users?: Array<{ username: string; password: string }>;
-    jwtSecret?: string;
-    customMiddleware?: RequestHandler;
-  };
+  /**
+   * Mount path for the control panel.
+   * Defaults to '/cpanel'.
+   */
+  mountPath?: string;
+
+  /**
+   * Route guard for the control panel.
+   * Defaults to basic auth in production.
+   */
+  guard?: RouteGuardConfig;
 
   /** Optional: CORS configuration */
   cors?: {

package/src/index.ts

@@ -12,6 +12,13 @@ export { createControlPanel } from './core/control-panel.js';
 export { createGateway } from './core/gateway.js';
 export { HealthManager } from './core/health-manager.js';
 
+// Guards exports
+export {
+  createRouteGuard,
+  isAuthenticated,
+  getAuthenticatedUser,
+} from './core/guards.js';
+
 // Logging exports
 export {
   initializeLogging,
@@ -33,6 +40,15 @@ export type {
   ConfigDisplayOptions,
   Logger,
   DiagnosticsReport,
+  // New mount path and guard types
+  RouteGuardType,
+  RouteGuardConfig,
+  BasicAuthGuardConfig,
+  SupabaseAuthGuardConfig,
+  Auth0GuardConfig,
+  NoAuthGuardConfig,
+  MountConfig,
+  FrontendAppConfig,
 } from './core/types.js';
 export type {
   GatewayConfig,
@@ -46,10 +62,34 @@ export {
   createLogsPlugin,
   createConfigPlugin,
   createDiagnosticsPlugin,
+  createFrontendAppPlugin,
+  // Database plugins
+  createPostgresPlugin,
+  getPostgres,
+  hasPostgres,
+  // Backward compatibility aliases (deprecated)
+  createPostgresPlugin as createDatabasePlugin,
+  getPostgres as getDatabase,
+  hasPostgres as hasDatabase,
+  // Cache plugins
+  createCachePlugin,
+  getCache,
+  hasCache,
 } from './plugins/index.js';
 export type {
   HealthPluginConfig,
   LogsPluginConfig,
   ConfigPluginConfig,
   DiagnosticsPluginConfig,
+  FrontendAppPluginConfig,
+  // Database plugin types
+  PostgresPluginConfig,
+  PostgresInstance,
+  TransactionCallback,
+  // Backward compatibility aliases (deprecated)
+  PostgresPluginConfig as DatabasePluginConfig,
+  PostgresInstance as DatabaseInstance,
+  // Cache plugin types
+  CachePluginConfig,
+  CacheInstance,
 } from './plugins/index.js';

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

@@ -0,0 +1,241 @@
+/**
+ * Cache Plugin Tests
+ *
+ * Note: These tests use mocks since we don't want to require a real Redis instance.
+ * Integration tests should be run separately with a real Redis instance.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// Mock ioredis before importing the plugin
+vi.mock('ioredis', () => {
+  const mockClient = {
+    get: vi.fn().mockResolvedValue(null),
+    setex: vi.fn().mockResolvedValue('OK'),
+    del: vi.fn().mockResolvedValue(1),
+    exists: vi.fn().mockResolvedValue(1),
+    expire: vi.fn().mockResolvedValue(1),
+    ttl: vi.fn().mockResolvedValue(3600),
+    incr: vi.fn().mockResolvedValue(1),
+    incrby: vi.fn().mockResolvedValue(5),
+    keys: vi.fn().mockResolvedValue([]),
+    info: vi.fn().mockResolvedValue('used_memory_human:1.5M\n'),
+    dbsize: vi.fn().mockResolvedValue(100),
+    ping: vi.fn().mockResolvedValue('PONG'),
+    quit: vi.fn().mockResolvedValue('OK'),
+    on: vi.fn(),
+    status: 'ready',
+  };
+
+  return {
+    default: vi.fn(() => mockClient),
+  };
+});
+
+import {
+  createCachePlugin,
+  getCache,
+  hasCache,
+  type CachePluginConfig,
+} from './cache-plugin.js';
+
+describe('Cache Plugin', () => {
+  const mockConfig: CachePluginConfig = {
+    url: 'redis://localhost:6379',
+    keyPrefix: 'test:',
+    defaultTtl: 3600,
+    healthCheck: false, // Disable for unit tests
+  };
+
+  const mockContext = {
+    config: { productName: 'Test', port: 3000 },
+    app: {} as any,
+    router: {} as any,
+    logger: {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    },
+    registerHealthCheck: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    // Clean up any registered instances
+    if (hasCache('test')) {
+      const cache = getCache('test');
+      await cache.close();
+    }
+  });
+
+  describe('createCachePlugin', () => {
+    it('should create a plugin with correct name', () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      expect(plugin.name).toBe('cache:test');
+    });
+
+    it('should use "default" as instance name when not specified', () => {
+      const plugin = createCachePlugin(mockConfig);
+      expect(plugin.name).toBe('cache:default');
+    });
+
+    it('should have low order number (initialize early)', () => {
+      const plugin = createCachePlugin(mockConfig);
+      expect(plugin.order).toBeLessThan(10);
+    });
+  });
+
+  describe('onInit', () => {
+    it('should register the cache instance', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(hasCache('test')).toBe(true);
+    });
+
+    it('should log debug message on successful connection', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(mockContext.logger.debug).toHaveBeenCalledWith(
+        expect.stringContaining('connected')
+      );
+    });
+
+    it('should register health check when enabled', async () => {
+      const configWithHealth = { ...mockConfig, healthCheck: true };
+      const plugin = createCachePlugin(configWithHealth, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(mockContext.registerHealthCheck).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'redis',
+          type: 'custom',
+        })
+      );
+    });
+
+    it('should use custom health check name when provided', async () => {
+      const configWithCustomName = {
+        ...mockConfig,
+        healthCheck: true,
+        healthCheckName: 'custom-cache',
+      };
+      const plugin = createCachePlugin(configWithCustomName, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(mockContext.registerHealthCheck).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'custom-cache',
+        })
+      );
+    });
+  });
+
+  describe('getCache', () => {
+    it('should return registered instance', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      const cache = getCache('test');
+      expect(cache).toBeDefined();
+      expect(cache.get).toBeDefined();
+      expect(cache.set).toBeDefined();
+      expect(cache.delete).toBeDefined();
+    });
+
+    it('should throw error for unregistered instance', () => {
+      expect(() => getCache('nonexistent')).toThrow(
+        'Cache instance "nonexistent" not found'
+      );
+    });
+  });
+
+  describe('hasCache', () => {
+    it('should return false for unregistered instance', () => {
+      expect(hasCache('nonexistent')).toBe(false);
+    });
+
+    it('should return true for registered instance', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(hasCache('test')).toBe(true);
+    });
+  });
+
+  describe('CacheInstance', () => {
+    it('should get value and parse JSON', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      const cache = getCache('test');
+      // Mock will return null by default
+      const result = await cache.get('key');
+      expect(result).toBeNull();
+    });
+
+    it('should set value with JSON stringification', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      const cache = getCache('test');
+      await cache.set('key', { foo: 'bar' }, 3600);
+      // Just verify it doesn't throw
+    });
+
+    it('should return cache stats', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      const cache = getCache('test');
+      const stats = await cache.getStats();
+      expect(stats).toHaveProperty('connected');
+      expect(stats).toHaveProperty('keyCount');
+    });
+
+    it('should check if key exists', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      const cache = getCache('test');
+      const exists = await cache.exists('key');
+      expect(typeof exists).toBe('boolean');
+    });
+
+    it('should get TTL for a key', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      const cache = getCache('test');
+      const ttl = await cache.ttl('key');
+      expect(typeof ttl).toBe('number');
+    });
+
+    it('should increment a value', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      const cache = getCache('test');
+      const value = await cache.incr('counter');
+      expect(typeof value).toBe('number');
+    });
+  });
+
+  describe('onShutdown', () => {
+    it('should close client and unregister instance', async () => {
+      const plugin = createCachePlugin(mockConfig, 'test');
+      await plugin.onInit?.(mockContext as any);
+
+      expect(hasCache('test')).toBe(true);
+
+      await plugin.onShutdown?.();
+
+      expect(hasCache('test')).toBe(false);
+    });
+  });
+});