@qwickapps/server 1.2.0 → 1.3.0

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

@@ -0,0 +1,141 @@
+/**
+ * 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';
+
+/**
+ * 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 {
+          id: string;
+          email: string;
+          email_confirmed_at?: string;
+          user_metadata?: {
+            full_name?: string;
+            name?: string;
+            avatar_url?: string;
+          };
+          app_metadata?: {
+            roles?: string[];
+          };
+        };
+
+        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,
+        };
+
+        // 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/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();
+  });
+});

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

@@ -0,0 +1,303 @@
+/**
+ * Auth Plugin
+ *
+ * Pluggable authentication plugin for @qwickapps/server.
+ * Supports multiple adapters (Auth0, Supabase, Basic) with fallback chain.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
+import type { Plugin, PluginConfig, PluginRegistry } from '../../core/plugin-registry.js';
+import type {
+  AuthPluginConfig,
+  AuthAdapter,
+  AuthenticatedUser,
+  AuthenticatedRequest,
+} from './types.js';
+
+// Store the plugin instance for helper access
+let currentAdapter: AuthAdapter | null = null;
+let fallbackAdapters: AuthAdapter[] = [];
+
+/**
+ * Create the Auth plugin
+ */
+export function createAuthPlugin(config: AuthPluginConfig): Plugin {
+  const excludePaths = config.excludePaths || [];
+  const authRequired = config.authRequired !== false;
+  const debug = config.debug || false;
+
+  function log(message: string, data?: Record<string, unknown>) {
+    if (debug) {
+      console.log(`[AuthPlugin] ${message}`, data || '');
+    }
+  }
+
+  return {
+    id: 'auth',
+    name: 'Auth Plugin',
+    version: '1.0.0',
+
+    async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
+      const app = registry.getApp();
+
+      // Store adapters for helper access
+      currentAdapter = config.adapter;
+      fallbackAdapters = config.fallback || [];
+
+      log('Initializing auth plugin', {
+        adapter: config.adapter.name,
+        fallback: fallbackAdapters.map((a) => a.name),
+        excludePaths,
+        authRequired,
+      });
+
+      // Initialize the primary adapter
+      const primaryMiddleware = config.adapter.initialize();
+      if (Array.isArray(primaryMiddleware)) {
+        primaryMiddleware.forEach((mw) => app.use(mw));
+      } else {
+        app.use(primaryMiddleware);
+      }
+
+      // Initialize fallback adapters
+      for (const fallback of fallbackAdapters) {
+        const fallbackMiddleware = fallback.initialize();
+        if (Array.isArray(fallbackMiddleware)) {
+          fallbackMiddleware.forEach((mw) => app.use(mw));
+        } else {
+          app.use(fallbackMiddleware);
+        }
+      }
+
+      // Add the auth checking middleware
+      app.use(createAuthMiddleware());
+
+      // Register auth status route
+      registry.addRoute({
+        method: 'get',
+        path: '/api/auth/status',
+        handler: (_req: Request, res: Response) => {
+          const authReq = _req as AuthenticatedRequest;
+          res.json({
+            authenticated: authReq.auth?.isAuthenticated || false,
+            user: authReq.auth?.user
+              ? {
+                  id: authReq.auth.user.id,
+                  email: authReq.auth.user.email,
+                  name: authReq.auth.user.name,
+                  picture: authReq.auth.user.picture,
+                  roles: authReq.auth.user.roles,
+                }
+              : null,
+            adapter: authReq.auth?.adapter,
+          });
+        },
+        pluginId: 'auth',
+      });
+
+      log('Auth plugin initialized');
+    },
+
+    async onStop(): Promise<void> {
+      log('Shutting down auth plugin');
+
+      // Cleanup adapters
+      if (currentAdapter?.shutdown) {
+        await currentAdapter.shutdown();
+      }
+      for (const fallback of fallbackAdapters) {
+        if (fallback.shutdown) {
+          await fallback.shutdown();
+        }
+      }
+
+      currentAdapter = null;
+      fallbackAdapters = [];
+    },
+  };
+
+  /**
+   * Create the auth checking middleware
+   */
+  function createAuthMiddleware(): RequestHandler {
+    return async (req: Request, res: Response, next: NextFunction) => {
+      const authReq = req as AuthenticatedRequest;
+
+      // Initialize auth object
+      authReq.auth = {
+        isAuthenticated: false,
+        user: null,
+        adapter: 'none',
+      };
+
+      // Check if path is excluded
+      const isExcluded = excludePaths.some((path) => {
+        if (path.endsWith('*')) {
+          return req.path.startsWith(path.slice(0, -1));
+        }
+        return req.path === path || req.path.startsWith(path + '/');
+      });
+
+      if (isExcluded) {
+        log('Path excluded from auth', { path: req.path });
+        return next();
+      }
+
+      // Try primary adapter
+      let authenticated = false;
+      let user: AuthenticatedUser | null = null;
+      let activeAdapter = config.adapter;
+
+      if (config.adapter.isAuthenticated(req)) {
+        user = await Promise.resolve(config.adapter.getUser(req));
+        if (user) {
+          authenticated = true;
+          log('Authenticated via primary adapter', { adapter: config.adapter.name });
+        }
+      }
+
+      // Try fallback adapters if primary didn't authenticate
+      if (!authenticated && fallbackAdapters.length > 0) {
+        for (const fallback of fallbackAdapters) {
+          if (fallback.isAuthenticated(req)) {
+            user = await Promise.resolve(fallback.getUser(req));
+            if (user) {
+              authenticated = true;
+              activeAdapter = fallback;
+              log('Authenticated via fallback adapter', { adapter: fallback.name });
+              break;
+            }
+          }
+        }
+      }
+
+      // Set auth info on request
+      authReq.auth = {
+        isAuthenticated: authenticated,
+        user,
+        adapter: activeAdapter.name,
+        accessToken: activeAdapter.getAccessToken?.(req) || undefined,
+      };
+
+      // Check if auth is required but user is not authenticated
+      if (authRequired && !authenticated) {
+        log('Auth required but not authenticated', { path: req.path });
+
+        // Use custom handler if provided
+        if (config.onUnauthorized) {
+          return config.onUnauthorized(req, res);
+        }
+
+        // Use adapter's unauthorized handler
+        if (activeAdapter.onUnauthorized) {
+          return activeAdapter.onUnauthorized(req, res);
+        }
+
+        // Default unauthorized response
+        return res.status(401).json({
+          error: 'Unauthorized',
+          message: 'Authentication required',
+        });
+      }
+
+      next();
+    };
+  }
+}
+
+/**
+ * Check if the current request is authenticated
+ */
+export function isAuthenticated(req: Request): boolean {
+  const authReq = req as AuthenticatedRequest;
+  return authReq.auth?.isAuthenticated || false;
+}
+
+/**
+ * Get the authenticated user from the request
+ */
+export function getAuthenticatedUser(req: Request): AuthenticatedUser | null {
+  const authReq = req as AuthenticatedRequest;
+  return authReq.auth?.user || null;
+}
+
+/**
+ * Get the access token from the request
+ */
+export function getAccessToken(req: Request): string | null {
+  const authReq = req as AuthenticatedRequest;
+  return authReq.auth?.accessToken || null;
+}
+
+/**
+ * Middleware to require authentication
+ */
+export function requireAuth(): RequestHandler {
+  return (req: Request, res: Response, next: NextFunction) => {
+    if (!isAuthenticated(req)) {
+      return res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Authentication required',
+      });
+    }
+    next();
+  };
+}
+
+/**
+ * Middleware to require specific roles
+ */
+export function requireRoles(...roles: string[]): RequestHandler {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const user = getAuthenticatedUser(req);
+
+    if (!user) {
+      return res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Authentication required',
+      });
+    }
+
+    const userRoles = user.roles || [];
+    const hasAllRoles = roles.every((role) => userRoles.includes(role));
+
+    if (!hasAllRoles) {
+      return res.status(403).json({
+        error: 'Forbidden',
+        message: `Required roles: ${roles.join(', ')}`,
+      });
+    }
+
+    next();
+  };
+}
+
+/**
+ * Middleware to require any of the specified roles
+ */
+export function requireAnyRole(...roles: string[]): RequestHandler {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const user = getAuthenticatedUser(req);
+
+    if (!user) {
+      return res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Authentication required',
+      });
+    }
+
+    const userRoles = user.roles || [];
+    const hasAnyRole = roles.some((role) => userRoles.includes(role));
+
+    if (!hasAnyRole) {
+      return res.status(403).json({
+        error: 'Forbidden',
+        message: `Required one of roles: ${roles.join(', ')}`,
+      });
+    }
+
+    next();
+  };
+}

package/src/plugins/auth/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Auth Plugin Index
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+// Main plugin
+export {
+  createAuthPlugin,
+  isAuthenticated,
+  getAuthenticatedUser,
+  getAccessToken,
+  requireAuth,
+  requireRoles,
+  requireAnyRole,
+} from './auth-plugin.js';
+
+// Types
+export type {
+  AuthPluginConfig,
+  AuthAdapter,
+  AuthenticatedUser,
+  AuthenticatedRequest,
+  Auth0AdapterConfig,
+  SupabaseAdapterConfig,
+  BasicAdapterConfig,
+} from './types.js';
+export { isAuthenticatedRequest } from './types.js';
+
+// Adapters
+export { auth0Adapter } from './adapters/auth0-adapter.js';
+export { basicAdapter } from './adapters/basic-adapter.js';
+export { supabaseAdapter } from './adapters/supabase-adapter.js';