@statewalker/httpeers-member 0.1.4

package/src/mesh-config.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 function parseMeshConfig(value: unknown): MeshConfig | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const { relayAddrs, hubPeerId } = value as Partial<MeshConfig>;
+
+  // 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/src/mesh-memory.ts

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ */
+
+// `MeshConfig` in `httpeers-core` — the shape `httpeers.json` has. It was
+// `HttpeersConfig`, declared in the browser peer assembly, which meant a Node
+// member had to import a browser module to name the file it reads.
+import type { MeshConfig as HttpeersConfig } from "@statewalker/httpeers-core";
+import type { AsyncKeyValueBackend } from "./kv.js";
+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";
+
+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;
+}
+
+/**
+ * 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: string | undefined): HttpeersConfig | null {
+  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: CreateMeshMemoryInit): MeshMemory {
+  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);
+    },
+  };
+}

package/src/node.ts

@@ -0,0 +1,49 @@
+/**
+ * The NODE half of `MemberPlatform` — the counterpart to
+ * `./browser-profile.ts`'s `createBrowserNode`.
+ *
+ * WHAT DIFFERS FROM THE BROWSER PROFILE, AND WHAT DELIBERATELY DOES NOT:
+ *
+ *   - `tcp()` is added. It is the one transport a page cannot have and the
+ *     one a Node member wants, for the direct member-to-member hop a page
+ *     makes over WebRTC instead.
+ *   - The LISTEN ADDRESSES ARE THE SAME — `/p2p-circuit` and `/webrtc`,
+ *     plus a loopback TCP port. If a Node member listened differently it
+ *     would reserve somewhere else, and the rung would be testing a
+ *     different design rather than the same one on another platform.
+ *   - The connection gater is permissive, which the browser profile also
+ *     does for loopback and private addresses (`dialNeedsPermissiveGater`).
+ *     Node has no browser default to relax, so this is the same policy
+ *     arrived at from the other side.
+ *   - There is no `mountEdge`: `MemberHandle.fetch` is the edge under Node.
+ *   - There is no `watchWake`: a Node process gets no wake events, so the
+ *     supervisor's backstop timer is the whole story.
+ */
+
+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 { tcp } from "@libp2p/tcp";
+import { webRTC } from "@libp2p/webrtc";
+import { webSockets } from "@libp2p/websockets";
+import { createLibp2p } from "libp2p";
+import type { MemberPlatform } from "./start-member.js";
+
+export async function createNodeMemberNode(init: {
+  privateKey?: Ed25519PrivateKey;
+}): Promise<Libp2p> {
+  return createLibp2p({
+    ...(init.privateKey != null ? { privateKey: init.privateKey } : {}),
+    addresses: { listen: ["/ip4/127.0.0.1/tcp/0", "/p2p-circuit", "/webrtc"] },
+    transports: [webSockets(), circuitRelayTransport(), webRTC(), tcp()],
+    connectionEncrypters: [noise()],
+    streamMuxers: [yamux()],
+    connectionGater: { denyDialMultiaddr: async () => false },
+    services: { identify: identify() },
+  });
+}
+
+/** The whole Node platform: a node factory, and nothing else. */
+export const nodePlatform: MemberPlatform = { createNode: createNodeMemberNode };

package/src/page-wake.ts

@@ -0,0 +1,59 @@
+/**
+ * The page events that mean "the relay link may have died while nothing was
+ * watching, and may be reachable again now" -- turned into one callback.
+ */
+
+/** The parts of `window` this reads. */
+export type WakeWindow = Pick<EventTarget, "addEventListener" | "removeEventListener">;
+
+/** The parts of `document` this reads. */
+export type WakeDocument = Pick<EventTarget, "addEventListener" | "removeEventListener"> & {
+  readonly visibilityState: string;
+};
+
+export interface WatchPageWakeInit {
+  win?: WakeWindow;
+  doc?: WakeDocument;
+}
+
+/**
+ * The two browser globals this file names, declared LOCALLY rather than by
+ * adding "dom" to the package's `lib`.
+ *
+ * Same technique and same reason as `httpeers-libp2p/src/browser.ts`'s
+ * `indexedDB`: one browser-only module must not put `window` and `document`
+ * in scope for every Node module beside it, where naming them is a bug the
+ * compiler should catch. The types are the two `Pick`s above, so the
+ * declaration also states exactly how much of each global is used.
+ */
+declare const window: WakeWindow;
+declare const document: WakeDocument;
+
+/**
+ * Call `onWake` whenever the page comes back; returns the unsubscribe.
+ *
+ * Why these events, and not a timer: a suspended page's timers are
+ * throttled or stopped, so the relay supervisor's own backoff may not fire
+ * for minutes after the page is usable again. See
+ * `tests/browser-page-wake.test.ts` for what each event means.
+ */
+export function watchPageWake(onWake: () => void, init: WatchPageWakeInit = {}): () => void {
+  const win = init.win ?? window;
+  const doc = init.doc ?? document;
+  const wake = (): void => onWake();
+  const onVisibility = (): void => {
+    if (doc.visibilityState === "visible") onWake();
+  };
+
+  win.addEventListener("online", wake);
+  win.addEventListener("pageshow", wake);
+  doc.addEventListener("resume", wake);
+  doc.addEventListener("visibilitychange", onVisibility);
+
+  return () => {
+    win.removeEventListener("online", wake);
+    win.removeEventListener("pageshow", wake);
+    doc.removeEventListener("resume", wake);
+    doc.removeEventListener("visibilitychange", onVisibility);
+  };
+}

package/src/peer-request.ts

@@ -0,0 +1,39 @@
+import { setMeshToken } from "@statewalker/httpeers-core";
+
+/**
+ * A `Request` addressed at a mesh path.
+ *
+ * `Peer.call(peerId, request)` takes a whole `Request`, because that is the
+ * contract every other seam in this system speaks — the prototype's peer took
+ * `(peerId, path, init)` instead, which meant it owned a second, narrower idea
+ * of what a call is and could not carry anything a `Request` can (a stream, an
+ * `AbortSignal`, a `Headers` instance a caller already had).
+ *
+ * The origin is a placeholder and is never dialled: the far side routes on the
+ * pathname alone. It is spelled `peer.local` rather than `localhost` so that a
+ * stray log line cannot be mistaken for a loopback request that really went out.
+ */
+export interface PeerRequestInit extends RequestInit {
+  /**
+   * A membership token, placed in `MESH_TOKEN_HEADER` -- never
+   * `Authorization`, which stays the caller's to use for the application it
+   * is calling.
+   *
+   * The prototype's `peer.call` took this as its own option and built the
+   * header internally. Keeping it here rather than making every call site
+   * write the header keeps those sites reading as intent — and keeps ONE
+   * place that decides the scheme, which is what a token's format being
+   * changed later will want.
+   */
+  token?: string;
+}
+
+export function peerRequest(path: string, init: PeerRequestInit = {}): Request {
+  const { token, headers, ...rest } = init;
+  const merged = new Headers(headers);
+  if (token != null) setMeshToken(merged, token);
+  return new Request(`http://peer.local${path.startsWith("/") ? path : `/${path}`}`, {
+    ...rest,
+    headers: merged,
+  });
+}

package/src/reset.ts

@@ -0,0 +1,127 @@
+/**
+ * Getting a stuck origin back to a first visit — and NOTHING ELSE IN IT.
+ *
+ * ITS OWN ENTRY POINT ON PURPOSE. This is what a rescue page loads when the
+ * app will not start, so it must not depend on the app starting. Importing it
+ * through `./browser` would drag in the session, the member lifecycle,
+ * `httpeers-access` and its Biscuit engine, crypto and transport code -- all to
+ * unregister a ServiceWorker. If any of that is what broke, the rescue page
+ * breaks with it.
+ *
+ * This was measured when the engine was WebAssembly: importing
+ * `@statewalker/httpeers-member/browser` failed outright until the wasm loader
+ * was wired. The engine is pure TypeScript now, but the rule stands for every
+ * other reason an app fails to start.
+ *
+ * So: zero imports. Everything here is a platform global.
+ */
+
+/**
+ * The page globals a reset touches. Declared locally, like the rest of this
+ * file — see `./page-wake.ts` for why not `lib: dom`.
+ */
+declare const navigator: {
+  serviceWorker?: { getRegistrations(): Promise<Array<{ unregister(): Promise<boolean> }>> };
+};
+declare const indexedDB: {
+  databases?(): Promise<Array<{ name?: string }>>;
+  deleteDatabase(name: string): {
+    onsuccess: (() => void) | null;
+    onerror: (() => void) | null;
+    onblocked: (() => void) | null;
+  };
+};
+declare const localStorage: { clear(): void } | undefined;
+declare const sessionStorage: { clear(): void } | undefined;
+
+/** What a reset actually removed, so a page can report it rather than guess. */
+export interface ResetResult {
+  /** ServiceWorker registrations unregistered on this origin. */
+  serviceWorkers: number;
+  /** IndexedDB databases deleted, by name. */
+  databases: string[];
+}
+
+/**
+ * Put this origin back to a first-visit state: no worker, no databases, no
+ * stored values.
+ *
+ * WHY THIS EXISTS AT ALL. A ServiceWorker is the stickiest thing a static site
+ * can install, and the obvious remedies do not work — measured in a real
+ * browser, not inferred:
+ *
+ *   - **A reload does not remove one.** Registration is durable state on the
+ *     ORIGIN, independent of any page's lifetime.
+ *   - **`unregister()` does not evict the worker already controlling this
+ *     page.** It removes the registration; the active worker keeps serving
+ *     open clients until they are unloaded. So a reset control that reports
+ *     success without reloading is still being served by the thing it says it
+ *     removed. **Reload after calling this.**
+ *   - **Unregistering alone is a half-reset.** The identity that makes a page
+ *     "the same peer" is in IndexedDB. Clear only the worker and the page
+ *     comes back as the same member, which is exactly the outcome people
+ *     report as "it did not work".
+ *
+ * EVERYTHING ON THE ORIGIN, NOT A LIST OF NAMES. The state spans idb-keyval's
+ * store (identity, remembered mesh), the hub's database, the libp2p key store,
+ * the ServiceWorker adapter's claimed-keys table and `localStorage` — five
+ * places across three packages today. A hand-maintained list would go stale
+ * the first time one moved, silently, leaving the half-reset above. An origin
+ * here belongs to one app, so "all of it" is both simpler and correct.
+ *
+ * NEVER THROWS. It runs on a rescue page that must work when everything else
+ * is broken, including on a first visit with nothing to remove.
+ */
+export async function resetBrowserState(): Promise<ResetResult> {
+  let serviceWorkers = 0;
+  try {
+    const registrations = (await navigator.serviceWorker?.getRegistrations()) ?? [];
+    for (const registration of registrations) {
+      try {
+        await registration.unregister();
+        serviceWorkers += 1;
+      } catch {
+        /* one that refuses must not stop the rest */
+      }
+    }
+  } catch {
+    /* no ServiceWorker support, or an insecure context */
+  }
+
+  const databases: string[] = [];
+  try {
+    // `indexedDB.databases()` is unsupported in Firefox, where enumeration is
+    // impossible and this half is a no-op. The worker and the stores below are
+    // still cleared, so a reset there is partial rather than absent -- worth
+    // knowing, and better than refusing to run.
+    const found = (await indexedDB.databases?.()) ?? [];
+    for (const { name } of found) {
+      if (name == null || name === "") continue;
+      await new Promise<void>((resolve) => {
+        const request = indexedDB.deleteDatabase(name);
+        request.onsuccess = () => resolve();
+        request.onerror = () => resolve();
+        // A database still open in another tab blocks. Resolving anyway keeps
+        // the reset moving; the page reload that follows closes this tab's
+        // handle, and the delete completes then.
+        request.onblocked = () => resolve();
+      });
+      databases.push(name);
+    }
+  } catch {
+    /* enumeration unsupported */
+  }
+
+  try {
+    localStorage?.clear();
+  } catch {
+    /* blocked site data */
+  }
+  try {
+    sessionStorage?.clear();
+  } catch {
+    /* blocked site data */
+  }
+
+  return { serviceWorkers, databases };
+}