Harden JWT authentication with claim validation, JWKS endpoint support, clock-skew tolerance, and token-refresh protocol

[levoski1]

Title

Harden JWT authentication with claim validation, JWKS endpoint support, clock-skew tolerance, and token-refresh protocol

Difficulty

10/10 — Expert. Estimated effort: 4–5 days for a senior engineer.

Context

src/auth.js (lines 27–47) performs JWT verification but only checks signature and expiry. It does not validate the iss (issuer), aud (audience), or nbf (not-before) claims beyond the library defaults. In a microservices environment, this means a JWT minted by an unrelated service (e.g., an internal SSO that shares the same symmetric secret) would be accepted by the gateway. The notBefore check is delegated to the library, but there is no clock-skew tolerance — clients whose clocks are even 1 second ahead of the server receive Token has expired on tokens that are nominally valid.

Additionally, there is no token-refresh mechanism. When a JWT expires, the client is disconnected with close code 4001 and must obtain a new token out-of-band. For mobile fleet-tracking clients that maintain persistent connections through cell handoffs, this means connection drops every expiresIn interval (commonly 1 hour), causing the gaps that issue 6 aims to fix. A proper refresh protocol allows the client to send a new token on the existing connection without disconnecting.

Finally, the auth module has no support for asymmetric key verification (RSA/ES256 via JWKS endpoint). The current implementation only supports HMAC symmetric secrets. Production deployments behind an API gateway or identity provider (Auth0, Keycloak, AWS Cognito) require JWKS-based key rotation.

Problem statement

Extend src/auth.js to support:

1. Claim validation: Validate iss (must match AUTH_ISSUER env var if set), aud (must match AUTH_AUDIENCE env var if set), and nbf (reject tokens not yet valid with a configurable clock-skew tolerance of ±30 seconds).
2. JWKS endpoint support: When AUTH_JWKS_URI is set, fetch the JWKS document (with caching and automatic refresh) and verify tokens using the matching kid header against the public key. Support both RSA (RS256) and EC (ES256) algorithms.
3. Clock-skew tolerance: Allow ±30 seconds of clock drift between client and server for exp and nbf checks.
4. Token refresh protocol: Add a new message type token_refresh that allows a connected client to send a new JWT on the existing connection. The server verifies the new token, updates the client's identity, and responds with { type: "token_refresh_ok" } or { type: "error", payload: { message: "..." } }.
5. Algorithm restriction: Reject tokens using the none algorithm and restrict to explicitly allowed algorithms (HS256, RS256, ES256).

Current behavior

src/auth.js lines 27–47:

export function verifyConnection(token) {
  const secret = process.env.AUTH_SECRET;
  if (!secret) {
    return { ok: false, error: "Server misconfiguration: AUTH_SECRET is missing" };
  }
  try {
    const payload = jwt.verify(token, secret);
    return { ok: true, clientId: payload.sub ?? payload.clientId ?? "anonymous" };
  } catch (err) {
    // ... error handling
  }
}

• No iss or aud claim validation.
• No JWKS support — only symmetric HMAC.
• No clock-skew tolerance — jwt.verify uses default options.
• No token refresh — client must disconnect and reconnect with a new token.
• No algorithm restriction — accepts whatever algorithm the JWT header specifies (algorithm confusion attack vector).

Required behavior

• verifyConnection(token) validates iss, aud, nbf with clock-skew tolerance when env vars are set.
• When AUTH_JWKS_URI is set, verification uses the public key from the JWKS document.
• none algorithm is explicitly rejected.
• Token refresh message type is accepted by the validator and processed by the server.
• All existing auth.test.js and auth-extended.test.js tests pass.
• New tests for: claim validation, JWKS verification, clock skew, token refresh, algorithm restriction.

Constraints

• Do not add new npm dependencies beyond the existing jsonwebtoken. For JWKS, implement the HTTP fetch and JWK-to-PEM conversion using Node.js built-in crypto.createPublicKey (available since Node 12) — do NOT add jose or node-jose.
• Do not break the existing AUTH_SECRET HMAC flow — it must remain the default when AUTH_JWKS_URI is not set.
• JWKS document must be cached with a configurable TTL (default 10 minutes) and refreshed in the background.
• Clock-skew tolerance must be ±30 seconds, configurable via AUTH_CLOCK_SKEW_MS env var.
• Do not modify server.js beyond adding the token_refresh message handling (or note that server.js is broken and this depends on issue 1).

Acceptance criteria

• auth.test.js passes (after accounting for the stale test — see below)
• auth-extended.test.js passes
• Token with invalid iss claim is rejected when AUTH_ISSUER is set
• Token with invalid aud claim is rejected when AUTH_AUDIENCE is set
• Token with nbf 31 seconds in the future is rejected
• Token with exp 29 seconds in the future (but past nominal expiry) is accepted with ±30s skew
• Token with alg: "none" is rejected
• JWKS verification works when AUTH_JWKS_URI is set (mock the HTTP endpoint in tests)
• Token refresh: connected client sends token_refresh with new JWT, receives token_refresh_ok
• Token refresh: invalid new token returns error frame, connection remains open
• npm run lint passes

Out of scope

• Changes to room-manager.js, rate-limiter.js, conn-rate-limiter.js, logger.js.
• Full OAuth2/OIDC integration (that is an identity provider concern).
• Token introspection endpoint (RFC 7662).
• Refresh token rotation (this is about refreshing the WS session token, not OAuth refresh tokens).

Hints and references

• The jsonwebtoken library's jwt.verify accepts an algorithms option: jwt.verify(token, secret, { algorithms: ["HS256", "RS256", "ES256"] }). Always pass this explicitly to prevent algorithm confusion attacks.
• For JWKS, the standard endpoint returns { keys: [{ kid, kty, n, e, ... }] }. Use crypto.createPublicKey({ format: "jwk", key: jwk }) (Node 16+) to convert JWK to a Node.js KeyObject.
• Clock-skew tolerance: subtract clockTolerance from currentTimestamp before comparing with exp, and add it before comparing with nbf. The jsonwebtoken library does not have a built-in clock-skew option — you must adjust the clockTolerance parameter manually or use the clockTimestamp option.
• The stale auth.test.js test (line 4–9) expects verifyConnection(null) to return { ok: true } when AUTH_SECRET is empty string. But auth.js was hardened to fail-closed. This test needs to be updated to expect { ok: false }. However, the issue constraint says not to modify test files — so ensure the test passes by making AUTH_SECRET="" behave as expected (empty string is falsy in JS, so the existing if (!secret) check already rejects it). The test will need updating — note this dependency.

[senku-7]

Can I work on this please?

[code-plate-not-leaf]

Hello Maintainer, I've looked into the issue and have an implementation strategy in mind. I'll focus on resolving the root cause rather than applying a temporary workaround. I'd be glad to work on it.

[queentiffany1111-cloud]

Application for Issue #197: Harden JWT authentication with claim validation, JWKS endpoint support, clock-skew tolerance, and token-refresh protocol

---

Motivation & Cultural Fit

In a distributed real-time gateway handling persistent WebSocket connections for fleet tracking, auth vulnerabilities can lead to cross-tenant data leaks, algorithm confusion attacks, or frequent connection drops during cell handoffs. Security must be foundational, zero-trust, and built to handle enterprise identity integrations like Keycloak or Cognito without introducing heavy external library bloat.

With 2 years of deep systems programming experience in Rust and Solidity, security engineering and defense-in-depth architecture are ingrained in how I write code. I specialize in cryptographic verification, strict protocol state handling, and resource-bounded caching. I want to build a bulletproof, zero-dependency JWKS authentication and token-refresh layer for RiftCore00 that hardens the gateway against attack vectors while keeping persistent connections stable.

Technical Competence & Relevant Experience

• Cryptographic Verification & Zero-Dependency Design: Coming from a systems background, I avoid bloated dependency chains. I am well-versed in native Node.js crypto primitives (specifically crypto.createPublicKey with JWK formatting) to verify RS256/ES256 signatures, restrict algorithms (HS256, RS256, ES256), and block alg: "none" exploit vectors natively.
• Zero-Trust Identity & Claim Validation: My background with immutable state and strict security boundaries allows me to implement precise claim checks (iss, aud, nbf, exp) with configurable clock-skew tolerance ($\pm30\text{s}$) to prevent connection drops across distributed nodes.
• JWKS In-Memory Caching & State Management: Experienced in designing asynchronous background fetchers with configurable TTL caching and automatic cache invalidation patterns, ensuring high-throughput token verification without blocking incoming connection handshakes.

---

My Proposed Execution Plan

I will deliver an end-to-end hardened authentication module in src/auth.js and extend test coverage to satisfy every acceptance criterion:

1. Hardened Verification Engine & Zero-Dependency JWKS (src/auth.js)

• Algorithm Restriction & Security: Explicitly set algorithms: ["HS256", "RS256", "ES256"] in jsonwebtoken options and explicitly reject alg: "none" headers before verification.
• Native JWKS Integration: Build a lightweight, zero-dependency HTTP/HTTPS client fetching JWKS keys when AUTH_JWKS_URI is set. Convert JWK keys using Node's native crypto.createPublicKey({ format: "jwk", key: jwk }) with in-memory TTL caching (default 10 minutes) and background refresh logic.
• Strict Claim & Clock-Skew Validation: Enforce AUTH_ISSUER and AUTH_AUDIENCE env var checks. Pass clockTolerance: AUTH_CLOCK_SKEW_MS / 1000 (default 30s) to jwt.verify to gracefully handle client/server clock drift on exp and nbf claims.
• Symmetric Fallback: Preserve AUTH_SECRET HMAC verification as the primary default when AUTH_JWKS_URI is absent.

2. In-Session Token Refresh Protocol

• In-Place Identity Updates: Process token_refresh messages over existing WebSocket connections. Verify the incoming JWT and update the client's session state on success with { type: "token_refresh_ok" }.
• Fault-Tolerant Rejection: If the refresh token is invalid or expired, return a structured error frame while keeping the WebSocket session open so the client can retry or gracefully handle auth state.

3. Test Suite Matrix

• Regression Safeguards: Ensure all existing tests in auth.test.js and auth-extended.test.js pass cleanly without breaking changes.
• New Comprehensive Tests: Add focused unit tests covering:
• Strict iss and aud mismatch rejections.
• nbf verification beyond the 30-second clock-skew tolerance limit.
• Acceptance of nominal expired tokens within the 30-second exp clock-skew window.
• Rejection of alg: "none" payloads and unsupported signature algorithms.
• JWKS HTTP endpoint fetching, key matching via kid, and caching behavior using mocked endpoints.
• Valid and invalid token_refresh frame handling over WebSocket connections.

I am ready to jump in immediately, deliver clean and audited code, and make src/auth.js production-ready for enterprise identity providers!

[grantfox-oss]

🦊 GrantFox — @queentiffany1111-cloud has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #197)
2. Your PR will be reviewed by the RiftCore00 maintainers

Good luck! Track your progress on GrantFox.