@dismissible/nestjs-jwt-auth-hook 0.0.1

package/src/jwt-auth.hook.spec.ts

@@ -0,0 +1,283 @@
+import { UnauthorizedException, ForbiddenException } from '@nestjs/common';
+import { mock } from 'ts-jest-mocker';
+import { JwtAuthHook } from './jwt-auth.hook';
+import { JwtAuthService, IJwtValidationResult } from './jwt-auth.service';
+import { JwtAuthHookConfig } from './jwt-auth-hook.config';
+import { IDismissibleLogger } from '@dismissible/nestjs-logger';
+import { IRequestContext } from '@dismissible/nestjs-dismissible';
+
+describe('JwtAuthHook', () => {
+  let hook: JwtAuthHook;
+  let mockJwtAuthService: jest.Mocked<JwtAuthService>;
+  let mockLogger: jest.Mocked<IDismissibleLogger>;
+  let mockConfig: JwtAuthHookConfig;
+
+  const testItemId = 'test-item-id';
+  const testUserId = 'test-user-id';
+
+  beforeEach(() => {
+    mockJwtAuthService = mock(JwtAuthService, { failIfMockNotProvided: false });
+    mockLogger = mock<IDismissibleLogger>({ failIfMockNotProvided: false });
+    mockConfig = {
+      enabled: true,
+      wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+      issuer: 'https://auth.example.com',
+    };
+
+    hook = new JwtAuthHook(mockJwtAuthService, mockConfig, mockLogger);
+  });
+
+  describe('priority', () => {
+    it('should default to -100 priority', () => {
+      expect(hook.priority).toBe(-100);
+    });
+
+    it('should use custom priority when provided', () => {
+      const customConfig = { ...mockConfig, priority: -50 };
+      const customHook = new JwtAuthHook(mockJwtAuthService, customConfig, mockLogger);
+      expect(customHook.priority).toBe(-50);
+    });
+  });
+
+  describe('onBeforeRequest', () => {
+    it('should skip validation and proceed when disabled', async () => {
+      const disabledConfig = { ...mockConfig, enabled: false };
+      const disabledHook = new JwtAuthHook(mockJwtAuthService, disabledConfig, mockLogger);
+
+      const context: IRequestContext = { requestId: 'req-123' };
+      const result = await disabledHook.onBeforeRequest(testItemId, testUserId, context);
+
+      expect(result.proceed).toBe(true);
+      expect(mockJwtAuthService.extractBearerToken).not.toHaveBeenCalled();
+      expect(mockJwtAuthService.validateToken).not.toHaveBeenCalled();
+    });
+
+    it('should throw UnauthorizedException when no authorization header is present', async () => {
+      mockJwtAuthService.extractBearerToken.mockReturnValue(null);
+
+      const context: IRequestContext = { requestId: 'req-123' };
+
+      await expect(hook.onBeforeRequest(testItemId, testUserId, context)).rejects.toThrow(
+        UnauthorizedException,
+      );
+      await expect(hook.onBeforeRequest(testItemId, testUserId, context)).rejects.toThrow(
+        'Missing or invalid bearer token',
+      );
+      expect(mockJwtAuthService.extractBearerToken).toHaveBeenCalledWith(undefined);
+    });
+
+    it('should throw UnauthorizedException when authorization header is malformed', async () => {
+      mockJwtAuthService.extractBearerToken.mockReturnValue(null);
+
+      const context: IRequestContext = {
+        requestId: 'req-123',
+        authorizationHeader: 'Basic abc123',
+      };
+
+      await expect(hook.onBeforeRequest(testItemId, testUserId, context)).rejects.toThrow(
+        UnauthorizedException,
+      );
+      await expect(hook.onBeforeRequest(testItemId, testUserId, context)).rejects.toThrow(
+        'Missing or invalid bearer token',
+      );
+    });
+
+    it('should throw UnauthorizedException when token validation fails', async () => {
+      const validationResult: IJwtValidationResult = {
+        valid: false,
+        error: 'Token expired',
+      };
+      mockJwtAuthService.extractBearerToken.mockReturnValue('valid-token');
+      mockJwtAuthService.validateToken.mockResolvedValue(validationResult);
+
+      const context: IRequestContext = {
+        requestId: 'req-123',
+        authorizationHeader: 'Bearer valid-token',
+      };
+
+      await expect(hook.onBeforeRequest(testItemId, testUserId, context)).rejects.toThrow(
+        UnauthorizedException,
+      );
+      await expect(hook.onBeforeRequest(testItemId, testUserId, context)).rejects.toThrow(
+        'Token expired',
+      );
+      expect(mockJwtAuthService.validateToken).toHaveBeenCalledWith('valid-token');
+    });
+
+    it('should proceed when token is valid', async () => {
+      const matchingUserId = 'user-123';
+      const validationResult: IJwtValidationResult = {
+        valid: true,
+        payload: {
+          sub: matchingUserId,
+          iss: 'https://auth.example.com',
+        },
+      };
+      mockJwtAuthService.extractBearerToken.mockReturnValue('valid-token');
+      mockJwtAuthService.validateToken.mockResolvedValue(validationResult);
+
+      const context: IRequestContext = {
+        requestId: 'req-123',
+        authorizationHeader: 'Bearer valid-token',
+      };
+      const result = await hook.onBeforeRequest(testItemId, matchingUserId, context);
+
+      expect(result.proceed).toBe(true);
+      expect(result.reason).toBeUndefined();
+    });
+
+    it('should throw UnauthorizedException when context is missing', async () => {
+      mockJwtAuthService.extractBearerToken.mockReturnValue(null);
+
+      await expect(hook.onBeforeRequest(testItemId, testUserId, undefined)).rejects.toThrow(
+        UnauthorizedException,
+      );
+      expect(mockJwtAuthService.extractBearerToken).toHaveBeenCalledWith(undefined);
+    });
+
+    it('should log debug message on successful validation', async () => {
+      const matchingUserId = 'user-123';
+      const validationResult: IJwtValidationResult = {
+        valid: true,
+        payload: { sub: matchingUserId },
+      };
+      mockJwtAuthService.extractBearerToken.mockReturnValue('valid-token');
+      mockJwtAuthService.validateToken.mockResolvedValue(validationResult);
+
+      const context: IRequestContext = {
+        requestId: 'req-123',
+        authorizationHeader: 'Bearer valid-token',
+      };
+      await hook.onBeforeRequest(testItemId, matchingUserId, context);
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        'JWT auth hook: Token validated successfully',
+        expect.objectContaining({
+          itemId: testItemId,
+          userId: matchingUserId,
+          requestId: 'req-123',
+          subject: matchingUserId,
+        }),
+      );
+    });
+
+    it('should throw ForbiddenException when userId does not match JWT sub claim', async () => {
+      const validationResult: IJwtValidationResult = {
+        valid: true,
+        payload: {
+          sub: 'different-user-id',
+          iss: 'https://auth.example.com',
+        },
+      };
+      mockJwtAuthService.extractBearerToken.mockReturnValue('valid-token');
+      mockJwtAuthService.validateToken.mockResolvedValue(validationResult);
+
+      const context: IRequestContext = {
+        requestId: 'req-123',
+        authorizationHeader: 'Bearer valid-token',
+      };
+
+      await expect(hook.onBeforeRequest(testItemId, testUserId, context)).rejects.toThrow(
+        ForbiddenException,
+      );
+      await expect(hook.onBeforeRequest(testItemId, testUserId, context)).rejects.toThrow(
+        'User ID in request does not match authenticated user',
+      );
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        'JWT auth hook: User ID mismatch',
+        expect.objectContaining({
+          itemId: testItemId,
+          userId: testUserId,
+          requestId: 'req-123',
+          tokenSubject: 'different-user-id',
+        }),
+      );
+    });
+
+    it('should proceed when userId matches JWT sub claim', async () => {
+      const validationResult: IJwtValidationResult = {
+        valid: true,
+        payload: {
+          sub: testUserId,
+          iss: 'https://auth.example.com',
+        },
+      };
+      mockJwtAuthService.extractBearerToken.mockReturnValue('valid-token');
+      mockJwtAuthService.validateToken.mockResolvedValue(validationResult);
+
+      const context: IRequestContext = {
+        requestId: 'req-123',
+        authorizationHeader: 'Bearer valid-token',
+      };
+      const result = await hook.onBeforeRequest(testItemId, testUserId, context);
+
+      expect(result.proceed).toBe(true);
+      expect(result.reason).toBeUndefined();
+    });
+
+    it('should proceed when verifyUserIdMatch is disabled even if userId does not match', async () => {
+      const disabledVerifyConfig = { ...mockConfig, verifyUserIdMatch: false };
+      const disabledVerifyHook = new JwtAuthHook(
+        mockJwtAuthService,
+        disabledVerifyConfig,
+        mockLogger,
+      );
+
+      const validationResult: IJwtValidationResult = {
+        valid: true,
+        payload: {
+          sub: 'different-user-id',
+          iss: 'https://auth.example.com',
+        },
+      };
+      mockJwtAuthService.extractBearerToken.mockReturnValue('valid-token');
+      mockJwtAuthService.validateToken.mockResolvedValue(validationResult);
+
+      const context: IRequestContext = {
+        requestId: 'req-123',
+        authorizationHeader: 'Bearer valid-token',
+      };
+      const result = await disabledVerifyHook.onBeforeRequest(testItemId, testUserId, context);
+
+      expect(result.proceed).toBe(true);
+    });
+
+    it('should proceed when JWT payload does not have sub claim and verifyUserIdMatch is enabled', async () => {
+      const validationResult: IJwtValidationResult = {
+        valid: true,
+        payload: {
+          iss: 'https://auth.example.com',
+          // No sub claim
+        },
+      };
+      mockJwtAuthService.extractBearerToken.mockReturnValue('valid-token');
+      mockJwtAuthService.validateToken.mockResolvedValue(validationResult);
+
+      const context: IRequestContext = {
+        requestId: 'req-123',
+        authorizationHeader: 'Bearer valid-token',
+      };
+      const result = await hook.onBeforeRequest(testItemId, testUserId, context);
+
+      expect(result.proceed).toBe(true);
+    });
+
+    it('should proceed when JWT payload is undefined and verifyUserIdMatch is enabled', async () => {
+      const validationResult: IJwtValidationResult = {
+        valid: true,
+        // No payload
+      };
+      mockJwtAuthService.extractBearerToken.mockReturnValue('valid-token');
+      mockJwtAuthService.validateToken.mockResolvedValue(validationResult);
+
+      const context: IRequestContext = {
+        requestId: 'req-123',
+        authorizationHeader: 'Bearer valid-token',
+      };
+      const result = await hook.onBeforeRequest(testItemId, testUserId, context);
+
+      expect(result.proceed).toBe(true);
+    });
+  });
+});

package/src/jwt-auth.hook.ts

@@ -0,0 +1,99 @@
+import { Injectable, Inject, UnauthorizedException, ForbiddenException } from '@nestjs/common';
+import {
+  IDismissibleLifecycleHook,
+  IHookResult,
+  IRequestContext,
+} from '@dismissible/nestjs-dismissible';
+import { DISMISSIBLE_LOGGER, IDismissibleLogger } from '@dismissible/nestjs-logger';
+import { JwtAuthService } from './jwt-auth.service';
+import { JWT_AUTH_HOOK_CONFIG, JwtAuthHookConfig } from './jwt-auth-hook.config';
+
+/**
+ * JWT authentication hook that validates bearer tokens on every request.
+ * This hook runs during the pre-request phase and rejects unauthorized requests.
+ */
+@Injectable()
+export class JwtAuthHook implements IDismissibleLifecycleHook {
+  readonly priority: number;
+
+  constructor(
+    private readonly jwtAuthService: JwtAuthService,
+    @Inject(JWT_AUTH_HOOK_CONFIG)
+    private readonly config: JwtAuthHookConfig,
+    @Inject(DISMISSIBLE_LOGGER)
+    private readonly logger: IDismissibleLogger,
+  ) {
+    // Default to -100 for authentication (runs early)
+    this.priority = config.priority ?? -100;
+  }
+
+  /**
+   * Validates the JWT bearer token from the Authorization header.
+   * Runs before any dismissible operation.
+   */
+  async onBeforeRequest(
+    itemId: string,
+    userId: string,
+    context?: IRequestContext,
+  ): Promise<IHookResult> {
+    if (!this.config.enabled) {
+      return { proceed: true };
+    }
+
+    const authorizationHeader = context?.authorizationHeader;
+
+    // Extract the bearer token
+    const token = this.jwtAuthService.extractBearerToken(authorizationHeader);
+
+    if (!token) {
+      this.logger.debug('JWT auth hook: No bearer token provided', {
+        itemId,
+        userId,
+        requestId: context?.requestId,
+      });
+
+      throw new UnauthorizedException('Missing or invalid bearer token');
+    }
+
+    // Validate the token
+    const result = await this.jwtAuthService.validateToken(token);
+
+    if (!result.valid) {
+      this.logger.debug('JWT auth hook: Token validation failed', {
+        itemId,
+        userId,
+        requestId: context?.requestId,
+        error: result.error,
+      });
+
+      throw new UnauthorizedException(result.error);
+    }
+
+    // Verify that the userId parameter matches the JWT subject (sub) claim
+    // This prevents users from accessing other users' data by changing the userId in the URL
+    const verifyUserIdMatch = this.config.verifyUserIdMatch ?? true;
+    if (verifyUserIdMatch && result.payload?.sub) {
+      if (result.payload.sub !== userId) {
+        this.logger.debug('JWT auth hook: User ID mismatch', {
+          itemId,
+          userId,
+          requestId: context?.requestId,
+          tokenSubject: result.payload.sub,
+        });
+
+        throw new ForbiddenException('User ID in request does not match authenticated user');
+      }
+    }
+
+    this.logger.debug('JWT auth hook: Token validated successfully', {
+      itemId,
+      userId,
+      requestId: context?.requestId,
+      subject: result.payload?.sub,
+    });
+
+    return {
+      proceed: true,
+    };
+  }
+}