nestjs-keycloak-auth 1.0.0

package/dist/decorators/enforcer-options.decorator.d.ts

@@ -0,0 +1,8 @@
+import { KeycloakEnforcerOptions } from '../interface/enforcer-options.interface';
+export declare const META_ENFORCER_OPTIONS = "enforcer-options";
+/**
+ * Keycloak enforcer options
+ * @param opts - enforcer options
+ * @since 1.3.0
+ */
+export declare const EnforcerOptions: (opts: KeycloakEnforcerOptions) => import("@nestjs/common").CustomDecorator<string>;

package/dist/decorators/enforcer-options.decorator.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnforcerOptions = exports.META_ENFORCER_OPTIONS = void 0;
+const common_1 = require("@nestjs/common");
+exports.META_ENFORCER_OPTIONS = 'enforcer-options';
+/**
+ * Keycloak enforcer options
+ * @param opts - enforcer options
+ * @since 1.3.0
+ */
+const EnforcerOptions = (opts) => (0, common_1.SetMetadata)(exports.META_ENFORCER_OPTIONS, opts);
+exports.EnforcerOptions = EnforcerOptions;

package/dist/decorators/keycloak-user.decorator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Retrieves the current Keycloak logged-in user.
+ * @since 1.5.0
+ */
+export declare const KeycloakUser: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/decorators/keycloak-user.decorator.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeycloakUser = void 0;
+const internal_util_1 = require("../internal.util");
+const common_1 = require("@nestjs/common");
+/**
+ * Retrieves the current Keycloak logged-in user.
+ * @since 1.5.0
+ */
+exports.KeycloakUser = (0, common_1.createParamDecorator)((data, ctx) => {
+    const [req] = (0, internal_util_1.extractRequest)(ctx);
+    return req.user;
+});

package/dist/decorators/public.decorator.d.ts

@@ -0,0 +1,6 @@
+export declare const META_PUBLIC = "public";
+/**
+ * Allows unauthorized traffic to enter the route.
+ * @since 1.2.0
+ */
+export declare const Public: () => import("@nestjs/common").CustomDecorator<string>;

package/dist/decorators/public.decorator.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Public = exports.META_PUBLIC = void 0;
+const common_1 = require("@nestjs/common");
+exports.META_PUBLIC = 'public';
+/**
+ * Allows unauthorized traffic to enter the route.
+ * @since 1.2.0
+ */
+const Public = () => (0, common_1.SetMetadata)(exports.META_PUBLIC, true);
+exports.Public = Public;

package/dist/decorators/resource.decorator.d.ts

@@ -0,0 +1,6 @@
+export declare const META_RESOURCE = "resource";
+/**
+ * Keycloak Resource.
+ * @param resource - name of resource
+ */
+export declare const Resource: (resource: string) => import("@nestjs/common").CustomDecorator<string>;

package/dist/decorators/resource.decorator.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Resource = exports.META_RESOURCE = void 0;
+const common_1 = require("@nestjs/common");
+exports.META_RESOURCE = 'resource';
+/**
+ * Keycloak Resource.
+ * @param resource - name of resource
+ */
+const Resource = (resource) => (0, common_1.SetMetadata)(exports.META_RESOURCE, resource);
+exports.Resource = Resource;

package/dist/decorators/roles.decorator.d.ts

@@ -0,0 +1,10 @@
+import { RoleMatch } from '../constants';
+export declare const META_ROLES = "roles";
+export declare const META_ROLE_MATCHING_MODE = "role-matching-mode";
+/**
+ * Keycloak user roles.
+ * @param roles - the roles to match
+ * @since 2.0.0
+ */
+export declare const Roles: (...roles: string[]) => import("@nestjs/common").CustomDecorator<string>;
+export declare const RoleMatchingMode: (mode: RoleMatch) => import("@nestjs/common").CustomDecorator<string>;

package/dist/decorators/roles.decorator.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleMatchingMode = exports.Roles = exports.META_ROLE_MATCHING_MODE = exports.META_ROLES = void 0;
+const common_1 = require("@nestjs/common");
+exports.META_ROLES = 'roles';
+exports.META_ROLE_MATCHING_MODE = 'role-matching-mode';
+/**
+ * Keycloak user roles.
+ * @param roles - the roles to match
+ * @since 2.0.0
+ */
+const Roles = (...roles) => (0, common_1.SetMetadata)(exports.META_ROLES, roles);
+exports.Roles = Roles;
+const RoleMatchingMode = (mode) => (0, common_1.SetMetadata)(exports.META_ROLE_MATCHING_MODE, mode);
+exports.RoleMatchingMode = RoleMatchingMode;

package/dist/decorators/scopes.decorator.d.ts

@@ -0,0 +1,19 @@
+import { ConditionalScopeFn } from '../types/conditional-scope.type';
+export { ConditionalScopeFn };
+export declare const META_SCOPES = "scopes";
+export declare const META_CONDITIONAL_SCOPES = "conditional-scopes";
+/**
+ * Keycloak authorization scopes.
+ * @param scopes - scopes that are associated with the resource
+ */
+export declare const Scopes: (...scopes: string[]) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * Keycloak authorization conditional scopes.
+ * @param resolver
+ */
+export declare const ConditionalScopes: (resolver: ConditionalScopeFn) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * Retrieves the resolved scopes.
+ * @since 1.5.0
+ */
+export declare const ResolvedScopes: (...dataOrPipes: unknown[]) => ParameterDecorator;

package/dist/decorators/scopes.decorator.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResolvedScopes = exports.ConditionalScopes = exports.Scopes = exports.META_CONDITIONAL_SCOPES = exports.META_SCOPES = void 0;
+const internal_util_1 = require("../internal.util");
+const common_1 = require("@nestjs/common");
+exports.META_SCOPES = 'scopes';
+exports.META_CONDITIONAL_SCOPES = 'conditional-scopes';
+/**
+ * Keycloak authorization scopes.
+ * @param scopes - scopes that are associated with the resource
+ */
+const Scopes = (...scopes) => (0, common_1.SetMetadata)(exports.META_SCOPES, scopes);
+exports.Scopes = Scopes;
+/**
+ * Keycloak authorization conditional scopes.
+ * @param resolver
+ */
+const ConditionalScopes = (resolver) => (0, common_1.SetMetadata)(exports.META_CONDITIONAL_SCOPES, resolver);
+exports.ConditionalScopes = ConditionalScopes;
+/**
+ * Retrieves the resolved scopes.
+ * @since 1.5.0
+ */
+exports.ResolvedScopes = (0, common_1.createParamDecorator)((data, ctx) => {
+    const [req] = (0, internal_util_1.extractRequest)(ctx);
+    return req.scopes;
+});

package/dist/decorators/token-scopes.decorator.d.ts

@@ -0,0 +1,19 @@
+export declare const META_TOKEN_SCOPES = "token-scopes";
+/**
+ * Decorator to require specific OAuth2 scopes from the JWT `scope` claim.
+ *
+ * Unlike `@Scopes()` which checks UMA resource permissions, this decorator
+ * validates the space-delimited `scope` string in the access token itself
+ * (e.g. `"openid profile email"`).
+ *
+ * Enforced by `AuthGuard` — returns 403 Forbidden when required scopes
+ * are missing (the user is authenticated but lacks the granted scope).
+ *
+ * @example
+ * ```ts
+ * @Get('profile')
+ * @TokenScopes('openid', 'profile')
+ * getProfile() { ... }
+ * ```
+ */
+export declare const TokenScopes: (...scopes: string[]) => import("@nestjs/common").CustomDecorator<string>;

package/dist/decorators/token-scopes.decorator.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenScopes = exports.META_TOKEN_SCOPES = void 0;
+const common_1 = require("@nestjs/common");
+exports.META_TOKEN_SCOPES = 'token-scopes';
+/**
+ * Decorator to require specific OAuth2 scopes from the JWT `scope` claim.
+ *
+ * Unlike `@Scopes()` which checks UMA resource permissions, this decorator
+ * validates the space-delimited `scope` string in the access token itself
+ * (e.g. `"openid profile email"`).
+ *
+ * Enforced by `AuthGuard` — returns 403 Forbidden when required scopes
+ * are missing (the user is authenticated but lacks the granted scope).
+ *
+ * @example
+ * ```ts
+ * @Get('profile')
+ * @TokenScopes('openid', 'profile')
+ * getProfile() { ... }
+ * ```
+ */
+const TokenScopes = (...scopes) => (0, common_1.SetMetadata)(exports.META_TOKEN_SCOPES, scopes);
+exports.TokenScopes = TokenScopes;

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Base error class for all nestjs-keycloak-auth errors.
+ * Consumers can catch `instanceof KeycloakAuthError` to handle any library error.
+ */
+export declare class KeycloakAuthError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+/** Configuration invariants, missing values, file not found. */
+export declare class KeycloakConfigError extends KeycloakAuthError {
+    constructor(message: string);
+}
+/** Token parsing, grant validation, JWKS key not found. */
+export declare class KeycloakTokenError extends KeycloakAuthError {
+    constructor(message: string);
+}
+/** Permission check failures. */
+export declare class KeycloakPermissionError extends KeycloakAuthError {
+    constructor(message: string);
+}
+/** Admin callback signature verification, invalid admin tokens. */
+export declare class KeycloakAdminError extends KeycloakAuthError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeycloakAdminError = exports.KeycloakPermissionError = exports.KeycloakTokenError = exports.KeycloakConfigError = exports.KeycloakAuthError = void 0;
+/**
+ * Base error class for all nestjs-keycloak-auth errors.
+ * Consumers can catch `instanceof KeycloakAuthError` to handle any library error.
+ */
+class KeycloakAuthError extends Error {
+    constructor(message, code = 'KEYCLOAK_AUTH_ERROR') {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.KeycloakAuthError = KeycloakAuthError;
+/** Configuration invariants, missing values, file not found. */
+class KeycloakConfigError extends KeycloakAuthError {
+    constructor(message) {
+        super(message, 'KEYCLOAK_CONFIG_ERROR');
+    }
+}
+exports.KeycloakConfigError = KeycloakConfigError;
+/** Token parsing, grant validation, JWKS key not found. */
+class KeycloakTokenError extends KeycloakAuthError {
+    constructor(message) {
+        super(message, 'KEYCLOAK_TOKEN_ERROR');
+    }
+}
+exports.KeycloakTokenError = KeycloakTokenError;
+/** Permission check failures. */
+class KeycloakPermissionError extends KeycloakAuthError {
+    constructor(message) {
+        super(message, 'KEYCLOAK_PERMISSION_ERROR');
+    }
+}
+exports.KeycloakPermissionError = KeycloakPermissionError;
+/** Admin callback signature verification, invalid admin tokens. */
+class KeycloakAdminError extends KeycloakAuthError {
+    constructor(message) {
+        super(message, 'KEYCLOAK_ADMIN_ERROR');
+    }
+}
+exports.KeycloakAdminError = KeycloakAdminError;

package/dist/guards/auth.guard.d.ts

@@ -0,0 +1,25 @@
+import { KeycloakGrantService } from '../services/keycloak-grant.service';
+import { ResolvedTenantConfig } from '../interface/tenant-config.interface';
+import { TokenValidationService } from '../services/token-validation.service';
+import { BackchannelLogoutService } from '../services/backchannel-logout.service';
+import { KeycloakAuthConfig } from '../interface/keycloak-auth-options.interface';
+import { KeycloakMultiTenantService } from '../services/keycloak-multitenant.service';
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+/**
+ * An authentication guard. Will return a 401 unauthorized when it is unable to
+ * verify the JWT token or Bearer header is missing.
+ */
+export declare class AuthGuard implements CanActivate {
+    private singleTenant;
+    private keycloakOpts;
+    private multiTenant;
+    private tokenValidation;
+    private keycloakGrant;
+    private backchannelLogout;
+    private readonly logger;
+    private readonly reflector;
+    constructor(singleTenant: ResolvedTenantConfig, keycloakOpts: KeycloakAuthConfig, multiTenant: KeycloakMultiTenantService, tokenValidation: TokenValidationService, keycloakGrant: KeycloakGrantService, backchannelLogout: BackchannelLogoutService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    private validateToken;
+    private extractJwt;
+}

package/dist/guards/auth.guard.js

@@ -0,0 +1,176 @@
+"use strict";
+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 __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var AuthGuard_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthGuard = void 0;
+const util_1 = require("../util");
+const core_1 = require("@nestjs/core");
+const public_decorator_1 = require("../decorators/public.decorator");
+const internal_util_1 = require("../internal.util");
+const token_scopes_decorator_1 = require("../decorators/token-scopes.decorator");
+const keycloak_grant_service_1 = require("../services/keycloak-grant.service");
+const token_validation_service_1 = require("../services/token-validation.service");
+const backchannel_logout_service_1 = require("../services/backchannel-logout.service");
+const keycloak_multitenant_service_1 = require("../services/keycloak-multitenant.service");
+const common_1 = require("@nestjs/common");
+const constants_1 = require("../constants");
+/**
+ * An authentication guard. Will return a 401 unauthorized when it is unable to
+ * verify the JWT token or Bearer header is missing.
+ */
+let AuthGuard = AuthGuard_1 = class AuthGuard {
+    constructor(singleTenant, keycloakOpts, multiTenant, tokenValidation, keycloakGrant, backchannelLogout) {
+        this.singleTenant = singleTenant;
+        this.keycloakOpts = keycloakOpts;
+        this.multiTenant = multiTenant;
+        this.tokenValidation = tokenValidation;
+        this.keycloakGrant = keycloakGrant;
+        this.backchannelLogout = backchannelLogout;
+        this.logger = new common_1.Logger(AuthGuard_1.name);
+        this.reflector = new core_1.Reflector();
+    }
+    canActivate(context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            const isPublic = this.reflector.getAllAndOverride(public_decorator_1.META_PUBLIC, [
+                context.getClass(),
+                context.getHandler(),
+            ]);
+            // Extract request/response
+            const [request] = (0, internal_util_1.extractRequest)(context);
+            // if is not an HTTP request ignore this guard
+            if (!request) {
+                return true;
+            }
+            const jwt = this.extractJwt(request.headers);
+            const isJwtEmpty = jwt === null || jwt === undefined;
+            // Not a public route, require jwt
+            if (!isPublic && isJwtEmpty) {
+                this.logger.verbose('Empty jwt, unauthorized');
+                throw new common_1.UnauthorizedException();
+            }
+            // Public route, no jwt sent
+            if (isPublic && isJwtEmpty) {
+                return true;
+            }
+            this.logger.verbose(`Validating jwt [${jwt.substring(0, 20)}...]`);
+            const tenantConfig = yield (0, internal_util_1.useTenantConfig)(request, jwt, this.singleTenant, this.multiTenant, this.keycloakOpts);
+            const isValidToken = yield this.validateToken(tenantConfig, jwt);
+            if (isValidToken) {
+                // Attach user info object
+                request.user = (0, util_1.parseToken)(jwt);
+                // Attach raw access token JWT extracted from bearer
+                request.accessToken = jwt;
+                // Check back-channel logout revocation
+                const sid = (_a = request.user) === null || _a === void 0 ? void 0 : _a.sid;
+                const sub = (_b = request.user) === null || _b === void 0 ? void 0 : _b.sub;
+                const iat = (_c = request.user) === null || _c === void 0 ? void 0 : _c.iat;
+                if (this.backchannelLogout.isRevoked(sid, sub, iat)) {
+                    this.logger.verbose('Session or user has been revoked via back-channel logout');
+                    if (isPublic) {
+                        request.user = undefined;
+                        request.accessToken = undefined;
+                        return true;
+                    }
+                    throw new common_1.UnauthorizedException();
+                }
+                // Check @TokenScopes() decorator requirements
+                const requiredScopes = this.reflector.getAllAndOverride(token_scopes_decorator_1.META_TOKEN_SCOPES, [context.getClass(), context.getHandler()]);
+                if (requiredScopes && requiredScopes.length > 0) {
+                    const scopeClaim = (_d = request.user) === null || _d === void 0 ? void 0 : _d.scope;
+                    const grantedScopes = new Set(typeof scopeClaim === 'string' ? scopeClaim.split(' ') : []);
+                    const missing = requiredScopes.filter((s) => !grantedScopes.has(s));
+                    if (missing.length > 0) {
+                        this.logger.verbose(`Token missing required scopes: ${missing.join(', ')}`);
+                        throw new common_1.ForbiddenException(`Missing required token scopes: ${missing.join(', ')}`);
+                    }
+                }
+                this.logger.verbose('User authenticated', { user: request.user });
+                return true;
+            }
+            // Valid token should return, this time we warn
+            if (isPublic) {
+                this.logger.warn('A jwt token was retrieved but failed validation.');
+                request.user = undefined;
+                request.accessToken = undefined;
+                return true;
+            }
+            throw new common_1.UnauthorizedException();
+        });
+    }
+    validateToken(tenantConfig, jwt) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const tokenValidationMethod = this.keycloakOpts.tokenValidation || constants_1.TokenValidation.ONLINE;
+            this.logger.verbose(`Using token validation method: ${tokenValidationMethod.toUpperCase()}`);
+            try {
+                switch (tokenValidationMethod) {
+                    case constants_1.TokenValidation.ONLINE:
+                        try {
+                            yield this.keycloakGrant.createGrant({ access_token: jwt }, tenantConfig.realmUrl, tenantConfig.clientId);
+                        }
+                        catch (ex) {
+                            this.logger.warn(`Cannot validate access token: ${ex}`);
+                            return false;
+                        }
+                        return yield this.tokenValidation.validateOnline(jwt, tenantConfig.realmUrl, tenantConfig.clientId, tenantConfig.secret);
+                    case constants_1.TokenValidation.OFFLINE:
+                        return yield this.tokenValidation.validateOffline(jwt, tenantConfig.realmUrl, tenantConfig.clientId);
+                    case constants_1.TokenValidation.NONE:
+                        return true;
+                    default:
+                        this.logger.warn(`Unknown validation method: ${tokenValidationMethod}`);
+                        return false;
+                }
+            }
+            catch (ex) {
+                this.logger.warn(`Cannot validate access token: ${ex}`);
+            }
+            return false;
+        });
+    }
+    extractJwt(headers) {
+        const authorization = headers === null || headers === void 0 ? void 0 : headers.authorization;
+        if (!authorization || typeof authorization !== 'string') {
+            this.logger.verbose('No authorization header');
+            return null;
+        }
+        const auth = authorization.split(' ');
+        // We only allow bearer
+        if (auth[0].toLowerCase() !== 'bearer') {
+            this.logger.verbose('No bearer header');
+            return null;
+        }
+        return auth[1];
+    }
+};
+exports.AuthGuard = AuthGuard;
+exports.AuthGuard = AuthGuard = AuthGuard_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(constants_1.KEYCLOAK_INSTANCE)),
+    __param(1, (0, common_1.Inject)(constants_1.KEYCLOAK_AUTH_OPTIONS)),
+    __param(2, (0, common_1.Inject)(constants_1.KEYCLOAK_MULTITENANT_SERVICE)),
+    __metadata("design:paramtypes", [Object, Object, keycloak_multitenant_service_1.KeycloakMultiTenantService,
+        token_validation_service_1.TokenValidationService,
+        keycloak_grant_service_1.KeycloakGrantService,
+        backchannel_logout_service_1.BackchannelLogoutService])
+], AuthGuard);

package/dist/guards/resource.guard.d.ts

@@ -0,0 +1,26 @@
+import { KeycloakHttpService } from '../services/keycloak-http.service';
+import { ResolvedTenantConfig } from '../interface/tenant-config.interface';
+import { KeycloakAuthConfig } from '../interface/keycloak-auth-options.interface';
+import { KeycloakMultiTenantService } from '../services/keycloak-multitenant.service';
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+/**
+ * This adds a resource guard, which is policy enforcement by default is permissive.
+ * Only controllers annotated with `@Resource` and methods with `@Scopes`
+ * are handled by this guard.
+ */
+export declare class ResourceGuard implements CanActivate {
+    private singleTenant;
+    private keycloakOpts;
+    private multiTenant;
+    private keycloakHttp;
+    private readonly logger;
+    private readonly reflector;
+    constructor(singleTenant: ResolvedTenantConfig, keycloakOpts: KeycloakAuthConfig, multiTenant: KeycloakMultiTenantService, keycloakHttp: KeycloakHttpService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+    * Validate server-returned permissions against expected resource:scope pairs.
+    * Matches keycloak-connect enforcer.js handlePermissions logic.
+    */
+    private validatePermissionsLocally;
+    private resolveClaims;
+}