Skip to main content

AEROSIM-TS-54

Project task

Enforce Keycloak JWT validation at the API boundary

The API accepts only valid Keycloak access tokens and derives one immutable authenticated-subject context for protected HTTP and Socket.IO operations.

AEROSIM-TS-54Canonical ID TASK-0054
Verified flow state
Done
Owner
AeroSim Architecture and Delivery
Component
API Service — Keycloak identity guard and Socket.IO gateway
Repository
corp-v1-aerosim/corp-v1-aerosim

Delivery scope

Implement JWKS retrieval and caching, issuer and audience checks, signature and expiry validation, normalized subject context, protected-route and socket guards, and credential-safe error responses. Health probes remain unauthenticated and disclose no pilot data. Concrete artifacts are applications/api/src/enforce-keycloak-jwt-validation-at-the-api-boundary.ts and applications/api/test/enforce-keycloak-jwt-validation-at-the-api-boundary.spec.ts; ownership is limited to the listed artifacts and their focused verification.

Implementation contract

Implementation artifacts

  • applications/api/src/enforce-keycloak-jwt-validation-at-the-api-boundary.ts
  • applications/api/test/enforce-keycloak-jwt-validation-at-the-api-boundary.spec.ts

Inputs

  • Bearer access token from a protected HTTPS request or Socket.IO handshake
  • Configured Keycloak issuer, AeroSim audience, and JWKS endpoint
  • Cached signing key identified by the token kid and its cache lifetime

Outputs

  • The API accepts only valid Keycloak access tokens and derives one immutable authenticated-subject context for protected HTTP and Socket.IO operations.

Failure boundaries

  • Deny missing, malformed, expired, wrong-issuer, wrong-audience, or unverifiable tokens before protected handlers run
  • If JWKS retrieval fails or a signing key is unknown after refresh, return a stable authorization failure and disclose neither token contents nor pilot data

Excluded scope

  • Issuing or refreshing browser tokens
  • Authorizing unauthenticated health probes to read profile, preference, progress, or resume data

Verification steps

  • Run applications/api/test/enforce-keycloak-jwt-validation-at-the-api-boundary.spec.ts against the exact implementation revision and retain the complete passing result.
  • Exercise the positive contract with bearer access token from a protected https request or socket.io handshake, then assert: The API accepts only valid Keycloak access tokens and derives one immutable authenticated-subject context for protected HTTP and Socket.IO operations.
  • Exercise every negative boundary: Deny missing, malformed, expired, wrong-issuer, wrong-audience, or unverifiable tokens before protected handlers run; If JWKS retrieval fails or a signing key is unknown after refresh, return a stable authorization failure and disclose neither token contents nor pilot data

Traceability

Requirements

Dependencies

UI/UX applicability

non_visual

This Task owns technical or behavioral acceptance and does not claim direct visual conformance to the approved UI/UX package.

Acceptance evidence

Verified delivery: application PR #47 reviewed head cfc97aa948faacc2a88446cf563827528b6577a2, exact-head validation task 1915 succeeded, merged as a3e4429a9970241b278a4f64aa7c6541c74e63a8; Wave 8 integrated application head a3e4429a9970241b278a4f64aa7c6541c74e63a8 passed publish task 1916 and validate task 1917. Release completion verified on product 1.0.0.0 at GitOps revision 5d3712d89dfbf7dacd993348e55f497d126c7bf9 with Argo Synced/Healthy, exact image digests, authenticated API/database access, and three-world configured-flight acceptance.

Current evidence boundary

No current implementation, acceptance, release, or deployment evidence is claimed for this planned Task. Any prior implementation may be used only as prototype and discovery evidence.