@statewalker/httpeers-member 0.1.4

package/dist/start-member.js

@@ -0,0 +1,307 @@
+/**
+ * `startMember` — the candidate `member` package's entry point.
+ *
+ * THIS IS `src/browser/peer-runtime.ts`'s `startBrowserPeer` WITH THREE
+ * COUPLINGS LIFTED OUT, and nothing else changed. Every step of the join is
+ * the proven one, imported from the stack rather than reimplemented:
+ * `dialRelay`, `reachHub`, `reachHubRelayed`, `createPeer`, `resumeMembership`,
+ * `redeemInvitation`, `reserveOnHub`, `superviseHubReservation`,
+ * `leaveRelay`, `startJoin`, `createRouteEnsurer`, `createEdgeDispatch`.
+ * If this file had to re-implement any of them, the seam would be in the
+ * wrong place and the rung would have failed.
+ *
+ * The three couplings, and why each is a platform boundary rather than a
+ * preference:
+ *
+ *   1. `createNode` — `createBrowserNode` hard-codes the browser transport
+ *      set (webSockets + webRTC + circuitRelay) and reads the identity key
+ *      out of IndexedDB. Node needs `tcp` as well, and its key comes from a
+ *      file. The LISTEN ADDRESSES ARE NOT A PLATFORM CHOICE and are kept
+ *      identical: a member listens on `/p2p-circuit` + `/webrtc` because it
+ *      reserves on its hub, which is what `feat/hub-relay` established.
+ *   2. `mountEdge` — the ServiceWorker is how a *page* turns `fetch()` into
+ *      a mesh call. Node has no ServiceWorker and needs none: the dispatch
+ *      handler IS the edge, callable in process. So the edge is optional,
+ *      and `MemberHandle.fetch` is always present — on both platforms it is
+ *      the same `createEdgeDispatch` handler, which is the whole isomorphism
+ *      claim in one field.
+ *   3. `watchWake` — `page-wake.ts` listens on `window`/`document`. A Node
+ *      process has no such events; the supervisor's own backstop timer is
+ *      what covers it, so the default is a no-op rather than a stub.
+ *
+ * `rules` replaces `policies`: `peer-runtime.ts` calls the app's `appRules`,
+ * which bakes `APP_RULES` — an application's vocabulary — into what ought to
+ * be library code. The caller passes a built `RuleSet` instead.
+ */
+import { peerIdFromString } from "@libp2p/peer-id";
+import { RevocationCache, withAccess } from "@statewalker/httpeers-access";
+import { ANONYMOUS, forwardLocalOnly, lookupPeer } from "@statewalker/httpeers-core";
+import { dialRelay, HubReservationError, leaveRelay, reachHub, reachHubRelayed, reserveOnHub, servePeer, superviseHubReservation, } from "@statewalker/httpeers-libp2p";
+import { classifyConnection } from "./connection-kind.js";
+import { createEdgeDispatch } from "./edge-dispatch.js";
+import { createRouteEnsurer, nextInitialSeq, REVOCATION_MAX_STALENESS_MS, redeemInvitation, resumeMembership, startJoin, } from "./join.js";
+export class MemberJoinError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+        this.name = "MemberJoinError";
+    }
+}
+/**
+ * Does a refused reservation on the hub leave the join standing, in relay
+ * mode? Only when the refusal says nothing about THIS member:
+ *
+ *   - `store-full` (`RESERVATION_REFUSED`) and `resource-limit`
+ *     (`RESOURCE_LIMIT_EXCEEDED`) -- the hub is out of capacity. This is the
+ *     production failure: a hub's relay grants a fixed number of
+ *     reservations, and once they were spent every direct-linked page failed
+ *     to join while relay-mode pages worked.
+ *   - `no-answer` -- a timeout or a dropped link; nothing was refused.
+ *
+ * The reservation only lets OTHER members reach this one; everything the
+ * member does itself works in relay mode, so failing the join over it is
+ * strictly worse than degrading.
+ *
+ * NOT for `not-a-member` (`PERMISSION_DENIED`): the hub has just accepted
+ * this peer, so a hub that now denies it membership contradicts itself (a
+ * revocation in between, a gater reading a different store) -- a real fault
+ * to report, not a condition to route around. NOT for `no-relay`: a hub
+ * deployed without its relay service is a configuration error that would put
+ * every member in relay mode silently. NOT for any other status, which is a
+ * protocol fault. And not for errors that are not refusals at all.
+ */
+export function fallsBackToRelay(err) {
+    if (!(err instanceof HubReservationError))
+        return false;
+    return (err.refusal === "store-full" || err.refusal === "resource-limit" || err.refusal === "no-answer");
+}
+export async function startMember(init) {
+    const onState = init.onState ?? (() => { });
+    const relayAddr = init.config.relayAddrs[0];
+    if (relayAddr == null)
+        throw new Error("startMember: config.relayAddrs is empty.");
+    const hubPeerId = init.config.hubPeerId;
+    onState("connecting-relay");
+    const node = await init.platform.createNode({ privateKey: init.privateKey });
+    const unwind = [async () => await node.stop()];
+    const startFailed = async () => {
+        for (const step of [...unwind].reverse())
+            await step().catch(() => { });
+    };
+    try {
+        await dialRelay(node, relayAddr);
+        onState("starting-peer");
+        const revocationCache = new RevocationCache({ maxStalenessMs: REVOCATION_MAX_STALENESS_MS });
+        // `createPeer` in the prototype did transport + binding + policy + router
+        // in one closed function. Here the three are separate packages that meet
+        // at a `FetchHandler`: `servePeer` owns the wire and the router,
+        // `withAccess` owns who may do what, and neither imports the other.
+        const peer = await servePeer({
+            node,
+            mounts: init.mounts,
+            // WITHOUT THIS A MEMBER CANNOT CALL ANOTHER MEMBER AT ALL. The edge
+            // hands `/{peerId}/{path}` to `peer.dispatch`, and the router refuses to
+            // forward unless asked — deny by default, which is right (R-2: relaying
+            // is its own capability). `createPeer` in the prototype supplied this
+            // policy; the extraction split it into `servePeer` + `withAccess` and
+            // dropped it, and every type check stayed green because a missing
+            // optional callback is not a type error. A real mesh found it in one
+            // call: 403 `this peer does not relay for you`, from the CALLER's own
+            // router.
+            allowForward: forwardLocalOnly,
+            // Calls TO THE HUB may ride a limited connection, and only those. Set
+            // before the link mode is known, and harmless when it turns out to be
+            // `"direct"`: the link prefers an unlimited connection whenever one is
+            // open. Serving stays closed to limited connections -- the hub's own
+            // relay limits are what protect member-to-member traffic.
+            callOnLimitedConnection: (peerId) => peerId === hubPeerId,
+            access: withAccess({
+                issuer: hubPeerId,
+                rules: init.rules,
+                selfPeer: node.peerId.toString(),
+                // What the TRANSPORT proved. `serveTransport` registers it on the
+                // request before dispatch, so reading it back here is the same fact,
+                // not a second opinion.
+                provenPeer: (req) => lookupPeer(req) ?? ANONYMOUS,
+                revocation: revocationCache,
+            }),
+        });
+        unwind.push(async () => await peer.stop());
+        // WEBRTC FIRST, ONCE PER JOIN, THEN THE RELAY CIRCUIT. Any failure of the
+        // upgrade counts: a hub that WebRTC cannot reach fails in more ways than
+        // one (no route, ICE timeout, no transport), and the fallback is the same
+        // for all.
+        onState("dialing-hub");
+        let hubLink;
+        let hubLinkNote;
+        try {
+            await reachHub(node, relayAddr, hubPeerId);
+            hubLink = "direct";
+        }
+        catch (upgradeErr) {
+            try {
+                await reachHubRelayed(node, relayAddr, hubPeerId);
+                hubLink = "relay";
+            }
+            catch (relayErr) {
+                throw new Error(`startMember: the hub (${hubPeerId}) could not be reached over WebRTC ` +
+                    `(${String(upgradeErr)}) nor over a relay circuit (${String(relayErr)}).`, { cause: relayErr });
+            }
+        }
+        onState("resuming");
+        const seq = nextInitialSeq();
+        const resume = await resumeMembership({
+            peer,
+            hubPeerId,
+            addrs: node.getMultiaddrs().map((addr) => addr.toString()),
+            advertisements: init.advertisements?.(),
+            seq,
+        });
+        let initialToken;
+        let joinedBy;
+        if (resume.status === "resumed") {
+            initialToken = resume.token;
+            joinedBy = "resumed";
+        }
+        else if (resume.refusal.kind === "duplicate-identity") {
+            throw new MemberJoinError("duplicate-identity", `another live peer is already using this identity (${peer.peerId}) on this mesh.`);
+        }
+        else if (resume.refusal.kind !== "not-a-member") {
+            throw new MemberJoinError("presence-refused", `the hub (${hubPeerId}) refused this peer's first heartbeat: ${resume.refusal.message}`);
+        }
+        else if (init.invitationId == null) {
+            throw new MemberJoinError("not-a-member", `the hub (${hubPeerId}) does not list this peer (${peer.peerId}) as a member, and no ` +
+                "invitation was supplied.");
+        }
+        else {
+            onState("joining");
+            try {
+                const redemption = await redeemInvitation(peer, hubPeerId, init.invitationId);
+                initialToken = redemption.token;
+                joinedBy = "redeemed";
+            }
+            catch (err) {
+                throw new MemberJoinError("invitation-refused", `the hub (${hubPeerId}) would not accept that invitation. ${String(err)}`, { cause: err });
+            }
+        }
+        // A MEMBER RESERVES ON ITS HUB, NOT ON THE PUBLIC RELAY, and only once
+        // the hub has accepted it — `hub-relay.ts`'s membership gater refuses
+        // everyone else. This is the ordering `feat/hub-relay` established.
+        //
+        // NOT OVER THE RELAY CIRCUIT. There is nothing to reserve over (the
+        // circuit carries only this member's calls), and `leaveRelay` would hang
+        // up the circuit itself, since it runs through the relay.
+        if (hubLink === "direct") {
+            onState("awaiting-reservation");
+            const refused = await reserveOnHub(node, hubPeerId).then(() => null, (err) => err);
+            if (refused != null && !fallsBackToRelay(refused))
+                throw refused;
+            if (refused != null) {
+                // DOWN TO RELAY MODE, INTO THE SAME STATE AS A MEMBER WHOSE UPGRADE
+                // FAILED: one kept circuit, no supervisor, no `leaveRelay`, the
+                // relay-mode re-link below. The WebRTC connection goes, too -- kept, it
+                // would make this a "direct" member with none of direct mode's
+                // reservation duties, and the hub would report it as direct while this
+                // handle says relay. The failed circuit listener stays behind, empty
+                // (`reserveOnHub`'s note).
+                await node.hangUp(peerIdFromString(hubPeerId)).catch(() => { });
+                try {
+                    await reachHubRelayed(node, relayAddr, hubPeerId);
+                }
+                catch (relayErr) {
+                    throw new Error(`startMember: the hub (${hubPeerId}) refused a reservation (${String(refused)}), ` +
+                        `and the relay circuit to it could not be opened (${String(relayErr)}).`, { cause: relayErr });
+                }
+                hubLink = "relay";
+                hubLinkNote =
+                    "Connected through the relay only: the hub refused this member a reservation, so " +
+                        "other members cannot reach it; its own calls are unaffected. Reconnecting tries the " +
+                        `direct link again. (${refused.message})`;
+            }
+        }
+        if (hubLink === "direct") {
+            const supervisor = superviseHubReservation({ node, relayAddr, hubPeerId });
+            const unwatchWake = init.platform.watchWake?.(() => supervisor.poke()) ?? (() => { });
+            unwind.push(async () => {
+                unwatchWake();
+                supervisor.stop();
+            });
+            await leaveRelay(node, relayAddr).catch(() => { });
+        }
+        const join = startJoin({
+            peer,
+            node,
+            hubPeerId,
+            relayAddr,
+            initialToken,
+            initialSeq: seq,
+            revocationCache,
+            advertisements: init.advertisements,
+            onPresenceRefused: init.onPresenceRefused,
+            heartbeatIntervalMs: init.heartbeatIntervalMs,
+            keepaliveIntervalMs: init.keepaliveIntervalMs,
+            // A relay-mode member re-links over a NEW CIRCUIT ONLY, and stays in
+            // relay mode: retrying WebRTC here could land it "direct" with none of
+            // the reservation duties above. One that joined direct keeps `reachHub`,
+            // with the supervisor restoring its reservation.
+            relinkHub: hubLink === "relay"
+                ? async () => {
+                    await reachHubRelayed(node, relayAddr, hubPeerId);
+                }
+                : undefined,
+        });
+        unwind.push(async () => join.stop());
+        onState("mounting-edge");
+        const dispatchInit = {
+            dispatch: peer.dispatch,
+            key: init.key,
+            token: () => join.token(),
+            ensureRoute: createRouteEnsurer({
+                node,
+                relayAddr,
+                selfPeerId: peer.peerId,
+                hubPeerId,
+                meshView: () => join.meshView(),
+            }),
+        };
+        const edgeFetch = createEdgeDispatch(dispatchInit);
+        const edge = await init.platform.mountEdge?.({ key: init.key, dispatch: edgeFetch });
+        if (edge != null)
+            unwind.push(async () => await edge.stop());
+        onState("ready");
+        return {
+            peerId: peer.peerId,
+            hubPeerId,
+            relayAddr,
+            joinedBy,
+            fetch: edgeFetch,
+            baseUrl: edge?.baseUrl,
+            node,
+            meshView: () => join.meshView(),
+            token: () => join.token(),
+            hubLink: () => hubLink,
+            hubLinkNote,
+            connectionKind(peerIdStr) {
+                try {
+                    return classifyConnection(node
+                        .getConnections(peerIdFromString(peerIdStr))
+                        .filter((c) => c.status === "open")
+                        .map((c) => c.remoteAddr.toString()));
+                }
+                catch {
+                    return "none";
+                }
+            },
+            async stop() {
+                for (const step of [...unwind].reverse())
+                    await step().catch(() => { });
+                onState("stopped");
+            },
+        };
+    }
+    catch (err) {
+        await startFailed();
+        throw err;
+    }
+}

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@statewalker/httpeers-member",
+  "version": "0.1.4",
+  "type": "module",
+  "description": "Everything a participant does: hold an identity, redeem or resume, connect, keep the link, advertise, discover, call, and serve.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/statewalker/httpeers.git",
+    "directory": "packages/httpeers-member"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "source": "./src/node.ts",
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./browser": {
+      "source": "./src/browser.ts",
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./reset": {
+      "source": "./src/reset.ts",
+      "types": "./dist/reset.d.ts",
+      "import": "./dist/reset.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@libp2p/crypto": "^5.1.23",
+    "@libp2p/interface": "^3.3.0",
+    "@libp2p/peer-id": "^6.0.15",
+    "@multiformats/multiaddr": "^13.0.3",
+    "@statewalker/httpeers-access": "^0.1.3",
+    "@statewalker/httpeers-libp2p": "^0.1.3",
+    "@statewalker/httpeers-core": "^0.1.2"
+  },
+  "peerDependencies": {
+    "@chainsafe/libp2p-noise": "^17.0.0",
+    "@chainsafe/libp2p-yamux": "^8.0.1",
+    "@libp2p/circuit-relay-v2": "^4.2.13",
+    "@libp2p/identify": "^4.1.14",
+    "@libp2p/tcp": "^11.0.28",
+    "@libp2p/webrtc": "^6.0.33",
+    "@libp2p/websockets": "^10.1.21",
+    "@statewalker/webrun-http-browser": "^0.6.0",
+    "idb-keyval": "^6.3.0",
+    "libp2p": "^3.3.11"
+  },
+  "peerDependenciesMeta": {
+    "@chainsafe/libp2p-noise": {
+      "optional": true
+    },
+    "@chainsafe/libp2p-yamux": {
+      "optional": true
+    },
+    "@libp2p/circuit-relay-v2": {
+      "optional": true
+    },
+    "@libp2p/identify": {
+      "optional": true
+    },
+    "@libp2p/tcp": {
+      "optional": true
+    },
+    "@libp2p/webrtc": {
+      "optional": true
+    },
+    "@libp2p/websockets": {
+      "optional": true
+    },
+    "@statewalker/webrun-http-browser": {
+      "optional": true
+    },
+    "idb-keyval": {
+      "optional": true
+    },
+    "libp2p": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@chainsafe/libp2p-noise": "^17.0.0",
+    "@chainsafe/libp2p-yamux": "^8.0.1",
+    "@libp2p/circuit-relay-v2": "^4.2.13",
+    "@libp2p/identify": "^4.1.14",
+    "@libp2p/tcp": "^11.0.28",
+    "@libp2p/webrtc": "^6.0.33",
+    "@libp2p/websockets": "^10.1.21",
+    "@statewalker/webrun-http-browser": "^0.6.0",
+    "@types/node": "^26.6.4",
+    "idb-keyval": "^6.3.0",
+    "libp2p": "^3.3.11",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "pnpm run build && pnpm run typecheck && vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src tests",
+    "lint:check": "biome check src tests"
+  }
+}

package/src/browser-platform.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 { Ed25519PrivateKey } from "@libp2p/interface";
+import { createBrowserNode } from "./browser-profile.js";
+import { mountEdge } from "./edge.js";
+import { watchPageWake } from "./page-wake.js";
+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 function browserPlatform(init: BrowserPlatformInit = {}): MemberPlatform {
+  return {
+    createNode: async ({ privateKey }: { privateKey: Ed25519PrivateKey }) =>
+      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/src/browser-profile.ts

@@ -0,0 +1,179 @@
+/**
+ * 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 type { Ed25519PrivateKey, Libp2p } from "@libp2p/interface";
+import { webRTC } from "@libp2p/webrtc";
+import { webSockets } from "@libp2p/websockets";
+import { hubRelayService, type IsMember, membershipGater } from "@statewalker/httpeers-libp2p";
+import { createLibp2p, type ServiceFactoryMap } 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: string): boolean {
+  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;
+}
+
+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 async function createBrowserNode(init: CreateBrowserNodeInit): Promise<Libp2p> {
+  // 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 as IsMember) : {}),
+    },
+    services: nodeServices(init.isMember),
+  });
+}
+
+/** The relay service only on a hub, and only behind its membership test. */
+function nodeServices(isMember: IsMember | undefined): ServiceFactoryMap {
+  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,
+  type WaitForCircuitReservationInit,
+  waitForCircuitReservation,
+} from "@statewalker/httpeers-libp2p";