@johnhenry/wsh 0.21.0 → 0.23.0

package/src/server/self-signed.mjs

@@ -0,0 +1,121 @@
+/**
+ * A short-lived self-signed certificate for WebTransport's
+ * `serverCertificateHashes` pinning, with no dependency: the X.509 structure
+ * is small enough to assemble as DER by hand, and `node:crypto` signs it.
+ *
+ * The web platform's rules for a pinned certificate (what a browser enforces):
+ * an ECDSA P-256 key, a validity period of at most 14 days, and the page pins
+ * the SHA-256 of the DER certificate. Nothing else about it is checked (no
+ * chain, and the name is not matched), but the subject alternative names are
+ * filled in anyway so the same certificate also works for a client that does.
+ */
+
+import { createHash, generateKeyPairSync, randomBytes, sign } from 'node:crypto';
+import net from 'node:net';
+
+/** What a browser allows for `serverCertificateHashes`. */
+export const MAX_PINNED_CERT_DAYS = 14;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const OID = {
+  ecdsaWithSha256: '2a8648ce3d040302',
+  commonName: '550403',
+  subjectAltName: '551d11',
+  extKeyUsage: '551d25',
+  serverAuth: '2b06010505070301',
+  keyUsage: '551d0f',
+};
+
+// ── DER ──────────────────────────────────────────────────────────────
+
+const concat = (...parts) => Buffer.concat(parts.map((p) => (Buffer.isBuffer(p) ? p : Buffer.from(p))));
+function der(tag, ...content) {
+  const body = concat(...content);
+  const n = body.length;
+  const len = n < 0x80 ? Buffer.from([n]) : n < 0x100 ? Buffer.from([0x81, n]) : Buffer.from([0x82, n >> 8, n & 0xff]);
+  return concat(Buffer.from([tag]), len, body);
+}
+const seq = (...c) => der(0x30, ...c);
+const set = (...c) => der(0x31, ...c);
+const oid = (hex) => der(0x06, Buffer.from(hex, 'hex'));
+const utf8 = (s) => der(0x0c, Buffer.from(s, 'utf8'));
+const octets = (b) => der(0x04, b);
+const bitString = (b) => der(0x03, Buffer.from([0]), b);
+/** Positive INTEGER from big-endian bytes. */
+function integer(bytes) {
+  let b = Buffer.from(bytes);
+  while (b.length > 1 && b[0] === 0) b = b.subarray(1);
+  if (b[0] & 0x80) b = concat(Buffer.from([0]), b);
+  return der(0x02, b);
+}
+function utcTime(date) {
+  const p = (n) => String(n).padStart(2, '0');
+  return der(0x17, Buffer.from(`${p(date.getUTCFullYear() % 100)}${p(date.getUTCMonth() + 1)}${p(date.getUTCDate())}${p(date.getUTCHours())}${p(date.getUTCMinutes())}${p(date.getUTCSeconds())}Z`, 'ascii'));
+}
+
+function ipBytes(addr) {
+  if (net.isIPv4(addr)) return Buffer.from(addr.split('.').map(Number));
+  // IPv6, possibly with "::" compression
+  const [head, tail = ''] = addr.split('::');
+  const h = head ? head.split(':') : [];
+  const t = tail ? tail.split(':') : [];
+  const groups = [...h, ...Array(8 - h.length - t.length).fill('0'), ...t];
+  return Buffer.from(groups.flatMap((g) => { const v = parseInt(g || '0', 16); return [v >> 8, v & 0xff]; }));
+}
+
+function pem(label, derBytes) {
+  const b64 = derBytes.toString('base64').match(/.{1,64}/g).join('\n');
+  return `-----BEGIN ${label}-----\n${b64}\n-----END ${label}-----\n`;
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string[]} [opts.hosts=['localhost', '127.0.0.1', '::1']] - DNS names and IP addresses for the SAN.
+ * @param {number} [opts.validityDays=13] - At most 14 (a browser refuses a pinned certificate valid for longer).
+ * @param {Date} [opts.now]
+ * @returns {{ cert: string, privKey: string, hash: Uint8Array, hashHex: string, notBefore: Date, notAfter: Date }}
+ *   `cert` / `privKey` are PEM; `hash` is the SHA-256 of the DER certificate, the value to pin.
+ */
+export function generateSelfSignedCertificate({ hosts = ['localhost', '127.0.0.1', '::1'], validityDays = 13, now = new Date() } = {}) {
+  if (!(validityDays > 0) || validityDays > MAX_PINNED_CERT_DAYS) {
+    throw new RangeError(`selfSigned: validityDays must be in (0, ${MAX_PINNED_CERT_DAYS}] -- browsers refuse a pinned certificate valid for longer`);
+  }
+  const { publicKey, privateKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' });
+  // An hour of back-dating tolerates clock skew; the whole window stays under 14 days for validityDays <= 13.
+  const skewMs = Math.min(60 * 60 * 1000, (MAX_PINNED_CERT_DAYS - validityDays) * DAY_MS);
+  const notBefore = new Date(Math.floor((now.getTime() - skewMs) / 1000) * 1000);
+  const notAfter = new Date(Math.floor((now.getTime() + validityDays * DAY_MS - skewMs) / 1000) * 1000);
+
+  const name = seq(set(seq(oid(OID.commonName), utf8('wsh self-signed'))));
+  const san = seq(...hosts.map((h) => (net.isIP(h) ? der(0x87, ipBytes(h)) : der(0x82, Buffer.from(h, 'ascii')))));
+  const extensions = der(0xa3, seq(
+    seq(oid(OID.keyUsage), der(0x01, Buffer.from([0xff])), octets(bitString(Buffer.from([0x80])))), // digitalSignature
+    seq(oid(OID.extKeyUsage), octets(seq(oid(OID.serverAuth)))),
+    seq(oid(OID.subjectAltName), octets(san)),
+  ));
+  const serial = randomBytes(16);
+  serial[0] &= 0x7f;
+  serial[0] |= 0x01;
+
+  const tbs = seq(
+    der(0xa0, integer([2])),                              // v3
+    integer(serial),
+    seq(oid(OID.ecdsaWithSha256)),
+    name,
+    seq(utcTime(notBefore), utcTime(notAfter)),
+    name,
+    publicKey.export({ type: 'spki', format: 'der' }),
+    extensions,
+  );
+  const signature = sign('sha256', tbs, privateKey);       // DER-encoded ECDSA-Sig-Value
+  const certDer = seq(tbs, seq(oid(OID.ecdsaWithSha256)), bitString(signature));
+  const hash = new Uint8Array(createHash('sha256').update(certDer).digest());
+  return {
+    cert: pem('CERTIFICATE', certDer),
+    privKey: privateKey.export({ type: 'pkcs8', format: 'pem' }),
+    hash,
+    hashHex: Buffer.from(hash).toString('hex'),
+    notBefore,
+    notAfter,
+  };
+}

package/src/server/webtransport.mjs

@@ -0,0 +1,188 @@
+/**
+ * WebTransport listener for `@johnhenry/wsh/server` (`createWshServer({ webTransport })`).
+ *
+ * QUIC already multiplexes, so the QMux layer the WebSocket path needs is not
+ * used. A session's FIRST bidirectional stream is the control stream (the
+ * client's `WebTransportTransport` opens it first): length-prefixed CBOR
+ * frames, exactly what `frameEncode` / `FrameDecoder` speak. Every later
+ * bidirectional stream the client opens is a data stream, bound to the next
+ * exec channel in `OpenOk` order like a QMux one.
+ *
+ * Streams a client creates are visible to the host the moment they are
+ * created (HTTP/3 sends the stream's WebTransport header with it), so the
+ * host's `stream-announce` feature holds here as it does over QMux: the
+ * client writes no primer.
+ *
+ * `@fails-components/webtransport` (and its native HTTP/3 transport package)
+ * are optional peers, imported only when `webTransport` is given.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { FrameDecoder, frameEncode } from '../cbor.mjs';
+import { generateSelfSignedCertificate } from './self-signed.mjs';
+
+const DEFAULT_PATH = '/wsh';
+
+/** What a QMux stream looks like to the connection code, over a WebTransport bidirectional stream. */
+function adaptStream({ readable, writable }, onGone) {
+  const writer = writable.getWriter();
+  const reader = readable.getReader();
+  const stream = {
+    onData: null,
+    onEnd: null,
+    onReset: null,
+    write: (bytes) => writer.write(bytes),
+    close: async () => { try { await writer.close(); } catch { /* peer gone or already closed */ } },
+    /** Start delivering: after the consumer has had the chance to set its handlers. */
+    start() {
+      (async () => {
+        try {
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) { stream.onEnd?.(); return; }
+            stream.onData?.(value);
+          }
+        } catch {
+          stream.onReset?.();
+        } finally {
+          onGone?.();
+        }
+      })();
+    },
+  };
+  return stream;
+}
+
+/**
+ * @param {object} opts
+ * @param {object} opts.options - `createWshServer`'s `webTransport` option
+ * @param {string} opts.host
+ * @param {(opts: object) => { receiveMessage: Function, bindStream: Function, close: Function }} opts.attach
+ * @param {(line: string) => void} opts.log
+ * @returns {Promise<{ port: number, host: string, path: string, certificateHash: Uint8Array | null, certificateHashHex: string | null, notAfter: Date | null, close(): Promise<void> }>}
+ */
+export async function startWebTransport({ options, host, attach, log }) {
+  const { port = 0, path = DEFAULT_PATH, selfSigned = false } = options;
+  let { cert, privKey } = options;
+  let generated = null;
+  if (selfSigned) {
+    if (cert || privKey) throw new TypeError('createWshServer: webTransport takes either selfSigned or cert/privKey, not both');
+    generated = generateSelfSignedCertificate(typeof selfSigned === 'object' ? selfSigned : {});
+    ({ cert, privKey } = generated);
+  }
+  if (!cert || !privKey) throw new TypeError('createWshServer: webTransport needs cert and privKey (PEM), or selfSigned: true');
+  if (typeof path !== 'string' || !path.startsWith('/')) throw new TypeError('createWshServer: webTransport.path must start with "/"');
+
+  let wtLib;
+  try {
+    wtLib = await import('@fails-components/webtransport');
+    await wtLib.quicheLoaded;
+  } catch (err) {
+    throw new Error(
+      'WebTransport needs the optional packages "@fails-components/webtransport" and '
+      + '"@fails-components/webtransport-transport-http3-quiche": npm install @fails-components/webtransport @fails-components/webtransport-transport-http3-quiche',
+      { cause: err },
+    );
+  }
+
+  const server = new wtLib.Http3Server({
+    port, host: options.host ?? host, secret: options.secret ?? randomBytes(16).toString('hex'), cert, privKey,
+  });
+  const sessions = server.sessionStream(path);
+  server.startServer();
+  try {
+    await server.ready;
+  } catch (err) {
+    try { server.stopServer(); } catch { /* never started */ }
+    throw err;
+  }
+  const addr = server.address();
+
+  const live = new Set();
+  let closing = false;
+
+  async function serve(session) {
+    let conn = null;
+    let closed = false;
+    const end = () => { if (!closed) { closed = true; live.delete(session); conn?.close(); } };
+    live.add(session);
+    session.closed.then(end, end);
+    try {
+      await session.ready;
+    } catch { end(); return; }
+
+    let controlWriter = null;
+    const decoder = new FrameDecoder();
+    conn = attach({
+      sendMessage: (msg) => (controlWriter ? controlWriter.write(frameEncode(msg)) : undefined),
+      remote: { address: session.peerAddress, headers: session.header ?? {} },
+      closeTransport: () => { try { session.close(); } catch { /* already closed */ } },
+    });
+
+    const incoming = session.incomingBidirectionalStreams.getReader();
+    let first = true;
+    try {
+      for (;;) {
+        const { done, value: bidi } = await incoming.read();
+        if (done) break;
+        if (first) {
+          first = false;
+          controlWriter = bidi.writable.getWriter();
+          const reader = bidi.readable.getReader();
+          (async () => {
+            try {
+              for (;;) {
+                const { done: fin, value } = await reader.read();
+                if (fin) break;
+                let msgs;
+                try { msgs = decoder.feed(value); } catch (e) { log(`webtransport frame decode error: ${e.message}`); break; }
+                for (const m of msgs) conn.receiveMessage(m);
+              }
+            } catch { /* session went away */ }
+            end();
+          })();
+        } else {
+          const s = adaptStream(bidi);
+          conn.bindStream(s);
+          s.start();
+        }
+      }
+    } catch { /* session closed under us */ }
+    end();
+  }
+
+  (async () => {
+    const reader = sessions.getReader();
+    try {
+      for (;;) {
+        const { done, value: session } = await reader.read();
+        if (done || closing) break;
+        serve(session).catch((e) => log(`webtransport session error: ${e.message}`));
+      }
+    } catch { /* server stopped */ }
+  })();
+
+  const bound = {
+    port: addr.port,
+    host: addr.host,
+    path,
+    certificateHash: generated?.hash ?? null,
+    certificateHashHex: generated?.hashHex ?? null,
+    notAfter: generated?.notAfter ?? null,
+    async close() {
+      closing = true;
+      const open = [...live];
+      for (const s of open) { try { s.close(); } catch { /* gone */ } }
+      // Let the close reach the peers before the socket is torn down (bounded: a peer that never acks cannot hold shutdown).
+      await Promise.race([
+        Promise.allSettled(open.map((s) => s.closed)),
+        new Promise((r) => { const t = setTimeout(r, 500); t.unref?.(); }),
+      ]);
+      live.clear();
+      try { server.stopServer(); } catch { /* already stopped */ }
+    },
+  };
+  log(`webtransport listening on https://${addr.host}:${addr.port}${path}`
+    + (generated ? ` (self-signed, sha-256 ${generated.hashHex}, until ${generated.notAfter.toISOString()})` : ''));
+  return bound;
+}

package/src/transport.mjs

@@ -493,6 +493,11 @@ export class WebTransportTransport extends WshTransport {
     const wt = wtOptions ? new WebTransport(url, wtOptions) : new WebTransport(url);
     this.#wt = wt;
 
+    // A session that never becomes ready rejects `closed` as well as `ready`. Nothing
+    // observes `closed` until #monitorClosed (below, after `ready`), so the second
+    // rejection would surface as an unhandled one -- fatal in Node.
+    wt.closed?.catch?.(() => {});
+
     // Wait for the connection to be ready.
     await wt.ready;