Skip to main content

AEROSIM-TS-40

Project task

Implement the Singularity Keycloak identity guard

Protected API routes validate Keycloak JWT signatures and claims and expose a trusted authenticated-subject context.

AEROSIM-TS-40Canonical ID TASK-0040
Verified flow state
Done
Owner
AeroSim Architecture and Delivery
Component
API Service — Keycloak identity guard
Repository
corp-v1-aerosim/corp-v1-aerosim

Delivery scope

Protect non-health Fastify routes with bearer JWT verification against cached Keycloak JWKS, require RS256 signature, exact issuer, configured audience, exp/nbf validity, and non-empty sub, then attach immutable AuthenticatedSubject to the request. Primary files: applications/api/src/auth/keycloak-config.ts, applications/api/src/auth/jwks-client.ts, applications/api/src/auth/identity-guard.ts, applications/api/src/types/fastify-auth.d.ts, applications/api/tests/auth/identity-guard.test.ts.

Implementation contract

Implementation artifacts

  • applications/api/src/auth/keycloak-config.ts
  • applications/api/src/auth/jwks-client.ts
  • applications/api/src/auth/identity-guard.ts
  • applications/api/src/types/fastify-auth.d.ts
  • applications/api/tests/auth/identity-guard.test.ts

Inputs

  • Authorization: Bearer <JWT> header
  • KeycloakConfig {issuer,jwksUri,audience,clockToleranceSeconds} and JWKS responses

Outputs

  • AuthenticatedSubject {sub,preferredUsername?,roles,tokenId?} on accepted requests
  • 401 ProblemDetails with code AUTH_REQUIRED or TOKEN_INVALID; 503 IDENTITY_PROVIDER_UNAVAILABLE only when no usable cached key exists

Failure boundaries

  • Reject missing bearer token, unsupported alg, unknown kid after one JWKS refresh, bad signature, wrong iss/aud, empty sub, expired token, and future nbf.
  • Never accept decoded claims before signature verification or return token contents/JWKS errors in responses.

Excluded scope

  • Fine-grained role authorization, token issuance, refresh-token handling, and Keycloak user lifecycle are outside the identity guard.

Verification steps

  • pnpm --filter @aerosim/api test -- auth/identity-guard.test.ts
  • Inject valid and each invalid JWT fixture; assert /health/live remains public and protected handlers run only for the valid token.

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 #30 reviewed head 5fc3452d04ca96d4d18455563c3b59b18fffabbf, exact-head validation task 1844 succeeded, merged as 7e6bb0a39ace683d2bf501a6c9a2313be0e188fe; Wave 5 integrated application head e6212bf637045138da191634fe113285156426b3 passed publish task 1856 and validate task 1857. 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.