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

package/README.md

@@ -0,0 +1,155 @@
+# @peerkit/transport-libp2p-react-native
+
+React Native implementation of the peerkit transport layer. Wires
+`@peerkit/transport-libp2p-core` to a libp2p stack configured for mobile:
+WebSockets (outbound), WebRTC, and circuit-relay-v2 client.
+
+## Install
+
+```sh
+npm install @peerkit/transport-libp2p-react-native
+npm install react-native-get-random-values react-native-quick-crypto react-native-webrtc
+```
+
+The three `react-native-*` peer dependencies provide native modules and must
+be linked via the standard React Native autolinking flow (iOS: `pod install`,
+Android: Gradle sync).
+
+## Polyfills
+
+libp2p depends on Node built-ins (`crypto`, `stream`, `buffer`, `events`,
+`process`) and on the Web Crypto / WebRTC globals. Hermes provides none of
+those out of the box (Hermes is Meta's JavaScript engine for React
+Native). The package ships a single side-effect entry that
+installs everything in the right order.
+
+Add **as the very first import** of the app entry (typically `index.js` or
+`App.tsx`):
+
+```js
+import "@peerkit/transport-libp2p-react-native/polyfills";
+```
+
+The polyfill module:
+
+1. Patches `globalThis.crypto.getRandomValues` via
+   `react-native-get-random-values`. Must run first — peer-id generation and
+   noise key generation reach for RNG during module init.
+2. Installs `react-native-quick-crypto`, providing a JSI-backed
+   `globalThis.crypto.subtle`.
+3. Registers `react-native-webrtc` globals (`RTCPeerConnection`,
+   `RTCSessionDescription`, etc.) consumed by `@libp2p/webrtc`.
+4. Assigns `globalThis.Buffer` and `globalThis.process` from the `buffer` and
+   `process` shims so libp2p code that touches these as globals (rather than
+   ES module imports) works.
+5. Installs the WHATWG `Event` / `EventTarget` / `CustomEvent` globals that
+   Hermes lacks but `@libp2p/interface` extends at module init.
+6. Installs UTF-8 `TextEncoder` / `TextDecoder` globals that Hermes lacks but
+   `uint8arrays` constructs at module init.
+
+## Metro config
+
+Metro (React Native's JavaScript bundler) must rewrite Node-style bare
+imports to their React Native shims. Add
+the following to `metro.config.js`:
+
+```js
+const { getDefaultConfig } = require("@react-native/metro-config");
+
+const config = getDefaultConfig(__dirname);
+
+config.resolver.extraNodeModules = {
+  ...config.resolver.extraNodeModules,
+  crypto: require.resolve("react-native-quick-crypto"),
+  stream: require.resolve("readable-stream"),
+  buffer: require.resolve("buffer"),
+  events: require.resolve("events"),
+  process: require.resolve("process"),
+};
+
+// libp2p 3.x publishes a `browser` conditional export that is broken under
+// Metro's package-exports resolver — see <https://github.com/libp2p/js-libp2p/issues/2969>.
+// Enabling the resolver is required for several libp2p subpackages to
+// resolve at all; per-package overrides may be needed if a specific module
+// fails to bundle.
+config.resolver.unstable_enablePackageExports = true;
+
+module.exports = config;
+```
+
+## Babel config
+
+Compile public class fields with spec `[[Define]]` semantics by setting the
+`setPublicClassFields: false` assumption:
+
+```js
+module.exports = {
+  presets: ["babel-preset-expo"], // or "module:@react-native/babel-preset"
+  assumptions: {
+    setPublicClassFields: false,
+  },
+};
+```
+
+This is **required**, not optional. `babel-preset-expo` defaults to loose
+(`[[Set]]`) class fields, which compile an uninitialized field declaration to
+`this.field = void 0`. React Native's webapis define read-only prototype
+constants — notably `Event.prototype.NONE` (and `CAPTURING_PHASE` /
+`AT_TARGET` / `BUBBLING_PHASE`) via `Object.defineProperty` without
+`writable: true`. The matching `this.NONE = void 0` walks the prototype chain
+and throws `Cannot assign to read-only property 'NONE'` the moment libp2p or
+WebRTC construct an `Event`. The `[[Define]]` assumption drops the bare
+declaration, so the read-only constant is never assigned.
+
+Do **not** add `["@babel/plugin-transform-private-methods", { loose: true }]`:
+its loose option sets the opposite assumption (`setPublicClassFields: true`)
+and reintroduces the crash. libp2p's private fields (`#field`) are transformed
+by the preset without it.
+
+## Usage
+
+```ts
+import "@peerkit/transport-libp2p-react-native/polyfills";
+import { createNode } from "@peerkit/transport-libp2p-react-native";
+
+const transport = await createNode({
+  networkAccessBytes: new Uint8Array([
+    /* network access bytes */
+  ]),
+  bootstrapRelays: ["/dns4/relay.example.com/tcp/443/wss/p2p/12D3Koo..."],
+  // Optional: defaults to ["/p2p-circuit", "/webrtc"].
+  addrs: ["/p2p-circuit", "/webrtc"],
+});
+```
+
+`createNode` returns a `TransportLibp2p` instance from
+`@peerkit/transport-libp2p-core`. Refer to that package's documentation for
+the public API (`onAccessConnect`, `onAgentsConnect`, `onMessageConnect`,
+`sendAgents`, `sendMessage`, etc.).
+
+## Noise crypto
+
+`createNode` wires Noise with a JSI-backed `ICryptoInterface` over
+`react-native-quick-crypto`. SHA-256, HKDF and ChaCha20-Poly1305 run as
+native code; X25519 stays on the pure-JS Noise default because
+`ICryptoInterface` is synchronous and quick-crypto's X25519 surface is not.
+
+The adapter is also exported standalone for consumers who want to wire it
+into their own libp2p stack:
+
+```ts
+import { quickCryptoNoise } from "@peerkit/transport-libp2p-react-native/quick-crypto-noise";
+```
+
+## Runtime scope
+
+Importing the package's main entry pulls `react-native-quick-crypto` at
+module load time. The package is therefore intended exclusively for React
+Native bundles — do not import it from Node test code. Type-only imports
+(`import type { ... }`) remain safe in any TypeScript context.
+
+## Known limitations
+
+- No background operation. iOS suspends the JS runtime when the app is
+  backgrounded; Android Doze mode throttles. Foreground-only without
+  additional OS-specific work.

package/dist/datachannel-early-message-polyfill.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Buffers the earliest message(s) arriving on a freshly opened inbound
+ * (in-band) datachannel and replays them once the JS `RTCDataChannel` object
+ * and its listener exist.
+ *
+ * On `react-native-webrtc`, the channel-open announcement and inbound message
+ * events can reach JS out of order during connection setup: a message for a
+ * newly opened inbound channel may arrive before the corresponding
+ * `RTCDataChannel` object is created, leaving no listener to receive it. This
+ * polyfill captures such early messages by `reactTag` and delivers them when
+ * the listener is attached.
+ *
+ * Pre-negotiated channels (`createDataChannel` with `negotiated: true, id: 0`
+ * on both ends) are unaffected: their JS object and listener exist before any
+ * data arrives.
+ */
+/**
+ * Install the early-message recovery. Idempotent, and a no-op when the WebRTC
+ * native module or the global `RTCPeerConnection` is absent (`registerGlobals()`
+ * has not run, or under tests).
+ */
+export declare function installDataChannelEarlyMessagePolyfill(): void;
+//# sourceMappingURL=datachannel-early-message-polyfill.d.ts.map

package/dist/datachannel-early-message-polyfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datachannel-early-message-polyfill.d.ts","sourceRoot":"","sources":["../src/datachannel-early-message-polyfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAuEH;;;;GAIG;AACH,wBAAgB,sCAAsC,IAAI,IAAI,CAoF7D"}

package/dist/datachannel-early-message-polyfill.js

@@ -0,0 +1,131 @@
+/**
+ * Buffers the earliest message(s) arriving on a freshly opened inbound
+ * (in-band) datachannel and replays them once the JS `RTCDataChannel` object
+ * and its listener exist.
+ *
+ * On `react-native-webrtc`, the channel-open announcement and inbound message
+ * events can reach JS out of order during connection setup: a message for a
+ * newly opened inbound channel may arrive before the corresponding
+ * `RTCDataChannel` object is created, leaving no listener to receive it. This
+ * polyfill captures such early messages by `reactTag` and delivers them when
+ * the listener is attached.
+ *
+ * Pre-negotiated channels (`createDataChannel` with `negotiated: true, id: 0`
+ * on both ends) are unaffected: their JS object and listener exist before any
+ * data arrives.
+ */
+import { Buffer } from "buffer";
+import { NativeEventEmitter, NativeModules } from "react-native";
+const PROBE_CHANNEL_LABEL = "peerkit-early-message-probe";
+const INSTALLED_FLAG = "__peerkitDataChannelEarlyMessagePatched";
+/**
+ * Decode a base64 datachannel payload to an exactly sized `ArrayBuffer`,
+ * matching how `react-native-webrtc` surfaces binary messages
+ * (`event.data.byteLength` must equal the message length).
+ */
+function base64ToArrayBuffer(base64) {
+    const view = Buffer.from(base64, "base64");
+    return view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength);
+}
+/**
+ * Capture the shared `RTCDataChannel` prototype. The class is not exported, so a
+ * throwaway peer connection mints a probe channel and its prototype is read off
+ * the instance. Returns `null` if a peer connection cannot be created.
+ */
+function captureDataChannelPrototype(RTCPeerConnectionCtor) {
+    let probeConnection;
+    try {
+        probeConnection = new RTCPeerConnectionCtor();
+        const channel = probeConnection.createDataChannel(PROBE_CHANNEL_LABEL);
+        return Object.getPrototypeOf(channel);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        probeConnection?.close();
+    }
+}
+/**
+ * Install the early-message recovery. Idempotent, and a no-op when the WebRTC
+ * native module or the global `RTCPeerConnection` is absent (`registerGlobals()`
+ * has not run, or under tests).
+ */
+export function installDataChannelEarlyMessagePolyfill() {
+    const webRtcModule = NativeModules.WebRTCModule;
+    const scope = globalThis;
+    const RTCPeerConnectionCtor = scope.RTCPeerConnection;
+    if (webRtcModule == null || RTCPeerConnectionCtor == null) {
+        return;
+    }
+    const prototype = captureDataChannelPrototype(RTCPeerConnectionCtor);
+    if (prototype == null || prototype[INSTALLED_FLAG] === true) {
+        return;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, "onmessage");
+    if (descriptor?.get == null || descriptor.set == null) {
+        return;
+    }
+    // Early messages buffered per datachannel reactTag, awaiting a consumer.
+    const buffered = new Map();
+    // reactTags whose consumer has attached. Their live messages are delivered by
+    // react-native-webrtc's own path, so the duplicate seen here is ignored.
+    const consumed = new Set();
+    const emitter = new NativeEventEmitter(webRtcModule);
+    emitter.addListener("dataChannelReceiveMessage", (raw) => {
+        const event = raw;
+        // libp2p only sends binary frames; ignore everything else.
+        if (event.type !== "binary" || consumed.has(event.reactTag)) {
+            return;
+        }
+        const payload = base64ToArrayBuffer(event.data);
+        const existing = buffered.get(event.reactTag);
+        if (existing) {
+            existing.push(payload);
+        }
+        else {
+            buffered.set(event.reactTag, [payload]);
+        }
+    });
+    emitter.addListener("dataChannelStateChanged", (raw) => {
+        const event = raw;
+        if (event.state === "closed") {
+            buffered.delete(event.reactTag);
+            consumed.delete(event.reactTag);
+        }
+    });
+    const originalGet = descriptor.get;
+    const originalSet = descriptor.set;
+    Object.defineProperty(prototype, "onmessage", {
+        configurable: true,
+        enumerable: descriptor.enumerable ?? false,
+        get() {
+            return originalGet.call(this);
+        },
+        set(handler) {
+            originalSet.call(this, handler);
+            if (handler == null) {
+                return;
+            }
+            const reactTag = this._reactTag;
+            // From now on react-native-webrtc delivers live messages to this handler;
+            // mark the channel so the duplicate copies seen here are dropped.
+            consumed.add(reactTag);
+            const pending = buffered.get(reactTag);
+            if (pending == null) {
+                return;
+            }
+            buffered.delete(reactTag);
+            for (const data of pending) {
+                handler({ data });
+            }
+        },
+    });
+    Object.defineProperty(prototype, INSTALLED_FLAG, {
+        value: true,
+        enumerable: false,
+        writable: false,
+        configurable: true,
+    });
+}
+//# sourceMappingURL=datachannel-early-message-polyfill.js.map

package/dist/datachannel-early-message-polyfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datachannel-early-message-polyfill.js","sourceRoot":"","sources":["../src/datachannel-early-message-polyfill.ts"],"names":[],"mappings":"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"}

package/dist/event-target-polyfill.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A self-contained WHATWG `Event` / `EventTarget` / `CustomEvent` polyfill for
+ * the React Native Hermes engine.
+ *
+ * React Native's `setUpDOM` polyfills a handful of DOM globals (`DOMRect`,
+ * `Node`, `Element`, ...) but **not** the event classes, and Hermes ships none
+ * of them. libp2p depends on all three at module-evaluation time:
+ *
+ *  - `@libp2p/interface` declares `class StreamMessageEvent extends Event`.
+ *  - `main-event`'s `TypedEventEmitter extends EventTarget` and dispatches
+ *    `new CustomEvent(type, { detail })`.
+ *
+ * Without these globals the bundle red-screens with
+ * `Property 'Event' doesn't exist` before any application code runs.
+ *
+ * This is a hand-rolled implementation rather than a dependency on
+ * `event-target-shim` on purpose: the shim's type definitions expose `Event`
+ * only as an interface (not a constructor value), and its dispatcher wraps
+ * foreign event objects in a copy — which breaks the `instanceof` checks and
+ * subclass fields (e.g. `StreamMessageEvent.data`) that libp2p relies on.
+ * Owning both `Event` and `EventTarget` here guarantees the exact event
+ * instance is delivered to every listener.
+ */
+/**
+ * Install `Event`, `EventTarget`, and `CustomEvent` on the global scope,
+ * overwriting any implementation the runtime already provides.
+ *
+ * The overwrite is deliberate, not defensive. React Native's own global `Event`
+ * exposes read-only/non-configurable members (`type`, the phase constants) that
+ * libp2p's event subclasses redeclare as class fields, which throws at
+ * construction on Hermes. {@link PolyfillEvent} declares them as writable,
+ * configurable fields, so the three globals are replaced outright (not `??=`d)
+ * to guarantee a single, subclass-safe hierarchy for libp2p's `instanceof`
+ * checks and `EventTarget` dispatch.
+ *
+ * Runs once from the polyfills entry, before any libp2p module evaluates. Safe
+ * to call more than once.
+ */
+export declare function installEventTargetPolyfill(): void;
+//# sourceMappingURL=event-target-polyfill.d.ts.map

package/dist/event-target-polyfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-target-polyfill.d.ts","sourceRoot":"","sources":["../src/event-target-polyfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA6NH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CASjD"}

package/dist/event-target-polyfill.js

@@ -0,0 +1,192 @@
+/**
+ * A self-contained WHATWG `Event` / `EventTarget` / `CustomEvent` polyfill for
+ * the React Native Hermes engine.
+ *
+ * React Native's `setUpDOM` polyfills a handful of DOM globals (`DOMRect`,
+ * `Node`, `Element`, ...) but **not** the event classes, and Hermes ships none
+ * of them. libp2p depends on all three at module-evaluation time:
+ *
+ *  - `@libp2p/interface` declares `class StreamMessageEvent extends Event`.
+ *  - `main-event`'s `TypedEventEmitter extends EventTarget` and dispatches
+ *    `new CustomEvent(type, { detail })`.
+ *
+ * Without these globals the bundle red-screens with
+ * `Property 'Event' doesn't exist` before any application code runs.
+ *
+ * This is a hand-rolled implementation rather than a dependency on
+ * `event-target-shim` on purpose: the shim's type definitions expose `Event`
+ * only as an interface (not a constructor value), and its dispatcher wraps
+ * foreign event objects in a copy — which breaks the `instanceof` checks and
+ * subclass fields (e.g. `StreamMessageEvent.data`) that libp2p relies on.
+ * Owning both `Event` and `EventTarget` here guarantees the exact event
+ * instance is delivered to every listener.
+ */
+function normalizeAddOptions(options) {
+    if (typeof options === "boolean") {
+        return { capture: options };
+    }
+    return options ?? {};
+}
+/** WHATWG `Event`. */
+class PolyfillEvent {
+    static NONE = 0;
+    static CAPTURING_PHASE = 1;
+    static AT_TARGET = 2;
+    static BUBBLING_PHASE = 3;
+    type;
+    bubbles;
+    cancelable;
+    composed;
+    timeStamp = 0;
+    isTrusted = false;
+    eventPhase = PolyfillEvent.NONE;
+    targetInternal = null;
+    currentTargetInternal = null;
+    defaultPreventedInternal = false;
+    propagationStopped = false;
+    immediatePropagationStopped = false;
+    constructor(type, eventInitDict) {
+        this.type = type;
+        this.bubbles = eventInitDict?.bubbles ?? false;
+        this.cancelable = eventInitDict?.cancelable ?? false;
+        this.composed = eventInitDict?.composed ?? false;
+    }
+    get target() {
+        return this.targetInternal;
+    }
+    get srcElement() {
+        return this.targetInternal;
+    }
+    get currentTarget() {
+        return this.currentTargetInternal;
+    }
+    get defaultPrevented() {
+        return this.defaultPreventedInternal;
+    }
+    preventDefault() {
+        if (this.cancelable) {
+            this.defaultPreventedInternal = true;
+        }
+    }
+    stopPropagation() {
+        this.propagationStopped = true;
+    }
+    stopImmediatePropagation() {
+        this.propagationStopped = true;
+        this.immediatePropagationStopped = true;
+    }
+    composedPath() {
+        return this.currentTargetInternal == null
+            ? []
+            : [this.currentTargetInternal];
+    }
+    // The following methods are polyfill-internal: `PolyfillEventTarget` uses them
+    // to drive dispatch state across the class boundary (TypeScript `private`
+    // members are not reachable from another class).
+    /** @internal */
+    beginDispatch(target) {
+        this.targetInternal = target;
+        this.currentTargetInternal = target;
+    }
+    /** @internal */
+    endDispatch() {
+        this.currentTargetInternal = null;
+    }
+    /** @internal */
+    get immediatePropagationWasStopped() {
+        return this.immediatePropagationStopped;
+    }
+}
+/** WHATWG `CustomEvent`. */
+class PolyfillCustomEvent extends PolyfillEvent {
+    detail;
+    constructor(type, eventInitDict) {
+        super(type, eventInitDict);
+        this.detail = eventInitDict?.detail ?? null;
+    }
+}
+/** WHATWG `EventTarget`. */
+class PolyfillEventTarget {
+    listenerMap = new Map();
+    addEventListener(type, callback, options) {
+        if (callback == null) {
+            return;
+        }
+        const opts = normalizeAddOptions(options);
+        const signal = opts.signal;
+        if (signal?.aborted === true) {
+            return;
+        }
+        const list = this.listenerMap.get(type) ?? [];
+        // Per spec a (callback, capture) pair is registered at most once.
+        if (list.some((entry) => entry.callback === callback)) {
+            return;
+        }
+        list.push({ callback, once: opts.once ?? false });
+        this.listenerMap.set(type, list);
+        if (signal != null) {
+            signal.addEventListener("abort", () => {
+                this.removeEventListener(type, callback);
+            });
+        }
+    }
+    removeEventListener(type, callback, _options) {
+        if (callback == null) {
+            return;
+        }
+        const list = this.listenerMap.get(type);
+        if (list == null) {
+            return;
+        }
+        const index = list.findIndex((entry) => entry.callback === callback);
+        if (index >= 0) {
+            list.splice(index, 1);
+        }
+    }
+    dispatchEvent(event) {
+        event.beginDispatch(this);
+        // Snapshot the list: a listener may add or remove listeners mid-dispatch.
+        const list = this.listenerMap.get(event.type);
+        if (list != null) {
+            for (const entry of [...list]) {
+                if (entry.once) {
+                    this.removeEventListener(event.type, entry.callback);
+                }
+                const { callback } = entry;
+                if (typeof callback === "function") {
+                    callback(event);
+                }
+                else {
+                    callback.handleEvent(event);
+                }
+                if (event.immediatePropagationWasStopped) {
+                    break;
+                }
+            }
+        }
+        event.endDispatch();
+        return !event.defaultPrevented;
+    }
+}
+/**
+ * Install `Event`, `EventTarget`, and `CustomEvent` on the global scope,
+ * overwriting any implementation the runtime already provides.
+ *
+ * The overwrite is deliberate, not defensive. React Native's own global `Event`
+ * exposes read-only/non-configurable members (`type`, the phase constants) that
+ * libp2p's event subclasses redeclare as class fields, which throws at
+ * construction on Hermes. {@link PolyfillEvent} declares them as writable,
+ * configurable fields, so the three globals are replaced outright (not `??=`d)
+ * to guarantee a single, subclass-safe hierarchy for libp2p's `instanceof`
+ * checks and `EventTarget` dispatch.
+ *
+ * Runs once from the polyfills entry, before any libp2p module evaluates. Safe
+ * to call more than once.
+ */
+export function installEventTargetPolyfill() {
+    const eventScope = globalThis;
+    eventScope.Event = PolyfillEvent;
+    eventScope.EventTarget = PolyfillEventTarget;
+    eventScope.CustomEvent = PolyfillCustomEvent;
+}
+//# sourceMappingURL=event-target-polyfill.js.map

package/dist/event-target-polyfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-target-polyfill.js","sourceRoot":"","sources":["../src/event-target-polyfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA0CH,SAAS,mBAAmB,CAC1B,OAA2C;IAE3C,IAAI,OAAO,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC9B,CAAC;IACD,OAAO,OAAO,IAAI,EAAE,CAAC;AACvB,CAAC;AAED,sBAAsB;AACtB,MAAM,aAAa;IACjB,MAAM,CAAU,IAAI,GAAG,CAAC,CAAC;IACzB,MAAM,CAAU,eAAe,GAAG,CAAC,CAAC;IACpC,MAAM,CAAU,SAAS,GAAG,CAAC,CAAC;IAC9B,MAAM,CAAU,cAAc,GAAG,CAAC,CAAC;IAE1B,IAAI,CAAS;IACb,OAAO,CAAU;IACjB,UAAU,CAAU;IACpB,QAAQ,CAAU;IAClB,SAAS,GAAG,CAAC,CAAC;IACd,SAAS,GAAG,KAAK,CAAC;IAClB,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC;IAEjC,cAAc,GAA+B,IAAI,CAAC;IAClD,qBAAqB,GAA+B,IAAI,CAAC;IACzD,wBAAwB,GAAG,KAAK,CAAC;IACjC,kBAAkB,GAAG,KAAK,CAAC;IAC3B,2BAA2B,GAAG,KAAK,CAAC;IAE5C,YAAY,IAAY,EAAE,aAA6B;QACrD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,aAAa,EAAE,OAAO,IAAI,KAAK,CAAC;QAC/C,IAAI,CAAC,UAAU,GAAG,aAAa,EAAE,UAAU,IAAI,KAAK,CAAC;QACrD,IAAI,CAAC,QAAQ,GAAG,aAAa,EAAE,QAAQ,IAAI,KAAK,CAAC;IACnD,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,qBAAqB,CAAC;IACpC,CAAC;IAED,IAAI,gBAAgB;QAClB,OAAO,IAAI,CAAC,wBAAwB,CAAC;IACvC,CAAC;IAED,cAAc;QACZ,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,IAAI,CAAC,wBAAwB,GAAG,IAAI,CAAC;QACvC,CAAC;IACH,CAAC;IAED,eAAe;QACb,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;IACjC,CAAC;IAED,wBAAwB;QACtB,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAC/B,IAAI,CAAC,2BAA2B,GAAG,IAAI,CAAC;IAC1C,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,qBAAqB,IAAI,IAAI;YACvC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IACnC,CAAC;IAED,+EAA+E;IAC/E,0EAA0E;IAC1E,iDAAiD;IAEjD,gBAAgB;IAChB,aAAa,CAAC,MAA2B;QACvC,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC;QAC7B,IAAI,CAAC,qBAAqB,GAAG,MAAM,CAAC;IACtC,CAAC;IAED,gBAAgB;IAChB,WAAW;QACT,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC;IACpC,CAAC;IAED,gBAAgB;IAChB,IAAI,8BAA8B;QAChC,OAAO,IAAI,CAAC,2BAA2B,CAAC;IAC1C,CAAC;;AAGH,4BAA4B;AAC5B,MAAM,mBAAiC,SAAQ,aAAa;IACjD,MAAM,CAAW;IAE1B,YAAY,IAAY,EAAE,aAAsC;QAC9D,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,aAAa,EAAE,MAAM,IAAI,IAAI,CAAC;IAC9C,CAAC;CACF;AAED,4BAA4B;AAC5B,MAAM,mBAAmB;IACN,WAAW,GAAG,IAAI,GAAG,EAAgC,CAAC;IAEvE,gBAAgB,CACd,IAAY,EACZ,QAAsC,EACtC,OAA2C;QAE3C,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC9C,kEAAkE;QAClE,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,EAAE,CAAC;YACtD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACjC,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;YACnB,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;gBACpC,IAAI,CAAC,mBAAmB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAC3C,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,mBAAmB,CACjB,IAAY,EACZ,QAAsC,EACtC,QAAyC;QAEzC,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;QACrE,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,aAAa,CAAC,KAAoB;QAChC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAC1B,0EAA0E;QAC1E,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACjB,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;gBAC9B,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;oBACf,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;gBACvD,CAAC;gBACD,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;gBAC3B,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;oBACnC,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAClB,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;gBAC9B,CAAC;gBACD,IAAI,KAAK,CAAC,8BAA8B,EAAE,CAAC;oBACzC,MAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;QACD,KAAK,CAAC,WAAW,EAAE,CAAC;QACpB,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC;IACjC,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,0BAA0B;IACxC,MAAM,UAAU,GAAG,UAIlB,CAAC;IACF,UAAU,CAAC,KAAK,GAAG,aAAa,CAAC;IACjC,UAAU,CAAC,WAAW,GAAG,mBAAmB,CAAC;IAC7C,UAAU,CAAC,WAAW,GAAG,mBAAmB,CAAC;AAC/C,CAAC"}

package/dist/factories.d.ts

@@ -0,0 +1,68 @@
+import type { ConnectionGater } from "@libp2p/interface";
+import type { NodeAddress, RelayDialAddress } from "@peerkit/api";
+import { TransportLibp2p, type NodeOptions } from "@peerkit/transport-libp2p-core";
+/**
+ * Default libp2p listen addresses for a React Native peerkit node.
+ *
+ * Mobile peers cannot accept inbound direct TCP/UDP (CGNAT, no listen socket
+ * survives backgrounding on iOS / Android), so reachability is always
+ * relay-mediated: `/p2p-circuit` advertises a reservation on a connected
+ * relay, `/webrtc` advertises that the peer can be upgraded to a direct
+ * WebRTC connection through the relay-coordinated SDP exchange.
+ */
+export declare const defaultNodeListenAddrs: NodeAddress[];
+/**
+ * React Native-specific options accepted by {@link createNode}, on top of the
+ * platform-agnostic {@link NodeOptions}.
+ */
+export interface CreateNodeOptions extends NodeOptions {
+    /**
+     * Listening addresses.
+     *
+     * Defaults to {@link defaultNodeListenAddrs}.
+     */
+    addrs?: string[];
+    /**
+     * Relay multiaddrs to dial at startup. Required on mobile — without an
+     * active relay reservation the peer is unreachable. The transport invokes
+     * {@link NodeOptions.connectedToRelayCallback} once the dialable circuit
+     * address has been received.
+     */
+    bootstrapRelays?: RelayDialAddress[];
+    /**
+     * List of ICE server URLs needed for establishing direct connections.
+     */
+    iceServerUrls?: string[];
+    /**
+     * Overrides libp2p's connection gater.
+     *
+     * On React Native libp2p applies its browser gater, which refuses to dial
+     * private/LAN addresses. A production deployment behind a public relay never
+     * hits this, but development and demo setups that target a LAN relay or LAN
+     * peers must supply a gater that permits those dials
+     * (e.g. `{ denyDialMultiaddr: async () => false }`).
+     *
+     * Left undefined, libp2p keeps its secure-by-default browser gater.
+     */
+    connectionGater?: ConnectionGater;
+}
+/**
+ * Build a React Native peerkit transport. Configures libp2p with WebRTC +
+ * WebRTC Direct + circuit-relay-v2 client + noise + yamux + identify.
+ *
+ * Noise is wired with `quickCryptoNoise`, the JSI-backed `ICryptoInterface`
+ * from `./quick-crypto-noise`, so SHA-256, HKDF, and ChaCha20-Poly1305 are
+ * offloaded to `react-native-quick-crypto`. X25519 stays on pure JS because
+ * `ICryptoInterface` is synchronous and quick-crypto's X25519 surface is not.
+ *
+ * Crypto primitives, RNG and the WebRTC globals come from runtime polyfills
+ * — the consumer must import `@peerkit/transport-libp2p-react-native/polyfills`
+ * once from the app entry before this factory runs.
+ *
+ * Handles all three peerkit protocols (access, agents, messages). DCUtR is
+ * deliberately not registered: mobile cannot listen on TCP/QUIC, so there is
+ * no relayed connection that can be upgraded by hole-punching; WebRTC ICE
+ * provides the only viable direct-connection path on mobile.
+ */
+export declare function createNode(options: CreateNodeOptions): Promise<TransportLibp2p>;
+//# sourceMappingURL=factories.d.ts.map

package/dist/factories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factories.d.ts","sourceRoot":"","sources":["../src/factories.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EACjB,MAAM,gCAAgC,CAAC;AAIxC;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,EAG/C,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACrC;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,4BAiC1D"}