@qwickapps/server 1.2.0 → 1.3.0

package/src/core/types.ts

@@ -116,6 +116,16 @@ export interface ControlPanelConfig {
   /** Product name displayed in the control panel */
   productName: string;
 
+  /** Optional: Logo name for ProductLogo component (defaults to productName) */
+  logoName?: string;
+
+  /**
+   * Optional: URL path to the product logo icon (SVG, PNG, etc.).
+   * Used by the React UI to display a custom logo instead of the default QwickIcon.
+   * Example: '/cpanel/logo.svg'
+   */
+  logoIconUrl?: string;
+
   /** Port to run the control panel on */
   port: number;
 
@@ -124,7 +134,6 @@ export interface ControlPanelConfig {
 
   /** Optional: Branding configuration */
   branding?: {
-    logo?: string;
     primaryColor?: string;
     favicon?: string;
   };
@@ -168,40 +177,20 @@ export interface ControlPanelConfig {
   customUiPath?: string;
 }
 
-/**
- * Plugin Context - passed to plugins during initialization
- */
-export interface PluginContext {
-  config: ControlPanelConfig;
-  app: Application;
-  router: Router;
-  logger: Logger;
-  registerHealthCheck: (check: HealthCheck) => void;
-}
-
-/**
- * Control Panel Plugin interface
- */
-export interface ControlPanelPlugin {
-  /** Unique plugin name */
-  name: string;
-
-  /** Order for tab display (lower = first) */
-  order?: number;
-
-  /** API routes provided by this plugin */
-  routes?: Array<{
-    method: 'get' | 'post' | 'put' | 'delete';
-    path: string;
-    handler: RequestHandler;
-  }>;
-
-  /** Lifecycle: Initialize plugin */
-  onInit?: (context: PluginContext) => Promise<void>;
-
-  /** Lifecycle: Shutdown plugin */
-  onShutdown?: () => Promise<void>;
-}
+// Plugin types are now in plugin-registry.ts
+// Re-export for convenience
+export type {
+  Plugin,
+  PluginConfig,
+  PluginInfo,
+  PluginEvent,
+  PluginEventHandler,
+  PluginRegistry,
+  MenuContribution,
+  PageContribution,
+  WidgetContribution,
+  RouteDefinition,
+} from './plugin-registry.js';
 
 /**
  * Health Check types
@@ -283,14 +272,17 @@ export interface ControlPanelInstance {
   /** Stop the control panel server */
   stop: () => Promise<void>;
 
-  /** Register a plugin */
-  registerPlugin: (plugin: ControlPanelPlugin) => Promise<void>;
+  /** Start a plugin with optional configuration */
+  startPlugin: (plugin: import('./plugin-registry.js').Plugin, config?: import('./plugin-registry.js').PluginConfig) => Promise<boolean>;
 
   /** Get health check results */
   getHealthStatus: () => Record<string, HealthCheckResult>;
 
   /** Get diagnostics for AI agents */
   getDiagnostics: () => DiagnosticsReport;
+
+  /** Get the plugin registry for direct access */
+  getPluginRegistry: () => import('./plugin-registry.js').PluginRegistry;
 }
 
 /**
@@ -300,6 +292,8 @@ export interface DiagnosticsReport {
   timestamp: string;
   product: string;
   version?: string;
+  /** @qwickapps/server framework version */
+  frameworkVersion?: string;
   uptime: number;
   health: Record<string, HealthCheckResult>;
   system: {

package/src/index.ts

@@ -9,15 +9,33 @@
 
 // Core exports
 export { createControlPanel } from './core/control-panel.js';
+export type { CreateControlPanelOptions } from './core/control-panel.js';
 export { createGateway } from './core/gateway.js';
 export { HealthManager } from './core/health-manager.js';
 
-// Guards exports
+// Plugin Registry exports (event-driven architecture v2.0)
 export {
-  createRouteGuard,
-  isAuthenticated,
-  getAuthenticatedUser,
-} from './core/guards.js';
+  createPluginRegistry,
+  getPluginRegistry,
+  hasPluginRegistry,
+  resetPluginRegistry,
+  PluginRegistryImpl,
+} from './core/plugin-registry.js';
+export type {
+  Plugin,
+  PluginConfig,
+  PluginEvent,
+  PluginEventHandler,
+  PluginRegistry,
+  PluginInfo,
+  MenuContribution,
+  PageContribution,
+  WidgetContribution,
+  RouteDefinition,
+} from './core/plugin-registry.js';
+
+// Route guards (for control panel protection)
+export { createRouteGuard } from './core/guards.js';
 
 // Logging exports
 export {
@@ -29,9 +47,7 @@ export type { LoggingConfig } from './core/logging.js';
 
 export type {
   ControlPanelConfig,
-  ControlPanelPlugin,
   ControlPanelInstance,
-  PluginContext,
   HealthCheck,
   HealthCheckType,
   HealthCheckResult,
@@ -40,7 +56,7 @@ export type {
   ConfigDisplayOptions,
   Logger,
   DiagnosticsReport,
-  // New mount path and guard types
+  // Route guard types
   RouteGuardType,
   RouteGuardConfig,
   BasicAuthGuardConfig,
@@ -53,7 +69,7 @@ export type {
 export type {
   GatewayConfig,
   GatewayInstance,
-  ServiceFactory,
+  MountedAppConfig,
 } from './core/gateway.js';
 
 // Built-in plugins
@@ -63,18 +79,64 @@ export {
   createConfigPlugin,
   createDiagnosticsPlugin,
   createFrontendAppPlugin,
-  // Database plugins
+  // Postgres plugin
   createPostgresPlugin,
   getPostgres,
   hasPostgres,
-  // Backward compatibility aliases (deprecated)
-  createPostgresPlugin as createDatabasePlugin,
-  getPostgres as getDatabase,
-  hasPostgres as hasDatabase,
-  // Cache plugins
+  // Cache plugin
   createCachePlugin,
   getCache,
   hasCache,
+  // Auth plugin
+  createAuthPlugin,
+  isAuthenticated,
+  getAuthenticatedUser,
+  getAccessToken,
+  requireAuth,
+  requireRoles,
+  requireAnyRole,
+  auth0Adapter,
+  basicAdapter,
+  supabaseAdapter,
+  isAuthenticatedRequest,
+  // Users plugin
+  createUsersPlugin,
+  getUserStore,
+  getUserById,
+  getUserByEmail,
+  findOrCreateUser,
+  postgresUserStore,
+  // Bans plugin (separate from Users, depends on Users)
+  createBansPlugin,
+  getBanStore,
+  isUserBanned,
+  isEmailBanned,
+  getActiveBan,
+  banUser,
+  unbanUser,
+  listActiveBans,
+  postgresBanStore,
+  // Entitlements plugin
+  createEntitlementsPlugin,
+  getEntitlementSource,
+  isSourceReadonly,
+  getEntitlements,
+  refreshEntitlements,
+  hasEntitlement,
+  hasAnyEntitlement,
+  hasAllEntitlements,
+  grantEntitlement,
+  revokeEntitlement,
+  setEntitlements,
+  getAvailableEntitlements,
+  getEntitlementStats,
+  invalidateEntitlementCache,
+  storeExternalIdMapping,
+  invalidateByExternalId,
+  requireEntitlement,
+  requireAnyEntitlement,
+  requireAllEntitlements,
+  postgresEntitlementSource,
 } from './plugins/index.js';
 export type {
   HealthPluginConfig,
@@ -82,14 +144,51 @@ export type {
   ConfigPluginConfig,
   DiagnosticsPluginConfig,
   FrontendAppPluginConfig,
-  // Database plugin types
+  // Postgres plugin types
   PostgresPluginConfig,
   PostgresInstance,
   TransactionCallback,
-  // Backward compatibility aliases (deprecated)
-  PostgresPluginConfig as DatabasePluginConfig,
-  PostgresInstance as DatabaseInstance,
   // Cache plugin types
   CachePluginConfig,
   CacheInstance,
+  // Auth plugin types
+  AuthPluginConfig,
+  AuthAdapter,
+  AuthenticatedUser,
+  AuthenticatedRequest,
+  Auth0AdapterConfig,
+  SupabaseAdapterConfig,
+  BasicAdapterConfig,
+  // Users plugin types
+  UsersPluginConfig,
+  UserStore,
+  User,
+  CreateUserInput,
+  UpdateUserInput,
+  UserSearchParams,
+  UserListResponse,
+  PostgresUserStoreConfig,
+  UserSyncConfig,
+  UsersApiConfig,
+  UsersUiConfig,
+  // Bans plugin types
+  BansPluginConfig,
+  BanStore,
+  Ban,
+  CreateBanInput,
+  RemoveBanInput,
+  BanCallbacks,
+  PostgresBanStoreConfig,
+  // Entitlements plugin types
+  EntitlementsPluginConfig,
+  EntitlementSource,
+  EntitlementResult,
+  EntitlementDefinition,
+  EntitlementCallbacks,
+  EntitlementsCacheConfig,
+  EntitlementsApiConfig,
+  PostgresEntitlementSourceConfig,
+  UserEntitlement,
+  CachedEntitlements,
+  EntitlementStats,
 } from './plugins/index.js';

package/src/plugins/auth/adapters/auth0-adapter.ts

@@ -0,0 +1,214 @@
+/**
+ * Auth0 Adapter
+ *
+ * Provides Auth0 authentication using express-openid-connect.
+ * Enhanced with RBAC support, domain whitelisting, and token exposure.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response, RequestHandler } from 'express';
+import type { AuthAdapter, AuthenticatedUser, Auth0AdapterConfig } from '../types.js';
+
+/**
+ * Extract user roles from Auth0 claims
+ */
+function extractUserRoles(req: Request, domain: string): string[] {
+  const oidc = (req as any).oidc;
+  const user = oidc?.user;
+
+  if (!user) return [];
+
+  // Check various common locations for roles
+  const roles: string[] = [];
+
+  // Standard RBAC claim
+  if (Array.isArray(user['https://roles'])) {
+    roles.push(...user['https://roles']);
+  }
+
+  // Namespaced roles (common pattern)
+  const namespace = domain ? `https://${domain}/` : '';
+  if (namespace && Array.isArray(user[`${namespace}roles`])) {
+    roles.push(...user[`${namespace}roles`]);
+  }
+
+  // Auth0 authorization extension
+  if (Array.isArray(user.roles)) {
+    roles.push(...user.roles);
+  }
+
+  // Custom claims
+  if (Array.isArray(user['custom:roles'])) {
+    roles.push(...user['custom:roles']);
+  }
+
+  return [...new Set(roles)]; // Deduplicate
+}
+
+/**
+ * Create an Auth0 authentication adapter
+ */
+export function auth0Adapter(config: Auth0AdapterConfig): AuthAdapter {
+  let authMiddleware: RequestHandler | null = null;
+  let initializationError: Error | null = null;
+
+  const adapter: AuthAdapter = {
+    name: 'auth0',
+
+    initialize(): RequestHandler {
+      // Return a middleware that lazily initializes Auth0
+      return async (req: Request, res: Response, next) => {
+        // Skip if already initialized with error
+        if (initializationError) {
+          return res.status(500).json({
+            error: 'Auth Configuration Error',
+            message: 'Auth0 is not properly configured.',
+          });
+        }
+
+        // Lazy initialize the Auth0 middleware
+        if (!authMiddleware) {
+          try {
+            const { auth } = await import('express-openid-connect');
+
+            const authConfig: Record<string, unknown> = {
+              authRequired: false, // We handle auth requirement ourselves
+              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',
+              },
+            };
+
+            // Add audience if specified (for API access tokens)
+            if (config.audience) {
+              authConfig.authorizationParams = {
+                audience: config.audience,
+                scope: (config.scopes || ['openid', 'profile', 'email']).join(' '),
+              };
+            }
+
+            // Enable access token fetching if needed
+            if (config.exposeAccessToken && config.audience) {
+              authConfig.afterCallback = (
+                _req: Request,
+                _res: Response,
+                session: Record<string, unknown>
+              ) => {
+                // Access token is automatically stored in session
+                return session;
+              };
+            }
+
+            authMiddleware = auth(authConfig);
+          } catch (error) {
+            initializationError =
+              error instanceof Error ? error : new Error('Failed to initialize Auth0');
+            console.error('[Auth0Adapter] Initialization error:', error);
+            return res.status(500).json({
+              error: 'Auth Configuration Error',
+              message:
+                'Auth0 is not properly configured. Install express-openid-connect package.',
+            });
+          }
+        }
+
+        // Apply the Auth0 middleware
+        authMiddleware!(req, res, next);
+      };
+    },
+
+    isAuthenticated(req: Request): boolean {
+      const oidc = (req as any).oidc;
+      if (!oidc?.isAuthenticated()) {
+        return false;
+      }
+
+      // Check domain whitelist if configured
+      if (config.allowedDomains && config.allowedDomains.length > 0) {
+        const email = oidc.user?.email;
+        if (!email) return false;
+
+        const domain = email.split('@')[1];
+        if (!config.allowedDomains.includes(domain) && !config.allowedDomains.includes(`@${domain}`)) {
+          return false;
+        }
+      }
+
+      // Check role whitelist if configured
+      if (config.allowedRoles && config.allowedRoles.length > 0) {
+        const userRoles = extractUserRoles(req, config.domain);
+        const hasRole = config.allowedRoles.some((role) => userRoles.includes(role));
+        if (!hasRole) {
+          return false;
+        }
+      }
+
+      return true;
+    },
+
+    getUser(req: Request): AuthenticatedUser | null {
+      const oidc = (req as any).oidc;
+
+      if (!adapter.isAuthenticated(req)) {
+        return null;
+      }
+
+      const user = oidc.user;
+      if (!user) return null;
+
+      return {
+        id: user.sub,
+        email: user.email,
+        name: user.name || user.nickname,
+        picture: user.picture,
+        emailVerified: user.email_verified,
+        roles: extractUserRoles(req, config.domain),
+        raw: user,
+      };
+    },
+
+    hasRoles(req: Request, roles: string[]): boolean {
+      const userRoles = extractUserRoles(req, config.domain);
+      return roles.every((role) => userRoles.includes(role));
+    },
+
+    getAccessToken(req: Request): string | null {
+      if (!config.exposeAccessToken) {
+        return null;
+      }
+
+      const oidc = (req as any).oidc;
+      return oidc?.accessToken?.access_token || null;
+    },
+
+    onUnauthorized(req: Request, res: Response): void {
+      // Check if it's an API request
+      const isApiRequest =
+        req.headers.accept?.includes('application/json') || req.path.startsWith('/api/');
+
+      if (isApiRequest) {
+        res.status(401).json({
+          error: 'Unauthorized',
+          message: 'Authentication required',
+          loginUrl: config.routes?.login || '/login',
+        });
+      } else {
+        // Redirect to login for browser requests
+        const loginPath = config.routes?.login || '/login';
+        const returnTo = encodeURIComponent(req.originalUrl);
+        res.redirect(`${loginPath}?returnTo=${returnTo}`);
+      }
+    },
+  };
+
+  return adapter;
+}

package/src/plugins/auth/adapters/basic-adapter.ts

@@ -0,0 +1,61 @@
+/**
+ * Basic Auth Adapter
+ *
+ * Provides HTTP Basic authentication for simple use cases.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response, RequestHandler } from 'express';
+import type { AuthAdapter, AuthenticatedUser, BasicAdapterConfig } from '../types.js';
+
+/**
+ * Create a Basic authentication adapter
+ */
+export function basicAdapter(config: BasicAdapterConfig): AuthAdapter {
+  const expectedAuth = `Basic ${Buffer.from(`${config.username}:${config.password}`).toString('base64')}`;
+  const realm = config.realm || 'Protected';
+
+  // Create a static user for basic auth
+  const staticUser: AuthenticatedUser = {
+    id: 'basic-auth-user',
+    email: `${config.username}@localhost`,
+    name: config.username,
+    roles: ['admin'], // Basic auth users typically have full access
+  };
+
+  return {
+    name: 'basic',
+
+    initialize(): RequestHandler {
+      // Basic auth doesn't need initialization middleware
+      // Just return a pass-through middleware
+      return (_req, _res, next) => next();
+    },
+
+    isAuthenticated(req: Request): boolean {
+      const authHeader = req.headers.authorization;
+      return authHeader === expectedAuth;
+    },
+
+    getUser(req: Request): AuthenticatedUser | null {
+      if (!this.isAuthenticated(req)) {
+        return null;
+      }
+      return staticUser;
+    },
+
+    hasRoles(_req: Request, roles: string[]): boolean {
+      // Basic auth user has 'admin' role
+      return roles.every((role) => staticUser.roles?.includes(role));
+    },
+
+    onUnauthorized(_req: Request, res: Response): void {
+      res.setHeader('WWW-Authenticate', `Basic realm="${realm}"`);
+      res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Authentication required.',
+      });
+    },
+  };
+}

package/src/plugins/auth/adapters/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Auth Adapters Index
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { auth0Adapter } from './auth0-adapter.js';
+export { basicAdapter } from './basic-adapter.js';
+export { supabaseAdapter } from './supabase-adapter.js';