Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import {
WebSocketGateway,
WebSocketServer,
OnGatewayInit,
OnGatewayConnection,
OnGatewayDisconnect,
SubscribeMessage,
MessageBody,
ConnectedSocket,
} from '@nestjs/websockets';
import { Server, Socket } from 'socket.io';
import { OnModuleDestroy } from '@nestjs/common';
import { createLogger } from '../../common/services/logger.service';
import { ConfigService } from '@nestjs/config';
import { AuthService } from '../auth/auth.service';
import { ChatScopeService } from '../auth/chat-scope.service';
import { isWsRedisEnabled } from './redis-io.adapter';
import { AuditService } from '../audit/audit.service';
import { AuditAction } from '../audit/entities/audit-log.entity';
import { resolveCorsPolicy } from '../../config/bootstrap-security';
import {
limiterKeyForIp,
parseTrustedProxies,
resolveClientIp as resolveRequestClientIp,
type RequestLike,
} from '../../common/utils/ip';
import { DEFAULT_WEBHOOK_MEDIA_INLINE_MAX_BYTES, shedInlineMedia } from '../../common/utils/inline-media';
import { isSafeSessionName } from '../../common/utils/path-safety';
import { ApiKeyRole, type ApiKey } from '../auth/entities/api-key.entity';
import { apiKeyAuthorizationFingerprint, apiKeyExpiryTime } from '../auth/api-key-authorization';
import {
readWsRateLimitConfig,
TokenBucketLimiter,
SlidingWindowLimiter,
type WsRateLimitConfig,
} from './ws-rate-limit';
/**
* WebSocket CORS origin: reuse the HTTP CORS policy instead of a hardcoded '*'.
* Dev → allow any origin; production → the configured CORS_ORIGINS allowlist (or none).
* Read from process.env at module load (real env vars apply; same-origin is unaffected).
*/
function resolveWsCorsOrigin(): boolean | string[] {
const policy = resolveCorsPolicy(process.env.CORS_ORIGINS, process.env.NODE_ENV);
return policy.allowAnyOrigin ? true : policy.origins;
}
/**
* Read TRUSTED_PROXIES once as a list — mirrors mcp.server.ts so the WS surface resolves the
* client IP with the same trusted-proxy-aware logic as the REST guard and the MCP mount.
*/
function readTrustedProxies(): string[] {
return parseTrustedProxies(process.env.TRUSTED_PROXIES);
}
import type {
WSClientMessage,
WSSubscribeRequest,
WSUnsubscribeRequest,
WSSubscribedResponse,
WSUnsubscribedResponse,
WSEventMessage,
WSErrorResponse,
WSPongResponse,
} from './dto/ws-messages.dto';
import { SUBSCRIBABLE_EVENTS, buildRoomName } from './dto/ws-messages.dto';
import type { DeliveryStatus, MessageReceiptStatus } from '../../engine/interfaces/whatsapp-engine.interface';
import { WILDCARD_EXCLUDED_EVENTS } from '../../common/utils/wildcard-events';
// The events a chat-restricted key may receive, each delivered only for a chat inside its allowlist.
// group.join_request is not one of them: it names the people asking to join, who are outside the
// allowed chats by definition, and the REST membership-request routes refuse these keys for that reason.
const CHAT_EVENTS = new Set([
'message.received',
'message.sent',
'message.ack',
'message.receipt',
'message.revoked',
'message.reaction',
'message.edited',
'group.join',
'group.leave',
'group.update',
'presence.update',
'event.response',
'poll.vote',
]);
/**
* The frame with a `requestId` that is not a short string dropped. A reply that carried client JSON back
* made the transport serialize whatever structure the client nested in it, which is not the client's to
* choose; the handlers below then never see anything but a string or nothing.
*/
function withSafeRequestId(message: WSClientMessage | null | undefined): WSClientMessage | null | undefined {
if (typeof message !== 'object' || message === null || Array.isArray(message)) return message;
const { requestId } = message as { requestId?: unknown };
if (requestId === undefined) return message;
if (typeof requestId === 'string' && requestId.length <= MAX_REQUEST_ID_LENGTH) return message;
return { ...message, requestId: undefined };
}
function chatRoom(sessionId: string, event: string, chatId: string): string {
return `${buildRoomName(sessionId, event)}:chat:${encodeURIComponent(chatId)}`;
}
/**
* Whether an API key may subscribe to a session's WebSocket event rooms.
* An unrestricted key (no `allowedSessions`) may subscribe to anything, including
* the `*` wildcard. A key scoped to specific sessions may NOT subscribe to `*`
* (which would receive every session's events) nor to a session outside its
* allowlist — preventing cross-tenant event leakage (#221).
*/
export function isSessionSubscriptionAllowed(allowedSessions: string[] | null | undefined, sessionId: string): boolean {
if (!allowedSessions || allowedSessions.length === 0) {
return true;
}
if (sessionId === '*') {
return false;
}
return allowedSessions.includes(sessionId);
}
/**
* Room holding every socket whose key may NOT read a session's pairing QR over REST
* (`GET /sessions/:sessionId/qr` requires OPERATOR). `session.qr` is broadcast with this room
* excluded, which covers the explicit event name and both wildcard subscribe forms. Membership is
* set from the re-validated key on every subscribe, before any subscription room is joined, so a
* socket can never hold a subscription room without it.
*/
export const QR_DENIED_ROOM = 'role:qr-denied';
/** Roles allowed to receive `session.qr`. Anything else, including an unknown role, is denied. */
const QR_ALLOWED_ROLES: ReadonlySet<string> = new Set([ApiKeyRole.OPERATOR, ApiKeyRole.ADMIN]);
/**
* Subscription rooms live until the socket disconnects, so their names and count are bounded: a session
* id is a uuid (any id the engines accept is isSafeSessionName), and one socket holds at most this many
* subscription rooms, far above every event of every session a client would follow.
*/
const MAX_SUBSCRIBE_SESSION_ID_LENGTH = 128;
// A request id only correlates a reply with its request, so only a short string is ever echoed back.
const MAX_REQUEST_ID_LENGTH = 128;
const MAX_ROOMS_PER_SOCKET = 4096;
const TOO_MANY_SUBSCRIPTIONS_MESSAGE = `A connection may hold at most ${MAX_ROOMS_PER_SOCKET} subscriptions; unsubscribe first`;
/** `*` or a session id: all a subscription room, and a reply that names one, may carry. */
function isSessionSelector(sessionId: string): boolean {
return sessionId === '*' || (sessionId.length <= MAX_SUBSCRIBE_SESSION_ID_LENGTH && isSafeSessionName(sessionId));
}
/** Why an API key's live WebSocket sockets are being torn down — drives the client-facing message. */
export type ApiKeyEvictionReason = 'revoked' | 'deleted' | 'authorization_changed' | 'expired';
const EVICTION_MESSAGES: Record<ApiKeyEvictionReason, string> = {
revoked: 'API key has been revoked',
deleted: 'API key has been deleted',
authorization_changed: 'API key authorization changed; please reconnect',
expired: 'API key has expired',
};
/**
* Largest client frame the socket accepts, in bytes. A client only sends subscribe, unsubscribe and ping
* frames, and the longest legal one (the longest session and request id, every event) is under 1 KB.
* Every frame is decoded and walked before it is answered, so the Socket.IO default of 1 MB is far more
* than any client needs.
*/
export const WS_MAX_FRAME_BYTES = 8 * 1024;
@WebSocketGateway({
cors: {
origin: resolveWsCorsOrigin(),
},
namespace: '/events',
maxHttpBufferSize: WS_MAX_FRAME_BYTES,
})
export class EventsGateway implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, OnModuleDestroy {
@WebSocketServer()
server!: Server;
private logger = createLogger('EventsGateway');
/**
* Active sockets keyed by their validating API-key id, so a key revoked/disabled
* mid-connection can have its live subscriptions torn down immediately (otherwise
* an already-subscribed socket keeps receiving events until it happens to disconnect).
*/
private readonly socketsByKeyId = new Map<string, Set<Socket>>();
private readonly chatDeliveries = new Map<string, Promise<void>>();
// Subscribes still re-validating their key. An unsubscribe answered meanwhile cancels the ones it covers, so
// they cannot join rooms after the client was told they were left.
private readonly pendingSubscriptions = new WeakMap<Socket, Set<{ sessionId: string; cancelled: boolean }>>();
private authzSweepTimer?: ReturnType<typeof setInterval>;
/**
* Rate limiting for the WS surface (see ws-rate-limit.ts). Frames never pass through the
* Nest guard pipeline, so these run in the gateway itself:
* - frameLimiter: per-key token bucket on every inbound client frame (pre-auth sockets are
* keyed by IP instead, since they have no validated key yet);
* - handshakeLimiter: pre-auth per-IP sliding window on new connections, so a handshake
* flood cannot force a DB validateApiKey per attempt;
* - maxSocketsPerKey: cap on simultaneous sockets per key, enforced at connect.
*/
private readonly rateLimits: WsRateLimitConfig;
private readonly frameLimiter: TokenBucketLimiter;
private readonly handshakeLimiter: SlidingWindowLimiter;
/**
* Rate-limit violation sampler: at most one audit row per kind+subject per minute. An abuser
* held at a limit would otherwise generate an audit write per blocked frame/handshake — the
* audit trail itself becoming the flood. `count` accumulates the suppressed violations since
* the last emitted row and is folded into the next one.
*/
private readonly violations = new Map<string, { count: number; since: number }>();
private static readonly VIOLATION_AUDIT_WINDOW_MS = 60_000;
private static readonly MAX_VIOLATION_KEYS = 10_000;
constructor(
private readonly authService: AuthService,
private readonly auditService: AuditService,
private readonly configService: ConfigService,
private readonly chatScope: ChatScopeService = new ChatScopeService(),
) {
this.rateLimits = readWsRateLimitConfig();
this.frameLimiter = new TokenBucketLimiter(this.rateLimits.framePerSecond, this.rateLimits.frameBurst);
this.handshakeLimiter = new SlidingWindowLimiter(this.rateLimits.handshakeMax, this.rateLimits.handshakeWindowMs);
}
afterInit() {
this.logger.log('WebSocket Gateway initialized');
this.authzSweepTimer = setInterval(() => {
void this.sweepApiKeyAuthorization().catch(error =>
this.logger.error(
'Failed to sweep WebSocket API key authorization',
error instanceof Error ? error.stack : error,
),
);
}, 60_000);
this.authzSweepTimer.unref?.();
}
onModuleDestroy(): void {
if (this.authzSweepTimer) clearInterval(this.authzSweepTimer);
this.authzSweepTimer = undefined;
}
/**
* Re-validate the keys behind the live sockets against the database, once per tick.
*
* A socket carries the key snapshot taken at connect and never refreshes it, so every later change
* to the row is invisible to it: a key deleted, revoked, expired or narrowed by a direct write to
* this node's main database, or by an operator change that committed in the window between this
* socket's validation and its registration here. The operator path still evicts synchronously in
* the same request (see AuthService.update/revoke/delete); this is the backstop for the changes
* that never reached this process.
*
* One batched read over the distinct key ids currently holding sockets, then eviction per key with
* the reason that actually applies. Only the authorization columns are compared (see
* apiKeyAuthorizationFingerprint), so the usage tracker's windowed lastUsedAt/usageCount write,
* which touches every key in use, evicts nobody.
*/
private async sweepApiKeyAuthorization(now = Date.now()): Promise<void> {
// The expiry a socket already carries is decided first, and without the database: it needs no row
// to be read, and a table that is unreachable or locked must not keep an expired key streaming
// events until the first tick whose read succeeds.
for (const [keyId, sockets] of Array.from(this.socketsByKeyId.entries())) {
if (Array.from(sockets).some(client => this.isSnapshotExpired(client, now))) {
this.evictApiKey(keyId, 'expired');
}
}
const keyIds = Array.from(this.socketsByKeyId.keys());
if (keyIds.length === 0) return;
const current = await this.authService.findAuthorizationStates(keyIds);
const byId = new Map(current.map(key => [key.id, key]));
for (const keyId of keyIds) {
const reason = this.evictionReason(byId.get(keyId), this.socketsByKeyId.get(keyId), now);
if (reason) this.evictApiKey(keyId, reason);
}
}
/**
* Why a key's sockets must go, or null to keep them. `current` is the row as it stands now, absent
* when the key was deleted. Order matters: the reason a client is told should be the strongest one
* that applies, not merely the first field that differs from its snapshot.
*/
private evictionReason(
current: ApiKey | undefined,
sockets: Set<Socket> | undefined,
now: number,
): ApiKeyEvictionReason | null {
if (!sockets || sockets.size === 0) return null;
if (!current) return 'deleted';
if (!current.isActive) return 'revoked';
const expiry = apiKeyExpiryTime(current.expiresAt);
// An expiry that does not parse is the epoch for apiKeyExpiryTime, so it is expired here as AuthService refuses it.
if (expiry !== null && expiry <= now) return 'expired';
const authorization = apiKeyAuthorizationFingerprint(current);
// Per socket, not per key: sockets under one key connected at different moments, so one can hold
// a stale snapshot while another already carries the new authorization. A socket that subscribed
// under something other than its snapshot goes too, even when the row matches that snapshot
// again: the rooms that subscribe granted are never revisited, so a widening reverted before this
// tick would otherwise leave them joined for the life of the connection.
const stale = Array.from(sockets).some(
client => this.snapshotFingerprint(client) !== authorization || this.hasDivergentGrant(client),
);
return stale ? 'authorization_changed' : null;
}
/** The authorization fingerprint of the key snapshot a socket has been carrying since connect. */
private snapshotFingerprint(client: Socket): string {
const snapshot = (client.data as { apiKey?: ApiKey } | undefined)?.apiKey;
return snapshot ? apiKeyAuthorizationFingerprint(snapshot) : '';
}
/** Whether the key snapshot a socket carries has expired, decided from the socket alone. */
private isSnapshotExpired(client: Socket, now: number): boolean {
const snapshot = (client.data as { apiKey?: Pick<ApiKey, 'expiresAt'> } | undefined)?.apiKey;
const expiry = apiKeyExpiryTime(snapshot?.expiresAt);
return expiry !== null && expiry <= now;
}
/** Whether a subscribe ever granted this socket something under a key other than its snapshot. */
private hasDivergentGrant(client: Socket): boolean {
return (client.data as { authorizationDiverged?: boolean } | undefined)?.authorizationDiverged === true;
}
/**
* Resolve the trusted-proxy-aware client IP for a socket, reusing the same shared
* `resolveClientIp` helper as the REST guard and MCP mount. X-Forwarded-For is only
* honored when the immediate peer is a configured trusted proxy, preventing IP-spoofing
* of the allowedIps allowlist over the WS surface.
*/
private resolveClientIp(client: Socket): string {
const handshake = client.handshake;
const req: RequestLike = {
ip: handshake.address,
socket: { remoteAddress: handshake.address },
headers: handshake.headers ?? {},
};
return resolveRequestClientIp(req, readTrustedProxies());
}
private trackSocket(keyId: string, client: Socket): void {
let sockets = this.socketsByKeyId.get(keyId);
if (!sockets) {
sockets = new Set();
this.socketsByKeyId.set(keyId, sockets);
}
sockets.add(client);
}
private untrackSocket(client: Socket): void {
const keyId = (client.data as { apiKey?: Pick<ApiKey, 'id'> } | undefined)?.apiKey?.id;
if (!keyId) return;
const sockets = this.socketsByKeyId.get(keyId);
if (!sockets) return;
sockets.delete(client);
if (sockets.size === 0) {
this.socketsByKeyId.delete(keyId);
}
}
/**
* Tear down every active socket authenticated with `keyId`. Called by AuthService when a key is
* revoked, deleted, or has its authorization (role/allowedSessions/allowedChats/allowedIps/expiry) narrowed, and
* by sweepApiKeyAuthorization for the same changes when they only reach this process through the
* database, so the key's already-subscribed sockets stop receiving events immediately instead of
* lingering until they disconnect on their own. Each socket gets a clean close (an `UNAUTHORIZED`
* reason) reflecting the actual trigger, rather than a silent drop.
*/
evictApiKey(keyId: string, reason: ApiKeyEvictionReason = 'revoked'): void {
const sockets = this.socketsByKeyId.get(keyId);
if (!sockets || sockets.size === 0) return;
this.logger.log(`Evicting ${sockets.size} WebSocket connection(s) (${reason}) for key ${keyId}`);
this.socketsByKeyId.delete(keyId);
const message = EVICTION_MESSAGES[reason];
for (const client of sockets) {
client.emit('message', this.createError('UNAUTHORIZED', message));
client.disconnect(true);
}
}
handleConnection(client: Socket): Promise<void> {
// socket.io sends CONNECT to the client before Nest calls this, and Nest binds the frame handlers
// without waiting for it, so a client that subscribes from its 'connect' handler can send a frame
// while the key below is still being validated. handleMessage waits on this promise; it is stored
// synchronously, before any frame can be dispatched.
const ready = this.authenticate(client);
(client.data as { authReady?: Promise<void> }).authReady = ready;
return ready;
}
private async authenticate(client: Socket): Promise<void> {
// Resolve the client IP once here so the handshake throttle, the validation, and the
// audit trail all use the same trusted-proxy-aware value (parity with the REST guard / MCP mount).
const clientIp = this.resolveClientIp(client);
// The handshake bucket key: an IPv6 client is charged on its /64. The refund below must name the
// same bucket, or an authenticated IPv6 handshake is never given back.
const handshakeKey = limiterKeyForIp(clientIp);
// Pre-auth, per-IP handshake throttle. This must run BEFORE any credential handling: an
// unauthenticated handshake flood otherwise reaches the DB validateApiKey below on every
// attempt (same gap the MCP pre-auth IP throttle covers for the /mcp mount).
const handshakeReservation = {};
if (!this.handshakeLimiter.allow(handshakeKey, handshakeReservation)) {
this.logger.warn(`Client ${client.id} rejected: handshake rate limit exceeded (ip: ${clientIp})`);
this.noteRateLimitViolation('handshake', { ipAddress: clientIp });
client.emit('message', this.createError('RATE_LIMITED', 'Too many connection attempts, retry later'));
client.disconnect();
return;
}
// Accept the key only via Socket.IO's `auth` field or the header — never the query string, which
// leaks the credential into proxy/access logs. (The deprecated `?apiKey=` fallback was removed.)
const handshakeAuth = client.handshake.auth as { apiKey?: string } | undefined;
const apiKey = handshakeAuth?.apiKey || (client.handshake.headers['x-api-key'] as string);
if (!apiKey) {
this.logger.warn(`Client ${client.id} rejected: No API key provided`);
void this.auditService.logWarn(AuditAction.API_KEY_AUTH_FAILED, {
ipAddress: clientIp,
metadata: { surface: 'websocket' },
errorMessage: 'missing API key',
});
client.emit('message', this.createError('UNAUTHORIZED', 'API key required'));
client.disconnect();
return;
}
try {
// validateApiKey THROWS on any failure (it never resolves to a falsy value), so the rejection
// path is the catch below — a separate `if (!validKey)` branch here was dead code. The clientIp
// is passed so an IP-restricted key (allowedIps set) is ENFORCED rather than blanket-rejected
// for "Client IP could not be determined".
const validKey = await this.authService.validateApiKey(apiKey, clientIp);
// Cap simultaneous sockets per key: each socket holds rooms, engine fan-out, and memory,
// so one key must not open connections without bound. Enough for multi-tab dashboards;
// excess connections get a clear error, not a silent drop.
const existing = this.socketsByKeyId.get(validKey.id);
if (existing && existing.size >= this.rateLimits.maxSocketsPerKey) {
this.logger.warn(
`Client ${client.id} rejected: socket cap reached for key ${validKey.id} (${this.rateLimits.maxSocketsPerKey})`,
);
this.noteRateLimitViolation('sockets', { apiKeyId: validKey.id, ipAddress: clientIp });
client.emit(
'message',
this.createError(
'RATE_LIMITED',
`Too many concurrent connections for this API key (max ${this.rateLimits.maxSocketsPerKey})`,
),
);
client.disconnect();
return;
}
// Store the validated key AND the raw key — the raw key lets handleSubscribe
// RE-validate on each subscription so a key revoked mid-connection is caught.
(client.data as { apiKey: unknown; rawApiKey: string }).apiKey = validKey;
(client.data as { rawApiKey: string }).rawApiKey = apiKey;
this.trackSocket(validKey.id, client);
// The handshake window is charged pre-auth to keep an unauthenticated flood off the DB. This
// one turned out to be authentic, so give the slot back: the window then bounds FAILED
// handshakes, and authenticated connections stay bounded by maxSocketsPerKey above. Without
// this, every client behind one NAT/proxy IP shares a 10/min budget and normal dashboard
// re-mounts lock each other out.
this.handshakeLimiter.refund(handshakeKey, handshakeReservation);
// The transport can close while validateApiKey is in flight, and Nest runs the disconnect
// handler before this one returns. That untrack found no key on client.data yet and did
// nothing, so the socket just tracked would stay in the per-key set for the life of the
// process, holding a slot of the cap above and keeping the Socket object reachable.
if (client.disconnected) {
this.untrackSocket(client);
// Logged rather than returned silently: the disconnect handler has already written a
// "Client disconnected" line for a client nothing ever announced as connected.
this.logger.log(`Client ${client.id} authenticated after it had already gone (key: ${validKey.name})`);
return;
}
this.logger.log(`Client connected: ${client.id} (key: ${validKey.name})`);
} catch (error) {
this.logger.warn(`Client ${client.id} rejected: Auth error`, {
error: error instanceof Error ? error.message : String(error),
});
// Audit the rejected credential like the REST guard does, so probing over the WS surface leaves
// a forensic trail too. Fire-and-forget: audit logging must never affect the rejection path.
void this.auditService.logWarn(AuditAction.API_KEY_AUTH_FAILED, {
ipAddress: clientIp,
metadata: { surface: 'websocket' },
errorMessage: error instanceof Error ? error.message : String(error),
});
client.emit('message', this.createError('UNAUTHORIZED', 'Authentication failed'));
client.disconnect();
}
}
/**
* Record a stored key refused after its authorization changed while the socket was connected.
*/
private auditAuthorizationRefusal(apiKey: ApiKey, clientIp: string, message: string): void {
void this.auditService.logWarn(AuditAction.API_KEY_AUTH_FAILED, {
apiKey,
ipAddress: clientIp,
metadata: { surface: 'websocket' },
errorMessage: message,
});
}
handleDisconnect(client: Socket) {
this.untrackSocket(client);
this.logger.log(`Client disconnected: ${client.id}`);
}
/**
* Answer a client command on the documented `message` event, and hand the same frame back so a
* client that passed an ack callback still receives it.
*
* Returning alone is not enough. The Socket.IO adapter delivers a handler's return value through
* the ack callback and nothing else, so a client that emits without one, which the dashboard and
* the documented example client both do, never saw a subscribe confirmation, a pong, or any of the
* refusals (FORBIDDEN_SESSION, INVALID_SESSION, INVALID_EVENTS, INVALID_MESSAGE).
*
* A path that answered and then closed the socket keeps its own emit, and this skips it rather than
* emitting again: socket.io still accepts a write to a disconnected socket, so without the guard a
* client could be handed the same frame twice on its way out.
*/
private reply<T>(client: Socket, frame: T): T {
if (!client.disconnected) {
client.emit('message', frame);
}
return frame;
}
@SubscribeMessage('message')
// A client may emit 'message' with no payload or with null, so the body is typed as possibly nil and
// every read is guarded: such a frame answers INVALID_MESSAGE instead of throwing in the handler.
async handleMessage(@ConnectedSocket() client: Socket, @MessageBody() incoming: WSClientMessage | null | undefined) {
const message = withSafeRequestId(incoming);
// Per-key token bucket on every inbound frame. Keyed by the validated key id; a socket
// whose handshake validation is still in flight has no key yet and is metered by IP.
// Over-budget frames get an error frame back and are NOT dispatched to a handler — in
// particular they never reach the per-subscribe DB re-validation.
const frameSubject =
(client.data as { apiKey?: Pick<ApiKey, 'id'> } | undefined)?.apiKey?.id ??
limiterKeyForIp(this.resolveClientIp(client));
if (!this.frameLimiter.allow(frameSubject)) {
const requestId = (message as { requestId?: string } | null | undefined)?.requestId;
this.noteRateLimitViolation('frame', {
apiKeyId: (client.data as { apiKey?: Pick<ApiKey, 'id'> } | undefined)?.apiKey?.id,
ipAddress: this.resolveClientIp(client),
});
return this.reply(client, this.createError('RATE_LIMITED', 'Frame rate limit exceeded, slow down', requestId));
}
// A frame sent during the handshake waits for it. Without this a subscribe found no key on the socket
// and was refused as 'API key is no longer valid', a server-side close the client does not retry.
// A socket the handshake refused has already been answered and closed, so its frame is dropped.
await (client.data as { authReady?: Promise<void> }).authReady;
if (client.disconnected) {
return undefined;
}
switch (message?.type) {
case 'subscribe':
return this.reply(client, await this.handleSubscribe(client, message));
case 'unsubscribe':
return this.reply(client, this.handleUnsubscribe(client, message));
case 'ping':
return this.reply(client, this.handlePing(client, message.requestId));
default:
return this.reply(
client,
this.createError(
'INVALID_MESSAGE',
`Unknown message type`,
(message as { requestId?: string } | null | undefined)?.requestId,
),
);
}
}
private async handleSubscribe(
client: Socket,
message: WSSubscribeRequest,
): Promise<WSSubscribedResponse | WSErrorResponse> {
const { sessionId, events, requestId } = message;
// Validate sessionId
if (!sessionId || typeof sessionId !== 'string') {
return this.createError('INVALID_SESSION', 'sessionId is required', requestId);
}
if (!isSessionSelector(sessionId)) {
return this.createError('INVALID_SESSION', 'sessionId must be "*" or a session id', requestId);
}
// Re-validate the API key on every subscribe: a long-lived socket whose key was
// revoked/expired after connect must not be able to keep opening new subscriptions.
// The clientIp is re-resolved (trusted-proxy-aware) so an IP-restricted key is enforced
// here too, not just at connect.
const rawApiKey = (client.data as { rawApiKey?: string }).rawApiKey;
const clientIp = this.resolveClientIp(client);
const subscription = { sessionId, cancelled: false };
let pending = this.pendingSubscriptions.get(client);
if (!pending) {
pending = new Set();
this.pendingSubscriptions.set(client, pending);
}
pending.add(subscription);
let subscriberKey: ApiKey | null;
try {
subscriberKey = rawApiKey ? await this.authService.validateApiKey(rawApiKey, clientIp) : null;
} catch (error) {
subscriberKey = null;
// A key refused here was valid at connect (revoked, expired, deleted or IP-refused since), so it
// is audited like the handshake refusal; the socket is disconnected below, bounding the volume.
void this.auditService.logWarn(AuditAction.API_KEY_AUTH_FAILED, {
ipAddress: clientIp,
metadata: { surface: 'websocket' },
errorMessage: error instanceof Error ? error.message : String(error),
});
} finally {
pending.delete(subscription);
if (pending.size === 0) this.pendingSubscriptions.delete(client);
}
if (!subscriberKey) {
client.emit('message', this.createError('UNAUTHORIZED', 'API key is no longer valid', requestId));
client.disconnect();
return this.createError('UNAUTHORIZED', 'API key is no longer valid', requestId);
}
// The socket can have been evicted while this re-validation was in flight (a revoke landing on
// the same tick as a subscribe). Joining rooms now would register a disconnected socket in the
// adapter, where nothing prunes it again.
if (client.disconnected) {
return this.createError('UNAUTHORIZED', 'Connection is closed', requestId);
}
const snapshot = (client.data as { apiKey?: ApiKey }).apiKey;
const chatRestricted = this.chatScope.isRestricted(subscriberKey);
// A changed chat fence cannot reuse rooms granted under the previous authorization.
if (
(chatRestricted || this.chatScope.isRestricted(snapshot)) &&
apiKeyAuthorizationFingerprint(subscriberKey) !== this.snapshotFingerprint(client)
) {
const refusal = this.createError('UNAUTHORIZED', EVICTION_MESSAGES.authorization_changed, requestId);
this.auditAuthorizationRefusal(subscriberKey, clientIp, refusal.message);
client.emit('message', refusal);
client.disconnect();
return refusal;
}
// The fresh key decides THIS subscribe, and is deliberately not written back over the connect-time
// snapshot in client.data: rooms joined earlier are never revisited, so a socket that refreshed its
// snapshot here would look current to the sweep while still holding rooms its key has since lost.
// What it does record is that the two diverged, since everything granted below outlives the key
// state that granted it, and the row can be back to the snapshot by the time the sweep reads it.
if (apiKeyAuthorizationFingerprint(subscriberKey) !== this.snapshotFingerprint(client)) {
(client.data as { authorizationDiverged?: boolean }).authorizationDiverged = true;
}
this.syncQrAccess(client, subscriberKey.role);
// Enforce per-key session scope against the FRESH key: a key restricted to specific
// sessions must not subscribe to '*' or a session outside its allowlist (#221).
if (!isSessionSubscriptionAllowed(subscriberKey.allowedSessions, sessionId)) {
return this.createError('FORBIDDEN_SESSION', 'API key is not authorized for this session', requestId);
}
// Validate events
if (!events || !Array.isArray(events) || events.length === 0) {
return this.createError('INVALID_EVENTS', 'events array is required', requestId);
}
// Validate each event type
const validEvents = [
...new Set(
events.filter(e => e === '*' || SUBSCRIBABLE_EVENTS.includes(e as (typeof SUBSCRIBABLE_EVENTS)[number])),
),
];
if (validEvents.length === 0) {
return this.createError(
'INVALID_EVENTS',
`No valid events. Valid: ${SUBSCRIBABLE_EVENTS.join(', ')}, *`,
requestId,
);
}
const permittedEvents = chatRestricted
? validEvents.filter(event => event === '*' || CHAT_EVENTS.has(event))
: validEvents;
if (permittedEvents.length === 0) {
return this.createError('FORBIDDEN_EVENTS', 'API key may subscribe only to chat events', requestId);
}
const chats = chatRestricted ? [...this.chatScope.scopeFor(subscriberKey)!.allowed] : undefined;
// A socket holds every room it asks for, so events x chats rooms that exceed the cap can never fit.
// Refused here, before the names are built: a large allowlist made each refused frame cost real time.
// No amount of unsubscribing makes that fit, so the reply names the cost per event, not the generic text.
if (chats && permittedEvents.length * chats.length > MAX_ROOMS_PER_SOCKET) {
// Fewer events help only while one event fits: a list stored before allowedChats was bounded may not.
const remedy = chats.length <= MAX_ROOMS_PER_SOCKET ? 'name fewer events or use "*"' : 'shorten the allowlist';
return this.createError(
'TOO_MANY_SUBSCRIPTIONS',
`This key's chat allowlist makes every event ${chats.length} subscriptions and a connection may hold at most ${MAX_ROOMS_PER_SOCKET}; ${remedy}`,
requestId,
);
}
const rooms = permittedEvents.flatMap(event =>
chats ? chats.map(chatId => chatRoom(sessionId, event, chatId)) : [buildRoomName(sessionId, event)],
);
if (rooms.length === 0) {
return this.createError('FORBIDDEN_EVENTS', 'API key has no valid chats to subscribe to', requestId);
}
// Only subscription rooms count: the socket also sits in its own id room and may hold a role room.
const held = [...client.rooms].filter(room => room.startsWith('session:')).length;
const newRooms = rooms.filter(room => !client.rooms.has(room)).length;
if (held + newRooms > MAX_ROOMS_PER_SOCKET) {
return this.createError('TOO_MANY_SUBSCRIPTIONS', TOO_MANY_SUBSCRIPTIONS_MESSAGE, requestId);
}
if (subscription.cancelled) {
return this.createError('SUBSCRIPTION_CANCELLED', 'Subscription was cancelled', requestId);
}
// Join rooms for each session/event combination
for (const room of rooms) {
void client.join(room);
}
this.logger.debug(`Client ${client.id} subscribed to: ${rooms.join(', ')}`);
return {
type: 'subscribed',
sessionId,
events: permittedEvents,
requestId,
timestamp: new Date().toISOString(),
};
}
/** Put the socket in or out of the QR-denied room for its key's current role. */
private syncQrAccess(client: Socket, role: ApiKeyRole | undefined): void {
if (role && QR_ALLOWED_ROLES.has(role)) {
void client.leave(QR_DENIED_ROOM);
} else {
void client.join(QR_DENIED_ROOM);
}
}
private handleUnsubscribe(client: Socket, message: WSUnsubscribeRequest): WSUnsubscribedResponse | WSErrorResponse {
const { sessionId, requestId } = message;
// Same checks as subscribe: a missing sessionId matched no room, left every subscription in place,
// and was still answered 'unsubscribed'. The reply carries the id back, so one no subscribe could
// have accepted is refused rather than echoed.
if (!sessionId || typeof sessionId !== 'string') {
return this.createError('INVALID_SESSION', 'sessionId is required', requestId);
}
if (!isSessionSelector(sessionId)) {
return this.createError('INVALID_SESSION', 'sessionId must be "*" or a session id', requestId);
}
for (const subscription of this.pendingSubscriptions.get(client) ?? []) {
if (sessionId === '*' || subscription.sessionId === sessionId) subscription.cancelled = true;
}
// Leave all rooms for this session
const clientRooms = Array.from(client.rooms);
const sessionPrefix = `session:${sessionId}:`;
for (const room of clientRooms) {
if (room.startsWith(sessionPrefix) || (sessionId === '*' && room.startsWith('session:'))) {
void client.leave(room);
}
}
this.logger.debug(`Client ${client.id} unsubscribed from session: ${sessionId}`);
return {
type: 'unsubscribed',
sessionId,
requestId,
timestamp: new Date().toISOString(),
};
}
private handlePing(_client: Socket, requestId?: string): WSPongResponse {
return {
type: 'pong',
requestId,
timestamp: new Date().toISOString(),
};
}
private createError(code: string, message: string, requestId?: string): WSErrorResponse {
return {
type: 'error',
code,
message,
requestId,
timestamp: new Date().toISOString(),
};
}
/**
* Sampled audit for rate-limit violations: emits at most one row per kind+subject per minute
* (fire-and-forget, like the auth-failure audit). Violations suppressed inside the window are
* counted and folded into the next emitted row's `suppressed` metadata, so the forensic trail
* stays accurate without one audit write per blocked frame/handshake.
*/
private noteRateLimitViolation(
kind: 'handshake' | 'frame' | 'sockets',
subject: { apiKeyId?: string; ipAddress?: string },
): void {
const mapKey = `${kind}:${subject.apiKeyId ?? (subject.ipAddress ? limiterKeyForIp(subject.ipAddress) : 'unknown')}`;
const now = Date.now();
const prior = this.violations.get(mapKey);
if (prior && now - prior.since < EventsGateway.VIOLATION_AUDIT_WINDOW_MS) {
prior.count += 1;
return;
}
const suppressed = prior?.count ?? 0;
this.violations.delete(mapKey);
this.violations.set(mapKey, { count: 0, since: now });
while (this.violations.size > EventsGateway.MAX_VIOLATION_KEYS) {
const oldest = this.violations.keys().next().value;
if (oldest === undefined) break;
this.violations.delete(oldest);
}
void this.auditService.logWarn(AuditAction.RATE_LIMIT_EXCEEDED, {
// Only the id is read (for the apiKeyId column) — enough to correlate with the key
// without a DB lookup on a hot path.
apiKey: subject.apiKeyId ? ({ id: subject.apiKeyId } as ApiKey) : undefined,
ipAddress: subject.ipAddress,
metadata: { surface: 'websocket', kind, suppressed },
errorMessage: `websocket ${kind} rate limit exceeded`,
});
}
// ========== Event Emission Methods (room-based) ==========
/**
* Emit event to specific rooms based on sessionId and event type
*/
private emitToRooms(sessionId: string, event: string, data: unknown, exceptRoom?: string): void {
const eventMessage: WSEventMessage = {
type: 'event',
payload: { event, sessionId, data },
timestamp: new Date().toISOString(),
};
// Emit once to the specific room + the three wildcard rooms. Chaining .to()
// unions the rooms into a single broadcast, so a socket joined to several of
// them receives the event exactly once (Socket.IO dedups recipients per
// broadcast). Four separate .emit() calls would deliver one copy per room.
// `except` is resolved by the adapter, so the exclusion also holds across nodes with Redis.
// An event in WILDCARD_EXCLUDED_EVENTS skips the two event-'*' rooms: only sockets that named it
// (for one session or for all) receive it.
const named = this.server.to(buildRoomName(sessionId, event)).to(buildRoomName('*', event));
const broadcast = WILDCARD_EXCLUDED_EVENTS.includes(event)
? named
: named.to(buildRoomName(sessionId, '*')).to(buildRoomName('*', '*'));
(exceptRoom ? broadcast.except(exceptRoom) : broadcast).emit('message', eventMessage);
if (!CHAT_EVENTS.has(event) || data === null || typeof data !== 'object') return;
const value = data as Record<string, unknown>;
const chatId = event.startsWith('group.') ? value.groupId : value.chatId;
if (typeof chatId !== 'string' || !chatId.trim()) return;
if (
!isWsRedisEnabled() &&
!Array.from(this.socketsByKeyId.values()).some(sockets =>
Array.from(sockets).some(client => this.chatScope.isRestricted((client.data as { apiKey?: ApiKey }).apiKey)),
)
) {
return;
}
// Expand the emitted identity using current persisted mappings, so new LID mappings work
// without rejoining rooms. Literal allowlist rooms also enforce the fence across Redis nodes.
// Resolve identities concurrently, but retain event order within each session, including
// after a failed lookup. Other sessions and unrestricted broadcasts remain independent.
const delivery = Promise.allSettled([
this.chatDeliveries.get(sessionId),
this.chatScope.idsForFilter({ allowedChats: [chatId] }),
])
.then(([, resolved]) => {
if (resolved.status === 'rejected') throw resolved.reason;
const ids = resolved.value;
if (!ids?.length) return;
const rooms = ids.flatMap(id => {
const namedRooms = [chatRoom(sessionId, event, id), chatRoom('*', event, id)];
return WILDCARD_EXCLUDED_EVENTS.includes(event)
? namedRooms
: [...namedRooms, chatRoom(sessionId, '*', id), chatRoom('*', '*', id)];
});
this.server.to(rooms).emit('message', eventMessage);
})
.catch(error =>
this.logger.warn('Could not resolve chat identity for WebSocket delivery', {
error: error instanceof Error ? error.message : String(error),
}),
)
.finally(() => {
if (this.chatDeliveries.get(sessionId) === delivery) this.chatDeliveries.delete(sessionId);
});
this.chatDeliveries.set(sessionId, delivery);
}
/**
* Emit session status change
*/
emitSessionStatus(sessionId: string, status: string, data?: Record<string, unknown>) {
this.emitToRooms(sessionId, 'session.status', { status, ...data });
}
/**
* Emit session authenticated (engine reached READY). Mirrors the webhook payload.
*/
emitSessionAuthenticated(sessionId: string, data: { phone: string; pushName: string }) {
this.emitToRooms(sessionId, 'session.authenticated', data);
}
/**
* Emit session disconnected. Carries the `reason` that the session.status flip drops.
*/
emitSessionDisconnected(sessionId: string, data: { reason: string }) {
this.emitToRooms(sessionId, 'session.disconnected', data);
}
/**
* Emit a restriction change (imposed or lifted), mirroring the `session.restriction` webhook
* payload. Needed live because a restriction can arrive with no status transition at all (the
* Baileys reachout timelock rides a connect probe) — without this push the dashboard badge only
* appeared on a full page reload.
*/
emitSessionRestriction(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'session.restriction', data);
}
/**
* The end of a ringing call, one method per outcome.
*
* Three methods rather than one taking the name as a parameter: the drift guard discovers emitters
* by reflection and invokes each with an empty payload, so a parameterised name would leave the
* event catalog unverifiable — exactly the drift the guard exists to catch.
*/
emitCallAccepted(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'call.accepted', data);
}
emitCallRejected(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'call.rejected', data);
}
emitCallMissed(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'call.missed', data);
}
/**
* Emit a presence update. Socket-subscribable as well as webhook-delivered because presence is the
* one event whose whole value is being live — a webhook round-trip to render a typing indicator
* has usually expired by the time it arrives. Only actual changes reach here (see the wiring).
*/
emitPresenceUpdate(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'presence.update', data);
}
/** Emit an RSVP to a WhatsApp event (Baileys only). Payload mirrors the `event.response` webhook. */
emitEventResponse(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'event.response', data);
}
/** Emit a voter's new selection on a poll (whatsapp-web.js only). Payload mirrors the `poll.vote` webhook. */
emitPollVote(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'poll.vote', data);
}
/**
* Emit QR code update for a session. Scanning the QR links a device to the account, so it only
* reaches keys that may read it over REST (OPERATOR and above).
*/
emitQRCode(sessionId: string, qrCode: string) {
this.emitToRooms(sessionId, 'session.qr', { qrCode }, QR_DENIED_ROOM);
}
/**
* Cap for inline base64 media on the message events, shared with the webhook delivery path so
* both outbound sinks emit the same omitted-marker contract for an over-cap blob. Without this,
* every subscribed socket (and, with the Redis adapter, every replica's pub/sub link) receives a
* full copy of a payload that can carry media up to MEDIA_DOWNLOAD_MAX_BYTES (~67 MB base64 for
* the 50 MiB cap); status.received already keeps its events media-free.
*/
private messageMediaInlineMaxBytes(): number {
return this.configService.get<number>('webhook.mediaInlineMaxBytes', DEFAULT_WEBHOOK_MEDIA_INLINE_MAX_BYTES);
}
/**
* Emit new message notification
*/
emitMessage(sessionId: string, message: Record<string, unknown>) {
this.emitToRooms(sessionId, 'message.received', this.shedMessageMedia(message));
}
/**
* Emit message sent notification
*/
emitMessageSent(sessionId: string, message: Record<string, unknown>) {
this.emitToRooms(sessionId, 'message.sent', this.shedMessageMedia(message));
}
private shedMessageMedia(message: Record<string, unknown>): Record<string, unknown> {
return shedInlineMedia(message, this.messageMediaInlineMaxBytes());
}
/**
* Emit a live delivery-status update. The payload mirrors the `message.ack` webhook exactly
* (`id`, `messageId`, neutral `status`, the deprecated legacy numeric `ack`, and `chatId` when
* the engine's update named the chat) so a socket client and a webhook consumer see the same
* shape.
*/
emitMessageAck(
sessionId: string,
data: { id: string; messageId: string; status: DeliveryStatus; ack: number; chatId?: string },
) {
this.emitToRooms(sessionId, 'message.ack', data);
}
/**
* Emit one recipient's receipt for a group or status message the account sent. Mirrors the
* `message.receipt` webhook. Not delivered to '*' subscriptions (see WILDCARD_EXCLUDED_EVENTS).
*/
emitMessageReceipt(
sessionId: string,
data: {
id: string;
messageId: string;
chatId: string;
participant: string;
status: MessageReceiptStatus;
timestamp: number;
},
) {
this.emitToRooms(sessionId, 'message.receipt', data);
}
/**
* Emit message revoked ("deleted for everyone") notification
*/
emitMessageRevoked(sessionId: string, message: Record<string, unknown>) {
this.emitToRooms(sessionId, 'message.revoked', message);
}
/**
* Emit message reaction notification
*/
emitMessageReaction(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'message.reaction', data);
}
/**
* Emit message edited notification
*/
emitMessageEdited(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'message.edited', data);
}
/**
* Emit a group membership join (a user was added or joined via invite). Payload mirrors the
* `group.join` webhook: `{ groupId, participantIds, timestamp, actorId? }`.
*/
emitGroupJoin(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'group.join', data);
}
/**
* Emit a group membership leave (a user left or was removed). Payload mirrors the
* `group.leave` webhook: `{ groupId, participantIds, timestamp, actorId? }`.
*/
emitGroupLeave(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'group.leave', data);
}
/**
* Emit a group metadata update (subject/description/announce/locked). Payload mirrors the
* `group.update` webhook: `{ groupId, participantIds, changes, timestamp, actorId? }`.
*/
emitGroupUpdate(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'group.update', data);
}
/**
* Emit a pending join request (someone asked to join a group the account admins, join-approval
* on). Payload mirrors the `group.join_request` webhook:
* `{ groupId, participantIds, timestamp, actorId? }` — participantIds are the users asking to
* join; actorId is who created the request when the engine reports one.
*/
emitGroupJoinRequest(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'group.join_request', data);
}
/**
* Emit an incoming-call notification (a call is ringing). Payload mirrors the `call.received`
* webhook: `{ callId, from, isVideo, isGroup, timestamp }`.
*/
emitCallReceived(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'call.received', data);
}
/**
* Emit a freshly ingested contact status (story). Payload mirrors the `status.received`
* webhook — no media bytes, just identity/type/flags — so the dashboard can refresh its
* statuses view live instead of waiting for a focus refetch.
*/
emitStatusReceived(sessionId: string, data: Record<string, unknown>) {
this.emitToRooms(sessionId, 'status.received', data);
}
}