@libp2p/webrtc 6.0.33 → 6.1.0-4a416447c

package/src/private-to-public/utils/stun-listener.ts

@@ -1,6 +1,7 @@
 import { isIPv4 } from '@chainsafe/is-ip'
 import { IceUdpMuxListener } from 'node-datachannel'
-import { handleStunRequest } from '../../util.ts'
+import { handleStunRequest } from './stun.ts'
+import type { StunRequestCallback } from './stun.ts'
 import type { Logger } from '@libp2p/interface'
 import type { AddressInfo } from 'node:net'
 
@@ -9,14 +10,15 @@ export interface StunServer {
   address(): AddressInfo
 }
 
-export interface Callback {
-  (ufrag: string, remoteHost: string, remotePort: number): void
-}
-
-export async function stunListener (host: string, port: number, log: Logger, cb: Callback): Promise<StunServer> {
+export async function stunListener (host: string, port: number, log: Logger, cb: StunRequestCallback): Promise<StunServer> {
   const listener = new IceUdpMuxListener(port, host)
   listener.onUnhandledStunRequest(request => {
-    handleStunRequest(request, log, cb)
+    // this runs inside a native callback where a throw would crash the process
+    try {
+      handleStunRequest(request, log, cb)
+    } catch (err) {
+      log.error('error handling STUN request from %s:%d - %e', request.host, request.port, err)
+    }
   })
 
   return {

package/src/private-to-public/utils/stun.ts

@@ -0,0 +1,128 @@
+import { UFRAG_PREFIX_V1, UFRAG_PREFIX_V2 } from '../../constants.ts'
+import type { Logger } from '@libp2p/interface'
+import type { IceUdpMuxRequest } from 'node-datachannel'
+
+// ICE credential charset and length, per RFC 8839 section 5.4
+// (ice-char = ALPHA / DIGIT / "+" / "/"; ufrag = 4*256ice-char;
+// password = 22*256ice-char).
+//
+// ice-char is ASCII-only, so any string that passes ICE_CHAR_REGEX has exactly
+// one UTF-16 code unit per character. The String.length checks below therefore
+// equal both the ice-char count and the byte length that go-libp2p measures with
+// len(), so the two implementations accept the same credentials; non-ice-char
+// input (including any multi-byte character) is rejected by both regardless of
+// how each counts length.
+const ICE_CHAR_REGEX = /^[A-Za-z0-9+/]+$/
+const ICE_UFRAG_MIN_LENGTH = 4
+const ICE_PWD_MIN_LENGTH = 22
+const ICE_CREDENTIAL_MAX_LENGTH = 256
+
+/**
+ * True if `value` is a valid ICE username fragment
+ * (RFC 8839 section 5.4: ufrag = 4*256ice-char).
+ */
+export function isIceUfrag (value: string): boolean {
+  return value.length >= ICE_UFRAG_MIN_LENGTH && value.length <= ICE_CREDENTIAL_MAX_LENGTH && ICE_CHAR_REGEX.test(value)
+}
+
+/**
+ * True if `value` is a valid ICE password
+ * (RFC 8839 section 5.4: password = 22*256ice-char).
+ */
+export function isIcePwd (value: string): boolean {
+  return value.length >= ICE_PWD_MIN_LENGTH && value.length <= ICE_CREDENTIAL_MAX_LENGTH && ICE_CHAR_REGEX.test(value)
+}
+
+export function parseStunUsernameUfrags (serverUfrag: string, clientUfrag: string): { serverUfrag: string, clientUfrag: string } | undefined {
+  // Both fragments come from the attacker-controlled STUN USERNAME
+  // ("<remote-ufrag>:<local-ufrag>", RFC 8445 section 7.2.2) and are ICE username
+  // fragments. Reject anything outside ice-char or the length bounds in RFC 8839
+  // section 5.4 before it goes into an SDP offer.
+  if (!isIceUfrag(serverUfrag) || !isIceUfrag(clientUfrag)) {
+    return undefined
+  }
+
+  return {
+    serverUfrag,
+    clientUfrag
+  }
+}
+
+/**
+ * The v2 server ufrag carries the client's ICE password so the server can
+ * infer the client's offer from the STUN USERNAME alone.
+ */
+export function serverUfragV2 (clientIcePwd: string): string {
+  return `${UFRAG_PREFIX_V2}${clientIcePwd}`
+}
+
+export function decodeV2ClientPwd (serverUfrag: string): string | undefined {
+  if (!serverUfrag.startsWith(UFRAG_PREFIX_V2)) {
+    return undefined
+  }
+
+  const clientPwd = serverUfrag.substring(UFRAG_PREFIX_V2.length)
+
+  // The recovered value becomes the inferred offer's ice-pwd, so it must be a
+  // valid ICE password (ice-char, length 22..256) per RFC 8839 section 5.4.
+  if (!isIcePwd(clientPwd)) {
+    return undefined
+  }
+
+  return clientPwd
+}
+
+export interface StunRequestCallback {
+  (serverUfrag: string, clientUfrag: string, clientPwd: string | undefined, remoteHost: string, remotePort: number): void
+}
+
+/**
+ * Validate a STUN request received by the UDP mux listener and forward the ICE
+ * credentials it carries. Every value comes from the attacker-controlled STUN
+ * USERNAME and is reused as an ICE credential during native connection setup,
+ * where an invalid value aborts the process, so anything malformed is dropped
+ * here.
+ */
+export function handleStunRequest (request: IceUdpMuxRequest, log: Logger, cb: StunRequestCallback): void {
+  if (request.ufrag == null) {
+    return
+  }
+
+  // The STUN USERNAME is "server_ufrag:client_ufrag" (RFC 8445 section 7.2.2),
+  // libjuice drops usernames without a colon so both halves are always present
+  const serverUfrag = request.localUfrag
+  const clientUfrag = request.ufrag
+
+  const parsed = parseStunUsernameUfrags(serverUfrag, clientUfrag)
+  if (parsed == null) {
+    log.trace('incoming STUN packet from %s:%d had invalid ufrags %s %s', request.host, request.port, serverUfrag, clientUfrag)
+    return
+  }
+
+  // Select the version explicitly from the server ufrag prefix. An unrecognized
+  // version is rejected, never assumed to be v1. See https://github.com/libp2p/specs/blob/master/webrtc/webrtc-direct.md.
+  if (parsed.serverUfrag.startsWith(UFRAG_PREFIX_V2)) {
+    const clientPwd = decodeV2ClientPwd(parsed.serverUfrag)
+    if (clientPwd == null) {
+      log.trace('incoming v2 STUN packet from %s:%d had an invalid client password %s', request.host, request.port, parsed.serverUfrag)
+      return
+    }
+    log.trace('incoming v2 STUN packet from %s:%d %s:%s', request.host, request.port, parsed.serverUfrag, parsed.clientUfrag)
+    cb(parsed.serverUfrag, parsed.clientUfrag, clientPwd, request.host, request.port)
+    return
+  }
+
+  if (parsed.serverUfrag.startsWith(UFRAG_PREFIX_V1)) {
+    // v1 reuses both ufrags as ICE passwords, so they must also satisfy the
+    // password length bound or native setup aborts the process
+    if (!isIcePwd(parsed.serverUfrag) || !isIcePwd(parsed.clientUfrag)) {
+      log.trace('incoming v1 STUN packet from %s:%d had ufrags that are not valid ICE passwords %s %s', request.host, request.port, parsed.serverUfrag, parsed.clientUfrag)
+      return
+    }
+    log.trace('incoming v1 STUN packet from %s:%d %s', request.host, request.port, parsed.serverUfrag)
+    cb(parsed.serverUfrag, parsed.clientUfrag, undefined, request.host, request.port)
+    return
+  }
+
+  log.trace('incoming STUN packet from %s:%d has an unsupported version prefix %s', request.host, request.port, parsed.serverUfrag)
+}

package/src/util.ts

@@ -1,9 +1,9 @@
 import pDefer from 'p-defer'
 import pTimeout from 'p-timeout'
-import { DATA_CHANNEL_DRAIN_TIMEOUT, DEFAULT_ICE_SERVERS, UFRAG_ALPHABET, UFRAG_PREFIX } from './constants.ts'
-import type { Logger, LoggerOptions } from '@libp2p/interface'
+import { DATA_CHANNEL_DRAIN_TIMEOUT, DEFAULT_ICE_SERVERS, UFRAG_ALPHABET, UFRAG_PREFIX_V1 } from './constants.ts'
+import type { LoggerOptions } from '@libp2p/interface'
 import type { Duplex, Source } from 'it-stream-types'
-import type { IceUdpMuxRequest, PeerConnection } from 'node-datachannel'
+import type { PeerConnection } from 'node-datachannel'
 
 export const nopSource = async function * nop (): AsyncGenerator<Uint8Array, any, unknown> {}
 
@@ -102,33 +102,6 @@ export async function getRtcConfiguration (config?: RTCConfiguration | (() => RT
   return config
 }
 
-export const genUfrag = (len: number = 32): string => {
-  return UFRAG_PREFIX + [...Array(len)].map(() => UFRAG_ALPHABET.at(Math.floor(Math.random() * UFRAG_ALPHABET.length))).join('')
-}
-
-// WebRTC-direct reuses the ufrag as the ICE password, which RFC 8445 requires to
-// be 22-256 chars from the ice-char set [a-zA-Z0-9+/]; other values crash the
-// process during native ICE setup, so reject them beforehand.
-const ICE_CREDENTIAL_REGEX = /^[a-zA-Z0-9+/]{22,256}$/
-
-export const isValidUfrag = (ufrag: string): boolean => {
-  return ICE_CREDENTIAL_REGEX.test(ufrag)
-}
-
-// Validate and forward a STUN request received by the UDP mux listener. The ufrag
-// is attacker-controlled and reused as the ICE password in native setup, where an
-// invalid value aborts the process, so drop anything that is not a valid credential.
-export function handleStunRequest (request: IceUdpMuxRequest, log: Logger, cb: (ufrag: string, host: string, port: number) => void): void {
-  if (request.ufrag == null) {
-    return
-  }
-
-  if (!isValidUfrag(request.ufrag)) {
-    log.trace('dropping incoming STUN packet from %s:%d with invalid ufrag', request.host, request.port)
-    return
-  }
-
-  log.trace('incoming STUN packet from %s:%d %s', request.host, request.port, request.ufrag)
-
-  cb(request.ufrag, request.host, request.port)
+export const genUfrag = (len: number = 32, prefix: string = UFRAG_PREFIX_V1): string => {
+  return prefix + [...Array(len)].map(() => UFRAG_ALPHABET.at(Math.floor(Math.random() * UFRAG_ALPHABET.length))).join('')
 }

package/src/webrtc/node-datachannel.browser.ts

@@ -0,0 +1,17 @@
+class NodeDataChannelUnavailableError extends Error {
+  constructor () {
+    super('node-datachannel is not available in browsers')
+  }
+}
+
+export class PeerConnection {
+  constructor () {
+    throw new NodeDataChannelUnavailableError()
+  }
+}
+
+export class IceUdpMuxListener {
+  constructor () {
+    throw new NodeDataChannelUnavailableError()
+  }
+}

package/dist/typedoc-urls.json

@@ -1,14 +0,0 @@
-{
-  "DataChannelOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_webrtc.DataChannelOptions.html",
-  ".:DataChannelOptions": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_webrtc.DataChannelOptions.html",
-  "TransportCertificate": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_webrtc.TransportCertificate.html",
-  ".:TransportCertificate": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_webrtc.TransportCertificate.html",
-  "WebRTCDirectTransportComponents": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_webrtc.WebRTCDirectTransportComponents.html",
-  "WebRTCTransportComponents": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_webrtc.WebRTCTransportComponents.html",
-  "WebRTCTransportDirectInit": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_webrtc.WebRTCTransportDirectInit.html",
-  "WebRTCTransportInit": "https://libp2p.github.io/js-libp2p/interfaces/_libp2p_webrtc.WebRTCTransportInit.html",
-  "webRTC": "https://libp2p.github.io/js-libp2p/functions/_libp2p_webrtc.webRTC.html",
-  ".:webRTC": "https://libp2p.github.io/js-libp2p/functions/_libp2p_webrtc.webRTC.html",
-  "webRTCDirect": "https://libp2p.github.io/js-libp2p/functions/_libp2p_webrtc.webRTCDirect.html",
-  ".:webRTCDirect": "https://libp2p.github.io/js-libp2p/functions/_libp2p_webrtc.webRTCDirect.html"
-}