kagenti-entity-provider: Migrate KeycloakAuthClient to Backstage cacheService (issue 17 after 15)

[gabemontero]

Labels: ready-to-code
Depends on: Issue 13 (#3309)

Refactor KeycloakAuthClient in boost-node to use Backstage cacheService for token caching instead of private instance fields, and add HTTPS validation for tokenEndpoint. This aligns with boost design principle 1 ("All operational caches use Backstage cacheService") and the PRD cache migration table which lists KeycloakAuthClient as P1 for cacheService migration.

Context

PR #3661 extracted KeycloakAuthClient from kagenti-entity-provider and boost-backend-module-kagenti into boost-node as a shared implementation. The current implementation uses in-memory token caching (private cachedToken and tokenExpiresAt fields) with in-flight deduplication. This works correctly but deviates from the architectural principle that all operational caches use cacheService.

The boost-backend-module-kagenti package already has a KeycloakTokenCache class wrapping cacheService. The refactored KeycloakAuthClient should compose with this pattern rather than duplicating it.

Additionally, KeycloakAuthClient.getBearerToken() sends clientId:clientSecret as a Basic auth header to tokenEndpoint without validating the URL scheme is HTTPS. The Zod schema validates URL format (z.string().url()) but not HTTPS. In production, sending credentials over HTTP exposes them in transit.

Tasks

• 17.6 Extract KeycloakAuthClient to boost-node so both boost-backend-module-kagenti and kagenti-entity-provider share one implementation (done in PR feat(#3309): add Kagenti auth, 401 retry, and user header #3661)
• 17.1 Add coreServices.cache to the kagenti-entity-provider module deps
• 17.2 Refactor KeycloakAuthClient constructor to accept a CacheService instance
• 17.3 Replace private cachedToken/tokenExpiresAt fields with cacheService.get()/cacheService.set() using TTL derived from token expiry minus buffer
• 17.4 Update module.ts to pass cache (with namespace) to KeycloakAuthClient
• 17.5 Update tests to mock cacheService instead of relying on in-memory state
• 17.7 Add HTTPS validation for tokenEndpoint in KeycloakAuthClient constructor — reject HTTP URLs unless security mode is development-only-no-auth
• 17.8 Remove KeycloakTokenCache and its test from boost-backend-module-kagenti — it becomes redundant once KeycloakAuthClient uses cacheService directly. Also remove the void keycloakTokenCache placeholder in module.ts.
• 17.9 Remove stale task-number references in KagentiProviderFactory JSDoc (references "task 3.3, 3.4, 3.7" from an older numbering scheme)

Specifications

• specifications/boost-context.md — Design Principle 1 (Backstage cacheService from Day One)
• specifications/prd/pluggable-ai-platform-architecture.md — Cache migration table (KeycloakAuthClient row)
• openspec/changes/security-safety-governance/specs/access-control/spec.md — Service-account auth scenarios
• openspec/changes/platform-operations-deployment/specs/cache-migration/spec.md

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 3:56 PM UTC · Completed 3:58 PM UTC
Commit: e2df0a3 · View workflow run →

[fullsend-ai-triage]

Triage: Blocked by prerequisites

This issue aims to refactor KeycloakAuthClient to use Backstage cacheService, but the code it targets does not yet exist on the main branch.

Blocking dependencies:

• boost-backend — Keycloak service-account auth via OAuth2 Client Credentials (issue 13 of 15) #3309 — The parent issue that introduced KeycloakAuthClient is still open with a blocked label. Several tasks (7.3, 7.5b, 7.6) remain incomplete.
• PR feat(#3647): auth pivot, dev scaffold, entity provider fixes #3648 — The PR that implements KeycloakAuthClient in kagenti-entity-provider/src/providers/kagentiAuth.ts has not been merged yet. Until it lands, the in-memory token caching fields (cachedToken, tokenExpiresAt) that this issue wants to migrate to cacheService don't exist in the codebase.

Once PR #3648 merges and the KeycloakAuthClient code is on main, the refactoring tasks (17.1–17.6) described here can proceed. The issue itself is well-specified with clear tasks and architectural rationale.

Blocked by:

• boost-backend — Keycloak service-account auth via OAuth2 Client Credentials (issue 13 of 15) #3309
• feat(#3647): auth pivot, dev scaffold, entity provider fixes #3648

---

Labels: Issue is blocked on unmerged prerequisite work; adding 'blocked' label to reflect dependency status.

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 4:07 PM UTC · Completed 4:09 PM UTC
Commit: e2df0a3 · View workflow run →

[fullsend-ai-triage]

Triage: Still blocked by prerequisites

Re-triage confirms the prior assessment — both blocking dependencies remain unresolved:

• boost-backend — Keycloak service-account auth via OAuth2 Client Credentials (issue 13 of 15) #3309 (Keycloak service-account auth) is still open and labeled blocked.
• PR feat(#3647): auth pivot, dev scaffold, entity provider fixes #3648 (which introduces KeycloakAuthClient in kagenti-entity-provider/src/providers/kagentiAuth.ts) has not been merged.

The in-memory token caching fields (cachedToken, tokenExpiresAt) that this issue wants to migrate to cacheService don't exist on main yet. Once PR #3648 merges, the well-specified refactoring tasks (17.1–17.7) can proceed.

The issue description, task breakdown, and architectural rationale remain clear and sufficient for implementation once unblocked.

Blocked by:

• boost-backend — Keycloak service-account auth via OAuth2 Client Credentials (issue 13 of 15) #3309
• feat(#3647): auth pivot, dev scaffold, entity provider fixes #3648

Blocked by:

• boost-backend — Keycloak service-account auth via OAuth2 Client Credentials (issue 13 of 15) #3309
• feat(#3647): auth pivot, dev scaffold, entity provider fixes #3648

---

Labels: Issue already has appropriate labels (enhancement, ai-integrations, blocked, workspace/boost); adding security label since task 17.7 addresses HTTPS validation for credential-bearing requests.

[gabemontero]

Update from PR #3661:

• Task 17.6 is done — KeycloakAuthClient has been extracted to boost-node and both boost-backend-module-kagenti and kagenti-entity-provider now import from there. The entity provider's local kagentiAuth.ts copy has been deleted.

• Additional task for this issue: Once the cacheService migration (tasks 17.2–17.5) is complete, KeycloakTokenCache in boost-backend-module-kagenti becomes redundant and should be removed along with its test file and the void keycloakTokenCache placeholder in module.ts.