Socket.IO JWT middleware token expiration handling on reconnection

Answer

No, the @socket.io/jwt middleware does not automatically re‑validate tokens mid‑session or provide built‑in per‑message validation. It validates the JWT only during the initial handshake. While a reconnection in Socket.IO v4 triggers a new handshake (and thus re‑runs the middleware), a client that remains connected will stay connected regardless of whether the token expires after the connection is established.

Confirmed Facts

• Handshake‑only: @socket.io/jwt (v5.x for Socket.IO v4) operates as a connection middleware via io.use(), meaning it only executes during the handshake phase.
• Reconnection Behavior: In Socket.IO v4, a reconnection attempt initiates a new engine.io handshake. If the client sends an expired token during this new handshake, the server will reject the connection.
• No Built‑in Per‑Message Logic: There are no configuration options (such as maxTokenAge) within the middleware to enforce expiration after the socket is open.

Likely Explanation

The middleware is designed to authorize the establishment of a session. Once the socket is open, the server treats the session as trusted. To enforce security‑sensitive expiration, the server must proactively track the token's exp claim and terminate the socket manually.

Implementation Steps for Expiry Enforcement

1. Capture Expiry: Store the expiration timestamp in the socket's data object during the connection event.
2. Server‑Side Sweep: Implement a periodic interval to disconnect sockets whose tokens have expired.

io.use(jwt({ secret: 'your-secret', algorithms: ['HS256'] }));

io.on('connection', (socket) => {
  const payload = socket.data?.payload;
  if (payload && payload.exp) {
    socket.data.tokenExp = payload.exp * 1000;
  }
});

// Periodic enforcement sweep
setInterval(() => {
  const now = Date.now();
  for (const [id, socket] of io.sockets.sockets) {
    if (socket.data.tokenExp && now > socket.data.tokenExp) {
      socket.disconnect(true);
    }
  }
}, 30000);

For per‑message validation, use a socket‑level middleware:

socket.use((packet, next) => {
  if (socket.data.tokenExp && Date.now() > socket.data.tokenExp) {
    return next(new Error('Token expired'));
  }
  next();
});

Simulating Expiry in Test Suites

1. Local Secret: Use a dedicated test secret (not production) to sign tokens.
2. Short TTL: Generate a JWT with an exp claim set to 5–10 seconds in the future.
3. Verification Flow: Connect the client → Wait for the TTL to lapse → Trigger a reconnection (e.g., socket.disconnect() followed by socket.connect()) → Assert that the server returns a connect_error.

Missing Diagnostic Detail: Does your client‑side logic refresh the JWT before attempting a reconnection? If the client fetches a new token before reconnecting, the handshake will succeed; if it reuses the expired token, the middleware will block the connection.