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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add JWT Authentication to a CodeIgniter 4 API (CodeIgniter)
- Add JWT Authentication to a Fiber API (Fiber)
- Add JWT Login to a Koa API (Koa)