@pawells/nestjs-auth 1.0.0-dev.4c8c698

package/build/keycloak/keycloak.interfaces.d.ts

@@ -0,0 +1,12 @@
+import { ModuleMetadata } from '@nestjs/common';
+import type { InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import type { KeycloakModuleOptions } from './keycloak.types.js';
+/**
+ * Async options for KeycloakModule configuration
+ */
+export interface KeycloakModuleAsyncOptions {
+    imports?: ModuleMetadata['imports'];
+    useFactory: (...args: unknown[]) => Promise<KeycloakModuleOptions> | KeycloakModuleOptions;
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+}
+//# sourceMappingURL=keycloak.interfaces.d.ts.map

package/build/keycloak/keycloak.interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keycloak.interfaces.d.ts","sourceRoot":"","sources":["../../src/keycloak/keycloak.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,0BAA0B;IAC1C,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IACpC,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAAC;IAC3F,MAAM,CAAC,EAAE,KAAK,CAAC,cAAc,GAAG,yBAAyB,CAAC,CAAC;CAC3D"}

package/build/keycloak/keycloak.interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=keycloak.interfaces.js.map

package/build/keycloak/keycloak.interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keycloak.interfaces.js","sourceRoot":"","sources":["../../src/keycloak/keycloak.interfaces.ts"],"names":[],"mappings":""}

package/build/keycloak/keycloak.module.d.ts

@@ -0,0 +1,56 @@
+import { DynamicModule } from '@nestjs/common';
+import type { KeycloakModuleOptions } from './keycloak.types.js';
+import type { KeycloakModuleAsyncOptions } from './keycloak.interfaces.js';
+/**
+ * Keycloak Token Validation Module
+ *
+ * Provides Keycloak token validation for NestJS resource servers. Supports two validation modes:
+ * - **Online mode (default)**: Uses Keycloak's token introspection endpoint for real-time token validation
+ * - **Offline mode (opt-in)**: Validates JWTs using cached JWKS (JSON Web Key Set) for stateless validation
+ *
+ * Export the `JwtAuthGuard` and decorate controllers/routes with `@UseGuards(JwtAuthGuard)` to enable
+ * token validation. The guard respects `@Public()` to bypass authentication on specific endpoints.
+ *
+ * @example
+ * ```typescript
+ * // Online mode (default)
+ * KeycloakModule.forRoot({
+ *   authServerUrl: 'https://keycloak.example.com',
+ *   clientId: 'my-client',
+ *   clientSecret: 'secret',
+ *   validationMode: 'online'
+ * })
+ *
+ * // Offline mode (JWKS-based)
+ * KeycloakModule.forRoot({
+ *   authServerUrl: 'https://keycloak.example.com',
+ *   clientId: 'my-client',
+ *   validationMode: 'offline'
+ * })
+ * ```
+ */
+export declare class KeycloakModule {
+    /**
+     * Register Keycloak module with static configuration
+     *
+     * @param options - Configuration options for the Keycloak module
+     * @returns Dynamic module configuration with KeycloakTokenValidationService and JwksCacheService
+     */
+    static forRoot(options: KeycloakModuleOptions): DynamicModule;
+    /**
+     * Register Keycloak module with asynchronous configuration
+     *
+     * Defers module configuration until runtime using a factory function.
+     * Useful for reading configuration from environment variables or other async sources.
+     *
+     * @param options - Async factory configuration
+     * @param options.useFactory - Function that returns KeycloakModuleOptions or a promise that resolves to it
+     * @param options.inject - Optional array of providers to inject into the factory function
+     * @param options.imports - Optional array of modules to import for dependency injection
+     * @returns Dynamic module configuration with KeycloakTokenValidationService and JwksCacheService.
+     *   Note: JwksCacheService is always provided in async mode (validationMode is not known at
+     *   module definition time). In online mode, it initializes but skips the JWKS fetch.
+     */
+    static forRootAsync(options: KeycloakModuleAsyncOptions): DynamicModule;
+}
+//# sourceMappingURL=keycloak.module.d.ts.map

package/build/keycloak/keycloak.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keycloak.module.d.ts","sourceRoot":"","sources":["../../src/keycloak/keycloak.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAI3E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBACa,cAAc;IAC1B;;;;;OAKG;WACW,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa;IAuBpE;;;;;;;;;;;;;OAaG;WACW,YAAY,CAAC,OAAO,EAAE,0BAA0B,GAAG,aAAa;CAgB9E"}

package/build/keycloak/keycloak.module.js

@@ -0,0 +1,104 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var KeycloakModule_1;
+import { Module } from '@nestjs/common';
+import { JwtModule } from '@nestjs/jwt';
+import { KEYCLOAK_MODULE_OPTIONS } from './keycloak.constants.js';
+import { JwksCacheService } from './services/jwks-cache.service.js';
+import { KeycloakTokenValidationService } from './services/keycloak-token-validation.service.js';
+/**
+ * Keycloak Token Validation Module
+ *
+ * Provides Keycloak token validation for NestJS resource servers. Supports two validation modes:
+ * - **Online mode (default)**: Uses Keycloak's token introspection endpoint for real-time token validation
+ * - **Offline mode (opt-in)**: Validates JWTs using cached JWKS (JSON Web Key Set) for stateless validation
+ *
+ * Export the `JwtAuthGuard` and decorate controllers/routes with `@UseGuards(JwtAuthGuard)` to enable
+ * token validation. The guard respects `@Public()` to bypass authentication on specific endpoints.
+ *
+ * @example
+ * ```typescript
+ * // Online mode (default)
+ * KeycloakModule.forRoot({
+ *   authServerUrl: 'https://keycloak.example.com',
+ *   clientId: 'my-client',
+ *   clientSecret: 'secret',
+ *   validationMode: 'online'
+ * })
+ *
+ * // Offline mode (JWKS-based)
+ * KeycloakModule.forRoot({
+ *   authServerUrl: 'https://keycloak.example.com',
+ *   clientId: 'my-client',
+ *   validationMode: 'offline'
+ * })
+ * ```
+ */
+let KeycloakModule = KeycloakModule_1 = class KeycloakModule {
+    /**
+     * Register Keycloak module with static configuration
+     *
+     * @param options - Configuration options for the Keycloak module
+     * @returns Dynamic module configuration with KeycloakTokenValidationService and JwksCacheService
+     */
+    static forRoot(options) {
+        const isOffline = options.validationMode === 'offline';
+        const providers = [
+            {
+                provide: KEYCLOAK_MODULE_OPTIONS,
+                useValue: options,
+            },
+            KeycloakTokenValidationService,
+            ...(isOffline ? [JwksCacheService] : []),
+        ];
+        return {
+            module: KeycloakModule_1,
+            imports: [JwtModule.register({})],
+            providers,
+            exports: [
+                KeycloakTokenValidationService,
+                ...(isOffline ? [JwksCacheService] : []),
+                KEYCLOAK_MODULE_OPTIONS,
+            ],
+        };
+    }
+    /**
+     * Register Keycloak module with asynchronous configuration
+     *
+     * Defers module configuration until runtime using a factory function.
+     * Useful for reading configuration from environment variables or other async sources.
+     *
+     * @param options - Async factory configuration
+     * @param options.useFactory - Function that returns KeycloakModuleOptions or a promise that resolves to it
+     * @param options.inject - Optional array of providers to inject into the factory function
+     * @param options.imports - Optional array of modules to import for dependency injection
+     * @returns Dynamic module configuration with KeycloakTokenValidationService and JwksCacheService.
+     *   Note: JwksCacheService is always provided in async mode (validationMode is not known at
+     *   module definition time). In online mode, it initializes but skips the JWKS fetch.
+     */
+    static forRootAsync(options) {
+        return {
+            module: KeycloakModule_1,
+            imports: [JwtModule.register({}), ...(options.imports ?? [])],
+            providers: [
+                {
+                    provide: KEYCLOAK_MODULE_OPTIONS,
+                    useFactory: options.useFactory,
+                    inject: options.inject ?? [],
+                },
+                JwksCacheService,
+                KeycloakTokenValidationService,
+            ],
+            exports: [KeycloakTokenValidationService, JwksCacheService, KEYCLOAK_MODULE_OPTIONS],
+        };
+    }
+};
+KeycloakModule = KeycloakModule_1 = __decorate([
+    Module({})
+], KeycloakModule);
+export { KeycloakModule };
+//# sourceMappingURL=keycloak.module.js.map

package/build/keycloak/keycloak.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keycloak.module.js","sourceRoot":"","sources":["../../src/keycloak/keycloak.module.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAE,MAAM,EAAiB,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,8BAA8B,EAAE,MAAM,iDAAiD,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEI,IAAM,cAAc,sBAApB,MAAM,cAAc;IAC1B;;;;;OAKG;IACI,MAAM,CAAC,OAAO,CAAC,OAA8B;QACnD,MAAM,SAAS,GAAG,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC;QACvD,MAAM,SAAS,GAAG;YACjB;gBACC,OAAO,EAAE,uBAAuB;gBAChC,QAAQ,EAAE,OAAO;aACjB;YACD,8BAA8B;YAC9B,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACxC,CAAC;QAEF,OAAO;YACN,MAAM,EAAE,gBAAc;YACtB,OAAO,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YACjC,SAAS;YACT,OAAO,EAAE;gBACR,8BAA8B;gBAC9B,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxC,uBAAuB;aACvB;SACD,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACI,MAAM,CAAC,YAAY,CAAC,OAAmC;QAC7D,OAAO;YACN,MAAM,EAAE,gBAAc;YACtB,OAAO,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;YAC7D,SAAS,EAAE;gBACV;oBACC,OAAO,EAAE,uBAAuB;oBAChC,UAAU,EAAE,OAAO,CAAC,UAAU;oBAC9B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;iBAC5B;gBACD,gBAAgB;gBAChB,8BAA8B;aAC9B;YACD,OAAO,EAAE,CAAC,8BAA8B,EAAE,gBAAgB,EAAE,uBAAuB,CAAC;SACpF,CAAC;IACH,CAAC;CACD,CAAA;AA5DY,cAAc;IAD1B,MAAM,CAAC,EAAE,CAAC;GACE,cAAc,CA4D1B"}

package/build/keycloak/keycloak.types.d.ts

@@ -0,0 +1,60 @@
+export interface KeycloakModuleOptions {
+    /** Keycloak realm base URL — e.g. 'https://auth.example.com/realms/myrealm' */
+    authServerUrl: string;
+    /** Realm name */
+    realm: string;
+    /** This service's Keycloak client ID — used for audience validation and client role extraction */
+    clientId: string;
+    /**
+     * Token validation mode.
+     * - 'online' (default): validate via Keycloak introspection — authoritative, detects revocation immediately
+     * - 'offline': validate JWT locally using JWKS — fast, no network hop, does not detect revocation
+     */
+    validationMode?: 'online' | 'offline';
+    /** Required when validationMode is 'online' (the default). Client secret for the introspection endpoint. */
+    clientSecret?: string;
+    /** JWKS cache TTL in milliseconds. Used in offline mode only. Default: 300000 (5 minutes). */
+    jwksCacheTtlMs?: number;
+    /**
+     * Expected token issuer. Must match the 'iss' claim exactly.
+     * Defaults to authServerUrl.
+     */
+    issuer?: string;
+}
+export interface KeycloakTokenClaims {
+    sub: string;
+    iss: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    jti?: string;
+    azp?: string;
+    session_state?: string;
+    email?: string;
+    email_verified?: boolean;
+    preferred_username?: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    realm_access?: {
+        roles: string[];
+    };
+    resource_access?: Record<string, {
+        roles: string[];
+    }>;
+    scope?: string;
+    [key: string]: unknown;
+}
+export interface KeycloakUser {
+    /** The user's unique ID (sub claim) */
+    id: string;
+    email?: string;
+    /** preferred_username claim */
+    username?: string;
+    name?: string;
+    /** Roles from realm_access.roles */
+    realmRoles: string[];
+    /** Roles from resource_access[clientId].roles */
+    clientRoles: string[];
+}
+//# sourceMappingURL=keycloak.types.d.ts.map

package/build/keycloak/keycloak.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keycloak.types.d.ts","sourceRoot":"","sources":["../../src/keycloak/keycloak.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACrC,+EAA+E;IAC/E,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACtC,4GAA4G;IAC5G,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC5B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iDAAiD;IACjD,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB"}

package/build/keycloak/keycloak.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=keycloak.types.js.map

package/build/keycloak/keycloak.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keycloak.types.js","sourceRoot":"","sources":["../../src/keycloak/keycloak.types.ts"],"names":[],"mappings":""}

package/build/keycloak/services/jwks-cache.service.d.ts

@@ -0,0 +1,64 @@
+import { OnModuleInit } from '@nestjs/common';
+import type { KeycloakModuleOptions } from '../keycloak.types.js';
+/**
+ * JWKS Cache Service
+ *
+ * Fetches and caches JWKS (JSON Web Key Set) from Keycloak for offline token validation.
+ * Used exclusively in offline validation mode to verify JWT signatures locally without
+ * contacting the Keycloak introspection endpoint.
+ *
+ * Caches keys with automatic expiration (default 5 minutes). On key rotation or cache expiry,
+ * automatically re-fetches the latest JWKS from Keycloak. Prevents concurrent fetches to avoid
+ * stampedes.
+ *
+ * @example
+ * ```typescript
+ * constructor(private jwksCache: JwksCacheService) {}
+ *
+ * async validateJwt(token: string): Promise<boolean> {
+ *   const decoded = jwt.decode(token, { complete: true });
+ *   const key = await this.jwksCache.getKey(decoded.header.kid);
+ *   return jwt.verify(token, key);
+ * }
+ * ```
+ */
+export declare class JwksCacheService implements OnModuleInit {
+    private readonly keyCache;
+    private cacheExpiresAt;
+    private fetchPromise;
+    private logger?;
+    private readonly options;
+    constructor(options: KeycloakModuleOptions);
+    private initializeLogger;
+    onModuleInit(): Promise<void>;
+    /**
+     * Get a public key from cache by key ID (kid)
+     *
+     * Checks the cache for the requested key. If found and not expired, returns it immediately.
+     * If not found or cache is expired, automatically re-fetches all keys from Keycloak.
+     * Prevents concurrent fetches with an internal lock.
+     *
+     * On key rotation, the next key request for a missing `kid` will trigger a refresh and
+     * cache the new key set.
+     *
+     * @param kid - The Key ID (from JWT header) to retrieve
+     * @returns The PEM-encoded public key (SPKI format)
+     * @throws {UnauthorizedException} If the key ID is not found after re-fetch attempt
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const key = await this.jwksCache.getKey('abc123');
+     *   // Use key for JWT verification
+     * } catch (error) {
+       *   // Handle unknown key ID
+     * }
+     * ```
+     */
+    getKey(kid: string): Promise<string>;
+    private fetchJwks;
+    private doFetch;
+    private convertJwkToPem;
+    private log;
+}
+//# sourceMappingURL=jwks-cache.service.d.ts.map

package/build/keycloak/services/jwks-cache.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks-cache.service.d.ts","sourceRoot":"","sources":["../../../src/keycloak/services/jwks-cache.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,YAAY,EAAiC,MAAM,gBAAgB,CAAC;AAIzF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAgBlE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBACa,gBAAiB,YAAW,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAE3D,OAAO,CAAC,cAAc,CAAa;IAEnC,OAAO,CAAC,YAAY,CAA8B;IAElD,OAAO,CAAC,MAAM,CAAC,CAAY;IAE3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;gBAGd,OAAO,EAAE,qBAAqB;IAMhE,OAAO,CAAC,gBAAgB;IAQX,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ1C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACU,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YA2BnC,SAAS;YAaT,OAAO;IA6BrB,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,GAAG;CASX"}

package/build/keycloak/services/jwks-cache.service.js

@@ -0,0 +1,176 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var JwksCacheService_1;
+import { Injectable, Inject, UnauthorizedException } from '@nestjs/common';
+import { createPublicKey } from 'node:crypto';
+import { AppLogger, getErrorMessage } from '@pawells/nestjs-shared/common';
+import { KEYCLOAK_MODULE_OPTIONS } from '../keycloak.constants.js';
+const DEFAULT_JWKS_CACHE_TTL_MS = 300_000;
+/**
+ * JWKS Cache Service
+ *
+ * Fetches and caches JWKS (JSON Web Key Set) from Keycloak for offline token validation.
+ * Used exclusively in offline validation mode to verify JWT signatures locally without
+ * contacting the Keycloak introspection endpoint.
+ *
+ * Caches keys with automatic expiration (default 5 minutes). On key rotation or cache expiry,
+ * automatically re-fetches the latest JWKS from Keycloak. Prevents concurrent fetches to avoid
+ * stampedes.
+ *
+ * @example
+ * ```typescript
+ * constructor(private jwksCache: JwksCacheService) {}
+ *
+ * async validateJwt(token: string): Promise<boolean> {
+ *   const decoded = jwt.decode(token, { complete: true });
+ *   const key = await this.jwksCache.getKey(decoded.header.kid);
+ *   return jwt.verify(token, key);
+ * }
+ * ```
+ */
+let JwksCacheService = JwksCacheService_1 = class JwksCacheService {
+    keyCache = new Map();
+    cacheExpiresAt = 0;
+    fetchPromise = null;
+    logger;
+    options;
+    constructor(options) {
+        this.options = options;
+        this.initializeLogger();
+    }
+    initializeLogger() {
+        try {
+            this.logger = new AppLogger(undefined, JwksCacheService_1.name);
+        }
+        catch {
+            // Logger unavailable, fall back to console
+        }
+    }
+    async onModuleInit() {
+        // Only fetch JWKS if in offline validation mode
+        if (this.options.validationMode !== 'offline') {
+            return;
+        }
+        await this.fetchJwks();
+    }
+    /**
+     * Get a public key from cache by key ID (kid)
+     *
+     * Checks the cache for the requested key. If found and not expired, returns it immediately.
+     * If not found or cache is expired, automatically re-fetches all keys from Keycloak.
+     * Prevents concurrent fetches with an internal lock.
+     *
+     * On key rotation, the next key request for a missing `kid` will trigger a refresh and
+     * cache the new key set.
+     *
+     * @param kid - The Key ID (from JWT header) to retrieve
+     * @returns The PEM-encoded public key (SPKI format)
+     * @throws {UnauthorizedException} If the key ID is not found after re-fetch attempt
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const key = await this.jwksCache.getKey('abc123');
+     *   // Use key for JWT verification
+     * } catch (error) {
+       *   // Handle unknown key ID
+     * }
+     * ```
+     */
+    async getKey(kid) {
+        // Check if key is in cache and not expired
+        if (this.keyCache.has(kid) && Date.now() < this.cacheExpiresAt) {
+            const key = this.keyCache.get(kid);
+            if (key) {
+                return key;
+            }
+        }
+        // Key not found or cache expired, re-fetch
+        try {
+            await this.fetchJwks();
+        }
+        catch (error) {
+            this.log('warn', `Failed to re-fetch JWKS during key lookup: ${getErrorMessage(error)}`);
+        }
+        // Check cache again after re-fetch — only return if cache is still valid
+        if (this.keyCache.has(kid) && Date.now() < this.cacheExpiresAt) {
+            const key = this.keyCache.get(kid);
+            if (key) {
+                return key;
+            }
+        }
+        throw new UnauthorizedException('Unknown signing key');
+    }
+    async fetchJwks() {
+        // If a fetch is already in-flight, await it instead of making another request
+        if (this.fetchPromise !== null) {
+            await this.fetchPromise;
+            return;
+        }
+        this.fetchPromise = this.doFetch().finally(() => {
+            this.fetchPromise = null;
+        });
+        await this.fetchPromise;
+    }
+    async doFetch() {
+        try {
+            const jwksUrl = `${this.options.authServerUrl}/realms/${this.options.realm}/protocol/openid-connect/certs`;
+            const response = await fetch(jwksUrl);
+            if (!response.ok) {
+                throw new Error(`JWKS fetch failed with status ${response.status}`);
+            }
+            const jwksData = await response.json();
+            if (!Array.isArray(jwksData.keys)) {
+                throw new Error('Invalid JWKS response: keys is not an array');
+            }
+            this.keyCache.clear();
+            for (const jwk of jwksData.keys) {
+                const pem = this.convertJwkToPem(jwk);
+                this.keyCache.set(jwk.kid, pem);
+            }
+            const ttlMs = this.options.jwksCacheTtlMs ?? DEFAULT_JWKS_CACHE_TTL_MS;
+            this.cacheExpiresAt = Date.now() + ttlMs;
+        }
+        catch (error) {
+            this.log('warn', `Failed to fetch JWKS: ${getErrorMessage(error)}`);
+            throw error;
+        }
+    }
+    convertJwkToPem(jwk) {
+        const key = createPublicKey({
+            key: jwk,
+            format: 'jwk',
+        });
+        return key.export({
+            type: 'spki',
+            format: 'pem',
+        });
+    }
+    log(level, message) {
+        if (this.logger) {
+            if (level === 'warn') {
+                this.logger.warn(message);
+            }
+            else {
+                this.logger.info(message);
+            }
+        }
+    }
+};
+JwksCacheService = JwksCacheService_1 = __decorate([
+    Injectable(),
+    __param(0, Inject(KEYCLOAK_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], JwksCacheService);
+export { JwksCacheService };
+//# sourceMappingURL=jwks-cache.service.js.map

package/build/keycloak/services/jwks-cache.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks-cache.service.js","sourceRoot":"","sources":["../../../src/keycloak/services/jwks-cache.service.ts"],"names":[],"mappings":"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"}

package/build/keycloak/services/keycloak-token-validation.service.d.ts

@@ -0,0 +1,88 @@
+import { JwtService } from '@nestjs/jwt';
+import type { KeycloakModuleOptions, KeycloakTokenClaims, KeycloakUser } from '../keycloak.types.js';
+import { JwksCacheService } from './jwks-cache.service.js';
+export interface TokenValidationResult {
+    valid: boolean;
+    claims?: KeycloakTokenClaims;
+    error?: string;
+}
+/**
+ * Keycloak Token Validation Service
+ *
+ * Validates JWT tokens issued by Keycloak in two modes:
+ * - **Online mode (default)**: Calls Keycloak's token introspection endpoint to validate the token
+ *   (requires real-time network access to Keycloak)
+ * - **Offline mode**: Validates JWTs locally using JWKS (no network call; suitable for high-traffic scenarios)
+ *
+ * After successful validation, extracts user identity and roles from token claims.
+ *
+ * @example
+ * ```typescript
+ * // Online mode validation
+ * const result = await this.validationService.validateToken(token);
+ * if (result.valid) {
+ *   const user = this.validationService.extractUser(result.claims!);
+ * }
+ *
+ * // Offline mode uses JWKS-based verification (faster, no network call)
+ * ```
+ */
+export declare class KeycloakTokenValidationService {
+    private logger?;
+    private readonly options;
+    private readonly jwtService;
+    private readonly jwksCacheService?;
+    constructor(options: KeycloakModuleOptions, jwtService: JwtService, jwksCacheService?: JwksCacheService);
+    private initializeLogger;
+    /**
+     * Validate a JWT token issued by Keycloak
+     *
+     * Routes to the appropriate validation mode based on configuration:
+     * - **Online**: Calls the Keycloak introspection endpoint (requires network access)
+     * - **Offline**: Verifies JWT signature using cached JWKS (no network call)
+     *
+     * Both modes verify token expiration and audience/issuer claims.
+     *
+     * @param token - The JWT to validate (Bearer token without "Bearer " prefix)
+     * @returns Result object with validation status and optional claims on success, or error code on failure
+     * @returns `{ valid: true, claims: KeycloakTokenClaims }` on success
+     * @returns `{ valid: false, error: string }` on failure (includes error codes like 'token_expired', 'invalid_issuer', etc.)
+     *
+     * @example
+     * ```typescript
+     * const result = await this.validateToken(jwtToken);
+     * if (result.valid && result.claims) {
+     *   const user = this.extractUser(result.claims);
+     * }
+     * ```
+     */
+    validateToken(token: string): Promise<TokenValidationResult>;
+    private validateTokenOnline;
+    private validateTokenOffline;
+    /**
+     * Extract user identity and roles from validated token claims
+     *
+     * Maps Keycloak token claims to a simplified `KeycloakUser` object.
+     * Extracts both realm-level roles (`realm_access.roles`) and client-specific roles
+     * (`resource_access[clientId].roles`).
+     *
+     * @param claims - The validated Keycloak token claims
+     * @returns User object with ID, email, username, name, and both realm and client roles
+     *
+     * @example
+     * ```typescript
+     * const user = this.extractUser(claims);
+     * // {
+     * //   id: 'user-uuid',
+     * //   email: 'user@example.com',
+     * //   username: 'john_doe',
+     * //   name: 'John Doe',
+     * //   realmRoles: ['admin', 'user'],
+     * //   clientRoles: ['read', 'write']
+     * // }
+     * ```
+     */
+    extractUser(claims: KeycloakTokenClaims): KeycloakUser;
+    private log;
+}
+//# sourceMappingURL=keycloak-token-validation.service.d.ts.map

package/build/keycloak/services/keycloak-token-validation.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keycloak-token-validation.service.d.ts","sourceRoot":"","sources":["../../../src/keycloak/services/keycloak-token-validation.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACrG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBACa,8BAA8B;IAC1C,OAAO,CAAC,MAAM,CAAC,CAAY;IAE3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAEhD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAmB;gBAGnB,OAAO,EAAE,qBAAqB,EAC/D,UAAU,EAAE,UAAU,EACV,gBAAgB,CAAC,EAAE,gBAAgB;IAQhD,OAAO,CAAC,gBAAgB;IAQxB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;YAe3D,mBAAmB;YA8CnB,oBAAoB;IAiElC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,WAAW,CAAC,MAAM,EAAE,mBAAmB,GAAG,YAAY;IAW7D,OAAO,CAAC,GAAG;CASX"}