@statewalker/httpeers-member 0.1.4

package/dist/connection-kind.js

@@ -0,0 +1,52 @@
+/**
+ * Is this peer reached directly, or through the relay?
+ *
+ * WHY THIS EXISTS. libp2p does not upgrade a circuit to WebRTC on its own:
+ * `join.ts`'s `preDialPeer` dials `<relay>/p2p-circuit/webrtc/p2p/<peer>`
+ * explicitly, and the circuit's only job there is to carry the SDP exchange.
+ * When that dial fails -- symmetric NAT on a mobile carrier, a VPN, no reachable
+ * STUN -- `edge-dispatch.ts` SWALLOWS the failure by design and the call is
+ * attempted anyway. `remote()` then dials by peer id, which resolves through the
+ * peerStore to a bare `/p2p-circuit` address, and every byte crosses the relay.
+ *
+ * That fallback works. What it does not do is announce itself, and the silence
+ * is the problem: it is 10-100x slower, it spends the relay operator's
+ * bandwidth instead of going peer-to-peer, and while the relay applied a
+ * per-connection data cap it truncated transfers mid-stream. The visible
+ * symptom was broken images in a gallery, with one of them loading fine in a
+ * fresh tab -- which reads as random corruption rather than as a transport
+ * that quietly changed underneath.
+ *
+ * Reading the open connection's own address is the whole diagnosis, and it is
+ * one call. Strings in, so this module needs no libp2p import and is testable
+ * under plain Node.
+ */
+/**
+ * Classify the connections open to one peer, from their multiaddrs.
+ *
+ * `/webrtc` present means the WebRTC upgrade completed and the relay is no
+ * longer in the data path. A `/p2p-circuit` WITHOUT it means it did not, and
+ * traffic is being relayed. Direct wins when both are open, because that is the
+ * one libp2p will actually use.
+ */
+export function classifyConnection(remoteAddrs) {
+    if (remoteAddrs.length === 0)
+        return "none";
+    if (remoteAddrs.some((addr) => addr.includes("/webrtc")))
+        return "direct";
+    if (remoteAddrs.some((addr) => addr.includes("/p2p-circuit")))
+        return "relayed";
+    // Anything else -- a plain TCP or WebSocket address -- is a direct dial.
+    return "direct";
+}
+/** One line a page can render unconditionally, saying what the kind means rather than naming it. */
+export function describeConnection(kind) {
+    switch (kind) {
+        case "direct":
+            return "direct (WebRTC) — data goes peer to peer, the relay is not involved";
+        case "relayed":
+            return "relayed — the WebRTC upgrade did not succeed, so every byte crosses the relay: expect it to be slow";
+        case "none":
+            return "not connected yet";
+    }
+}

package/dist/describe-error.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Turn anything thrown into something a person can act on.
+ *
+ * WHY THIS EXISTS. Every "could not reach the relay" message in this app ended
+ * with `Cause: ${String(err)}`, and a failed WebSocket does not reject with an
+ * `Error` -- it rejects with a DOM `Event`. `String(event)` is
+ * **"[object Event]"**. A phone that could not reach the relay reported exactly
+ * that, and it named nothing: not the URL, not whether the socket ever opened,
+ * not whether it was closed or refused. The one message whose entire job was to
+ * explain a connection failure discarded every fact about it.
+ *
+ * The event carries what is needed -- `type`, `target.url`, `target.readyState`
+ * and, for a close event, `code` and `reason`. This reads them defensively,
+ * because an object that is not what we assume must not turn a bad error message
+ * into a second exception thrown while reporting the first.
+ */
+export declare function describeError(err: unknown): string;
+//# sourceMappingURL=describe-error.d.ts.map

package/dist/describe-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-error.d.ts","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAgBH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CA4ClD"}

package/dist/describe-error.js

@@ -0,0 +1,72 @@
+/**
+ * Turn anything thrown into something a person can act on.
+ *
+ * WHY THIS EXISTS. Every "could not reach the relay" message in this app ended
+ * with `Cause: ${String(err)}`, and a failed WebSocket does not reject with an
+ * `Error` -- it rejects with a DOM `Event`. `String(event)` is
+ * **"[object Event]"**. A phone that could not reach the relay reported exactly
+ * that, and it named nothing: not the URL, not whether the socket ever opened,
+ * not whether it was closed or refused. The one message whose entire job was to
+ * explain a connection failure discarded every fact about it.
+ *
+ * The event carries what is needed -- `type`, `target.url`, `target.readyState`
+ * and, for a close event, `code` and `reason`. This reads them defensively,
+ * because an object that is not what we assume must not turn a bad error message
+ * into a second exception thrown while reporting the first.
+ */
+/** WebSocket.readyState, in words. The bare number tells a reader nothing. */
+const READY_STATE = ["CONNECTING", "OPEN", "CLOSING", "CLOSED"];
+function pick(obj, key) {
+    try {
+        return obj != null && typeof obj === "object"
+            ? obj[key]
+            : undefined;
+    }
+    catch {
+        // A getter that throws must not take the error report down with it.
+        return undefined;
+    }
+}
+export function describeError(err) {
+    if (err instanceof Error) {
+        const cause = err.cause;
+        if (cause == null || cause === err)
+            return err.message;
+        // Compare the DESCRIPTIONS, not the objects. libp2p wraps a WebSocket
+        // error event in an Error whose `cause` is a different object describing
+        // the same failure, so identity comparison lets it print twice --
+        // "socket CLOSED (cause: ... socket CLOSED)" -- which reads like two
+        // problems.
+        const described = describeError(cause);
+        return err.message.includes(described) ? err.message : `${err.message} (cause: ${described})`;
+    }
+    const type = pick(err, "type");
+    if (typeof type === "string") {
+        const target = pick(err, "target");
+        const parts = [`${type} event`];
+        const url = pick(target, "url");
+        if (typeof url === "string" && url !== "")
+            parts.push(url);
+        const state = pick(target, "readyState");
+        if (typeof state === "number" && READY_STATE[state] != null) {
+            parts.push(`socket ${READY_STATE[state]}`);
+        }
+        const code = pick(err, "code");
+        if (typeof code === "number")
+            parts.push(`code ${code}`);
+        const reason = pick(err, "reason");
+        if (typeof reason === "string" && reason !== "")
+            parts.push(`reason "${reason}"`);
+        // A `error` event on a socket still CONNECTING means the connection was
+        // never established -- DNS, TLS, a proxy or a blocked port -- rather than
+        // anything the peers said to each other. That distinction is the whole
+        // value of printing the state.
+        return parts.join(", ");
+    }
+    try {
+        return String(err);
+    }
+    catch {
+        return "an error that could not be converted to a string";
+    }
+}

package/dist/edge-control.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Turning a failure to get the page's ServiceWorker into an error a user can
+ * act on.
+ *
+ * THE HANG THIS USED TO GUARD. A page can load UNCONTROLLED while its worker
+ * is already active -- a HARD RELOAD (Ctrl+Shift+R; Firefox's
+ * `location.reload(true)`) bypasses the worker by spec, and Firefox has left a
+ * second tab uncontrolled too. The worker claimed its clients when it
+ * activated, long ago, so no `controllerchange` ever comes. Up to
+ * `@statewalker/webrun-http-browser` 0.4, `SwHttpAdapter.start()` then waited
+ * forever: llm-chat's mesh.html sat at "Joining… (mounting-edge)" after every
+ * hard reload, and this file carried a reload guard of its own.
+ *
+ * SINCE 0.5 THE LIBRARY RECOVERS IT ITSELF. `start()` asks the active worker to
+ * claim the page again (a `CLAIM` call, answered with `clients.claim()` by the
+ * package's own `sw-worker` -- which is what this stack's `/sw.js` is), so a
+ * hard-reloaded page is taken over in place, with no navigation. Every wait is
+ * bounded by `timeout`; past it `start()` rejects with a
+ * `ServiceWorkerControlError` whose `reason` says which wait failed. And with
+ * `reloadIfUncontrolled` it reloads once, guarded by `sessionStorage`, when the
+ * claim did not take. Measured in Chromium and Firefox by
+ * `packages/httpeers-browser-conformance/scripts/edge-reload.mjs`.
+ *
+ * What is left here is the message: `edgeStartError` maps the library's error
+ * onto the ones `mountEdge` has always thrown, so a page shows "close the tab
+ * and reopen it" rather than a library's diagnostic. It matches on `name` and
+ * `reason`, not `instanceof`: every bundle of webrun-http-browser carries its
+ * own copy of the class.
+ */
+/** The error a page shows when it cannot get its ServiceWorker's control. */
+export declare class UncontrolledPageError extends Error {
+    constructor(detail: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The error `mountEdge` throws when `SwHttpAdapter.start()` rejects:
+ *
+ *   - `reason: "uncontrolled"` -- the worker is active but did not take the
+ *     page when asked, and the one automatic reload was already spent (or
+ *     could not be guarded) -> `UncontrolledPageError`;
+ *   - `"activation-timeout"` / `"unresponsive"` -- the worker never activated,
+ *     or controls the page but did not answer -> an `Error` naming the worker
+ *     and the bound, and saying what to do;
+ *   - anything else is not a control failure and is returned unchanged.
+ *
+ * The library's own error is kept as `cause`, for DevTools.
+ */
+export declare function edgeStartError(error: unknown, serviceWorkerUrl: string, timeoutMs: number): unknown;
+//# sourceMappingURL=edge-control.d.ts.map

package/dist/edge-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-control.d.ts","sourceRoot":"","sources":["../src/edge-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,6EAA6E;AAC7E,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAOxD;CACF;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,gBAAgB,EAAE,MAAM,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAmBT"}

package/dist/edge-control.js

@@ -0,0 +1,69 @@
+/**
+ * Turning a failure to get the page's ServiceWorker into an error a user can
+ * act on.
+ *
+ * THE HANG THIS USED TO GUARD. A page can load UNCONTROLLED while its worker
+ * is already active -- a HARD RELOAD (Ctrl+Shift+R; Firefox's
+ * `location.reload(true)`) bypasses the worker by spec, and Firefox has left a
+ * second tab uncontrolled too. The worker claimed its clients when it
+ * activated, long ago, so no `controllerchange` ever comes. Up to
+ * `@statewalker/webrun-http-browser` 0.4, `SwHttpAdapter.start()` then waited
+ * forever: llm-chat's mesh.html sat at "Joining… (mounting-edge)" after every
+ * hard reload, and this file carried a reload guard of its own.
+ *
+ * SINCE 0.5 THE LIBRARY RECOVERS IT ITSELF. `start()` asks the active worker to
+ * claim the page again (a `CLAIM` call, answered with `clients.claim()` by the
+ * package's own `sw-worker` -- which is what this stack's `/sw.js` is), so a
+ * hard-reloaded page is taken over in place, with no navigation. Every wait is
+ * bounded by `timeout`; past it `start()` rejects with a
+ * `ServiceWorkerControlError` whose `reason` says which wait failed. And with
+ * `reloadIfUncontrolled` it reloads once, guarded by `sessionStorage`, when the
+ * claim did not take. Measured in Chromium and Firefox by
+ * `packages/httpeers-browser-conformance/scripts/edge-reload.mjs`.
+ *
+ * What is left here is the message: `edgeStartError` maps the library's error
+ * onto the ones `mountEdge` has always thrown, so a page shows "close the tab
+ * and reopen it" rather than a library's diagnostic. It matches on `name` and
+ * `reason`, not `instanceof`: every bundle of webrun-http-browser carries its
+ * own copy of the class.
+ */
+/** The error a page shows when it cannot get its ServiceWorker's control. */
+export class UncontrolledPageError extends Error {
+    constructor(detail, options) {
+        super("This page isn't controlled by its ServiceWorker, so the mesh cannot be reached through " +
+            `it — close the tab and reopen it. (${detail})`, options);
+        this.name = "UncontrolledPageError";
+    }
+}
+function isControlError(error) {
+    return (error instanceof Error &&
+        error.name === "ServiceWorkerControlError" &&
+        typeof error.reason === "string");
+}
+/**
+ * The error `mountEdge` throws when `SwHttpAdapter.start()` rejects:
+ *
+ *   - `reason: "uncontrolled"` -- the worker is active but did not take the
+ *     page when asked, and the one automatic reload was already spent (or
+ *     could not be guarded) -> `UncontrolledPageError`;
+ *   - `"activation-timeout"` / `"unresponsive"` -- the worker never activated,
+ *     or controls the page but did not answer -> an `Error` naming the worker
+ *     and the bound, and saying what to do;
+ *   - anything else is not a control failure and is returned unchanged.
+ *
+ * The library's own error is kept as `cause`, for DevTools.
+ */
+export function edgeStartError(error, serviceWorkerUrl, timeoutMs) {
+    if (!isControlError(error))
+        return error;
+    if (error.reason === "uncontrolled") {
+        return new UncontrolledPageError("its ServiceWorker is active but did not take control when asked, and the page " +
+            "has already been reloaded once to recover, or could not be", { cause: error });
+    }
+    const what = error.reason === "activation-timeout"
+        ? "did not activate"
+        : "did not answer the page, although it controls it,";
+    return new Error(`mountEdge: the ServiceWorker ${serviceWorkerUrl} ${what} within ` +
+        `${Math.round(timeoutMs / 1000)} s. Close the tab and reopen it; if that does not help, ` +
+        "clear this site's data in the browser to remove the ServiceWorker and start clean.", { cause: error });
+}

package/dist/edge-dispatch.d.ts

@@ -0,0 +1,188 @@
+/**
+ * The one module that sits between a page's own `fetch()` and this peer's
+ * `dispatch`. Everything a request needs in order to survive the crossing
+ * page -> ServiceWorker -> `SwHttpAdapter` -> `peer.dispatch` lives here,
+ * and nowhere else -- above all, NOT in the page.
+ *
+ * IT EXISTS SO THAT A PAGE IS AN ORDINARY HTTP CLIENT. The project's
+ * central bet is that application code calls a mesh peer with a plain
+ * `fetch()` -- no SDK, no client library. A page that had to hand-assemble
+ * a bearer header on every call, strip a mount prefix, or parse an error
+ * message string to tell "gone" from "refused" would have an SDK; it would
+ * just be an undocumented one, reimplemented per page. This module is the
+ * runtime's side of that bet.
+ *
+ * Kept dependency-free of libp2p AND of `@statewalker/webrun-http-browser`
+ * on purpose (only `httpeers.core`, all of it pure): that is what lets
+ * every rule below be proven under plain Node in `tests/browser-edge-
+ * dispatch.test.ts` rather than deferred to Task 15's Playwright run.
+ *
+ * THREE JOBS, IN ORDER.
+ *
+ * 1. STRIP THE EDGE'S OWN MOUNT PREFIX. Verified directly against
+ *    `@statewalker/webrun-http-browser@workspace:0.3.3`, not assumed:
+ *    `SwHttpAdapter._handleHttpRequest` (`src/sw/http-sw-dispatcher.ts`)
+ *    selects a handler by `requestUrl.indexOf(urlPrefix) === 0` and then
+ *    calls `handler(request)` with the ORIGINAL, UNMODIFIED request. So a
+ *    page fetching `${baseUrl}${peerId}/search` -- where `baseUrl` ends in
+ *    `/${key}/`, and `key` must be the first path segment
+ *    (`edge-guard.ts`'s `assertKeyMatchesPrefix`; `SwHttpDispatcher` keys
+ *    its channel lookup on that segment, so mounting at `/` is not
+ *    available) -- reaches `dispatch` with pathname
+ *    `/${key}/${peerId}/search`. `httpeers.core`'s router
+ *    (`router.ts`'s `route`) reads the FIRST segment and asks
+ *    `looksLikePeerId`; `key` is not a peer id, so the request is served
+ *    LOCALLY against a path no mount claims -- a 404 whose body says "not
+ *    found", three layers away from the mistake. Stripping the prefix here
+ *    is what makes the router see `/${peerId}/search`, which is the shape
+ *    it documents.
+ *
+ * 2. ATTACH THE MEMBERSHIP TOKEN (Ruling 59). `peer.call()` turns a
+ *    `{ token }` option into a `MESH_TOKEN_HEADER` header (`peer-request.ts`);
+ *    `fetch()` has no such option, so without this every mesh call from a
+ *    page would arrive at the provider tokenless and be refused 401. The
+ *    token is NOT the page's to hold: it rotates on each 5 s heartbeat
+ *    inside `startJoin`'s closure (`join.ts`), so a page that read one and
+ *    kept it would be sending a stale token within seconds. `token()` is
+ *    therefore called per request, never snapshotted.
+ *
+ * 3. TURN A THROWN `PeerCallError` INTO A RESPONSE (Ruling 60). `remote()`
+ *    THROWS T-2's typed error; nothing between it and the page converts it
+ *    to a Response, and `SwHttpDispatcher`'s own catch
+ *    (`http-sw-dispatcher.ts`) collapses any thrown handler error into a
+ *    bare 500 with no body. A page would then see one indistinguishable
+ *    500 for a departed peer, a reset stream and a timeout -- precisely the
+ *    "no way to tell 'this peer is gone' from 'this peer refused you'
+ *    without parsing a message string" that `httpeers.core`'s `errors.ts`
+ *    exists to end. The mapping below forwards `kind` in the body so the
+ *    page can `switch` on it.
+ *
+ * WHY THE STATUS TABLE LIVES IN THE APP AND NOT IN `httpeers.core`. Same
+ * split the core already uses for `allowForward` (supplied by the caller,
+ * never decided in the router): a status code is policy. `errors.ts`
+ * anticipated this crossing -- `kind` exists, in its own words, "so a
+ * caller can `switch` on it, or forward it across a boundary that cannot
+ * carry a class reference" -- but anticipating the crossing is not owning
+ * the status choice.
+ *
+ * 4. MAKE SURE A ROUTE TO THE TARGET PEER EXISTS FIRST (Task 15). Added
+ *    after the Playwright suite found that this had NEVER worked: a page
+ *    calling ANOTHER PAGE got `peer-unreachable`, every time, while a Node
+ *    peer calling that same browser provider over the same relay got a 200.
+ *    The cause is not in the provider and not in the transport --
+ *    `httpeers.core`'s `remote()` dials by PEER ID, which resolves through
+ *    libp2p's peerStore, and a browser peer's peerStore entry for another
+ *    browser peer is either absent or a bare `/p2p-circuit` address that
+ *    libp2p refuses to open `/httpeers/1.0.0` over. Something has to dial
+ *    `<relay>/p2p-circuit/webrtc/p2p/<peer>` explicitly, exactly as
+ *    `peer-runtime.ts` already does for the HUB at startup, and the page
+ *    cannot be the thing that does it without becoming the SDK this module
+ *    exists to prevent. So the edge does it, through the `ensureRoute` hook
+ *    below -- a callback, so this module stays libp2p-free and testable
+ *    under plain Node (see the note above).
+ *
+ *    IT NEVER FAILS THE CALL ITSELF. A dial that throws is swallowed and
+ *    `dispatch` is attempted anyway: the call that follows produces T-2's
+ *    own typed `PeerCallError` -- with the right `kind` for the page to
+ *    render -- whereas a rethrow here would surface as an untyped 500 from
+ *    `SwHttpDispatcher`'s catch and lose exactly the distinction job 3
+ *    exists to preserve.
+ *
+ * THIS IS A LOCAL INGRESS, AND ONLY THAT. Traffic arriving from other peers
+ * over libp2p does NOT come through here -- `serveTransport` dispatches it to
+ * `peer.dispatch` directly, which is what keeps our token off it (handing our
+ * token to inbound traffic would let any peer that can reach us borrow our
+ * membership for a call to a third party).
+ *
+ * So the first thing this does is STRIP the proven-peer header. A page builds
+ * the requests that enter its own edge; a header here is a claim, not a fact,
+ * and nothing downstream can tell the difference. An earlier version branched
+ * on `lookupPeer(req) !== undefined` to mean "arrived from the network" --
+ * correct while that binding was a WeakMap a page could not write, and a
+ * forgery hole the moment it became a header. `tests/ingress-forgery.test.ts`
+ * holds that shut.
+ */
+import type { FetchHandler, PeerErrorKind, PeerIdStr } from "@statewalker/httpeers-core";
+/**
+ * `PeerErrorKind` -> HTTP status, the whole table.
+ *
+ * A timeout is a 504 (`Gateway Timeout`) because that is literally what
+ * happened: this peer, acting as the page's gateway onto the mesh, gave up
+ * waiting for the peer behind it. Everything else is a 502 (`Bad Gateway`):
+ * the upstream peer could not be reached, does not speak the protocol, reset
+ * the stream, blew a relay limit, or offered only a limited connection the
+ * call did not opt in to -- all of them "the gateway could not
+ * get an answer from upstream", none of them a fault in the request the page
+ * made. Deliberately never a 5xx that would blame the page's own request
+ * (a 400-family status), and never a 500: a 500 here is reserved for a
+ * genuine bug (see `createEdgeDispatch`'s rethrow).
+ */
+export declare const PEER_ERROR_STATUS: Readonly<Record<PeerErrorKind, number>>;
+/** The body shape a page reads back from a failed mesh call. `kind` is the discriminant to `switch` on; `error` is for a human, never for a `switch`. */
+export interface PeerErrorBody {
+    error: string;
+    kind: PeerErrorKind;
+    peerId: string;
+}
+export interface EdgeDispatchInit {
+    /** This peer's own router -- `peer.dispatch`. Never called with a modified request unless the request originated locally; see the module comment. */
+    dispatch: FetchHandler;
+    /** The ServiceWorker adapter key. Requests arriving from the page still carry `/${key}` on their path -- job 1 above. */
+    key: string;
+    /** This peer's current membership token, READ AT CALL TIME -- `JoinHandle.token`. */
+    token: () => string;
+    /**
+     * Establish a usable route to `peerId` before the call rides it -- job 4
+     * above. Optional: omitting it restores the pre-Task-15 behaviour, which
+     * is correct for a caller whose peers are already connected (every Node
+     * suite in this app) and broken for a browser page (see job 4).
+     *
+     * CALLED FOR EVERY PEER-ID-SHAPED FIRST SEGMENT, INCLUDING THIS PEER'S
+     * OWN. This module knows the shape of a peer id (`targetPeerId`) and not
+     * which one it is: `createEdgeDispatch` is never told its own peer id, and
+     * giving it one only to skip a call would duplicate a check the
+     * implementation has to make anyway. `join.ts`'s `createRouteEnsurer` is
+     * where "that is us" is recognised and returns immediately. An
+     * implementation that does not know its own id must therefore tolerate
+     * being asked to route to itself.
+     *
+     * Called once per outbound request that names a peer; an implementation is
+     * expected to be cheap when a route already exists, because it is on the
+     * path of every single mesh call the page makes.
+     */
+    ensureRoute?: (peerId: PeerIdStr) => Promise<void>;
+}
+/**
+ * The peer id an outbound request is addressed to -- the first path segment,
+ * when it looks like one -- or `null` for a request this peer serves itself.
+ *
+ * THE SHAPE TEST IS A COPY, AND IT SHOULD NOT BE. `httpeers.core`'s
+ * `router.ts` has exactly this function (`looksLikePeerId`) and it is the
+ * one that decides, three layers down, whether the first segment is treated
+ * as a peer id at all. It is not exported, so this module cannot share it,
+ * and a copy that drifts from it would make `ensureRoute` dial for requests
+ * the router serves locally (harmless -- the dial is skipped for a
+ * non-member) or, worse, skip the dial for requests the router forwards
+ * (the Task 15 bug, back again). Reported to the core package rather than
+ * worked around further; see this task's report.
+ */
+export declare function targetPeerId(pathname: string): PeerIdStr | null;
+/**
+ * Removes a leading `/${key}` segment from `pathname`, respecting segment
+ * boundaries: with `key` `"app"`, `/app/x` -> `/x` and `/app` -> `/`, but
+ * `/application/x` is left alone (it is not this prefix, it merely starts
+ * with the same characters -- the same trap `httpeers.core`'s own mount
+ * matching documents in `router.ts`, "`/test` does NOT match `/testing`").
+ *
+ * Exported for its own test: this is pure string logic and there is no
+ * reason to reach it only through a Request.
+ */
+export declare function stripEdgePrefix(pathname: string, key: string): string;
+/**
+ * Wraps `dispatch` with the three jobs above, for mounting on the
+ * ServiceWorker edge (`edge.ts`'s `mountEdge`). The result is still a plain
+ * `FetchHandler`, so `mountEdge` keeps passing a handler through unchanged
+ * and nothing about that contract changes.
+ */
+export declare function createEdgeDispatch(init: EdgeDispatchInit): FetchHandler;
+//# sourceMappingURL=edge-dispatch.d.ts.map

package/dist/edge-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-dispatch.d.ts","sourceRoot":"","sources":["../src/edge-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuGG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAUzF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAQrE,CAAC;AAEF,yJAAyJ;AACzJ,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,qJAAqJ;IACrJ,QAAQ,EAAE,YAAY,CAAC;IACvB,yHAAyH;IACzH,GAAG,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAO/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CA0EvE"}

package/dist/edge-dispatch.js

@@ -0,0 +1,142 @@
+import { bodyOf, json, MESH_TOKEN_HEADER, PeerCallError, setMeshToken, stripPeerBinding, } from "@statewalker/httpeers-core";
+/**
+ * `PeerErrorKind` -> HTTP status, the whole table.
+ *
+ * A timeout is a 504 (`Gateway Timeout`) because that is literally what
+ * happened: this peer, acting as the page's gateway onto the mesh, gave up
+ * waiting for the peer behind it. Everything else is a 502 (`Bad Gateway`):
+ * the upstream peer could not be reached, does not speak the protocol, reset
+ * the stream, blew a relay limit, or offered only a limited connection the
+ * call did not opt in to -- all of them "the gateway could not
+ * get an answer from upstream", none of them a fault in the request the page
+ * made. Deliberately never a 5xx that would blame the page's own request
+ * (a 400-family status), and never a 500: a 500 here is reserved for a
+ * genuine bug (see `createEdgeDispatch`'s rethrow).
+ */
+export const PEER_ERROR_STATUS = {
+    "request-timeout": 504,
+    "peer-unreachable": 502,
+    "protocol-unsupported": 502,
+    "stream-reset": 502,
+    "relay-limit-exceeded": 502,
+    "limited-connection": 502,
+    unknown: 502,
+};
+/**
+ * The peer id an outbound request is addressed to -- the first path segment,
+ * when it looks like one -- or `null` for a request this peer serves itself.
+ *
+ * THE SHAPE TEST IS A COPY, AND IT SHOULD NOT BE. `httpeers.core`'s
+ * `router.ts` has exactly this function (`looksLikePeerId`) and it is the
+ * one that decides, three layers down, whether the first segment is treated
+ * as a peer id at all. It is not exported, so this module cannot share it,
+ * and a copy that drifts from it would make `ensureRoute` dial for requests
+ * the router serves locally (harmless -- the dial is skipped for a
+ * non-member) or, worse, skip the dial for requests the router forwards
+ * (the Task 15 bug, back again). Reported to the core package rather than
+ * worked around further; see this task's report.
+ */
+export function targetPeerId(pathname) {
+    const [, first = ""] = pathname.split("/");
+    const looksLikePeerId = /^12D3Koo[A-Za-z0-9]{40,}$/.test(first) ||
+        /^Qm[1-9A-HJ-NP-Za-km-z]{44}$/.test(first) ||
+        /^k51[a-z0-9]{55,}$/.test(first);
+    return looksLikePeerId ? first : null;
+}
+/**
+ * Removes a leading `/${key}` segment from `pathname`, respecting segment
+ * boundaries: with `key` `"app"`, `/app/x` -> `/x` and `/app` -> `/`, but
+ * `/application/x` is left alone (it is not this prefix, it merely starts
+ * with the same characters -- the same trap `httpeers.core`'s own mount
+ * matching documents in `router.ts`, "`/test` does NOT match `/testing`").
+ *
+ * Exported for its own test: this is pure string logic and there is no
+ * reason to reach it only through a Request.
+ */
+export function stripEdgePrefix(pathname, key) {
+    const prefix = `/${key}`;
+    if (pathname === prefix)
+        return "/";
+    if (pathname.startsWith(`${prefix}/`))
+        return pathname.slice(prefix.length);
+    return pathname;
+}
+/**
+ * Wraps `dispatch` with the three jobs above, for mounting on the
+ * ServiceWorker edge (`edge.ts`'s `mountEdge`). The result is still a plain
+ * `FetchHandler`, so `mountEdge` keeps passing a handler through unchanged
+ * and nothing about that contract changes.
+ */
+export function createEdgeDispatch(init) {
+    const { dispatch, key } = init;
+    return async function edgeDispatch(req) {
+        // THE EDGE IS A LOCAL INGRESS, ALWAYS. Strip any proven-peer header the
+        // caller supplied: a page builds the requests that enter its own edge, so
+        // a header here is a CLAIM, never a fact, and `withAccess` downstream
+        // cannot tell the two apart.
+        //
+        // This used to return early when a binding was present, on the reading
+        // "it arrived from the network, not ours to touch". That was safe while
+        // the binding lived in a WeakMap no page could write; with a header it
+        // let a page name itself any peer AND skip the token attachment. The
+        // branch is removed rather than repaired, because a network request never
+        // reaches here anyway -- `serveTransport` dispatches to `peer.dispatch`
+        // directly. See `tests/ingress-forgery.test.ts`.
+        stripPeerBinding(req);
+        const url = new URL(req.url);
+        url.pathname = stripEdgePrefix(url.pathname, key);
+        // `new Request(url, req)` reads `req.body` off the init object -- and
+        // FIREFOX HAS NO `Request.prototype.body` (checked against 155), so that
+        // read is `undefined` there and the outbound request loses its body
+        // entirely, silently. Rebuilt explicitly through `bodyOf`, the one copy
+        // of this logic, exactly as `gateway.ts` and the ghost's `pin.ts` already
+        // do for the same reason.
+        const body = await bodyOf(req);
+        const outbound = new Request(url, {
+            method: req.method,
+            headers: req.headers,
+            body,
+            ...(body instanceof ReadableStream ? { duplex: "half" } : {}),
+            signal: req.signal,
+        });
+        // NEVER OVERWRITE A CALLER'S OWN MEMBERSHIP TOKEN. A page that set one
+        // deliberately -- calling a peer with a token it was handed out of band,
+        // or testing what a provider does with a bad one -- meant it, and
+        // silently replacing it would make that call untestable and its failure
+        // inexplicable.
+        //
+        // `Authorization` is not looked at at all. It is the page's header for
+        // the application it is calling (LiteLLM's dashboard puts its own key
+        // there); when the token lived in it too, a page that set it got no mesh
+        // token and the provider refused the application key `malformed-token`.
+        if (!outbound.headers.has(MESH_TOKEN_HEADER)) {
+            setMeshToken(outbound.headers, init.token());
+        }
+        // Job 4. Before the call, not after a failure: a retry-on-failure shape
+        // would turn every genuinely-unreachable peer into two attempts and a
+        // doubled wait, and it would still be wrong for the case that matters
+        // (the first call to a peer this page has never dialed, which is most
+        // of them).
+        const target = targetPeerId(url.pathname);
+        if (init.ensureRoute != null && target != null) {
+            // Swallowed deliberately -- see job 4's second paragraph.
+            await init.ensureRoute(target).catch((err) => {
+                console.warn(`edge: could not establish a route to ${target}:`, err);
+            });
+        }
+        try {
+            return await dispatch(outbound);
+        }
+        catch (err) {
+            // `instanceof` ONLY, and rethrow everything else. A genuine bug in a
+            // handler must still surface as `SwHttpDispatcher`'s 500 rather than
+            // be dressed up as a network condition the page will politely offer
+            // to retry -- the failure mode this mapping exists to prevent, turned
+            // inside out.
+            if (!(err instanceof PeerCallError))
+                throw err;
+            const body = { error: err.message, kind: err.kind, peerId: err.peerId };
+            return json(body, PEER_ERROR_STATUS[err.kind]);
+        }
+    };
+}

package/dist/edge-guard.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 declare function assertKeyMatchesPrefix(key: string, prefix: string): void;
+//# sourceMappingURL=edge-guard.d.ts.map

package/dist/edge-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-guard.d.ts","sourceRoot":"","sources":["../src/edge-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAsBxE"}