When a WebSocket Outlives Its Token

// A toy signed token: base64url(JSON claims) + "." + HMAC. Illustration only; use a real JWT/PASETO library in production.
import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
const SECRET = "demo-secret";
const b64 = (s) => Buffer.from(s).toString("base64url");
const sign = (p) => createHmac("sha256", SECRET).update(p).digest("base64url");

export const mint = (sub, ttlMs, scope = ["read"]) => {
  const p = b64(JSON.stringify({ sub, scope, exp: Date.now() + ttlMs, jti: randomUUID() }));
  return `${p}.${sign(p)}`;
};
export const verify = (token) => {
  const [p, s] = String(token).split(".");
  if (!p || !s || s.length !== sign(p).length || !timingSafeEqual(Buffer.from(s), Buffer.from(sign(p)))) return null;
  const claims = JSON.parse(Buffer.from(p, "base64url"));
  return claims.exp > Date.now() ? claims : null;
};

// A WebSocket server that authenticates at the handshake and then keeps authorizing for the life of the connection.
import http from "node:http";
import { WebSocketServer } from "ws";
import { verify } from "./token.mjs";

export const CLOSE_EXPIRED = 4401, CLOSE_FORBIDDEN = 4403;     // 4000-4999: private use (RFC 6455 section 7.4.2)

export function startServer({ leadMs = 150, revoked = new Set() } = {}) {
  const conns = new Set();
  const wss = new WebSocketServer({ noServer: true, handleProtocols: () => "bearer" });
  const server = http.createServer(async (req, res) => {
    // Strategy C (out of band): an ordinary authenticated HTTP request that names a live connection.
    if (req.method === "POST" && req.url.startsWith("/renew/")) {
      const claims = verify((req.headers.authorization ?? "").replace(/^Bearer /, ""));
      const conn = [...conns].find((c) => c.id === req.url.slice(7));
      if (!claims || !conn) { res.writeHead(401).end(); return; }
      res.writeHead(accept(conn, claims) ? 204 : 403).end();
      return;
    }
    res.writeHead(404).end();
  });

  server.on("upgrade", (req, socket, head) => {
    const offered = String(req.headers["sec-websocket-protocol"] ?? "").split(/,\s*/);   // ["bearer", "<token>"]
    const claims = verify(offered[1]);
    if (!claims || revoked.has(claims.jti)) { socket.end("HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\n\r\n"); return; }
    wss.handleUpgrade(req, socket, head, (ws) => {
      ws.id = new URL(req.url, "http://x").searchParams.get("id"); ws.claims = claims; conns.add(ws);
      ws.on("close", () => { conns.delete(ws); clearTimeout(ws.warn); clearTimeout(ws.kill); });
      ws.on("message", (raw) => {                              // Strategy B (in band)
        let m; try { m = JSON.parse(raw); } catch { return ws.close(1008); }
        if (m.type === "auth") { const c = verify(m.token); if (!c || !accept(ws, c)) ws.close(CLOSE_FORBIDDEN, "renewal rejected"); }
      });
      arm(ws);
      wss.emit("ready", ws);
    });
  });

  // Renewal rules: same subject, never widen the scope, never shorten the lifetime.
  function accept(ws, c) {
    if (revoked.has(c.jti) || c.sub !== ws.claims.sub) return false;
    if (!c.scope.every((s) => ws.claims.scope.includes(s))) return false;   // more rights need a fresh handshake
    ws.claims = { ...ws.claims, scope: c.scope, exp: Math.max(ws.claims.exp, c.exp) };  // narrow now; extend, never shorten
    arm(ws);
    return true;
  }
  // The server, not the client, enforces the deadline: ask for credentials shortly before, close at expiry.
  function arm(ws) {
    clearTimeout(ws.warn); clearTimeout(ws.kill);
    const left = ws.claims.exp - Date.now();
    ws.warn = setTimeout(() => ws.readyState === 1 && ws.send(JSON.stringify({ type: "reauth" })), Math.max(0, left - leadMs));
    ws.kill = setTimeout(() => ws.close(CLOSE_EXPIRED, "token expired"), left);
  }
  return { server, wss, conns };
}

// Three ways to keep a connection alive past its token. Run: npm i ws && node demo.mjs
import WebSocket from "ws";
import { mint } from "./token.mjs";
import { startServer, CLOSE_EXPIRED } from "./server.mjs";

const TTL = 500, RUN = 2600;                                    // tiny lifetimes so that the demo takes seconds
const { server, wss } = startServer({ leadMs: 150 });
await new Promise((r) => server.listen(0, "127.0.0.1", r));
const port = server.address().port;
wss.on("ready", (ws) => { let n = 0; ws.tick = setInterval(() => ws.readyState === 1 && ws.send(JSON.stringify({ type: "tick", n: ++n })), 100); ws.on("close", () => clearInterval(ws.tick)); });

const getToken = async () => mint("alice", TTL);                // stands in for your token endpoint

async function run(strategy) {
  const stats = { connections: 0, closes: [], ticks: 0 };
  let ws, stop = false, id = 0;
  const open = async () => {
    stats.connections++; id++;
    ws = new WebSocket(`ws://127.0.0.1:${port}/?id=${id}`, ["bearer", await getToken()]);
    ws.on("message", async (raw) => {
      const m = JSON.parse(raw);
      if (m.type === "tick") stats.ticks++;
      if (m.type === "reauth" && strategy === "in-band") ws.send(JSON.stringify({ type: "auth", token: await getToken() }));
      if (m.type === "reauth" && strategy === "out-of-band")
        await fetch(`http://127.0.0.1:${port}/renew/${id}`, { method: "POST", headers: { authorization: `Bearer ${await getToken()}` } });
    });
    ws.on("close", (code) => { stats.closes.push(code); if (!stop) open(); });   // every strategy falls back to reconnect
    ws.on("error", () => {});
  };
  await open();
  await new Promise((r) => setTimeout(r, RUN));
  stop = true; ws.close();
  await new Promise((r) => setTimeout(r, 50));
  return stats;
}

for (const s of ["reconnect", "in-band", "out-of-band"]) {
  const { connections, closes, ticks } = await run(s);
  console.log(`${s.padEnd(12)} connections=${connections}  server closes with 4401=${closes.filter((c) => c === CLOSE_EXPIRED).length}  ticks received=${ticks}`);
}
server.close(); server.closeAllConnections();

import assert from "node:assert/strict";
import { test, before, after } from "node:test";
import WebSocket from "ws";
import { mint, verify } from "./token.mjs";
import { startServer, CLOSE_EXPIRED, CLOSE_FORBIDDEN } from "./server.mjs";

const revoked = new Set();
const { server, conns } = startServer({ leadMs: 100, revoked });
let port;
before(async () => { await new Promise((r) => server.listen(0, "127.0.0.1", r)); port = server.address().port; });
after(() => { server.close(); server.closeAllConnections(); });

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const connect = (token) => new Promise((resolve, reject) => {
  const ws = new WebSocket(`ws://127.0.0.1:${port}/?id=${Math.random()}`, ["bearer", token]);
  ws.closed = new Promise((r) => ws.on("close", (code) => r(code)));
  ws.on("open", () => resolve(ws)); ws.on("error", reject);
});

test("without renewal the server closes with 4401 at expiry", async () => {
  const ws = await connect(mint("alice", 300));
  assert.equal(await ws.closed, CLOSE_EXPIRED);
});

test("a valid in-band renewal keeps the connection past the original expiry", async () => {
  const ws = await connect(mint("alice", 300));
  ws.send(JSON.stringify({ type: "auth", token: mint("alice", 2000) }));
  await sleep(500);
  assert.equal(ws.readyState, WebSocket.OPEN);
  ws.close();
});

test("a token for another subject is refused", async () => {
  const ws = await connect(mint("alice", 2000));
  ws.send(JSON.stringify({ type: "auth", token: mint("bob", 4000) }));
  assert.equal(await ws.closed, CLOSE_FORBIDDEN);
});

test("a renewal cannot widen the scope", async () => {
  const ws = await connect(mint("alice", 2000, ["read"]));
  ws.send(JSON.stringify({ type: "auth", token: mint("alice", 4000, ["read", "write"]) }));
  assert.equal(await ws.closed, CLOSE_FORBIDDEN);
});

test("a narrower scope is applied immediately", async () => {
  const ws = await connect(mint("alice", 2000, ["read", "write"]));
  ws.send(JSON.stringify({ type: "auth", token: mint("alice", 100, ["read"]) }));   // narrower and older
  await sleep(100);
  const server_side = [...conns].find((c) => c.claims.sub === "alice" && c.claims.scope.length === 1);
  assert.ok(server_side, "the server now holds the narrower scope");
  assert.equal(ws.readyState, WebSocket.OPEN);
  ws.close();
});

test("a stale token cannot shorten the lifetime", async () => {
  const ws = await connect(mint("alice", 2000));
  ws.send(JSON.stringify({ type: "auth", token: mint("alice", 100) }));   // valid, but older than the current expiry
  await sleep(400);
  assert.equal(ws.readyState, WebSocket.OPEN);
  ws.close();
});

test("revocation does not cut off an open connection before it expires", async () => {
  const old = mint("alice", 600);
  const ws = await connect(old);
  revoked.add(verify(old).jti);                                            // revoke the token the connection was admitted with
  await sleep(200);
  assert.equal(ws.readyState, WebSocket.OPEN);                             // still open: nothing re-checks revocation by itself
  assert.equal(await ws.closed, CLOSE_EXPIRED);                            // it ends at expiry, the worst-case revocation delay
});

test("a revoked token is refused as a renewal", async () => {
  const ws = await connect(mint("alice", 2000));
  const renewal = mint("alice", 4000); revoked.add(verify(renewal).jti);
  ws.send(JSON.stringify({ type: "auth", token: renewal }));
  assert.equal(await ws.closed, CLOSE_FORBIDDEN);
});

test("a revoked token cannot be admitted", async () => {
  const t = mint("alice", 2000); revoked.add(verify(t).jti);
  await assert.rejects(connect(t), /401/);
});

// What can a page's script see when a WebSocket handshake or connection is rejected?
// Run: npm i ws && node browser_check.mjs   (needs Chrome/Chromium; set CHROME=/path if needed)
import http from "node:http";
import { spawn } from "node:child_process";
import { WebSocketServer } from "ws";

const page = `<script>
const results = {};
function probe(name, url, protocols) {
  return new Promise((resolve) => {
    const info = { opened: false, error: false, close: null };
    const ws = protocols ? new WebSocket(url, protocols) : new WebSocket(url);
    ws.onopen = () => { info.opened = true; info.protocol = ws.protocol; };
    ws.onerror = () => { info.error = true; };
    ws.onclose = (e) => { info.close = { code: e.code, reason: e.reason, wasClean: e.wasClean }; results[name] = info; resolve(); };
  });
}
(async () => {
  const base = "ws://" + location.host;
  await probe("subprotocol echoed, then server closes 4401", base + "/ok", ["bearer", "tok"]);
  await probe("subprotocol offered but not selected", base + "/noproto", ["bearer", "tok"]);
  await probe("HTTP 401 at the upgrade", base + "/unauth");
  await fetch("/report", { method: "POST", body: JSON.stringify(results, null, 1) });
})();
</script>`;

const http_ = http.createServer(async (req, res) => {
  if (req.url === "/") { res.writeHead(200, { "content-type": "text/html" }); return res.end(page); }
  if (req.url === "/report") {
    let b = ""; for await (const c of req) b += c;
    console.log(b); res.end("ok"); clearTimeout(guard); chrome.kill(); http_.close(); http_.closeAllConnections();
  }
});
const wss = new WebSocketServer({ noServer: true, handleProtocols: (set, req) => (req.url === "/noproto" ? false : "bearer") });
http_.on("upgrade", (req, socket, head) => {
  if (req.url === "/unauth") { socket.end("HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"); return; }
  wss.handleUpgrade(req, socket, head, (ws) => setTimeout(() => ws.close(4401, "token expired"), 100));
});
await new Promise((r) => http_.listen(0, "127.0.0.1", r));
const guard = setTimeout(() => { console.log("timeout"); chrome.kill(); process.exit(1); }, 20000);
const chrome = spawn(process.env.CHROME ?? "google-chrome", [
  "--headless=new", "--no-sandbox", "--disable-gpu", "--user-data-dir=./ws-check-profile",
  `http://127.0.0.1:${http_.address().port}/`,
], { stdio: "ignore" });