@minip2p/web 0.0.0 → 0.10.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deepso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @minip2p/web
+
+The browser package for [minip2p](https://minip2p.com): minip2p compiled to WebAssembly, dialing native nodes over libp2p WebTransport, with the same `@minip2p/core` API as `@minip2p/node`. It is ESM-only.
+
+```ts
+import { Minip2p, generateSecretKey } from "@minip2p/web";
+
+const endpoint = Minip2p.create({
+  protocols: ["/minip2p/echo/1"],
+  secretKey: generateSecretKey(),
+});
+
+// A native node's WebTransport address, certhashes and peer ID included.
+const path = await endpoint.connect(
+  "/ip4/192.0.2.1/udp/4001/quic-v1/webtransport/certhash/uEi…/certhash/uEi…/p2p/12D3KooW…"
+);
+console.log(await endpoint.ping(path.peerId));
+```
+
+A native node serves browsers by listening on a `/…/quic-v1/webtransport` address beside (or instead of) its `/quic-v1` one; its `listenAddrs()` then include the full address to hand to the browser. The [browser example](https://github.com/deepso7/minip2p/tree/main/examples/web) runs this against `minip2p-peer`.
+
+## Loading the wasm
+
+- **`@minip2p/web`** loads its `.wasm` (resolved from `import.meta.url`, so bundlers emit it as an asset) with top-level `await`. Once the import resolves, `Minip2p.create` is synchronous, as in Node. Bundlers need an `es2022` target for the top-level `await`; Vite also needs `optimizeDeps.exclude: ["@minip2p/web"]` so pre-bundling keeps the package next to its `.wasm`.
+- **`@minip2p/web/manual`** exports the same API plus `initMinip2p({ wasm })` and fetches nothing at import: serve the `.wasm` yourself (a CDN, a strict CSP) and pass a URL, a `Response`, its bytes or a compiled `WebAssembly.Module`. `Minip2p.create` throws until `initMinip2p` has resolved.
+
+## What works in a browser
+
+Dialing native nodes at `/webtransport/certhash` addresses, Identify, ping, custom protocol streams with backpressure, gossipsub, and relay reservations with circuits to and from other browsers and native nodes. The page must be a secure context (HTTPS or `localhost`). Chrome and Firefox are supported; Safari 26.4+ is best-effort.
+
+`Minip2p.create` throws `InvalidConfigError`, with the reason, for what a browser cannot do:
+
+| Option           | Why                                           |
+| ---------------- | --------------------------------------------- |
+| `listen`         | Browsers cannot listen.                       |
+| `mdns`           | Browsers have no multicast sockets.           |
+| `discovery`      | Signed discovery is not in the browser build. |
+| `autonatServers` | Browsers cannot be dialed back.               |
+
+Other limits:
+
+- Only WebTransport addresses with certhashes dial; a `/quic-v1` or `/tcp` candidate fails as a candidate. There is no CA-certificate mode.
+- `listenAddrs()` is always empty (a reservation is `circuitAddress`), `knownPeers()` is empty and `reachability()` stays `unknown`.
+- `close()` closes every session at once with WebTransport's close capsule; its timeout is ignored. `setActive()` is ignored as well: the page's own timers drive the endpoint.
+- A page on a public origin that dials a private address may trigger Chrome's Local Network Access prompt.
+- A trapped wasm module (a Rust panic) fails the endpoint with `DriverFailedError`; its WebTransport sessions are closed from TypeScript, `close()` still resolves (`Failed`), and later calls throw `ClosedError`. Create a new endpoint to carry on.
+
+## Relays
+
+With `relays` (WebTransport addresses with certhashes) the browser holds a reservation on the relay and is reachable at its `/p2p-circuit` address (`node.circuitAddress`), from other browsers and from native nodes. Connecting by peer ID goes through the relay; connecting to a native peer's WebTransport address races the direct dial against the relay leg, so the path is `direct` or `relayed`, never `punched`: browsers never hole punch. `forceRelay: true` skips the direct dial. `activeReservation()` reports the reservation.
+
+## Development
+
+```bash
+rustup target add wasm32-unknown-unknown
+cargo install wasm-bindgen-cli --version 0.2.128
+pnpm wasm:build    # crates/web → wasm/
+pnpm test          # unit tests (runs wasm:build first)
+pnpm test:e2e      # Playwright: Chromium and Firefox against native nodes
+```
+
+`wasm:build` regenerates `wasm/minip2p_web.js` and its `.d.ts`, the checked-in wasm-bindgen glue; commit them, CI fails when they are stale. The `.wasm` is a build output. The e2e suite needs `pnpm build:bindings`, the Node addon (`pnpm --filter @minip2p/node native:build`), the relay-server example (`cargo build -p minip2p-relay-server-example`) and `npx playwright install chromium firefox`.
+
+`src/io.ts` is `JsIo`, the `WebTransportIo` seam the Rust client drives over the browser's `WebTransport`; [`crates/web`](https://github.com/deepso7/minip2p/tree/main/crates/web) is the Rust side.
+
+The release workflow publishes the package with npm trusted publishing. Before the first release that includes it, an owner of the `@minip2p` scope runs `scripts/npm-trusted-publisher-web.sh` once to register the publisher.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@minip2p/web`: minip2p for the browser, with the same API as
+ * `@minip2p/node`. Importing it loads the wasm module (the `.wasm` beside
+ * the package, resolved from `import.meta.url`) with top-level `await`, so
+ * `Minip2p.create` is ready to call. Use `@minip2p/web/manual` to load the
+ * `.wasm` yourself.
+ */
+export * from "@minip2p/core";
+export { Minip2p, circuitAddress, generateSecretKey, peerIdFromSecretKey, } from "./sdk.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,cAAc,eAAe,CAAC;AAC9B,OAAO,EACL,OAAO,EACP,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@minip2p/web`: minip2p for the browser, with the same API as
+ * `@minip2p/node`. Importing it loads the wasm module (the `.wasm` beside
+ * the package, resolved from `import.meta.url`) with top-level `await`, so
+ * `Minip2p.create` is ready to call. Use `@minip2p/web/manual` to load the
+ * `.wasm` yourself.
+ */
+import { initMinip2p } from "./sdk.js";
+await initMinip2p();
+export * from "@minip2p/core";
+export { Minip2p, circuitAddress, generateSecretKey, peerIdFromSecretKey, } from "./sdk.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,WAAW,EAAE,CAAC;AAEpB,cAAc,eAAe,CAAC;AAC9B,OAAO,EACL,OAAO,EACP,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,UAAU,CAAC"}

package/dist/io.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `JsIo`: the `WebTransportIo` seam of `minip2p-webtransport` over the
+ * browser's `WebTransport` API. Rust owns the protocol and calls these
+ * methods synchronously; every outcome the browser learns later (a session
+ * coming up, a read, a write resolving, a reset) is queued as an
+ * {@link IoEvent} and handed back by {@link JsIo.pollEvent}, and `wake`
+ * asks the host to pump.
+ *
+ * The rules Rust relies on:
+ *
+ * - `write` copies what it accepts before returning, so a queued browser
+ *   write never views wasm memory, and caps each stream's in-flight bytes;
+ *   each accepted write reports exactly one `writeCompleted` with its own
+ *   length, and a write the browser rejects reports nothing.
+ * - Reads are pulled: `grantRead` is additive, at most one read is
+ *   outstanding per stream, and `data` never exceeds what was granted.
+ * - Handles are never reused, and events for a reset stream or an ended
+ *   session are dropped. A stream whose read side ended and whose write
+ *   side finished (every accepted write reported first) or was stopped is
+ *   retired, so finished streams hold nothing.
+ * - Stream error codes are WebTransport application codes cut to `u8`
+ *   (minip2p only sends 0); a missing code is 0.
+ * - Only `connect`, `openStream` and `write` may throw (Rust catches those
+ *   as `IoError`s). An exception escaping any other method would unwind
+ *   through Rust and leave the `WebEndpoint` borrowed for good, so they
+ *   swallow everything.
+ */
+/** In-flight write bytes each stream may hold in the browser. */
+export declare const MAX_IN_FLIGHT_BYTES: number;
+/** One outcome for Rust, the shape `crates/web/src/io.rs` decodes. */
+export type IoEvent = {
+    readonly kind: "sessionReady";
+    readonly session: number;
+} | {
+    readonly kind: "sessionClosed";
+    readonly session: number;
+    readonly code: number;
+    readonly reason: string;
+} | {
+    readonly kind: "sessionFailed";
+    readonly session: number;
+    readonly reason: string;
+} | {
+    readonly kind: "streamOpened";
+    readonly stream: number;
+} | {
+    readonly kind: "incomingStream";
+    readonly session: number;
+    readonly stream: number;
+} | {
+    readonly kind: "data";
+    readonly stream: number;
+    readonly bytes: Uint8Array;
+} | {
+    readonly kind: "fin";
+    readonly stream: number;
+} | {
+    readonly kind: "reset";
+    readonly stream: number;
+    readonly code: number;
+} | {
+    readonly kind: "stopSending";
+    readonly stream: number;
+    readonly code: number;
+} | {
+    readonly kind: "writeCompleted";
+    readonly stream: number;
+    readonly bytes: number;
+};
+/** The part of a browser `WebTransport` that `JsIo` uses. */
+export type WebTransportSession = Pick<WebTransport, "close" | "closed" | "createBidirectionalStream" | "incomingBidirectionalStreams" | "ready">;
+/** Opens one session; the browser's `new WebTransport(url, options)`. */
+export type OpenSession = (url: string, options: WebTransportOptions) => WebTransportSession;
+/** The browser `WebTransportIo` behind one `WebEndpoint`. */
+export declare class JsIo {
+    #private;
+    /**
+     * `wake` runs whenever an event is queued; `openSession` defaults to the
+     * global `WebTransport`.
+     */
+    constructor(wake: () => void, openSession?: OpenSession | undefined);
+    /** Starts a session trusting exactly the certificates `certhashes` name. */
+    connect(url: string, certhashes: Uint8Array<ArrayBuffer>[]): number;
+    /** Opens a bidirectional stream; `streamOpened` follows. */
+    openStream(sessionId: number): number;
+    /** Copies and queues a prefix of `data`; a short write is backpressure. */
+    write(streamId: number, data: Uint8Array): number;
+    /** Finishes the write side after every accepted write. */
+    closeWrite(streamId: number): void;
+    /** Resets the stream both ways (`abort()` and `cancel()`). */
+    reset(streamId: number, code: number): void;
+    /** Asks the peer to stop sending (`cancel()` only). */
+    stop(streamId: number, code: number): void;
+    /** Lets the stream deliver up to `bytes` more. */
+    grantRead(streamId: number, bytes: number): void;
+    /** Closes the session with a close capsule, as `WebTransport.close()` does. */
+    close(sessionId: number, code: number, reason: string): void;
+    /** The next queued event, if any. */
+    pollEvent(): IoEvent | undefined;
+    /**
+     * Closes every session and forgets everything, for an owner that can no
+     * longer drive Rust (a trapped wasm module): no later event or wake, and
+     * `connect` throws. Idempotent; called from TypeScript, not Rust.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=io.d.ts.map

package/dist/io.d.ts.map

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