Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { UnauthorizedException } from '@nestjs/common';
import type { ConfigService } from '@nestjs/config';
// ConfigService stub for the media-shed knob: no override means the default cap applies.
const asConfig = (): { get: jest.Mock } => ({ get: jest.fn((_key: string, defaultValue?: unknown) => defaultValue) });
import { Socket } from 'socket.io';
import { EventsGateway, QR_DENIED_ROOM, isSessionSubscriptionAllowed } from './events.gateway';
import { AuthService } from '../auth/auth.service';
import { AuditService } from '../audit/audit.service';
import { AuditAction } from '../audit/entities/audit-log.entity';
import { SUBSCRIBABLE_EVENTS, buildRoomName } from './dto/ws-messages.dto';
import type { WSClientMessage, WSErrorResponse, WSSubscribedResponse, WSEventMessage } from './dto/ws-messages.dto';
import { WEBHOOK_RESERVED_EVENTS } from '../webhook/dto/webhook.dto';
import { SlidingWindowLimiter } from './ws-rate-limit';
describe('isSessionSubscriptionAllowed (WS session-scope enforcement)', () => {
it('allows an unrestricted key (null allowedSessions) to subscribe to anything, including *', () => {
expect(isSessionSubscriptionAllowed(null, '*')).toBe(true);
expect(isSessionSubscriptionAllowed(null, 'sess-1')).toBe(true);
});
it('allows an unrestricted key (empty allowedSessions) to subscribe to *', () => {
expect(isSessionSubscriptionAllowed([], '*')).toBe(true);
});
it('forbids a session-scoped key from subscribing to the * wildcard', () => {
expect(isSessionSubscriptionAllowed(['sess-1'], '*')).toBe(false);
});
it('allows a session-scoped key to subscribe to a session in its allowlist', () => {
expect(isSessionSubscriptionAllowed(['sess-1', 'sess-2'], 'sess-2')).toBe(true);
});
it('forbids a session-scoped key from subscribing to a session outside its allowlist', () => {
expect(isSessionSubscriptionAllowed(['sess-1'], 'sess-2')).toBe(false);
});
});
interface MockSocket {
id: string;
handshake: {
headers: Record<string, string>;
query: Record<string, string>;
auth: { apiKey?: string };
address: string;
};
data: Record<string, unknown>;
/** socket.io sets this the moment the transport closes, before the disconnect handler runs. */
disconnected?: boolean;
emit: jest.Mock;
disconnect: jest.Mock;
join: jest.Mock;
leave: jest.Mock;
rooms: Set<string>;
}
describe('EventsGateway connection auth + subscribe re-validation', () => {
let gateway: EventsGateway;
let authService: { validateApiKey: jest.Mock };
const makeSocket = (auth: { apiKey?: string } = {}): MockSocket => {
const s: MockSocket = {
id: 'sock-1',
handshake: { headers: {}, query: {}, auth, address: '203.0.113.5' },
data: {},
emit: jest.fn(),
// Like socket.io, a server-side close marks the socket disconnected at once.
disconnect: jest.fn(() => {
s.disconnected = true;
}),
join: jest.fn(),
leave: jest.fn(),
// Socket.IO puts every socket in a room named after its own id.
rooms: new Set<string>(['sock-1']),
};
return s;
};
const unauthorizedEmits = (s: MockSocket): unknown[] =>
s.emit.mock.calls.filter(([, frame]) => (frame as WSErrorResponse | undefined)?.code === 'UNAUTHORIZED');
// Subscription rooms joined by the socket; the QR-denied role room is not a subscription.
const sessionRoomJoins = (s: MockSocket): string[] =>
s.join.mock.calls.map(([room]) => room as string).filter(room => room.startsWith('session:'));
const asSocket = (s: MockSocket): Socket => s as unknown as Socket;
const subscribeMsg = (sessionId: string, events: string[]): WSClientMessage =>
({ type: 'subscribe', sessionId, events, requestId: 'r1' }) as unknown as WSClientMessage;
let auditService: { logWarn: jest.Mock };
beforeEach(() => {
authService = { validateApiKey: jest.fn() };
auditService = { logWarn: jest.fn().mockResolvedValue(null) };
gateway = new EventsGateway(
authService as unknown as AuthService,
auditService as unknown as AuditService,
asConfig() as unknown as ConfigService,
);
});
it('rejects a connection with no API key (and never calls validate)', async () => {
const sock = makeSocket({});
await gateway.handleConnection(asSocket(sock));
expect(sock.disconnect).toHaveBeenCalled();
expect(authService.validateApiKey).not.toHaveBeenCalled();
});
it('does NOT accept the API key from the query string (credential must not travel in the URL)', async () => {
const sock = makeSocket({});
sock.handshake.query.apiKey = 'leaky-key-in-url';
await gateway.handleConnection(asSocket(sock));
expect(authService.validateApiKey).not.toHaveBeenCalled(); // query key ignored → treated as missing
expect(sock.disconnect).toHaveBeenCalled();
});
it('audits a rejected WebSocket auth attempt (forensic parity with the REST guard)', async () => {
authService.validateApiKey.mockRejectedValue(new UnauthorizedException('Invalid API key'));
const sock = makeSocket({ apiKey: 'bad' });
await gateway.handleConnection(asSocket(sock));
expect(auditService.logWarn).toHaveBeenCalledWith(
AuditAction.API_KEY_AUTH_FAILED,
expect.objectContaining({ ipAddress: '203.0.113.5', metadata: { surface: 'websocket' } }),
);
});
it('rejects a connection when validateApiKey throws (the real auth-failure contract)', async () => {
authService.validateApiKey.mockRejectedValue(new UnauthorizedException('Invalid API key'));
const sock = makeSocket({ apiKey: 'bad' });
await gateway.handleConnection(asSocket(sock));
expect(sock.disconnect).toHaveBeenCalled();
});
it('accepts a valid key via handshake.auth and stores the raw key for re-validation', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
expect(sock.disconnect).not.toHaveBeenCalled();
expect(sock.data.rawApiKey).toBe('good');
});
it('accepts a chat-restricted key without granting global event rooms at the handshake', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null, allowedChats: ['[email protected]'] });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
expect(sock.disconnect).not.toHaveBeenCalled();
expect(sessionRoomJoins(sock)).toEqual([]);
expect(auditService.logWarn).not.toHaveBeenCalled();
});
it('refuses a subscribe once the key has gained allowedChats after connect', async () => {
authService.validateApiKey.mockResolvedValueOnce({ name: 'k', allowedSessions: null }); // connect
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
expect(sock.disconnect).not.toHaveBeenCalled();
authService.validateApiKey.mockResolvedValueOnce({ name: 'k', allowedSessions: null, allowedChats: ['[email protected]'] });
const res = (await gateway.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['*']))) as WSErrorResponse;
expect(res.code).toBe('UNAUTHORIZED');
expect(sock.disconnect).toHaveBeenCalled();
expect(sessionRoomJoins(sock)).toEqual([]);
expect(unauthorizedEmits(sock)).toHaveLength(1);
expect(auditService.logWarn).toHaveBeenCalledWith(
AuditAction.API_KEY_AUTH_FAILED,
expect.objectContaining({
apiKey: expect.objectContaining({ allowedChats: ['[email protected]'] }) as unknown,
ipAddress: '203.0.113.5',
metadata: { surface: 'websocket' },
}),
);
});
it('re-validates on subscribe and disconnects a key revoked after connect', async () => {
authService.validateApiKey.mockResolvedValueOnce({ name: 'k', allowedSessions: null }); // connect
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
// validateApiKey throws on a revoked key; it never resolves to a falsy value.
authService.validateApiKey.mockRejectedValueOnce(new UnauthorizedException('API key revoked'));
const res = (await gateway.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['*']))) as WSErrorResponse;
expect(sock.disconnect).toHaveBeenCalled();
expect(res.code).toBe('UNAUTHORIZED');
expect(unauthorizedEmits(sock)).toHaveLength(1);
expect(auditService.logWarn).toHaveBeenCalledWith(AuditAction.API_KEY_AUTH_FAILED, {
ipAddress: '203.0.113.5',
metadata: { surface: 'websocket' },
errorMessage: 'API key revoked',
});
});
it('allows subscribe when the key still re-validates', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
const res = (await gateway.handleMessage(
asSocket(sock),
subscribeMsg('sess-1', ['session.status']),
)) as WSSubscribedResponse;
expect(res.type).toBe('subscribed');
expect(sock.join).toHaveBeenCalled();
});
it('accepts a subscription to group.join (a live, engine-emitted event)', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
const res = (await gateway.handleMessage(
asSocket(sock),
subscribeMsg('sess-1', ['group.join']),
)) as WSSubscribedResponse;
expect(res.type).toBe('subscribed');
expect(res.events).toEqual(['group.join']);
expect(sock.join).toHaveBeenCalledWith(buildRoomName('sess-1', 'group.join'));
});
it('rejects a subscription to an unknown, never-emitted event with INVALID_EVENTS', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
const res = (await gateway.handleMessage(
asSocket(sock),
subscribeMsg('sess-1', ['session.connected']),
)) as WSErrorResponse;
expect(res.type).toBe('error');
expect(res.code).toBe('INVALID_EVENTS');
expect(sessionRoomJoins(sock)).toEqual([]);
});
it('keeps the valid events when a subscription mixes a valid and an unknown event', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
const res = (await gateway.handleMessage(
asSocket(sock),
subscribeMsg('sess-1', ['message.received', 'session.connected']),
)) as WSSubscribedResponse;
expect(res.type).toBe('subscribed');
expect(res.events).toEqual(['message.received']);
expect(sock.join).toHaveBeenCalledWith(buildRoomName('sess-1', 'message.received'));
});
// Cross-tenant guard (#221): a session-scoped key must not subscribe to a foreign session or '*'.
// The pure predicate is covered above; these drive it through handleSubscribe so a regression that
// drops the check (or reads the stale connect-time key) is caught end-to-end.
it('forbids a session-scoped key from subscribing to a session outside its allowlist', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: ['sess-1'] });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
const res = (await gateway.handleMessage(asSocket(sock), subscribeMsg('sess-2', ['*']))) as WSErrorResponse;
expect(res.type).toBe('error');
expect(res.code).toBe('FORBIDDEN_SESSION');
expect(sessionRoomJoins(sock)).toEqual([]);
});
// The session id becomes part of every room name the socket keeps until it disconnects, so an
// oversized or malformed one must be refused before it costs a key lookup or a room.
it.each([
['oversized', 'a'.repeat(129)],
['malformed', 'sess:1'],
])('refuses a %s sessionId with INVALID_SESSION', async (_label, sessionId) => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
authService.validateApiKey.mockClear();
const res = (await gateway.handleMessage(asSocket(sock), subscribeMsg(sessionId, ['*']))) as WSErrorResponse;
expect(res.code).toBe('INVALID_SESSION');
expect(authService.validateApiKey).not.toHaveBeenCalled();
expect(sessionRoomJoins(sock)).toEqual([]);
});
it('refuses a subscribe that would take the socket past its room cap', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
for (let i = 0; i < 4096; i++) sock.rooms.add(buildRoomName(`s${i}`, '*'));
const res = (await gateway.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['*']))) as WSErrorResponse;
expect(res.code).toBe('TOO_MANY_SUBSCRIPTIONS');
expect(sessionRoomJoins(sock)).toEqual([]);
// Re-subscribing a room the socket already holds adds nothing, so it is still granted.
const again = (await gateway.handleMessage(asSocket(sock), subscribeMsg('s1', ['*']))) as WSSubscribedResponse;
expect(again.type).toBe('subscribed');
});
it('counts only subscription rooms toward the cap, not the own-id or role rooms', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
sock.rooms.add(QR_DENIED_ROOM);
for (let i = 0; i < 4095; i++) sock.rooms.add(buildRoomName(`s${i}`, '*'));
const res = (await gateway.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['*']))) as WSSubscribedResponse;
expect(res.type).toBe('subscribed');
expect(sessionRoomJoins(sock)).toEqual([buildRoomName('sess-1', '*')]);
});
it('pushes a command reply on the message event, not only through the ack callback', async () => {
// The Socket.IO adapter delivers a handler's return value through the ack callback and nothing
// else, so a client that emits without one (the dashboard, and the documented example client)
// saw no answer at all: no subscribe confirmation, and none of the refusals.
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: ['sess-1'] });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
sock.emit.mockClear();
const granted = (await gateway.handleMessage(
asSocket(sock),
subscribeMsg('sess-1', ['message.received']),
)) as WSSubscribedResponse;
expect(sock.emit).toHaveBeenCalledWith('message', granted);
sock.emit.mockClear();
const refused = (await gateway.handleMessage(asSocket(sock), subscribeMsg('sess-2', ['*']))) as WSErrorResponse;
expect(refused.code).toBe('FORBIDDEN_SESSION');
expect(sock.emit).toHaveBeenCalledWith('message', refused);
sock.emit.mockClear();
const pong = await gateway.handleMessage(asSocket(sock), { type: 'ping' } as unknown as WSClientMessage);
expect(sock.emit).toHaveBeenCalledWith('message', pong);
sock.emit.mockClear();
const unsubscribed = await gateway.handleMessage(asSocket(sock), {
type: 'unsubscribe',
sessionId: 'sess-1',
events: ['message.received'],
} as unknown as WSClientMessage);
expect(sock.emit).toHaveBeenCalledWith('message', unsubscribed);
sock.emit.mockClear();
const unknown = await gateway.handleMessage(asSocket(sock), { type: 'nonsense' } as unknown as WSClientMessage);
expect((unknown as WSErrorResponse).code).toBe('INVALID_MESSAGE');
expect(sock.emit).toHaveBeenCalledWith('message', unknown);
// A 'message' emitted with no payload, or with null, is answered like any unknown frame rather
// than throwing inside the handler.
for (const nil of [undefined, null]) {
sock.emit.mockClear();
const invalid = await gateway.handleMessage(asSocket(sock), nil);
expect((invalid as WSErrorResponse).code).toBe('INVALID_MESSAGE');
expect(sock.emit).toHaveBeenCalledTimes(1);
expect(sock.emit).toHaveBeenCalledWith('message', invalid);
}
});
it('holds a frame that arrives while the handshake is still validating until it completes', async () => {
// socket.io sends CONNECT before Nest runs handleConnection, so a client that subscribes from its
// 'connect' handler can land here before the key is stored on the socket.
let finishHandshake!: (key: unknown) => void;
authService.validateApiKey.mockReturnValueOnce(new Promise(resolve => (finishHandshake = resolve)));
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
const connecting = gateway.handleConnection(asSocket(sock));
const subscribing = gateway.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['message.received']));
finishHandshake({ id: 'k1', name: 'k', allowedSessions: null });
await connecting;
const res = (await subscribing) as WSSubscribedResponse;
expect(res.type).toBe('subscribed');
expect(sock.disconnect).not.toHaveBeenCalled();
expect(sessionRoomJoins(sock)).toEqual([buildRoomName('sess-1', 'message.received')]);
});
it('drops a frame that arrived during a handshake that was then refused', async () => {
let failHandshake!: (err: Error) => void;
authService.validateApiKey.mockReturnValueOnce(new Promise((_, reject) => (failHandshake = reject)));
const sock = makeSocket({ apiKey: 'bad' });
sock.disconnect.mockImplementation(() => (sock.disconnected = true));
const connecting = gateway.handleConnection(asSocket(sock));
const subscribing = gateway.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['message.received']));
failHandshake(new UnauthorizedException('Invalid API key'));
await connecting;
expect(await subscribing).toBeUndefined();
// Only the handshake's own refusal reached the client, and the frame never re-validated.
expect(sock.emit).toHaveBeenCalledTimes(1);
expect(authService.validateApiKey).toHaveBeenCalledTimes(1);
expect(sessionRoomJoins(sock)).toEqual([]);
});
it('answers an unsubscribe without a sessionId with INVALID_SESSION and leaves the rooms alone', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
sock.rooms.add(buildRoomName('sess-1', 'message.received'));
for (const sessionId of [undefined, null, 5]) {
const res = (await gateway.handleMessage(asSocket(sock), {
type: 'unsubscribe',
sessionId,
requestId: 'r1',
} as unknown as WSClientMessage)) as WSErrorResponse;
expect(res.code).toBe('INVALID_SESSION');
expect(res.requestId).toBe('r1');
}
expect(sock.leave).not.toHaveBeenCalledWith(buildRoomName('sess-1', 'message.received'));
});
// An unsubscribe is answered with the session id it names, so it is bound like the one a subscribe
// accepts: a reply holds only "*" or a short session id, never whatever string the client sent.
it.each([
['oversized', 'a'.repeat(129)],
['malformed', 'sess:1'],
])('refuses an unsubscribe with a %s sessionId instead of echoing it', async (_label, sessionId) => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
sock.rooms.add(buildRoomName('sess-1', 'message.received'));
const res = (await gateway.handleMessage(asSocket(sock), {
type: 'unsubscribe',
sessionId,
requestId: 'r1',
} as unknown as WSClientMessage)) as WSErrorResponse;
expect(res.code).toBe('INVALID_SESSION');
expect(res.requestId).toBe('r1');
expect(JSON.stringify(sock.emit.mock.calls)).not.toContain(sessionId);
expect(sock.leave).not.toHaveBeenCalled();
});
it('still answers an unsubscribe from "*" and from a session id at the length limit', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
const longest = 'a'.repeat(128);
sock.rooms.add(buildRoomName(longest, 'message.received'));
sock.rooms.add(buildRoomName('sess-2', 'message.received'));
const one = await gateway.handleMessage(asSocket(sock), { type: 'unsubscribe', sessionId: longest } as never);
expect(one).toMatchObject({ type: 'unsubscribed', sessionId: longest });
expect(sock.leave).toHaveBeenCalledTimes(1);
expect(sock.leave).toHaveBeenCalledWith(buildRoomName(longest, 'message.received'));
const all = await gateway.handleMessage(asSocket(sock), { type: 'unsubscribe', sessionId: '*' } as never);
expect(all).toMatchObject({ type: 'unsubscribed', sessionId: '*' });
expect(sock.leave).toHaveBeenCalledWith(buildRoomName('sess-2', 'message.received'));
});
it('forbids a session-scoped key from subscribing to the * wildcard', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: ['sess-1'] });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
const res = (await gateway.handleMessage(
asSocket(sock),
subscribeMsg('*', ['message.received']),
)) as WSErrorResponse;
expect(res.code).toBe('FORBIDDEN_SESSION');
expect(sessionRoomJoins(sock)).toEqual([]);
});
it('allows a session-scoped key to subscribe to a session in its allowlist', async () => {
authService.validateApiKey.mockResolvedValue({ name: 'k', allowedSessions: ['sess-1'] });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
const res = (await gateway.handleMessage(
asSocket(sock),
subscribeMsg('sess-1', ['message.received']),
)) as WSSubscribedResponse;
expect(res.type).toBe('subscribed');
expect(sock.join).toHaveBeenCalledWith(buildRoomName('sess-1', 'message.received'));
});
it('enforces scope using the FRESH re-validated key, not the connect-time key', async () => {
// Connect with an unrestricted key, but the key is narrowed to ['sess-1'] by the subscribe re-check.
authService.validateApiKey.mockResolvedValueOnce({ name: 'k', allowedSessions: null }); // connect
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
authService.validateApiKey.mockResolvedValueOnce({ name: 'k', allowedSessions: ['sess-1'] }); // subscribe re-check
const res = (await gateway.handleMessage(
asSocket(sock),
subscribeMsg('sess-2', ['message.received']),
)) as WSErrorResponse;
expect(res.code).toBe('FORBIDDEN_SESSION');
expect(sessionRoomJoins(sock)).toEqual([]);
});
describe('pending subscription cancellation', () => {
const pendingSubscribe = async (sessionId = 'sess-1') => {
const apiKey = { id: 'k1', name: 'k', role: 'viewer', allowedSessions: null };
authService.validateApiKey.mockResolvedValue(apiKey);
const sock = makeSocket({ apiKey: 'good' });
sock.join.mockImplementation((room: string) => sock.rooms.add(room));
sock.leave.mockImplementation((room: string) => sock.rooms.delete(room));
await gateway.handleConnection(asSocket(sock));
let resolve!: (key: typeof apiKey) => void;
let reject!: (error: Error) => void;
const validation = new Promise<typeof apiKey>((yes, no) => {
resolve = yes;
reject = no;
});
let entered!: () => void;
const started = new Promise<void>(yes => (entered = yes));
authService.validateApiKey.mockImplementationOnce(() => {
entered();
return validation;
});
const subscribing = gateway.handleMessage(asSocket(sock), subscribeMsg(sessionId, ['message.received']));
await started;
return { sock, apiKey, resolve, reject, subscribing };
};
const pendingFor = (sock: MockSocket) =>
(gateway as unknown as { pendingSubscriptions: WeakMap<Socket, Set<unknown>> }).pendingSubscriptions.get(
asSocket(sock),
);
it.each([
['sess-1', 'sess-1'],
['sess-1', '*'],
['*', '*'],
])('cancels a pending subscribe to %s when unsubscribing from %s', async (sessionId, unsubscribe) => {
const pending = await pendingSubscribe(sessionId);
expect(
await gateway.handleMessage(asSocket(pending.sock), { type: 'unsubscribe', sessionId: unsubscribe }),
).toMatchObject({ type: 'unsubscribed' });
pending.resolve(pending.apiKey);
expect(await pending.subscribing).toMatchObject({ code: 'SUBSCRIPTION_CANCELLED', requestId: 'r1' });
expect(sessionRoomJoins(pending.sock)).toEqual([]);
expect(pendingFor(pending.sock)).toBeUndefined();
expect(
await gateway.handleMessage(asSocket(pending.sock), subscribeMsg(sessionId, ['message.received'])),
).toMatchObject({ type: 'subscribed' });
expect(pending.sock.rooms.has(buildRoomName(sessionId, 'message.received'))).toBe(true);
});
it('does not cancel a pending subscribe when another session is unsubscribed', async () => {
const pending = await pendingSubscribe();
expect(
await gateway.handleMessage(asSocket(pending.sock), { type: 'unsubscribe', sessionId: 'sess-2' }),
).toMatchObject({ type: 'unsubscribed' });
pending.resolve(pending.apiKey);
expect(await pending.subscribing).toMatchObject({ type: 'subscribed' });
expect(pending.sock.rooms.has(buildRoomName('sess-1', 'message.received'))).toBe(true);
});
it('still refuses failed authorization after a cancellation and clears the pending subscription', async () => {
const pending = await pendingSubscribe();
await gateway.handleMessage(asSocket(pending.sock), { type: 'unsubscribe', sessionId: '*' });
pending.reject(new UnauthorizedException('API key revoked'));
expect(await pending.subscribing).toMatchObject({ code: 'UNAUTHORIZED' });
expect(pending.sock.disconnected).toBe(true);
expect(sessionRoomJoins(pending.sock)).toEqual([]);
expect(pendingFor(pending.sock)).toBeUndefined();
});
});
// Client-IP resolution: an IP-restricted key (allowedIps set) must be ENFORCED at the WS surface,
// not blanket-rejected. validateApiKey throws "Client IP could not be determined" when allowedIps is
// set but no clientIp is supplied — so the gateway must pass the trusted-proxy-aware IP at connect
// and at subscribe re-validation. Without the fix every IP-restricted key was locked out of WS.
it('passes the trusted-proxy-aware client IP to validateApiKey at connect (RED-without-fix: undefined)', async () => {
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' }); // address defaults to 203.0.113.5
await gateway.handleConnection(asSocket(sock));
expect(authService.validateApiKey).toHaveBeenCalledWith('good', '203.0.113.5');
expect(sock.disconnect).not.toHaveBeenCalled();
});
it('passes the resolved client IP to validateApiKey on subscribe re-validation', async () => {
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
authService.validateApiKey.mockClear();
await gateway.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['message.received']));
expect(authService.validateApiKey).toHaveBeenCalledWith('good', '203.0.113.5');
});
it('honors TRUSTED_PROXIES + X-Forwarded-For when resolving the WS client IP', async () => {
const prev = process.env.TRUSTED_PROXIES;
process.env.TRUSTED_PROXIES = '10.0.0.1';
try {
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
sock.handshake.address = '10.0.0.1'; // immediate peer is the trusted proxy
sock.handshake.headers['x-forwarded-for'] = '198.51.100.7';
await gateway.handleConnection(asSocket(sock));
expect(authService.validateApiKey).toHaveBeenCalledWith('good', '198.51.100.7');
} finally {
process.env.TRUSTED_PROXIES = prev;
}
});
// Revocation teardown: a revoked key's already-subscribed sockets are evicted immediately,
// with a clean close (an UNAUTHORIZED reason) rather than lingering until natural disconnect.
describe('evictApiKey (revoke/disable socket teardown)', () => {
it('disconnects every active socket authenticated with the revoked key', async () => {
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
expect(sock.disconnect).not.toHaveBeenCalled();
gateway.evictApiKey('k1');
expect(sock.disconnect).toHaveBeenCalledWith(true);
expect(sock.emit).toHaveBeenCalledWith('message', expect.objectContaining({ code: 'UNAUTHORIZED' }));
});
it('does NOT evict sockets authenticated with a different (still-active) key', async () => {
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
gateway.evictApiKey('some-other-key');
expect(sock.disconnect).not.toHaveBeenCalled();
});
it('is a no-op when no sockets are tracked for the key', () => {
expect(() => gateway.evictApiKey('nobody')).not.toThrow();
});
it('cleans up tracking on disconnect so an evicted key holds no stale socket refs', async () => {
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const sock = makeSocket({ apiKey: 'good' });
await gateway.handleConnection(asSocket(sock));
gateway.evictApiKey('k1');
// Socket.IO fires the disconnect handler on disconnect(true); simulate it here to confirm
// untracking is idempotent and leaves no dangling references.
gateway.handleDisconnect(asSocket(sock));
expect(() => gateway.evictApiKey('k1')).not.toThrow();
});
// The periodic sweep (expiry, revocation, deletion, narrowing) reads the api_keys table, so it is
// exercised against a real one in events.gateway.authz-sweep.spec.ts rather than a stub here.
});
it('runs the authorization sweep every minute from afterInit until onModuleDestroy', async () => {
jest.useFakeTimers();
try {
const sweep = jest
.spyOn(gateway as unknown as { sweepApiKeyAuthorization: () => Promise<void> }, 'sweepApiKeyAuthorization')
.mockRejectedValueOnce(new Error('database is locked'))
.mockResolvedValue(undefined);
gateway.afterInit();
await jest.advanceTimersByTimeAsync(60_000);
expect(sweep).toHaveBeenCalledTimes(1);
// A failed tick is logged, and the next one still runs.
await jest.advanceTimersByTimeAsync(60_000);
expect(sweep).toHaveBeenCalledTimes(2);
gateway.onModuleDestroy();
await jest.advanceTimersByTimeAsync(120_000);
expect(sweep).toHaveBeenCalledTimes(2);
} finally {
jest.useRealTimers();
}
});
});
// A capturing, chainable Socket.IO server stub: server.to(r1).to(r2)...emit(...) all
// resolve to one operator whose emit() we count. Mirrors the real BroadcastOperator,
// where chained .to() accumulates rooms into a single deduped broadcast.
const makeCapturingServer = () => {
const rooms: string[] = [];
const emit = jest.fn();
const op: { to: jest.Mock; except: jest.Mock; emit: jest.Mock } = { to: jest.fn(), except: jest.fn(), emit };
op.to.mockImplementation((r: string) => {
rooms.push(r);
return op;
});
op.except.mockImplementation(() => op);
const server = { to: jest.fn((r: string) => (rooms.push(r), op)) };
return { server, emit, rooms };
};
describe('EventsGateway inline-media shedding on message events', () => {
const gwWithCap = (cap?: number) => {
const config = {
get: jest.fn((_key: string, defaultValue?: unknown) => (cap === undefined ? defaultValue : cap)),
};
return new EventsGateway(
{ validateApiKey: jest.fn() } as unknown as AuthService,
{ logWarn: jest.fn().mockResolvedValue(null) } as unknown as AuditService,
config as unknown as ConfigService,
);
};
const bigMedia = (): Record<string, unknown> => ({
id: 'm1',
media: { mimetype: 'image/jpeg', filename: 'big.jpg', data: 'A'.repeat(1024 * 1024 * 2) }, // ~1.5 MB decoded
});
it('replaces an over-cap inline media blob with the omitted marker on message.received', () => {
const gateway = gwWithCap();
const { server, emit } = makeCapturingServer();
(gateway as unknown as { server: unknown }).server = server;
const message = bigMedia();
gateway.emitMessage('sess-1', message);
const [, sent] = emit.mock.calls[0] as [string, WSEventMessage];
expect(sent.payload.event).toBe('message.received');
const media = (sent.payload.data as Record<string, unknown>).media as Record<string, unknown>;
expect(media.omitted).toBe(true);
expect(media.data).toBeUndefined();
expect(media.mimetype).toBe('image/jpeg');
expect(media.filename).toBe('big.jpg');
expect(typeof media.sizeBytes).toBe('number');
// The caller's event object is never mutated: the webhook fan-out receives the same object.
expect((message.media as Record<string, unknown>).data).toHaveLength(1024 * 1024 * 2);
});
it('sheds on message.sent with the same contract', () => {
const gateway = gwWithCap();
const { server, emit } = makeCapturingServer();
(gateway as unknown as { server: unknown }).server = server;
gateway.emitMessageSent('sess-1', bigMedia());
const [, sent] = emit.mock.calls[0] as [string, WSEventMessage];
expect(sent.payload.event).toBe('message.sent');
expect(((sent.payload.data as Record<string, unknown>).media as Record<string, unknown>).omitted).toBe(true);
});
it('passes small inline media through untouched', () => {
const gateway = gwWithCap();
const { server, emit } = makeCapturingServer();
(gateway as unknown as { server: unknown }).server = server;
const small = { id: 'm2', media: { mimetype: 'image/png', data: 'aGk=' } };
gateway.emitMessage('sess-1', small);
const [, sent] = emit.mock.calls[0] as [string, WSEventMessage];
expect((sent.payload.data as Record<string, unknown>).media).toEqual({ mimetype: 'image/png', data: 'aGk=' });
});
it('honors a tightened cap (0 sheds every inline blob, matching the webhook knob semantics)', () => {
const gateway = gwWithCap(0);
const { server, emit } = makeCapturingServer();
(gateway as unknown as { server: unknown }).server = server;
gateway.emitMessage('sess-1', { id: 'm3', media: { mimetype: 'image/png', data: 'aGk=' } });
const [, sent] = emit.mock.calls[0] as [string, WSEventMessage];
expect(((sent.payload.data as Record<string, unknown>).media as Record<string, unknown>).omitted).toBe(true);
});
});
describe('EventsGateway.emitToRooms fan-out', () => {
const gw = () =>
new EventsGateway(
{ validateApiKey: jest.fn() } as unknown as AuthService,
{ logWarn: jest.fn().mockResolvedValue(null) } as unknown as AuditService,
asConfig() as unknown as ConfigService,
);
it('delivers one event with a single broadcast across all four rooms (no per-room duplicate emit)', () => {
const gateway = gw();
const { server, emit, rooms } = makeCapturingServer();
(gateway as unknown as { server: unknown }).server = server;
gateway.emitMessage('sess-1', { id: 'm1' });
// One broadcast, not one-emit-per-room: a socket in several of the rooms gets it once.
expect(emit).toHaveBeenCalledTimes(1);
const [channel, message] = emit.mock.calls[0] as [string, WSEventMessage];
expect(channel).toBe('message');
expect(message.type).toBe('event');
expect(message.payload.event).toBe('message.received');
expect(message.payload.sessionId).toBe('sess-1');
// Still targets the specific room plus the three wildcard rooms.
expect(new Set(rooms)).toEqual(
new Set([
buildRoomName('sess-1', 'message.received'),
buildRoomName('sess-1', '*'),
buildRoomName('*', 'message.received'),
buildRoomName('*', '*'),
]),
);
});
});
// session.qr is a pairing credential: GET /sessions/:sessionId/qr requires OPERATOR, so the socket push
// must not hand it to a VIEWER key under any subscribe form. The stub below stands in for the Socket.IO
// adapter: it tracks each socket's rooms and resolves to()/except() like a real broadcast (union of the
// target rooms, minus sockets in an excluded room, one copy per socket).
describe('EventsGateway session.qr role gate', () => {
interface RoomSocket {
id: string;
handshake: { headers: Record<string, string>; auth: { apiKey: string }; address: string };
data: Record<string, unknown>;
rooms: Set<string>;
received: WSEventMessage[];
emit: jest.Mock;
disconnect: jest.Mock;
join: (room: string) => void;
leave: (room: string) => void;
}
type Broadcast = {
to: (room: string) => Broadcast;
except: (room: string) => Broadcast;
emit: (channel: string, msg: WSEventMessage) => boolean;
};
let keys: Record<string, { id: string; name: string; role: string; allowedSessions: string[] | null }>;
let gateway: EventsGateway;
let sockets: RoomSocket[];
const broadcast = (to: string[], except: string[]): Broadcast => ({
to: room => broadcast([...to, room], except),
except: room => broadcast(to, [...except, room]),
emit: (_channel, msg) => {
for (const s of sockets) {
if (to.some(r => s.rooms.has(r)) && !except.some(r => s.rooms.has(r))) s.received.push(msg);
}
return true;
},
});
const connect = async (apiKey: string): Promise<RoomSocket> => {
const rooms = new Set<string>();
const sock: RoomSocket = {
id: `sock-${sockets.length}`,
handshake: { headers: {}, auth: { apiKey }, address: '203.0.113.5' },
data: {},
rooms,
received: [],
emit: jest.fn(),
disconnect: jest.fn(),
join: room => void rooms.add(room),
leave: room => void rooms.delete(room),
};
sockets.push(sock);
await gateway.handleConnection(sock as unknown as Socket);
return sock;
};
const subscribe = (sock: RoomSocket, sessionId: string, events: string[]) =>
gateway.handleMessage(
sock as unknown as Socket,
{
type: 'subscribe',
sessionId,
events,
requestId: 'r1',
} as unknown as WSClientMessage,
);
const qrEvents = (sock: RoomSocket) => sock.received.filter(m => m.payload.event === 'session.qr');
beforeEach(() => {
sockets = [];
keys = {
viewer: { id: 'k-viewer', name: 'viewer', role: 'viewer', allowedSessions: null },
operator: { id: 'k-operator', name: 'operator', role: 'operator', allowedSessions: null },
admin: { id: 'k-admin', name: 'admin', role: 'admin', allowedSessions: null },
};
gateway = new EventsGateway(
{ validateApiKey: jest.fn((raw: string) => Promise.resolve({ ...keys[raw] })) } as unknown as AuthService,
{ logWarn: jest.fn().mockResolvedValue(null) } as unknown as AuditService,
asConfig() as unknown as ConfigService,
);
(gateway as unknown as { server: unknown }).server = { to: (room: string) => broadcast([room], []) };
});
it('never delivers the QR to a VIEWER socket, whatever it subscribed to, while OPERATOR and ADMIN get it', async () => {
const viewerByName = await connect('viewer');
const viewerSessionWildcard = await connect('viewer');
const viewerGlobalWildcard = await connect('viewer');
const viewerEventWildcard = await connect('viewer');
const operator = await connect('operator');
const admin = await connect('admin');
await subscribe(viewerByName, 'sess-1', ['session.qr']);
await subscribe(viewerSessionWildcard, 'sess-1', ['*']);
await subscribe(viewerGlobalWildcard, '*', ['*']);
await subscribe(viewerEventWildcard, '*', ['session.qr']);
await subscribe(operator, '*', ['*']);
await subscribe(admin, 'sess-1', ['session.qr']);
gateway.emitQRCode('sess-1', 'data:image/png;base64,QR');
for (const viewer of [viewerByName, viewerSessionWildcard, viewerGlobalWildcard, viewerEventWildcard]) {
expect(qrEvents(viewer)).toEqual([]);
}
expect(qrEvents(operator)).toHaveLength(1);
expect(qrEvents(operator)[0].payload.data).toEqual({ qrCode: 'data:image/png;base64,QR' });
expect(qrEvents(admin)).toHaveLength(1);
});
it('keeps delivering every other event to a VIEWER wildcard subscription', async () => {
const viewer = await connect('viewer');
await subscribe(viewer, '*', ['*']);
gateway.emitSessionStatus('sess-1', 'qr_ready');
expect(viewer.received.map(m => m.payload.event)).toEqual(['session.status']);
});
it('follows the role re-validated on subscribe: a narrowed key stops receiving the QR, a widened one starts', async () => {
const narrowed = await connect('operator');
const widened = await connect('viewer');
await subscribe(widened, 'sess-1', ['*']);
expect(widened.rooms.has(QR_DENIED_ROOM)).toBe(true);
keys.operator.role = 'viewer';
keys.viewer.role = 'operator';
await subscribe(narrowed, 'sess-1', ['*']);
await subscribe(widened, 'sess-1', ['*']);
gateway.emitQRCode('sess-1', 'data:image/png;base64,QR');
expect(qrEvents(narrowed)).toEqual([]);
expect(qrEvents(widened)).toHaveLength(1);
});
it('denies the QR to a key with an unrecognised role', async () => {
keys.viewer.role = 'unknown';
const sock = await connect('viewer');
await subscribe(sock, 'sess-1', ['session.qr']);
gateway.emitQRCode('sess-1', 'data:image/png;base64,QR');
expect(sock.rooms.has(QR_DENIED_ROOM)).toBe(true);
expect(qrEvents(sock)).toEqual([]);
});
it('delivers message.receipt only to sockets that named it, never through a wildcard', async () => {
const wildcard = await connect('operator');
await subscribe(wildcard, '*', ['*']);
const sessionWildcard = await connect('operator');
await subscribe(sessionWildcard, 'sess-1', ['*']);
const named = await connect('operator');
await subscribe(named, 'sess-1', ['message.receipt']);
const namedAllSessions = await connect('operator');
await subscribe(namedAllSessions, '*', ['message.receipt']);
gateway.emitMessageReceipt('sess-1', {
id: 'OUT1',
messageId: 'OUT1',
chatId: '[email protected]',
participant: '[email protected]',
status: 'read',
timestamp: 1700000000,
});
const events = (s: RoomSocket): string[] => s.received.map(m => m.payload.event);
expect(events(wildcard)).toEqual([]);
expect(events(sessionWildcard)).toEqual([]);
expect(events(named)).toEqual(['message.receipt']);
expect(events(namedAllSessions)).toEqual(['message.receipt']);
});
});
describe('event catalog ⇔ emitter invariants (drift guard)', () => {
// Derive the events the gateway ACTUALLY emits by invoking every public emit* room
// method against a capturing server. Reflection-based so it cannot rot: a new emit*
// method is auto-discovered; an advertised-but-unemitted event fails the equality.
const deriveEmittedEvents = (): Set<string> => {
const gateway = new EventsGateway(
{ validateApiKey: jest.fn() } as unknown as AuthService,
{ logWarn: jest.fn().mockResolvedValue(null) } as unknown as AuditService,
asConfig() as unknown as ConfigService,
);
const captured: string[] = [];
const op: { to: () => unknown; except: () => unknown; emit: (ch: string, msg: WSEventMessage) => boolean } = {
to: () => op,
except: () => op,
emit: (_ch, msg) => (captured.push(msg.payload.event), true),
};
(gateway as unknown as { server: unknown }).server = { to: () => op };
const proto = Object.getPrototypeOf(gateway) as object;
const emitMethods = Object.getOwnPropertyNames(proto).filter(n => n.startsWith('emit') && n !== 'emitToRooms');
for (const name of emitMethods) {
(gateway as unknown as Record<string, (...a: unknown[]) => void>)[name]('sess-1', {});
}
return new Set(captured);
};
it('every advertised SUBSCRIBABLE_EVENT has a gateway emitter, and every emitter is advertised', () => {
expect(new Set(SUBSCRIBABLE_EVENTS)).toEqual(deriveEmittedEvents());
});
it('reserved webhook events (currently none) never overlap the socket-subscribable catalog', () => {
// WEBHOOK_RESERVED_EVENTS is intentionally empty — the former group.* occupants are now live,
// engine-emitted (and socket-subscribable) events covered by the equality guard above. The
// export stays so a future declared-but-undispatched event can be whitelisted there; whenever
// the list is non-empty, no reserved event may also be advertised as subscribable.
expect(WEBHOOK_RESERVED_EVENTS).toHaveLength(0);
for (const reserved of WEBHOOK_RESERVED_EVENTS) {
expect(SUBSCRIBABLE_EVENTS).not.toContain(reserved);
}
});
});
// Rate limiting on the WS surface: the gateway sits outside the Nest guard pipeline, so the
// per-key frame bucket, the pre-auth per-IP handshake window, and the per-key socket cap are
// all enforced inside EventsGateway. The gateway reads its config from the env at construction,
// so these tests pin the WS_* env vars per test (and restore them afterwards).
describe('EventsGateway rate limiting', () => {
const WS_ENV_KEYS = [
'WS_RATE_LIMIT_FRAME_PER_SECOND',
'WS_RATE_LIMIT_FRAME_BURST',
'WS_RATE_LIMIT_HANDSHAKE_MAX',
'WS_RATE_LIMIT_HANDSHAKE_WINDOW_MS',
'WS_MAX_SOCKETS_PER_KEY',
] as const;
let gateway: EventsGateway;
let authService: { validateApiKey: jest.Mock };
let auditService: { logWarn: jest.Mock };
let savedEnv: Record<string, string | undefined>;
const makeSock = (id: string, auth: { apiKey?: string } = {}, address = '203.0.113.5'): MockSocket => ({
id,
handshake: { headers: {}, query: {}, auth, address },
data: {},
emit: jest.fn(),
disconnect: jest.fn(),
join: jest.fn(),
leave: jest.fn(),
rooms: new Set<string>(),
});
const asSocket = (s: MockSocket): Socket => s as unknown as Socket;
const subscribeMsg = (sessionId: string, events: string[]): WSClientMessage =>
({ type: 'subscribe', sessionId, events, requestId: 'r1' }) as unknown as WSClientMessage;
beforeEach(() => {
savedEnv = {};
for (const key of WS_ENV_KEYS) {
savedEnv[key] = process.env[key];
delete process.env[key];
}
authService = { validateApiKey: jest.fn() };
auditService = { logWarn: jest.fn().mockResolvedValue(null) };
});
afterEach(() => {
for (const key of WS_ENV_KEYS) {
if (savedEnv[key] === undefined) delete process.env[key];
else process.env[key] = savedEnv[key];
}
jest.useRealTimers();
});
const buildGateway = (): EventsGateway => {
gateway = new EventsGateway(
authService as unknown as AuthService,
auditService as unknown as AuditService,
asConfig() as unknown as ConfigService,
);
return gateway;
};
// Typed view over the audit mock's calls so assertions on action/metadata don't wade through `any`.
interface WarnContext {
metadata?: Record<string, unknown>;
}
const warnCalls = (): [AuditAction, WarnContext?][] =>
auditService.logWarn.mock.calls as [AuditAction, WarnContext?][];
describe('per-key frame token bucket', () => {
it('rejects the frame above the bucket with a RATE_LIMITED error frame and never reaches the handler', async () => {
process.env.WS_RATE_LIMIT_FRAME_PER_SECOND = '2';
process.env.WS_RATE_LIMIT_FRAME_BURST = '3';
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const gw = buildGateway();
const sock = makeSock('s1', { apiKey: 'good' });
await gw.handleConnection(asSocket(sock));
expect(authService.validateApiKey).toHaveBeenCalledTimes(1);
// The 3-frame burst passes; each subscribe re-validates the key.
for (let i = 0; i < 3; i++) {
const res = (await gw.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['session.status']))) as {
type: string;
};
expect(res.type).toBe('subscribed');
}
expect(authService.validateApiKey).toHaveBeenCalledTimes(4);
// The frame above the bucket: error frame back to the client, and NOT dispatched —
// in particular it never reaches the per-subscribe DB re-validation.
const res = (await gw.handleMessage(
asSocket(sock),
subscribeMsg('sess-1', ['session.status']),
)) as WSErrorResponse;
expect(res.type).toBe('error');
expect(res.code).toBe('RATE_LIMITED');
expect(sock.emit).toHaveBeenCalledWith('message', expect.objectContaining({ code: 'RATE_LIMITED' }));
expect(authService.validateApiKey).toHaveBeenCalledTimes(4);
});
it('lets a normal dashboard connect-time subscribe burst (8 frames) through untouched', async () => {
// Defaults: 60 frames/s sustained + 120 burst — far above a page-mount burst.
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const gw = buildGateway();
const sock = makeSock('s1', { apiKey: 'good' });
await gw.handleConnection(asSocket(sock));
for (let i = 0; i < 8; i++) {
const res = (await gw.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['session.status']))) as {
type: string;
};
expect(res.type).toBe('subscribed');
}
});
it('recovers after the refill window: a throttled key can send again', async () => {
process.env.WS_RATE_LIMIT_FRAME_PER_SECOND = '2';
process.env.WS_RATE_LIMIT_FRAME_BURST = '2';
jest.useFakeTimers();
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const gw = buildGateway();
const sock = makeSock('s1', { apiKey: 'good' });
await gw.handleConnection(asSocket(sock));
await gw.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['session.status']));
await gw.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['session.status']));
const limited = (await gw.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['session.status']))) as {
code?: string;
};
expect(limited.code).toBe('RATE_LIMITED');
jest.advanceTimersByTime(1_000); // 2 tokens refill at 2/s
const res = (await gw.handleMessage(asSocket(sock), subscribeMsg('sess-1', ['session.status']))) as {
type: string;
};
expect(res.type).toBe('subscribed');
});
});
describe('pre-auth per-IP handshake window', () => {
it('rejects the handshake above the window BEFORE validateApiKey runs', async () => {
process.env.WS_RATE_LIMIT_HANDSHAKE_MAX = '3';
process.env.WS_RATE_LIMIT_HANDSHAKE_WINDOW_MS = '60000';
// Failed handshakes are what the window is for — an authenticated one is refunded (below).
authService.validateApiKey.mockRejectedValue(new Error('bad key'));
const gw = buildGateway();
for (let i = 0; i < 3; i++) {
await gw.handleConnection(asSocket(makeSock(`s${i}`, { apiKey: 'good' })));
}
expect(authService.validateApiKey).toHaveBeenCalledTimes(3);
// The 4th handshake from the same IP inside the window is gated pre-auth: the DB
// validate is never reached.
const blocked = makeSock('s-blocked', { apiKey: 'good' });
await gw.handleConnection(asSocket(blocked));
expect(authService.validateApiKey).toHaveBeenCalledTimes(3);
expect(blocked.disconnect).toHaveBeenCalled();
expect(blocked.emit).toHaveBeenCalledWith('message', expect.objectContaining({ code: 'RATE_LIMITED' }));
const violations = warnCalls().filter(([action]) => action === AuditAction.RATE_LIMIT_EXCEEDED);
expect(violations).toHaveLength(1);
expect(violations[0]?.[1]?.metadata).toEqual(
expect.objectContaining({ surface: 'websocket', kind: 'handshake' }),
);
});
it('emits the RATE_LIMITED error frame BEFORE disconnecting, so the client can tell throttling from a dead server', async () => {
process.env.WS_RATE_LIMIT_HANDSHAKE_MAX = '1';
authService.validateApiKey.mockRejectedValue(new Error('bad key'));
const gw = buildGateway();
await gw.handleConnection(asSocket(makeSock('s1', { apiKey: 'good' })));
const blocked = makeSock('s-blocked', { apiKey: 'good' });
await gw.handleConnection(asSocket(blocked));
// Order is the client-visible contract: socket.io delivers the queued error frame ahead of
// the disconnect packet, and the dashboard keys its reconnect banner on receiving a
// distinguishable error plus the server-initiated close.
expect(blocked.emit).toHaveBeenCalledWith(
'message',
expect.objectContaining({ type: 'error', code: 'RATE_LIMITED' }),
);
expect(blocked.disconnect).toHaveBeenCalled();
const emitOrder = blocked.emit.mock.invocationCallOrder[0];
const disconnectOrder = blocked.disconnect.mock.invocationCallOrder[0];
expect(emitOrder).toBeLessThan(disconnectOrder);
});
it('does not spend the shared per-IP budget on handshakes that authenticate', async () => {
// The window is charged pre-auth to keep a flood off the DB, but every client behind one
// NAT/proxy IP shares the subject — charging successful connects too would let a few
// dashboards re-mounting lock each other out. Authenticated volume is bounded by the
// per-key socket cap instead.
process.env.WS_RATE_LIMIT_HANDSHAKE_MAX = '2';
process.env.WS_RATE_LIMIT_HANDSHAKE_WINDOW_MS = '60000';
process.env.WS_MAX_SOCKETS_PER_KEY = '99';
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const gw = buildGateway();
for (let i = 0; i < 6; i++) {
const sock = makeSock(`ok${i}`, { apiKey: 'good' });
await gw.handleConnection(asSocket(sock));
expect(sock.disconnect).not.toHaveBeenCalled();
}
expect(authService.validateApiKey).toHaveBeenCalledTimes(6);
});
it.each([false, true])(
'keeps newer failures charged after a delayed valid handshake (pruned: %s)',
async pruned => {
let now = 0;
let finish!: (key: unknown) => void;
const validation = new Promise(resolve => (finish = resolve));
authService.validateApiKey.mockImplementation((raw: string) =>
raw === 'good' ? validation : Promise.reject(new UnauthorizedException('Invalid API key')),
);
const gw = buildGateway();
(gw as unknown as { handshakeLimiter: SlidingWindowLimiter }).handshakeLimiter = new SlidingWindowLimiter(
2,
1000,
() => now,
);
const good = makeSock('good', { apiKey: 'good' });
const connecting = gw.handleConnection(asSocket(good));
now = pruned ? 1001 : 500;
await gw.handleConnection(asSocket(makeSock('bad-1', { apiKey: 'bad' })));
now = pruned ? 1002 : 600;
finish({ id: 'k1', name: 'k', allowedSessions: null });
await connecting;
expect(good.disconnect).not.toHaveBeenCalled();
expect(authService.validateApiKey).toHaveBeenCalledWith('good', '203.0.113.5');
now = pruned ? 1003 : 1001;
await gw.handleConnection(asSocket(makeSock('bad-2', { apiKey: 'bad' })));
const blocked = makeSock('bad-3', { apiKey: 'bad' });
await gw.handleConnection(asSocket(blocked));
expect(blocked.emit).toHaveBeenCalledWith('message', expect.objectContaining({ code: 'RATE_LIMITED' }));
expect(authService.validateApiKey).toHaveBeenCalledTimes(3);
gw.handleDisconnect(asSocket(good));
},
);
it('throttles an unauthenticated handshake flood before any credential/audit work', async () => {
process.env.WS_RATE_LIMIT_HANDSHAKE_MAX = '2';
const gw = buildGateway();
// Three key-less handshakes from one IP: the first two reach the missing-key audit,
// the third is gated by the limiter instead (no per-attempt auth failure processing).
await gw.handleConnection(asSocket(makeSock('a')));
await gw.handleConnection(asSocket(makeSock('b')));
await gw.handleConnection(asSocket(makeSock('c')));
const authFailed = warnCalls().filter(([action]) => action === AuditAction.API_KEY_AUTH_FAILED);
expect(authFailed).toHaveLength(2);
expect(authService.validateApiKey).not.toHaveBeenCalled();
});
it('recovers once the window slides past the oldest handshake', async () => {
process.env.WS_RATE_LIMIT_HANDSHAKE_MAX = '1';
process.env.WS_RATE_LIMIT_HANDSHAKE_WINDOW_MS = '60000';
jest.useFakeTimers();
authService.validateApiKey.mockRejectedValue(new Error('bad key'));
const gw = buildGateway();
await gw.handleConnection(asSocket(makeSock('a', { apiKey: 'good' })));
const blocked = makeSock('b', { apiKey: 'good' });
await gw.handleConnection(asSocket(blocked));
expect(blocked.disconnect).toHaveBeenCalled();
expect(authService.validateApiKey).toHaveBeenCalledTimes(1);
jest.advanceTimersByTime(60_001);
const recovered = makeSock('c', { apiKey: 'good' });
await gw.handleConnection(asSocket(recovered));
// No longer shed by the window: it reaches the credential check. (It is still rejected here
// because this test drives the window with failing credentials, so assert on WHICH rejection.)
expect(authService.validateApiKey).toHaveBeenCalledTimes(2);
expect(recovered.emit).toHaveBeenCalledWith('message', expect.objectContaining({ code: 'UNAUTHORIZED' }));
expect(recovered.emit).not.toHaveBeenCalledWith('message', expect.objectContaining({ code: 'RATE_LIMITED' }));
});
it('samples the violation audit: one row per subject per minute, suppressed count folded in', async () => {
process.env.WS_RATE_LIMIT_HANDSHAKE_MAX = '1';
process.env.WS_RATE_LIMIT_HANDSHAKE_WINDOW_MS = '60000';
jest.useFakeTimers();
authService.validateApiKey.mockRejectedValue(new Error('bad key'));
const gw = buildGateway();
await gw.handleConnection(asSocket(makeSock('a', { apiKey: 'good' }))); // allowed
await gw.handleConnection(asSocket(makeSock('b', { apiKey: 'good' }))); // rejected → audit #1
await gw.handleConnection(asSocket(makeSock('c', { apiKey: 'good' }))); // rejected → suppressed
jest.advanceTimersByTime(61_000);
await gw.handleConnection(asSocket(makeSock('d', { apiKey: 'good' }))); // allowed again
await gw.handleConnection(asSocket(makeSock('e', { apiKey: 'good' }))); // rejected → audit #2
const rateLimited = warnCalls().filter(([action]) => action === AuditAction.RATE_LIMIT_EXCEEDED);
expect(rateLimited).toHaveLength(2);
expect(rateLimited[0]?.[1]?.metadata).toEqual(expect.objectContaining({ kind: 'handshake', suppressed: 0 }));
expect(rateLimited[1]?.[1]?.metadata).toEqual(expect.objectContaining({ kind: 'handshake', suppressed: 1 }));
});
});
describe('IPv6 clients are limited on their /64', () => {
const ipOf = ([, ctx]: [AuditAction, WarnContext?]): unknown =>
(ctx as { ipAddress?: string } | undefined)?.ipAddress;
it('refunds an authenticated handshake to the /64 bucket it was charged to', async () => {
// The charge lands on the /64; a refund keyed on the full address finds no bucket, so every
// authenticated connect from one IPv6 network would spend the shared window after all.
process.env.WS_RATE_LIMIT_HANDSHAKE_MAX = '2';
process.env.WS_RATE_LIMIT_HANDSHAKE_WINDOW_MS = '60000';
process.env.WS_MAX_SOCKETS_PER_KEY = '99';
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const gw = buildGateway();
const addresses = ['2001:db8:1:2::a', '2001:db8:1:2::a', '2001:db8:1:2::b', '2001:db8:1:2::c', '2001:db8:1:2::a'];
for (const [i, address] of addresses.entries()) {
const sock = makeSock(`ok${i}`, { apiKey: 'good' }, address);
await gw.handleConnection(asSocket(sock));
expect(sock.disconnect).not.toHaveBeenCalled();
}
expect(authService.validateApiKey).toHaveBeenCalledTimes(addresses.length);
});
it('shares the handshake window and the violation sample across a /64, keeping the real address', async () => {
process.env.WS_RATE_LIMIT_HANDSHAKE_MAX = '1';
authService.validateApiKey.mockRejectedValue(new Error('bad key'));
const gw = buildGateway();
await gw.handleConnection(asSocket(makeSock('a', { apiKey: 'good' }, '2001:db8:1:2::a')));
const rotatedOnce = makeSock('b', { apiKey: 'good' }, '2001:db8:1:2::b');
await gw.handleConnection(asSocket(rotatedOnce));
const rotatedTwice = makeSock('c', { apiKey: 'good' }, '2001:db8:1:2::c');
await gw.handleConnection(asSocket(rotatedTwice));
expect(rotatedOnce.emit).toHaveBeenCalledWith('message', expect.objectContaining({ code: 'RATE_LIMITED' }));
expect(rotatedTwice.emit).toHaveBeenCalledWith('message', expect.objectContaining({ code: 'RATE_LIMITED' }));
expect(authService.validateApiKey).toHaveBeenCalledTimes(1);
const rateLimited = warnCalls().filter(([action]) => action === AuditAction.RATE_LIMIT_EXCEEDED);
expect(rateLimited).toHaveLength(1);
expect(ipOf(rateLimited[0])).toBe('2001:db8:1:2::b');
await gw.handleConnection(asSocket(makeSock('d', { apiKey: 'good' }, '2001:db8:1:3::a')));
expect(authService.validateApiKey).toHaveBeenCalledTimes(2);
});
it('meters a not-yet-authenticated socket on its /64', async () => {
process.env.WS_RATE_LIMIT_FRAME_PER_SECOND = '1';
process.env.WS_RATE_LIMIT_FRAME_BURST = '1';
const gw = buildGateway();
const ping = { type: 'ping', requestId: 'p' } as unknown as WSClientMessage;
const first = (await gw.handleMessage(asSocket(makeSock('a', {}, '2001:db8:1:2::a')), ping)) as { type: string };
expect(first.type).not.toBe('error');
const sameSubnet = (await gw.handleMessage(asSocket(makeSock('b', {}, '2001:db8:1:2::b')), ping)) as {
code?: string;
};
expect(sameSubnet.code).toBe('RATE_LIMITED');
const frameViolation = warnCalls().find(([action]) => action === AuditAction.RATE_LIMIT_EXCEEDED);
expect(frameViolation && ipOf(frameViolation)).toBe('2001:db8:1:2::b');
const otherSubnet = (await gw.handleMessage(asSocket(makeSock('c', {}, '2001:db8:1:3::a')), ping)) as {
type: string;
};
expect(otherSubnet.type).not.toBe('error');
});
});
// A reply that carried client JSON back made the transport serialize whatever the client nested in it,
// so every path that answers a frame is held to the same rule: a string of at most 128 characters, or none.
describe('request id in replies', () => {
const HOSTILE = ['x'.repeat(129), { a: { b: 1 } }, ['r'], 7, true, null];
const idOf = (reply: unknown): unknown => (reply as { requestId?: unknown }).requestId;
it('echoes a request id only when it is a short string, never structure the client built', async () => {
process.env.WS_RATE_LIMIT_FRAME_PER_SECOND = '1000';
process.env.WS_RATE_LIMIT_FRAME_BURST = '1000';
const gw = buildGateway();
const send = async (message: unknown) =>
(await gw.handleMessage(asSocket(makeSock('a', {}, '203.0.113.9')), message as WSClientMessage)) as {
requestId?: unknown;
code?: string;
};
expect((await send({ type: 'ping', requestId: 'r1' })).requestId).toBe('r1');
expect((await send({ type: 'ping', requestId: 'x'.repeat(128) })).requestId).toBe('x'.repeat(128));
for (const hostile of HOSTILE) {
expect((await send({ type: 'ping', requestId: hostile })).requestId).toBeUndefined();
const refused = await send({ type: 'no-such-type', requestId: hostile });
expect(refused.code).toBe('INVALID_MESSAGE');
expect(refused.requestId).toBeUndefined();
}
});
it('drops it from the RATE_LIMITED reply too, the one an abusive client is sent', async () => {
process.env.WS_RATE_LIMIT_FRAME_PER_SECOND = '1';
process.env.WS_RATE_LIMIT_FRAME_BURST = '1';
jest.useFakeTimers();
const gw = buildGateway();
const sock = makeSock('a', {}, '203.0.113.9');
await gw.handleMessage(asSocket(sock), { type: 'ping' }); // spends the one token
for (const hostile of HOSTILE) {
const reply = await gw.handleMessage(asSocket(sock), { type: 'ping', requestId: hostile } as never);
expect(reply).toMatchObject({ type: 'error', code: 'RATE_LIMITED' });
expect(idOf(reply)).toBeUndefined();
}
const short = await gw.handleMessage(asSocket(sock), { type: 'ping', requestId: 'r1' } as never);
expect(short).toMatchObject({ code: 'RATE_LIMITED', requestId: 'r1' });
// The frame the socket was pushed is the one a client reads: none of the hostile ids is in it.
const pushed = sock.emit.mock.calls.map(([, frame]) => idOf(frame));
expect(pushed.filter(id => id !== undefined)).toEqual(['r1']);
});
it('drops it from subscribe and unsubscribe replies, granted or refused', async () => {
process.env.WS_RATE_LIMIT_FRAME_PER_SECOND = '1000';
process.env.WS_RATE_LIMIT_FRAME_BURST = '1000';
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const gw = buildGateway();
const sock = makeSock('s1', { apiKey: 'good' });
await gw.handleConnection(asSocket(sock));
const send = (message: Record<string, unknown>) =>
gw.handleMessage(asSocket(sock), message as unknown as WSClientMessage);
const commands: Array<[string, Record<string, unknown>, string]> = [
['subscribed', { type: 'subscribe', sessionId: 'sess-1', events: ['message.received'] }, 'subscribed'],
['refused subscribe', { type: 'subscribe', sessionId: 'sess:1', events: ['*'] }, 'error'],
['unsubscribed', { type: 'unsubscribe', sessionId: 'sess-1' }, 'unsubscribed'],
['refused unsubscribe', { type: 'unsubscribe', sessionId: 'sess:1' }, 'error'],
];
for (const [label, command, type] of commands) {
const kept = await send({ ...command, requestId: 'r1' });
expect([label, kept]).toEqual([label, expect.objectContaining({ type, requestId: 'r1' })]);
for (const hostile of HOSTILE) {
const reply = await send({ ...command, requestId: hostile });
expect([label, reply]).toEqual([label, expect.objectContaining({ type })]);
expect([label, idOf(reply)]).toEqual([label, undefined]);
}
}
});
});
describe('per-key simultaneous socket cap', () => {
it('rejects the socket above the cap with a clear error, and frees the slot on disconnect', async () => {
process.env.WS_MAX_SOCKETS_PER_KEY = '2';
// Keep the handshake window out of the way: this test is about the socket cap.
process.env.WS_RATE_LIMIT_HANDSHAKE_MAX = '100';
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const gw = buildGateway();
const s1 = makeSock('s1', { apiKey: 'good' });
const s2 = makeSock('s2', { apiKey: 'good' });
await gw.handleConnection(asSocket(s1));
await gw.handleConnection(asSocket(s2));
expect(s1.disconnect).not.toHaveBeenCalled();
expect(s2.disconnect).not.toHaveBeenCalled();
// The 3rd simultaneous socket for the same key IS authenticated (the cap is a post-auth
// fairness bound, not an auth failure) and then refused with a clear error.
const s3 = makeSock('s3', { apiKey: 'good' });
await gw.handleConnection(asSocket(s3));
expect(authService.validateApiKey).toHaveBeenCalledTimes(3);
expect(s3.disconnect).toHaveBeenCalled();
expect(s3.emit).toHaveBeenCalledWith(
'message',
expect.objectContaining({
code: 'RATE_LIMITED',
message: expect.stringContaining('Too many concurrent connections') as unknown,
}),
);
const violations = warnCalls().filter(([action]) => action === AuditAction.RATE_LIMIT_EXCEEDED);
expect(violations).toHaveLength(1);
expect(violations[0]?.[1]?.metadata).toEqual(expect.objectContaining({ kind: 'sockets' }));
// Disconnecting one socket frees the slot for the next connection.
gw.handleDisconnect(asSocket(s2));
const s4 = makeSock('s4', { apiKey: 'good' });
await gw.handleConnection(asSocket(s4));
expect(s4.disconnect).not.toHaveBeenCalled();
});
it('does not spend a cap slot on a handshake whose transport closed while it was validating', async () => {
// Nest runs the disconnect handler as soon as the transport closes, which can be before
// handleConnection returns. That untrack ran before the key was on client.data and found
// nothing, so the socket tracked a moment later stayed in the per-key set forever.
process.env.WS_MAX_SOCKETS_PER_KEY = '1';
process.env.WS_RATE_LIMIT_HANDSHAKE_MAX = '100';
authService.validateApiKey.mockResolvedValue({ id: 'k1', name: 'k', allowedSessions: null });
const gw = buildGateway();
const aborted = makeSock('aborted', { apiKey: 'good' });
const connecting = gw.handleConnection(asSocket(aborted));
aborted.disconnected = true; // the client went away mid-validation
gw.handleDisconnect(asSocket(aborted)); // Nest dispatches it before the connect resolves
await connecting;
// The one slot the key has must still be free.
const next = makeSock('next', { apiKey: 'good' });
await gw.handleConnection(asSocket(next));
expect(next.disconnect).not.toHaveBeenCalled();
});
});
});