@miqro/core 5.1.5 → 5.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/websocket.ts CHANGED
@@ -21,6 +21,26 @@ export class WebSocketServer implements ConnectionUpgrader {
21
21
  return !this.clients.has(uuid);
22
22
  }
23
23
 
24
+ /**
25
+ * With no allowedOrigins and no validate() every origin is accepted, which is the old
26
+ * behaviour. It is warned about once rather than changed, because refusing by default
27
+ * would break every existing deployment on upgrade.
28
+ */
29
+ protected isOriginAllowed(req: Request): boolean {
30
+ const allowed = this.options.allowedOrigins;
31
+ if (!allowed) {
32
+ if (!this.originWarned && !this.options.validate) {
33
+ this.originWarned = true;
34
+ req.logger.warn("WebSocketServer has no allowedOrigins and no validate, every origin can open a connection");
35
+ }
36
+ return true;
37
+ }
38
+ const origin = req.headers.origin;
39
+ return typeof origin === "string" && allowed.indexOf(origin) !== -1;
40
+ }
41
+
42
+ private originWarned = false;
43
+
24
44
  public async broadcast(data: string, fromUUID?: string) {
25
45
  const tR = [];
26
46
  const clients = this.clients.values();
@@ -74,6 +94,22 @@ export class WebSocketServer implements ConnectionUpgrader {
74
94
  }
75
95
 
76
96
  public async onUpgrade(req: Request, socket: Duplex, head: Buffer) {
97
+ // node removes its own socket error handler before emitting "upgrade", so this
98
+ // listener has to be in place before the first await below. a client that resets
99
+ // while validate() is still running would otherwise emit an unhandled "error"
100
+ // and take down the process.
101
+ let upgradedClient: WebSocketClient | undefined = undefined;
102
+ socket.on("error", async (error) => {
103
+ req.logger.debug("upgraded connection error!");
104
+ req.logger.error(error);
105
+ if (upgradedClient && this.options.onError) {
106
+ try {
107
+ await this.options.onError(upgradedClient, error);
108
+ } catch (e) {
109
+ req.logger.error(e);
110
+ }
111
+ }
112
+ });
77
113
  const acceptKey = req.headers["sec-websocket-key"];
78
114
  req.logger.debug("validating with acceptKey [%s]", acceptKey);
79
115
  if (
@@ -81,12 +117,24 @@ export class WebSocketServer implements ConnectionUpgrader {
81
117
  (!req.headers.connection || String(req.headers.connection).toLocaleLowerCase().indexOf("upgrade") === -1) ||
82
118
  String(req.headers.upgrade).toLocaleLowerCase() !== "websocket" ||
83
119
  String(req.method).toUpperCase() !== "GET" ||
84
- !acceptKey
120
+ !acceptKey ||
121
+ // RFC 6455 4.2.1: version 13 is the only one this implements, and the key is 16 random
122
+ // bytes base64 encoded. Neither was checked, so a client speaking an older draft got a
123
+ // 101 and then talked a protocol nobody here parses.
124
+ String(req.headers["sec-websocket-version"]) !== "13" ||
125
+ !isValidWebSocketKey(acceptKey)
85
126
  ) {
86
127
  req.logger.warn("bad request");
87
128
  socket.end("HTTP/1.1 400 Bad Request");
88
129
  socket.destroy();
89
130
  return;
131
+ } else if (!this.isOriginAllowed(req)) {
132
+ // a WebSocket upgrade is not subject to the same origin policy and cookies are sent
133
+ // with it, so without this any site can open an authenticated socket
134
+ req.logger.warn("origin [%s] not allowed", req.headers.origin);
135
+ socket.end("HTTP/1.1 403 Forbidden");
136
+ socket.destroy();
137
+ return;
90
138
  } else {
91
139
  const validateRet = this.options.validate ? await this.options.validate(req) : true;
92
140
  const uuid = typeof validateRet === "boolean" ?
@@ -119,39 +167,69 @@ export class WebSocketServer implements ConnectionUpgrader {
119
167
  req,
120
168
  socket
121
169
  };
170
+ upgradedClient = client;
122
171
  req.logger.debug("upgrading connection");
123
172
 
124
- socket.write(createUpgradeHeaders(acceptKey, extraHeaders));
173
+ let upgradeHeaders: string;
174
+ try {
175
+ upgradeHeaders = createUpgradeHeaders(acceptKey, extraHeaders);
176
+ } catch (e) {
177
+ // an extra header the app asked for cannot be written safely, so nothing is written
178
+ req.logger.error(e);
179
+ socket.end("HTTP/1.1 500 Internal Server Error");
180
+ socket.destroy();
181
+ return;
182
+ }
183
+ socket.write(upgradeHeaders);
184
+
185
+ const closeWith = (code: number, reason: string) => {
186
+ req.logger.warn("closing upgraded connection [%s] with [%s]: %s", uuid, code, reason);
187
+ try {
188
+ socket.write(createCloseFrame(code));
189
+ } catch (e) {
190
+ req.logger.error(e);
191
+ }
192
+ socket.end();
193
+ socket.destroy();
194
+ };
125
195
 
126
- socket.on("data", async (data: Buffer) => {
196
+ const onFrame = async (data: Buffer) => {
127
197
  try {
128
198
  const frame = parseFrame(data, this.options.maxFrameSize);
129
- if (frame === PING) {
130
- try {
131
- socket.write(Buffer.from([0x8A, 0x00])); // pong frame
132
- } catch (e) {
133
- req.logger.error(e);
134
- }
135
- } else if (frame !== null) {
136
- if (!this.options.onMessage) {
137
- socket.end();
138
- socket.destroy();
139
- } else {
199
+ switch (frame.kind) {
200
+ case "ping":
140
201
  try {
141
- await this.options.onMessage(client, frame);
202
+ socket.write(Buffer.from([0x8A, 0x00])); // pong frame
142
203
  } catch (e) {
143
204
  req.logger.error(e);
144
205
  }
145
- }
146
- } else {
147
- // send close frame back and clean up
148
- try {
149
- socket.write(Buffer.from([0x88, 0x00]));
150
- } catch (e) {
151
- req.logger.error(e);
152
- }
153
- socket.end();
154
- socket.destroy();
206
+ break;
207
+ case "pong":
208
+ // an unsolicited pong is legal and means the peer is alive. dropping the
209
+ // connection for it, which is what returning null used to do, killed healthy
210
+ // clients that answer their own keepalives.
211
+ req.logger.debug("pong from [%s]", uuid);
212
+ break;
213
+ case "close":
214
+ closeWith(CLOSE_NORMAL, "peer sent close");
215
+ break;
216
+ case "incomplete":
217
+ closeWith(CLOSE_TOO_BIG, "frame split across chunks, reassembly is not supported");
218
+ break;
219
+ case "protocolError":
220
+ closeWith(frame.code, frame.reason);
221
+ break;
222
+ case "text":
223
+ if (!this.options.onMessage) {
224
+ closeWith(CLOSE_UNSUPPORTED_DATA, "no onMessage handler configured");
225
+ } else {
226
+ try {
227
+ await this.options.onMessage(client, frame.data);
228
+ } catch (e) {
229
+ req.logger.error(e);
230
+ }
231
+ }
232
+ break;
155
233
  }
156
234
  } catch (e) {
157
235
  try {
@@ -162,21 +240,16 @@ export class WebSocketServer implements ConnectionUpgrader {
162
240
  console.error(e);
163
241
  }
164
242
  }
165
- });
243
+ };
166
244
 
167
- socket.on("error", async (error) => {
168
- req.logger.debug("upgraded connection error!");
169
- req.logger.error(error);
170
- if (this.options.onError) {
171
- try {
172
- await this.options.onError(client, error);
173
- } catch (e) {
174
- req.logger.error(e);
175
- }
176
- }
177
- });
245
+ socket.on("data", onFrame);
178
246
 
179
- socket.on("end", async () => {
247
+ let disconnectNotified = false;
248
+ const onSocketDisconnect = async () => {
249
+ if (disconnectNotified) {
250
+ return;
251
+ }
252
+ disconnectNotified = true;
180
253
  req.logger.debug("upgraded connection disconnected!");
181
254
  this.clients.delete(uuid);
182
255
  if (this.options.onDisconnect) {
@@ -186,7 +259,14 @@ export class WebSocketServer implements ConnectionUpgrader {
186
259
  req.logger.error(e);
187
260
  }
188
261
  }
189
- });
262
+ };
263
+ // "end" fires on a clean FIN from the peer and leaves the socket half-open, so
264
+ // it is the only signal on that path. it never fires for a reset, a timeout, or
265
+ // a teardown we started ourselves (bad frame, oversized frame, failed write) --
266
+ // those only produce "close", and without it the registry entry leaked and the
267
+ // disconnect went unreported. the flag keeps the two from double-reporting.
268
+ socket.on("end", onSocketDisconnect);
269
+ socket.on("close", onSocketDisconnect);
190
270
 
191
271
 
192
272
 
@@ -199,6 +279,12 @@ export class WebSocketServer implements ConnectionUpgrader {
199
279
  req.logger.error(e);
200
280
  }
201
281
  }
282
+ // a client that writes its first frame in the same packet as the handshake has that
283
+ // frame delivered here, not through "data". it was stored on the client and never
284
+ // read, so the message was lost.
285
+ if (head && head.length > 0) {
286
+ await onFrame(head);
287
+ }
202
288
  return;
203
289
  }
204
290
  }
@@ -216,6 +302,14 @@ export interface ClusterWebSocketServerMessage {
216
302
  payload?: Serializable;
217
303
  }
218
304
 
305
+ /**
306
+ * @deprecated Use miqro's ClusterWebSocketServer2, which this is a stale near duplicate of.
307
+ *
308
+ * The differences are not cosmetic: this class has a `static instance` singleton guard, so a
309
+ * process can only ever have one of them, and its messages carry no `target`, so every
310
+ * instance would receive every other instance's traffic anyway -- one WebSocket path per
311
+ * process, total. It also never prunes remoteClients when a worker dies.
312
+ */
219
313
  export class ClusterWebSocketServer extends WebSocketServer {
220
314
  public static instance: ClusterWebSocketServer;
221
315
  public remoteClients: Set<string> = new Set();
@@ -371,9 +465,31 @@ export class ClusterWebSocketServer extends WebSocketServer {
371
465
  * Private
372
466
  */
373
467
 
374
- const PING = Symbol()
375
- const OPCODES = { text: 0x01, close: 0x08, ping: 0x09, pong: 0x0A };
468
+ const OPCODES = { continuation: 0x00, text: 0x01, binary: 0x02, close: 0x08, ping: 0x09, pong: 0x0A };
376
469
  const GUID: string = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
470
+
471
+ /**
472
+ * RFC 6455 4.1: the key is 16 random bytes, base64 encoded.
473
+ */
474
+ export function isValidWebSocketKey(key: string | string[]): boolean {
475
+ if (typeof key !== "string" || !/^[A-Za-z0-9+/]{22}==$/.test(key)) {
476
+ return false;
477
+ }
478
+ return Buffer.from(key, "base64").length === 16;
479
+ }
480
+
481
+ /**
482
+ * A header name or value carrying CR or LF ends the header and starts another one, so an app
483
+ * echoing anything request derived through validate()'s headers would let the caller append
484
+ * headers to the 101 response, or a body after it. Refusing the upgrade is the only safe
485
+ * outcome: the header cannot be dropped silently, the app asked for it to be sent.
486
+ */
487
+ function assertHeaderSafe(part: string, what: string): void {
488
+ if (typeof part !== "string" || /[\r\n\0]/.test(part)) {
489
+ throw new Error(`invalid character in websocket upgrade header ${what} [${JSON.stringify(part)}]`);
490
+ }
491
+ }
492
+
377
493
  //Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly
378
494
  function createUpgradeHeaders(acceptKey: string, extraHeaders?: {
379
495
  name: string;
@@ -382,69 +498,158 @@ function createUpgradeHeaders(acceptKey: string, extraHeaders?: {
382
498
  const acceptValue = createHash('sha1')
383
499
  .update(acceptKey + GUID, 'binary')
384
500
  .digest('base64');
501
+ if (extraHeaders) {
502
+ for (const header of extraHeaders) {
503
+ assertHeaderSafe(header.name, "name");
504
+ assertHeaderSafe(header.value, "value");
505
+ }
506
+ }
385
507
  let extra = extraHeaders && extraHeaders.length > 0 ? `\r\n${extraHeaders.map(h => `${h.name}: ${h.value}`).join("\r\n")}` : "";
386
508
  return `HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${acceptValue}${extra}\r\n\r\n`;
387
509
  }
388
510
 
389
511
  const DEFAULT_MAX_FRAME_SIZE = 1024 * 1024; // 1 MiB
390
512
 
391
- function parseFrame(buffer: Buffer, maxFrameSize = DEFAULT_MAX_FRAME_SIZE) {
513
+ /**
514
+ * RFC 6455 close codes used here.
515
+ */
516
+ export const CLOSE_NORMAL = 1000;
517
+ export const CLOSE_PROTOCOL_ERROR = 1002;
518
+ export const CLOSE_UNSUPPORTED_DATA = 1003;
519
+ export const CLOSE_TOO_BIG = 1009;
520
+
521
+ export type ParsedFrame =
522
+ { kind: "text"; data: string; } |
523
+ { kind: "ping"; } |
524
+ { kind: "pong"; } |
525
+ { kind: "close"; } |
526
+ { kind: "incomplete"; } |
527
+ { kind: "protocolError"; code: number; reason: string; };
528
+
529
+ function protocolError(code: number, reason: string): ParsedFrame {
530
+ return { kind: "protocolError", code, reason };
531
+ }
532
+
533
+ const INCOMPLETE: ParsedFrame = { kind: "incomplete" };
534
+
535
+ /**
536
+ * Parses a single frame out of one chunk.
537
+ *
538
+ * This parser does not reassemble. A chunk that carries less than a whole frame is
539
+ * "incomplete" and a fragmented message (FIN=0, or a continuation opcode) is a protocol
540
+ * error, so both end the connection with a close code. That is deliberate: silently
541
+ * handing a truncated payload -- possibly cut mid codepoint -- to onMessage, and then
542
+ * reading the next chunk's payload byte as an opcode, is worse than refusing the message.
543
+ *
544
+ * Every read is bounds checked. A one byte chunk used to throw a RangeError from
545
+ * readUInt8(1), which the caller then treated as a bad frame and destroyed the socket.
546
+ */
547
+ export function parseFrame(buffer: Buffer, maxFrameSize = DEFAULT_MAX_FRAME_SIZE): ParsedFrame {
548
+ if (buffer.length < 2) {
549
+ return INCOMPLETE;
550
+ }
551
+
392
552
  const firstByte = buffer.readUInt8(0);
393
- const opCode = firstByte & 0b00001111; // get last 4 bits of a byte
553
+ const fin = (firstByte & 0b10000000) !== 0;
554
+ const rsv = firstByte & 0b01110000;
555
+ const opCode = firstByte & 0b00001111;
556
+
557
+ // no extension is ever negotiated, so a reserved bit can only be noise or an attempt to
558
+ // negotiate one out of band
559
+ if (rsv !== 0) {
560
+ return protocolError(CLOSE_PROTOCOL_ERROR, "reserved bit set without a negotiated extension");
561
+ }
394
562
 
395
- if (opCode === OPCODES.close) {
396
- //this.emit('close');
397
- return null;
398
- } else if (opCode === OPCODES.ping) {
399
- return PING;
400
- } else if (opCode !== OPCODES.text) {
401
- return null;
563
+ if (opCode === OPCODES.continuation || !fin) {
564
+ return protocolError(CLOSE_TOO_BIG, "fragmented messages are not supported");
565
+ }
566
+
567
+ if (opCode === OPCODES.binary) {
568
+ return protocolError(CLOSE_UNSUPPORTED_DATA, "binary frames are not supported");
402
569
  }
403
570
 
404
- const secondByte = buffer.readUInt8(1); // start with a payload length
571
+ if (opCode !== OPCODES.text && opCode !== OPCODES.ping && opCode !== OPCODES.pong && opCode !== OPCODES.close) {
572
+ return protocolError(CLOSE_PROTOCOL_ERROR, `unknown opcode [${opCode}]`);
573
+ }
405
574
 
575
+ const secondByte = buffer.readUInt8(1);
576
+ const isMasked = (secondByte & 0b10000000) !== 0;
577
+ let payloadLength = secondByte & 0b01111111;
406
578
  let offset = 2;
407
- let payloadLength = secondByte & 0b01111111; // get last 7 bits of a second byte
408
579
 
409
580
  if (payloadLength === 126) {
410
- payloadLength = buffer.readUInt16BE(offset); // read real 16-bit length
581
+ if (buffer.length < offset + 2) {
582
+ return INCOMPLETE;
583
+ }
584
+ payloadLength = buffer.readUInt16BE(offset);
411
585
  offset += 2;
412
586
  } else if (payloadLength === 127) {
413
- payloadLength = Number(buffer.readBigUInt64BE(offset)); // read real 64-bit length
587
+ if (buffer.length < offset + 8) {
588
+ return INCOMPLETE;
589
+ }
590
+ const declared = buffer.readBigUInt64BE(offset);
414
591
  offset += 8;
592
+ if (declared > BigInt(Number.MAX_SAFE_INTEGER)) {
593
+ return protocolError(CLOSE_TOO_BIG, "declared payload length is not representable");
594
+ }
595
+ payloadLength = Number(declared);
415
596
  }
416
597
 
417
598
  if (payloadLength > maxFrameSize) {
418
- return null;
599
+ return protocolError(CLOSE_TOO_BIG, `frame of ${payloadLength} bytes exceeds maxFrameSize ${maxFrameSize}`);
419
600
  }
420
601
 
421
- const isMasked = Boolean((secondByte >>> 7) & 0x1); // get first bit of a second byte
602
+ // RFC 6455 5.1: a server must close the connection on an unmasked client frame
603
+ if (!isMasked) {
604
+ return protocolError(CLOSE_PROTOCOL_ERROR, "client frame is not masked");
605
+ }
422
606
 
423
- if (isMasked) {
424
- const maskingKey = buffer.readUInt32BE(offset); // read 4-byte mask
425
- offset += 4;
426
- const payload = buffer.subarray(offset, offset + payloadLength);
427
- const result = unmask(payload, maskingKey);
428
- return result.toString('utf-8');
607
+ if (buffer.length < offset + 4) {
608
+ return INCOMPLETE;
429
609
  }
610
+ const maskingKey = buffer.subarray(offset, offset + 4);
611
+ offset += 4;
430
612
 
431
- return buffer.subarray(offset, offset + payloadLength).toString('utf-8');
613
+ if (buffer.length < offset + payloadLength) {
614
+ return INCOMPLETE;
615
+ }
616
+
617
+ if (opCode === OPCODES.ping) {
618
+ return { kind: "ping" };
619
+ }
620
+ if (opCode === OPCODES.pong) {
621
+ return { kind: "pong" };
622
+ }
623
+ if (opCode === OPCODES.close) {
624
+ return { kind: "close" };
625
+ }
626
+
627
+ const payload = unmask(buffer.subarray(offset, offset + payloadLength), maskingKey);
628
+ return { kind: "text", data: payload.toString("utf-8") };
432
629
  }
433
630
 
434
- function unmask(payload: Buffer, maskingKey: number) {
631
+ function unmask(payload: Buffer, maskingKey: Buffer) {
435
632
  const result = Buffer.alloc(payload.byteLength);
436
633
 
437
634
  for (let i = 0; i < payload.byteLength; ++i) {
438
- const j = i % 4;
439
- const maskingKeyByteShift = j === 3 ? 0 : (3 - j) << 3;
440
- const maskingKeyByte = (maskingKeyByteShift === 0 ? maskingKey : maskingKey >>> maskingKeyByteShift) & 0b11111111;
441
- const transformedByte = maskingKeyByte ^ payload.readUInt8(i);
442
- result.writeUInt8(transformedByte, i);
635
+ result[i] = payload[i] ^ maskingKey[i % 4];
443
636
  }
444
637
 
445
638
  return result;
446
639
  }
447
640
 
641
+ /**
642
+ * Close frame carrying a status code, so the peer learns why instead of seeing a bare
643
+ * teardown.
644
+ */
645
+ function createCloseFrame(code: number): Buffer {
646
+ const frame = Buffer.alloc(4);
647
+ frame[0] = 0x88;
648
+ frame[1] = 0x02;
649
+ frame.writeUInt16BE(code, 2);
650
+ return frame;
651
+ }
652
+
448
653
  function createFrame(payload: string) {
449
654
 
450
655
  const payloadByteLength = Buffer.byteLength(payload);