@qwickapps/server 1.5.1 → 1.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qwickapps/server",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Plugin-based application server framework for building websites, APIs, admin dashboards, and full-stack products",
   "type": "module",
   "main": "dist/index.js",

package/src/core/control-panel.ts

@@ -378,6 +378,53 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
       }
     }
 
+    // Register all routes with automatic ordering by path specificity
+    const routes = pluginRegistry.getRoutes();
+
+    // Sort routes by path specificity (longest first, wildcards last)
+    routes.sort((a, b) => {
+      // Wildcards last
+      const aWild = a.path.includes('*') ? 1 : 0;
+      const bWild = b.path.includes('*') ? 1 : 0;
+      if (aWild !== bWild) return aWild - bWild;
+
+      // Longer paths first (more specific)
+      return b.path.length - a.path.length;
+    });
+
+    // Register routes with Express
+    logger.debug(`Registering ${routes.length} routes in priority order:`);
+    for (const route of routes) {
+      // TODO: Add auth middleware if route.auth?.required
+      // For now, just register the handler
+      // Auth will be handled by auth plugin middleware globally
+
+      const handlers = [route.handler];
+
+      switch (route.method) {
+        case 'get':
+          app.get(route.path, ...handlers);
+          break;
+        case 'post':
+          app.post(route.path, ...handlers);
+          break;
+        case 'put':
+          app.put(route.path, ...handlers);
+          break;
+        case 'delete':
+          app.delete(route.path, ...handlers);
+          break;
+        case 'patch':
+          app.patch(route.path, ...handlers);
+          break;
+        case 'use':
+          app.use(route.path, ...handlers);
+          break;
+      }
+
+      logger.debug(`  ${route.method.toUpperCase()} ${route.path}`);
+    }
+
     return new Promise((resolve) => {
       server = app.listen(config.port, () => {
         logger.debug(`Control panel listening on port ${config.port}`);

package/src/core/guards.ts

@@ -6,6 +6,7 @@
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
+import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { Request, Response, NextFunction, RequestHandler } from 'express';
 import type {
   RouteGuardConfig,
@@ -14,6 +15,68 @@ import type {
   Auth0GuardConfig,
 } from './types.js';
 
+// Session cookie configuration
+const SESSION_COOKIE_NAME = 'cpanel_session';
+const DEFAULT_SESSION_DURATION_HOURS = 8;
+
+/**
+ * Create a signed session token with expiration
+ */
+function createSessionToken(secret: string, durationHours: number): string {
+  const expiresAt = Date.now() + durationHours * 60 * 60 * 1000;
+  const payload = `cpanel:${expiresAt}`;
+  const signature = createHmac('sha256', secret).update(payload).digest('hex');
+  return `${payload}:${signature}`;
+}
+
+/**
+ * Verify a session token and check expiration
+ */
+function verifySessionToken(token: string, secret: string): boolean {
+  const parts = token.split(':');
+  if (parts.length !== 3 || parts[0] !== 'cpanel') {
+    return false;
+  }
+
+  const [prefix, expiresAt, signature] = parts;
+  const payload = `${prefix}:${expiresAt}`;
+
+  // Verify signature
+  const expectedSignature = createHmac('sha256', secret).update(payload).digest('hex');
+  try {
+    if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+
+  // Check expiration
+  const expires = parseInt(expiresAt, 10);
+  if (isNaN(expires) || Date.now() > expires) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Parse cookies from Cookie header
+ */
+function parseCookies(cookieHeader: string | undefined): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  if (!cookieHeader) return cookies;
+
+  cookieHeader.split(';').forEach((cookie) => {
+    const [name, ...rest] = cookie.trim().split('=');
+    if (name && rest.length > 0) {
+      cookies[name] = rest.join('=');
+    }
+  });
+
+  return cookies;
+}
+
 /**
  * Create a route guard middleware from configuration
  */
@@ -34,11 +97,18 @@ export function createRouteGuard(config: RouteGuardConfig): RequestHandler {
 
 /**
  * Create basic auth guard middleware
+ *
+ * This guard supports session cookies to prevent repeated login prompts.
+ * After successful Basic Auth, a signed session cookie is set that allows
+ * subsequent requests to proceed without re-prompting for credentials.
  */
 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 || [];
+  const sessionDurationHours = config.sessionDurationHours ?? DEFAULT_SESSION_DURATION_HOURS;
+  // Use password as HMAC secret for session tokens
+  const sessionSecret = config.password;
 
   return (req: Request, res: Response, next: NextFunction) => {
     // Check if path is excluded
@@ -46,11 +116,30 @@ function createBasicAuthGuard(config: BasicAuthGuardConfig): RequestHandler {
       return next();
     }
 
+    // Check for valid session cookie first
+    const cookies = parseCookies(req.headers.cookie);
+    const sessionToken = cookies[SESSION_COOKIE_NAME];
+    if (sessionToken && verifySessionToken(sessionToken, sessionSecret)) {
+      return next();
+    }
+
+    // Check Authorization header
     const authHeader = req.headers.authorization;
     if (authHeader === expectedAuth) {
+      // Set session cookie on successful auth
+      const token = createSessionToken(sessionSecret, sessionDurationHours);
+      const maxAge = sessionDurationHours * 60 * 60; // seconds
+      // Add Secure flag when running over HTTPS
+      const isSecure = req.secure || req.headers['x-forwarded-proto'] === 'https';
+      const secureFlag = isSecure ? ' Secure;' : '';
+      res.setHeader(
+        'Set-Cookie',
+        `${SESSION_COOKIE_NAME}=${token}; Path=/; HttpOnly; SameSite=Strict;${secureFlag} Max-Age=${maxAge}`
+      );
       return next();
     }
 
+    // No valid session or auth header - prompt for credentials
     res.setHeader('WWW-Authenticate', `Basic realm="${realm}"`);
     res.status(401).json({
       error: 'Unauthorized',

package/src/core/health-manager.ts

@@ -182,6 +182,10 @@ export class HealthManager {
 
   /**
    * Get aggregated status
+   *
+   * Returns 'degraded' instead of 'unhealthy' when subsystems fail,
+   * allowing the service to remain available even when dependencies are down.
+   * This ensures the control panel and other features remain accessible.
    */
   getAggregatedStatus(): HealthStatus {
     const results = Array.from(this.results.values());
@@ -191,7 +195,8 @@ export class HealthManager {
     const unhealthyCount = results.filter((r) => r.status === 'unhealthy').length;
     const degradedCount = results.filter((r) => r.status === 'degraded').length;
 
-    if (unhealthyCount > 0) return 'unhealthy';
+    // Return 'degraded' instead of 'unhealthy' to keep service available (HTTP 200)
+    if (unhealthyCount > 0) return 'degraded';
     if (degradedCount > 0) return 'degraded';
 
     const hasUnknown = results.some((r) => r.status === 'unknown');

package/src/core/plugin-registry.ts

@@ -51,10 +51,19 @@ export interface PluginInfo {
   id: string;
   name: string;
   version?: string;
+  type: PluginType;
+  slug?: string;  // Current slug (may be customized)
   status: 'starting' | 'active' | 'stopped' | 'error';
   error?: string;
 }
 
+/**
+ * Plugin type determines routing capabilities
+ * - regular: Can only handle routes under their slug prefix (e.g., /mcp/*)
+ * - system: Can handle any path (e.g., /*, /auth/*)
+ */
+export type PluginType = 'regular' | 'system';
+
 /**
  * The Plugin interface - simple lifecycle with event handling
  */
@@ -68,6 +77,30 @@ export interface Plugin {
   /** Plugin version (semver) */
   version?: string;
 
+  /**
+   * Plugin type determines routing capabilities
+   * - regular: Must use slug prefix for all routes
+   * - system: Can register routes at any path
+   * Default: 'regular'
+   */
+  type?: PluginType;
+
+  /**
+   * Default slug for regular plugins (path prefix for routes)
+   * Example: 'mcp' makes routes available under /mcp/*
+   * Can be overridden via plugin config
+   * Ignored for system plugins
+   */
+  slug?: string;
+
+  /**
+   * Configuration options for this plugin
+   */
+  configurable?: {
+    /** Allow users to customize the slug via UI */
+    slug?: boolean;
+  };
+
   /**
    * Called when the plugin starts.
    * Initialize resources, register routes/UI contributions here.
@@ -150,18 +183,34 @@ export interface WidgetContribution {
   pluginId: string;
 }
 
+/**
+ * Auth configuration for routes
+ */
+export interface RouteAuthConfig {
+  /** Whether authentication is required */
+  required: boolean;
+  /** Allowed roles (if auth required) */
+  roles?: string[];
+  /** Paths to exclude from auth (for middleware routes using 'use' method) */
+  excludePaths?: string[];
+}
+
 /**
  * Route definition for API routes
  */
 export interface RouteDefinition {
-  /** HTTP method */
-  method: 'get' | 'post' | 'put' | 'delete' | 'patch';
-  /** Route path */
+  /** HTTP method (including 'use' for middleware) */
+  method: 'get' | 'post' | 'put' | 'delete' | 'patch' | 'use';
+  /** Route path (will be auto-prefixed with slug for regular plugins) */
   path: string;
   /** Request handler */
   handler: RequestHandler;
-  /** Plugin ID that contributed this */
-  pluginId: string;
+  /** Authentication configuration */
+  auth?: RouteAuthConfig;
+  /** Plugin ID that contributed this (set automatically) */
+  pluginId?: string;
+  /** Original path before slug prefixing (set automatically) */
+  originalPath?: string;
 }
 
 /**
@@ -321,6 +370,8 @@ export class PluginRegistryImpl implements PluginRegistry {
   private pluginStatus = new Map<string, PluginInfo['status']>();
   private pluginErrors = new Map<string, string>();
   private pluginConfigs = new Map<string, PluginConfig>();
+  private pluginSlugs = new Map<string, string>();  // pluginId -> slug
+  private currentPlugin: string | null = null;  // Track plugin during onStart
 
   private routes: RouteDefinition[] = [];
   private menuItems: MenuContribution[] = [];
@@ -371,6 +422,8 @@ export class PluginRegistryImpl implements PluginRegistry {
       id: plugin.id,
       name: plugin.name,
       version: plugin.version,
+      type: plugin.type || 'regular',
+      slug: this.pluginSlugs.get(plugin.id),
       status: this.pluginStatus.get(plugin.id) || 'stopped',
       error: this.pluginErrors.get(plugin.id),
     }));
@@ -381,28 +434,34 @@ export class PluginRegistryImpl implements PluginRegistry {
   // ---------------------------------------------------------------------------
 
   addRoute(route: RouteDefinition): void {
-    this.routes.push(route);
-
-    // Register with Express router
-    switch (route.method) {
-      case 'get':
-        this.router.get(route.path, route.handler);
-        break;
-      case 'post':
-        this.router.post(route.path, route.handler);
-        break;
-      case 'put':
-        this.router.put(route.path, route.handler);
-        break;
-      case 'delete':
-        this.router.delete(route.path, route.handler);
-        break;
-      case 'patch':
-        this.router.patch(route.path, route.handler);
-        break;
+    if (!this.currentPlugin) {
+      throw new Error('addRoute can only be called during plugin.onStart()');
     }
 
-    this.logger.debug(`Route registered: ${route.method.toUpperCase()} ${route.path} by ${route.pluginId}`);
+    const plugin = this.plugins.get(this.currentPlugin)!;
+    const pluginType = plugin.type || 'regular';
+    const originalPath = route.path;
+    let fullPath = route.path;
+
+    // Auto-prefix for regular plugins
+    if (pluginType === 'regular') {
+      const slug = this.pluginSlugs.get(this.currentPlugin)!;
+      fullPath = `/${slug}${route.path}`;
+    }
+
+    const routeWithMetadata: RouteDefinition = {
+      ...route,
+      path: fullPath,
+      pluginId: this.currentPlugin,
+      originalPath,
+    };
+
+    this.routes.push(routeWithMetadata);
+
+    this.logger.debug(
+      `Route registered: ${route.method.toUpperCase()} ${fullPath} by ${this.currentPlugin}` +
+      (pluginType === 'regular' ? ` (original: ${originalPath})` : '')
+    );
   }
 
   addMenuItem(menu: MenuContribution): void {
@@ -572,6 +631,22 @@ export class PluginRegistryImpl implements PluginRegistry {
     return this.healthManager;
   }
 
+  // ---------------------------------------------------------------------------
+  // Slug management (internal)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Check if a slug is available
+   */
+  private isSlugAvailable(slug: string, excludePluginId?: string): boolean {
+    for (const [pluginId, existingSlug] of this.pluginSlugs.entries()) {
+      if (pluginId !== excludePluginId && existingSlug === slug) {
+        return false;
+      }
+    }
+    return true;
+  }
+
   // ---------------------------------------------------------------------------
   // Plugin lifecycle management (internal)
   // ---------------------------------------------------------------------------
@@ -583,6 +658,27 @@ export class PluginRegistryImpl implements PluginRegistry {
     this.plugins.set(plugin.id, plugin);
     this.pluginConfigs.set(plugin.id, config);
     this.pluginStatus.set(plugin.id, 'starting');
+    this.currentPlugin = plugin.id;
+
+    const pluginType = plugin.type || 'regular';
+
+    // Handle slug for regular plugins
+    if (pluginType === 'regular') {
+      const slug = (config.slug as string | undefined) || plugin.slug || plugin.id;
+
+      // Validate slug uniqueness
+      if (!this.isSlugAvailable(slug, plugin.id)) {
+        this.currentPlugin = null;
+        const errorMessage = `Slug conflict: "${slug}" already in use`;
+        this.pluginStatus.set(plugin.id, 'error');
+        this.pluginErrors.set(plugin.id, errorMessage);
+        this.logger.error(`Plugin ${plugin.id} failed to start: ${errorMessage}`);
+        return false;
+      }
+
+      this.pluginSlugs.set(plugin.id, slug);
+      this.logger.debug(`Plugin ${plugin.id} registered with slug: ${slug}`);
+    }
 
     try {
       await Promise.race([
@@ -592,6 +688,7 @@ export class PluginRegistryImpl implements PluginRegistry {
 
       this.pluginStatus.set(plugin.id, 'active');
       this.pluginErrors.delete(plugin.id);
+      this.currentPlugin = null;
 
       this.emit({
         type: 'plugin:started',
@@ -605,6 +702,7 @@ export class PluginRegistryImpl implements PluginRegistry {
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.pluginStatus.set(plugin.id, 'error');
       this.pluginErrors.set(plugin.id, errorMessage);
+      this.currentPlugin = null;
 
       this.emit({
         type: 'plugin:error',

package/src/core/types.ts

@@ -24,6 +24,8 @@ export interface BasicAuthGuardConfig {
   realm?: string;
   /** Paths to exclude from authentication (e.g., ['/health']) */
   excludePaths?: string[];
+  /** Session cookie duration in hours (default: 8) */
+  sessionDurationHours?: number;
 }
 
 /**

package/src/index.ts

@@ -262,6 +262,10 @@ export {
   getActivityLog,
   postgresParentalStore,
   kidsAdapter,
+  // QwickBrain plugin
+  createQwickBrainPlugin,
+  getConnectionStatus,
+  isConnected,
 } from './plugins/index.js';
 export type {
   HealthPluginConfig,
@@ -414,4 +418,11 @@ export type {
   ParentalApiConfig,
   PostgresParentalStoreConfig,
   KidsAdapterConfig,
+  // QwickBrain plugin types
+  QwickBrainPluginConfig,
+  MCPToolDefinition,
+  MCPToolCallRequest,
+  MCPToolCallResponse,
+  QwickBrainConnectionStatus,
+  MCPRateLimitConfig,
 } from './plugins/index.js';

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

@@ -174,3 +174,170 @@ describe('Auth Plugin helpers', () => {
     expect(authModule.requireAnyRole).toBeDefined();
   });
 });
+
+describe('onAuthenticated callback', () => {
+  // Mock adapter that always authenticates
+  function createMockAdapter(user: AuthenticatedUser | null): ReturnType<typeof basicAdapter> {
+    return {
+      name: 'mock',
+      initialize: () => (_req: Request, _res: Response, next: NextFunction) => next(),
+      isAuthenticated: () => user !== null,
+      getUser: () => user,
+    };
+  }
+
+  it('should call onAuthenticated callback after successful authentication', async () => {
+    const { createAuthPlugin } = await import('./auth-plugin.js');
+    const mockUser: AuthenticatedUser = {
+      id: 'user-123',
+      email: 'test@example.com',
+      name: 'Test User',
+    };
+    const onAuthenticated = vi.fn().mockResolvedValue(undefined);
+
+    const plugin = createAuthPlugin({
+      adapter: createMockAdapter(mockUser),
+      authRequired: false,
+      onAuthenticated,
+    });
+
+    // Create mock registry
+    const mockApp = {
+      use: vi.fn(),
+    };
+    const mockRegistry = {
+      getApp: () => mockApp,
+      addRoute: vi.fn(),
+    };
+
+    // Start the plugin to register middleware
+    await plugin.onStart?.({} as never, mockRegistry as never);
+
+    // Get the auth middleware (last middleware added)
+    const authMiddleware = mockApp.use.mock.calls[mockApp.use.mock.calls.length - 1][0];
+
+    // Call middleware
+    const req = createMockRequest();
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    await authMiddleware(req, res, next);
+
+    expect(onAuthenticated).toHaveBeenCalledWith(mockUser);
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('should not call onAuthenticated when authentication fails', async () => {
+    const { createAuthPlugin } = await import('./auth-plugin.js');
+    const onAuthenticated = vi.fn().mockResolvedValue(undefined);
+
+    const plugin = createAuthPlugin({
+      adapter: createMockAdapter(null), // null user = not authenticated
+      authRequired: false,
+      onAuthenticated,
+    });
+
+    const mockApp = {
+      use: vi.fn(),
+    };
+    const mockRegistry = {
+      getApp: () => mockApp,
+      addRoute: vi.fn(),
+    };
+
+    await plugin.onStart?.({} as never, mockRegistry as never);
+
+    const authMiddleware = mockApp.use.mock.calls[mockApp.use.mock.calls.length - 1][0];
+
+    const req = createMockRequest();
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    await authMiddleware(req, res, next);
+
+    expect(onAuthenticated).not.toHaveBeenCalled();
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('should not fail authentication when onAuthenticated throws an error', async () => {
+    const { createAuthPlugin } = await import('./auth-plugin.js');
+    const mockUser: AuthenticatedUser = {
+      id: 'user-123',
+      email: 'test@example.com',
+      name: 'Test User',
+    };
+    const onAuthenticated = vi.fn().mockRejectedValue(new Error('Sync failed'));
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const plugin = createAuthPlugin({
+      adapter: createMockAdapter(mockUser),
+      authRequired: false,
+      onAuthenticated,
+    });
+
+    const mockApp = {
+      use: vi.fn(),
+    };
+    const mockRegistry = {
+      getApp: () => mockApp,
+      addRoute: vi.fn(),
+    };
+
+    await plugin.onStart?.({} as never, mockRegistry as never);
+
+    const authMiddleware = mockApp.use.mock.calls[mockApp.use.mock.calls.length - 1][0];
+
+    const req = createMockRequest();
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    await authMiddleware(req, res, next);
+
+    // Callback was called
+    expect(onAuthenticated).toHaveBeenCalledWith(mockUser);
+    // Error was logged
+    expect(consoleSpy).toHaveBeenCalled();
+    // Request still proceeds
+    expect(next).toHaveBeenCalled();
+    // Auth info is still set correctly
+    expect((req as unknown as { auth: { isAuthenticated: boolean } }).auth.isAuthenticated).toBe(true);
+
+    consoleSpy.mockRestore();
+  });
+
+  it('should not call onAuthenticated when callback is not provided', async () => {
+    const { createAuthPlugin } = await import('./auth-plugin.js');
+    const mockUser: AuthenticatedUser = {
+      id: 'user-123',
+      email: 'test@example.com',
+      name: 'Test User',
+    };
+
+    const plugin = createAuthPlugin({
+      adapter: createMockAdapter(mockUser),
+      authRequired: false,
+      // No onAuthenticated callback
+    });
+
+    const mockApp = {
+      use: vi.fn(),
+    };
+    const mockRegistry = {
+      getApp: () => mockApp,
+      addRoute: vi.fn(),
+    };
+
+    await plugin.onStart?.({} as never, mockRegistry as never);
+
+    const authMiddleware = mockApp.use.mock.calls[mockApp.use.mock.calls.length - 1][0];
+
+    const req = createMockRequest();
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    // Should not throw
+    await authMiddleware(req, res, next);
+
+    expect(next).toHaveBeenCalled();
+  });
+});

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

@@ -38,6 +38,7 @@ export function createAuthPlugin(config: AuthPluginConfig): Plugin {
     id: 'auth',
     name: 'Auth Plugin',
     version: '1.0.0',
+    type: 'system' as const,
 
     async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
       const app = registry.getApp();
@@ -181,6 +182,21 @@ export function createAuthPlugin(config: AuthPluginConfig): Plugin {
         accessToken: activeAdapter.getAccessToken?.(req) || undefined,
       };
 
+      // Call onAuthenticated callback if provided and user is authenticated
+      if (authenticated && user && config.onAuthenticated) {
+        try {
+          await config.onAuthenticated(user);
+          log('onAuthenticated callback completed', { userId: user.id, email: user.email });
+        } catch (error) {
+          // Log error but don't fail the request - auth succeeded, sync is optional
+          console.error('[AuthPlugin] onAuthenticated callback error:', {
+            userId: user.id,
+            email: user.email,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
       // Check if auth is required but user is not authenticated
       if (authRequired && !authenticated) {
         log('Auth required but not authenticated', { path: req.path });