Gateway Token Validation: JWKS Retrieval and Cache Rotation in Node.js 20

Validating gateway tokens with public keys from JWKS documents is crucial for Node.js 20 applications. The keys should remain with the issuer, and keeping them in memory with an expiry and refresh lock helps manage rotation. When a key id is missing, refreshing the cache should happen once, while serving a known-good key set during its TTL. The cache should have a hard limit on how long stale data can be used.

A CAPTCHA result indicates abuse resistance but does not authenticate the issuer. Both outcomes should be logged with the request ID so that a blocked bot and an invalid JWT can be distinguished. The Node.js gateway should call the documented auth route, use GET for the request, honor Retry-After for 429 responses, and avoid looping forever. The response is treated as a JWKS document, with signature verification and claim checks performed afterward.

To implement this, create a remote JWK set using the JWKS URL, set a cache max age of 5 minutes, and a cooldown duration of 30 seconds. Fetch the keys with a GET request, including the API key in the Authorization header. If the response status is not 429, return the response. If it is 429, wait for a retry duration and try again up to three times. If rate limiting persists, throw an error.

The authenticateGatewayToken function takes a token string and verifies it using the remote keys and specific settings. The payload is then checked for expiration, and if valid, returned. The important policy, such as recording token_verified, captcha_verified, and the signup decision as separate events, should be handled outside the snippet. During a rotation, provide clear evidence to differentiate issuer changes from transient network problems.