@qwickapps/server 1.3.1 → 1.5.0

package/src/plugins/auth/adapter-wrapper.test.ts

@@ -0,0 +1,395 @@
+/**
+ * Auth Adapter Wrapper Tests
+ *
+ * Unit tests for the hot-reload adapter wrapper.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { Request, Response, NextFunction } from 'express';
+import { createAdapterWrapper } from './adapter-wrapper.js';
+import type { AuthAdapter, AuthenticatedUser } from './types.js';
+
+// Helper to create a mock adapter
+function createMockAdapter(name: string, overrides: Partial<AuthAdapter> = {}): AuthAdapter {
+  return {
+    name,
+    initialize: vi.fn().mockReturnValue((_req: Request, _res: Response, next: NextFunction) => next()),
+    isAuthenticated: vi.fn().mockReturnValue(false),
+    getUser: vi.fn().mockReturnValue(null),
+    hasRoles: vi.fn().mockReturnValue(false),
+    getAccessToken: vi.fn().mockReturnValue(null),
+    onUnauthorized: vi.fn(),
+    shutdown: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  };
+}
+
+// Helper to create mock request/response
+function createMockReq(): Request {
+  return {} as Request;
+}
+
+function createMockRes(): Response {
+  return {
+    status: vi.fn().mockReturnThis(),
+    json: vi.fn().mockReturnThis(),
+  } as unknown as Response;
+}
+
+describe('createAdapterWrapper', () => {
+  describe('initialization', () => {
+    it('should create wrapper with no-op adapter by default', () => {
+      const wrapper = createAdapterWrapper();
+
+      expect(wrapper.name).toBe('none');
+      expect(wrapper.hasAdapter()).toBe(false);
+    });
+
+    it('should create wrapper with initial adapter', () => {
+      const mockAdapter = createMockAdapter('test');
+      const wrapper = createAdapterWrapper(mockAdapter);
+
+      expect(wrapper.name).toBe('test');
+      expect(wrapper.hasAdapter()).toBe(true);
+    });
+
+    it('should return adapter info', () => {
+      const mockAdapter = createMockAdapter('test');
+      const wrapper = createAdapterWrapper(mockAdapter);
+
+      const info = wrapper.getAdapterInfo();
+
+      expect(info.name).toBe('test');
+      expect(info.initialized).toBe(false);
+    });
+  });
+
+  describe('initialize', () => {
+    it('should call underlying adapter initialize', () => {
+      const mockAdapter = createMockAdapter('test');
+      const wrapper = createAdapterWrapper(mockAdapter);
+
+      wrapper.initialize();
+
+      expect(mockAdapter.initialize).toHaveBeenCalled();
+    });
+
+    it('should mark wrapper as initialized', () => {
+      const mockAdapter = createMockAdapter('test');
+      const wrapper = createAdapterWrapper(mockAdapter);
+
+      wrapper.initialize();
+
+      expect(wrapper.getAdapterInfo().initialized).toBe(true);
+    });
+
+    it('should return middleware from underlying adapter', () => {
+      const mockMiddleware = vi.fn();
+      const mockAdapter = createMockAdapter('test', {
+        initialize: vi.fn().mockReturnValue(mockMiddleware),
+      });
+      const wrapper = createAdapterWrapper(mockAdapter);
+
+      const result = wrapper.initialize();
+
+      expect(result).toBe(mockMiddleware);
+    });
+  });
+
+  describe('isAuthenticated', () => {
+    it('should delegate to current adapter', () => {
+      const mockAdapter = createMockAdapter('test', {
+        isAuthenticated: vi.fn().mockReturnValue(true),
+      });
+      const wrapper = createAdapterWrapper(mockAdapter);
+      const req = createMockReq();
+
+      const result = wrapper.isAuthenticated(req);
+
+      expect(mockAdapter.isAuthenticated).toHaveBeenCalledWith(req);
+      expect(result).toBe(true);
+    });
+
+    it('should use new adapter after swap', async () => {
+      const oldAdapter = createMockAdapter('old', {
+        isAuthenticated: vi.fn().mockReturnValue(false),
+      });
+      const newAdapter = createMockAdapter('new', {
+        isAuthenticated: vi.fn().mockReturnValue(true),
+      });
+
+      const wrapper = createAdapterWrapper(oldAdapter);
+      await wrapper.setAdapter(newAdapter);
+
+      const req = createMockReq();
+      const result = wrapper.isAuthenticated(req);
+
+      expect(result).toBe(true);
+      expect(newAdapter.isAuthenticated).toHaveBeenCalledWith(req);
+    });
+  });
+
+  describe('getUser', () => {
+    it('should delegate to current adapter', () => {
+      const mockUser: AuthenticatedUser = {
+        id: '123',
+        email: 'test@example.com',
+        name: 'Test User',
+      };
+      const mockAdapter = createMockAdapter('test', {
+        getUser: vi.fn().mockReturnValue(mockUser),
+      });
+      const wrapper = createAdapterWrapper(mockAdapter);
+      const req = createMockReq();
+
+      const result = wrapper.getUser(req);
+
+      expect(mockAdapter.getUser).toHaveBeenCalledWith(req);
+      expect(result).toEqual(mockUser);
+    });
+
+    it('should return null for no-op adapter', () => {
+      const wrapper = createAdapterWrapper();
+      const req = createMockReq();
+
+      const result = wrapper.getUser(req);
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('hasRoles', () => {
+    it('should delegate to current adapter if method exists', () => {
+      const mockAdapter = createMockAdapter('test', {
+        hasRoles: vi.fn().mockReturnValue(true),
+      });
+      const wrapper = createAdapterWrapper(mockAdapter);
+      const req = createMockReq();
+
+      // Wrapper always implements hasRoles
+      const result = wrapper.hasRoles!(req, ['admin']);
+
+      expect(mockAdapter.hasRoles).toHaveBeenCalledWith(req, ['admin']);
+      expect(result).toBe(true);
+    });
+
+    it('should return false if adapter has no hasRoles method', () => {
+      const mockAdapter = createMockAdapter('test');
+      delete (mockAdapter as Partial<AuthAdapter>).hasRoles;
+      const wrapper = createAdapterWrapper(mockAdapter);
+      const req = createMockReq();
+
+      // Wrapper always implements hasRoles, even if underlying adapter doesn't
+      const result = wrapper.hasRoles!(req, ['admin']);
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('getAccessToken', () => {
+    it('should delegate to current adapter if method exists', () => {
+      const mockAdapter = createMockAdapter('test', {
+        getAccessToken: vi.fn().mockReturnValue('token123'),
+      });
+      const wrapper = createAdapterWrapper(mockAdapter);
+      const req = createMockReq();
+
+      // Wrapper always implements getAccessToken
+      const result = wrapper.getAccessToken!(req);
+
+      expect(mockAdapter.getAccessToken).toHaveBeenCalledWith(req);
+      expect(result).toBe('token123');
+    });
+
+    it('should return null if adapter has no getAccessToken method', () => {
+      const mockAdapter = createMockAdapter('test');
+      delete (mockAdapter as Partial<AuthAdapter>).getAccessToken;
+      const wrapper = createAdapterWrapper(mockAdapter);
+      const req = createMockReq();
+
+      // Wrapper always implements getAccessToken, returns null when adapter doesn't have it
+      const result = wrapper.getAccessToken!(req);
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('onUnauthorized', () => {
+    it('should delegate to current adapter if method exists', () => {
+      const mockAdapter = createMockAdapter('test');
+      const wrapper = createAdapterWrapper(mockAdapter);
+      const req = createMockReq();
+      const res = createMockRes();
+
+      // Wrapper always implements onUnauthorized
+      wrapper.onUnauthorized!(req, res);
+
+      expect(mockAdapter.onUnauthorized).toHaveBeenCalledWith(req, res);
+    });
+
+    it('should return 401 JSON response if adapter has no onUnauthorized', () => {
+      const mockAdapter = createMockAdapter('test');
+      delete (mockAdapter as Partial<AuthAdapter>).onUnauthorized;
+      const wrapper = createAdapterWrapper(mockAdapter);
+      const req = createMockReq();
+      const res = createMockRes();
+
+      // Wrapper always implements onUnauthorized with default behavior
+      wrapper.onUnauthorized!(req, res);
+
+      expect(res.status).toHaveBeenCalledWith(401);
+      expect(res.json).toHaveBeenCalledWith({
+        error: 'Unauthorized',
+        message: 'Authentication required',
+      });
+    });
+  });
+
+  describe('setAdapter (hot-reload)', () => {
+    it('should swap adapter successfully', async () => {
+      const oldAdapter = createMockAdapter('old');
+      const newAdapter = createMockAdapter('new');
+      const wrapper = createAdapterWrapper(oldAdapter);
+
+      await wrapper.setAdapter(newAdapter);
+
+      expect(wrapper.name).toBe('new');
+    });
+
+    it('should shutdown old adapter before swap', async () => {
+      const oldAdapter = createMockAdapter('old');
+      const newAdapter = createMockAdapter('new');
+      const wrapper = createAdapterWrapper(oldAdapter);
+
+      await wrapper.setAdapter(newAdapter);
+
+      expect(oldAdapter.shutdown).toHaveBeenCalled();
+    });
+
+    it('should initialize new adapter if wrapper was initialized', async () => {
+      const oldAdapter = createMockAdapter('old');
+      const newAdapter = createMockAdapter('new');
+      const wrapper = createAdapterWrapper(oldAdapter);
+
+      // Initialize wrapper
+      wrapper.initialize();
+
+      // Swap adapter
+      await wrapper.setAdapter(newAdapter);
+
+      expect(newAdapter.initialize).toHaveBeenCalled();
+    });
+
+    it('should not initialize new adapter if wrapper was not initialized', async () => {
+      const oldAdapter = createMockAdapter('old');
+      const newAdapter = createMockAdapter('new');
+      const wrapper = createAdapterWrapper(oldAdapter);
+
+      // Don't initialize wrapper
+
+      // Swap adapter
+      await wrapper.setAdapter(newAdapter);
+
+      expect(newAdapter.initialize).not.toHaveBeenCalled();
+    });
+
+    it('should prevent concurrent adapter swaps', async () => {
+      const oldAdapter = createMockAdapter('old', {
+        shutdown: vi.fn().mockImplementation(() => new Promise((resolve) => setTimeout(resolve, 100))),
+      });
+      const newAdapter1 = createMockAdapter('new1');
+      const newAdapter2 = createMockAdapter('new2');
+      const wrapper = createAdapterWrapper(oldAdapter);
+
+      // Start first swap
+      const swap1 = wrapper.setAdapter(newAdapter1);
+
+      // Try second swap immediately (should fail)
+      await expect(wrapper.setAdapter(newAdapter2)).rejects.toThrow('Adapter swap already in progress');
+
+      // Wait for first swap to complete
+      await swap1;
+
+      // Now second swap should work
+      await wrapper.setAdapter(newAdapter2);
+      expect(wrapper.name).toBe('new2');
+    });
+
+    it('should handle shutdown errors gracefully', async () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      const oldAdapter = createMockAdapter('old', {
+        shutdown: vi.fn().mockRejectedValue(new Error('Shutdown failed')),
+      });
+      const newAdapter = createMockAdapter('new');
+      const wrapper = createAdapterWrapper(oldAdapter);
+
+      // Should not throw
+      await wrapper.setAdapter(newAdapter);
+
+      expect(wrapper.name).toBe('new');
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        '[AdapterWrapper] Error shutting down old adapter:',
+        expect.any(Error)
+      );
+
+      consoleErrorSpy.mockRestore();
+    });
+  });
+
+  describe('shutdown', () => {
+    it('should shutdown current adapter', async () => {
+      const mockAdapter = createMockAdapter('test');
+      const wrapper = createAdapterWrapper(mockAdapter);
+      wrapper.initialize();
+
+      // Wrapper always implements shutdown
+      await wrapper.shutdown!();
+
+      expect(mockAdapter.shutdown).toHaveBeenCalled();
+      expect(wrapper.getAdapterInfo().initialized).toBe(false);
+    });
+
+    it('should handle adapters without shutdown method', async () => {
+      const mockAdapter = createMockAdapter('test');
+      delete (mockAdapter as Partial<AuthAdapter>).shutdown;
+      const wrapper = createAdapterWrapper(mockAdapter);
+      wrapper.initialize();
+
+      // Should not throw - wrapper handles missing shutdown gracefully
+      await wrapper.shutdown!();
+
+      expect(wrapper.getAdapterInfo().initialized).toBe(false);
+    });
+  });
+
+  describe('no-op adapter', () => {
+    it('should return false for isAuthenticated', () => {
+      const wrapper = createAdapterWrapper();
+      const req = createMockReq();
+
+      expect(wrapper.isAuthenticated(req)).toBe(false);
+    });
+
+    it('should return null for getUser', () => {
+      const wrapper = createAdapterWrapper();
+      const req = createMockReq();
+
+      expect(wrapper.getUser(req)).toBeNull();
+    });
+
+    it('should return middleware that calls next', () => {
+      const wrapper = createAdapterWrapper();
+      const middleware = wrapper.initialize();
+
+      const req = createMockReq();
+      const res = createMockRes();
+      const next = vi.fn();
+
+      if (typeof middleware === 'function') {
+        middleware(req, res, next);
+        expect(next).toHaveBeenCalled();
+      }
+    });
+  });
+});

package/src/plugins/auth/adapter-wrapper.ts

@@ -0,0 +1,205 @@
+/**
+ * Auth Adapter Wrapper
+ *
+ * Wraps an auth adapter to enable hot-reload without server restart.
+ * All method calls are delegated to the underlying adapter, which can
+ * be swapped at runtime via setAdapter().
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response, RequestHandler } from 'express';
+import type { AuthAdapter, AuthenticatedUser } from './types.js';
+
+/**
+ * Extended adapter interface with hot-reload capabilities
+ */
+export interface AdapterWrapper extends AuthAdapter {
+  /**
+   * Replace the underlying adapter (for hot-reload)
+   * Calls shutdown() on the old adapter before swapping
+   */
+  setAdapter(adapter: AuthAdapter): Promise<void>;
+
+  /**
+   * Get information about the current adapter
+   */
+  getAdapterInfo(): { name: string; initialized: boolean };
+
+  /**
+   * Check if an adapter is currently set
+   */
+  hasAdapter(): boolean;
+}
+
+/**
+ * Create a no-op adapter for when auth is disabled
+ */
+function createNoopAdapter(): AuthAdapter {
+  return {
+    name: 'none',
+    initialize: () => ((_req, _res, next) => next()) as RequestHandler,
+    isAuthenticated: () => false,
+    getUser: () => null,
+  };
+}
+
+/**
+ * Create an adapter wrapper for hot-reload support
+ *
+ * @param initialAdapter Optional initial adapter (defaults to no-op)
+ * @returns AdapterWrapper that delegates to the underlying adapter
+ *
+ * @example
+ * ```ts
+ * const wrapper = createAdapterWrapper(supertokensAdapter(config));
+ *
+ * // Later, swap the adapter without restart:
+ * await wrapper.setAdapter(auth0Adapter(newConfig));
+ * ```
+ */
+export function createAdapterWrapper(initialAdapter?: AuthAdapter): AdapterWrapper {
+  let currentAdapter: AuthAdapter = initialAdapter || createNoopAdapter();
+  let isInitialized = false;
+  let isSwapping = false; // Prevent concurrent adapter swaps
+
+  return {
+    // Delegate name to current adapter
+    get name(): string {
+      return currentAdapter.name;
+    },
+
+    /**
+     * Initialize returns the middleware
+     * Note: This is called once at startup. The middleware itself
+     * will delegate to currentAdapter, which can be swapped.
+     */
+    initialize(): RequestHandler | RequestHandler[] {
+      isInitialized = true;
+
+      // Get the initial middleware
+      const initialMiddleware = currentAdapter.initialize();
+
+      // Return a wrapper middleware that delegates to current adapter's middleware
+      // This allows hot-reload to work - new adapter's middleware will be used
+      // Note: For simplicity, we return the initial middleware. Full hot-reload
+      // of middleware would require more complex Express route manipulation.
+      // The key hot-reload capability is in isAuthenticated/getUser which ARE
+      // delegated dynamically.
+      return initialMiddleware;
+    },
+
+    /**
+     * Delegate isAuthenticated to current adapter
+     */
+    isAuthenticated(req: Request): boolean {
+      return currentAdapter.isAuthenticated(req);
+    },
+
+    /**
+     * Delegate getUser to current adapter
+     */
+    getUser(req: Request): AuthenticatedUser | null | Promise<AuthenticatedUser | null> {
+      return currentAdapter.getUser(req);
+    },
+
+    /**
+     * Delegate hasRoles to current adapter (if available)
+     */
+    hasRoles(req: Request, roles: string[]): boolean {
+      if (currentAdapter.hasRoles) {
+        return currentAdapter.hasRoles(req, roles);
+      }
+      return false;
+    },
+
+    /**
+     * Delegate getAccessToken to current adapter (if available)
+     */
+    getAccessToken(req: Request): string | null {
+      if (currentAdapter.getAccessToken) {
+        return currentAdapter.getAccessToken(req);
+      }
+      return null;
+    },
+
+    /**
+     * Delegate onUnauthorized to current adapter (if available)
+     */
+    onUnauthorized(req: Request, res: Response): void {
+      if (currentAdapter.onUnauthorized) {
+        currentAdapter.onUnauthorized(req, res);
+      } else {
+        res.status(401).json({
+          error: 'Unauthorized',
+          message: 'Authentication required',
+        });
+      }
+    },
+
+    /**
+     * Shutdown the current adapter
+     */
+    async shutdown(): Promise<void> {
+      if (currentAdapter.shutdown) {
+        await currentAdapter.shutdown();
+      }
+      isInitialized = false;
+    },
+
+    /**
+     * Hot-reload: Replace the underlying adapter
+     * @throws Error if another adapter swap is already in progress
+     */
+    async setAdapter(adapter: AuthAdapter): Promise<void> {
+      // Prevent concurrent adapter swaps
+      if (isSwapping) {
+        throw new Error('Adapter swap already in progress');
+      }
+      isSwapping = true;
+
+      try {
+        const oldAdapter = currentAdapter;
+
+        // Shutdown old adapter
+        if (oldAdapter.shutdown) {
+          try {
+            await oldAdapter.shutdown();
+          } catch (err) {
+            console.error('[AdapterWrapper] Error shutting down old adapter:', err);
+          }
+        }
+
+        // Set new adapter
+        currentAdapter = adapter;
+
+        // Initialize new adapter if we're already running
+        if (isInitialized) {
+          // Note: We initialize the new adapter but can't easily swap Express middleware
+          // The new adapter's isAuthenticated/getUser will be used immediately
+          // Full middleware hot-reload would require server restart
+          currentAdapter.initialize();
+        }
+      } finally {
+        isSwapping = false;
+      }
+    },
+
+    /**
+     * Get info about the current adapter
+     */
+    getAdapterInfo(): { name: string; initialized: boolean } {
+      return {
+        name: currentAdapter.name,
+        initialized: isInitialized,
+      };
+    },
+
+    /**
+     * Check if a real adapter is set (not the no-op)
+     */
+    hasAdapter(): boolean {
+      return currentAdapter.name !== 'none';
+    },
+  };
+}