beatrina 0.8.6

package/host/ws.mjs

@@ -0,0 +1,190 @@
+// ws.mjs — a WebSocket SERVER, RFC 6455, over Node's http upgrade event.
+//
+// Node ships a WebSocket client (>= 22) and no server, and the host has no
+// dependencies by decision (tools/mcp/carmar-mcp.mjs and test/fixtures/
+// ws-origin.mjs set the precedent: a few hundred lines of protocol beat a
+// package the security review must then read). What this implements is the
+// subset a notebook page uses: text frames, masked client → unmasked server,
+// ping answered, close handshake, continuation reassembled. No extensions, no
+// permessage-deflate (the client never negotiates one; a request for it is
+// simply not granted).
+//
+// The gate is the caller's. `attachWebSocket` hands every upgrade request to
+// `gate(req)` first and refuses with the returned status/text when it answers
+// anything but null — that is where Origin and Host are decided, and it is
+// deliberately outside this file so the protocol code never grows an opinion
+// about trust.
+
+import crypto from "node:crypto";
+
+const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+/** A single message larger than this closes the socket (1009). serve.R's
+ *  8 MB refusal is applied by the frame handler above; this is the ceiling
+ *  under which a message is even assembled. */
+const MAX_MESSAGE_BYTES = 16 * 1024 * 1024;
+
+/**
+ * @typedef {Object} WsSocket
+ * @property {(text: string) => boolean} send   false when the socket is gone
+ * @property {(code?: number, reason?: string) => void} close
+ * @property {(fn: (text: string) => void) => void} onMessage
+ * @property {(fn: () => void) => void} onClose
+ * @property {import("node:http").IncomingMessage} request  the upgrade request, kept —
+ *   the gate's reasoning is recomputed from it (socket_class in serve.R)
+ * @property {boolean} open
+ */
+
+/**
+ * Listen for upgrades on an http.Server.
+ *
+ * @param {import("node:http").Server} server
+ * @param {Object} opts
+ * @param {(req: import("node:http").IncomingMessage) => (null | {status:number, body:string})} opts.gate
+ * @param {(socket: WsSocket) => void} opts.onOpen
+ */
+export function attachWebSocket(server, { gate, onOpen }) {
+  server.on("upgrade", (req, raw, head) => {
+    const refusal = gate(req);
+    if (refusal) {
+      raw.write(`HTTP/1.1 ${refusal.status} ${statusText(refusal.status)}\r\n`
+        + "Content-Type: text/plain\r\nCache-Control: no-store\r\nConnection: close\r\n"
+        + `Content-Length: ${Buffer.byteLength(refusal.body)}\r\n\r\n${refusal.body}`);
+      raw.destroy();
+      return;
+    }
+    const key = req.headers["sec-websocket-key"];
+    const version = req.headers["sec-websocket-version"];
+    if (String(req.headers.upgrade || "").toLowerCase() !== "websocket" || !key || version !== "13") {
+      raw.write("HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+      raw.destroy();
+      return;
+    }
+    const accept = crypto.createHash("sha1").update(key + GUID).digest("base64");
+    raw.write("HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n"
+      + `Sec-WebSocket-Accept: ${accept}\r\n\r\n`);
+    raw.setNoDelay(true);
+    const socket = wrap(raw, req, head);
+    onOpen(socket);
+  });
+}
+
+function wrap(raw, request, head) {
+  let buf = head && head.length ? Buffer.from(head) : Buffer.alloc(0);
+  let partial = null;          // continuation in progress: {opcode, chunks, bytes}
+  let open = true;
+  let closeSent = false;
+  const messageHandlers = [];
+  const closeHandlers = [];
+
+  const finish = () => {
+    if (!open) return;
+    open = false;
+    closeHandlers.forEach((fn) => { try { fn(); } catch { /* a listener must not break teardown */ } });
+  };
+  const sendFrame = (opcode, payload) => {
+    if (!open || raw.destroyed) return false;
+    try { raw.write(frame(opcode, payload)); return true; } catch { return false; }
+  };
+  const closeWith = (code, reason = "") => {
+    if (!closeSent) {
+      closeSent = true;
+      const body = Buffer.concat([Buffer.from([code >> 8, code & 0xff]), Buffer.from(reason, "utf8")]);
+      sendFrame(0x8, body);
+    }
+    // Give the peer's close frame a moment, then drop the transport either way.
+    setTimeout(() => { try { raw.destroy(); } catch { /* gone */ } }, 200).unref();
+    finish();
+  };
+
+  raw.on("data", (chunk) => {
+    buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+    drain();
+  });
+  raw.on("close", finish);
+  raw.on("error", finish);
+  raw.on("end", () => { try { raw.end(); } catch { /* gone */ } finish(); });
+
+  function drain() {
+    for (;;) {
+      if (buf.length < 2) return;
+      const fin = (buf[0] & 0x80) !== 0;
+      const rsv = buf[0] & 0x70;
+      const opcode = buf[0] & 0x0f;
+      const masked = (buf[1] & 0x80) !== 0;
+      let len = buf[1] & 0x7f;
+      let off = 2;
+      if (len === 126) {
+        if (buf.length < 4) return;
+        len = buf.readUInt16BE(2); off = 4;
+      } else if (len === 127) {
+        if (buf.length < 10) return;
+        const big = buf.readBigUInt64BE(2);
+        if (big > BigInt(MAX_MESSAGE_BYTES)) return closeWith(1009, "message too big");
+        len = Number(big); off = 10;
+      }
+      // A client MUST mask (RFC 6455 §5.1) and no extension was negotiated, so
+      // a set RSV bit is a protocol error, not a feature.
+      if (!masked || rsv !== 0) return closeWith(1002, "protocol error");
+      if (buf.length < off + 4 + len) return;
+      const mask = buf.subarray(off, off + 4);
+      const payload = Buffer.from(buf.subarray(off + 4, off + 4 + len));
+      buf = buf.subarray(off + 4 + len);
+      for (let i = 0; i < payload.length; i += 1) payload[i] ^= mask[i & 3];
+
+      if (opcode === 0x8) {                 // close: echo, then drop
+        if (!closeSent) { closeSent = true; sendFrame(0x8, payload.subarray(0, 2)); }
+        try { raw.end(); } catch { /* gone */ }
+        finish();
+        return;
+      }
+      if (opcode === 0x9) { sendFrame(0xa, payload); continue; }   // ping → pong
+      if (opcode === 0xa) continue;                                 // pong: a reply to nothing we sent
+      if (opcode === 0x1 || opcode === 0x2) {
+        if (partial) return closeWith(1002, "interleaved message");
+        partial = { opcode, chunks: [payload], bytes: payload.length };
+      } else if (opcode === 0x0) {
+        if (!partial) return closeWith(1002, "continuation without a start");
+        partial.chunks.push(payload);
+        partial.bytes += payload.length;
+      } else {
+        return closeWith(1002, "unknown opcode");
+      }
+      if (partial.bytes > MAX_MESSAGE_BYTES) return closeWith(1009, "message too big");
+      if (!fin) continue;
+      const message = partial.chunks.length === 1 ? partial.chunks[0] : Buffer.concat(partial.chunks);
+      const isText = partial.opcode === 0x1;
+      partial = null;
+      // Binary is not the protocol (serve.R: `if (is.raw(message)) return`).
+      // Dropped without error, exactly as there.
+      if (!isText) continue;
+      const text = message.toString("utf8");
+      messageHandlers.forEach((fn) => { try { fn(text); } catch { /* a handler must not break the read loop */ } });
+    }
+  }
+
+  return {
+    request,
+    get open() { return open; },
+    send: (text) => sendFrame(0x1, Buffer.from(String(text), "utf8")),
+    close: (code = 1000, reason = "") => closeWith(code, reason),
+    onMessage: (fn) => { messageHandlers.push(fn); },
+    onClose: (fn) => { closeHandlers.push(fn); },
+  };
+}
+
+/** A server frame: never masked. */
+function frame(opcode, payload) {
+  const body = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload), "utf8");
+  let head;
+  if (body.length < 126) head = Buffer.from([0x80 | opcode, body.length]);
+  else if (body.length < 65536) {
+    head = Buffer.alloc(4); head[0] = 0x80 | opcode; head[1] = 126; head.writeUInt16BE(body.length, 2);
+  } else {
+    head = Buffer.alloc(10); head[0] = 0x80 | opcode; head[1] = 127; head.writeBigUInt64BE(BigInt(body.length), 2);
+  }
+  return Buffer.concat([head, body]);
+}
+
+function statusText(status) {
+  return { 400: "Bad Request", 403: "Forbidden", 404: "Not Found", 429: "Too Many Requests" }[status] || "Error";
+}