feat: improve authenticateClient by avoiding unnecessary token creation

[wilsonrivera]

The goal of this PR is to avoid creating Keycloak access tokens every time we call authenticateClient.

To achieve this we are taking a look at the existing token (if any) and, if that token still valid, we don't do anything, however, if there is a refresh token, we try to refresh the current access token with it and if everything fails or is unavailable, we fallback to the original flow or creating a new access token.

Summary by CodeRabbit

• Bug Fixes

  • Avoids unnecessary re-authentication by checking token expiration before requesting new credentials.

• New Features

  • Automatically refreshes sessions when a valid refresh token is available.

• Behavior

  • Falls back to the existing sign-in flow if tokens are invalid or refresh fails.
  • Gracefully handles token decode errors and proceeds with the standard sign-in process.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Checklist

• I have discussed my proposed changes in an issue and have received approval to proceed.
• I have followed the coding standards of the project.
• Tests or benchmarks have been added or updated.
• Documentation has been updated on https://github.com/wundergraph/cosmo-docs.
• I have read the Contributors Guide.

[coderabbitai]

Walkthrough

Checks existing Keycloak access tokens by decoding the JWT to read the exp claim; if token is valid, skips re-authentication; if expired and a refresh token exists, performs a refresh_token grant; otherwise falls back to the password grant. Decoding errors are ignored and do not block fallback.

Changes

Cohort / File(s)	Summary
Keycloak authentication token handling controlplane/src/core/services/Keycloak.ts	Added decodeJwt import from jose. In authenticateClient, decode existing access tokens to check exp; return early if token present and not expired; if expired and a refresh token exists, call the refresh_token grant to obtain new tokens; on decode failure proceed to existing flows. Password grant retained as fallback.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• fix(controlplane): handle authentication errors correctly #2354: Modifies the same authenticateClient method in controlplane/src/core/services/Keycloak.ts, adjusting error handling around authentication flows.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and concisely summarizes the main change: improving authenticateClient by avoiding unnecessary token creation, which matches the primary objective of the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @controlplane/src/core/services/Keycloak.ts:
- Around line 41-48: The current check in the Keycloak token validation treats
tokens missing an exp claim as valid indefinitely; update the logic in the
Keycloak method that inspects this.client.accessToken (where decodeJwt is used)
so that absence of exp does NOT cause an early return—only return early when exp
exists and exp*1000 > Date.now(); if exp is missing or expired, fall through to
re-authenticate. Ensure you only change the conditional that now reads something
like `if (!exp || exp * 1000 > Date.now()) return;` to require exp to be present
and valid (e.g., `if (exp && exp * 1000 > Date.now()) return;`), so tokens
without expiration force re-authentication.

🧹 Nitpick comments (2)

controlplane/src/core/services/Keycloak.ts (2)

50-58: Token refresh logic looks correct.

The refresh token flow properly uses the refresh_token grant type and maintains consistency with the password flow by using the same admin-cli client ID.

Consider adding logging when token refresh succeeds to aid in debugging and monitoring:

🔎 Suggested logging enhancement

         if (this.client.refreshToken) {
           await this.client.auth({
             grantType: 'refresh_token',
             refreshToken: this.client.refreshToken,
             clientId: 'admin-cli',
           });
-
+          this.logger.debug('Successfully refreshed Keycloak admin access token');
           return;
         }

---

59-61: Add logging in the error handler for better observability.

The silent catch block makes it difficult to diagnose token refresh failures. Adding debug-level logging would help identify whether the issue is token decode failure, refresh token expiration, or network problems.

🔎 Proposed enhancement

-      } catch {
-        // ignore
+      } catch (error) {
+        this.logger.debug(error, 'Token validation or refresh failed, falling back to password grant');
       }

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between aa4c66a and ddc6c0c.

📒 Files selected for processing (1)

• controlplane/src/core/services/Keycloak.ts

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: wilsonrivera
Repo: wundergraph/cosmo PR: 2100
File: docker/keycloak/realm.json:1768-1774
Timestamp: 2025-08-04T17:50:30.553Z
Learning: The sso-cookie-authenticator in Keycloak authentication flows must use "REQUIRED" as the requirement setting, not "ALTERNATIVE". This is due to implementation constraints of the custom SSOCookieAuthenticator class.

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: build_push_image
• GitHub Check: build_test
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Analyze (go)

🔇 Additional comments (2)

controlplane/src/core/services/Keycloak.ts (2)

44-48: Consider the security implications of not verifying JWT signatures.

decodeJwt only decodes the token without cryptographic signature verification. While this may be acceptable for the admin client's self-managed token (since Keycloak will validate it on actual API calls), it does mean that a tampered or forged token could bypass the expiration check.

Please confirm that skipping signature verification aligns with your security requirements. If this token could be exposed or if there's a risk of tampering, consider using jwtVerify from jose instead, which validates signatures against a JWKS endpoint.

---

6-6: No action needed. The jose dependency is properly declared in controlplane/package.json as "jose": "^5.2.4". The import statement at line 6 is valid and will not cause runtime failures.

Likely an incorrect or invalid review comment.

[codecov]

Codecov Report

❌ Patch coverage is 44.44444% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 62.77%. Comparing base (cf76d6f) to head (131a633).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
controlplane/src/core/services/Keycloak.ts	44.44%	10 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##            main    #2443       +/-   ##
==========================================
+ Coverage   1.49%   62.77%   +61.28%     
==========================================
  Files        292      296        +4     
  Lines      46983    41440     -5543     
  Branches     431     4266     +3835     
==========================================
+ Hits         703    26015    +25312     
+ Misses     45997    15404    -30593     
+ Partials     283       21      -262     

Files with missing lines	Coverage Δ
controlplane/src/core/services/Keycloak.ts	81.04% <44.44%> (ø)

... and 587 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[StarpTech]

LGTM

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@controlplane/src/core/services/Keycloak.ts`:
- Around line 59-60: The catch block in Keycloak (method handling token
lifecycle) currently logs "Failed to refresh the existing access token..." even
when decodeJwt throws; update the logic in the function that calls decodeJwt and
refreshExistingToken to differentiate failures: wrap decodeJwt(...) in its own
try/catch and log a decode-specific warning (e.g., "Failed to decode JWT, will
request a new token") and only catch refresh errors from
refreshExistingToken(...) with the existing refresh message, or adjust the
logger.warn message to generically cover both cases; reference decodeJwt and
refreshExistingToken (and the Keycloak class logger.warn) when making the
changes so the logs accurately reflect whether decoding or refreshing failed.

♻️ Duplicate comments (1)

controlplane/src/core/services/Keycloak.ts (1)

44-47: Don’t treat missing exp as valid indefinitely.

Line 45 returns early when exp is missing, which makes non-expiring tokens effectively permanent. That’s the same concern raised earlier; it’s still present. Please require exp to be present and valid before returning.

✅ Proposed fix

-        const { exp } = decodeJwt(this.client.accessToken);
-        if (!exp || exp * 1000 > Date.now()) {
-          // Either the access token never expires or it hasn't expired
+        const { exp } = decodeJwt(this.client.accessToken);
+        if (exp && exp * 1000 > Date.now()) {
+          // Access token is valid and hasn't expired
           return;
         }

[StarpTech]

LGTM