@peerkit/transport-libp2p-react-native 0.1.0-alpha.13

package/src/polyfills.ts

@@ -0,0 +1,72 @@
+/**
+ * Runtime polyfills required by libp2p when running on React Native (Hermes).
+ *
+ * Side-effect import from the app entry, **before any other import**:
+ *
+ * ```ts
+ * import "@peerkit/transport-libp2p-react-native/polyfills";
+ * ```
+ *
+ * Order matters:
+ *  1. `react-native-get-random-values` — patches `globalThis.crypto.getRandomValues`.
+ *     Must run first so anything that touches RNG during module init (peer-id,
+ *     noise key generation) observes the JSI implementation.
+ *  2. `react-native-quick-crypto` `install()` — installs the JSI-backed
+ *     `globalThis.crypto.subtle` (Ed25519, X25519, AES-GCM, ChaCha20-Poly1305,
+ *     HMAC, SHA-256) used by `@chainsafe/libp2p-noise`.
+ *  3. `react-native-webrtc` `registerGlobals()` — defines the global
+ *     `RTCPeerConnection`, `RTCSessionDescription`, etc. used by
+ *     `@libp2p/webrtc`, followed by `installWebRtcCertificatePolyfill()` which
+ *     adds the static `RTCPeerConnection.generateCertificate` method the
+ *     webrtc-direct dialer needs but `react-native-webrtc` does not provide
+ *     (see `webrtc-certificate-polyfill`), and
+ *     `installDataChannelEarlyMessagePolyfill()` which recovers the first
+ *     inbound datachannel message `react-native-webrtc` drops during connection
+ *     setup, otherwise mobile-to-mobile stream handshakes hang (see
+ *     `datachannel-early-message-polyfill`).
+ *
+ * It also installs the WHATWG `Event` / `EventTarget` / `CustomEvent` globals
+ * that Hermes lacks but libp2p extends at module-evaluation time (see
+ * `event-target-polyfill`), plus the `TextEncoder` / `TextDecoder` globals that
+ * `uint8arrays` constructs at module-evaluation time (see `text-codec-polyfill`).
+ * Those steps are order-independent relative to the three above.
+ *
+ * Consumers must also configure Metro to map bare Node imports (`crypto`,
+ * `stream`, `buffer`, `events`) to their React Native equivalents and enable
+ * `@babel/plugin-transform-private-methods` (loose) so libp2p's ES2022
+ * private fields parse under Hermes. See the package README for the full
+ * Metro / Babel configuration.
+ */
+
+import "react-native-get-random-values";
+import { Buffer } from "buffer";
+import process from "process";
+import { install as installQuickCrypto } from "react-native-quick-crypto";
+import { registerGlobals as registerWebRtcGlobals } from "react-native-webrtc";
+import { installDataChannelEarlyMessagePolyfill } from "./datachannel-early-message-polyfill.js";
+import { installEventTargetPolyfill } from "./event-target-polyfill.js";
+import { installTextCodecPolyfill } from "./text-codec-polyfill.js";
+import { installWebRtcCertificatePolyfill } from "./webrtc-certificate-polyfill.js";
+import { installWebSocketBufferedAmountPolyfill } from "./websocket-buffered-amount-polyfill.js";
+
+// Buffer + process must live on globalThis: some libp2p dependencies reach for these as globals
+// rather than as ES module imports. Metro's `extraNodeModules` only rewrites
+// bare imports — code that touches `globalThis.Buffer` or
+// `globalThis.process.nextTick` directly relies on this assignment.
+const globalScope = globalThis as {
+  Buffer?: typeof Buffer;
+  process?: typeof process;
+};
+globalScope.Buffer ??= Buffer;
+globalScope.process ??= process;
+
+installEventTargetPolyfill();
+installTextCodecPolyfill();
+installWebSocketBufferedAmountPolyfill();
+installQuickCrypto();
+registerWebRtcGlobals();
+// Must run after `registerWebRtcGlobals()`: both patch the global
+// `RTCPeerConnection` that step installs (the early-message polyfill also probes
+// it for the `RTCDataChannel` prototype).
+installWebRtcCertificatePolyfill();
+installDataChannelEarlyMessagePolyfill();

package/src/quick-crypto-noise.ts

@@ -0,0 +1,130 @@
+/**
+ * `ICryptoInterface` implementation backed by `react-native-quick-crypto`,
+ * intended to be passed to `noise({ crypto: quickCryptoNoise })` on React
+ * Native. JSI-backed primitives are noticeably faster than the pure-JS Noise
+ * defaults on Hermes, which matters for handshake latency and bulk transfer.
+ *
+ * Only the primitives that have a usable synchronous quick-crypto mapping are
+ * overridden:
+ *
+ *  - `hashSHA256` — `createHash('sha256')`
+ *  - `getHKDF` — RFC 5869 HKDF built on `createHmac('sha256', ...)`
+ *  - `chaCha20Poly1305Encrypt` / `chaCha20Poly1305Decrypt` —
+ *    `createCipheriv` / `createDecipheriv` with the `chacha20-poly1305`
+ *    AEAD, 16-byte authentication tag appended to / split from the
+ *    ciphertext per the Noise specification.
+ *
+ * X25519 key generation and shared-secret derivation are delegated to
+ * `pureJsCrypto` because the quick-crypto X25519 API is asynchronous
+ * (subtle-style) whereas `ICryptoInterface` requires synchronous methods.
+ * The pure-JS X25519 implementation is fast enough that JSI offers little
+ * practical gain.
+ *
+ * This module pulls in `react-native-quick-crypto` at import time and must
+ * therefore only be imported in a React Native bundle. It is exposed via the
+ * dedicated `./quick-crypto-noise` subexport so the package's main entry
+ * remains free of React Native-only side effects.
+ */
+
+import { pureJsCrypto, type ICryptoInterface } from "@chainsafe/libp2p-noise";
+import QuickCrypto from "react-native-quick-crypto";
+import type { Uint8ArrayList } from "uint8arraylist";
+
+const TAG_LENGTH = 16;
+
+function toBytes(data: Uint8Array | Uint8ArrayList): Uint8Array {
+  // `Uint8ArrayList.subarray()` returns a contiguous Uint8Array view, which
+  // is what quick-crypto's Node-compatible API expects.
+  return data instanceof Uint8Array ? data : data.subarray();
+}
+
+function hashSHA256(data: Uint8Array | Uint8ArrayList): Uint8Array {
+  return QuickCrypto.createHash("sha256").update(toBytes(data)).digest();
+}
+
+function hmacSHA256(key: Uint8Array, data: Uint8Array): Uint8Array {
+  return QuickCrypto.createHmac("sha256", key).update(data).digest();
+}
+
+function getHKDF(
+  ck: Uint8Array,
+  ikm: Uint8Array,
+): [Uint8Array, Uint8Array, Uint8Array] {
+  // RFC 5869 HKDF with SHA-256, three 32-byte outputs as required by the
+  // Noise specification. Extract step: PRK = HMAC(ck, ikm). Expand step:
+  // outN = HMAC(PRK, outN-1 || counter), starting from an empty previous
+  // block.
+  const prk = hmacSHA256(ck, ikm);
+  const out1 = hmacSHA256(prk, new Uint8Array([0x01]));
+
+  const out2Input = new Uint8Array(out1.length + 1);
+  out2Input.set(out1, 0);
+  out2Input[out1.length] = 0x02;
+  const out2 = hmacSHA256(prk, out2Input);
+
+  const out3Input = new Uint8Array(out2.length + 1);
+  out3Input.set(out2, 0);
+  out3Input[out2.length] = 0x03;
+  const out3 = hmacSHA256(prk, out3Input);
+
+  return [out1, out2, out3];
+}
+
+function chaCha20Poly1305Encrypt(
+  plaintext: Uint8Array | Uint8ArrayList,
+  nonce: Uint8Array,
+  ad: Uint8Array,
+  k: Uint8Array,
+): Uint8Array {
+  const cipher = QuickCrypto.createCipheriv("chacha20-poly1305", k, nonce, {
+    authTagLength: TAG_LENGTH,
+  });
+  cipher.setAAD(ad);
+  const head = cipher.update(toBytes(plaintext));
+  const tail = cipher.final();
+  const tag = cipher.getAuthTag();
+  // Noise wire format: ciphertext || tag (16 bytes).
+  const out = new Uint8Array(head.length + tail.length + tag.length);
+  out.set(head, 0);
+  out.set(tail, head.length);
+  out.set(tag, head.length + tail.length);
+  return out;
+}
+
+function chaCha20Poly1305Decrypt(
+  ciphertext: Uint8Array | Uint8ArrayList,
+  nonce: Uint8Array,
+  ad: Uint8Array,
+  k: Uint8Array,
+): Uint8Array {
+  const bytes = toBytes(ciphertext);
+  if (bytes.length < TAG_LENGTH) {
+    throw new Error("ChaCha20-Poly1305 ciphertext shorter than tag length");
+  }
+  const ct = bytes.subarray(0, bytes.length - TAG_LENGTH);
+  const tag = bytes.subarray(bytes.length - TAG_LENGTH);
+  const decipher = QuickCrypto.createDecipheriv("chacha20-poly1305", k, nonce, {
+    authTagLength: TAG_LENGTH,
+  });
+  decipher.setAAD(ad);
+  decipher.setAuthTag(tag);
+  const head = decipher.update(ct);
+  const tail = decipher.final();
+  const out = new Uint8Array(head.length + tail.length);
+  out.set(head, 0);
+  out.set(tail, head.length);
+  return out;
+}
+
+/**
+ * Quick-crypto-backed Noise crypto. Inherits synchronous X25519 operations
+ * from `pureJsCrypto`; overrides SHA-256, HKDF, and ChaCha20-Poly1305 with
+ * JSI-backed implementations.
+ */
+export const quickCryptoNoise: ICryptoInterface = {
+  ...pureJsCrypto,
+  hashSHA256,
+  getHKDF,
+  chaCha20Poly1305Encrypt,
+  chaCha20Poly1305Decrypt,
+};

package/src/rn-modules.d.ts

@@ -0,0 +1,100 @@
+// Ambient module declarations for React Native-only packages that ship without
+// TypeScript types or are not resolvable in the workspace's host toolchain.
+// Real implementations are pulled in by Metro at app build time; here we only
+// need enough surface to let `tsc` type-check `polyfills.ts`.
+
+declare module "react-native-get-random-values";
+
+declare module "react-native-quick-crypto" {
+  export function install(): void;
+
+  type BinaryLike = Uint8Array;
+
+  export interface Hash {
+    update(data: BinaryLike): Hash;
+    digest(): Uint8Array;
+  }
+
+  export interface Hmac {
+    update(data: BinaryLike): Hmac;
+    digest(): Uint8Array;
+  }
+
+  export interface CipherOptions {
+    authTagLength?: number;
+  }
+
+  export interface Cipher {
+    setAAD(buffer: BinaryLike): Cipher;
+    update(data: BinaryLike): Uint8Array;
+    final(): Uint8Array;
+    getAuthTag(): Uint8Array;
+  }
+
+  export interface Decipher {
+    setAAD(buffer: BinaryLike): Decipher;
+    setAuthTag(tag: BinaryLike): Decipher;
+    update(data: BinaryLike): Uint8Array;
+    final(): Uint8Array;
+  }
+
+  export function createHash(algorithm: "sha256"): Hash;
+  export function createHmac(algorithm: "sha256", key: BinaryLike): Hmac;
+  export function createCipheriv(
+    algorithm: "chacha20-poly1305",
+    key: BinaryLike,
+    iv: BinaryLike,
+    options?: CipherOptions,
+  ): Cipher;
+  export function createDecipheriv(
+    algorithm: "chacha20-poly1305",
+    key: BinaryLike,
+    iv: BinaryLike,
+    options?: CipherOptions,
+  ): Decipher;
+
+  const QuickCrypto: {
+    install: typeof install;
+    createHash: typeof createHash;
+    createHmac: typeof createHmac;
+    createCipheriv: typeof createCipheriv;
+    createDecipheriv: typeof createDecipheriv;
+  };
+  export default QuickCrypto;
+}
+
+declare module "react-native-webrtc" {
+  export function registerGlobals(): void;
+}
+
+declare module "react-native" {
+  export const NativeModules: Record<string, unknown>;
+
+  export interface NativeEventSubscription {
+    remove(): void;
+  }
+
+  export class NativeEventEmitter {
+    constructor(nativeModule?: unknown);
+    addListener(
+      eventType: string,
+      listener: (event: unknown) => void,
+    ): NativeEventSubscription;
+  }
+}
+
+declare module "buffer" {
+  export const Buffer: {
+    from(...args: readonly unknown[]): unknown;
+    alloc(...args: readonly unknown[]): unknown;
+    isBuffer(value: unknown): boolean;
+  };
+}
+
+declare module "process" {
+  const process: {
+    nextTick(callback: () => void): void;
+    env: Record<string, string | undefined>;
+  };
+  export default process;
+}

package/src/text-codec-polyfill.ts

@@ -0,0 +1,118 @@
+/**
+ * A `TextEncoder` / `TextDecoder` polyfill for the React Native Hermes engine.
+ *
+ * Hermes ships neither global, yet libp2p reaches for them at
+ * module-evaluation time: `uint8arrays` (a transitive dependency of nearly
+ * every libp2p package) constructs `new TextEncoder()` / `new TextDecoder()`
+ * to convert between UTF-8 strings and byte arrays for peer ids, multiaddrs,
+ * and protocol names. Without these globals the bundle red-screens with
+ * `Property 'TextDecoder' doesn't exist` before any application code runs.
+ *
+ * Only UTF-8 is implemented — the single encoding libp2p uses through these
+ * APIs. The conversion is delegated to `Buffer` (already a required shim, see
+ * `polyfills`), which provides a spec-correct UTF-8 implementation including
+ * surrogate-pair handling and replacement of malformed sequences. Owning a
+ * thin wrapper here, rather than pulling in a third-party text-encoding
+ * package, keeps the polyfill surface small and dependency-free.
+ */
+
+import { Buffer } from "buffer";
+
+const UTF8_ENCODING = "utf-8";
+
+// The WHATWG labels that all denote UTF-8. A `TextDecoder` constructed with any
+// other label must throw, matching browser behavior and surfacing accidental
+// non-UTF-8 usage rather than silently misdecoding.
+const UTF8_LABELS: ReadonlySet<string> = new Set([
+  "utf-8",
+  "utf8",
+  "unicode-1-1-utf-8",
+]);
+
+interface TextDecoderOptionsLike {
+  readonly fatal?: boolean;
+  readonly ignoreBOM?: boolean;
+}
+
+// A `Buffer` is a `Uint8Array` whose `toString` accepts an encoding argument.
+// The package's ambient `buffer` declaration (see `rn-modules.d.ts`) types
+// `from` loosely as returning `unknown`; this narrows it to just the surface
+// the codec needs without widening that shared shim.
+interface Utf8Buffer extends Uint8Array {
+  toString(encoding?: string): string;
+}
+
+interface BufferFactory {
+  from(value: string, encoding: string): Utf8Buffer;
+  from(
+    value: ArrayBufferLike,
+    byteOffset?: number,
+    length?: number,
+  ): Utf8Buffer;
+}
+
+const bufferFactory = Buffer as unknown as BufferFactory;
+
+/** WHATWG `TextEncoder`, UTF-8 only. */
+class PolyfillTextEncoder {
+  get encoding(): string {
+    return UTF8_ENCODING;
+  }
+
+  encode(input: string = ""): Uint8Array {
+    return new Uint8Array(bufferFactory.from(input, "utf8"));
+  }
+}
+
+/**
+ * WHATWG `TextDecoder`, UTF-8 only.
+ *
+ * `fatal` and `ignoreBOM` are accepted and reflected as readonly properties for
+ * API-shape compatibility, but not honored: `Buffer.toString('utf8')` always
+ * replaces malformed sequences (`fatal: false`) and never strips a BOM. libp2p
+ * constructs decoders with default options, so this is sufficient — a caller
+ * relying on `fatal`/`ignoreBOM` semantics is out of this polyfill's scope.
+ */
+class PolyfillTextDecoder {
+  readonly encoding = UTF8_ENCODING;
+  readonly fatal: boolean;
+  readonly ignoreBOM: boolean;
+
+  constructor(
+    label: string = UTF8_ENCODING,
+    options: TextDecoderOptionsLike = {},
+  ) {
+    if (!UTF8_LABELS.has(label.toLowerCase())) {
+      throw new RangeError(
+        `Unsupported encoding: ${label}. Only UTF-8 is supported.`,
+      );
+    }
+    this.fatal = options.fatal ?? false;
+    this.ignoreBOM = options.ignoreBOM ?? false;
+  }
+
+  decode(input?: ArrayBuffer | ArrayBufferView): string {
+    if (input == null) {
+      return "";
+    }
+    const bytes = ArrayBuffer.isView(input)
+      ? bufferFactory.from(input.buffer, input.byteOffset, input.byteLength)
+      : bufferFactory.from(input);
+    return bytes.toString("utf8");
+  }
+}
+
+/**
+ * Install `TextEncoder` and `TextDecoder` on the global scope if the runtime
+ * does not already provide them. Idempotent and safe to call more than once;
+ * on a runtime that ships its own implementations (e.g. Node in tests) this is
+ * a no-op.
+ */
+export function installTextCodecPolyfill(): void {
+  const codecScope = globalThis as {
+    TextEncoder?: unknown;
+    TextDecoder?: unknown;
+  };
+  codecScope.TextEncoder ??= PolyfillTextEncoder;
+  codecScope.TextDecoder ??= PolyfillTextDecoder;
+}

package/src/webrtc-certificate-polyfill.ts

@@ -0,0 +1,60 @@
+/**
+ * Give React Native's `RTCPeerConnection` the static `generateCertificate`
+ * method that `@libp2p/webrtc`'s webrtc-direct dialer requires.
+ *
+ * Metro selects the browser build of `@libp2p/webrtc` on React Native. Its
+ * dialer creates the peer connection like this:
+ *
+ * ```js
+ * const certificate = await RTCPeerConnection.generateCertificate({
+ *   name: "ECDSA",
+ *   namedCurve: "P-256",
+ * });
+ * new RTCPeerConnection({ certificates: [certificate] });
+ * ```
+ *
+ * `react-native-webrtc` (v124) implements neither the static
+ * `generateCertificate` method nor the `certificates` constructor option — it
+ * always generates its own DTLS certificate natively — so the dialer throws
+ * `RTCPeerConnection.generateCertificate is not a function`.
+ *
+ * Supplying a specific certificate is unnecessary for webrtc-direct. The dialer
+ * reads its own fingerprint back out of the generated local SDP
+ * (`getFingerprintFromSdp(peerConnection.localDescription.sdp)`) and binds it
+ * into the Noise prologue, so the certificate the native layer produces is the
+ * one that actually gets authenticated. We only need the call to resolve: the
+ * returned value is forwarded as the `certificates` option, which
+ * `react-native-webrtc` does not read, so a plain placeholder object that the
+ * native bridge can serialize is sufficient.
+ */
+
+interface CertificateCapablePeerConnection {
+  generateCertificate?: (algorithm?: unknown) => Promise<unknown>;
+}
+
+const CERTIFICATE_TTL_MS = 365 * 24 * 60 * 60 * 1000;
+
+/**
+ * Install the static `generateCertificate` method on the global
+ * `RTCPeerConnection`. Idempotent, and a no-op when the global is absent
+ * (`registerGlobals()` has not run, or under tests) or already provides the
+ * method (a browser, or a future `react-native-webrtc` release).
+ */
+export function installWebRtcCertificatePolyfill(): void {
+  const scope = globalThis as {
+    RTCPeerConnection?: CertificateCapablePeerConnection;
+  };
+  const peerConnection = scope.RTCPeerConnection;
+  if (peerConnection == null) {
+    return;
+  }
+  if (typeof peerConnection.generateCertificate === "function") {
+    return;
+  }
+  peerConnection.generateCertificate = (): Promise<unknown> => {
+    // react-native-webrtc generates its own DTLS certificate natively; libp2p
+    // reads the resulting fingerprint from the SDP rather than from this
+    // object, so a serializable placeholder is enough to satisfy the dialer.
+    return Promise.resolve({ expires: Date.now() + CERTIFICATE_TTL_MS });
+  };
+}

package/src/websocket-buffered-amount-polyfill.ts

@@ -0,0 +1,45 @@
+/**
+ * Make React Native's `WebSocket` report a numeric `bufferedAmount`.
+ *
+ * React Native declares `bufferedAmount` on its `WebSocket` but never assigns
+ * it, so it reads as `undefined`. `@libp2p/websockets` drives write backpressure
+ * off that value, and the `undefined` comparisons leave every write parked
+ * waiting for a `drain` that never fires, hanging the connection.
+ *
+ * React Native hands every frame straight to the native socket with no
+ * JS-visible send buffer to measure, so `0` ("fully flushed") is the correct,
+ * backpressure-free answer. A prototype accessor returns `0` for reads and
+ * swallows React Native's `undefined` field initialization with a no-op setter,
+ * so no shadowing own property is left on the instance.
+ */
+
+interface PrototypeHost {
+  readonly prototype?: object;
+}
+
+/**
+ * Install the `bufferedAmount` accessor on the global `WebSocket` prototype.
+ * Idempotent, and a no-op when the runtime already exposes a real getter (e.g.
+ * a browser or Node polyfill) or provides no `WebSocket` at all (e.g. tests).
+ */
+export function installWebSocketBufferedAmountPolyfill(): void {
+  const scope = globalThis as { WebSocket?: PrototypeHost };
+  const prototype = scope.WebSocket?.prototype;
+  if (prototype == null) {
+    return;
+  }
+  const existing = Object.getOwnPropertyDescriptor(prototype, "bufferedAmount");
+  if (existing?.get != null) {
+    return;
+  }
+  Object.defineProperty(prototype, "bufferedAmount", {
+    configurable: true,
+    get(): number {
+      return 0;
+    },
+    set(): void {
+      // Swallow React Native's `undefined` field initialization so it cannot
+      // create an own property that shadows this accessor.
+    },
+  });
+}