@statewalker/httpeers-member 0.1.4

package/dist/edge-guard.js

@@ -0,0 +1,62 @@
+/**
+ * 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, prefix) {
+    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/dist/edge.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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 { assertKeyMatchesPrefix } from "./edge-guard.js";
+export { UncontrolledPageError } from "./edge-control.js";
+export { assertKeyMatchesPrefix };
+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 declare const DEFAULT_CONTROL_TIMEOUT_MS = 30000;
+/**
+ * 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 declare 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 declare function mountEdge(init: MountEdgeInit): Promise<EdgeHandle>;
+//# sourceMappingURL=edge.d.ts.map

package/dist/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../src/edge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAclC,MAAM,WAAW,aAAa;IAC5B,mJAAmJ;IACnJ,GAAG,EAAE,MAAM,CAAC;IACZ,mKAAmK;IACnK,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oIAAoI;IACpI,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,EAAE,YAAY,CAAC;IACvB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,0BAA0B,WAAW,CAAC;AAEnD,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CA2DxE"}

package/dist/edge.js

@@ -0,0 +1,104 @@
+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 };
+/**
+ * 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";
+/**
+ * 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) {
+    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/dist/gateway.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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";
+/** 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 declare const GATEWAY_MARKER = "x-httpeers-gateway";
+export declare function createGateway(init: GatewayInit): FetchHandler;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAGzE,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,KAAK,EAAE,YAAY,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,IAAI,QAAQ,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iFAAiF;AACjF,eAAO,MAAM,cAAc,uBAAuB,CAAC;AAEnD,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,YAAY,CAiD7D"}

package/dist/gateway.js

@@ -0,0 +1,102 @@
+/**
+ * 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 { bodyOf, stripPeerBinding } from "@statewalker/httpeers-core";
+/** 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) {
+    const base = normaliseBase(init.basePath ?? "");
+    return async (request) => {
+        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" } : {}),
+            // 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) {
+    if (value === "" || value === "/")
+        return "";
+    const withSlash = value.startsWith("/") ? value : `/${value}`;
+    return withSlash.endsWith("/") ? withSlash.slice(0, -1) : withSlash;
+}
+function listing(source) {
+    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, status, kind) {
+    return new Response(message, { status, headers: { [GATEWAY_MARKER]: kind } });
+}

package/dist/identity.d.ts

@@ -0,0 +1,78 @@
+import type { Ed25519PrivateKey } from "@libp2p/interface";
+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 declare 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;
+}
+/**
+ * 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 declare function decodeIdentity(bytes: Uint8Array): Ed25519PrivateKey;
+/** The bytes this store holds for `key`. The inverse of `decodeIdentity`. */
+export declare function encodeIdentity(key: Ed25519PrivateKey): Uint8Array;
+/**
+ * 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 declare function peerIdOf(key: Ed25519PrivateKey): string;
+/**
+ * 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 declare function loadOrCreateIdentity(init: IdentityStoreInit): Promise<Ed25519PrivateKey>;
+/**
+ * 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 declare function readIdentity(init: IdentityStoreInit): Promise<Ed25519PrivateKey | null>;
+/**
+ * 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 declare function clearIdentity(init: IdentityStoreInit): Promise<void>;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,8IAA8I;AAC9I,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAKD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,iBAAiB,CASnE;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,GAAG,EAAE,iBAAiB,GAAG,UAAU,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAEvD;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAM9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAI7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1E"}

package/dist/identity.js

@@ -0,0 +1,117 @@
+/**
+ * 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 { peerIdFromPrivateKey } from "@libp2p/peer-id";
+import { generateKey } from "@statewalker/httpeers-libp2p";
+/** 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";
+const backendOf = (init) => init.backend;
+const keyOf = (init) => 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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    await backendOf(init).delete(keyOf(init));
+}