@statewalker/httpeers-member 0.1.4

package/src/edge-guard.ts

@@ -0,0 +1,67 @@
+/**
+ * The key/prefix guard, factored out of `edge.ts` on its own -- see that
+ * module's doc comment for the full story of the trap this closes (design
+ * note 39 §3, work item 1). Kept dependency-free and in its own file
+ * DELIBERATELY: it is pure logic that needs no browser, but `edge.ts`
+ * itself imports `@statewalker/webrun-http-browser/sw`, whose workspace
+ * build has no committed `dist/` (note 39's own "published 0.3.3 and
+ * workspace 0.3.3 are different artefacts" finding -- see this task's
+ * report). Importing THIS file instead of `edge.ts` lets the guard's own
+ * unit test run without depending on that package's build state at all.
+ */
+
+/**
+ * `@statewalker/webrun-http-browser`'s `SwHttpDispatcher` (the
+ * ServiceWorker side) keys a registration by the incoming URL's FIRST
+ * PATH SEGMENT (`sw-dispatcher.ts`'s `_handleFetchEvent`); `SwHttpAdapter`
+ * (the page side) registers a handler under a prefix matched against the
+ * FULL base URL (`http-sw-dispatcher.ts`'s `_handleHttpRequest`). Nothing
+ * connects the two: an adapter constructed with `key: 'peer-under-test'`
+ * that then calls `register('mesh/', dispatch)` reports success at every
+ * step -- constructed, started, registered, correct `baseUrl` -- while the
+ * ServiceWorker looks up channel `'mesh'`, finds nothing registered under
+ * that key, and the request falls through to the origin server. The
+ * symptom looks exactly like a routing bug in httpeers; it is not one.
+ *
+ * Refuse to start instead, the same remedy `ruleSet()` applies to a policy
+ * typo (`httpeers.core`'s `rules.ts`, `assertValid`) and note 39 §5
+ * (work item 1) prescribes here: throw before `SwHttpAdapter.register` is
+ * ever called, so a mismatch is a loud construction-time error rather than
+ * a silent 404 three layers away.
+ *
+ * THE SECOND RULE -- THE TRAILING SLASH -- IS NEWER AND HAS ITS OWN TRAP.
+ * `SwHttpRegistration.baseUrl` is `new URL("./" + prefix, rootUrl)`, so a
+ * prefix with no trailing slash (`"app"`, or `"app/sub"`) produces a
+ * baseUrl with none either. Since Ruling 58 that baseUrl is a published
+ * contract -- `BrowserPeerHandle.baseUrl`, documented as always ending in
+ * a slash, because every page-originated call composes
+ * `${baseUrl}${peerId}/...`. A slash-less baseUrl silently yields
+ * `/appPEERID/search`: a URL the ServiceWorker still routes (its key is
+ * the first segment, `appPEERID`... which matches nothing), so the request
+ * falls through to the origin server exactly like the first trap, and for
+ * a reason just as invisible. No caller does this today; the point of a
+ * guard is that none ever can.
+ */
+export function assertKeyMatchesPrefix(key: string, prefix: string): void {
+  const firstSegment = prefix.split("/")[0];
+  if (firstSegment !== key) {
+    throw new Error(
+      `mountEdge: prefix "${prefix}" does not start with adapter key "${key}" -- ` +
+        "the ServiceWorker dispatcher keys a registration by the URL's first path segment " +
+        "while the adapter matches the full base URL; a mismatch here means every mounting " +
+        "step reports success while the handler is never called, and the request silently " +
+        "falls through to the origin server (design note 39 §3). Refusing to start rather " +
+        "than mount a registration nothing can ever reach.",
+    );
+  }
+  if (!prefix.endsWith("/")) {
+    throw new Error(
+      `mountEdge: prefix "${prefix}" does not end with "/" -- the resulting baseUrl would ` +
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: quoting what a page writes, not interpolating.
+        "not either, and every mesh call a page composes as `${baseUrl}${peerId}/...` would " +
+        "run the two together into one segment the ServiceWorker cannot route, falling " +
+        "through to the origin server. `BrowserPeerHandle.baseUrl` promises a trailing " +
+        "slash (Ruling 58); this is what makes that promise keepable.",
+    );
+  }
+}

package/src/edge.ts

@@ -0,0 +1,175 @@
+/**
+ * The ServiceWorker edge: mounts a peer's `dispatch` into
+ * `@statewalker/webrun-http-browser`'s `SwHttpAdapter` so a page's own
+ * `fetch()` (same-origin) can reach it, no different in shape from any
+ * other HTTP request on the page.
+ *
+ * `dispatch` MOUNTS UNCHANGED -- NO WRAPPER, NO CAST (design note 22 §1,
+ * criterion 1 of prototype E-1). `httpeers.core`'s `FetchHandler` is
+ * `(Request) => Promise<Response>`; `SwHttpAdapter.register`'s `HttpHandler`
+ * (`@statewalker/webrun-http-streams`) is `(Request) => Response |
+ * Promise<Response>` -- the same contract, arrived at independently, which
+ * is exactly why `mountEdge` below passes `dispatch` straight through with
+ * no adapter of its own.
+ *
+ * THE KEY/PREFIX TRAP -- see `edge-guard.ts`'s `assertKeyMatchesPrefix` for
+ * the mechanism and why it is factored into its own file.
+ *
+ * THE `/sw` SUBPATH IS A BUILT FILE. `@statewalker/webrun-http-browser`
+ * (an optional peer, `^0.5.0`) points its `./sw` export at `./dist/sw.js`,
+ * which the published tarball ships. Inside an assembly, where the package is
+ * a linked workspace checkout, `dist/` is gitignored and only exists once
+ * `pnpm --filter @statewalker/webrun-http-browser build` has run -- and a
+ * stale one is bundled silently.
+ */
+import type { FetchHandler } from "@statewalker/httpeers-core";
+import { SwHttpAdapter } from "@statewalker/webrun-http-browser/sw";
+import { edgeStartError } from "./edge-control.js";
+import { assertKeyMatchesPrefix } from "./edge-guard.js";
+
+export { UncontrolledPageError } from "./edge-control.js";
+export { assertKeyMatchesPrefix };
+
+/**
+ * The two browser globals this file names, declared LOCALLY rather than by
+ * adding "dom" to the package's `lib` -- see `./page-wake.ts` for the reason.
+ *
+ * `navigator` is the interesting one: @types/node declares it too, and ITS
+ * `Navigator` has no `serviceWorker`, so this is not merely filling a gap but
+ * shadowing a same-named global that means something else in the other
+ * runtime. Narrow on purpose -- only the members `mountEdge` reads.
+ */
+declare const navigator: { serviceWorker?: unknown };
+declare const location: { origin: string; href: string };
+
+export interface MountEdgeInit {
+  /** The ServiceWorker adapter's channel key -- see `assertKeyMatchesPrefix`'s doc comment for why this must equal `prefix`'s first path segment. */
+  key: string;
+  /** Defaults to `${key}/` -- the one prefix shape `assertKeyMatchesPrefix` is guaranteed to accept. Overridable only for a caller with a real reason to diverge. */
+  prefix?: string;
+  /** Defaults to `DEFAULT_SERVICE_WORKER_URL` -- see its own comment; omitting it entirely is NOT an option this adapter survives. */
+  serviceWorkerUrl?: string;
+  /** The peer's own router. Mounted unchanged -- see this module's doc comment. */
+  dispatch: FetchHandler;
+  /**
+   * The bound on getting a controlling ServiceWorker, in ms -- passed to
+   * `SwHttpAdapter` as its `timeout`. Defaults to `DEFAULT_CONTROL_TIMEOUT_MS`.
+   */
+  controlTimeoutMs?: number;
+}
+
+/**
+ * How long `mountEdge` waits for its ServiceWorker to activate, take control
+ * of the page and answer, before giving up with an error.
+ *
+ * Before webrun-http-browser 0.5 `SwHttpAdapter.start()` had no bound, and a
+ * page that never got a controller -- a hard reload was the case that
+ * shipped; see `./edge-control.ts` -- hung at "mounting-edge" for good. The
+ * library now bounds every wait by its `timeout`; this is the value passed.
+ * A first visit installs a ~60 KB script and activates it, which takes well
+ * under a second on a slow link; thirty seconds is generous. It is also how
+ * long a worker that does NOT answer the `CLAIM` request (one older than 0.5,
+ * say) keeps a hard-reloaded page waiting before the one automatic reload.
+ */
+export const DEFAULT_CONTROL_TIMEOUT_MS = 30_000;
+
+/**
+ * Where each origin's ServiceWorker script lives: `/sw.js`, the dist root.
+ * Fixed by `../static-server/main.ts`'s own `swFile` default (it serves
+ * exactly that filename with `Service-Worker-Allowed: /`) and by both vite
+ * configs, which name the `sw` entry `sw.js` with no content hash for this
+ * exact reason.
+ *
+ * SUPPLYING THIS IS NOT OPTIONAL, AND OMITTING IT IS NOT A GRACEFUL
+ * DEGRADATION. `SwHttpAdapter`'s own defaults are mutually recursive:
+ * `scope` reads `serviceWorkerUrl`, which (when unset) computes
+ * `new URL("./index-sw.js", rootUrl)`, and `rootUrl` reads `scope` again
+ * (`sw-dispatcher.ts`'s three getters). With neither `scope` nor
+ * `serviceWorkerUrl` given, the CONSTRUCTOR -- which validates `this.scope`
+ * -- recurses until the stack is exhausted. Verified directly by
+ * constructing one under Node: `RangeError: Maximum call stack size
+ * exceeded`, before `start()` is ever reached. `mountEdge` previously
+ * forwarded `init.serviceWorkerUrl` straight through, so every caller that
+ * left it unset (the image peer page, Task 12) would have hit that
+ * RangeError the first time it ran in a real browser. Defaulting here fixes
+ * every such caller at once rather than asking each page to remember.
+ */
+export const DEFAULT_SERVICE_WORKER_URL = "/sw.js";
+
+export interface EdgeHandle {
+  /** The URL a same-origin `fetch()` reaches this peer's `dispatch` through. */
+  baseUrl: string;
+  stop(): Promise<void>;
+}
+
+/**
+ * Register a peer's `dispatch` on the ServiceWorker edge. Throws (via
+ * `assertKeyMatchesPrefix`) before `SwHttpAdapter` is even constructed if
+ * `key`/`prefix` disagree -- the failure this function exists to make
+ * loud instead of silent.
+ *
+ * On a page its ServiceWorker does not control (a hard reload) the adapter asks
+ * the worker to claim it, in place; if that does not take, it reloads the page
+ * once, guarded, and otherwise this throws `UncontrolledPageError`. It gives up
+ * after `controlTimeoutMs` rather than wait forever. See `./edge-control.ts`.
+ */
+export async function mountEdge(init: MountEdgeInit): Promise<EdgeHandle> {
+  const prefix = init.prefix ?? `${init.key}/`;
+  assertKeyMatchesPrefix(init.key, prefix);
+
+  // SAY WHAT IS ACTUALLY WRONG. ServiceWorkers exist only in a secure context:
+  // `https://`, or `http://` on `localhost`/`127.0.0.1`. Served from a LAN
+  // address over plain HTTP -- exactly what someone does when opening these
+  // pages from a phone -- `navigator.serviceWorker` is `undefined`, and the
+  // first symptom is `TypeError: Cannot read properties of undefined (reading
+  // 'register')` thrown from inside the adapter, which names neither the cause
+  // nor the fix. This is a browser rule, not something this stack can work
+  // around; the deployment answer is the TLS the design already provides for
+  // (`TLS_CERT`/`TLS_KEY`).
+  if (typeof navigator === "undefined" || navigator.serviceWorker == null) {
+    const origin = typeof location !== "undefined" ? location.origin : "this origin";
+    throw new Error(
+      `mountEdge: this browser exposes no ServiceWorker at ${origin}, so a peer cannot be ` +
+        "reached through the page's own fetch(). ServiceWorkers require a secure context: " +
+        "serve the page over https, or open it on localhost / 127.0.0.1. " +
+        "(A LAN address over plain http is not a secure context, which is why this fails " +
+        "there but works on localhost.)",
+    );
+  }
+
+  // Resolved against the page's own origin: `SwHttpAdapter` passes this to
+  // `new URL(...)` with no base, so a bare "/sw.js" would throw `Invalid
+  // URL` rather than being treated as origin-relative.
+  const serviceWorkerUrl = new URL(
+    init.serviceWorkerUrl ?? DEFAULT_SERVICE_WORKER_URL,
+    location.href,
+  ).href;
+
+  // AN UNCONTROLLED PAGE UNDER AN ACTIVE WORKER (a hard reload): `start()` asks
+  // the worker to claim it (`CLAIM`), and failing that reloads once --
+  // `reloadIfUncontrolled`, kept as the last resort for a worker that does not
+  // answer `CLAIM` (an older `/sw.js` still installed in a returning visitor's
+  // browser, or a custom `serviceWorkerUrl`). It costs nothing when the claim
+  // works, and the library guards it against looping. See `./edge-control.ts`.
+  const timeoutMs = init.controlTimeoutMs ?? DEFAULT_CONTROL_TIMEOUT_MS;
+  const adapter = new SwHttpAdapter({
+    key: init.key,
+    serviceWorkerUrl,
+    timeout: timeoutMs,
+    reloadIfUncontrolled: true,
+  });
+  try {
+    await adapter.start();
+  } catch (error) {
+    throw edgeStartError(error, serviceWorkerUrl, timeoutMs);
+  }
+  const registration = await adapter.register(prefix, init.dispatch);
+
+  return {
+    baseUrl: registration.baseUrl,
+    async stop() {
+      await registration.remove();
+      await adapter.stop();
+    },
+  };
+}

package/src/gateway.ts

@@ -0,0 +1,141 @@
+/**
+ * 08 — the mesh as ordinary HTTP.
+ *
+ * ONE `FetchHandler` that serves every resource in the mesh at
+ * `/{peerId}/{servicePath}`, so whatever mounts it — `@hono/node-server`, a
+ * ServiceWorker, a relay — never learns that libp2p exists.
+ *
+ * BUILT ON THE PROVEN EDGE, NOT BESIDE IT. The dispatch a page already uses
+ * (`src/browser/edge-dispatch.ts`) does four things that took four separate
+ * bugs to discover: strip the mount prefix, attach the membership token at
+ * call time, ensure a route before the call rides it, and map a thrown
+ * `PeerCallError` onto a status the caller can read. This file does not
+ * reimplement any of them — it rewrites the request and hands it to that
+ * handler, which is what `MemberHandle.fetch` exposes.
+ *
+ * WHAT IS NEW HERE, and the only thing that is:
+ *
+ *   1. `basePath` is a parameter. The ServiceWorker edge is keyed to
+ *      `/{key}/` and cannot mount at `/`; a Node server mounts wherever it
+ *      likes, including `/`. One handler, three hosts.
+ *   2. A listing at `GET {basePath}/`, which enumerates peers and the KINDS
+ *      they advertise — never URLs. The mesh view carries no service paths,
+ *      so a listing that promised URLs would be inventing them.
+ *   3. Dispatch is read per request from the live mesh view, so a peer that
+ *      joins after the server started is reachable with no rebuild.
+ */
+
+import type { FetchHandler, MeshView } from "@statewalker/httpeers-core";
+import { bodyOf, stripPeerBinding } from "@statewalker/httpeers-core";
+
+/** What the gateway needs of a member. `MemberHandle` satisfies it; so does a test double. */
+export interface GatewaySource {
+  peerId: string;
+  /** The proven edge dispatch: `/{key}/{peerId}/{path}` in, mesh call out. */
+  fetch: FetchHandler;
+  /** Read per request — a peer that joined a second ago must be dispatchable. */
+  meshView(): MeshView | null;
+}
+
+export interface GatewayInit {
+  source: GatewaySource;
+  /**
+   * The prefix this gateway is mounted at, stripped before dispatch.
+   * `""` on a Node server; `"/peers"` behind a ServiceWorker keyed `peers`.
+   */
+  basePath?: string;
+  /** The key the underlying edge dispatch expects as the first segment. */
+  edgeKey: string;
+}
+
+/** Marks the gateway's own responses so they are never mistaken for a peer's. */
+export const GATEWAY_MARKER = "x-httpeers-gateway";
+
+export function createGateway(init: GatewayInit): FetchHandler {
+  const base = normaliseBase(init.basePath ?? "");
+
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+
+    if (base !== "" && !url.pathname.startsWith(base)) {
+      return marked(`not under ${base}`, 404, "outside-mount");
+    }
+    const rest = url.pathname.slice(base.length) || "/";
+
+    // The listing. Honest about what it knows: peers and advertised kinds,
+    // with the view's own version and an `asOf` — never a URL, because the
+    // mesh view carries no service paths.
+    if ((rest === "/" || rest === "") && request.method === "GET") {
+      return listing(init.source);
+    }
+
+    // SEGMENTS, NEVER A URL HOST. A peer id is base58 and case-sensitive; a
+    // URL host is lower-cased by normalisation and userinfo (`a@b`) silently
+    // reassigns it. The path is the only safe place to carry one.
+    const [, first = "", ...tail] = rest.split("/");
+    if (first === "") return marked("no peer in the path", 404, "no-peer");
+
+    // Hand it to the proven dispatch, spelled the way that handler expects.
+    const target = new URL(
+      `/${init.edgeKey}/${first}${tail.length > 0 ? `/${tail.join("/")}` : ""}${url.search}`,
+      "http://gateway.local",
+    );
+
+    // ORDINARY HTTP IN FRONT OF A MEMBER, so the caller is a browser or a
+    // curl and any proven-peer header it sent is a claim about somebody else.
+    // Strip before the request enters the mesh.
+    stripPeerBinding(request);
+
+    const body = await bodyOf(request);
+    const forwarded = new Request(target, {
+      method: request.method,
+      headers: request.headers,
+      body,
+      ...(body instanceof ReadableStream ? { duplex: "half" as const } : {}),
+      // FORWARDED DELIBERATELY. `@hono/node-server` aborts this signal when the
+      // client hangs up, and nothing else would stop the libp2p call — the
+      // stream would run to completion with nobody to receive it.
+      signal: request.signal,
+    });
+
+    return await init.source.fetch(forwarded);
+  };
+}
+
+/** `""` or `/a/b` — never a trailing slash, so `base.length` is a clean cut. */
+function normaliseBase(value: string): string {
+  if (value === "" || value === "/") return "";
+  const withSlash = value.startsWith("/") ? value : `/${value}`;
+  return withSlash.endsWith("/") ? withSlash.slice(0, -1) : withSlash;
+}
+
+function listing(source: GatewaySource): Response {
+  const view = source.meshView();
+  // `null` is a real state — "no view yet" is not "nobody is here" — and a
+  // listing that flattened the two would be a lie on every first load.
+  if (view == null) {
+    return Response.json(
+      { ready: false, self: source.peerId, peers: [], offers: [] },
+      { headers: { [GATEWAY_MARKER]: "no-view" } },
+    );
+  }
+  return Response.json({
+    ready: true,
+    self: source.peerId,
+    version: view.version,
+    asOf: Date.now(),
+    peers: view.members.map((m) => ({ peerId: m.peerId, roles: m.roles })),
+    // Flat, and independent of `peers`: the hub advertises under its own id
+    // and is in no member list.
+    offers: view.advertisements.map((a) => ({
+      peerId: a.peerId,
+      id: a.id,
+      kind: a.kind,
+      title: a.title,
+    })),
+  });
+}
+
+function marked(message: string, status: number, kind: string): Response {
+  return new Response(message, { status, headers: { [GATEWAY_MARKER]: kind } });
+}

package/src/identity.ts

@@ -0,0 +1,146 @@
+/**
+ * This origin's persistent libp2p identity, in IndexedDB.
+ *
+ * IDENTITY PERSISTS PER ORIGIN. Each page (the main app, the image peer,
+ * the hub page) is its own origin (`../static-server/main.ts`'s "ORIGINS
+ * ARE A CORRECTNESS REQUIREMENT" note) and therefore its own IndexedDB, so
+ * each gets its OWN signing key and its own peerId. That is deliberate: two
+ * pages sharing one identity would be two independent libp2p nodes racing
+ * to be "the" peer for that identity, which is a different and worse
+ * problem than two distinct mesh members.
+ *
+ * THE KEY FORMAT IS THE NODE SIDE'S, EXACTLY. `@libp2p/crypto/keys`'s
+ * protobuf encoding -- the same bytes `../setup/keys.ts` writes to
+ * `.httpeers/hub.key` and `../hub/main.ts` reads back -- just stored in
+ * IndexedDB instead of a file, because a browser has no filesystem to write
+ * one to. That is not a cosmetic alignment: `peerIdFromPrivateKey` on a key
+ * that round-tripped through this store must produce the SAME peerId string
+ * as the Node path produces for the same key, or the hub page's mesh
+ * identity would not be the thing every token's `mesh` claim restates.
+ * `tests/browser-identity.test.ts` pins that round trip.
+ *
+ * WHY THIS IS SPLIT OUT OF `./browser-profile.ts` (Task 24). That module
+ * loaded the key and handed it straight to `createLibp2p`, which never
+ * gives it back -- fine for a page that only needs a node, and impossible
+ * for the hub page, which must ALSO pass the very same key to `createPeer`
+ * so its `mintToken` closure signs as the mesh (`httpeers.core`'s
+ * `CreatePeerInit.privateKey`). Loading the identity is now its own step
+ * that a caller can take first and use twice. `browser-profile.ts` re-exports
+ * everything here, so nothing that imported it from there had to change.
+ */
+import { privateKeyFromProtobuf, privateKeyToProtobuf } from "@libp2p/crypto/keys";
+import type { Ed25519PrivateKey } from "@libp2p/interface";
+import { peerIdFromPrivateKey } from "@libp2p/peer-id";
+import { generateKey } from "@statewalker/httpeers-libp2p";
+import type { AsyncBytesBackend } from "./kv.js";
+
+/** Where this origin's identity key lives in IndexedDB (via `idb-keyval`, the same store `@statewalker/webrun-http-browser` already uses). */
+export const IDENTITY_STORAGE_KEY = "httpeers:identity-key";
+
+/**
+ * Where the key is kept, injectable -- `./kv.ts`'s bytes seam, defaulting
+ * to the real IndexedDB.
+ *
+ * ADDED IN TASK 28 SO THE STORE'S OWN BEHAVIOUR IS NODE-TESTABLE, not just
+ * its codec. "A first run has no key", "a second run gets the same peerId
+ * back", and "after a reset the next run is a different peerId" are the
+ * three facts the two consumer pages' whole resume story rests on, and all
+ * three used to be unreachable from Node because `idb-keyval` needs a real
+ * IndexedDB. The stored VALUE is unchanged -- raw protobuf bytes, exactly
+ * as Task 24 wrote them -- so a page that already holds a key reads it back
+ * identically; see `./kv.ts` on why the bytes seam is separate from the
+ * string one.
+ */
+export interface IdentityStoreInit {
+  backend: AsyncBytesBackend;
+  storageKey?: string;
+}
+
+const backendOf = (init: IdentityStoreInit): AsyncBytesBackend => init.backend;
+const keyOf = (init: IdentityStoreInit): string => init.storageKey ?? IDENTITY_STORAGE_KEY;
+
+/**
+ * Decode the protobuf bytes this store holds, refusing anything that is not
+ * Ed25519. Exported so a Node test can exercise the decode half of the
+ * round trip without an IndexedDB (see this module's comment).
+ */
+export function decodeIdentity(bytes: Uint8Array): Ed25519PrivateKey {
+  const key = privateKeyFromProtobuf(bytes);
+  if (key.type !== "Ed25519") {
+    throw new Error(
+      `identity: the key stored at "${IDENTITY_STORAGE_KEY}" is a ${key.type} key -- ` +
+        "only Ed25519 is supported (design note 05 §2).",
+    );
+  }
+  return key;
+}
+
+/** The bytes this store holds for `key`. The inverse of `decodeIdentity`. */
+export function encodeIdentity(key: Ed25519PrivateKey): Uint8Array {
+  return privateKeyToProtobuf(key);
+}
+
+/**
+ * The peerId a key derives to -- the same computation `httpeers.core`'s
+ * `mintToken` uses, and the same one `../setup/keys.ts`'s `peerIdOf` does
+ * on the Node side. Not imported from there: that module reads
+ * `node:fs`/`node:crypto` at module scope and would poison a browser
+ * bundle. `tests/browser-identity.test.ts` pins that the two agree.
+ */
+export function peerIdOf(key: Ed25519PrivateKey): string {
+  return peerIdFromPrivateKey(key).toString();
+}
+
+/**
+ * Load this origin's persisted identity, or generate and persist one on
+ * first run. Reuses `httpeers.core`'s own `generateKey` rather than
+ * calling `@libp2p/crypto`'s `generateKeyPair` directly a second time --
+ * one call site for "how this mesh mints a fresh identity," matching the
+ * lesson note 22 §5/§6 draws about reading this workspace's own source
+ * before re-deriving something already sitting in it.
+ */
+export async function loadOrCreateIdentity(init: IdentityStoreInit): Promise<Ed25519PrivateKey> {
+  const stored = await readIdentity(init);
+  if (stored != null) return stored;
+  const key = await generateKey();
+  await backendOf(init).set(keyOf(init), encodeIdentity(key));
+  return key;
+}
+
+/**
+ * This origin's persisted identity, or `null` when it has never had one.
+ *
+ * THE DIFFERENCE BETWEEN THIS AND `loadOrCreateIdentity` IS A SENTENCE ON
+ * SCREEN. A page that starts by trying to RESUME a membership has to tell
+ * an operator which of two situations it is in, and they are not alike:
+ * "this browser has never joined anything" is a first run, and "this
+ * browser holds an identity the hub does not recognise" is a hub reset or a
+ * revoked membership -- the second being the one that is otherwise baffling
+ * (Task 28, requirement 3). `loadOrCreateIdentity` cannot tell them apart
+ * by construction, because it has already created the key by the time it
+ * returns. So the read is its own step, and creation happens only when the
+ * page actually goes on to join.
+ */
+export async function readIdentity(init: IdentityStoreInit): Promise<Ed25519PrivateKey | null> {
+  const stored = await backendOf(init).get(keyOf(init));
+  if (stored == null) return null;
+  return decodeIdentity(stored);
+}
+
+/**
+ * Forget this origin's identity, so the next `loadOrCreateIdentity` mints a
+ * fresh one.
+ *
+ * DESTRUCTIVE, AND FOR THE HUB PAGE IT IS THE MOST DESTRUCTIVE THING THERE
+ * IS: the hub's peerId IS the mesh (`claims.mesh === claims.iss`), so
+ * dropping this key does not rotate a credential, it founds a DIFFERENT
+ * mesh -- every token ever issued stops verifying and every join URL handed
+ * out stops working. Whoever calls this owes the operator a confirmation
+ * that says so in those terms; `../pages/hub/main.ts` is where that lives.
+ * A caller that also holds hub state must clear it in the same breath (see
+ * that page): members carried into a new mesh would be peers that never
+ * joined it.
+ */
+export async function clearIdentity(init: IdentityStoreInit): Promise<void> {
+  await backendOf(init).delete(keyOf(init));
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+/**
+ * Everything a participant does: hold an identity, redeem or resume, connect,
+ * keep the link, advertise, discover, call, and serve.
+ *
+ * `startMember` is the seam rung 01 proved: one lifecycle, with the three
+ * things that genuinely differ between a Node process and a page injected as a
+ * `MemberPlatform`. `MemberHandle.fetch` IS the edge on both platforms;
+ * `baseUrl` is the browser-only part.
+ */
+
+export { type ConnectionKind, classifyConnection, describeConnection } from "./connection-kind.js";
+export { describeError } from "./describe-error.js";
+
+export {
+  createEdgeDispatch,
+  type EdgeDispatchInit,
+  PEER_ERROR_STATUS,
+  type PeerErrorBody,
+  stripEdgePrefix,
+  targetPeerId,
+} from "./edge-dispatch.js";
+/**
+ * The mesh as ordinary HTTP.
+ *
+ * `createGateway` turns a member into a `FetchHandler` dispatching
+ * `/{peerId}/{path}` — so a client with no peer object, no token and no
+ * knowledge of libp2p can `fetch()` a mesh resource. `GatewaySource` is
+ * structurally a subset of `MemberHandle`, so a member IS one.
+ */
+export { createGateway, GATEWAY_MARKER, type GatewayInit, type GatewaySource } from "./gateway.js";
+export {
+  clearIdentity,
+  decodeIdentity,
+  encodeIdentity,
+  IDENTITY_STORAGE_KEY,
+  type IdentityStoreInit,
+  loadOrCreateIdentity,
+  peerIdOf,
+  readIdentity,
+} from "./identity.js";
+export {
+  decodeJoinBlob,
+  encodeJoinBlob,
+  invitationFromQrText,
+  JOIN_BLOB_PARAM,
+  type JoinBlob,
+  type JoinInput,
+  joinUrl,
+  readJoinInputFromSearch,
+  readJoinInputFromText,
+} from "./join-blob.js";
+export type { AsyncBytesBackend, AsyncKeyValueBackend } from "./kv.js";
+export { parseMeshConfig } from "./mesh-config.js";
+export {
+  type CreateMeshMemoryInit,
+  createMeshMemory,
+  MESH_STORAGE_KEY,
+  type MeshMemory,
+} from "./mesh-memory.js";
+export { type PeerRequestInit, peerRequest } from "./peer-request.js";
+/**
+ * The session machine — ISOMORPHIC, and exported from the root on purpose.
+ *
+ * It used to be the browser peer's private business. Everything platform-bound
+ * in it is now injected (the platform, the two stores, the reload), so a Node
+ * member that wants resume-or-redeem and the same four operator controls gets
+ * them here rather than reimplementing them. `./browser`'s `createSession` is
+ * the same thing with a page's defaults filled in.
+ */
+export {
+  createIdentityStore,
+  createPeerSession,
+  DEFAULT_HTTPEERS_CONFIG_URL,
+  describeMeshDrift,
+  type IdentityStore,
+  type NeedsInvitationReason,
+  type PeerSession,
+  type PeerSessionInit,
+  type SessionControls,
+  type SessionPhase,
+  type SessionStartState,
+  type SessionState,
+  type StartPeer,
+} from "./session.js";
+export {
+  type HubLink,
+  type JoinMethod,
+  type MemberEdge,
+  type MemberHandle,
+  MemberJoinError,
+  type MemberPlatform,
+  type MemberState,
+  type StartMemberInit,
+  startMember,
+} from "./start-member.js";