keycloak-express-middleware 6.3.2 → 6.3.3

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [6.3.3] - 2026-03-18
+
+### Added
+- Expanded test coverage for outbound helper APIs:
+  - `getServiceToken()` edge cases (`minValiditySeconds`, custom `cacheKey`, scope array normalization, per-scope cache isolation, missing `access_token` handling)
+  - `callProtectedApi()` edge cases (`passthrough`/`none` modes, invalid inputs, JSON body serialization, timeout abort, non-JSON and empty response handling, retry toggle behavior)
+- Added integration coverage for:
+  - service token retrieval and cache behavior against configured Keycloak test realm
+  - outbound helper call behavior in user mode and none mode
+  - token-claim decoding flow in `getTokenClaims`
+- Added OIDC negative-path tests for non-JSON token-endpoint errors and failed PKCE token exchange responses.
+
+### Changed
+- Updated deploy setup output in `test/docker-keycloak/setup-keycloak.js` to reflect the current automated bootstrap flow (no misleading manual secret-copy instruction in the default path).
+- Normalized formatting of `test/config/default.json`.
+
 ## [6.3.2] - 2026-03-18
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keycloak-express-middleware",
-  "version": "6.3.2",
+  "version": "6.3.3",
   "description": "Adapter API to integrate Node.js (Express) applications with Keycloak. Provides middleware for authentication, authorization, token validation, and route protection via OpenID Connect.",
   "main": "index.js",
   "typings": "index.d.ts",

package/test/config/default.json

@@ -10,6 +10,7 @@
       "realm": "express-middleware-test",
       "clientId": "express-middleware-test-client",
       "clientSecret": "test-client-secret",
-      "testUser": "test-user"    }
+      "testUser": "test-user"
+    }
   }
-}
+}

package/test/docker-keycloak/setup-keycloak.js

@@ -521,11 +521,11 @@ async function main() {
     
     log('\n✓ Setup complete!\n', 'green');
 
-    // === CLIENT SECRET RETRIEVAL INSTRUCTION ===
-    log('4. Copy the Secret value and update test/config/secrets.json and test/config/default.json', 'yellow');
-    log('   ("clientSecret" field under the "test" keycloak block)', 'yellow');
-    log('5. Re-run npm test', 'yellow');
-    log('\nIf you want to automate this, add a script to fetch the secret via Keycloak Admin API after deployment.\n', 'yellow');
+    // Test config bootstrap already creates local config files and test setup recreates realm/client.
+    log('4. Run npm test to bootstrap test config and sync realm/client/user automatically.', 'yellow');
+    log('   (test/helpers/ensure-test-config.js + test/helpers/keycloak-setup.js)', 'yellow');
+    log('5. Only update test/config/secrets.json manually if you intentionally changed credentials.', 'yellow');
+    log('   (adminPassword, clientSecret, testPassword)', 'yellow');
     
   } catch (err) {
     log(`\nSetup failed: ${err.message}\n`, 'red');

package/test/keycloak-integration.test.js

@@ -80,5 +80,72 @@ describe('Keycloak Integration - All Methods', function() {
     );
   });
 
+
+  it('should obtain a service token via client_credentials', async function() {
+    const result = await keycloak.getServiceToken({ scope: 'openid' });
+    assert(result.accessToken, 'should get access_token via client_credentials');
+    assert.strictEqual(result.source, 'fresh');
+    assert.strictEqual(typeof result.expiresIn, 'number');
+    assert(result.expiresIn > 0, 'expiresIn should be positive');
+  });
+
+  it('should return cached service token on second call', async function() {
+    // First call already made in previous test — same scope key hits cache
+    const a = await keycloak.getServiceToken({ scope: 'openid' });
+    const b = await keycloak.getServiceToken({ scope: 'openid' });
+    assert.strictEqual(b.source, 'cache');
+    assert.strictEqual(a.accessToken, b.accessToken);
+  });
+
+  it('should call Keycloak userinfo endpoint via callProtectedApi', async function() {
+    // Use a deterministic public endpoint and send user token in Authorization header.
+    const openidConfigUrl = `${config.baseUrl.replace(/\/$/, '')}/realms/${config.realm}/.well-known/openid-configuration`;
+
+    const result = await keycloak.callProtectedApi({
+      url: openidConfigUrl,
+      authMode: 'user',
+      userToken: tokens.access_token
+    });
+
+    assert.strictEqual(result.ok, true, `OpenID configuration call failed: ${JSON.stringify(result.data)}`);
+    assert(result.data.issuer, 'response should contain issuer');
+    assert.strictEqual(result.auth.mode, 'user');
+    assert.strictEqual(result.auth.retriedWithFreshToken, false);
+  });
+
+  it('should return 401 data with invalid token via callProtectedApi (none mode)', async function() {
+    const userInfoUrl = `${config.baseUrl.replace(/\/$/, '')}/realms/${config.realm}/protocol/openid-connect/userinfo`;
+
+    const result = await keycloak.callProtectedApi({
+      url: userInfoUrl,
+      authMode: 'none'  // no auth header → 401
+    });
+
+    assert.strictEqual(result.ok, false);
+    assert.strictEqual(result.status, 401);
+  });
+
+  it('should decode token claims with getTokenClaims after real login', function() {
+    // tokens.access_token is a JWT, decode payload and place it where getTokenClaims expects it.
+    const jwtPayloadPart = String(tokens.access_token || '').split('.')[1] || '';
+    const jsonPayload = Buffer.from(
+      jwtPayloadPart.replace(/-/g, '+').replace(/_/g, '/'),
+      'base64'
+    ).toString('utf8');
+    const decodedPayload = JSON.parse(jsonPayload);
+
+    const mockReq = {
+      kauth: {
+        grant: {
+          access_token: {
+            content: decodedPayload
+          }
+        }
+      }
+    };
+    const claims = keycloak.getTokenClaims(mockReq);
+    assert(claims.sub, 'should have sub claim');
+  });
+
   // Add more tests for middleware and utility methods as needed
 });

package/test/middleware-functions.test.js

@@ -749,4 +749,333 @@ describe('Middleware and Imperative Methods', function() {
       }
     });
   });
+
+    // ── getServiceToken edge cases ──────────────────────────────────────────
+
+    it('getServiceToken forces fresh fetch when token is within minValiditySeconds', async function() {
+      const adapter = buildAdapter();
+      let calls = 0;
+
+      adapter.loginWithCredentials = async () => {
+        calls += 1;
+        return {
+          access_token: `svc-token-${calls}`,
+          token_type: 'Bearer',
+          expires_in: 10,   // expires in 10 s
+          scope: 'openid'
+        };
+      };
+
+      // First fetch — stores token with ~10 s TTL
+      await adapter.getServiceToken({ scope: 'openid' });
+
+      // Request with minValiditySeconds=20 → cached token expires too soon → must refresh
+      const result = await adapter.getServiceToken({ scope: 'openid', minValiditySeconds: 20 });
+
+      assert.strictEqual(result.source, 'fresh');
+      assert.strictEqual(calls, 2, 'should refetch when token expires within minValiditySeconds');
+    });
+
+    it('getServiceToken uses custom cacheKey independently from default key', async function() {
+      const adapter = buildAdapter();
+      let calls = 0;
+
+      adapter.loginWithCredentials = async () => {
+        calls += 1;
+        return { access_token: `token-${calls}`, token_type: 'Bearer', expires_in: 300 };
+      };
+
+      const a = await adapter.getServiceToken({ scope: 'openid', cacheKey: 'my-key' });
+      const b = await adapter.getServiceToken({ scope: 'openid', cacheKey: 'my-key' }); // same key → cache
+      const c = await adapter.getServiceToken({ scope: 'openid' }); // default key → fresh
+
+      assert.strictEqual(a.source, 'fresh');
+      assert.strictEqual(b.source, 'cache');
+      assert.strictEqual(c.source, 'fresh');
+      assert.strictEqual(calls, 2);
+    });
+
+    it('getServiceToken joins scope array into space-separated string', async function() {
+      const adapter = buildAdapter();
+      let capturedScope;
+
+      adapter.loginWithCredentials = async (creds) => {
+        capturedScope = creds.scope;
+        return { access_token: 'tok', token_type: 'Bearer', expires_in: 300, scope: creds.scope };
+      };
+
+      await adapter.getServiceToken({ scope: ['openid', 'profile', 'email'] });
+      assert.strictEqual(capturedScope, 'openid profile email');
+    });
+
+    it('getServiceToken isolates cache entries per scope', async function() {
+      const adapter = buildAdapter();
+      let calls = 0;
+
+      adapter.loginWithCredentials = async (creds) => {
+        calls += 1;
+        return { access_token: `tok-${creds.scope}`, token_type: 'Bearer', expires_in: 300, scope: creds.scope };
+      };
+
+      const a = await adapter.getServiceToken({ scope: 'openid' });
+      const b = await adapter.getServiceToken({ scope: 'openid profile' });
+      const c = await adapter.getServiceToken({ scope: 'openid' }); // cache hit
+
+      assert.strictEqual(a.accessToken, 'tok-openid');
+      assert.strictEqual(b.accessToken, 'tok-openid profile');
+      assert.strictEqual(c.source, 'cache');
+      assert.strictEqual(calls, 2);
+    });
+
+    it('getServiceToken throws when token endpoint returns no access_token', async function() {
+      const adapter = buildAdapter();
+
+      adapter.loginWithCredentials = async () => ({ token_type: 'Bearer', expires_in: 300 });
+
+      await assert.rejects(
+        () => adapter.getServiceToken({ scope: 'openid' }),
+        /access_token/
+      );
+    });
+
+    // ── callProtectedApi edge cases ─────────────────────────────────────────
+
+    it('callProtectedApi throws when url is missing', async function() {
+      const adapter = buildAdapter();
+
+      await assert.rejects(
+        () => adapter.callProtectedApi({ authMode: 'none' }),
+        /url/i
+      );
+    });
+
+    it('callProtectedApi passthrough mode preserves existing Authorization header', async function() {
+      const adapter = buildAdapter();
+      const originalFetch = global.fetch;
+      let capturedAuth;
+
+      global.fetch = async (_url, options) => {
+        capturedAuth = options.headers.Authorization;
+        return {
+          ok: true, status: 200, statusText: 'OK',
+          headers: { forEach: () => {}, get: () => null },
+          text: async () => ''
+        };
+      };
+
+      try {
+        await adapter.callProtectedApi({
+          url: 'https://api.example.com/data',
+          authMode: 'passthrough',
+          headers: { Authorization: 'Bearer my-existing-token' }
+        });
+        assert.strictEqual(capturedAuth, 'Bearer my-existing-token');
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it('callProtectedApi none mode sends no Authorization header', async function() {
+      const adapter = buildAdapter();
+      const originalFetch = global.fetch;
+      let capturedHeaders;
+
+      global.fetch = async (_url, options) => {
+        capturedHeaders = options.headers;
+        return {
+          ok: true, status: 200, statusText: 'OK',
+          headers: { forEach: () => {}, get: () => null },
+          text: async () => ''
+        };
+      };
+
+      try {
+        await adapter.callProtectedApi({ url: 'https://api.example.com/data', authMode: 'none' });
+        assert.strictEqual(capturedHeaders.Authorization, undefined);
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it('callProtectedApi throws when authMode=user without userToken', async function() {
+      const adapter = buildAdapter();
+
+      await assert.rejects(
+        () => adapter.callProtectedApi({ url: 'https://api.example.com/data', authMode: 'user' }),
+        /userToken/i
+      );
+    });
+
+    it('callProtectedApi throws on unsupported authMode', async function() {
+      const adapter = buildAdapter();
+
+      await assert.rejects(
+        () => adapter.callProtectedApi({ url: 'https://api.example.com/data', authMode: 'magic' }),
+        /unsupported authMode/i
+      );
+    });
+
+    it('callProtectedApi serializes json body and sets content-type', async function() {
+      const adapter = buildAdapter();
+      const originalFetch = global.fetch;
+      let capturedBody, capturedContentType;
+
+      global.fetch = async (_url, options) => {
+        capturedBody = options.body;
+        capturedContentType = options.headers['content-type'];
+        return {
+          ok: true, status: 200, statusText: 'OK',
+          headers: { forEach: () => {}, get: () => 'application/json' },
+          text: async () => JSON.stringify({ ok: true })
+        };
+      };
+
+      try {
+        await adapter.callProtectedApi({
+          url: 'https://api.example.com/data',
+          method: 'POST',
+          authMode: 'none',
+          json: { foo: 'bar', num: 42 }
+        });
+        assert.strictEqual(capturedBody, JSON.stringify({ foo: 'bar', num: 42 }));
+        assert.strictEqual(capturedContentType, 'application/json');
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it('callProtectedApi skips retry when retryOnAuthError=false', async function() {
+      const adapter = buildAdapter();
+      const originalFetch = global.fetch;
+      let fetchCalls = 0;
+      let getTokenCalls = 0;
+
+      adapter.getServiceToken = async () => {
+        getTokenCalls += 1;
+        return { accessToken: 'tok', tokenType: 'Bearer', source: 'cache' };
+      };
+
+      global.fetch = async () => {
+        fetchCalls += 1;
+        return {
+          ok: false, status: 401, statusText: 'Unauthorized',
+          headers: { forEach: () => {}, get: () => null },
+          text: async () => 'Unauthorized'
+        };
+      };
+
+      try {
+        const result = await adapter.callProtectedApi({
+          url: 'https://api.example.com/data',
+          authMode: 'service',
+          retryOnAuthError: false
+        });
+        assert.strictEqual(result.status, 401);
+        assert.strictEqual(fetchCalls, 1, 'should not retry');
+        assert.strictEqual(result.auth.retriedWithFreshToken, false);
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it('callProtectedApi aborts request on timeout', async function() {
+      const adapter = buildAdapter();
+      const originalFetch = global.fetch;
+
+      global.fetch = async (_url, options) => {
+        return new Promise((_resolve, reject) => {
+          if (options.signal) {
+            options.signal.addEventListener('abort', () => {
+              const err = new Error('The operation was aborted');
+              err.name = 'AbortError';
+              reject(err);
+            });
+          }
+          // Never resolve — waits for abort
+        });
+      };
+
+      try {
+        await assert.rejects(
+          () => adapter.callProtectedApi({
+            url: 'https://api.example.com/slow',
+            authMode: 'none',
+            timeoutMs: 30
+          }),
+          (err) => err.name === 'AbortError' || /aborted/i.test(err.message)
+        );
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it('callProtectedApi returns text data for non-JSON response', async function() {
+      const adapter = buildAdapter();
+      const originalFetch = global.fetch;
+
+      global.fetch = async () => ({
+        ok: true, status: 200, statusText: 'OK',
+        headers: { forEach: () => {}, get: () => 'text/plain' },
+        text: async () => 'plain text response'
+      });
+
+      try {
+        const result = await adapter.callProtectedApi({
+          url: 'https://api.example.com/text',
+          authMode: 'none'
+        });
+        assert.strictEqual(result.data, 'plain text response');
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it('callProtectedApi returns null data for empty body', async function() {
+      const adapter = buildAdapter();
+      const originalFetch = global.fetch;
+
+      global.fetch = async () => ({
+        ok: true, status: 204, statusText: 'No Content',
+        headers: { forEach: () => {}, get: () => null },
+        text: async () => ''
+      });
+
+      try {
+        const result = await adapter.callProtectedApi({
+          url: 'https://api.example.com/delete',
+          method: 'DELETE',
+          authMode: 'none'
+        });
+        assert.strictEqual(result.status, 204);
+        assert.strictEqual(result.data, null);
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it('callProtectedApi auth.retriedWithFreshToken is false on first-attempt success', async function() {
+      const adapter = buildAdapter();
+      const originalFetch = global.fetch;
+
+      adapter.getServiceToken = async () => ({
+        accessToken: 'tok', tokenType: 'Bearer', source: 'cache'
+      });
+
+      global.fetch = async () => ({
+        ok: true, status: 200, statusText: 'OK',
+        headers: { forEach: () => {}, get: () => 'application/json' },
+        text: async () => JSON.stringify({ data: 1 })
+      });
+
+      try {
+        const result = await adapter.callProtectedApi({
+          url: 'https://api.example.com/data',
+          authMode: 'service'
+        });
+        assert.strictEqual(result.auth.retriedWithFreshToken, false);
+        assert.strictEqual(result.auth.mode, 'service');
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
 });

package/test/oidc-methods.test.js

@@ -313,6 +313,24 @@ describe('OIDC Methods', function() {
         global.fetch = originalFetch;
       }
     });
+
+    it('should throw on non-JSON error body from token endpoint', async function() {
+      const originalFetch = global.fetch;
+
+      global.fetch = async () => ({
+        ok: false,
+        text: async () => 'Service Unavailable'
+      });
+
+      try {
+        await adapter.loginWithCredentials({ grant_type: 'client_credentials' });
+        assert.fail('should have thrown');
+      } catch (error) {
+        assert(error.message.length > 0, 'should throw a non-empty error');
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
   });
 
   describe('loginPKCE()', function() {
@@ -410,5 +428,33 @@ describe('OIDC Methods', function() {
         global.fetch = originalFetch;
       }
     });
+
+    it('should throw on failed HTTP response from token endpoint', async function() {
+      const originalFetch = global.fetch;
+
+      global.fetch = async () => ({
+        ok: false,
+        text: async () => JSON.stringify({
+          error: 'invalid_grant',
+          error_description: 'Code not valid'
+        })
+      });
+
+      try {
+        await adapter.loginPKCE({
+          code: 'expired-code',
+          redirect_uri: 'https://app.example.com/callback',
+          code_verifier: 'verifier-123'
+        });
+        assert.fail('should have thrown');
+      } catch (error) {
+        assert(
+          error.message.includes('invalid_grant') || error.message.includes('Code not valid') || error.message.includes('failed'),
+          `unexpected error: ${error.message}`
+        );
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
   });
 });

package/test/package-lock.json

@@ -23,7 +23,7 @@
       }
     },
     "..": {
-      "version": "6.1.3",
+      "version": "6.3.2",
       "license": "MIT",
       "dependencies": {
         "express-session": "^1.19.0",