@qwickapps/server 1.0.0 → 1.1.6

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,12 @@ export {
   createLogsPlugin,
   createConfigPlugin,
   createDiagnosticsPlugin,
+  createFrontendAppPlugin,
 } from './plugins/index.js';
 export type {
   HealthPluginConfig,
   LogsPluginConfig,
   ConfigPluginConfig,
   DiagnosticsPluginConfig,
+  FrontendAppPluginConfig,
 } from './plugins/index.js';

package/src/plugins/frontend-app-plugin.ts

@@ -0,0 +1,211 @@
+/**
+ * Frontend App Plugin
+ *
+ * Plugin for serving a frontend application at the root path (/).
+ * Supports:
+ * - Redirect to another URL
+ * - Serve static files
+ * - Display a landing page
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import express from 'express';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { ControlPanelPlugin, FrontendAppConfig } from '../core/types.js';
+import { createRouteGuard } from '../core/guards.js';
+
+export interface FrontendAppPluginConfig {
+  /** Redirect to another URL */
+  redirectUrl?: string;
+  /** Path to static files to serve */
+  staticPath?: string;
+  /** Landing page configuration */
+  landingPage?: {
+    title: string;
+    heading?: string;
+    description?: string;
+    links?: Array<{ label: string; url: string }>;
+    branding?: {
+      logo?: string;
+      primaryColor?: string;
+    };
+  };
+  /** Route guard configuration */
+  guard?: FrontendAppConfig['mount']['guard'];
+}
+
+/**
+ * Create a frontend app plugin that handles the root path
+ */
+export function createFrontendAppPlugin(config: FrontendAppPluginConfig): ControlPanelPlugin {
+  return {
+    name: 'frontend-app',
+    order: 0, // Run first to capture root path
+
+    async onInit(context) {
+      const { app, logger } = context;
+
+      // Apply guard if configured
+      if (config.guard && config.guard.type !== 'none') {
+        const guardMiddleware = createRouteGuard(config.guard);
+        // Apply guard only to root path
+        app.use('/', (req, res, next) => {
+          // Skip if not at root
+          if (req.path !== '/' && !req.path.startsWith('/?')) {
+            return next();
+          }
+          guardMiddleware(req, res, next);
+        });
+      }
+
+      // Priority 1: Redirect
+      if (config.redirectUrl) {
+        logger.info(`Frontend app: Redirecting / to ${config.redirectUrl}`);
+        app.get('/', (_req, res) => {
+          res.redirect(config.redirectUrl!);
+        });
+        return;
+      }
+
+      // Priority 2: Serve static files
+      if (config.staticPath && existsSync(config.staticPath)) {
+        logger.info(`Frontend app: Serving static files from ${config.staticPath}`);
+        app.use('/', express.static(config.staticPath));
+
+        // SPA fallback
+        app.get('/', (_req, res) => {
+          res.sendFile(resolve(config.staticPath!, 'index.html'));
+        });
+        return;
+      }
+
+      // Priority 3: Landing page
+      if (config.landingPage) {
+        logger.info(`Frontend app: Serving landing page`);
+        app.get('/', (_req, res) => {
+          const html = generateLandingPageHtml(config.landingPage!);
+          res.type('html').send(html);
+        });
+        return;
+      }
+
+      // Default: Simple welcome page
+      logger.info(`Frontend app: Serving default welcome page`);
+      app.get('/', (_req, res) => {
+        const html = generateLandingPageHtml({
+          title: context.config.productName,
+          heading: `Welcome to ${context.config.productName}`,
+          description: 'Your application is running.',
+          links: [
+            { label: 'Control Panel', url: context.config.mountPath || '/cpanel' },
+          ],
+        });
+        res.type('html').send(html);
+      });
+    },
+  };
+}
+
+/**
+ * Generate landing page HTML
+ */
+function generateLandingPageHtml(config: NonNullable<FrontendAppPluginConfig['landingPage']>): string {
+  const primaryColor = config.branding?.primaryColor || '#6366f1';
+
+  const linksHtml = (config.links || [])
+    .map(
+      (link) =>
+        `<a href="${link.url}" class="link">${link.label}</a>`
+    )
+    .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.title}</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: linear-gradient(135deg, #0f172a 0%, #1e293b 100%);
+      color: #e2e8f0;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    .container {
+      text-align: center;
+      max-width: 600px;
+      padding: 2rem;
+    }
+    ${config.branding?.logo ? `
+    .logo {
+      width: 80px;
+      height: 80px;
+      margin-bottom: 1.5rem;
+    }
+    ` : ''}
+    h1 {
+      font-size: 2.5rem;
+      color: ${primaryColor};
+      margin-bottom: 1rem;
+    }
+    p {
+      font-size: 1.125rem;
+      color: #94a3b8;
+      margin-bottom: 2rem;
+      line-height: 1.6;
+    }
+    .links {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 1rem;
+      justify-content: center;
+    }
+    .link {
+      display: inline-block;
+      padding: 0.875rem 2rem;
+      background: ${primaryColor};
+      color: white;
+      text-decoration: none;
+      border-radius: 0.5rem;
+      font-weight: 500;
+      transition: all 0.2s;
+    }
+    .link:hover {
+      transform: translateY(-2px);
+      box-shadow: 0 10px 20px rgba(0,0,0,0.3);
+    }
+    .footer {
+      position: fixed;
+      bottom: 1rem;
+      left: 0;
+      right: 0;
+      text-align: center;
+      color: #64748b;
+      font-size: 0.875rem;
+    }
+    .footer a {
+      color: ${primaryColor};
+      text-decoration: none;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    ${config.branding?.logo ? `<img src="${config.branding.logo}" alt="Logo" class="logo">` : ''}
+    <h1>${config.heading || config.title}</h1>
+    ${config.description ? `<p>${config.description}</p>` : ''}
+    ${linksHtml ? `<div class="links">${linksHtml}</div>` : ''}
+  </div>
+  <div class="footer">
+    Powered by <a href="https://qwickapps.com" target="_blank">QwickApps</a>
+  </div>
+</body>
+</html>`;
+}

package/src/plugins/index.ts

@@ -15,3 +15,6 @@ export type { ConfigPluginConfig } from './config-plugin.js';
 
 export { createDiagnosticsPlugin } from './diagnostics-plugin.js';
 export type { DiagnosticsPluginConfig } from './diagnostics-plugin.js';
+
+export { createFrontendAppPlugin } from './frontend-app-plugin.js';
+export type { FrontendAppPluginConfig } from './frontend-app-plugin.js';