@dismissible/nestjs-jwt-auth-hook 0.0.1

package/README.md

@@ -0,0 +1,171 @@
+# @dismissible/nestjs-jwt-auth-hook
+
+JWT authentication hook for Dismissible applications using OpenID Connect (OIDC) well-known discovery.
+
+## Overview
+
+This library provides a lifecycle hook that integrates with the `@dismissible/nestjs-dismissible` module to authenticate requests using JWT bearer tokens. It validates tokens using JWKS (JSON Web Key Set) fetched from an OIDC well-known endpoint.
+
+## Installation
+
+```bash
+npm install @dismissible/nestjs-jwt-auth-hook @nestjs/axios axios
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { DismissibleModule } from '@dismissible/nestjs-dismissible';
+import { JwtAuthHookModule, JwtAuthHook } from '@dismissible/nestjs-jwt-auth-hook';
+
+@Module({
+  imports: [
+    // Configure the JWT auth hook module
+    JwtAuthHookModule.forRoot({
+      wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+      issuer: 'https://auth.example.com',
+      audience: 'my-api',
+    }),
+
+    // Pass the hook to the DismissibleModule
+    DismissibleModule.forRoot({
+      hooks: [JwtAuthHook],
+      // ... other options
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Async Configuration
+
+When configuration values come from environment variables or other async sources:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { DismissibleModule } from '@dismissible/nestjs-dismissible';
+import { JwtAuthHookModule, JwtAuthHook } from '@dismissible/nestjs-jwt-auth-hook';
+
+@Module({
+  imports: [
+    JwtAuthHookModule.forRootAsync({
+      useFactory: (configService: ConfigService) => ({
+        wellKnownUrl: configService.getOrThrow('OIDC_WELL_KNOWN_URL'),
+        issuer: configService.get('OIDC_ISSUER'),
+        audience: configService.get('OIDC_AUDIENCE'),
+      }),
+      inject: [ConfigService],
+    }),
+
+    DismissibleModule.forRoot({
+      hooks: [JwtAuthHook],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Configuration Options
+
+| Option              | Type       | Required | Default     | Description                                                                                 |
+| ------------------- | ---------- | -------- | ----------- | ------------------------------------------------------------------------------------------- |
+| `enabled`           | `boolean`  | Yes      | `true`      | Whether JWT authentication is enabled                                                       |
+| `wellKnownUrl`      | `string`   | Yes\*    | -           | The OIDC well-known URL (e.g., `https://auth.example.com/.well-known/openid-configuration`) |
+| `issuer`            | `string`   | No       | -           | Expected issuer (`iss`) claim. If not provided, issuer validation is skipped.               |
+| `audience`          | `string`   | No       | -           | Expected audience (`aud`) claim. If not provided, audience validation is skipped.           |
+| `algorithms`        | `string[]` | No       | `['RS256']` | Allowed algorithms for JWT verification                                                     |
+| `jwksCacheDuration` | `number`   | No       | `600000`    | JWKS cache duration in milliseconds (10 minutes)                                            |
+| `requestTimeout`    | `number`   | No       | `30000`     | Request timeout in milliseconds (30 seconds)                                                |
+| `priority`          | `number`   | No       | `-100`      | Hook priority (lower numbers run first)                                                     |
+
+\* `wellKnownUrl` is only required when `enabled` is `true`.
+
+## Environment Variables
+
+When using the Dismissible API Docker image or the standalone API, these environment variables configure JWT authentication:
+
+| Variable                                   | Description                            | Default  |
+| ------------------------------------------ | -------------------------------------- | -------- |
+| `DISMISSIBLE_JWT_AUTH_ENABLED`             | Enable JWT authentication              | `true`   |
+| `DISMISSIBLE_JWT_AUTH_WELL_KNOWN_URL`      | OIDC well-known URL for JWKS discovery | `""`     |
+| `DISMISSIBLE_JWT_AUTH_ISSUER`              | Expected issuer claim (optional)       | `""`     |
+| `DISMISSIBLE_JWT_AUTH_AUDIENCE`            | Expected audience claim (optional)     | `""`     |
+| `DISMISSIBLE_JWT_AUTH_ALGORITHMS`          | Allowed algorithms (comma-separated)   | `RS256`  |
+| `DISMISSIBLE_JWT_AUTH_JWKS_CACHE_DURATION` | JWKS cache duration in ms              | `600000` |
+| `DISMISSIBLE_JWT_AUTH_REQUEST_TIMEOUT`     | Request timeout in ms                  | `30000`  |
+| `DISMISSIBLE_JWT_AUTH_PRIORITY`            | Hook priority (lower runs first)       | `-100`   |
+
+### Example: Disabling JWT Auth for Development
+
+```bash
+docker run -p 3001:3001 \
+  -e DISMISSIBLE_JWT_AUTH_ENABLED=false \
+  -e DISMISSIBLE_POSTGRES_STORAGE_CONNECTION_STRING="postgresql://..." \
+  dismissibleio/dismissible-api:latest
+```
+
+### Example: Enabling JWT Auth with Auth0
+
+```bash
+docker run -p 3001:3001 \
+  -e DISMISSIBLE_JWT_AUTH_ENABLED=true \
+  -e DISMISSIBLE_JWT_AUTH_WELL_KNOWN_URL="https://your-tenant.auth0.com/.well-known/openid-configuration" \
+  -e DISMISSIBLE_JWT_AUTH_ISSUER="https://your-tenant.auth0.com/" \
+  -e DISMISSIBLE_JWT_AUTH_AUDIENCE="your-api-identifier" \
+  -e DISMISSIBLE_POSTGRES_STORAGE_CONNECTION_STRING="postgresql://..." \
+  dismissibleio/dismissible-api:latest
+```
+
+## How It Works
+
+1. **Initialization**: On module initialization, the hook fetches the OIDC configuration from the well-known URL to discover the JWKS endpoint.
+
+2. **Token Extraction**: For each request, the hook extracts the bearer token from the `Authorization` header.
+
+3. **Token Validation**: The token is validated by:
+   - Decoding the JWT to get the key ID (`kid`)
+   - Fetching the corresponding public key from JWKS
+   - Verifying the signature
+   - Validating claims (expiration, issuer, audience)
+
+4. **Request Handling**:
+   - If valid: The request proceeds
+   - If invalid: The request is blocked with a `403 Forbidden` response
+
+## Error Responses
+
+When authentication fails, the hook returns a structured error:
+
+```json
+{
+  "statusCode": 403,
+  "message": "Authorization failed: Token expired",
+  "error": "Forbidden"
+}
+```
+
+Common error messages:
+
+- `Authorization required: Missing or invalid bearer token`
+- `Authorization failed: Token expired`
+- `Authorization failed: Invalid signature`
+- `Authorization failed: Unable to find signing key`
+
+## Supported OIDC Providers
+
+This hook works with any OIDC-compliant identity provider, including:
+
+- Auth0
+- Okta
+- Keycloak
+- Azure AD
+- Google Identity Platform
+- AWS Cognito
+
+## License
+
+MIT

package/jest.config.ts

@@ -0,0 +1,27 @@
+export default {
+  displayName: 'jwt-auth-hook',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../coverage/libs/jwt-auth-hook',
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.spec.ts',
+    '!src/**/*.interface.ts',
+    '!src/**/*.dto.ts',
+    '!src/**/*.enum.ts',
+    '!src/**/index.ts',
+    '!src/**/*.module.ts',
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+      statements: 80,
+    },
+  },
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@dismissible/nestjs-jwt-auth-hook",
+  "version": "0.0.1",
+  "description": "JWT authentication hook for Dismissible applications using OIDC well-known discovery",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.mjs",
+      "require": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "jwks-rsa": "^3.1.0",
+    "jsonwebtoken": "^9.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/axios": "^4.0.0",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@dismissible/nestjs-dismissible": "*",
+    "@dismissible/nestjs-logger": "*"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/axios": {
+      "optional": false
+    },
+    "@nestjs/common": {
+      "optional": false
+    },
+    "@nestjs/core": {
+      "optional": false
+    },
+    "@dismissible/nestjs-dismissible": {
+      "optional": false
+    },
+    "@dismissible/nestjs-logger": {
+      "optional": false
+    }
+  },
+  "keywords": [
+    "nestjs",
+    "jwt",
+    "authentication",
+    "jwks",
+    "oidc",
+    "dismissible",
+    "hook"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DismissibleIo/dismissible-api"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/project.json

@@ -0,0 +1,42 @@
+{
+  "name": "jwt-auth-hook",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/jwt-auth-hook/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/jwt-auth-hook",
+        "main": "libs/jwt-auth-hook/src/index.ts",
+        "tsConfig": "libs/jwt-auth-hook/tsconfig.lib.json",
+        "assets": ["libs/jwt-auth-hook/package.json", "libs/jwt-auth-hook/README.md"],
+        "generatePackageJson": true
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["libs/jwt-auth-hook/**/*.ts"]
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/libs/jwt-auth-hook"],
+      "options": {
+        "jestConfig": "libs/jwt-auth-hook/jest.config.ts",
+        "passWithNoTests": true
+      }
+    },
+    "npm-publish": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "npm publish --access public",
+        "cwd": "dist/libs/jwt-auth-hook"
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './jwt-auth-hook.config';
+export * from './jwt-auth-hook.module';
+export * from './jwt-auth.hook';
+export * from './jwt-auth.service';

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

@@ -0,0 +1,158 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { JwtAuthHookConfig } from './jwt-auth-hook.config';
+
+describe('JwtAuthHookConfig', () => {
+  describe('enabled property', () => {
+    it('should transform boolean true to true', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: true,
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+      });
+
+      expect(config.enabled).toBe(true);
+    });
+
+    it('should transform boolean false to false', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: false,
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+      });
+
+      expect(config.enabled).toBe(false);
+    });
+
+    it('should transform string "true" to boolean true', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: 'true',
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+      });
+
+      expect(config.enabled).toBe(true);
+    });
+
+    it('should transform string "false" to boolean false', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: 'false',
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+      });
+
+      expect(config.enabled).toBe(false);
+    });
+
+    it('should transform string "True" (case insensitive) to boolean true', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: 'True',
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+      });
+
+      expect(config.enabled).toBe(true);
+    });
+
+    it('should convert non-true string values to false', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: 'other',
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+      });
+
+      // The transform converts string values: 'true' -> true, anything else -> false
+      expect(config.enabled).toBe(false);
+    });
+  });
+
+  describe('wellKnownUrl validation', () => {
+    it('should require wellKnownUrl when enabled is true', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: true,
+      });
+
+      const errors = await validate(config);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors.some((e) => e.property === 'wellKnownUrl')).toBe(true);
+    });
+
+    it('should not require wellKnownUrl when enabled is false', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: false,
+      });
+
+      const errors = await validate(config);
+      // wellKnownUrl should not be required when enabled is false
+      expect(errors.some((e) => e.property === 'wellKnownUrl')).toBe(false);
+    });
+
+    it('should validate wellKnownUrl is a valid URL', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: true,
+        wellKnownUrl: 'not-a-valid-url',
+      });
+
+      const errors = await validate(config);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors.some((e) => e.property === 'wellKnownUrl')).toBe(true);
+    });
+  });
+
+  describe('optional properties', () => {
+    it('should accept optional issuer', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: true,
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+        issuer: 'https://auth.example.com',
+      });
+
+      expect(config.issuer).toBe('https://auth.example.com');
+    });
+
+    it('should accept optional audience', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: true,
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+        audience: 'my-api',
+      });
+
+      expect(config.audience).toBe('my-api');
+    });
+
+    it('should accept optional algorithms array', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: true,
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+        algorithms: ['RS256', 'RS384'],
+      });
+
+      expect(config.algorithms).toEqual(['RS256', 'RS384']);
+    });
+
+    it('should transform jwksCacheDuration to number', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: true,
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+        jwksCacheDuration: '600000',
+      });
+
+      expect(config.jwksCacheDuration).toBe(600000);
+    });
+
+    it('should transform requestTimeout to number', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: true,
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+        requestTimeout: '30000',
+      });
+
+      expect(config.requestTimeout).toBe(30000);
+    });
+
+    it('should transform priority to number', async () => {
+      const config = plainToInstance(JwtAuthHookConfig, {
+        enabled: true,
+        wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+        priority: '-100',
+      });
+
+      expect(config.priority).toBe(-100);
+    });
+  });
+});

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

@@ -0,0 +1,94 @@
+import {
+  IsString,
+  IsUrl,
+  IsOptional,
+  IsArray,
+  IsNumber,
+  IsBoolean,
+  ValidateIf,
+} from 'class-validator';
+import { Type } from 'class-transformer';
+import { TransformBoolean } from '@dismissible/nestjs-validation';
+
+/**
+ * Injection token for JWT auth hook configuration.
+ */
+export const JWT_AUTH_HOOK_CONFIG = Symbol('JWT_AUTH_HOOK_CONFIG');
+
+/**
+ * Configuration options for JWT authentication hook.
+ */
+export class JwtAuthHookConfig {
+  @IsBoolean()
+  @TransformBoolean()
+  public readonly enabled!: boolean;
+
+  /**
+   * The OpenID Connect well-known URL (e.g., https://auth.example.com/.well-known/openid-configuration).
+   * The JWKS URI will be fetched from this endpoint.
+   */
+  @ValidateIf((o) => o.enabled === true)
+  @IsUrl()
+  public readonly wellKnownUrl!: string;
+
+  /**
+   * Optional: Expected issuer claim (iss) to validate.
+   * If not provided, issuer validation is skipped.
+   */
+  @IsOptional()
+  @IsString()
+  public readonly issuer?: string;
+
+  /**
+   * Optional: Expected audience claim (aud) to validate.
+   * If not provided, audience validation is skipped.
+   */
+  @IsOptional()
+  @IsString()
+  public readonly audience?: string;
+
+  /**
+   * Optional: Allowed algorithms for JWT verification.
+   * Defaults to ['RS256'].
+   */
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  public readonly algorithms?: string[];
+
+  /**
+   * Optional: Cache duration in milliseconds for JWKS.
+   * Defaults to 600000 (10 minutes).
+   */
+  @IsOptional()
+  @IsNumber()
+  @Type(() => Number)
+  public readonly jwksCacheDuration?: number;
+
+  /**
+   * Optional: Request timeout in milliseconds.
+   * Defaults to 30000 (30 seconds).
+   */
+  @IsOptional()
+  @IsNumber()
+  @Type(() => Number)
+  public readonly requestTimeout?: number;
+
+  /**
+   * Optional: Hook priority (lower numbers run first).
+   * Defaults to -100 (runs early for authentication).
+   */
+  @IsOptional()
+  @IsNumber()
+  @Type(() => Number)
+  public readonly priority?: number;
+
+  /**
+   * Optional: Verify that the userId parameter matches the JWT subject (sub) claim.
+   * Defaults to true for security. Set to false for service-to-service scenarios.
+   */
+  @IsOptional()
+  @IsBoolean()
+  @TransformBoolean(true) // Default to true if not provided
+  public readonly verifyUserIdMatch?: boolean;
+}

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

@@ -0,0 +1,79 @@
+import { Module, DynamicModule, InjectionToken } from '@nestjs/common';
+import { HttpModule } from '@nestjs/axios';
+import { JwtAuthHook } from './jwt-auth.hook';
+import { JwtAuthService } from './jwt-auth.service';
+import { JWT_AUTH_HOOK_CONFIG, JwtAuthHookConfig } from './jwt-auth-hook.config';
+
+/**
+ * Async module options for JWT auth hook.
+ */
+export interface IJwtAuthHookModuleAsyncOptions {
+  useFactory: (...args: unknown[]) => JwtAuthHookConfig | Promise<JwtAuthHookConfig>;
+  inject?: InjectionToken[];
+}
+
+/**
+ * Module that provides JWT authentication hook for Dismissible.
+ *
+ * @example
+ * ```typescript
+ * import { DismissibleModule } from '@dismissible/nestjs-dismissible';
+ * import { JwtAuthHookModule, JwtAuthHook } from '@dismissible/nestjs-jwt-auth-hook';
+ *
+ * @Module({
+ *   imports: [
+ *     JwtAuthHookModule.forRoot({
+ *       wellKnownUrl: 'https://auth.example.com/.well-known/openid-configuration',
+ *       issuer: 'https://auth.example.com',
+ *       audience: 'my-api',
+ *     }),
+ *     DismissibleModule.forRoot({
+ *       hooks: [JwtAuthHook],
+ *       // ... other options
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+@Module({})
+export class JwtAuthHookModule {
+  static forRoot(config: JwtAuthHookConfig): DynamicModule {
+    return {
+      module: JwtAuthHookModule,
+      imports: [HttpModule],
+      providers: [
+        {
+          provide: JWT_AUTH_HOOK_CONFIG,
+          useValue: config,
+        },
+        JwtAuthService,
+        JwtAuthHook,
+      ],
+      exports: [JwtAuthHook, JwtAuthService, JWT_AUTH_HOOK_CONFIG],
+      global: true,
+    };
+  }
+
+  /**
+   * Create module with async configuration.
+   * Useful when config values come from environment or other async sources.
+   */
+  static forRootAsync(options: IJwtAuthHookModuleAsyncOptions): DynamicModule {
+    return {
+      module: JwtAuthHookModule,
+      imports: [HttpModule],
+      providers: [
+        {
+          provide: JWT_AUTH_HOOK_CONFIG,
+          useFactory: options.useFactory,
+          inject: options.inject ?? [],
+        },
+        JwtAuthService,
+        JwtAuthHook,
+      ],
+      exports: [JwtAuthHook, JwtAuthService, JWT_AUTH_HOOK_CONFIG],
+      global: true,
+    };
+  }
+}