keycloak-api-manager 6.0.0 → 6.0.2

package/index.js

@@ -1,5 +1,22 @@
+
+/**
+ * **************************************************************************************************
+ * Keycloak API Manager - Main Entry Point
+ *
+ * This module provides a centralized interface for managing Keycloak administrative resources via the REST Admin API.
+ * It exposes methods for client configuration, token handling, and wiring all resource handlers.
+ *
+ * Each handler in Handlers/ encapsulates logic for a specific Keycloak resource (users, roles, groups, etc.).
+ *
+ * NOTE: OIDC authentication functions are deprecated and have been moved to keycloak-express-middleware.
+ * **************************************************************************************************
+ */
 const KeycloakAdminClient = require('@keycloak/keycloak-admin-client').default;
 
+
+/**
+ * Resource handler registry. Each key represents a Keycloak resource and maps to its handler module.
+ */
 const handlerRegistry = {
     realms: require('./Handlers/realmsHandler'),
     users: require('./Handlers/usersHandler'),
@@ -17,17 +34,33 @@ const handlerRegistry = {
     serverInfo: require('./Handlers/serverInfoHandler')
 };
 
+
+// Keycloak Admin client instance
 let kcAdminClient = null;
+// Interval ID for automatic token refresh
 let tokenRefreshInterval = null;
+// Current runtime configuration
 let runtimeConfig = null;
+// Authentication payload used for token refresh
 let authPayload = null;
 
+
+/**
+ * Ensures the client is configured before executing operations.
+ * Throws an error when configuration is missing.
+ */
 function assertConfigured() {
     if (!kcAdminClient || !runtimeConfig) {
         throw new Error('Keycloak Admin Client is not configured. Call configure() first.');
     }
 }
 
+
+/**
+ * Normalizes the baseUrl by removing a trailing slash, if present.
+ * @param {string} baseUrl
+ * @returns {string}
+ */
 function toBaseUrl(baseUrl) {
     if (!baseUrl || typeof baseUrl !== 'string') {
         throw new Error('Invalid baseUrl. It must be a non-empty string.');
@@ -35,6 +68,10 @@ function toBaseUrl(baseUrl) {
     return baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
 }
 
+
+/**
+ * Binds all resource handlers by injecting the configured Keycloak client and exporting the modules.
+ */
 function bindHandlers() {
     Object.entries(handlerRegistry).forEach(([name, handler]) => {
         handler.setKcAdminClient(kcAdminClient);
@@ -42,6 +79,10 @@ function bindHandlers() {
     });
 }
 
+
+/**
+ * Stops and resets the token refresh timer.
+ */
 function clearRefreshTimer() {
     if (tokenRefreshInterval) {
         clearInterval(tokenRefreshInterval);
@@ -49,6 +90,11 @@ function clearRefreshTimer() {
     }
 }
 
+
+/**
+ * Starts the automatic access token refresh timer.
+ * @param {number} intervalMs - interval in milliseconds
+ */
 function startRefreshTimer(intervalMs) {
     clearRefreshTimer();
 
@@ -65,6 +111,25 @@ function startRefreshTimer(intervalMs) {
     }
 }
 
+/**
+ * Initializes and authenticates the Keycloak Admin Client. Must be called before using any handler.
+ * Supports password and client_credentials grant types.
+ * Starts automatic token refresh and propagates the configured client to all handlers.
+ *
+ * @param {Object} adminClientCredentials - Credentials and configuration object:
+ *   - baseUrl {string} Keycloak server base URL
+ *   - realmName {string} Realm name
+ *   - clientId {string} Client ID
+ *   - clientSecret {string} (optional) Secret for client_credentials
+ *   - username {string} (optional) Admin username
+ *   - password {string} (optional) Admin password
+ *   - grantType {string} ("password" | "client_credentials")
+ *   - tokenLifeSpan {number} (optional) Token refresh interval (seconds)
+ *   - ... Other OAuth2 parameters
+ * @returns {Promise<void>} Promise resolved when configuration is complete
+ * @example
+ * await KeycloakManager.configure({ baseUrl, realmName, clientId, clientSecret, grantType: 'client_credentials' })
+ */
 exports.configure = async function configure(adminClientCredentials = {}) {
     const {
         baseUrl,
@@ -89,6 +154,8 @@ exports.configure = async function configure(adminClientCredentials = {}) {
         realmName
     });
 
+    // Guard against null/empty refresh token updates from upstream client internals.
+    // Without this, some refresh paths can keep a stale token value in memory.
     const originalSetRefreshToken = kcAdminClient.setRefreshToken?.bind(kcAdminClient);
     if (originalSetRefreshToken) {
         kcAdminClient.setRefreshToken = (token) => {
@@ -100,6 +167,7 @@ exports.configure = async function configure(adminClientCredentials = {}) {
         };
     }
 
+    // Keep a canonical auth payload so the refresh timer can reuse the same grant context.
     authPayload = {
         clientId,
         ...(clientSecret ? { clientSecret } : {}),
@@ -107,6 +175,8 @@ exports.configure = async function configure(adminClientCredentials = {}) {
     };
     await kcAdminClient.auth(authPayload);
 
+    // Refresh midway through the configured lifespan to reduce expiration race conditions.
+    // Fallback to 30s when tokenLifeSpan is omitted/invalid.
     const intervalMs = Number.isFinite(Number(tokenLifeSpan)) && Number(tokenLifeSpan) > 0
         ? (Number(tokenLifeSpan) * 1000) / 2
         : 30000;
@@ -115,10 +185,40 @@ exports.configure = async function configure(adminClientCredentials = {}) {
     bindHandlers();
 };
 
+
+/**
+ * Updates Keycloak client runtime configuration without re-initializing the session or re-authenticating.
+ * Allows switching realm, baseUrl, or HTTP request options (requestConfig) at runtime.
+ *
+ * @param {Object} overrides - Configuration overrides object.
+ * @param {string} [overrides.realmName] - Changes the target realm for all subsequent calls.
+ * @param {string} [overrides.baseUrl] - Changes the Keycloak server base URL.
+ * @param {object} [overrides.requestConfig] - HTTP request option overrides (e.g., timeout, custom headers). These options are passed internally to the HTTP client used by keycloak-admin-client (typically Axios).
+ * @returns {void}
+ *
+ * @example
+ * // Change only the realm
+ * KeycloakManager.setConfig({ realmName: 'my-app' });
+ *
+ * // Change realm and add custom request headers
+ * KeycloakManager.setConfig({
+ *   realmName: 'my-realm',
+ *   requestConfig: {
+ *     timeout: 10000,
+ *     headers: { 'X-Custom-Header': 'value' }
+ *   }
+ * });
+ *
+ * // Change baseUrl (e.g., for different environments)
+ * KeycloakManager.setConfig({ baseUrl: 'https://keycloak-alt.example.com' });
+ *
+ * @note Does not perform login/token refresh. It only updates runtime context. The token remains valid if compatible with the new realm.
+ */
 exports.setConfig = function setConfig(configToOverride = {}) {
     assertConfigured();
     kcAdminClient.setConfig(configToOverride);
 
+    // Keep local runtimeConfig aligned with client overrides used by helper methods.
     runtimeConfig = {
         ...runtimeConfig,
         ...(configToOverride.baseUrl ? { baseUrl: toBaseUrl(configToOverride.baseUrl) } : {}),
@@ -126,6 +226,16 @@ exports.setConfig = function setConfig(configToOverride = {}) {
     };
 };
 
+
+/**
+ * Returns the current access and refresh tokens.
+ * Useful for debugging or passing the token to other services.
+ * The token is automatically refreshed by the internal timer.
+ *
+ * @returns {{ accessToken: string, refreshToken: string }}
+ * @example
+ * const { accessToken } = KeycloakManager.getToken();
+ */
 exports.getToken = function getToken() {
     assertConfigured();
     return {
@@ -134,20 +244,40 @@ exports.getToken = function getToken() {
     };
 };
 
+
+/**
+ * Stops the automatic token refresh timer and releases resources.
+ * Call this before shutting down the application to avoid dangling processes.
+ *
+ * @returns {void}
+ * @example
+ * KeycloakManager.stop();
+ */
 exports.stop = function stop() {
     clearRefreshTimer();
 };
 
+
+/**
+ * Executes a direct request to the Keycloak OIDC token endpoint.
+ * Used internally for password, client_credentials, authorization_code (PKCE), and other grant types.
+ *
+ * @param {Object} credentials - OAuth2 parameters (grant_type, username, password, code, etc.)
+ * @returns {Promise<Object>} Token endpoint response (access_token, refresh_token, etc.)
+ * @throws {Error} If the request fails
+ */
 async function requestOidcToken(credentials = {}) {
     assertConfigured();
 
     const body = new URLSearchParams();
+    // Serialize only defined values to avoid sending "undefined"/"null" to Keycloak.
     Object.entries(credentials).forEach(([key, value]) => {
         if (value !== undefined && value !== null) {
             body.append(key, String(value));
         }
     });
 
+    // Apply runtime client credentials as defaults unless explicitly overridden.
     if (runtimeConfig.clientId && !body.has('client_id')) {
         body.append('client_id', runtimeConfig.clientId);
     }
@@ -167,6 +297,7 @@ async function requestOidcToken(credentials = {}) {
     );
 
     const responseText = await response.text();
+    // Keycloak usually returns JSON; keep empty-body responses safe.
     const payload = responseText ? JSON.parse(responseText) : {};
 
     if (!response.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keycloak-api-manager",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "description": "Enhanced Node.js wrapper for Keycloak Admin REST API. Professional alternative to @keycloak/keycloak-admin-client with advanced features, bug fixes, automatic token refresh, Organizations API support, fine-grained permissions, and comprehensive resource management. Battle-tested with 113+ integration tests.",
   "main": "index.js",
   "scripts": {

package/test/helpers/config.js

@@ -79,8 +79,8 @@ function loadConfig() {
 }
 
 /**
- * Inizializza il client Keycloak admin
- * Aspetta che Keycloak sia pronto prima di connettersi
+ * Initializes the Keycloak admin client.
+ * Waits until Keycloak is ready before connecting.
  */
 async function initializeAdminClient() {
   if (adminClient) {
@@ -90,6 +90,7 @@ async function initializeAdminClient() {
   // Load configuration (after local.json has been created from Docker)
   const config = loadConfig();
 
+  // Retry loop is intentionally generous to tolerate container cold-start time.
   let retries = 30;
   let lastError;
 
@@ -113,9 +114,11 @@ async function initializeAdminClient() {
       lastError = err;
       retries--;
       if (retries > 0) {
+        // Keycloak may still be booting; wait and retry.
         console.log(`Waiting for Keycloak... (${retries} retries left)`);
         await delay(2000);
       } else {
+        // Last attempt: print as much OAuth2 context as possible for diagnostics.
         console.error('OAuth2 Error Details:', {
           message: err.message,
           response: err.response?.data,
@@ -130,21 +133,22 @@ async function initializeAdminClient() {
 }
 
 /**
- * Crea il realm di test
+ * Creates the test realm.
  */
 async function setupTestRealm() {
   const client = await initializeAdminClient();
   const config = loadConfig();
 
-  // Switcha a master realm per creare il test realm
+  // Switch to the master realm to create the test realm
   client.realmName = 'master';
 
   try {
-    // Controlla se il realm esiste già
+    // Check if the realm already exists
     const realms = await client.realms.find();
     const realmExists = realms.some((r) => r.realm === config.realmName);
 
     if (!realmExists) {
+      // Keep realm defaults explicit so tests behave consistently across environments.
       await client.realms.create({
         realm: config.realmName,
         displayName: 'Test Realm',
@@ -159,6 +163,7 @@ async function setupTestRealm() {
       console.log(`✓ Test realm '${config.realmName}' already exists`);
     }
   } catch (err) {
+    // 409 means the realm already exists, which is acceptable for idempotent setup.
     if (err.response?.status === 409) {
       console.log(`✓ Test realm '${config.realmName}' already exists`);
     } else {
@@ -166,12 +171,12 @@ async function setupTestRealm() {
     }
   }
 
-  // Switcha back al test realm
+  // Switch back to the test realm
   client.realmName = config.realmName;
 }
 
 /**
- * Pulisce il realm di test
+ * Cleans up the test realm.
  */
 async function cleanupTestRealm() {
   if (!adminClient) return;
@@ -183,6 +188,7 @@ async function cleanupTestRealm() {
     await adminClient.realms.del({ realm: config.realmName });
     console.log(`✓ Test realm '${config.realmName}' deleted`);
   } catch (err) {
+    // Ignore not-found during cleanup to keep teardown idempotent.
     if (err.response?.status !== 404) {
       console.warn(`Warning: Failed to delete test realm: ${err.message}`);
     }
@@ -190,7 +196,7 @@ async function cleanupTestRealm() {
 }
 
 /**
- * Ritorna il client admin configurato e autenticato
+ * Returns the configured and authenticated admin client.
  */
 function getAdminClient() {
   if (!adminClient) {
@@ -200,7 +206,7 @@ function getAdminClient() {
 }
 
 /**
- * Reset del client (principalmente per i test)
+ * Resets the admin client (mainly for tests).
  */
 function resetAdminClient() {
   adminClient = null;

package/test-output.log

@@ -1,72 +0,0 @@
-
-> keycloak-api-manager@4.1.0 test
-> npm --prefix test install && npm --prefix test test
-
-
-up to date, audited 260 packages in 2s
-
-48 packages are looking for funding
-  run `npm fund` for details
-
-12 vulnerabilities (3 low, 3 moderate, 4 high, 2 critical)
-
-To address all issues possible (including breaking changes), run:
-  npm audit fix --force
-
-Some issues need review, and may require choosing
-a different dependency.
-
-Run `npm audit` for details.
-
-> keycloak-api-manager-tests@1.0.0 test
-> NODE_ENV=test NODE_PATH=./node_modules mocha --exit
-
-
- Exception during run: /Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/Handlers/userProfileHandler.js:79
-        body: JSON.strasync function(filter) {
-                            ^^^^^^^^
-
-SyntaxError: Unexpected token 'function'
-    at wrapSafe (node:internal/modules/cjs/loader:1515:18)
-    at Module._compile (node:internal/modules/cjs/loader:1537:20)
-    at Object..js (node:internal/modules/cjs/loader:1708:10)
-    at Module.load (node:internal/modules/cjs/loader:1318:32)
-    at Function._load (node:internal/modules/cjs/loader:1128:12)
-    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
-    at wrapModuleLoad (node:internal/modules/cjs/loader:219:24)
-    at Module.require (node:internal/modules/cjs/loader:1340:12)
-    at require (node:internal/modules/helpers:138:16)
-    at Object.<anonymous> (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/index.js:15:24)
-    at Module._compile (node:internal/modules/cjs/loader:1565:14)
-    at Object..js (node:internal/modules/cjs/loader:1708:10)
-    at Module.load (node:internal/modules/cjs/loader:1318:32)
-    at Function._load (node:internal/modules/cjs/loader:1128:12)
-    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
-    at wrapModuleLoad (node:internal/modules/cjs/loader:219:24)
-    at Module.require (node:internal/modules/cjs/loader:1340:12)
-    at require (node:internal/modules/helpers:138:16)
-    at Object.<anonymous> (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/enableServerFeatures.js:47:25)
-    at Module._compile (node:internal/modules/cjs/loader:1565:14)
-    at Object..js (node:internal/modules/cjs/loader:1708:10)
-    at Module.load (node:internal/modules/cjs/loader:1318:32)
-    at Function._load (node:internal/modules/cjs/loader:1128:12)
-    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
-    at wrapModuleLoad (node:internal/modules/cjs/loader:219:24)
-    at Module.require (node:internal/modules/cjs/loader:1340:12)
-    at require (node:internal/modules/helpers:138:16)
-    at Object.<anonymous> (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/setup.js:29:30)
-    at Module._compile (node:internal/modules/cjs/loader:1565:14)
-    at Object..js (node:internal/modules/cjs/loader:1708:10)
-    at Module.load (node:internal/modules/cjs/loader:1318:32)
-    at Function._load (node:internal/modules/cjs/loader:1128:12)
-    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
-    at wrapModuleLoad (node:internal/modules/cjs/loader:219:24)
-    at cjsLoader (node:internal/modules/esm/translators:263:5)
-    at ModuleWrap.<anonymous> (node:internal/modules/esm/translators:196:7)
-    at ModuleJob.run (node:internal/modules/esm/module_job:271:25)
-    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:547:26)
-    at async formattedImport (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/node_modules/mocha/lib/nodejs/esm-utils.js:9:14)
-    at async exports.requireOrImport (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/node_modules/mocha/lib/nodejs/esm-utils.js:42:28)
-    at async exports.loadFilesAsync (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/node_modules/mocha/lib/nodejs/esm-utils.js:100:20)
-    at async singleRun (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/node_modules/mocha/lib/cli/run-helpers.js:162:3)
-    at async exports.handler (/Users/Alessandro/Src/WorkSpace/WorkspaceDemo/Idealia/Keyclock/keycloak-api-manager/test/node_modules/mocha/lib/cli/run.js:375:5)