@statewalker/httpeers-libp2p 0.1.3

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,173 @@
+# @statewalker/httpeers-libp2p
+
+The transport: nodes, identity, reachability, and `servePeer` — **the one
+package in the extraction that knows what libp2p is.**
+
+```ts
+import { createNode, generateKey, servePeer } from "@statewalker/httpeers-libp2p";
+import { nodeTransports } from "@statewalker/httpeers-libp2p/node";
+
+const node = await createNode({ privateKey: await generateKey(), transports: nodeTransports() });
+const peer = await servePeer({ node, mounts, access: guard });
+
+await peer.call("12D3KooWOther", new Request("http://peer.local/hello"));
+```
+
+Everything above this package speaks `FetchHandler` and `Mounts`. Nothing above
+it imports `libp2p`.
+
+## `servePeer` is the seam three assemblies collapse into
+
+A hub, a Node member and a page were each wiring a node, a router, an inbound
+handler and an outbound dialler by hand. `servePeer` is that arrangement, once:
+it owns the wire and the router, and it takes `access` as a parameter rather
+than knowing what a token is.
+
+```
+servePeer  ──owns──>  the protocol handler, the router, the outbound dialler
+           ──takes──> access: (handler) => handler        ← withAccess, from httpeers-access
+```
+
+The two never import each other. `httpeers-access` has no transport and this
+has no crypto policy; the graph runs `core → access` and `core → libp2p`, and
+`tests/boundary.test.ts` fails if either starts pointing at the other.
+
+`Peer.dispatch` is exposed deliberately — it is the inbound router *after*
+identity binding and policy, which is what lets a local edge reuse the same
+decision path instead of building a second one.
+
+## Transports are a parameter, and that was a defect fix
+
+`createNode` **requires** `transports`. The prototype hard-coded `tcp()` inside
+its node factory, so importing the transport module at all dragged a Node-only
+transport into a browser bundle — in a package whose whole claim was that one
+implementation runs on both.
+
+| Import | Holds | Why it cannot be at the root |
+|---|---|---|
+| `.` | `createNode`, `servePeer`, identity, reachability, duplex | — |
+| `./node` | `nodeTransports()` (adds `tcp`), `fileBytesStore` | `@libp2p/tcp` cannot run in a browser; `node:fs` cannot either |
+| `./browser` | `browserTransports()`, `idbBytesStore` | IndexedDB |
+
+The root's boundary test asserts `@libp2p/tcp` and `node:` never appear there.
+Note what is *not* forbidden: `@libp2p/webrtc` is at the root, because a page
+needs it and a Node process can load it too — though only if its native
+dependency actually built. See the note on `node-datachannel` at the repository
+root.
+
+An explicit export list, never `export *`: the barrel this code came from ended
+with `export * from "./transport-duplex.js"`, which is how a package that
+documented itself as isomorphic pulled libp2p, TCP, Noise and yamux into every
+consumer's bundle.
+
+## Reachability, which is most of what is here
+
+A browser cannot listen for inbound TCP. It reserves a slot on a relay and
+accepts an upgrade brokered over it, and the modules here are the steps of
+that:
+
+| Module | What it does |
+|---|---|
+| `reservation` | `dialRelay`, `waitForCircuitReservation`, `circuitAddrs`, `superviseRelay` (+ `reservationHealthy`, `renewalIntervalMs`) |
+| `hop-reserve` | `requestRelayReservation` — ask the relay itself, in its own protocol |
+| `timers` | the injectable `Timers` seam (`worker-timers` in a background tab) |
+| `hub-link` | `reachHub`, `reachHubRelayed`, `reserveOnHub` (+ `HubReservationError`), `leaveRelay`, `superviseHubReservation` |
+| `hub-relay` | `hubRelayService`, `membershipGater`, `releaseReservation` — a hub relaying for **its own members and nobody else** |
+| `identity` | `generateKey`, `peerIdOf`, `signerOf`, the persisted `identityStore` |
+| `duplex` | the second altitude — see below |
+
+**A reservation yields two addresses and only one works.** The bare
+`/p2p-circuit` entry is a *limited* connection on which libp2p silently refuses
+the protocol; the `/webrtc`-suffixed one is the one to publish. `circuitAddrs`
+returns both, labelled, so nobody has to rediscover which is which by pasting
+the wrong one.
+
+**Only the relay knows whether you are reserved.** `node.getMultiaddrs()` is
+the node's own belief, and on 2026-09-19 a deployed hub held that belief for
+hours while the relay held no reservation at all: the websocket was still up,
+every member got `NO_RESERVATION`, and the supervisor — which decided from that
+address list — saw nothing wrong. So `superviseRelay` asks the relay, on a
+schedule derived from the TTL the relay itself granted (`renewalIntervalMs`: a
+quarter of it, jittered down into its upper quarter; 22.5–30 minutes against a
+two-hour TTL). The request is a circuit-relay v2 `HOP RESERVE` over the
+existing connection (`requestRelayReservation`) — libp2p's own `addRelay` short
+-circuits on its cached entry, is not reachable from `Libp2p`, and blacklists a
+relay locally on failure. Because a relay's reservation store is keyed by peer,
+that one request renews an entry that exists and re-creates one that does not,
+reusing the slot and leaving live circuits alone.
+
+The address list now proves a **loss** (it is gone) and never proves health (it
+is there). `supervisor.state()` carries the whole picture — status,
+`verifiedAt`, `expiresAt`, `lostSince`, consecutive failures, renewal and
+restore counts, last error — and `reservationHealthy(state)` is the rule a
+healthcheck should use: reserved, or lost for less than two minutes. Every
+transition logs one line naming the relay and the reason; the old
+implementation swallowed all of them.
+
+`scripts/probe-hub.mjs <hubPeerId>` answers the same question from OUTSIDE, as
+a member would: it dials `<relay>/p2p-circuit/p2p/<hub>` with an independent
+libp2p client and prints one JSON line. Run it from this package's directory so
+its dependencies resolve. That probe is how the incident was confirmed to be
+real rather than a member-side fault, and it is the check to run first next
+time.
+
+**A refused reservation says which refusal it was.** libp2p reports every
+failed reservation alike ("Some configured addresses failed to be listened
+on"), with the relay's status only in the text. `reserveOnHub` reads it out and
+throws a `HubReservationError` with `status` (the circuit-relay status, or
+`null`) and `refusal`: `store-full` (`RESERVATION_REFUSED` — the hub's relay
+holds as many reservations as it grants), `resource-limit`
+(`RESOURCE_LIMIT_EXCEEDED`), `not-a-member` (`PERMISSION_DENIED`), `no-relay`
+(the hub runs no relay service), `no-answer` (a timeout or a dropped link) or
+`other`. It used to throw one message naming `PERMISSION_DENIED` whatever had
+happened, and a full store was diagnosed in production as a membership problem.
+
+**`membershipGater` takes a thunk, not a value.** A hub's node must exist
+before the member store that answers "is this a member" does, and the thunk is
+read at decision time, which is what closes that ordering cycle.
+
+**A hub's reservation store is sized for a mesh, not for a public relay.**
+libp2p's default holds 15 reservations for two hours each and keeps one after
+its holder hangs up; a hub on it refused every member with
+`RESERVATION_REFUSED` after fifteen distinct peers. `hubRelayService` sizes the
+store at `HUB_MAX_RESERVATIONS` (4096; `{ maxReservations }` overrides it),
+releases a reservation when its holder's last connection closes, and
+`releaseReservation(relay, peerId)` frees a revoked member's slot at once. None
+of this touches the per-circuit data limits (128 KiB, 2 min), which are what
+keep a hub a signalling channel: the store says how *many* members are
+reachable through the hub, not how *much* may cross it.
+
+## `signerOf` — the bridge that stops a mesh naming nobody
+
+A hub signs membership tokens with the same key its node speaks with. Build the
+node from one key and mint with another, and every token's `mesh` claim names a
+peer nobody is talking to — a failure that looks like a policy bug.
+
+```ts
+const signer = signerOf(hubKey);   // { mesh: peerIdOf(hubKey), seed: key.raw.slice(0, 32) }
+```
+
+The return type is declared **structurally** rather than imported from
+`httpeers-access`, so this package does not depend on it. A mismatch is a
+compile error in whichever assembly wires the two together, which is where it
+belongs.
+
+## The second altitude: duplex
+
+A fetch-only contract cannot express a WebSocket — both sides talking with
+neither input closed. `serveDuplex` / `openDuplex` run one `Duplex` per libp2p
+stream, addressed by path through their own mount table, on a separate
+protocol. This exists because the requirement did, not because `FetchHandler`
+was inconvenient: it is a different shape, so it gets a different seam rather
+than a flag.
+
+## Tests
+
+**68, plus 4 skipped** (the platform-entry exemptions in the boundary test).
+`tests/hub-link.test.ts` pins how `reserveOnHub` reads each refusal out of
+libp2p's error text. `tests/serve-peer.test.ts` stands up two real nodes over a real Noise
+handshake and checks that what arrives carries the identity the **transport**
+proved rather than anything the caller said.
+
+The whole stack — relay, hub, members, tokens — is exercised together in
+`@statewalker/httpeers-conformance`.

package/dist/browser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The browser profile.
+ *
+ * A page cannot listen and cannot open a TCP socket. It reaches the mesh by
+ * reserving on a relay and being dialled back through the circuit, so its
+ * transports are the three that make that work:
+ *
+ *   webSockets          — to reach the relay itself, which does listen.
+ *   circuitRelayTransport — to be dialled through that reservation.
+ *   webRTC              — so that once two members have exchanged an offer
+ *                         over the circuit, the data goes directly and the
+ *                         hub stays a signalling channel.
+ *
+ * `tcp()` is absent because it cannot exist here, which is the whole reason
+ * this file is separate from `./node`.
+ */
+import type { BytesStore } from "./identity.js";
+import type { TransportFactory } from "./transport.js";
+/** Transports for a page. Fresh instances per call — libp2p's are not reusable. */
+export declare function browserTransports(): TransportFactory[];
+/**
+ * A `BytesStore` in IndexedDB — where a page keeps its identity.
+ *
+ * NOT `localStorage`, and the difference matters: a key is bytes, and
+ * `localStorage` stores strings, so every read and write would go through a
+ * base64 round trip that can silently truncate. IndexedDB stores a
+ * `Uint8Array` as itself.
+ *
+ * Written against the raw IndexedDB API rather than a wrapper so this package
+ * keeps its single dependency. It is thirty lines and it never changes.
+ */
+export declare function idbBytesStore(name?: string, store?: string): BytesStore;
+//# 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;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAkCvD,mFAAmF;AACnF,wBAAgB,iBAAiB,IAAI,gBAAgB,EAAE,CAMtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,SAAa,EAAE,KAAK,SAAa,GAAG,UAAU,CA0C/E"}

package/dist/browser.js

@@ -0,0 +1,77 @@
+/**
+ * The browser profile.
+ *
+ * A page cannot listen and cannot open a TCP socket. It reaches the mesh by
+ * reserving on a relay and being dialled back through the circuit, so its
+ * transports are the three that make that work:
+ *
+ *   webSockets          — to reach the relay itself, which does listen.
+ *   circuitRelayTransport — to be dialled through that reservation.
+ *   webRTC              — so that once two members have exchanged an offer
+ *                         over the circuit, the data goes directly and the
+ *                         hub stays a signalling channel.
+ *
+ * `tcp()` is absent because it cannot exist here, which is the whole reason
+ * this file is separate from `./node`.
+ */
+import { circuitRelayTransport } from "@libp2p/circuit-relay-v2";
+import { webRTC } from "@libp2p/webrtc";
+import { webSockets } from "@libp2p/websockets";
+/** Transports for a page. Fresh instances per call — libp2p's are not reusable. */
+export function browserTransports() {
+    return [
+        webSockets(),
+        circuitRelayTransport(),
+        webRTC(),
+    ];
+}
+/**
+ * A `BytesStore` in IndexedDB — where a page keeps its identity.
+ *
+ * NOT `localStorage`, and the difference matters: a key is bytes, and
+ * `localStorage` stores strings, so every read and write would go through a
+ * base64 round trip that can silently truncate. IndexedDB stores a
+ * `Uint8Array` as itself.
+ *
+ * Written against the raw IndexedDB API rather than a wrapper so this package
+ * keeps its single dependency. It is thirty lines and it never changes.
+ */
+export function idbBytesStore(name = "httpeers", store = "identity") {
+    const open = () => new Promise((resolve, reject) => {
+        const request = indexedDB.open(name, 1);
+        request.onupgradeneeded = () => {
+            if (!request.result.objectStoreNames.contains(store)) {
+                request.result.createObjectStore(store);
+            }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+    const run = async (mode, act) => {
+        const db = await open();
+        try {
+            return await new Promise((resolve, reject) => {
+                const request = act(db.transaction(store, mode).objectStore(store));
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error);
+            });
+        }
+        finally {
+            db.close();
+        }
+    };
+    return {
+        async get(key) {
+            const value = await run("readonly", (s) => s.get(key));
+            if (value === undefined)
+                return undefined;
+            return value instanceof Uint8Array ? value : new Uint8Array(value);
+        },
+        async set(key, value) {
+            await run("readwrite", (s) => s.put(value, key));
+        },
+        async delete(key) {
+            await run("readwrite", (s) => s.delete(key));
+        },
+    };
+}

package/dist/duplex.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 09 — the second altitude: duplex streams over the same mesh.
+ *
+ * WHY THIS EXISTS. `Handler = (Request) => Promise<Response>` cannot express a
+ * WebSocket, an A2UI message stream, or anything else where both ends keep
+ * talking. It never could: `fetch` is not the foundation of this stack but a
+ * NARROWING of it. `@statewalker/webrun-http-streams` builds fetch semantics on
+ * a `Duplex`, and `httpeers.core`'s transport performs that narrowing at two
+ * call sites. So adding duplex REMOVES a restriction rather than adding a
+ * layer — webrun-wire's ADR-0004 calls `Duplex` "the canonical adapter seam".
+ *
+ *   Duplex = (input: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array>
+ *
+ * THREE THINGS THIS FILE IS CAREFUL ABOUT:
+ *
+ *   1. IDENTITY IS AN ARGUMENT, NOT A LOOKUP. The fetch path carries the
+ *      proven peer in a `WeakMap<Request, …>` written inside the per-stream
+ *      closure. A duplex has no `Request` to key on, so `DuplexContext.peerId`
+ *      is passed to the handler. `serveConnections` gives us the only claim
+ *      that cannot be forged by the payload: `ConnectionContext.remotePeer`.
+ *   2. A SEPARATE PROTOCOL ID. `/httpeers-duplex/1.0.0` lives beside
+ *      `/httpeers/1.0.0`, so the fetch path is untouched and cannot regress.
+ *   3. THE OPEN FRAME IS THE EXISTING ENVELOPE. `encodeMessage`/`decodeMessage`
+ *      from webrun-http-streams — JSON line, then body bytes. Nothing new on
+ *      the wire.
+ */
+import type { Libp2p } from "@libp2p/interface";
+import type { Duplex } from "@statewalker/webrun-streams";
+export declare const DUPLEX_PROTOCOL = "/httpeers-duplex/1.0.0";
+/** What a duplex handler is told. The peer is an argument because there is no Request to key a map on. */
+export interface DuplexContext {
+    /** Proven by the Noise handshake. Never read from the payload. */
+    readonly peerId: string;
+    readonly path: string;
+    /** Whatever the caller put in the open frame. A CLAIM, never proof — see `peerId`. */
+    readonly token?: string;
+}
+export type DuplexHandler = (input: AsyncIterable<Uint8Array>, ctx: DuplexContext) => AsyncIterable<Uint8Array>;
+export interface DuplexMounts {
+    /** Longest-prefix on segment boundaries, like the fetch router. */
+    provide(prefix: string, handler: DuplexHandler): () => void;
+    match(path: string): {
+        handler: DuplexHandler;
+        prefix: string;
+    } | null;
+    list(): string[];
+}
+export declare function createDuplexMounts(): DuplexMounts;
+/** Thrown into the caller's stream when no mount claims the path. */
+export declare const NO_MOUNT = "httpeers-duplex: no mount for ";
+export interface ServeDuplexInit {
+    node: Libp2p;
+    mounts: DuplexMounts;
+    protocol?: string;
+    /** Left unset, libp2p's default (32) applies — the ceiling on concurrent inbound streams. */
+    maxInboundStreams?: number;
+    /** A relayed circuit is a limited connection; libp2p refuses this protocol on one unless told otherwise. */
+    runOnLimitedConnection?: boolean;
+}
+/** Register the duplex protocol. Returns the teardown `serveConnections` gives us. */
+export declare function serveDuplex(init: ServeDuplexInit): Promise<() => Promise<void>>;
+export interface OpenDuplexInit {
+    node: Libp2p;
+    peerId: string;
+    path: string;
+    token?: string;
+    protocol?: string;
+    runOnLimitedConnection?: boolean;
+}
+export interface PeerDuplex {
+    readonly peerId: string;
+    readonly path: string;
+    /** Feed it outbound bytes, iterate the inbound ones. */
+    readonly call: Duplex;
+    close(): Promise<void>;
+}
+/**
+ * Open a duplex stream to `(peerId, path)`.
+ *
+ * ADDRESSED BY A PAIR, NEVER BY A URL. A URL is the fetch layer's addressing
+ * scheme and a duplex stream has no request-line; reusing `peer://…` here
+ * would also re-open the URL-derived-peer hole the ghost's pin exists to
+ * close (`new URL("peer://a@b/x").host === "b"`, measured in rung 06).
+ */
+export declare function openDuplex(init: OpenDuplexInit): Promise<PeerDuplex>;
+//# sourceMappingURL=duplex.d.ts.map

package/dist/duplex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplex.d.ts","sourceRoot":"","sources":["../src/duplex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAO1D,eAAO,MAAM,eAAe,2BAA2B,CAAC;AAExD,0GAA0G;AAC1G,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,aAAa,GAAG,CAC1B,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,EAChC,GAAG,EAAE,aAAa,KACf,aAAa,CAAC,UAAU,CAAC,CAAC;AAE/B,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,IAAI,CAAC;IAC5D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACvE,IAAI,IAAI,MAAM,EAAE,CAAC;CAClB;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAuBjD;AAED,qEAAqE;AACrE,eAAO,MAAM,QAAQ,mCAAmC,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4GAA4G;IAC5G,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,sFAAsF;AACtF,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CA0BrF;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAmB1E"}

package/dist/duplex.js

@@ -0,0 +1,101 @@
+/**
+ * 09 — the second altitude: duplex streams over the same mesh.
+ *
+ * WHY THIS EXISTS. `Handler = (Request) => Promise<Response>` cannot express a
+ * WebSocket, an A2UI message stream, or anything else where both ends keep
+ * talking. It never could: `fetch` is not the foundation of this stack but a
+ * NARROWING of it. `@statewalker/webrun-http-streams` builds fetch semantics on
+ * a `Duplex`, and `httpeers.core`'s transport performs that narrowing at two
+ * call sites. So adding duplex REMOVES a restriction rather than adding a
+ * layer — webrun-wire's ADR-0004 calls `Duplex` "the canonical adapter seam".
+ *
+ *   Duplex = (input: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array>
+ *
+ * THREE THINGS THIS FILE IS CAREFUL ABOUT:
+ *
+ *   1. IDENTITY IS AN ARGUMENT, NOT A LOOKUP. The fetch path carries the
+ *      proven peer in a `WeakMap<Request, …>` written inside the per-stream
+ *      closure. A duplex has no `Request` to key on, so `DuplexContext.peerId`
+ *      is passed to the handler. `serveConnections` gives us the only claim
+ *      that cannot be forged by the payload: `ConnectionContext.remotePeer`.
+ *   2. A SEPARATE PROTOCOL ID. `/httpeers-duplex/1.0.0` lives beside
+ *      `/httpeers/1.0.0`, so the fetch path is untouched and cannot regress.
+ *   3. THE OPEN FRAME IS THE EXISTING ENVELOPE. `encodeMessage`/`decodeMessage`
+ *      from webrun-http-streams — JSON line, then body bytes. Nothing new on
+ *      the wire.
+ */
+import { peerIdFromString } from "@libp2p/peer-id";
+import { decodeMessage, encodeMessage } from "@statewalker/webrun-http-streams";
+import { connect, serveConnections, } from "@statewalker/webrun-streams-libp2p";
+export const DUPLEX_PROTOCOL = "/httpeers-duplex/1.0.0";
+export function createDuplexMounts() {
+    const table = [];
+    const norm = (p) => (p.endsWith("/") && p !== "/" ? p.slice(0, -1) : p);
+    return {
+        provide(prefix, handler) {
+            const entry = { prefix: norm(prefix), handler };
+            table.push(entry);
+            table.sort((a, b) => b.prefix.length - a.prefix.length);
+            return () => {
+                const at = table.indexOf(entry);
+                if (at >= 0)
+                    table.splice(at, 1);
+            };
+        },
+        match(path) {
+            const target = norm(path);
+            const hit = table.find((m) => m.prefix === "/" || target === m.prefix || target.startsWith(`${m.prefix}/`));
+            return hit == null ? null : { handler: hit.handler, prefix: hit.prefix };
+        },
+        list: () => table.map((m) => m.prefix),
+    };
+}
+/** Thrown into the caller's stream when no mount claims the path. */
+export const NO_MOUNT = "httpeers-duplex: no mount for ";
+/** Register the duplex protocol. Returns the teardown `serveConnections` gives us. */
+export async function serveDuplex(init) {
+    return await serveConnections({
+        node: init.node,
+        protocol: init.protocol ?? DUPLEX_PROTOCOL,
+        ...(init.maxInboundStreams == null ? {} : { maxInboundStreams: init.maxInboundStreams }),
+        ...(init.runOnLimitedConnection == null
+            ? {}
+            : { runOnLimitedConnection: init.runOnLimitedConnection }),
+    }, 
+    // Called ONCE PER INBOUND STREAM, which is what keeps the proven peer in
+    // the closure and out of the payload.
+    (context) => {
+        const peerId = context.remotePeer.toString();
+        return async function* (input) {
+            const { envelope, body } = await decodeMessage(input);
+            const found = init.mounts.match(envelope.path);
+            if (found == null)
+                throw new Error(`${NO_MOUNT}${envelope.path}`);
+            yield* found.handler(body, {
+                peerId,
+                path: envelope.path,
+                ...(envelope.token == null ? {} : { token: envelope.token }),
+            });
+        };
+    });
+}
+/**
+ * Open a duplex stream to `(peerId, path)`.
+ *
+ * ADDRESSED BY A PAIR, NEVER BY A URL. A URL is the fetch layer's addressing
+ * scheme and a duplex stream has no request-line; reusing `peer://…` here
+ * would also re-open the URL-derived-peer hole the ghost's pin exists to
+ * close (`new URL("peer://a@b/x").host === "b"`, measured in rung 06).
+ */
+export async function openDuplex(init) {
+    const conn = await connect({
+        node: init.node,
+        peer: peerIdFromString(init.peerId),
+        protocol: init.protocol ?? DUPLEX_PROTOCOL,
+        ...(init.runOnLimitedConnection == null
+            ? {}
+            : { runOnLimitedConnection: init.runOnLimitedConnection }),
+    });
+    const call = (input) => conn.call(encodeMessage({ path: init.path, ...(init.token == null ? {} : { token: init.token }) }, input));
+    return { peerId: init.peerId, path: init.path, call, close: conn.close };
+}

package/dist/hop-reserve.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Asking the RELAY whether this node is still reserved -- and renewing the
+ * reservation in the same breath.
+ *
+ * THE QUESTION THIS MODULE EXISTS TO ANSWER. `node.getMultiaddrs()` reports
+ * what the node's own transport reservation store believes, and in the
+ * 2026-09-19 incident that belief was wrong for hours: the relay held no
+ * reservation, the websocket was still up, every member got
+ * `NO_RESERVATION`, and the hub saw nothing to repair. The only authority on
+ * "is there a reservation" is the relay, so this asks it, over the wire.
+ *
+ * WHY NOT LIBP2P'S OWN CALL. `@libp2p/circuit-relay-v2`'s transport keeps a
+ * `ReservationStore` whose `addRelay(peer, type)` is the renewal entry point,
+ * and it is unusable as a probe for three separate reasons:
+ *
+ *   1. It SHORT-CIRCUITS. If it still holds an entry, the connection is open
+ *      and the recorded expiry is more than ten minutes away, it returns the
+ *      cached entry without sending a byte -- so a proactive call answers from
+ *      the very belief we are trying to check.
+ *   2. It is NOT REACHABLE. The store is a private component of the transport;
+ *      nothing on `Libp2p` exposes it.
+ *   3. Its failure paths are SURPRISING. A dial or protocol failure puts the
+ *      relay in a "previously invalid" cuckoo filter (`relayFilter`) so later
+ *      attempts are refused locally, and a discovered reservation can be
+ *      refused with `HadEnoughRelaysError` when no pending slot is free.
+ *
+ * So we speak HOP ourselves. A `RESERVE` request on the relay's own protocol
+ * is two bytes, and the answer is the relay's, not ours.
+ *
+ * IT REUSES THE SLOT, IT DOES NOT LEAK A SECOND ONE. The relay's reservation
+ * store is keyed by peer id: `reserve()` finds the existing entry, resets its
+ * expiry signal in place and returns OK (see `server/reservation-store.js` in
+ * the installed 4.2.11). A peer cannot hold two reservations on one relay, so
+ * "renew" and "re-reserve" are the same request -- which is also why this one
+ * call both DETECTS a loss and REPAIRS it.
+ *
+ * IT DOES NOT DISTURB LIVE CIRCUITS. It opens one short-lived stream on a
+ * connection that already exists; already-established circuits are separate
+ * connections and are untouched, and the relay's refresh path does not close
+ * anything.
+ *
+ * THE CODEC IS HAND-WRITTEN, four fields wide, because it has to be:
+ * `@libp2p/circuit-relay-v2` publishes only `.` in its `exports` map, so its
+ * generated `pb/index.js` cannot be imported, and vendoring protons to
+ * regenerate a message we send ONE variant of would be more code than this.
+ * The wire format is pinned by `tests/hop-reserve.test.ts` against bytes taken
+ * from that generated encoder, and end to end by `tests/reservation-renewal.test.ts`
+ * against a real relay -- which is the check that actually matters, since a
+ * codec that agrees only with its own tests proves nothing.
+ */
+import type { Libp2p } from "@libp2p/interface";
+/** circuit-relay v2 `Status`, by number. The relay answers one of these. */
+export declare const HOP_STATUS_NAMES: Readonly<Record<number, string>>;
+/** `Status.OK`. */
+export declare const HOP_STATUS_OK = 100;
+/** How long one RESERVE round trip may take, matching libp2p's own `DEFAULT_RESERVATION_COMPLETION_TIMEOUT`. */
+export declare const HOP_RESERVE_TIMEOUT_MS = 5000;
+/** What the relay granted. `expiresAt` is `null` when the relay sent no reservation body. */
+export interface RelayReservationGrant {
+    /** ms since the epoch, from the relay's own `Reservation.expire` (Unix seconds). */
+    expiresAt: number | null;
+    /** `expiresAt` minus now, at the moment the answer arrived. `null` when unknown. */
+    ttlMs: number | null;
+}
+/** The relay answered, and the answer was not OK. `status` is its own `Status` number. */
+export declare class RelayReservationRefusedError extends Error {
+    readonly relayPeerId: string;
+    readonly status: number;
+    constructor(relayPeerId: string, status: number);
+}
+/** There is no connection this node could ask the relay over. Not a refusal: nothing was asked. */
+export declare class RelayNotConnectedError extends Error {
+    readonly relayPeerId: string;
+    constructor(relayPeerId: string);
+}
+/** The subset of `HopMessage` this module reads. Everything else is skipped. */
+export interface HopAnswer {
+    /** `HopMessage.Type`: 0 RESERVE, 1 CONNECT, 2 STATUS. */
+    type?: number;
+    status?: number;
+    /** `Reservation.expire`, Unix SECONDS as the relay sent it. */
+    expire?: number;
+}
+/**
+ * Read the fields of a `HopMessage` this module needs, skipping the rest.
+ *
+ * Deliberately lenient about everything it does not use -- an unknown field,
+ * a voucher, a limit -- because a decoder that throws on a field a future
+ * relay adds would turn a healthy relay into a lost reservation.
+ */
+export declare function decodeHopAnswer(data: Uint8Array | {
+    subarray(): Uint8Array;
+}): HopAnswer;
+/**
+ * Request (or renew) this node's reservation on `relayPeerId`, and return what
+ * the relay granted. Throws `RelayReservationRefusedError` on any non-OK
+ * status, `RelayNotConnectedError` when there is nothing to ask over, and
+ * whatever the stream threw otherwise. Every one of those means "not reserved
+ * as far as the relay is concerned", which is the only judgement the caller
+ * needs.
+ */
+export declare function requestRelayReservation(node: Libp2p, relayPeerId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<RelayReservationGrant>;
+//# sourceMappingURL=hop-reserve.d.ts.map

package/dist/hop-reserve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hop-reserve.d.ts","sourceRoot":"","sources":["../src/hop-reserve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAGH,OAAO,KAAK,EAAc,MAAM,EAAU,MAAM,mBAAmB,CAAC;AAIpE,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7D,CAAC;AAEF,mBAAmB;AACnB,eAAO,MAAM,aAAa,MAAM,CAAC;AAYjC,gHAAgH;AAChH,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AAE5C,6FAA6F;AAC7F,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oFAAoF;IACpF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,0FAA0F;AAC1F,qBAAa,4BAA6B,SAAQ,KAAK;IAEnD,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM;IAFzB,YACW,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EAOxB;CACF;AAED,mGAAmG;AACnG,qBAAa,sBAAuB,SAAQ,KAAK;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM;IAAxC,YAAqB,WAAW,EAAE,MAAM,EAKvC;CACF;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG;IAAE,QAAQ,IAAI,UAAU,CAAA;CAAE,GAAG,SAAS,CAoBxF;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACrC,OAAO,CAAC,qBAAqB,CAAC,CA4BhC"}