Authentication and Authorization

// server.mjs -- Chatterbox authentication demo: login, one-time tickets, handshake checks, expiry, revocation.
import { createServer } from 'node:http';
import { randomBytes } from 'node:crypto';
import { WebSocketServer } from 'ws';
import { SignJWT, jwtVerify } from 'jose';
import { createClient } from 'redis';

const PORT = Number(process.env.PORT ?? 8080);
const ORIGINS = new Set((process.env.ORIGINS ?? 'https://chat.example.test').split(','));
const ACCESS_TTL_S = Number(process.env.ACCESS_TTL_S ?? 300);   // access token life
const TICKET_TTL_S = Number(process.env.TICKET_TTL_S ?? 30);    // one-time ticket life
const SESSION_TTL_S = 3600;                                      // cookie session life
const HELLO_MS = 5000;
const KEY = new TextEncoder().encode(process.env.JWT_SECRET ?? 'change-me-change-me-change-me-32b'); // HS256 needs 32 bytes
const USERS = {                                                  // stand-in for a user store
  alice: { password: 'change-me', role: 'member' },
  bob: { password: 'change-me', role: 'member' },
  carol: { password: 'change-me', role: 'admin' },
};

const redis = await createClient({ url: process.env.REDIS_URL ?? 'redis://localhost:6379' }).connect();
const sub = redis.duplicate();
await sub.connect();

const b64 = () => randomBytes(24).toString('base64url');
const sid = () => 's_' + [...randomBytes(26)].map((b) => '0123456789ABCDEFGHJKMNPQRSTVWXYZ'[b & 31]).join('');
const now = () => Math.floor(Date.now() / 1000);

// ---------- identity on plain HTTP requests: bearer token first, then session cookie ----------
async function identify(req) {
  const auth = req.headers.authorization ?? '';
  if (auth.startsWith('Bearer ')) {
    try {
      const { payload } = await jwtVerify(auth.slice(7), KEY, { algorithms: ['HS256'], issuer: 'chatterbox', audience: 'chatterbox-api' });
      return { user: payload.sub, role: payload.role, exp: payload.exp };
    } catch { return null; }
  }
  const sessionId = /(?:^|;\s*)cb_sid=([\w-]+)/.exec(req.headers.cookie ?? '')?.[1];
  if (!sessionId) return null;
  const [raw, ttl] = await Promise.all([redis.get(`session:${sessionId}`), redis.ttl(`session:${sessionId}`)]);
  return raw ? { ...JSON.parse(raw), exp: now() + ttl } : null;
}

const originOk = (req) => !req.headers.origin || ORIGINS.has(req.headers.origin);
const json = (res, status, body, headers = {}) => {
  res.writeHead(status, { 'Content-Type': 'application/json', ...headers });
  res.end(JSON.stringify(body));
};
const readJson = async (req) => { let s = ''; for await (const c of req) s += c; return s ? JSON.parse(s) : {}; };

const http = createServer(async (req, res) => {
  try {
    if (req.method !== 'POST') return json(res, 404, {});
    if (!originOk(req)) return json(res, 403, { error: 'origin' });   // cookie-authenticated POSTs need an Origin check too
    if (req.url === '/api/login') {
      const { user, password } = await readJson(req);
      if (!USERS[user] || USERS[user].password !== password) return json(res, 401, { error: 'bad credentials' });
      const id = b64();
      await redis.set(`session:${id}`, JSON.stringify({ user, role: USERS[user].role }), { EX: SESSION_TTL_S });
      const accessToken = await new SignJWT({ role: USERS[user].role })
        .setProtectedHeader({ alg: 'HS256' }).setSubject(user).setIssuer('chatterbox').setAudience('chatterbox-api')
        .setIssuedAt().setExpirationTime(`${ACCESS_TTL_S}s`).sign(KEY);
      return json(res, 200, { accessToken, expiresIn: ACCESS_TTL_S },
        { 'Set-Cookie': `cb_sid=${id}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=${SESSION_TTL_S}` });
    }
    if (req.url === '/api/ticket') {
      const who = await identify(req);
      if (!who) return json(res, 401, { error: 'unauthorized' });
      const ticket = b64();
      await redis.set(`ticket:${ticket}`, JSON.stringify(who), { EX: TICKET_TTL_S });  // carries the credential's own expiry
      return json(res, 200, { ticket, expiresIn: TICKET_TTL_S });
    }
    if (req.url === '/api/logout') {
      const who = await identify(req);
      if (!who) return json(res, 401, { error: 'unauthorized' });
      await redis.publish('revoke', who.user);                      // every instance closes this user's sockets
      return json(res, 200, { ok: true });
    }
    return json(res, 404, {});
  } catch (e) { return json(res, 500, { error: 'internal' }); }
});

// ---------- WebSocket: authenticate the handshake when the browser can, else on the first frame ----------
const wss = new WebSocketServer({ noServer: true, maxPayload: 16384, handleProtocols: (p) => (p.has('chatterbox.v1') ? 'chatterbox.v1' : false) });
const deny = (socket, status, text) => { socket.write(`HTTP/1.1 ${status} ${text}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`); socket.destroy(); };
const redeem = async (t) => { const raw = typeof t === 'string' && t ? await redis.getDel(`ticket:${t}`) : null; return raw ? JSON.parse(raw) : null; };

http.on('upgrade', async (req, socket, head) => {
  socket.on('error', () => {});
  try {
    const url = new URL(req.url, 'http://localhost');
    if (url.pathname !== '/ws') return deny(socket, 404, 'Not Found');
    if (!originOk(req)) return deny(socket, 403, 'Forbidden');       // CSWSH defence: Origin allow-list
    const offered = (req.headers['sec-websocket-protocol'] ?? '').split(',').map((s) => s.trim());
    if (!offered.includes('chatterbox.v1')) return deny(socket, 400, 'Bad Request');
    let who = null;
    const t = url.searchParams.get('ticket') ?? offered.find((p) => p.startsWith('ticket.'))?.slice(7);
    if (t !== undefined) { who = await redeem(t); if (!who) return deny(socket, 401, 'Unauthorized'); }
    else if (req.headers.cookie) who = await identify(req);          // cookie session: no ticket needed
    wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req, who));
  } catch { deny(socket, 500, 'Internal Server Error'); }
});

const byUser = new Map();       // user -> Set<conn>, for revocation
const rooms = new Map();        // room -> { seq, members: Set<conn>, messages: Map<id, envelope> }
const roomOf = (name) => rooms.get(name) ?? rooms.set(name, { seq: 0, members: new Set(), messages: new Map() }).get(name);

function canJoin({ user, role }, room) {                              // per-room authorization
  if (!/^[a-z0-9-]{1,64}$/.test(room)) return false;
  if (room.startsWith('dm-')) return room.slice(3).split('-').includes(user);   // placeholder: real names need a safe delimiter
  if (room === 'staff') return role === 'admin';
  return true;
}

function send(conn, type, ref, room, payload) {
  conn.ws.send(JSON.stringify({ v: 1, type, id: sid(), room, ts: Date.now(), payload: ref ? { ref, ...payload } : payload }));
}
function end(conn, code, reason) {
  conn.ws.close(code, reason);
  setTimeout(() => conn.ws.terminate(), 1000).unref();
}
function fail(conn, ref, code, message, closeCode) {
  send(conn, 'error', null, null, { ref, code, message, retryable: false });
  if (closeCode) end(conn, closeCode, message);
}

function bind(conn, who) {                                           // identity known: remember it and arm the expiry timer
  Object.assign(conn, who);
  (byUser.get(who.user) ?? byUser.set(who.user, new Set()).get(who.user)).add(conn);
  const ms = Math.min(who.exp * 1000 - Date.now(), 2 ** 31 - 1);
  conn.expiry = setTimeout(() => end(conn, 4401, 'token expired'), Math.max(ms, 0));
}

wss.on('connection', (ws, req, who) => {
  const conn = { ws, user: null, helloDone: false, joined: new Set() };
  if (who) bind(conn, who);
  const helloTimer = setTimeout(() => end(conn, 4408, 'hello timeout'), HELLO_MS);
  ws.on('close', () => {
    clearTimeout(helloTimer); clearTimeout(conn.expiry);
    byUser.get(conn.user)?.delete(conn);
    for (const r of conn.joined) rooms.get(r)?.members.delete(conn);
  });
  ws.on('error', () => {});
  ws.on('message', async (data, isBinary) => {
    if (isBinary) return end(conn, 4400, 'text only');
    let env;
    try { env = JSON.parse(data.toString()); } catch { return end(conn, 4400, 'bad json'); }
    if (conn.user && conn.exp * 1000 <= Date.now()) return end(conn, 4401, 'token expired');   // belt and braces
    if (env.type === 'hello') return hello(conn, env, helloTimer);
    if (!conn.helloDone) return fail(conn, env.id, 'unauthorized', 'say hello first', 4401);
    handlers[env.type] ? handlers[env.type](conn, env) : fail(conn, env.id, 'bad_request', 'unknown type');
  });
});

async function hello(conn, env, helloTimer) {
  if (conn.helloDone) return fail(conn, env.id, 'conflict', 'already authenticated');
  if (!conn.user) {                                                  // not authenticated by the handshake: redeem the ticket
    const who = await redeem(env.payload?.token);
    if (!who) return fail(conn, env.id, 'unauthorized', 'invalid or used ticket', 4401);
    bind(conn, who);
  }
  clearTimeout(helloTimer);
  conn.helloDone = true;
  send(conn, 'hello', env.id, null, { userId: conn.user, name: conn.user, sessionId: b64(), heartbeatMs: 20000, maxFrameBytes: 16384, resumed: false, rooms: [] });
}

const ack = (conn, env, seq = null, result = {}) => send(conn, 'ack', env.id, env.room ?? null, { ok: true, seq, dup: false, result });
const handlers = {
  join(conn, env) {
    if (!canJoin(conn, env.room)) return fail(conn, env.id, 'forbidden', 'not allowed in this room');
    const room = roomOf(env.room);
    room.members.add(conn); conn.joined.add(env.room);
    ack(conn, env, null, { members: [...room.members].map((m) => ({ userId: m.user, name: m.user, status: 'online' })), lastSeq: room.seq });
  },
  message(conn, env) {
    if (!conn.joined.has(env.room)) return fail(conn, env.id, 'forbidden', 'join the room first');
    const room = roomOf(env.room);
    const out = { from: { userId: conn.user, name: conn.user }, text: String(env.payload?.text ?? ''), replyTo: null, attachments: [], seq: ++room.seq, edited: false };
    room.messages.set(env.id, out);
    ack(conn, env, out.seq);
    for (const m of room.members) send(m, 'message', null, env.room, out);
  },
  edit(conn, env) {
    const target = roomOf(env.room).messages.get(env.payload?.target);
    if (!target) return fail(conn, env.id, 'not_found', 'unknown message');
    if (target.from.userId !== conn.user) return fail(conn, env.id, 'forbidden', 'only the author can edit');  // object-level check
    target.text = String(env.payload.text); target.edited = true;
    ack(conn, env);
  },
};

await sub.subscribe('revoke', (user) => { for (const c of byUser.get(user) ?? []) end(c, 4401, 'session revoked'); });
http.listen(PORT, () => console.log(`chatterbox auth demo on :${PORT}`));

// client.mjs -- browser-style Chatterbox client: ticket per connection, first-message hello, re-auth on close 4401.
const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
const newId = () => {                                              // 26 characters: 10 of time, 16 random (ULID layout)
  let t = Date.now(), time = '';
  for (let i = 0; i < 10; i++) { time = CROCKFORD[t % 32] + time; t = Math.floor(t / 32); }
  return time + [...crypto.getRandomValues(new Uint8Array(16))].map((b) => CROCKFORD[b & 31]).join('');
};

export class SignedOut extends Error {}

export function connectChat({ api, url, getAccessToken, onState, onEnvelope = () => {} }) {
  let socket, attempts = 0, closedByUs = false;

  async function fetchTicket() {
    const res = await fetch(`${api}/api/ticket`, { method: 'POST', headers: { Authorization: `Bearer ${await getAccessToken()}` } });
    if (res.status === 401) throw new SignedOut();
    if (!res.ok) throw new Error(`ticket ${res.status}`);
    return (await res.json()).ticket;
  }

  const retryLater = () => {                                       // full jitter, capped
    const ms = Math.random() * Math.min(30000, 500 * 2 ** attempts++);
    onState(`retry in ${Math.round(ms)} ms`);
    setTimeout(open, ms);
  };

  async function open() {
    if (closedByUs) return;
    let ticket;
    try { ticket = await fetchTicket(); }
    catch (e) { return e instanceof SignedOut ? onState('signed-out') : retryLater(); }   // 401: stop, do not hammer

    socket = new WebSocket(url, ['chatterbox.v1']);
    socket.onopen = () => socket.send(JSON.stringify({ v: 1, type: 'hello', id: newId(), room: null, ts: 0, payload: { token: ticket, client: 'web/1.4' } }));
    socket.onmessage = (e) => {
      const env = JSON.parse(e.data);
      if (env.type === 'hello') { attempts = 0; onState(`online as ${env.payload.userId}`); } else onEnvelope(env);
    };
    socket.onclose = (e) => {
      if (closedByUs) return;
      if (e.code === 4401) { onState('credential expired, re-authenticating'); return open(); }   // new token, new ticket, no back-off
      if (e.code === 4403 || e.code === 4426) return onState(`fatal close ${e.code}`);             // retrying cannot help
      retryLater();
    };
  }

  open();
  return { close() { closedByUs = true; socket?.close(1000); } };
}

   27 ms  online as alice
 1087 ms  credential expired, re-authenticating
 1092 ms  online as alice
 3090 ms  credential expired, re-authenticating
 3101 ms  online as alice
 5089 ms  credential expired, re-authenticating
 5098 ms  online as alice

ok   login returns an access token and a session cookie
ok   ticket endpoint refuses an anonymous request
ok   ticket endpoint refuses a tampered token
-- first-message ticket (the Chatterbox default)
ok   ticket minted by one instance is redeemed by another
ok   a replayed ticket gets unauthorized and close 4401
ok   hello without a token gets unauthorized and close 4401
ok   any frame before hello closes with 4401
ok   silence after open closes with 4408 after 5 s
-- handshake checks
ok   a foreign Origin is refused with HTTP 403
ok   a client without Origin reaches hello (it must still present a ticket)
ok   a request without the chatterbox.v1 subprotocol is refused
-- cookie session (same origin, no ticket in hello)
ok   the session cookie authenticates the handshake
ok   a cross-site page with a valid cookie is still refused by the Origin check
ok   the cookie-authenticated ticket endpoint checks Origin as well
-- ticket in the query string and in the subprotocol
ok   query-string ticket authenticates the handshake
ok   an unknown query-string ticket is refused with 401 at the handshake
ok   the server selects chatterbox.v1, never echoing the ticket entry
ok   subprotocol ticket authenticates the handshake
-- authorization
ok   a third user cannot join a DM room
ok   a participant can join the DM room
ok   a member cannot join the admin-only room
ok   an admin can join it
ok   sending to a room you have not joined is forbidden
ok   a member of the room can send and others receive
ok   only the author can edit a message
ok   the author can edit it
-- revocation on logout
ok   logout on instance B closes the user's socket on instance A with 4401
-- expiry of the credential
ok   the server closes the socket with 4401 when the token expires (after 1291 ms)
ok   an expired access token can no longer mint tickets
ok   reconnecting with a fresh token and a new ticket works
all authentication checks passed

// Server: refuse unknown tickets, close at credential expiry.
io.use((socket, next) => {
  const who = redeem(socket.handshake.auth?.ticket);       // one-time: Redis GETDEL in production
  if (!who) { const err = new Error('unauthorized'); err.data = { code: 'unauthorized' }; return next(err); }
  socket.data.user = who.user;
  socket.data.expiry = setTimeout(() => socket.disconnect(true), who.exp - Date.now());
  next();
});
io.on('connection', (socket) => {
  socket.on('disconnect', () => clearTimeout(socket.data.expiry));
  socket.emit('hello', { userId: socket.data.user });
});

// Client: auth is a function, so every attempt gets a new ticket.
const socket = io(url, { auth: (cb) => cb({ ticket: mint() }) });
socket.on('disconnect', (reason) => { if (reason === 'io server disconnect') socket.connect(); });

import { createHmac } from 'node:crypto';

const key = 'example-key', secret = 'example-secret';     // placeholders; the secret never leaves the servers
const sign = (stringToSign) => `${key}:${createHmac('sha256', secret).update(stringToSign).digest('hex')}`;

const socketId = '1234.5678', channel = 'presence-chat.general';
const channelData = JSON.stringify({ user_id: '1', user_info: { name: 'alice' } });
console.log({ auth: sign(`${socketId}:${channel}:${channelData}`), channel_data: channelData });