docs(boost): clarify X-Backstage-User scope in auth specs

X-Backstage-User header only applies to user-initiated requests via
KagentiApiClient (chat, agent operations), not entity provider
background polling which has no user context. Updated access-control
spec, security design doc, and boost-context to make this distinction
explicit.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: gabemontero <gmontero@redhat.com>

Author: gabemontero

workspaces/boost/openspec/changes/security-safety-governance/design.md

@@ -42,7 +42,7 @@ The `IS_NOT_CREATOR` permission rule is the primary enforcement mechanism. A rou
 
 ### Decision 4: Service-account auth with KeycloakAuthClient
 
-`KeycloakAuthClient` acquires tokens via OAuth2 Client Credentials Grant, caches them with a configurable expiry buffer (`tokenExpiryBufferSeconds`, default: 60), and automatically refreshes before expiry. On 401 responses, the token is refreshed and the request retried once (max-1-retry). User identity is propagated via `X-Backstage-User` header for audit trails. This is deliberately simple: service-account auth provides consistent authentication without per-user token management complexity.
+`KeycloakAuthClient` acquires tokens via OAuth2 Client Credentials Grant, caches them with a configurable expiry buffer (`tokenExpiryBufferSeconds`, default: 60), and automatically refreshes before expiry. On 401 responses, the token is refreshed and the request retried once (max-1-retry). For user-initiated requests via `KagentiApiClient`, user identity is propagated via `X-Backstage-User` header for audit trails; entity provider background polling omits this header (no user context). This is deliberately simple: service-account auth provides consistent authentication without per-user token management complexity.
 
 ### Decision 5: Separation of authorization concerns
 

workspaces/boost/openspec/changes/security-safety-governance/specs/access-control/spec.md

@@ -83,7 +83,7 @@ Inference responses are not stored on the server when ZDR is enabled.
 
 ### Requirement: Service-Account Keycloak Authentication for Kagenti
 
-Kagenti API calls MUST be authenticated via OAuth2 Client Credentials Grant using `KeycloakAuthClient` for service-account authentication. User identity is propagated via the `X-Backstage-User` header for audit purposes.
+Kagenti API calls MUST be authenticated via OAuth2 Client Credentials Grant using `KeycloakAuthClient` for service-account authentication. For user-initiated requests (chat, agent operations via `KagentiApiClient`), user identity is propagated via the `X-Backstage-User` header for audit purposes. Entity provider background polling has no user context and omits this header.
 
 #### Scenario: Token acquisition
 
@@ -105,11 +105,12 @@ Kagenti API calls MUST be authenticated via OAuth2 Client Credentials Grant usin
 - **AND** the request is retried with the new token
 - **AND** if the retried request also returns 401, the error is propagated to the caller
 
-#### Scenario: User identity propagation
+#### Scenario: User identity propagation (KagentiApiClient only)
 
-- **WHEN** a Kagenti API call is made on behalf of a user
-- **THEN** the `X-Backstage-User` header is set to the user's identity
+- **WHEN** a user-initiated Kagenti API call is made via `KagentiApiClient` (chat, agent operations)
+- **THEN** the `X-Backstage-User` header is set to the user's Backstage identity
 - **AND** the service-account bearer token is used for authentication (not the user's token)
+- **AND** entity provider background polling omits this header (no user context available)
 
 #### Scenario: Service-account auth configuration
 

workspaces/boost/specifications/boost-context.md

@@ -105,7 +105,7 @@ _Augment lesson: Pivoted from 5-stage to 4-stage model mid-development, requirin
 
 ### 10. Service-Account Keycloak Authentication
 
-Kagenti authentication uses OAuth2 Client Credentials Grant via `KeycloakAuthClient` for service-account authentication from the start. The token manager handles token acquisition, caching with configurable expiry buffer, and automatic refresh. User identity is propagated via the `X-Backstage-User` header for audit purposes.
+Kagenti authentication uses OAuth2 Client Credentials Grant via `KeycloakAuthClient` for service-account authentication from the start. The token manager handles token acquisition, caching with configurable expiry buffer, and automatic refresh. For user-initiated requests via `KagentiApiClient`, user identity is propagated via the `X-Backstage-User` header for audit purposes; entity provider background polling omits this header.
 
 _Augment lesson: All Kagenti requests used a shared service-account token. `X-Backstage-User` header was informational only. Per-user audit trail impossible at the provider level._
 

workspaces/boost/staged-issues.md

@@ -508,7 +508,7 @@ https://github.com/redhat-developer/rhdh-plugins/issues/3654
 **Labels:** `ready-to-code`
 **Depends on:** Issue 13 (#3309)
 
-Refactor `KeycloakAuthClient` in `kagenti-entity-provider` to use Backstage `cacheService` for token caching instead of private instance fields. Aligns with design principle 1 and the PRD cache migration table.
+Refactor `KeycloakAuthClient` in `kagenti-entity-provider` to use Backstage `cacheService` for token caching instead of private instance fields, and add HTTPS validation for `tokenEndpoint`. Aligns with design principle 1 and the PRD cache migration table.
 
 ### Tasks
 
@@ -518,6 +518,7 @@ Refactor `KeycloakAuthClient` in `kagenti-entity-provider` to use Backstage `cac
 - 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.6 Consider extracting `KeycloakAuthClient` to a shared location (e.g., `boost-node`) so `boost-backend-module-kagenti` can reuse it for task 7.5b
+- 17.7 Add HTTPS validation for `tokenEndpoint` in `KeycloakAuthClient` constructor — reject HTTP URLs unless security mode is `development-only-no-auth`
 
 ### Specifications