@statewalker/httpeers-member 0.1.4

package/dist/join.js

@@ -0,0 +1,409 @@
+/**
+ * Joining the mesh: the `/webrtc` pre-dial, invitation redemption, the
+ * membership RESUME probe, and the two timers this runtime owns itself (the
+ * third -- circuit-relay's own reservation refresh -- is libp2p-managed;
+ * there is no code for it here, on purpose, see `startJoin`'s doc comment).
+ *
+ * THERE ARE TWO WAYS INTO A MESH, NOT ONE (Task 28). `redeemInvitation` is
+ * the first join and can only ever happen once per invitation -- the id is
+ * moved to `spentInvitationIds` on redemption and the spent check runs
+ * first, unconditionally (`../hub/hub-state.ts`). A page that persists its
+ * identity and reloads is therefore NOT making a first join: it is already
+ * a member, and redeeming again would fail `already-redeemed` forever.
+ * `resumeMembership` below is the other way in, and it needs no new hub
+ * route because the hub already has one that answers exactly this question
+ * -- see that function.
+ */
+import { peerIdFromString } from "@libp2p/peer-id";
+import { multiaddr } from "@multiformats/multiaddr";
+import { hubRoute, reachHub } from "@statewalker/httpeers-libp2p";
+import { peerRequest } from "./peer-request.js";
+/**
+ * Dial `${relayAddr}/p2p-circuit/webrtc/p2p/${peerId}` explicitly, BEFORE
+ * opening any protocol against `peerId` (design note's Step 2; applies to
+ * the hub exactly as it does to any other peer -- spec §7, the hub
+ * declares no listen address of its own).
+ *
+ * WHY THIS IS NOT OPTIONAL. libp2p's auto-dial may already hold a
+ * relay-only LIMITED connection to `peerId` -- reachable, but not upgraded
+ * to WebRTC -- from nothing more than address exchange via `identify`.
+ * libp2p SILENTLY refuses to open a custom protocol (`/httpeers/1.0.0`)
+ * over a limited connection: the dial simply never completes, with no
+ * error naming a limited connection as the cause. Explicitly dialling the
+ * full `/webrtc/p2p/...` address forces the WebRTC upgrade before any
+ * `peer.call` is attempted, so that failure mode never has a chance to
+ * occur.
+ */
+export async function preDialPeer(node, relayAddr, peerId) {
+    const target = multiaddr(`${relayAddr}/p2p-circuit/webrtc/p2p/${peerId}`);
+    await node.dial(target);
+}
+/**
+ * "Make sure this peer can be called" -- the function
+ * `../browser/edge-dispatch.ts`'s `ensureRoute` hook wants, and the piece
+ * that was missing for browser-to-browser calls entirely (Task 15; see that
+ * module's job 4 for the symptom and the diagnosis).
+ *
+ * ADDRESSES COME FROM THE MESH VIEW, WHICH IS THE CONTRACT
+ * `../browser/peer-runtime.ts`'s module comment already stated and nothing
+ * had yet had to honour: the hub builds each member's `addrs` from that
+ * member's own most recent heartbeat, so it is the freshest source there
+ * is, and libp2p's peerStore -- what `remote()` falls back on when it dials
+ * by bare peer id -- is exactly the stale/absent one that comment warns
+ * about.
+ *
+ * ONLY THE `/webrtc` ENTRIES ARE DIALED. The same view also carries bare
+ * `/p2p-circuit` addresses for every member; connecting over one of those
+ * produces a LIMITED connection, on which libp2p silently refuses to open
+ * `/httpeers/1.0.0` (`preDialPeer`'s own comment, and Task 14's test that
+ * pins the refusal). Dialing them would therefore "succeed" and leave the
+ * call to fail anyway.
+ *
+ * THE COMPOSED ADDRESS IS THE FALLBACK, NOT THE PRIMARY. `preDialPeer`'s
+ * `<relay>/p2p-circuit/webrtc/p2p/<peer>` is right whenever every peer
+ * reserves on the one relay `httpeers.json` names -- true of this
+ * deployment, and how the hub itself is reached at startup, since the hub
+ * is not a mesh MEMBER and so never appears in the view at all. It is the
+ * fallback rather than the rule because a peer that reserved on a different
+ * relay is reachable only at the address it reported.
+ *
+ * THE HUB ITSELF IS NEVER DIALED HERE. `hubRoute(hub, hub)` routes the hub
+ * through itself, which cannot work; and a member on the relay fallback holds
+ * only a limited circuit to the hub, so without this every edge call to the
+ * hub would pay a doomed dial -- up to libp2p's dial timeout -- first. The
+ * hub link is `startMember`'s and the keepalive's to keep.
+ *
+ * AN EXISTING UNLIMITED CONNECTION SHORT-CIRCUITS. This runs on every
+ * outbound mesh call, including every `<img src>` in a gallery; re-dialing
+ * a peer that is already connected would add a round trip per image.
+ */
+export function createRouteEnsurer(init) {
+    const { node, relayAddr, selfPeerId } = init;
+    return async function ensureRoute(peerId) {
+        if (peerId === selfPeerId || peerId === init.hubPeerId)
+            return;
+        let target;
+        try {
+            target = peerIdFromString(peerId);
+        }
+        catch {
+            // Not a peer id after all (the shape test in `edge-dispatch.ts` is a
+            // regex, not a decoder). Nothing to dial; let the router decide what
+            // this path means.
+            return;
+        }
+        if (node.getConnections(target).some((conn) => conn.limits == null))
+            return;
+        if (init.hubPeerId != null && init.hubPeerId !== selfPeerId) {
+            await node.dial(multiaddr(hubRoute(init.hubPeerId, peerId)));
+            return;
+        }
+        const advertised = (init.meshView()?.members.find((m) => m.peerId === peerId)?.addrs ?? [])
+            .filter((addr) => addr.includes("/p2p-circuit") && addr.includes("/webrtc"))
+            .map((addr) => multiaddr(addr));
+        // Every candidate in ONE dial, not a loop: libp2p ranks and races the
+        // addresses of a single peer itself, and a sequential loop would pay the
+        // full dial timeout for each unreachable interface address the provider
+        // reported (a browser peer behind a relay routinely reports several).
+        if (advertised.length > 0)
+            await node.dial(advertised);
+        else
+            await preDialPeer(node, relayAddr, peerId);
+    };
+}
+/** Redeem `invitationId` against the hub -- `POST /.well-known/invite`, `../hub/endpoints.ts`'s bootstrap handler. No token exists yet: this call is proven by the transport handshake alone. */
+export async function redeemInvitation(peer, hubPeerId, invitationId) {
+    const res = await peer.call(hubPeerId, peerRequest("/.well-known/invite", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ id: invitationId }),
+    }));
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`join: invitation redemption failed (${res.status} ${res.statusText}): ${body}`);
+    }
+    return (await res.json());
+}
+/** Turn a refused presence response into one of the three cases above. Pure, so a test can pin the mapping without a hub. */
+export function classifyPresenceRefusal(status, body) {
+    if (status === 403) {
+        return {
+            kind: "not-a-member",
+            status,
+            message: "this hub does not list this peer as a member",
+        };
+    }
+    if (status === 409) {
+        return {
+            kind: "duplicate-identity",
+            status,
+            message: "the hub has already accepted a newer heartbeat for this peer id",
+        };
+    }
+    return { kind: "refused", status, message: body === "" ? `HTTP ${status}` : body };
+}
+/**
+ * The sequence number a fresh run starts from: THE WALL CLOCK, not zero.
+ *
+ * THIS IS NOT A STYLE CHOICE, IT IS WHAT MAKES RESUMING POSSIBLE AT ALL.
+ * The hub keeps `lastSeqByPeer` for the life of the process and refuses any
+ * presence write at or below it (`../hub/endpoints.ts`). A page that
+ * persists its identity and starts counting from 1 again after a reload
+ * would be refused `stale-sequence` on every beat until it had climbed back
+ * past wherever its previous run left off -- minutes of a live, joined page
+ * silently failing to report presence, and a mesh view in which it never
+ * appears. Seeding from `Date.now()` makes every run start above every
+ * previous run's numbers by construction (a run advances its own counter by
+ * 1 per beat while the clock advances by thousands), which is also exactly
+ * the property `PresenceRefusal`'s duplicate-identity diagnosis rests on.
+ *
+ * The hub compares numbers and nothing else -- it never reads a seq as a
+ * time -- so this borrows the clock's monotonicity without giving the value
+ * any meaning it has to keep.
+ */
+export function nextInitialSeq() {
+    return Date.now();
+}
+/**
+ * "Does this hub still consider me a member?" -- asked, and answered,
+ * WITHOUT A TOKEN, and answered by an endpoint that already exists.
+ *
+ * THE ORDERING TRAP THIS WALKS AROUND. Proving membership normally needs a
+ * token, and a token is what joining produces; a page resuming a membership
+ * has neither, and every ordinary hub read (`/.well-known/mesh` included)
+ * is gated on claims it cannot yet present. But `POST
+ * /.well-known/presence` is one of exactly two BOOTSTRAP routes
+ * (`usesTransportIdentity()` in `../hub/endpoints.ts`): `httpeers.core`'s
+ * binding middleware sees it, skips the token check and the access tree
+ * entirely, and hands the handler the peer id the libp2p handshake itself
+ * proved. That handler then looks the peer up in the member store and
+ * either mints a fresh token or answers 403. Which is precisely the
+ * question, precisely the proof, and precisely the credential -- so this
+ * needs no new route, and adding one would have been adding a second,
+ * weaker answer to a question the hub already answers.
+ *
+ * IT IS ALSO THE FIRST HEARTBEAT, NOT A PROBE BESIDE ONE. The body is an
+ * ordinary presence write, so a successful resume has already reported this
+ * peer's addresses and advertisements and is already visible in the mesh
+ * view -- there is no window where the page is "resumed" but absent. Its
+ * `seq` is the one `startJoin` continues from (`JoinInit.initialSeq`).
+ *
+ * Transport failures are NOT caught here: a call that never reached the hub
+ * is a different fact from a hub that answered, and only the caller knows
+ * what to say about it (`./peer-runtime.ts` does).
+ */
+export async function resumeMembership(init) {
+    const res = await init.peer.call(init.hubPeerId, peerRequest("/.well-known/presence", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            seq: init.seq,
+            addrs: init.addrs,
+            ...(init.advertisements !== undefined ? { advertisements: init.advertisements } : {}),
+        }),
+    }));
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        return { status: "refused", refusal: classifyPresenceRefusal(res.status, body) };
+    }
+    const parsed = (await res.json());
+    return { status: "resumed", token: parsed.token, versions: parsed.versions, ttl: parsed.ttl };
+}
+/** How often the presence heartbeat fires -- design note's Step 3, 5 s. */
+export const HEARTBEAT_INTERVAL_MS = 5_000;
+/**
+ * How often the connection-keepalive timer checks the link to the hub.
+ * DELIBERATELY SEPARATE from `HEARTBEAT_INTERVAL_MS`: a heartbeat that
+ * fails to send says "the request failed," which could be the connection,
+ * the hub, or a revoked membership -- it does not by itself diagnose
+ * "the underlying libp2p connection to the hub is gone." This timer
+ * checks that fact directly (`node.getConnections(hubPeerId)`) and
+ * re-runs the `/webrtc` pre-dial when it finds nothing open, independent
+ * of whether a heartbeat happens to be in flight at the same moment.
+ * Matches the interval the validated p2p-demo prototype uses for the same
+ * purpose (`workspaces/webrun-wire/apps/p2p-demo/server-page/main.ts`,
+ * "relay link lost; re-dialing").
+ */
+export const KEEPALIVE_INTERVAL_MS = 10_000;
+/**
+ * How long a pulled revocation snapshot may go unconfirmed before this
+ * peer refuses every token rather than trust one it can no longer vouch
+ * for (`RevocationCache`'s own `maxStalenessMs` -- "there is a case that
+ * no default is correct and this should be required," `revocation.ts`).
+ * Generous relative to `HEARTBEAT_INTERVAL_MS` deliberately: the cache's
+ * freshness clock is reset on EVERY successful heartbeat (see
+ * `startJoin` below), not only when `versions.policy` actually moves, so
+ * this bound is really "how many consecutive heartbeats may fail before
+ * this peer stops trusting its own revocation snapshot," not "how often
+ * the policy must change." Twelve missed 5 s heartbeats' worth of
+ * tolerance before a live peer starts refusing tokens on staleness alone.
+ */
+export const REVOCATION_MAX_STALENESS_MS = 60_000;
+/**
+ * Start the presence heartbeat and the connection-keepalive timer over an
+ * already-joined peer (post `redeemInvitation`). Fires an immediate
+ * heartbeat rather than waiting for the first interval tick, so a caller
+ * observing `meshView()` sees a populated view as soon as the network
+ * allows rather than up to `heartbeatIntervalMs` later.
+ *
+ * THREE TIMERS, KEPT APART (design note's Step 3 / note 07 §6). This
+ * function owns two of them -- the heartbeat and the keepalive, below.
+ * THE THIRD, the reservation on the relay, is NOT started here either:
+ * libp2p renews a reservation it holds on its own schedule, and restoring
+ * one lost with the relay link -- which libp2p attempts once and then never
+ * again -- is `../reservation.ts`'s `superviseRelay`, started by the
+ * runtime. The keepalive below is NOT that: it watches the HUB connection,
+ * which can stay up over WebRTC after the relay link is gone. Folding
+ * either into these two would conflate "is my reservation still valid"
+ * with "does the hub still consider me a member" or "is my connection to
+ * the hub still open" -- three questions this design keeps separate
+ * because they fail independently and mean different things.
+ */
+export function startJoin(init) {
+    const { peer, node, hubPeerId, relayAddr, revocationCache } = init;
+    const heartbeatIntervalMs = init.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+    const keepaliveIntervalMs = init.keepaliveIntervalMs ?? KEEPALIVE_INTERVAL_MS;
+    let token = init.initialToken;
+    let seq = init.initialSeq ?? nextInitialSeq();
+    let heartbeatInFlight = false;
+    let meshViewCache = null;
+    let meshVersion = 0;
+    let rulesCache = null;
+    let rulesVersion = 0;
+    let revocationEntriesCache = [];
+    async function heartbeatOnce() {
+        if (heartbeatInFlight)
+            return; // never overlap two in-flight heartbeats -- see the module comment on why this is safe to just skip a tick rather than queue.
+        heartbeatInFlight = true;
+        // EVERYTHING BELOW IS INSIDE ONE try/catch, DELIBERATELY -- not only
+        // the presence call. `heartbeatOnce` is invoked as `void
+        // heartbeatOnce()` (fire-and-forget, on a `setInterval`), so ANY
+        // rejection that escapes it -- a dropped connection mid-call, a
+        // malformed JSON body from the hub, a follow-up GET failing after the
+        // presence POST already succeeded -- becomes an unhandled promise
+        // rejection, not the "next tick retries" behaviour the rest of this
+        // function's comments describe. A single catch-all below is what
+        // actually delivers that contract; catching only the first call and
+        // leaving the rest unprotected (an earlier version of this function)
+        // does not (found on review; reproduced by forcing an unconditional
+        // refetch and watching a follow-up call's rejection escape uncaught).
+        try {
+            seq += 1;
+            // THE PEER'S OWN CURRENT MULTIADDRS -- `node.getMultiaddrs()`, read
+            // fresh on every heartbeat. This is what makes THIS peer's own
+            // addresses the freshest possible source for OTHER peers reading
+            // them back out of the mesh view -- see `JoinHandle.meshView`'s doc
+            // comment and `peer-runtime.ts`'s module comment for the other half
+            // of this contract (never read a PEER's addrs from libp2p's own
+            // `peerStore`).
+            const addrs = node.getMultiaddrs().map((addr) => addr.toString());
+            const advertisements = init.advertisements?.() ?? [];
+            const res = await peer.call(hubPeerId, peerRequest("/.well-known/presence", {
+                method: "POST",
+                token,
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ seq, addrs, advertisements }),
+            }));
+            if (!res.ok) {
+                // A refusal is not a transport fault and must not be swallowed with
+                // one: 403 means this peer is no longer a member (revoked, or the
+                // hub's state was reset) and 409 means a SECOND node is beating
+                // under this identity. Both are permanent until someone acts, so a
+                // page that only stopped advancing its caches would sit there
+                // looking joined. Every cache is still left exactly as it was --
+                // that part was always right.
+                init.onPresenceRefused?.(classifyPresenceRefusal(res.status, await res.text().catch(() => "")));
+                return;
+            }
+            const body = (await res.json());
+            token = body.token; // rotates every heartbeat -- the hub mints a fresh token on each call.
+            if (body.versions.mesh !== meshVersion) {
+                const meshRes = await peer.call(hubPeerId, peerRequest("/.well-known/mesh", { method: "GET", token }));
+                if (meshRes.ok) {
+                    meshViewCache = (await meshRes.json());
+                    meshVersion = body.versions.mesh;
+                }
+            }
+            if (body.versions.rules !== rulesVersion) {
+                const rulesRes = await peer.call(hubPeerId, peerRequest("/.well-known/rules", {
+                    method: "GET",
+                    token,
+                }));
+                if (rulesRes.ok) {
+                    rulesCache = (await rulesRes.json());
+                    rulesVersion = body.versions.rules;
+                }
+            }
+            if (body.versions.policy !== revocationCache.knownVersion()) {
+                const revRes = await peer.call(hubPeerId, peerRequest("/.well-known/revocations", {
+                    method: "GET",
+                    token,
+                }));
+                if (revRes.ok) {
+                    const revBody = (await revRes.json());
+                    revocationEntriesCache = revBody.entries;
+                }
+            }
+            // Refresh the cache's freshness stamp on EVERY successful heartbeat
+            // -- see `REVOCATION_MAX_STALENESS_MS`'s doc comment for why this is
+            // NOT gated on the policy version having actually moved.
+            revocationCache.update(body.versions.policy, revocationEntriesCache);
+            init.onHeartbeat?.(body.versions);
+        }
+        catch {
+            // Dial/transport failure, a malformed response body, or any other
+            // fault anywhere in the sequence above -- leave every cached value
+            // exactly as it was; the next tick retries from scratch.
+            // `KEEPALIVE_INTERVAL_MS`'s timer is what actually diagnoses and
+            // repairs a dropped connection to the hub; this heartbeat has no
+            // business doing that job too, only refusing to crash the page over
+            // it.
+        }
+        finally {
+            heartbeatInFlight = false;
+        }
+    }
+    const heartbeatTimer = setInterval(() => void heartbeatOnce(), heartbeatIntervalMs);
+    void heartbeatOnce();
+    let hubPeerIdObj;
+    try {
+        hubPeerIdObj = peerIdFromString(hubPeerId);
+    }
+    catch {
+        hubPeerIdObj = undefined; // malformed hubPeerId -- the keepalive timer below simply never finds a match and keeps re-predialling, which is the correct degraded behaviour.
+    }
+    // `reachHub`, not a bare pre-dial: it also closes the limited signalling
+    // circuit, which would otherwise break relaying THROUGH the hub (and so
+    // restoring this page's reservation on it) -- see `../hub-link.ts`.
+    const relinkHub = init.relinkHub ?? (() => reachHub(node, relayAddr, hubPeerId));
+    // One re-link at a time: a dial can outlast a tick, and two overlapping
+    // attempts would open two connections.
+    let relinking = false;
+    // A KEPT LIMITED CIRCUIT COUNTS AS OPEN, so a member on the relay fallback is
+    // left alone for as long as its circuit lives -- nothing here closes or
+    // replaces it -- and re-links only once it has gone.
+    const keepaliveTimer = setInterval(() => {
+        const stillOpen = hubPeerIdObj != null && node.getConnections(hubPeerIdObj).some((c) => c.status === "open");
+        if (stillOpen || relinking)
+            return;
+        relinking = true;
+        void relinkHub()
+            .catch(() => {
+            // Best-effort -- the next tick retries, and a heartbeat that keeps
+            // failing on its own schedule surfaces the same underlying
+            // unreachability independently.
+        })
+            .finally(() => {
+            relinking = false;
+        });
+    }, keepaliveIntervalMs);
+    return {
+        meshView: () => meshViewCache,
+        rules: () => rulesCache,
+        token: () => token, // read at call time, never snapshotted -- see `JoinHandle.token`.
+        stop() {
+            clearInterval(heartbeatTimer);
+            clearInterval(keepaliveTimer);
+        },
+    };
+}

package/dist/kv.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The key-value seams a member stores things behind — the SHAPES only.
+ *
+ * The IndexedDB implementations moved to `./browser.js`. They import
+ * `idb-keyval`, which needs a real IndexedDB, and a Node member reading its
+ * own identity has no business pulling a browser database into its bundle to
+ * do it. What is left here is what both platforms genuinely share: two
+ * interfaces, and nothing that can run.
+ */
+export interface AsyncKeyValueBackend {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface AsyncBytesBackend {
+    get(key: string): Promise<Uint8Array | undefined>;
+    set(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+//# sourceMappingURL=kv.d.ts.map

package/dist/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../src/kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAClD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC"}

package/dist/kv.js

@@ -0,0 +1,10 @@
+/**
+ * The key-value seams a member stores things behind — the SHAPES only.
+ *
+ * The IndexedDB implementations moved to `./browser.js`. They import
+ * `idb-keyval`, which needs a real IndexedDB, and a Node member reading its
+ * own identity has no business pulling a browser database into its bundle to
+ * do it. What is left here is what both platforms genuinely share: two
+ * interfaces, and nothing that can run.
+ */
+export {};

package/dist/mesh-config.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one place a `MeshConfig` is validated, whatever channel it arrived on.
+ *
+ * Two channels exist and both used to check differently: `mesh-memory.ts`
+ * validated what it read from storage, and `session.ts` CAST what it fetched
+ * over HTTP (`return (await res.json()) as HttpeersConfig`). A cast checks
+ * nothing, and the gap showed up as soon as the hub moved into a tab: a
+ * hub-page deployment has no stable `hubPeerId` to publish, so its
+ * `httpeers.json` carries `relayAddrs` alone, and that config reached
+ * `startMember` with `hubPeerId: undefined` — failing far from the cause.
+ *
+ * `null` FOR ANYTHING UNUSABLE, never a throw. The session already renders
+ * `null` correctly ("no mesh to join — paste an invitation"), which is exactly
+ * the state a hub-page deployment starts every other page in. Throwing would
+ * take out the page, including the invitation field that fixes it.
+ */
+import type { MeshConfig } from "@statewalker/httpeers-core";
+/**
+ * A usable `MeshConfig`, or `null`.
+ *
+ * Returns a FRESH object carrying only the two known fields: a deployment may
+ * publish more, and passing unknown keys through would let an unrelated one
+ * look like configuration this library honours.
+ */
+export declare function parseMeshConfig(value: unknown): MeshConfig | null;
+//# sourceMappingURL=mesh-config.d.ts.map

package/dist/mesh-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-config.d.ts","sourceRoot":"","sources":["../src/mesh-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAcjE"}

package/dist/mesh-config.js

@@ -0,0 +1,39 @@
+/**
+ * The one place a `MeshConfig` is validated, whatever channel it arrived on.
+ *
+ * Two channels exist and both used to check differently: `mesh-memory.ts`
+ * validated what it read from storage, and `session.ts` CAST what it fetched
+ * over HTTP (`return (await res.json()) as HttpeersConfig`). A cast checks
+ * nothing, and the gap showed up as soon as the hub moved into a tab: a
+ * hub-page deployment has no stable `hubPeerId` to publish, so its
+ * `httpeers.json` carries `relayAddrs` alone, and that config reached
+ * `startMember` with `hubPeerId: undefined` — failing far from the cause.
+ *
+ * `null` FOR ANYTHING UNUSABLE, never a throw. The session already renders
+ * `null` correctly ("no mesh to join — paste an invitation"), which is exactly
+ * the state a hub-page deployment starts every other page in. Throwing would
+ * take out the page, including the invitation field that fixes it.
+ */
+/**
+ * A usable `MeshConfig`, or `null`.
+ *
+ * Returns a FRESH object carrying only the two known fields: a deployment may
+ * publish more, and passing unknown keys through would let an unrelated one
+ * look like configuration this library honours.
+ */
+export function parseMeshConfig(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const { relayAddrs, hubPeerId } = value;
+    // A relay list that is empty is not a mesh: `startMember` reads
+    // `relayAddrs[0]` and has nothing to dial.
+    if (!Array.isArray(relayAddrs) || relayAddrs.length === 0)
+        return null;
+    if (!relayAddrs.every((addr) => typeof addr === "string" && addr !== ""))
+        return null;
+    // The hub's peerId IS the mesh's name — every token's `mesh` claim restates
+    // it — so a config without one names no mesh at all.
+    if (typeof hubPeerId !== "string" || hubPeerId === "")
+        return null;
+    return { relayAddrs, hubPeerId };
+}

package/dist/mesh-memory.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The mesh this origin last joined -- `{ relayAddrs, hubPeerId }`, kept
+ * beside the identity key it belongs to.
+ *
+ * WHY A PAGE HAS TO REMEMBER THIS AT ALL (Task 28). A page that resumes a
+ * membership needs two things: the identity that holds it
+ * (`./identity.ts`) and the mesh that granted it. The first has persisted
+ * since Task 24. The second has not, and for the Node hub it did not need
+ * to -- `httpeers.json` names that mesh on every origin, forever. For a
+ * mesh whose hub is a BROWSER PAGE it does need to: that hub's peerId
+ * exists only in a tab's IndexedDB and reaches other pages exactly once, in
+ * the join blob that admitted them (`./join-blob.ts`). Reload such a page
+ * without its `?join=` query and it holds a membership in a mesh it can no
+ * longer name. This module is that missing half -- and it is genuinely only
+ * a memory: nothing here is a credential, and every field in it was
+ * published in the blob anyway.
+ *
+ * WHAT IT DOES NOT CHANGE: WHAT A BARE INVITATION ID MEANS. `./join-blob.ts`
+ * is explicit that a `?invite=` id with no blob means "the mesh
+ * `httpeers.json` names", i.e. the Node hub's -- both deployments are
+ * supported deliberately. So this memory is consulted ONLY when resuming
+ * (no invitation in hand). The moment someone supplies an invitation, the
+ * invitation decides: a blob names its own mesh, and a bare id still means
+ * the deployment's. Reversing that would have silently pointed the Node-hub
+ * path at whatever mesh the page had last seen. See `./session.ts`, which
+ * is where the two rules meet.
+ *
+ * WRITTEN ONLY AFTER A JOIN ACTUALLY SUCCEEDS. A remembered mesh that was
+ * never reachable would turn one failed paste into a page that keeps
+ * failing the same way on every later load, with the operator's original
+ * mistake no longer visible anywhere.
+ */
+import type { MeshConfig as HttpeersConfig } from "@statewalker/httpeers-core";
+import type { AsyncKeyValueBackend } from "./kv.js";
+/** Where the remembered mesh lives, namespaced like `./identity.ts`'s key and `./snapshot-store.ts`'s snapshot. */
+export declare const MESH_STORAGE_KEY = "httpeers:mesh";
+export interface MeshMemory {
+    /** The mesh this origin last joined, or `null` -- also `null` when the stored value is unreadable; see `parseMesh`. */
+    read(): Promise<HttpeersConfig | null>;
+    write(config: HttpeersConfig): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface CreateMeshMemoryInit {
+    /**
+     * Where this lives. REQUIRED, and deliberately so: it used to default to
+     * IndexedDB, which put a browser database in the default path of a module
+     * that a Node member also imports. The platform supplies its own store —
+     * `./browser`'s for a page, a file-backed one for a process.
+     */
+    backend: AsyncKeyValueBackend;
+    /** Defaults to `MESH_STORAGE_KEY`. */
+    storageKey?: string;
+}
+export declare function createMeshMemory(init: CreateMeshMemoryInit): MeshMemory;
+//# sourceMappingURL=mesh-memory.d.ts.map

package/dist/mesh-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-memory.d.ts","sourceRoot":"","sources":["../src/mesh-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,OAAO,KAAK,EAAE,UAAU,IAAI,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAGpD,mHAAmH;AACnH,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,uHAAuH;IACvH,IAAI,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACvC,KAAK,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,OAAO,EAAE,oBAAoB,CAAC;IAC9B,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA4BD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,UAAU,CAevE"}

package/dist/mesh-memory.js

@@ -0,0 +1,74 @@
+/**
+ * The mesh this origin last joined -- `{ relayAddrs, hubPeerId }`, kept
+ * beside the identity key it belongs to.
+ *
+ * WHY A PAGE HAS TO REMEMBER THIS AT ALL (Task 28). A page that resumes a
+ * membership needs two things: the identity that holds it
+ * (`./identity.ts`) and the mesh that granted it. The first has persisted
+ * since Task 24. The second has not, and for the Node hub it did not need
+ * to -- `httpeers.json` names that mesh on every origin, forever. For a
+ * mesh whose hub is a BROWSER PAGE it does need to: that hub's peerId
+ * exists only in a tab's IndexedDB and reaches other pages exactly once, in
+ * the join blob that admitted them (`./join-blob.ts`). Reload such a page
+ * without its `?join=` query and it holds a membership in a mesh it can no
+ * longer name. This module is that missing half -- and it is genuinely only
+ * a memory: nothing here is a credential, and every field in it was
+ * published in the blob anyway.
+ *
+ * WHAT IT DOES NOT CHANGE: WHAT A BARE INVITATION ID MEANS. `./join-blob.ts`
+ * is explicit that a `?invite=` id with no blob means "the mesh
+ * `httpeers.json` names", i.e. the Node hub's -- both deployments are
+ * supported deliberately. So this memory is consulted ONLY when resuming
+ * (no invitation in hand). The moment someone supplies an invitation, the
+ * invitation decides: a blob names its own mesh, and a bare id still means
+ * the deployment's. Reversing that would have silently pointed the Node-hub
+ * path at whatever mesh the page had last seen. See `./session.ts`, which
+ * is where the two rules meet.
+ *
+ * WRITTEN ONLY AFTER A JOIN ACTUALLY SUCCEEDS. A remembered mesh that was
+ * never reachable would turn one failed paste into a page that keeps
+ * failing the same way on every later load, with the operator's original
+ * mistake no longer visible anywhere.
+ */
+import { parseMeshConfig } from "./mesh-config.js";
+/** Where the remembered mesh lives, namespaced like `./identity.ts`'s key and `./snapshot-store.ts`'s snapshot. */
+export const MESH_STORAGE_KEY = "httpeers:mesh";
+/**
+ * Validate rather than trust, and return `null` rather than throw.
+ *
+ * The same tolerance `./snapshot-store.ts` applies to a corrupt snapshot,
+ * for the same reason and with a smaller cost: a page whose remembered mesh
+ * is unreadable has simply not got one, which is the first-run state it
+ * already knows how to render (say so, offer the invitation field). Throwing
+ * would take out the page -- including the reset control -- over a value
+ * that is a convenience.
+ */
+function parseMesh(raw) {
+    if (raw == null)
+        return null;
+    try {
+        // The SAME validator the HTTP channel uses. It was a second copy here,
+        // which is how the two channels came to disagree in the first place.
+        return parseMeshConfig(JSON.parse(raw));
+    }
+    catch (err) {
+        console.warn(`mesh-memory: the stored mesh at "${MESH_STORAGE_KEY}" is not readable JSON -- this page ` +
+            "will ask for an invitation instead of resuming.", err);
+        return null;
+    }
+}
+export function createMeshMemory(init) {
+    const backend = init.backend;
+    const storageKey = init.storageKey ?? MESH_STORAGE_KEY;
+    return {
+        async read() {
+            return parseMesh(await backend.get(storageKey));
+        },
+        async write(config) {
+            await backend.set(storageKey, JSON.stringify(config));
+        },
+        async clear() {
+            await backend.delete(storageKey);
+        },
+    };
+}