@qwickapps/server 1.6.0 → 1.7.0

package/src/core/control-panel.ts

@@ -6,7 +6,13 @@
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
-import express, { type Application, type Router, type Request, type Response } from 'express';
+import express, {
+  type Application,
+  type Router,
+  type Request,
+  type Response,
+  type RequestHandler,
+} from 'express';
 import helmet from 'helmet';
 import cors from 'cors';
 import compression from 'compression';
@@ -29,6 +35,8 @@ import {
   type PluginConfig,
   type PluginRegistryImpl,
 } from './plugin-registry.js';
+import { bearerTokenAuth } from '../plugins/api-keys/index.js';
+import { createCorePlugin } from '../plugins/core/index.js';
 
 // Get the package root directory for serving UI assets
 const __filename = fileURLToPath(import.meta.url);
@@ -60,6 +68,61 @@ export interface CreateControlPanelOptions {
   logging?: LoggingConfig;
 }
 
+/**
+ * Infer a descriptive route name from path and method
+ * Examples:
+ *   /api/logs + GET → query
+ *   /api/logs/sources + GET → sources
+ *   /api/users/:id + GET → get
+ *   /api/users + POST → create
+ */
+function inferRouteName(path: string, method: string, pluginId?: string): string {
+  // Remove /api prefix and leading/trailing slashes
+  let cleanPath = path.replace(/^\/api\//, '').replace(/^\/|\/$/g, '');
+
+  // For non-core plugins, strip the plugin slug prefix from the path
+  if (pluginId && pluginId !== 'core' && cleanPath.startsWith(pluginId + '/')) {
+    cleanPath = cleanPath.substring(pluginId.length + 1);
+  } else if (pluginId && pluginId !== 'core' && cleanPath === pluginId) {
+    // Handle root path for plugin (e.g., /logs -> '')
+    cleanPath = '';
+  }
+
+  // Split into segments
+  const segments = cleanPath.split('/').filter(Boolean);
+
+  // If path has parameters (e.g., /users/:id), use method-based naming
+  if (path.includes(':')) {
+    const methodMap: Record<string, string> = {
+      get: 'get',
+      post: 'create',
+      put: 'update',
+      patch: 'update',
+      delete: 'delete',
+    };
+    return methodMap[method.toLowerCase()] || method.toLowerCase();
+  }
+
+  // For root paths (plugin root), use 'query' for GET, otherwise method name
+  if (segments.length === 0) {
+    if (method.toLowerCase() === 'get') {
+      return 'query';
+    }
+    return method.toLowerCase();
+  }
+
+  if (segments.length === 1) {
+    // Single segment paths like /sources, /health, /info, /invite, /sync, /stats
+    // Use the segment name directly for all methods
+    const segment = segments[0];
+    // Convert hyphens to camelCase (ui-contributions -> uiContributions)
+    return segment.replace(/-./g, x => x[1].toUpperCase());
+  }
+
+  // Multi-segment paths like /logs/sources - use last segment
+  return segments[segments.length - 1];
+}
+
 /**
  * Create a control panel instance
  */
@@ -129,129 +192,72 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
     // Only protect the control panel path, not the root or other paths
     app.use(mountPath, guardMiddleware);
   }
-  const apiBasePath = mountPath === '/' ? '/api' : `${mountPath}/api`;
-
   // Request logging
   app.use((req, _res, next) => {
     logger.debug(`${req.method} ${req.path}`);
     next();
   });
 
-  // Mount router at the configured path
-  app.use(apiBasePath, router);
+  // CRITICAL: System APIs always mount at /api regardless of mountPath
+  // This ensures consistent API paths across all products
+  // See: ADR-012-QwickApps-Server-Routing-Architecture
+  app.use('/api', router);
 
   // Built-in routes
 
-  /**
-   * GET /api/health - Aggregated health status
-   */
-  router.get('/health', (_req: Request, res: Response) => {
-    const results = healthManager.getResults();
-    const status = healthManager.getAggregatedStatus();
-    const uptime = Date.now() - startTime;
-
-    res.status(status === 'healthy' ? 200 : status === 'degraded' ? 200 : 503).json({
-      status,
-      timestamp: new Date().toISOString(),
-      uptime,
-      checks: results,
-    });
-  });
+  // Core routes (/health, /info, /diagnostics, /ui-contributions, /plugins) have been moved
+  // to the core plugin (src/plugins/core/index.ts) so they appear in the API client manifest
 
   /**
-   * GET /api/info - Product information
+   * GET /api/client-manifest - Route manifest for client code generation
+   *
+   * Returns all registered API routes with metadata for dynamic client building.
+   * Frontend applications can fetch this manifest to auto-generate typed API clients.
    */
-  router.get('/info', (_req: Request, res: Response) => {
-    res.json({
-      product: config.productName,
-      logoName: config.logoName || config.productName,
-      logoIconUrl: config.logoIconUrl,
-      version: config.version || 'unknown',
-      uptime: Date.now() - startTime,
-      links: config.links || [],
-      branding: config.branding || {},
-    });
-  });
+  router.get('/client-manifest', (_req: Request, res: Response) => {
+    const routes = pluginRegistry.getRoutes();
 
-  /**
-   * GET /api/diagnostics - Full diagnostics for AI agents
-   */
-  router.get('/diagnostics', (_req: Request, res: Response) => {
-    const report = getDiagnostics();
-    res.json(report);
-  });
+    // Build manifest with namespaced keys (pluginId.routeName)
+    const manifest: Record<string, {
+      method: string;
+      path: string;
+      auth: boolean;
+    }> = {};
 
-  /**
-   * GET /api/ui-contributions - UI contributions from all plugins
-   *
-   * Returns menu items, pages, and widgets registered by plugins.
-   * Used by the React UI to build dynamic navigation and pages.
-   */
-  router.get('/ui-contributions', (_req: Request, res: Response) => {
-    res.json({
-      menuItems: pluginRegistry.getMenuItems(),
-      pages: pluginRegistry.getPages(),
-      widgets: pluginRegistry.getWidgets(),
-      plugins: pluginRegistry.listPlugins(),
-    });
-  });
+    for (const route of routes) {
+      // Skip middleware routes (method: 'use')
+      if (route.method === 'use') {
+        continue;
+      }
 
-  /**
-   * GET /api/plugins - List all registered plugins with contribution counts
-   */
-  router.get('/plugins', (_req: Request, res: Response) => {
-    const plugins = pluginRegistry.listPlugins().map((plugin) => {
-      const contributions = pluginRegistry.getPluginContributions(plugin.id);
-      return {
-        ...plugin,
-        contributionCounts: {
-          routes: contributions.routes.length,
-          menuItems: contributions.menuItems.length,
-          pages: contributions.pages.length,
-          widgets: contributions.widgets.length,
-          hasConfig: !!contributions.config,
-        },
-      };
-    });
-    res.json({ plugins });
-  });
+      const pluginId = route.pluginId || 'core';
+      const routeName = inferRouteName(route.path, route.method, pluginId);
+      const key = `${pluginId}.${routeName}`;
 
-  /**
-   * GET /api/plugins/:id - Get detailed plugin info with contributions
-   */
-  router.get('/plugins/:id', (req: Request, res: Response) => {
-    const { id } = req.params;
-    const plugins = pluginRegistry.listPlugins();
-    const plugin = plugins.find((p) => p.id === id);
-
-    if (!plugin) {
-      res.status(404).json({ error: `Plugin not found: ${id}` });
-      return;
+      manifest[key] = {
+        method: route.method.toUpperCase(),
+        path: `/api${route.path}`,
+        auth: route.auth?.required || false,
+      };
     }
 
-    const contributions = pluginRegistry.getPluginContributions(id);
-    res.json({
-      ...plugin,
-      contributions,
-    });
+    res.json({ routes: manifest, version: '1.0' });
   });
 
   /**
    * Serve dashboard UI at the configured mount path
    *
-   * Priority:
-   * 1. If useRichUI is true and dist-ui exists, serve React SPA
-   * 2. Otherwise serve simple static HTML dashboard
+   * ONLY serves the React SPA from dist-ui. No HTML fallback.
    */
   if (!config.disableDashboard) {
     // Use customUiPath if provided, otherwise fall back to package's dist-ui
     const effectiveUiPath = config.customUiPath || uiDistPath;
     const hasRichUI = existsSync(effectiveUiPath);
-    const useRichUI = config.useRichUI !== false && hasRichUI;
-
-    logger.debug(`Dashboard config: mountPath=${mountPath}, effectiveUiPath=${effectiveUiPath}, hasRichUI=${hasRichUI}, useRichUI=${useRichUI}`);
 
-    if (useRichUI) {
+    if (!hasRichUI) {
+      logger.error(`React UI not found at ${effectiveUiPath}. Control panel UI will not be available.`);
+      logger.error(`Build the UI first: cd packages/qwickapps-server && npm run build:ui`);
+    } else {
       logger.debug(`Serving React UI from ${effectiveUiPath}`);
 
       // Read index.html template
@@ -297,8 +303,8 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
       // SPA fallback - serve index.html for all non-API routes under the mount path
       const spaFallbackPath = mountPath === '/' ? '/*' : `${mountPath}/*`;
       app.get(spaFallbackPath, (req: Request, res: Response, next) => {
-        // Skip API routes
-        if (req.path.startsWith(apiBasePath)) {
+        // Skip API routes (always at /api)
+        if (req.path.startsWith('/api')) {
           return next();
         }
         res.type('html').send(getIndexHtml(req));
@@ -310,13 +316,6 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
           res.type('html').send(getIndexHtml(req));
         });
       }
-    } else {
-      logger.debug(`Serving basic HTML dashboard`);
-      const dashboardPath = mountPath === '/' ? '/' : mountPath;
-      app.get(dashboardPath, (_req: Request, res: Response) => {
-        const html = generateDashboardHtml(config, healthManager.getResults(), mountPath);
-        res.type('html').send(html);
-      });
     }
   }
 
@@ -370,11 +369,26 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
 
   // Start server
   const start = async (): Promise<void> => {
+    // Start core plugin first (registers /info, /health, /diagnostics, etc.)
+    const corePlugin = createCorePlugin({
+      config,
+      startTime,
+      healthManager,
+      getDiagnostics,
+    });
+    const coreSuccess = await pluginRegistry.startPlugin(corePlugin, {});
+    if (!coreSuccess) {
+      logger.error('Failed to start core plugin');
+    }
+
     // Start initial plugins via registry
     for (const { plugin, config: pluginConfig } of plugins) {
       const success = await pluginRegistry.startPlugin(plugin, pluginConfig || {});
       if (!success) {
-        logger.error(`Failed to start plugin: ${plugin.id}`);
+        // Retrieve error details from registry for better debugging
+        const pluginInfo = pluginRegistry.listPlugins().find(p => p.id === plugin.id);
+        const errorDetails = pluginInfo?.error || 'Unknown error';
+        logger.error(`Failed to start plugin: ${plugin.id}`, { error: errorDetails });
       }
     }
 
@@ -395,11 +409,19 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
     // Register routes with Express router (mounted at apiBasePath)
     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: RequestHandler[] = [];
+
+      // Add auth middleware if route requires it
+      if (route.auth?.required) {
+        handlers.push(
+          bearerTokenAuth({
+            allowedKeyTypes: ['m2m'], // M2M keys for authenticated routes
+            requiredScopes: [], // No specific scopes required for now
+          })
+        );
+      }
 
-      const handlers = [route.handler];
+      handlers.push(route.handler);
 
       switch (route.method) {
         case 'get':
@@ -422,7 +444,7 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
           break;
       }
 
-      logger.debug(`  ${route.method.toUpperCase()} ${apiBasePath}${route.path}`);
+      logger.debug(`  ${route.method.toUpperCase()} /api${route.path}`);
     }
 
     return new Promise((resolve) => {
@@ -463,171 +485,6 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
   };
 }
 
-/**
- * Generate simple dashboard HTML
- */
-function generateDashboardHtml(
-  config: ControlPanelConfig,
-  health: Record<string, { status: string; latency?: number; lastChecked: Date }>,
-  mountPath: string = '/cpanel'
-): string {
-  const apiBasePath = mountPath === '/' ? '/api' : `${mountPath}/api`;
-  const healthEntries = Object.entries(health);
-  const overallStatus = healthEntries.every((e) => e[1].status === 'healthy')
-    ? 'healthy'
-    : healthEntries.some((e) => e[1].status === 'unhealthy')
-    ? 'unhealthy'
-    : 'degraded';
-
-  const statusColor =
-    overallStatus === 'healthy' ? '#22c55e' : overallStatus === 'degraded' ? '#f59e0b' : '#ef4444';
-
-  const linksHtml = (config.links || [])
-    .map(
-      (link) =>
-        `<a href="${link.url}" ${link.external ? 'target="_blank"' : ''} class="link">${link.label}</a>`
-    )
-    .join('');
-
-  const healthHtml = healthEntries
-    .map(
-      ([name, result]) => `
-      <div class="health-item">
-        <span class="status-dot" style="background-color: ${
-          result.status === 'healthy' ? '#22c55e' : result.status === 'degraded' ? '#f59e0b' : '#ef4444'
-        }"></span>
-        <span class="name">${name}</span>
-        <span class="latency">${result.latency ? `${result.latency}ms` : '-'}</span>
-      </div>
-    `
-    )
-    .join('');
-
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${config.productName} - Control Panel</title>
-  <style>
-    * { margin: 0; padding: 0; box-sizing: border-box; }
-    body {
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-      background: #0f172a;
-      color: #e2e8f0;
-      min-height: 100vh;
-      padding: 2rem;
-    }
-    .container { max-width: 1200px; margin: 0 auto; }
-    header {
-      display: flex;
-      justify-content: space-between;
-      align-items: center;
-      margin-bottom: 2rem;
-      padding-bottom: 1rem;
-      border-bottom: 1px solid #334155;
-    }
-    h1 { font-size: 1.5rem; color: ${config.branding?.primaryColor || '#6366f1'}; }
-    .status-badge {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.5rem;
-      padding: 0.5rem 1rem;
-      border-radius: 9999px;
-      background: ${statusColor}20;
-      color: ${statusColor};
-      font-weight: 600;
-    }
-    .status-dot {
-      width: 8px;
-      height: 8px;
-      border-radius: 50%;
-      background: currentColor;
-    }
-    .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1.5rem; }
-    .card {
-      background: #1e293b;
-      border-radius: 0.75rem;
-      padding: 1.5rem;
-      border: 1px solid #334155;
-    }
-    .card h2 {
-      font-size: 0.875rem;
-      text-transform: uppercase;
-      letter-spacing: 0.05em;
-      color: #94a3b8;
-      margin-bottom: 1rem;
-    }
-    .health-item {
-      display: flex;
-      align-items: center;
-      gap: 0.75rem;
-      padding: 0.75rem 0;
-      border-bottom: 1px solid #334155;
-    }
-    .health-item:last-child { border-bottom: none; }
-    .health-item .name { flex: 1; }
-    .health-item .latency { color: #64748b; font-size: 0.875rem; }
-    .links { display: flex; flex-wrap: wrap; gap: 0.75rem; }
-    .link {
-      display: inline-block;
-      padding: 0.75rem 1.5rem;
-      background: #334155;
-      color: #e2e8f0;
-      text-decoration: none;
-      border-radius: 0.5rem;
-      transition: background 0.2s;
-    }
-    .link:hover { background: #475569; }
-    .api-links { margin-top: 2rem; padding-top: 1rem; border-top: 1px solid #334155; }
-    .api-links a { color: #6366f1; margin-right: 1.5rem; text-decoration: none; }
-    .api-links a:hover { text-decoration: underline; }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <header>
-      <h1>${config.productName} Control Panel</h1>
-      <div class="status-badge">
-        <span class="status-dot"></span>
-        ${overallStatus.charAt(0).toUpperCase() + overallStatus.slice(1)}
-      </div>
-    </header>
-
-    <div class="cards">
-      <div class="card">
-        <h2>Health Checks</h2>
-        ${healthHtml || '<p style="color: #64748b;">No health checks configured</p>'}
-      </div>
-
-      ${
-        (config.links || []).length > 0
-          ? `
-      <div class="card">
-        <h2>Quick Links</h2>
-        <div class="links">${linksHtml}</div>
-      </div>
-      `
-          : ''
-      }
-    </div>
-
-    <div class="api-links">
-      <strong>API:</strong>
-      <a href="${apiBasePath}/health">Health</a>
-      <a href="${apiBasePath}/info">Info</a>
-      <a href="${apiBasePath}/diagnostics">Diagnostics</a>
-    </div>
-  </div>
-
-  <script>
-    // Auto-refresh health status every 10 seconds
-    setTimeout(() => location.reload(), 10000);
-  </script>
-</body>
-</html>`;
-}
-
 /**
  * Generate landing page HTML for root path
  */
@@ -641,10 +498,7 @@ function generateLandingPageHtml(options: {
 }): string {
   const { productName, title, heading, description, controlPanelPath, links = [] } = options;
 
-  const linksHtml = [
-    { label: 'Control Panel', url: controlPanelPath },
-    ...links,
-  ]
+  const linksHtml = links
     .map(
       (link) =>
         `<a href="${link.url}" class="link">${link.label}</a>`
@@ -739,3 +593,4 @@ function generateLandingPageHtml(options: {
 </body>
 </html>`;
 }
+

package/src/core/plugin-registry.ts

@@ -23,7 +23,7 @@ import { HealthManager } from './health-manager.js';
  * Events that plugins can react to
  */
 export type PluginEvent =
-  | { type: 'plugin:started'; pluginId: string; config: unknown }
+  | { type: 'plugin:started'; pluginId: string; plugin: Plugin; config: unknown }
   | { type: 'plugin:stopped'; pluginId: string }
   | { type: 'plugin:config-changed'; pluginId: string; key: string; oldValue: unknown; newValue: unknown }
   | { type: 'plugin:error'; pluginId: string; error: Error };
@@ -64,6 +64,18 @@ export interface PluginInfo {
  */
 export type PluginType = 'regular' | 'system';
 
+/**
+ * Plugin scope definition for API key authorization
+ */
+export interface PluginScope {
+  /** Scope name in format 'plugin-id:action' (e.g., 'qwickbrain:execute') */
+  name: string;
+  /** Human-readable description for UI */
+  description: string;
+  /** Optional category for grouping (read, write, admin) */
+  category?: 'read' | 'write' | 'admin';
+}
+
 /**
  * The Plugin interface - simple lifecycle with event handling
  */
@@ -93,6 +105,15 @@ export interface Plugin {
    */
   slug?: string;
 
+  /**
+   * Scopes that this plugin declares for API key authorization
+   * Format: 'plugin-id:action' (e.g., 'qwickbrain:execute')
+   *
+   * Scopes are registered automatically when the plugin starts and
+   * can be assigned to API keys for fine-grained access control.
+   */
+  scopes?: PluginScope[];
+
   /**
    * Configuration options for this plugin
    */
@@ -446,7 +467,22 @@ export class PluginRegistryImpl implements PluginRegistry {
     // Auto-prefix for regular plugins
     if (pluginType === 'regular') {
       const slug = this.pluginSlugs.get(this.currentPlugin)!;
-      fullPath = `/${slug}${route.path}`;
+
+      // Detect and auto-fix duplicate slug prefix (defensive measure)
+      // Example: Plugin 'users' should use prefix '/' not '/users'
+      // If configured as '/users', we auto-fix to '/' to prevent /api/users/users
+      let normalizedPath = route.path;
+      if (route.path.startsWith(`/${slug}/`) || route.path === `/${slug}`) {
+        normalizedPath = route.path.substring(slug.length + 1) || '/';
+        this.logger.warn(
+          `⚠️  DUPLICATE SLUG PREFIX DETECTED: Plugin '${this.currentPlugin}' configured with prefix='${route.path}'` +
+          `\n   Auto-fixed to prefix='${normalizedPath}' to prevent double-prefixing.` +
+          `\n   Please update plugin configuration to use prefix='${normalizedPath}' instead of prefix='${route.path}'.` +
+          `\n   See: packages/qwickapps-server/src/plugins/*/types.ts for correct prefix documentation.`
+        );
+      }
+
+      fullPath = `/${slug}${normalizedPath}`;
     }
 
     const routeWithMetadata: RouteDefinition = {
@@ -693,6 +729,7 @@ export class PluginRegistryImpl implements PluginRegistry {
       this.emit({
         type: 'plugin:started',
         pluginId: plugin.id,
+        plugin,
         config,
       });
 
@@ -710,7 +747,19 @@ export class PluginRegistryImpl implements PluginRegistry {
         error: error instanceof Error ? error : new Error(errorMessage),
       });
 
-      this.logger.error(`Plugin ${plugin.id} failed to start`, { error: errorMessage });
+      // Log full error with stack trace for debugging
+      if (error instanceof Error) {
+        this.logger.error(`Plugin ${plugin.id} failed to start: ${errorMessage}`, {
+          error: error.message,
+          stack: error.stack,
+          plugin: plugin.id,
+        });
+      } else {
+        this.logger.error(`Plugin ${plugin.id} failed to start: ${errorMessage}`, {
+          error: errorMessage,
+          plugin: plugin.id,
+        });
+      }
       return false;
     }
   }

package/src/index.ts

@@ -76,9 +76,11 @@ export type {
 export {
   createHealthPlugin,
   createLogsPlugin,
+  createMaintenancePlugin,
   createConfigPlugin,
   createDiagnosticsPlugin,
   createFrontendAppPlugin,
+  createCMSPlugin,
   // Postgres plugin
   createPostgresPlugin,
   getPostgres,
@@ -92,6 +94,7 @@ export {
   createAuthPluginFromEnv,
   getAuthStatus,
   setAuthConfigStore,
+  registerAuthConfigRoutes,
   postgresAuthConfigStore,
   isAuthenticated,
   getAuthenticatedUser,
@@ -123,6 +126,17 @@ export {
   unbanUser,
   listActiveBans,
   postgresBanStore,
+  // API Keys plugin (M2M authentication, depends on Users)
+  createApiKeysPlugin,
+  getApiKeysStore,
+  verifyApiKey,
+  createApiKey,
+  listApiKeys,
+  getApiKey,
+  updateApiKey,
+  deleteApiKey,
+  postgresApiKeyStore,
+  bearerTokenAuth,
   // Entitlements plugin
   createEntitlementsPlugin,
   getEntitlementSource,
@@ -270,9 +284,11 @@ export {
 export type {
   HealthPluginConfig,
   LogsPluginConfig,
+  MaintenancePluginConfig,
   ConfigPluginConfig,
   DiagnosticsPluginConfig,
   FrontendAppPluginConfig,
+  CMSPluginConfig,
   // Postgres plugin types
   PostgresPluginConfig,
   PostgresInstance,
@@ -316,6 +332,17 @@ export type {
   RemoveBanInput,
   BanCallbacks,
   PostgresBanStoreConfig,
+  // API Keys plugin types
+  ApiKeysPluginConfig,
+  ApiKeyStore,
+  ApiKey,
+  ApiKeyWithPlaintext,
+  ApiKeyScope,
+  ApiKeyType,
+  CreateApiKeyParams,
+  UpdateApiKeyParams,
+  PostgresApiKeyStoreConfig,
+  ApiKeysApiConfig,
   // Entitlements plugin types
   EntitlementsPluginConfig,
   EntitlementSource,