@qwickapps/server 1.5.1 → 1.6.0

package/dist-ui-lib/pages/APIKeysPage.d.ts

@@ -0,0 +1,13 @@
+/**
+ * APIKeysPage Component
+ *
+ * API key management page for authentication and authorization.
+ * Allows users to create, view, and manage API keys with scopes.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+export interface APIKeysPageProps {
+    title?: string;
+    subtitle?: string;
+}
+export declare function APIKeysPage({ title, subtitle, }: APIKeysPageProps): import("react/jsx-runtime").JSX.Element;

package/dist-ui-lib/pages/AcceptInvitationPage.d.ts

@@ -0,0 +1,28 @@
+/**
+ * AcceptInvitationPage Component
+ *
+ * Standalone page for users to accept invitations and activate their accounts.
+ * Can be used in control panel or frontend applications.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import { type User } from '../api/controlPanelApi';
+export interface AcceptInvitationPageProps {
+    /** Invitation token (if not provided, will extract from URL) */
+    token?: string;
+    /** Title text */
+    title?: string;
+    /** Subtitle text */
+    subtitle?: string;
+    /** Success message */
+    successMessage?: string;
+    /** URL to redirect to after successful activation (optional) */
+    redirectUrl?: string;
+    /** Label for the redirect button */
+    redirectLabel?: string;
+    /** Callback when invitation is accepted successfully */
+    onSuccess?: (user: User) => void;
+    /** Callback when invitation acceptance fails */
+    onError?: (error: string) => void;
+}
+export declare function AcceptInvitationPage({ token: tokenProp, title, subtitle, successMessage, redirectUrl, redirectLabel, onSuccess, onError, }: AcceptInvitationPageProps): import("react/jsx-runtime").JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qwickapps/server",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Plugin-based application server framework for building websites, APIs, admin dashboards, and full-stack products",
   "type": "module",
   "main": "dist/index.js",
@@ -54,7 +54,8 @@
     "cors": "^2.8.5",
     "express": "^4.18.2",
     "helmet": "^7.1.0",
-    "http-proxy-middleware": "^3.0.3"
+    "http-proxy-middleware": "^3.0.3",
+    "zod": "^3.22.4"
   },
   "devDependencies": {
     "@emotion/react": "^11.14.0",

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 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 = [route.handler];
+
+      switch (route.method) {
+        case 'get':
+          router.get(route.path, ...handlers);
+          break;
+        case 'post':
+          router.post(route.path, ...handlers);
+          break;
+        case 'put':
+          router.put(route.path, ...handlers);
+          break;
+        case 'delete':
+          router.delete(route.path, ...handlers);
+          break;
+        case 'patch':
+          router.patch(route.path, ...handlers);
+          break;
+        case 'use':
+          router.use(route.path, ...handlers);
+          break;
+      }
+
+      logger.debug(`  ${route.method.toUpperCase()} ${apiBasePath}${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';