@decaf-ts/integrations 0.2.1 → 0.3.0

package/lib/types/nest/keycloakAuthHandler.d.cts

@@ -5,9 +5,9 @@
  * Extends the framework-agnostic {@link AuthHandler} from `@decaf-ts/for-http/server`.
  *
  * Only overrides the two extension points:
- * - {@link extractFromAuth} — decodes the JWT and returns auth data (no validation).
+ * - {@link KeycloakAuthHandler.extractFromAuth} — decodes the JWT and returns auth data (no validation).
  *   Returns empty data for public routes without requiring a token.
- * - {@link validate} — validates the JWT via {@link AuthService.assertValidToken},
+ * - {@link KeycloakAuthHandler.validate} — validates the JWT via {@link AuthService.assertValidToken},
  *   then delegates to the base class for route-level and model-level role checks.
  *   Skips entirely for public routes.
  *
@@ -17,8 +17,9 @@
 import type { Constructor } from "@decaf-ts/decoration";
 import { Context, ContextualArgs } from "@decaf-ts/core";
 import { AuthHandler, AuthData } from "@decaf-ts/for-http/server";
-import { AuthService } from "./authService.d.cts";
+import { AuthService, type AuthServiceOptions } from "./authService.d.cts";
 import type { AuthExecutionContextLike } from "./types.d.cts";
+import { getClientRoles } from "./utils.d.cts";
 /**
  * Auth data returned by {@link KeycloakAuthHandler.extractFromAuth}.
  *
@@ -32,8 +33,15 @@ export interface KeycloakAuthData extends AuthData {
     isPublic: boolean;
 }
 export declare class KeycloakAuthHandler extends AuthHandler<AuthExecutionContextLike, Context, KeycloakAuthData> {
-    private readonly authService;
-    constructor(authService?: AuthService);
+    /**
+     * @param authService  An {@link AuthService} configured with JWKS verification
+     *                     options.  When omitted a default decode-only service is
+     *                     used.
+     * @param authServiceOptions  Convenience: if `authService` is omitted, these
+     *                     options are used to construct one.
+     */
+    constructor(authService?: AuthService, authServiceOptions?: AuthServiceOptions);
+    protected readonly authService: AuthService;
     protected extractFromAuth(ctx: AuthExecutionContextLike): KeycloakAuthData;
     /**
      * Validates the JWT against the Keycloak instance (signature, expiry, etc.)
@@ -42,3 +50,4 @@ export declare class KeycloakAuthHandler extends AuthHandler<AuthExecutionContex
      */
     protected validate(data: KeycloakAuthData, routeRoles: string[] | undefined, model: string | Constructor, ...args: ContextualArgs<Context>): Promise<void>;
 }
+export { getClientRoles };

package/lib/types/nest/keycloakAuthHandler.d.mts

@@ -5,9 +5,9 @@
  * Extends the framework-agnostic {@link AuthHandler} from `@decaf-ts/for-http/server`.
  *
  * Only overrides the two extension points:
- * - {@link extractFromAuth} — decodes the JWT and returns auth data (no validation).
+ * - {@link KeycloakAuthHandler.extractFromAuth} — decodes the JWT and returns auth data (no validation).
  *   Returns empty data for public routes without requiring a token.
- * - {@link validate} — validates the JWT via {@link AuthService.assertValidToken},
+ * - {@link KeycloakAuthHandler.validate} — validates the JWT via {@link AuthService.assertValidToken},
  *   then delegates to the base class for route-level and model-level role checks.
  *   Skips entirely for public routes.
  *
@@ -17,8 +17,9 @@
 import type { Constructor } from "@decaf-ts/decoration";
 import { Context, ContextualArgs } from "@decaf-ts/core";
 import { AuthHandler, AuthData } from "@decaf-ts/for-http/server";
-import { AuthService } from "./authService.d.mts";
+import { AuthService, type AuthServiceOptions } from "./authService.d.mts";
 import type { AuthExecutionContextLike } from "./types.d.mts";
+import { getClientRoles } from "./utils.d.mts";
 /**
  * Auth data returned by {@link KeycloakAuthHandler.extractFromAuth}.
  *
@@ -32,8 +33,15 @@ export interface KeycloakAuthData extends AuthData {
     isPublic: boolean;
 }
 export declare class KeycloakAuthHandler extends AuthHandler<AuthExecutionContextLike, Context, KeycloakAuthData> {
-    private readonly authService;
-    constructor(authService?: AuthService);
+    /**
+     * @param authService  An {@link AuthService} configured with JWKS verification
+     *                     options.  When omitted a default decode-only service is
+     *                     used.
+     * @param authServiceOptions  Convenience: if `authService` is omitted, these
+     *                     options are used to construct one.
+     */
+    constructor(authService?: AuthService, authServiceOptions?: AuthServiceOptions);
+    protected readonly authService: AuthService;
     protected extractFromAuth(ctx: AuthExecutionContextLike): KeycloakAuthData;
     /**
      * Validates the JWT against the Keycloak instance (signature, expiry, etc.)
@@ -42,3 +50,4 @@ export declare class KeycloakAuthHandler extends AuthHandler<AuthExecutionContex
      */
     protected validate(data: KeycloakAuthData, routeRoles: string[] | undefined, model: string | Constructor, ...args: ContextualArgs<Context>): Promise<void>;
 }
+export { getClientRoles };

package/lib/types/nest/keycloakModule.d.cts

@@ -3,13 +3,13 @@
  * @summary Nest module wiring for Keycloak auth.
  * @description Exposes the Nest module setup for the integration auth service and Keycloak handler.
  */
-import { AuthService } from "./authService.d.cts";
+import { AuthService, type AuthServiceOptions } from "./authService.d.cts";
 import { KeycloakAuthHandler } from "./keycloakAuthHandler.d.cts";
 export declare class KeycloakModule {
     readonly authService: AuthService;
     readonly authHandler: KeycloakAuthHandler;
-    constructor(authService?: AuthService, authHandler?: KeycloakAuthHandler);
-    static create(): KeycloakModule;
+    constructor(authService: AuthService, authHandler: KeycloakAuthHandler);
+    static create(options?: AuthServiceOptions): KeycloakModule;
 }
 export declare class AuthModule extends KeycloakModule {
 }

package/lib/types/nest/keycloakModule.d.mts

@@ -3,13 +3,13 @@
  * @summary Nest module wiring for Keycloak auth.
  * @description Exposes the Nest module setup for the integration auth service and Keycloak handler.
  */
-import { AuthService } from "./authService.d.mts";
+import { AuthService, type AuthServiceOptions } from "./authService.d.mts";
 import { KeycloakAuthHandler } from "./keycloakAuthHandler.d.mts";
 export declare class KeycloakModule {
     readonly authService: AuthService;
     readonly authHandler: KeycloakAuthHandler;
-    constructor(authService?: AuthService, authHandler?: KeycloakAuthHandler);
-    static create(): KeycloakModule;
+    constructor(authService: AuthService, authHandler: KeycloakAuthHandler);
+    static create(options?: AuthServiceOptions): KeycloakModule;
 }
 export declare class AuthModule extends KeycloakModule {
 }

package/lib/types/nest/utils.d.cts

@@ -7,5 +7,14 @@ import type { KeycloakAccessTokenPayload, KeycloakUser } from "./types.d.cts";
 export declare const DECAF_ADAPTER_OPTIONS: unique symbol;
 export declare function getTokenPayload(jwt: string): KeycloakAccessTokenPayload | null;
 export declare function extractKeycloakRoles(payload: KeycloakAccessTokenPayload | null): string[];
+/**
+ * Extracts roles from the `resource_access` claim only, optionally excluding
+ * specified client IDs (e.g. `"account"`).  Unlike {@link extractKeycloakRoles}
+ * this does NOT include `realm_access.roles`.
+ *
+ * @param payload   The decoded JWT payload.
+ * @param excluded  Client IDs to skip.  @default ["account"]
+ */
+export declare function getClientRoles(payload: KeycloakAccessTokenPayload | null, excluded?: string[]): string[];
 export declare function getUser(jwt: string): KeycloakUser | undefined;
 export declare function getRealmFromIssuer(jwt: string): string;

package/lib/types/nest/utils.d.mts

@@ -7,5 +7,14 @@ import type { KeycloakAccessTokenPayload, KeycloakUser } from "./types.d.mts";
 export declare const DECAF_ADAPTER_OPTIONS: unique symbol;
 export declare function getTokenPayload(jwt: string): KeycloakAccessTokenPayload | null;
 export declare function extractKeycloakRoles(payload: KeycloakAccessTokenPayload | null): string[];
+/**
+ * Extracts roles from the `resource_access` claim only, optionally excluding
+ * specified client IDs (e.g. `"account"`).  Unlike {@link extractKeycloakRoles}
+ * this does NOT include `realm_access.roles`.
+ *
+ * @param payload   The decoded JWT payload.
+ * @param excluded  Client IDs to skip.  @default ["account"]
+ */
+export declare function getClientRoles(payload: KeycloakAccessTokenPayload | null, excluded?: string[]): string[];
 export declare function getUser(jwt: string): KeycloakUser | undefined;
 export declare function getRealmFromIssuer(jwt: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decaf-ts/integrations",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.mts",
@@ -214,11 +214,11 @@
     "reset": "rm -rf * && git checkout . && git pull && npm run do-install",
     "build": "build-scripts --dev",
     "build:prod": "build-scripts --prod",
-    "test": "npm run build && NODE_OPTIONS=\"--experimental-vm-modules\" jest --runInBand --coverage --detectOpenHandles",
+    "test": "npm run build && KEYCLOAK_HOST=172.20.0.4:8080 NODE_OPTIONS=\"--experimental-vm-modules\" jest --runInBand --coverage --detectOpenHandles",
     "test:unit": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --testPathPatterns=\"/tests/unit\" --passWithNoTests --detectOpenHandles",
-    "test:integration": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --testPathPatterns=\"/tests/(integration)\" --passWithNoTests --detectOpenHandles",
-    "test:e2e": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --testPathPatterns=\"/tests/(e2e)\" --passWithNoTests --detectOpenHandles",
-    "test:all": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --runInBand --testPathPatterns=\"/tests\" --passWithNoTests",
+    "test:integration": "KEYCLOAK_HOST=172.20.0.4:8080 NODE_OPTIONS=\"--experimental-vm-modules\" jest --testPathPatterns=\"/tests/(integration)\" --passWithNoTests --detectOpenHandles",
+    "test:e2e": "KEYCLOAK_HOST=172.20.0.4:8080 NODE_OPTIONS=\"--experimental-vm-modules\" jest --testPathPatterns=\"/tests/(e2e)\" --passWithNoTests --detectOpenHandles",
+    "test:all": "KEYCLOAK_HOST=172.20.0.4:8080 NODE_OPTIONS=\"--experimental-vm-modules\" jest --runInBand --testPathPatterns=\"/tests\" --passWithNoTests",
     "test:circular": "dpdm -T --no-warning --no-tree ./src/index.ts",
     "coverage": "rimraf ./workdocs/reports/data/*.json && npm run test:all -- --coverage --config=./workdocs/reports/jest.coverage.config.cjs",
     "lint": "eslint .",
@@ -254,8 +254,10 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
+    "@decaf-ts/cli": "latest",
     "@decaf-ts/for-http": "latest",
-    "@decaf-ts/for-nest": "^0.11.2-refactor",
+    "@decaf-ts/for-nano": "latest",
+    "@decaf-ts/for-nest": "0.11.2-refactor.5",
     "@decaf-ts/utils": "latest",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
@@ -269,11 +271,19 @@
     "supertest": "^7.0.0"
   },
   "peerDependencies": {
-    "@decaf-ts/for-http": ">=0.18.0"
+    "@decaf-ts/for-http": "latest",
+    "@decaf-ts/for-nest": "0.11.2-refactor.5",
+    "jose": ">=5.0.0"
   },
   "peerDependenciesMeta": {
     "@decaf-ts/for-http": {
       "optional": true
+    },
+    "@decaf-ts/for-nest": {
+      "optional": true
+    },
+    "jose": {
+      "optional": true
     }
   },
   "overrides": {