# Add JWT Authentication to a Socket.IO Server

Yes. An agent adds an io.use middleware that verifies a JWT from the handshake auth, refuses bad tokens with connect_error, tests it end to end, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-jwt-authentication/socket-io/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the handshake before it guards it. In a Socket.IO app like socketio/chat-example, `package.json` is `type: module` with `socket.io` `^4.7.2`, `express` `^4.18.2`, `@socket.io/cluster-adapter` `^0.2.2`, `sqlite` and `sqlite3`, one `start` script and no dev dependencies or test script. `index.js` does everything: the cluster primary forks one worker per CPU with `PORT` set to `3000 + i` and calls `setupPrimary()`; each worker opens `chat.db`, creates a `messages` table (`id`, `client_offset UNIQUE`, `content`), builds `new Server(server, { connectionStateRecovery: {}, adapter: createAdapter() })`, and in `io.on('connection')` handles `chat message` by inserting the row and calling `io.emit`, then replays missed rows with `SELECT id, content FROM messages WHERE id > ?` using `socket.handshake.auth.serverOffset` when `socket.recovered` is false. `index.html` connects with `io({ auth: { serverOffset: 0 }, ackTimeout: 10000, retries: 3 })`. The `auth` object already crosses the handshake; nothing checks who is on the other end, so anyone who can reach the port can post into every browser.

The agent adds `jsonwebtoken` and a `src/auth.js` exporting `verifySocket(socket, next)`: it reads `socket.handshake.auth.token`, calls `jwt.verify(token, process.env.JWT_SECRET, { algorithms: ['HS256'] })`, stores `{ id: payload.sub, name: payload.name }` on `socket.data.user`, and on any failure calls `next(err)` with an `Error('unauthorized')` whose `data` carries a code (`TOKEN_MISSING`, `TOKEN_EXPIRED`, `TOKEN_INVALID`) so the client can tell them apart. `io.use(verifySocket)` goes before `io.on('connection')` in every worker; since `connectionStateRecovery` is on, the agent checks what the installed Socket.IO version does with middleware on a recovered connection and writes the answer in the pull request rather than assuming. The server refuses to start without `JWT_SECRET`, because a missing secret must not mean an open server.

To make the worker testable, the agent moves the worker body into `src/server.js` as `createApp({ dbFile })` returning `{ app, server, io }`, leaving `index.js` as the cluster bootstrap that calls it. The `chat message` handler now emits `socket.data.user.name` with each message so clients can show who wrote it, without changing the `messages` table, because `CREATE TABLE IF NOT EXISTS` would not migrate an existing `chat.db`; the description says a column needs a migration if you want authors persisted. `index.html` sends `auth: { token, serverOffset: 0 }` with the token read from the page's query string for the demo, and adds a `connect_error` listener that shows `err.message` and `err.data.code` instead of retrying silently.

Tests use `node:test` with `socket.io-client` as a dev dependency and a `test` script of `node --test`. Each test starts `createApp` on port 0 with a temporary database file: no `token` ends in `connect_error` with `TOKEN_MISSING`; a token signed with the test secret connects and gets its own `chat message` back with the user name; a token signed with another secret or with `expiresIn: -1` is refused with the matching code; and after a refusal the socket never reaches the `connection` handler, asserted with a counter. The agent runs `npm install` and `npm test` in its sandbox, starts `JWT_SECRET=… node index.js` once to confirm the cluster still forks, and keeps the output. `README.md` documents `JWT_SECRET` and how to mint a token for local use; the `.codesandbox` config is untouched.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add JWT authentication to this Socket.IO server. Read package.json, index.js and index.html first. Add a jsonwebtoken-based io.use middleware that reads the token from the handshake auth, verifies it with JWT_SECRET and HS256, puts the user on socket.data, and rejects missing, expired and invalid tokens with distinct codes in the error data. Refuse to start without JWT_SECRET. Check and document how middleware behaves with connection state recovery in the installed version. Split the worker setup into an exported factory so it can be tested without the cluster, keep index.js as the cluster bootstrap, and have the client send the token in auth and handle connect_error. Write node:test tests with socket.io-client for the missing, valid, wrong-secret and expired cases, add a test script, run npm test and include the output. Do not change the messages table. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds `src/auth.js`, `src/server.js` and `test/auth.test.js`, and changes `index.js` (cluster bootstrap only), `index.html` (the `token` in `auth` and the `connect_error` handler), `package.json` (`jsonwebtoken`, `socket.io-client` as a dev dependency, the `test` script) and `README.md`. The `messages` schema and the cluster adapter setup are unchanged.

The description lists each rejection code and the test that covers it, quotes the `node --test` summary, states what the installed Socket.IO version does with middleware on a recovered connection, and shows the startup refusal when `JWT_SECRET` is unset. The commands and full output are in the transcript at `GET /o/{org}/sessions/{id}/messages`.

Before merging, a reviewer decides where tokens are minted (the demo reads one from the query string, which is not a login), whether `connectionStateRecovery` should keep its window, and whether messages need an author column. A follow-up message to the same session can add a `/login` route that issues tokens, or switch verification to an RS256 public key.

## Run it on every Socket.IO service that trusts every connection

A team with several realtime services starts one run per repository with one `POST /o/{org}/sessions` each, the repository in `resources` and this prompt as `input`. Each run reads its own namespaces and handlers, so a server with an `/admin` namespace gets the middleware on that namespace with a role check, and a server already using cookies gets the token read from `socket.handshake.headers.cookie` instead of `auth`.

Send a `request_id`, a UUID v5 of the repository's full name, so a retried call returns the run it already started. The key's `webhook_url` reports when each run the key starts finishes, with the run's final answer in `result`.

## Why run it on Rush?

A handshake guard is ten lines, but testing it means a real server, a real client, a signed token and a clock, which is why it rarely gets written. The agent splits the worker so it can be started on port 0, drives it with `socket.io-client` under `node:test` in a sandbox of its own, and keeps the output for each rejection case.

The pull request shows the middleware, the client change and the passing tests together, and states the recovery behaviour it checked, so review is reading a diff rather than reproducing four handshake failures by hand. Several services can be done at once, each in its own sandbox with its own pull request.

## Frequently asked questions

### Where does the client get a token?

That is your login, not this change. The demo page reads one from the query string so the flow can be tried locally, and the README shows how to mint one with the secret. Say in the prompt if you want a `/login` route or an existing session cookie used instead, and the agent reads the token from there.

### Does the cluster adapter still work?

Yes. The middleware runs in each worker, which is where the handshake lands; the primary only forks and runs `setupPrimary()`. The secret reaches every worker through the environment the primary already passes down with `PORT`.

### Why not pass the token as a query parameter to the socket?

Query strings end up in access logs and proxies. Socket.IO's `auth` payload is sent in the handshake body and is the documented place for credentials, and `socket.handshake.auth` is what the app already uses for `serverOffset`.

### Will existing clients break?

Yes, on purpose: a client without a token now gets `connect_error` with `TOKEN_MISSING` instead of a connection. Deploy the client change first or accept a short window; the description says so.

## More Socket.IO jobs

- [Show Online Users in a Socket.IO Chat](https://getrush.ai/run/add-online-users/socket-io/)
- [Add Message History Pagination to a Socket.IO Chat](https://getrush.ai/run/add-pagination/socket-io/)
- [Add Private Messaging to a Socket.IO Chat](https://getrush.ai/run/add-private-messaging/socket-io/)

## The same job on other stacks

- [Add JWT Authentication to a CodeIgniter 4 API](https://getrush.ai/run/add-jwt-authentication/codeigniter/)
- [Add JWT Authentication to a Fiber API](https://getrush.ai/run/add-jwt-authentication/fiber/)
- [Add JWT Login to a Koa API](https://getrush.ai/run/add-jwt-authentication/koa/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
