@statewalker/httpeers-member 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Kotelnikov
+
+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,203 @@
+# @statewalker/httpeers-member
+
+Everything a participant does: hold an identity, redeem or resume, connect,
+keep the link, advertise, discover, call, and serve.
+
+```ts
+import { startMember } from "@statewalker/httpeers-member";
+import { nodePlatform } from "@statewalker/httpeers-member/node";
+
+const member = await startMember({
+  key: "peers",
+  mounts,                 // what this peer serves
+  rules,                  // the mesh's policy
+  config: { relayAddrs, hubPeerId },
+  platform: nodePlatform,
+  invitationId,           // omit to resume an existing membership
+});
+
+await member.fetch(new Request(`http://local/peers/${otherPeer}/hello`));
+```
+
+## One lifecycle, and a platform object with three methods
+
+The prototype had **two** lifecycles — a 644-line `startBrowserPeer` and a Node
+equivalent — that agreed on every step and diverged on three. `startMember` is
+both of them, with the three differences injected:
+
+```ts
+interface MemberPlatform {
+  createNode(init): Promise<Libp2p>;                  // required
+  mountEdge?(init): Promise<MemberEdge>;              // a page only
+  watchWake?(onWake): () => void;                     // a page only
+}
+```
+
+That is the extraction's central claim, so `browser/peer-runtime.ts` was
+deliberately **not ported**: porting it would have walked the duplication back
+in through the front door. There is no browser peer runtime in this package,
+only `browserPlatform()`.
+
+| Import | Holds |
+|---|---|
+| `.` | `startMember`, the session, the join blob, the gateway, the edge dispatch, identity, mesh memory |
+| `./node` | `nodePlatform` — a value, because a Node member has nothing per-instance to build |
+| `./browser` | `browserPlatform()`, `createSession()`, `mountEdge`, `watchPageWake`, the IndexedDB backends |
+
+## `MemberHandle.fetch` IS the edge, on both platforms
+
+A Node caller writes `member.fetch(...)`; a page writes
+`fetch(`${baseUrl}${peer}/x`)` and the ServiceWorker hands it to the same
+handler. `baseUrl` is the browser-only extra, which is why it is optional.
+
+**The edge is a local ingress and strips the proven-peer header.** A page
+builds the requests that enter its own edge, so a header there is a claim, not
+a fact. `createEdgeDispatch` used to branch on "does this already have a
+binding" to mean "it arrived from the network" — safe while that binding was a
+WeakMap no page could write, and a forgery hole the moment it became a header.
+The branch is gone: a network request never reaches the edge, because
+`serveTransport` dispatches to `peer.dispatch` directly.
+
+**A member must be told it may route its own traffic.** The edge hands
+`/{peerId}/{path}` to the peer's router, and that router refuses to forward
+unless asked — relaying is its own capability, deny by default. `startMember`
+passes `forwardLocalOnly` (from `httpeers-core`), which allows what originated
+at this edge and refuses anything that arrived from the network. Omitting it
+does not fail to compile; it fails at runtime with `403 this peer does not
+relay for you`, from the **caller's own** router. That was a real defect here,
+found by standing up a live mesh.
+
+## `mountEdge` never waits for a controller that cannot come
+
+The edge is `webrun-http-browser`'s `SwHttpAdapter` (`^0.5.0`). A **hard
+reload** (Ctrl+Shift+R; Firefox's `location.reload(true)`) loads the page
+bypassing its ServiceWorker, while that worker is already active and claimed its
+clients long ago — so no `controllerchange` ever comes. Up to 0.4 `start()`
+then waited forever, and llm-chat's `mesh.html` shipped sitting at "Joining…
+(mounting-edge)" for good after one.
+
+Since 0.5 the library recovers it, and `mountEdge` relies on that:
+
+- uncontrolled under an active worker → `start()` sends a `CLAIM` request, the
+  stock `sw-worker` (every app's `/sw.js`) answers with `clients.claim()`, and
+  the page is taken over **in place, without a reload**;
+- a worker that does not answer `CLAIM` (an older `/sw.js` still installed in a
+  returning visitor's browser, or a custom `serviceWorkerUrl`) → after the
+  bound, **one reload** (`reloadIfUncontrolled`, kept as the last resort; the
+  library guards it with a `sessionStorage` marker, so it cannot loop);
+- still uncontrolled after that, or no usable `sessionStorage` → throw
+  `UncontrolledPageError` ("close the tab and reopen it").
+
+Every wait is bounded (`controlTimeoutMs`, default `DEFAULT_CONTROL_TIMEOUT_MS`
+= 30 s, passed to the adapter as its `timeout`); a worker that never activates
+or never answers fails with an `Error` that says what to do. `edge-control.ts`
+maps the library's `ServiceWorkerControlError` onto those errors, matching on
+`name`/`reason` rather than `instanceof`. `tests/edge-control.test.ts` pins the
+mapping; `httpeers-browser-conformance`'s `pnpm run test:reload` runs first
+visit, reload, a hard reload (asserting it recovers with no extra navigation) and
+a second tab, then — against a worker that ignores `CLAIM` — the fallback reload
+and a spent guard, in real Chromium and Firefox.
+
+## Direct or relay: how a member reaches its hub
+
+`MemberHandle.hubLink()` is `"direct"` or `"relay"`, decided once per join.
+**Direct** is a WebRTC upgrade to the hub plus a reservation on it, which is
+what lets other members reach this one. **Relay** is a kept, limited circuit
+through the public relay: the member calls the hub over it and nothing else
+can reach the member. A member lands in relay mode when
+
+- the WebRTC upgrade fails (a hub in Docker on a bridge network), or
+- the upgrade works but the hub **refuses the reservation for want of capacity**
+  (`RESERVATION_REFUSED`, `RESOURCE_LIMIT_EXCEEDED`) or does not answer. The
+  WebRTC link is then closed and the member continues exactly as in the first
+  case. `MemberHandle.hubLinkNote` says why, and the session shows it as the
+  live phase's note (the join widget: `Connected (relay)` plus the reason).
+
+Before this, a full reservation store on the hub failed the whole join while a
+relay-mode member worked. Any other refusal — `PERMISSION_DENIED` from a hub
+that has just accepted this peer, a hub with no relay service — still fails the
+join: those are faults to report, not conditions to route around
+(`fallsBackToRelay` in `start-member.ts`). Relay mode does not retry the
+upgrade; a reconnect decides again.
+
+## `createGateway` — the mesh as ordinary HTTP
+
+```ts
+const gateway = createGateway({ source: member, basePath: "", edgeKey: "peers" });
+```
+
+A `FetchHandler` dispatching `/{peerId}/{path}`, so a client with no peer
+object, no token and no knowledge of libp2p can `fetch()` a mesh resource.
+`GatewaySource` is structurally a subset of `MemberHandle`, so **a member is
+one** — no adapter.
+
+## Joining: a blob, a bare id, and one rule that must not bend
+
+| What someone supplies | Which mesh |
+|---|---|
+| a join **blob** (`eyJ…`) | the one the blob names — a hub page's |
+| a **bare invitation id** | the one the deployment's `httpeers.json` names |
+| nothing (a resume) | the one this origin remembers, else the deployment's |
+
+Only a **resume** consults the remembered mesh. A bare id still means the
+deployment's, because that is the contract a Node-hub invitation travels under;
+reversing it would silently point those joins at whatever mesh the page last
+saw. `tests/session.test.ts` pins all three.
+
+`invitationFromQrText` lives here rather than in `@statewalker/httpeers-qr`,
+because it is entirely about the join format — a QR package that knew it could
+not be used for anything else. It is a **predicate, never a parser**: it cannot
+throw, because a live scanner that died on a malformed URL would die on the
+first poster.
+
+## The session, and why it is isomorphic
+
+`createPeerSession` holds the four operator controls — join, disconnect,
+reconnect, reset identity — and the state a page renders. It has **no DOM and
+no browser imports**, so all fifteen of its branches are tested under Node with
+no browser, no relay and no ServiceWorker.
+
+That is load-bearing rather than tidy: `browserPlatform` reaches
+`@libp2p/webrtc`, whose Node build loads a native module, so a browser default
+inside the session would have made importing it a browser-only act. The
+defaults live in `./browser`'s `createSession` instead.
+
+**Disconnect is not leaving.** `stop()` drops presence and keeps membership, so
+reconnecting needs no new invitation. `resetIdentity` is the destructive one,
+named separately and documented with what it costs.
+
+## The two "cannot resume" states are different, and say so
+
+A page with no saved identity has never joined; a page whose identity the hub
+does not recognise has had its membership revoked, or is talking to a hub that
+was reset. Both would otherwise render as "please paste an invitation", and an
+operator could not tell which had happened. When a resume fails *and* the
+deployment now names a different hub, the session says so — that is almost
+always a re-run of `pnpm bootstrap`, and saying it is the difference between a
+two-minute fix and an hour.
+
+## Isomorphism, measured by reachability
+
+`tests/boundary.test.ts` walks the import closure of `index.ts` and fails if it
+reaches `node:`, `@libp2p/tcp`, `@libp2p/webrtc`, `idb-keyval`, a ServiceWorker
+adapter or a DOM-only global. It does **not** exempt filenames: `edge.ts` and
+`page-wake.ts` are browser-only by construction and simply are not reachable
+from the root, which the test asserts explicitly. Verified non-vacuous by
+re-exporting `mountEdge` from `index.ts` and watching three named tests fail.
+
+## Tests
+
+**116.** `tests/edge-control.test.ts` pins the error `mountEdge` throws when
+its ServiceWorker cannot take control. `tests/reservation-fallback.test.ts` pins which refused reservations
+drop a join to relay mode and which fail it. `tests/consumer.test.ts` compiles a real dependent against all three
+entry points under three tsconfig shapes — the `NodeNext` row is the only one
+that honours the `exports` map, and for a subpath there is no legacy `types`
+field to fall back to.
+
+A member is also exercised for real in `@statewalker/httpeers-conformance`:
+two live members redeem invitations from a live hub over a relay, call each
+other, and the far side reports back a subject read out of a verified Biscuit
+that matches the peer its handshake proved. `member-relay-fallback.test.ts` and
+`member-reservation-fallback.test.ts` there run the two ways into relay mode
+against a live hub: an upgrade that fails, and a hub whose reservation store is
+full.

package/dist/browser-platform.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The three things a page does differently, as one `MemberPlatform`.
+ *
+ * THIS IS WHAT THE EXTRACTION IS FOR. The prototype had two lifecycles —
+ * `startBrowserPeer` (644 lines) and a Node equivalent — that agreed on every
+ * step and diverged on three: how a node is built, whether an edge is mounted,
+ * and whether the process gets wake events. Rung 01 replaced both with
+ * `startMember` plus an injected platform, and porting `peer-runtime.ts` here
+ * would have brought the duplication back through the front door.
+ *
+ * So there is no browser peer runtime in this package. There is one lifecycle
+ * and this object.
+ */
+import type { MemberPlatform } from "./start-member.js";
+export interface BrowserPlatformInit {
+    /**
+     * Where the ServiceWorker script lives. Omitting it is not an option the
+     * edge survives — see `mountEdge`.
+     */
+    serviceWorkerUrl?: string;
+    /**
+     * Relax libp2p's dial gater for loopback and private addresses.
+     *
+     * A page dialling `127.0.0.1` is a development setup, and the default gater
+     * refuses it silently. Off in production, where refusing is right.
+     */
+    dev?: boolean;
+}
+export declare function browserPlatform(init?: BrowserPlatformInit): MemberPlatform;
+//# sourceMappingURL=browser-platform.d.ts.map

package/dist/browser-platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-platform.d.ts","sourceRoot":"","sources":["../src/browser-platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAgB,eAAe,CAAC,IAAI,GAAE,mBAAwB,GAAG,cAAc,CAiB9E"}

package/dist/browser-platform.js

@@ -0,0 +1,30 @@
+/**
+ * The three things a page does differently, as one `MemberPlatform`.
+ *
+ * THIS IS WHAT THE EXTRACTION IS FOR. The prototype had two lifecycles —
+ * `startBrowserPeer` (644 lines) and a Node equivalent — that agreed on every
+ * step and diverged on three: how a node is built, whether an edge is mounted,
+ * and whether the process gets wake events. Rung 01 replaced both with
+ * `startMember` plus an injected platform, and porting `peer-runtime.ts` here
+ * would have brought the duplication back through the front door.
+ *
+ * So there is no browser peer runtime in this package. There is one lifecycle
+ * and this object.
+ */
+import { createBrowserNode } from "./browser-profile.js";
+import { mountEdge } from "./edge.js";
+import { watchPageWake } from "./page-wake.js";
+export function browserPlatform(init = {}) {
+    return {
+        createNode: async ({ privateKey }) => createBrowserNode({ privateKey, dev: init.dev ?? false }),
+        // A PAGE ONLY. `MemberHandle.fetch` is the edge on both platforms; what a
+        // page additionally gets is a same-origin URL a plain `fetch()` reaches it
+        // through, which is what `baseUrl` is and why it is optional on the handle.
+        mountEdge: async ({ key, dispatch }) => mountEdge({ key, dispatch, serviceWorkerUrl: init.serviceWorkerUrl }),
+        // A PAGE ONLY. A Node process gets no wake events, so there the
+        // supervisor's backstop timer is the whole story. A tab that was suspended
+        // and is now visible again should re-check its hub link immediately rather
+        // than wait out a backoff the user can feel.
+        watchWake: (onWake) => watchPageWake(onWake),
+    };
+}

package/dist/browser-profile.d.ts

@@ -0,0 +1,85 @@
+import type { Ed25519PrivateKey, Libp2p } from "@libp2p/interface";
+import { type IsMember } from "@statewalker/httpeers-libp2p";
+/**
+ * Re-exported from `./identity.ts`, which is where they live now -- see
+ * this module's own note on the move. A page that imports
+ * `IDENTITY_STORAGE_KEY` from here keeps working.
+ */
+export { clearIdentity, decodeIdentity, encodeIdentity, IDENTITY_STORAGE_KEY, loadOrCreateIdentity, peerIdOf, } from "./identity.js";
+/**
+ * Does dialing this address need the permissive gater?
+ *
+ * libp2p's browser default refuses to dial loopback and private-range
+ * addresses. `dev` used to be derived from the PAGE's hostname
+ * (`localhost`/`127.0.0.1`), which asks the wrong question: what the gater
+ * objects to is the address being DIALLED, not where the page came from. Open
+ * the same page at `http://192.168.1.5:5177` and the hostname test says
+ * "production" while `httpeers.json` still names a loopback relay -- so every
+ * address in the dial is denied and the failure surfaces as
+ * `DialDeniedError`, whose message blames the relay for being unreachable
+ * when the relay is running perfectly well.
+ *
+ * Asking it of the address fixes both that case and the LAN one (a page on
+ * `192.168.1.5` dialling a relay on `192.168.1.5`, also a private address,
+ * also denied). A public relay address returns false and the gater stays at
+ * its default, which is the behaviour a deployment wants.
+ */
+export declare function dialNeedsPermissiveGater(addr: string): boolean;
+export interface CreateBrowserNodeInit {
+    /**
+     * Relaxes the libp2p connection gater to allow insecure (`ws://`) and
+     * private/loopback dials. libp2p 3.x's browser-only default gater denies
+     * BOTH on its own (`libp2p/dist/src/config/connection-gater.browser.js`)
+     * -- fine in production, where a real deployment's relay is `wss://` on
+     * a real DNS name (`../setup/main.ts`'s `relayAddrFamily`), but fatal in
+     * local development, where the relay is `ws://127.0.0.1:<port>/ws`: with
+     * the default gater EVERY dial this node makes -- to the relay itself,
+     * and to every derived `/p2p-circuit/webrtc/p2p/...` peer address -- is
+     * denied before any handshake even starts. Precedent:
+     * `workspaces/webrun-wire/apps/p2p-demo/lib/browser-node.ts`, which
+     * applies exactly this relaxation gated on `import.meta.env.DEV`.
+     * Required here (no default), rather than silently inferred from
+     * `import.meta.env.DEV`, because THIS file has no bundler-injected `env`
+     * of its own to read -- inferring it here would mean guessing at a value
+     * only the caller (a Vite-built page, see `../static-server/main.ts`'s
+     * "DIST DIRECTORY LAYOUT" note) actually knows.
+     */
+    dev: boolean;
+    /**
+     * This node's signing key. Defaults to this origin's persisted identity
+     * (`./identity.ts`'s `loadOrCreateIdentity`) -- which is what both
+     * ordinary pages want and neither has to say.
+     *
+     * SUPPLIED BY A CALLER THAT NEEDS THE KEY FOR SOMETHING ELSE TOO, which
+     * today means the hub page: `createLibp2p` never gives a key back out,
+     * and the hub must hand the SAME key to `createPeer` (`mintToken` signs
+     * with it, and a mesh whose hub node and hub signer were different keys
+     * would mint tokens no peer could match to the hub it is talking to).
+     * Loading it once and passing it here is the only way to guarantee they
+     * are the same key rather than two reads that happen to agree.
+     */
+    privateKey: Ed25519PrivateKey;
+    /**
+     * Makes this node a HUB: it relays signalling for the peers this answers
+     * true for, and for nobody else. See `../hub-relay.ts`. Only the hub page
+     * passes it.
+     */
+    isMember?: IsMember;
+}
+/**
+ * Build this origin's browser libp2p node -- identity loaded/generated,
+ * transports and encryption wired, NOT yet dialled anywhere. See
+ * `dialRelay` / `waitForCircuitReservation` for the next two steps, kept
+ * separate so a caller (`peer-runtime.ts`) can report distinct lifecycle
+ * states for "connecting to the relay" and "waiting for the reservation"
+ * rather than one opaque await.
+ */
+export declare function createBrowserNode(init: CreateBrowserNodeInit): Promise<Libp2p>;
+/**
+ * Re-exported from `../reservation.ts`, which is where they live now -- see
+ * this module's own note on the move. A page that imports them from here
+ * keeps working, and a reader looking for "what happens after
+ * `createBrowserNode`" still finds the answer named in this file.
+ */
+export { dialRelay, RESERVATION_POLL_ATTEMPTS, RESERVATION_POLL_INTERVAL_MS, type WaitForCircuitReservationInit, waitForCircuitReservation, } from "@statewalker/httpeers-libp2p";
+//# sourceMappingURL=browser-profile.d.ts.map

package/dist/browser-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-profile.d.ts","sourceRoot":"","sources":["../src/browser-profile.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGnE,OAAO,EAAmB,KAAK,QAAQ,EAAmB,MAAM,8BAA8B,CAAC;AAG/F;;;;GAIG;AACH,OAAO,EACL,aAAa,EACb,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAO9D;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;;;;;;;OAiBG;IACH,GAAG,EAAE,OAAO,CAAC;IACb;;;;;;;;;;;;OAYG;IACH,UAAU,EAAE,iBAAiB,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBpF;AASD;;;;;GAKG;AACH,OAAO,EACL,SAAS,EACT,yBAAyB,EACzB,4BAA4B,EAC5B,KAAK,6BAA6B,EAClC,yBAAyB,GAC1B,MAAM,8BAA8B,CAAC"}

package/dist/browser-profile.js

@@ -0,0 +1,120 @@
+/**
+ * The browser libp2p profile.
+ *
+ * A browser cannot listen for inbound TCP the way `../hub/main.ts` /
+ * `../relay/main.ts` do (`transport-duplex.ts`'s `createNode`, TCP-only,
+ * is Node-side and stays Node-side). Instead this node reserves a relayed
+ * address on the deployment's relay and accepts a WebRTC upgrade brokered
+ * over it -- WebSockets to dial the relay in the first place,
+ * Circuit-Relay-v2 for the reservation and for dialling other peers'
+ * relayed addresses, WebRTC for the peer-to-peer upgrade once a relayed
+ * connection exists. `addresses.listen: ['/p2p-circuit', '/webrtc']` and
+ * this transport list are the exact configuration design note 17 §4 (the
+ * relay prototype) and the validated browser-WebRTC prototype (repo notes,
+ * `httpeers-plan/prototypes/21-browser-webrtc-prototype-validated/app.ts`)
+ * both landed on -- not a guess assembled from the libp2p docs.
+ *
+ * DIALING THE RELAY AND WAITING FOR THE RESERVATION LIVE IN
+ * `../reservation.ts`, re-exported below so this module still reads as the
+ * one place a page asks "how do I get a browser node onto the mesh". They
+ * moved there in Task 20 because they touch nothing transport-specific and
+ * three callers now need them -- this file, `../hub/main.ts`, and
+ * `tests/e2e/harness.ts`, the last of which had hand-copied the poll loop
+ * rather than import it through this module's `@libp2p/webrtc` dependency.
+ *
+ * IDENTITY PERSISTS PER ORIGIN, IN INDEXEDDB -- and it lives in
+ * `./identity.ts` now, re-exported below. It moved there in Task 24
+ * because the hub page needs the key itself, not just a node built from
+ * it: `createLibp2p` never hands a generated key back out, and the hub must
+ * pass the very same key to `createPeer` so its `mintToken` closure signs
+ * as the mesh. See that module for the format contract and for why
+ * per-origin identities are deliberate.
+ */
+import { noise } from "@chainsafe/libp2p-noise";
+import { yamux } from "@chainsafe/libp2p-yamux";
+import { circuitRelayTransport } from "@libp2p/circuit-relay-v2";
+import { identify } from "@libp2p/identify";
+import { webRTC } from "@libp2p/webrtc";
+import { webSockets } from "@libp2p/websockets";
+import { hubRelayService, membershipGater } from "@statewalker/httpeers-libp2p";
+import { createLibp2p } from "libp2p";
+/**
+ * Re-exported from `./identity.ts`, which is where they live now -- see
+ * this module's own note on the move. A page that imports
+ * `IDENTITY_STORAGE_KEY` from here keeps working.
+ */
+export { clearIdentity, decodeIdentity, encodeIdentity, IDENTITY_STORAGE_KEY, loadOrCreateIdentity, peerIdOf, } from "./identity.js";
+/**
+ * Does dialing this address need the permissive gater?
+ *
+ * libp2p's browser default refuses to dial loopback and private-range
+ * addresses. `dev` used to be derived from the PAGE's hostname
+ * (`localhost`/`127.0.0.1`), which asks the wrong question: what the gater
+ * objects to is the address being DIALLED, not where the page came from. Open
+ * the same page at `http://192.168.1.5:5177` and the hostname test says
+ * "production" while `httpeers.json` still names a loopback relay -- so every
+ * address in the dial is denied and the failure surfaces as
+ * `DialDeniedError`, whose message blames the relay for being unreachable
+ * when the relay is running perfectly well.
+ *
+ * Asking it of the address fixes both that case and the LAN one (a page on
+ * `192.168.1.5` dialling a relay on `192.168.1.5`, also a private address,
+ * also denied). A public relay address returns false and the gater stays at
+ * its default, which is the behaviour a deployment wants.
+ */
+export function dialNeedsPermissiveGater(addr) {
+    const ip = /\/ip4\/([0-9.]+)/.exec(addr)?.[1];
+    if (ip == null)
+        return /\/dns4?\/localhost(\/|$)/.test(addr);
+    if (ip === "127.0.0.1" || ip.startsWith("127."))
+        return true;
+    if (ip.startsWith("10.") || ip.startsWith("192.168."))
+        return true;
+    const m = /^172\.(\d+)\./.exec(ip);
+    return m != null && Number(m[1]) >= 16 && Number(m[1]) <= 31;
+}
+/**
+ * Build this origin's browser libp2p node -- identity loaded/generated,
+ * transports and encryption wired, NOT yet dialled anywhere. See
+ * `dialRelay` / `waitForCircuitReservation` for the next two steps, kept
+ * separate so a caller (`peer-runtime.ts`) can report distinct lifecycle
+ * states for "connecting to the relay" and "waiting for the reservation"
+ * rather than one opaque await.
+ */
+export async function createBrowserNode(init) {
+    // REQUIRED now. It used to fall back to `loadOrCreateIdentity()`, which
+    // reached for IndexedDB from a function a Node member also calls — see
+    // `./kv.js`. The caller holds the key; this only starts a node with it.
+    const privateKey = init.privateKey;
+    return createLibp2p({
+        privateKey,
+        // ONLY A HUB RESERVES ON THE PUBLIC RELAY. A member is reached through
+        // its hub (`../hub-link.ts`), so it listens for WebRTC upgrades and
+        // nothing else; a `/p2p-circuit` entry here would make libp2p reserve on
+        // the first relay it meets -- the public one -- and spend its capacity.
+        addresses: { listen: init.isMember != null ? ["/p2p-circuit", "/webrtc"] : ["/webrtc"] },
+        transports: [webSockets(), webRTC(), circuitRelayTransport()],
+        connectionEncrypters: [noise()],
+        streamMuxers: [yamux()],
+        connectionGater: {
+            ...(init.dev ? { denyDialMultiaddr: async () => false } : {}),
+            // The thunk is read at DECISION time, so it closes the ordering cycle:
+            // this node must exist before the hub that answers `isMember` does.
+            ...(init.isMember != null ? membershipGater(() => init.isMember) : {}),
+        },
+        services: nodeServices(init.isMember),
+    });
+}
+/** The relay service only on a hub, and only behind its membership test. */
+function nodeServices(isMember) {
+    return isMember != null
+        ? { identify: identify(), relay: hubRelayService() }
+        : { identify: identify() };
+}
+/**
+ * Re-exported from `../reservation.ts`, which is where they live now -- see
+ * this module's own note on the move. A page that imports them from here
+ * keeps working, and a reader looking for "what happens after
+ * `createBrowserNode`" still finds the answer named in this file.
+ */
+export { dialRelay, RESERVATION_POLL_ATTEMPTS, RESERVATION_POLL_INTERVAL_MS, waitForCircuitReservation, } from "@statewalker/httpeers-libp2p";

package/dist/browser.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The BROWSER half of a member: the platform object, the two IndexedDB
+ * stores, and one function that assembles a page session out of them.
+ *
+ * EVERYTHING BROWSER-BOUND IS BEHIND THIS ENTRY, and that is a load-bearing
+ * arrangement rather than tidiness. `idb-keyval` needs a real IndexedDB;
+ * `@libp2p/webrtc`'s Node build loads a native module and throws on import;
+ * `@statewalker/webrun-http-browser/sw` is a ServiceWorker adapter. Any of
+ * them reachable from `./index.ts` would make a Node member fail at import
+ * time, which `tests/boundary.test.ts` now measures by reachability.
+ *
+ * `createSession` IS THE ONLY THING HERE THAT IS NOT A RE-EXPORT. It is the
+ * defaults `session.ts` deliberately does not carry: the platform, the two
+ * stores, `location.search` and the reload. A page that wants to substitute
+ * any of them passes it and this steps aside.
+ */
+import type { AsyncBytesBackend, AsyncKeyValueBackend } from "./kv.js";
+import type { PeerSession, PeerSessionInit } from "./session.js";
+export { type BrowserPlatformInit, browserPlatform } from "./browser-platform.js";
+export { type CreateBrowserNodeInit, createBrowserNode, dialNeedsPermissiveGater, } from "./browser-profile.js";
+export { DEFAULT_CONTROL_TIMEOUT_MS, DEFAULT_SERVICE_WORKER_URL, type MountEdgeInit, mountEdge, UncontrolledPageError, } from "./edge.js";
+export { type WakeDocument, type WakeWindow, type WatchPageWakeInit, watchPageWake, } from "./page-wake.js";
+/** The real thing: the same IndexedDB store `@statewalker/webrun-http-browser` already uses. */
+export declare function idbBackend(): AsyncKeyValueBackend;
+export declare function idbBytesBackend(): AsyncBytesBackend;
+/**
+ * `PeerSessionInit` with every browser-supplied part made optional.
+ *
+ * The four that become optional are exactly the four `session.ts` refuses to
+ * default, and they are listed there with the reason. `serviceWorkerUrl` and
+ * `dev` are here rather than there because they are `browserPlatform`'s
+ * arguments, and a page that passes its own `platform` has no use for them.
+ */
+export interface CreateSessionInit extends Omit<PeerSessionInit, "platform" | "identity" | "meshMemory" | "reload" | "search"> {
+    platform?: PeerSessionInit["platform"];
+    identity?: PeerSessionInit["identity"];
+    meshMemory?: PeerSessionInit["meshMemory"];
+    reload?: () => void;
+    /** Defaults to `location.search`, read once at `start()`. */
+    search?: string;
+    /** Where the ServiceWorker script lives — see `mountEdge`. */
+    serviceWorkerUrl?: string;
+    /** Relax libp2p's dial gater for loopback and private addresses. Off in production. */
+    dev?: boolean;
+}
+export declare function createSession(init: CreateSessionInit): PeerSession;
+export { type ResetResult, resetBrowserState } from "./reset.js";
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEvE,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGjE,OAAO,EAAE,KAAK,mBAAmB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EACL,KAAK,qBAAqB,EAC1B,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,KAAK,aAAa,EAClB,SAAS,EACT,qBAAqB,GACtB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,aAAa,GACd,MAAM,gBAAgB,CAAC;AASxB,gGAAgG;AAChG,wBAAgB,UAAU,IAAI,oBAAoB,CAMjD;AAED,wBAAgB,eAAe,IAAI,iBAAiB,CAMnD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBACf,SAAQ,IAAI,CAAC,eAAe,EAAE,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC3F,QAAQ,CAAC,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;IACvC,QAAQ,CAAC,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;IACvC,UAAU,CAAC,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,WAAW,CAWlE;AACD,OAAO,EAAE,KAAK,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/browser.js

@@ -0,0 +1,51 @@
+/**
+ * The BROWSER half of a member: the platform object, the two IndexedDB
+ * stores, and one function that assembles a page session out of them.
+ *
+ * EVERYTHING BROWSER-BOUND IS BEHIND THIS ENTRY, and that is a load-bearing
+ * arrangement rather than tidiness. `idb-keyval` needs a real IndexedDB;
+ * `@libp2p/webrtc`'s Node build loads a native module and throws on import;
+ * `@statewalker/webrun-http-browser/sw` is a ServiceWorker adapter. Any of
+ * them reachable from `./index.ts` would make a Node member fail at import
+ * time, which `tests/boundary.test.ts` now measures by reachability.
+ *
+ * `createSession` IS THE ONLY THING HERE THAT IS NOT A RE-EXPORT. It is the
+ * defaults `session.ts` deliberately does not carry: the platform, the two
+ * stores, `location.search` and the reload. A page that wants to substitute
+ * any of them passes it and this steps aside.
+ */
+import { del, get, set } from "idb-keyval";
+import { browserPlatform } from "./browser-platform.js";
+import { createMeshMemory } from "./mesh-memory.js";
+import { createIdentityStore, createPeerSession } from "./session.js";
+export { browserPlatform } from "./browser-platform.js";
+export { createBrowserNode, dialNeedsPermissiveGater, } from "./browser-profile.js";
+export { DEFAULT_CONTROL_TIMEOUT_MS, DEFAULT_SERVICE_WORKER_URL, mountEdge, UncontrolledPageError, } from "./edge.js";
+export { watchPageWake, } from "./page-wake.js";
+/** The real thing: the same IndexedDB store `@statewalker/webrun-http-browser` already uses. */
+export function idbBackend() {
+    return {
+        get: async (key) => (await get(key)) ?? undefined,
+        set: async (key, value) => await set(key, value),
+        delete: async (key) => await del(key),
+    };
+}
+export function idbBytesBackend() {
+    return {
+        get: async (key) => (await get(key)) ?? undefined,
+        set: async (key, value) => await set(key, value),
+        delete: async (key) => await del(key),
+    };
+}
+export function createSession(init) {
+    return createPeerSession({
+        ...init,
+        search: init.search ?? location.search,
+        platform: init.platform ??
+            browserPlatform({ serviceWorkerUrl: init.serviceWorkerUrl, dev: init.dev ?? false }),
+        identity: init.identity ?? createIdentityStore({ backend: idbBytesBackend() }),
+        meshMemory: init.meshMemory ?? createMeshMemory({ backend: idbBackend() }),
+        reload: init.reload ?? (() => location.reload()),
+    });
+}
+export { resetBrowserState } from "./reset.js";

package/dist/connection-kind.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Is this peer reached directly, or through the relay?
+ *
+ * WHY THIS EXISTS. libp2p does not upgrade a circuit to WebRTC on its own:
+ * `join.ts`'s `preDialPeer` dials `<relay>/p2p-circuit/webrtc/p2p/<peer>`
+ * explicitly, and the circuit's only job there is to carry the SDP exchange.
+ * When that dial fails -- symmetric NAT on a mobile carrier, a VPN, no reachable
+ * STUN -- `edge-dispatch.ts` SWALLOWS the failure by design and the call is
+ * attempted anyway. `remote()` then dials by peer id, which resolves through the
+ * peerStore to a bare `/p2p-circuit` address, and every byte crosses the relay.
+ *
+ * That fallback works. What it does not do is announce itself, and the silence
+ * is the problem: it is 10-100x slower, it spends the relay operator's
+ * bandwidth instead of going peer-to-peer, and while the relay applied a
+ * per-connection data cap it truncated transfers mid-stream. The visible
+ * symptom was broken images in a gallery, with one of them loading fine in a
+ * fresh tab -- which reads as random corruption rather than as a transport
+ * that quietly changed underneath.
+ *
+ * Reading the open connection's own address is the whole diagnosis, and it is
+ * one call. Strings in, so this module needs no libp2p import and is testable
+ * under plain Node.
+ */
+export type ConnectionKind = "direct" | "relayed" | "none";
+/**
+ * Classify the connections open to one peer, from their multiaddrs.
+ *
+ * `/webrtc` present means the WebRTC upgrade completed and the relay is no
+ * longer in the data path. A `/p2p-circuit` WITHOUT it means it did not, and
+ * traffic is being relayed. Direct wins when both are open, because that is the
+ * one libp2p will actually use.
+ */
+export declare function classifyConnection(remoteAddrs: readonly string[]): ConnectionKind;
+/** One line a page can render unconditionally, saying what the kind means rather than naming it. */
+export declare function describeConnection(kind: ConnectionKind): string;
+//# sourceMappingURL=connection-kind.d.ts.map

package/dist/connection-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-kind.d.ts","sourceRoot":"","sources":["../src/connection-kind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3D;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAMjF;AAED,oGAAoG;AACpG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAS/D"}