@qwickapps/server 1.2.0 → 1.3.1

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

@@ -0,0 +1,149 @@
+/**
+ * Supabase Auth Adapter
+ *
+ * Provides Supabase authentication using JWT validation.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+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
+ */
+export function supabaseAdapter(config: SupabaseAdapterConfig): AuthAdapter {
+  // Cache for validated users (short TTL to avoid stale data)
+  const userCache = new Map<string, { user: AuthenticatedUser; expires: number }>();
+  const CACHE_TTL = 60 * 1000; // 1 minute
+
+  return {
+    name: 'supabase',
+
+    initialize(): RequestHandler {
+      // Supabase validation happens per-request, no initialization needed
+      return (_req, _res, next) => next();
+    },
+
+    isAuthenticated(req: Request): boolean {
+      // Check if we already validated this request
+      if ((req as any)._supabaseUser) {
+        return true;
+      }
+
+      const authHeader = req.headers.authorization;
+      return !!authHeader && authHeader.startsWith('Bearer ');
+    },
+
+    async getUser(req: Request): Promise<AuthenticatedUser | null> {
+      // Return cached user if available
+      if ((req as any)._supabaseUser) {
+        return (req as any)._supabaseUser;
+      }
+
+      const authHeader = req.headers.authorization;
+      if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        return null;
+      }
+
+      const token = authHeader.substring(7);
+
+      // Check token cache
+      const cached = userCache.get(token);
+      if (cached && cached.expires > Date.now()) {
+        (req as any)._supabaseUser = cached.user;
+        return cached.user;
+      }
+
+      try {
+        // Validate the JWT with Supabase
+        const response = await fetch(`${config.url}/auth/v1/user`, {
+          headers: {
+            Authorization: `Bearer ${token}`,
+            apikey: config.anonKey,
+          },
+        });
+
+        if (!response.ok) {
+          return null;
+        }
+
+        const supabaseUser = (await response.json()) as SupabaseUserResponse;
+
+        const user: AuthenticatedUser = {
+          id: supabaseUser.id,
+          email: supabaseUser.email,
+          name: supabaseUser.user_metadata?.full_name || supabaseUser.user_metadata?.name,
+          picture: supabaseUser.user_metadata?.avatar_url,
+          emailVerified: !!supabaseUser.email_confirmed_at,
+          roles: supabaseUser.app_metadata?.roles || [],
+          raw: supabaseUser as unknown as Record<string, unknown>,
+        };
+
+        // Cache the validated user
+        userCache.set(token, { user, expires: Date.now() + CACHE_TTL });
+        (req as any)._supabaseUser = user;
+
+        // Cleanup old cache entries periodically
+        if (userCache.size > 1000) {
+          const now = Date.now();
+          for (const [key, value] of userCache) {
+            if (value.expires < now) {
+              userCache.delete(key);
+            }
+          }
+        }
+
+        return user;
+      } catch (error) {
+        console.error('[SupabaseAdapter] Token validation error:', error);
+        return null;
+      }
+    },
+
+    hasRoles(req: Request, roles: string[]): boolean {
+      const user = (req as any)._supabaseUser as AuthenticatedUser | undefined;
+      if (!user?.roles) return false;
+      return roles.every((role) => user.roles?.includes(role));
+    },
+
+    getAccessToken(req: Request): string | null {
+      const authHeader = req.headers.authorization;
+      if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        return null;
+      }
+      return authHeader.substring(7);
+    },
+
+    onUnauthorized(_req: Request, res: Response): void {
+      res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Missing or invalid authorization header. Expected: Bearer <token>',
+      });
+    },
+
+    async shutdown(): Promise<void> {
+      userCache.clear();
+    },
+  };
+}

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;
+    },
+  };
+}

package/src/plugins/auth/auth-plugin.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Auth Plugin Tests
+ *
+ * Unit tests for the authentication plugin and adapters.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { Request, Response, NextFunction } from 'express';
+import { basicAdapter } from './adapters/basic-adapter.js';
+import type { AuthenticatedUser } from './types.js';
+
+// Mock request/response helpers
+function createMockRequest(overrides: Partial<Request> = {}): Request {
+  return {
+    headers: {},
+    path: '/',
+    originalUrl: '/',
+    ...overrides,
+  } as unknown as Request;
+}
+
+function createMockResponse(): Response {
+  const res = {
+    status: vi.fn().mockReturnThis(),
+    json: vi.fn().mockReturnThis(),
+    setHeader: vi.fn().mockReturnThis(),
+    redirect: vi.fn().mockReturnThis(),
+  };
+  return res as unknown as Response;
+}
+
+describe('basicAdapter', () => {
+  const config = {
+    username: 'admin',
+    password: 'secret123',
+    realm: 'Test Realm',
+  };
+
+  let adapter: ReturnType<typeof basicAdapter>;
+
+  beforeEach(() => {
+    adapter = basicAdapter(config);
+  });
+
+  describe('name', () => {
+    it('should return "basic"', () => {
+      expect(adapter.name).toBe('basic');
+    });
+  });
+
+  describe('initialize', () => {
+    it('should return a pass-through middleware', () => {
+      const middleware = adapter.initialize();
+      const req = createMockRequest();
+      const res = createMockResponse();
+      const next = vi.fn();
+
+      // Handle both single middleware and array of middlewares
+      if (Array.isArray(middleware)) {
+        middleware[0](req, res, next);
+      } else {
+        middleware(req, res, next);
+      }
+
+      expect(next).toHaveBeenCalled();
+    });
+  });
+
+  describe('isAuthenticated', () => {
+    it('should return true for valid basic auth credentials', () => {
+      const expectedAuth = `Basic ${Buffer.from('admin:secret123').toString('base64')}`;
+      const req = createMockRequest({
+        headers: { authorization: expectedAuth },
+      });
+
+      expect(adapter.isAuthenticated(req)).toBe(true);
+    });
+
+    it('should return false for invalid credentials', () => {
+      const wrongAuth = `Basic ${Buffer.from('admin:wrongpassword').toString('base64')}`;
+      const req = createMockRequest({
+        headers: { authorization: wrongAuth },
+      });
+
+      expect(adapter.isAuthenticated(req)).toBe(false);
+    });
+
+    it('should return false for missing authorization header', () => {
+      const req = createMockRequest();
+      expect(adapter.isAuthenticated(req)).toBe(false);
+    });
+
+    it('should return false for non-basic auth header', () => {
+      const req = createMockRequest({
+        headers: { authorization: 'Bearer some-token' },
+      });
+      expect(adapter.isAuthenticated(req)).toBe(false);
+    });
+  });
+
+  describe('getUser', () => {
+    it('should return user for authenticated request', async () => {
+      const expectedAuth = `Basic ${Buffer.from('admin:secret123').toString('base64')}`;
+      const req = createMockRequest({
+        headers: { authorization: expectedAuth },
+      });
+
+      const user = await Promise.resolve(adapter.getUser(req));
+      expect(user).not.toBeNull();
+      expect(user?.id).toBe('basic-auth-user');
+      expect(user?.email).toBe('admin@localhost');
+      expect(user?.name).toBe('admin');
+      expect(user?.roles).toContain('admin');
+    });
+
+    it('should return null for unauthenticated request', async () => {
+      const req = createMockRequest();
+      expect(await Promise.resolve(adapter.getUser(req))).toBeNull();
+    });
+  });
+
+  describe('hasRoles', () => {
+    it('should return true if user has the role', () => {
+      const expectedAuth = `Basic ${Buffer.from('admin:secret123').toString('base64')}`;
+      const req = createMockRequest({
+        headers: { authorization: expectedAuth },
+      });
+
+      expect(adapter.hasRoles!(req, ['admin'])).toBe(true);
+    });
+
+    it('should return false if user does not have the role', () => {
+      const expectedAuth = `Basic ${Buffer.from('admin:secret123').toString('base64')}`;
+      const req = createMockRequest({
+        headers: { authorization: expectedAuth },
+      });
+
+      expect(adapter.hasRoles!(req, ['superadmin'])).toBe(false);
+    });
+  });
+
+  describe('onUnauthorized', () => {
+    it('should set WWW-Authenticate header and return 401', () => {
+      const req = createMockRequest();
+      const res = createMockResponse();
+
+      adapter.onUnauthorized!(req, res);
+
+      expect(res.setHeader).toHaveBeenCalledWith('WWW-Authenticate', 'Basic realm="Test Realm"');
+      expect(res.status).toHaveBeenCalledWith(401);
+      expect(res.json).toHaveBeenCalledWith({
+        error: 'Unauthorized',
+        message: 'Authentication required.',
+      });
+    });
+  });
+});
+
+describe('Auth Plugin helpers', () => {
+  // These tests would require more complex setup with express app
+  // For now, we test the basic functionality
+
+  it('should export all required functions', async () => {
+    const authModule = await import('./auth-plugin.js');
+
+    expect(authModule.createAuthPlugin).toBeDefined();
+    expect(authModule.isAuthenticated).toBeDefined();
+    expect(authModule.getAuthenticatedUser).toBeDefined();
+    expect(authModule.getAccessToken).toBeDefined();
+    expect(authModule.requireAuth).toBeDefined();
+    expect(authModule.requireRoles).toBeDefined();
+    expect(authModule.requireAnyRole).toBeDefined();
+  });
+});