@qwickapps/server 1.3.0 → 1.3.1

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

@@ -0,0 +1 @@
+export declare function AuthPage(): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1 @@
+export declare function PluginsPage(): import("react/jsx-runtime").JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qwickapps/server",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Plugin-based application server framework for building websites, APIs, admin dashboards, and full-stack products",
   "type": "module",
   "main": "dist/index.js",
@@ -76,6 +76,7 @@
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-router-dom": "^6.30.1",
+    "supertokens-node": "^20.1.7",
     "tsx": "^4.20.6",
     "typescript": "^5.3.3",
     "vite": "^6.0.0",
@@ -85,7 +86,8 @@
     "@qwickapps/react-framework": ">=1.0.0",
     "express-openid-connect": ">=2.0.0",
     "ioredis": ">=5.0.0",
-    "pg": ">=8.0.0"
+    "pg": ">=8.0.0",
+    "supertokens-node": ">=20.0.0"
   },
   "peerDependenciesMeta": {
     "@qwickapps/react-framework": {
@@ -99,6 +101,9 @@
     },
     "pg": {
       "optional": true
+    },
+    "supertokens-node": {
+      "optional": true
     }
   },
   "keywords": [

package/src/core/control-panel.ts

@@ -197,11 +197,42 @@ export function createControlPanel(options: CreateControlPanelOptions): ControlP
   });
 
   /**
-   * GET /api/plugins - List all registered plugins
+   * 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 });
+  });
+
+  /**
+   * 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;
+    }
+
+    const contributions = pluginRegistry.getPluginContributions(id);
     res.json({
-      plugins: pluginRegistry.listPlugins(),
+      ...plugin,
+      contributions,
     });
   });
 

package/src/core/plugin-registry.ts

@@ -164,6 +164,31 @@ export interface RouteDefinition {
   pluginId: string;
 }
 
+/**
+ * Configuration UI contribution for plugin settings
+ */
+export interface ConfigContribution {
+  /** Unique ID for this config contribution */
+  id: string;
+  /** React component name to render (matched by frontend registry) */
+  component: string;
+  /** Display title for the config section */
+  title?: string;
+  /** Plugin ID that contributed this */
+  pluginId: string;
+}
+
+/**
+ * Aggregated contributions for a specific plugin
+ */
+export interface PluginContributions {
+  routes: Array<{ method: string; path: string }>;
+  menuItems: MenuContribution[];
+  pages: PageContribution[];
+  widgets: WidgetContribution[];
+  config?: ConfigContribution;
+}
+
 // =============================================================================
 // Plugin Registry Interface
 // =============================================================================
@@ -204,6 +229,9 @@ export interface PluginRegistry {
   /** Register a widget */
   addWidget(widget: WidgetContribution): void;
 
+  /** Register a config component for plugin settings UI */
+  addConfigComponent(config: ConfigContribution): void;
+
   // ---------------------------------------------------------------------------
   // Contribution queries
   // ---------------------------------------------------------------------------
@@ -220,6 +248,12 @@ export interface PluginRegistry {
   /** Get all widgets */
   getWidgets(): WidgetContribution[];
 
+  /** Get all config components */
+  getConfigComponents(): ConfigContribution[];
+
+  /** Get all contributions for a specific plugin */
+  getPluginContributions(pluginId: string): PluginContributions;
+
   // ---------------------------------------------------------------------------
   // Configuration
   // ---------------------------------------------------------------------------
@@ -292,6 +326,7 @@ export class PluginRegistryImpl implements PluginRegistry {
   private menuItems: MenuContribution[] = [];
   private pages: PageContribution[] = [];
   private widgets: WidgetContribution[] = [];
+  private configComponents: ConfigContribution[] = [];
 
   private eventHandlers = new Set<PluginEventHandler>();
 
@@ -385,6 +420,17 @@ export class PluginRegistryImpl implements PluginRegistry {
     this.logger.debug(`Widget registered: ${widget.title} by ${widget.pluginId}`);
   }
 
+  addConfigComponent(config: ConfigContribution): void {
+    // Only one config component per plugin - warn if replacing
+    const existing = this.configComponents.find((c) => c.pluginId === config.pluginId);
+    if (existing) {
+      this.logger.warn(`Replacing config component for plugin ${config.pluginId}: ${existing.component} → ${config.component}`);
+    }
+    this.configComponents = this.configComponents.filter((c) => c.pluginId !== config.pluginId);
+    this.configComponents.push(config);
+    this.logger.debug(`Config component registered: ${config.component} by ${config.pluginId}`);
+  }
+
   // ---------------------------------------------------------------------------
   // Contribution queries
   // ---------------------------------------------------------------------------
@@ -405,6 +451,22 @@ export class PluginRegistryImpl implements PluginRegistry {
     return [...this.widgets];
   }
 
+  getConfigComponents(): ConfigContribution[] {
+    return [...this.configComponents];
+  }
+
+  getPluginContributions(pluginId: string): PluginContributions {
+    return {
+      routes: this.routes
+        .filter((r) => r.pluginId === pluginId)
+        .map((r) => ({ method: r.method, path: r.path })),
+      menuItems: this.menuItems.filter((m) => m.pluginId === pluginId),
+      pages: this.pages.filter((p) => p.pluginId === pluginId),
+      widgets: this.widgets.filter((w) => w.pluginId === pluginId),
+      config: this.configComponents.find((c) => c.pluginId === pluginId),
+    };
+  }
+
   // ---------------------------------------------------------------------------
   // Configuration
   // ---------------------------------------------------------------------------
@@ -577,6 +639,7 @@ export class PluginRegistryImpl implements PluginRegistry {
       this.menuItems = this.menuItems.filter((m) => m.pluginId !== pluginId);
       this.pages = this.pages.filter((p) => p.pluginId !== pluginId);
       this.widgets = this.widgets.filter((w) => w.pluginId !== pluginId);
+      this.configComponents = this.configComponents.filter((c) => c.pluginId !== pluginId);
 
       this.emit({
         type: 'plugin:stopped',

package/src/index.ts

@@ -89,6 +89,8 @@ export {
   hasCache,
   // Auth plugin
   createAuthPlugin,
+  createAuthPluginFromEnv,
+  getAuthStatus,
   isAuthenticated,
   getAuthenticatedUser,
   getAccessToken,
@@ -98,6 +100,7 @@ export {
   auth0Adapter,
   basicAdapter,
   supabaseAdapter,
+  supertokensAdapter,
   isAuthenticatedRequest,
   // Users plugin
   createUsersPlugin,
@@ -159,6 +162,10 @@ export type {
   Auth0AdapterConfig,
   SupabaseAdapterConfig,
   BasicAdapterConfig,
+  SupertokensAdapterConfig,
+  AuthPluginState,
+  AuthEnvPluginOptions,
+  AuthConfigStatus,
   // Users plugin types
   UsersPluginConfig,
   UserStore,

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

@@ -7,3 +7,4 @@
 export { auth0Adapter } from './auth0-adapter.js';
 export { basicAdapter } from './basic-adapter.js';
 export { supabaseAdapter } from './supabase-adapter.js';
+export { supertokensAdapter } from './supertokens-adapter.js';

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

@@ -9,6 +9,26 @@
 import type { Request, Response, RequestHandler } from 'express';
 import type { AuthAdapter, AuthenticatedUser, SupabaseAdapterConfig } from '../types.js';
 
+/**
+ * Supabase user response from /auth/v1/user endpoint
+ * @see https://supabase.com/docs/reference/javascript/auth-getuser
+ */
+interface SupabaseUserResponse {
+  id: string;
+  email: string;
+  email_confirmed_at?: string;
+  user_metadata?: {
+    full_name?: string;
+    name?: string;
+    avatar_url?: string;
+    [key: string]: unknown;
+  };
+  app_metadata?: {
+    roles?: string[];
+    [key: string]: unknown;
+  };
+}
+
 /**
  * Create a Supabase authentication adapter
  */
@@ -68,19 +88,7 @@ export function supabaseAdapter(config: SupabaseAdapterConfig): AuthAdapter {
           return null;
         }
 
-        const supabaseUser = (await response.json()) as {
-          id: string;
-          email: string;
-          email_confirmed_at?: string;
-          user_metadata?: {
-            full_name?: string;
-            name?: string;
-            avatar_url?: string;
-          };
-          app_metadata?: {
-            roles?: string[];
-          };
-        };
+        const supabaseUser = (await response.json()) as SupabaseUserResponse;
 
         const user: AuthenticatedUser = {
           id: supabaseUser.id,
@@ -89,7 +97,7 @@ export function supabaseAdapter(config: SupabaseAdapterConfig): AuthAdapter {
           picture: supabaseUser.user_metadata?.avatar_url,
           emailVerified: !!supabaseUser.email_confirmed_at,
           roles: supabaseUser.app_metadata?.roles || [],
-          raw: supabaseUser,
+          raw: supabaseUser as unknown as Record<string, unknown>,
         };
 
         // Cache the validated user

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

@@ -0,0 +1,326 @@
+/**
+ * Supertokens Auth Adapter
+ *
+ * Provides Supertokens authentication using EmailPassword and ThirdParty recipes.
+ * Supports email/password and social logins (Google, Apple, GitHub).
+ *
+ * Note: Requires supertokens-node v20+
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response, RequestHandler } from 'express';
+import type { AuthAdapter, AuthenticatedUser, SupertokensAdapterConfig } from '../types.js';
+
+// Keys for storing data on the request object
+const REQUEST_USER_KEY = '_supertokensUser';
+const REQUEST_RES_KEY = '_supertokensRes';
+const REQUEST_SESSION_KEY = '_supertokensSession';
+
+// Type for extended request with our custom properties
+interface SupertokensExtendedRequest extends Request {
+  [REQUEST_USER_KEY]?: AuthenticatedUser;
+  [REQUEST_RES_KEY]?: Response;
+  [REQUEST_SESSION_KEY]?: unknown;
+}
+
+/**
+ * Create a Supertokens authentication adapter
+ *
+ * Uses EmailPassword and ThirdParty recipes (Supertokens v20+)
+ */
+export function supertokensAdapter(config: SupertokensAdapterConfig): AuthAdapter {
+  // Track initialization state
+  let initialized = false;
+  let initializationError: Error | null = null;
+
+  return {
+    name: 'supertokens',
+
+    initialize(): RequestHandler[] {
+      // Return middleware that lazily initializes Supertokens
+      const initMiddleware: RequestHandler = async (
+        req: Request,
+        res: Response,
+        next: (err?: unknown) => void
+      ) => {
+        // Store response on request for later use in getUser()
+        (req as SupertokensExtendedRequest)[REQUEST_RES_KEY] = res;
+
+        // Skip if already initialized with error
+        if (initializationError) {
+          return res.status(500).json({
+            error: 'Auth Configuration Error',
+            message:
+              'Supertokens is not properly configured. Install supertokens-node package: npm install supertokens-node',
+            details: initializationError.message,
+          });
+        }
+
+        // Lazy initialize Supertokens
+        if (!initialized) {
+          try {
+            const supertokens = await import('supertokens-node');
+            const Session = await import('supertokens-node/recipe/session');
+            const EmailPassword = await import('supertokens-node/recipe/emailpassword');
+            const ThirdParty = await import('supertokens-node/recipe/thirdparty');
+
+            // Build recipe list - using any[] for Supertokens internal types
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const recipeList: any[] = [];
+
+            // Add EmailPassword recipe if enabled (default: true)
+            if (config.enableEmailPassword !== false) {
+              recipeList.push(EmailPassword.default.init());
+            }
+
+            // Add ThirdParty recipe if any social providers configured
+            if (config.socialProviders) {
+              // Build provider configurations using Supertokens ProviderInput type
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              const providers: any[] = [];
+
+              if (config.socialProviders.google) {
+                providers.push({
+                  config: {
+                    thirdPartyId: 'google',
+                    clients: [
+                      {
+                        clientId: config.socialProviders.google.clientId,
+                        clientSecret: config.socialProviders.google.clientSecret,
+                      },
+                    ],
+                  },
+                });
+              }
+
+              if (config.socialProviders.apple) {
+                // Apple requires keyId, teamId, and privateKey in additionalConfig
+                providers.push({
+                  config: {
+                    thirdPartyId: 'apple',
+                    clients: [
+                      {
+                        clientId: config.socialProviders.apple.clientId,
+                        clientSecret: config.socialProviders.apple.clientSecret,
+                        additionalConfig: {
+                          keyId: config.socialProviders.apple.keyId,
+                          teamId: config.socialProviders.apple.teamId,
+                        },
+                      },
+                    ],
+                  },
+                });
+              }
+
+              if (config.socialProviders.github) {
+                providers.push({
+                  config: {
+                    thirdPartyId: 'github',
+                    clients: [
+                      {
+                        clientId: config.socialProviders.github.clientId,
+                        clientSecret: config.socialProviders.github.clientSecret,
+                      },
+                    ],
+                  },
+                });
+              }
+
+              if (providers.length > 0) {
+                recipeList.push(
+                  ThirdParty.default.init({
+                    signInAndUpFeature: {
+                      providers,
+                    },
+                  })
+                );
+              }
+            }
+
+            // Always add Session recipe
+            recipeList.push(Session.default.init());
+
+            // Initialize Supertokens
+            supertokens.default.init({
+              framework: 'express',
+              supertokens: {
+                connectionURI: config.connectionUri,
+                apiKey: config.apiKey,
+              },
+              appInfo: {
+                appName: config.appName,
+                apiDomain: config.apiDomain,
+                websiteDomain: config.websiteDomain,
+                apiBasePath: config.apiBasePath ?? '/auth',
+                websiteBasePath: config.websiteBasePath ?? '/auth',
+              },
+              recipeList,
+            });
+
+            initialized = true;
+          } catch (error) {
+            initializationError =
+              error instanceof Error ? error : new Error('Failed to initialize Supertokens');
+            console.error('[SupertokensAdapter] Initialization error:', error);
+            return res.status(500).json({
+              error: 'Auth Configuration Error',
+              message:
+                'Supertokens is not properly configured. Install supertokens-node package: npm install supertokens-node',
+              details: initializationError.message,
+            });
+          }
+        }
+
+        next();
+      };
+
+      // Supertokens middleware for handling auth routes
+      const supertokensMiddleware: RequestHandler = async (req, res, next) => {
+        if (!initialized) {
+          return next();
+        }
+
+        try {
+          const { middleware } = await import('supertokens-node/framework/express');
+          middleware()(req, res, next);
+        } catch {
+          next();
+        }
+      };
+
+      return [initMiddleware, supertokensMiddleware];
+    },
+
+    isAuthenticated(req: Request): boolean {
+      const extReq = req as SupertokensExtendedRequest;
+
+      // Check if we already validated this request
+      if (extReq[REQUEST_USER_KEY]) {
+        return true;
+      }
+
+      // Check if session was already retrieved
+      if (extReq[REQUEST_SESSION_KEY]) {
+        return true;
+      }
+
+      // For synchronous check, we can only check if session cookies exist
+      // Full validation happens in getUser()
+      // Supertokens uses cookies, so we check for session tokens
+      const cookies = req.cookies || {};
+      const accessToken = cookies.sAccessToken;
+      const refreshToken = cookies.sRefreshToken;
+
+      // Also check for Authorization header (for API clients)
+      const authHeader = req.headers.authorization;
+      const hasBearerToken = authHeader?.startsWith('Bearer ');
+
+      return !!(accessToken || refreshToken || hasBearerToken);
+    },
+
+    async getUser(req: Request): Promise<AuthenticatedUser | null> {
+      const extReq = req as SupertokensExtendedRequest;
+
+      // Return cached user if available
+      const cachedUser = extReq[REQUEST_USER_KEY];
+      if (cachedUser) {
+        return cachedUser;
+      }
+
+      if (!initialized) {
+        return null;
+      }
+
+      // Get response object stored during middleware
+      const res = extReq[REQUEST_RES_KEY];
+      if (!res) {
+        console.error('[SupertokensAdapter] Response object not found on request');
+        return null;
+      }
+
+      try {
+        const Session = await import('supertokens-node/recipe/session');
+        const supertokens = await import('supertokens-node');
+
+        // Get session - sessionRequired: false means it won't throw if no session
+        const session = await Session.default.getSession(req, res, {
+          sessionRequired: false,
+        });
+
+        if (!session) {
+          return null;
+        }
+
+        // Cache session for isAuthenticated check
+        extReq[REQUEST_SESSION_KEY] = session;
+
+        const userId = session.getUserId();
+
+        // Get user info from Supertokens
+        const userInfo = await supertokens.default.getUser(userId);
+
+        if (!userInfo) {
+          return null;
+        }
+
+        // Get roles from session access token payload if available
+        const accessTokenPayload = session.getAccessTokenPayload();
+        const roles: string[] = accessTokenPayload?.roles || [];
+
+        // Map Supertokens user to AuthenticatedUser
+        const user: AuthenticatedUser = {
+          id: userId,
+          email: userInfo.emails?.[0] ?? '',
+          name:
+            accessTokenPayload?.name ||
+            userInfo.thirdParty?.[0]?.userId ||
+            userInfo.emails?.[0]?.split('@')[0],
+          picture: accessTokenPayload?.picture,
+          emailVerified: userInfo.emails?.[0] ? true : false,
+          roles,
+          raw: {
+            ...userInfo,
+            sessionHandle: session.getHandle(),
+            accessTokenPayload,
+          } as Record<string, unknown>,
+        };
+
+        // Cache on request object
+        extReq[REQUEST_USER_KEY] = user;
+
+        return user;
+      } catch (error) {
+        console.error('[SupertokensAdapter] Error getting user:', error);
+        return null;
+      }
+    },
+
+    hasRoles(req: Request, roles: string[]): boolean {
+      const extReq = req as SupertokensExtendedRequest;
+      const user = extReq[REQUEST_USER_KEY];
+      if (!user?.roles) return false;
+      return roles.every((role) => user.roles?.includes(role));
+    },
+
+    getAccessToken(_req: Request): string | null {
+      // Supertokens uses session cookies, not access tokens
+      // Return null as per the design decision
+      return null;
+    },
+
+    onUnauthorized(_req: Request, res: Response): void {
+      res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Authentication required. Please sign in.',
+        hint: 'Use the /auth endpoints to authenticate',
+      });
+    },
+
+    async shutdown(): Promise<void> {
+      // Supertokens doesn't require explicit cleanup
+      initialized = false;
+      initializationError = null;
+    },
+  };
+}