@statewalker/httpeers-share 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Kotelnikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# @statewalker/httpeers-share
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## What it is
+
+Sharing an HTTP service with the members of an httpeers mesh. It covers:
+- how the Sharer reaches the service (upstream kinds);
+- what may be shared (policy);
+- whether it works for Guests (probe);
+- how Guests see it (service table);
+- how they are invited (invite links);
+- what a failed join means (join outcome).
+
+`./bridge` is the PeerShare Bridge, for Node and Bun only.
+
+## Why it exists
+
+PeerShare (a SandClaw app: share a local HTTP service with invited Guests) needs the same
+rules in the Sharer's browser tab, in the Bridge and in tests. Everything here was proven in
+a prototype rung first (`statewalker-sandbox`, `apps/peershare-protos`, whose rung READMEs
+say why each rule is the way it is) and moved here with its tests.
+
+## How to use
+
+```sh
+pnpm add @statewalker/httpeers-share
+```
+
+| Import | Gives | Runs in | Rung |
+|---|---|---|---|
+| `.` | `createUpstream`, `unreachable`, the `BRIDGE_*` header contract | anywhere | 01 |
+| `.` | `checkServiceTarget` (v1 policy), `checkTarget`, `isPrivateAddress` | anywhere | 04, 02 |
+| `.` | `probe` | anywhere | 04 |
+| `.` | `serviceTable` (catalog at `/s/`, Pause, routing) | anywhere | 07 |
+| `.` | `encodeInvite`, `decodeInvite` | anywhere | 06 |
+| `.` | `joinOutcome`, `revokeGuest`, `isSharerOffline`, `stampGuest` | anywhere | 09, 10, 16 |
+| `.` | `openTunnel`, `sharerSocket`, `encodeFrame`/`decodeFrames`: a WebSocket inside one full-duplex mesh request | anywhere | 15 |
+| `./bridge` | `createBridge` (HTTP and its WebSocket gate), `listenLoopback` (Node), `connectApp`/`relaySocket` (for a Bun host) | Node, Bun | 02, 03, 16 |
+
+## Examples
+
+```ts
+import { createUpstream, serviceTable, checkServiceTarget } from "@statewalker/httpeers-share";
+
+checkServiceTarget("direct", "http://api.example.com"); // { ok: false, reason: "needs-https" }
+
+const upstream = createUpstream({
+  kind: "bridged",
+  target: "http://localhost:5173",
+  bridge: { base: "http://127.0.0.1:9090", token },
+});
+const mount = serviceTable(
+  () => [{ id: "foo", name: "fooService", upstream, enabled: true, isDefault: true }],
+  { sharerName: "Dirk" },
+); // the Sharer's `/s` mount
+```
+
+## Internals
+
+- The root entry point is isomorphic. `tests/boundary.test.ts` fails if any file under `src/`
+  (other than `src/bridge/`) imports a `node:` module.
+- Tests run against real ports and the real Bridge. `tests/fixtures.ts` includes a stand-in
+  Bridge, kept on purpose: it proves the upstream depends only on the wire contract.
+- `service-table`, `join-outcome` and `stamp-guest` were tested over the mesh in the rungs.
+  Their unit tests here characterise code that moved, and passed on their first run.
+
+- `./bridge` serves with `@hono/node-server`'s `overrideGlobalObjects: false`. By default that
+  server replaces the process's global `Request`/`Response`, which stalls streaming fetches
+  (the mesh member's full-duplex requests) everywhere else in the process.
+
+```sh
+pnpm --filter @statewalker/httpeers-share test
+```
+
+## License
+
+MIT

package/dist/bridge/bridge.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The Bridge: a loopback relay from the PeerShare page to the Sharer's local
+ * Services, speaking rung 01's wire contract.
+ *
+ * A loopback port that answers cross-origin requests is reachable by EVERY
+ * website the Sharer visits. Each rule below closes one way in; the tests in
+ * `../tests/` name them.
+ */
+import { type FetchHandler } from "@statewalker/webrun-http-proxy";
+import { type SocketGate } from "./sockets.js";
+export interface BridgeInit {
+    /** The Pairing token generated at launch; nothing is answered without it. */
+    token: string;
+    /** The PeerShare page's origin; the only one granted cross-origin access. */
+    allowedOrigin: string;
+    /** Injected by tests; defaults to the platform's. */
+    fetchImpl?: typeof fetch;
+    /** Every address a `.local` name resolves to. Injected by tests; defaults to the OS resolver. */
+    resolveHost?: (name: string) => Promise<string[]>;
+    /**
+     * Keep one cookie jar per Guest (rung 16, spike): a Service's `Set-Cookie`
+     * goes into the jar of the Guest named in `x-peershare-guest`, and that
+     * jar's cookies go on the Guest's next requests. Cookies never reach the
+     * page, which could not use them anyway.
+     */
+    cookieJars?: boolean;
+}
+/** Whether the Bridge may relay to `target` (rung 02 rules): `ok`, `forbidden` or `unreachable`. */
+export declare function reachable(target: string, resolveHost: (name: string) => Promise<string[]>): Promise<"ok" | "forbidden" | "unreachable">;
+export declare function systemResolve(name: string): Promise<string[]>;
+/** The Bridge's HTTP handler, carrying its WebSocket gate for whichever server hosts it. */
+export type BridgeHandler = FetchHandler & {
+    sockets: SocketGate;
+};
+export declare function createBridge(init: BridgeInit): BridgeHandler;
+export declare function sameSecret(given: string | null, expected: string): boolean;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/bridge/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,KAAK,YAAY,EAAuB,MAAM,gCAAgC,CAAC;AAYxF,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,cAAc,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,iGAAiG;IACjG,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAClD;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,oGAAoG;AACpG,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GAC/C,OAAO,CAAC,IAAI,GAAG,WAAW,GAAG,aAAa,CAAC,CAO7C;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAGnE;AAED,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG;IAAE,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC;AAEnE,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,aAAa,CA+E5D;AAsDD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAK1E"}

package/dist/bridge/bridge.js

@@ -0,0 +1,195 @@
+/**
+ * The Bridge: a loopback relay from the PeerShare page to the Sharer's local
+ * Services, speaking rung 01's wire contract.
+ *
+ * A loopback port that answers cross-origin requests is reachable by EVERY
+ * website the Sharer visits. Each rule below closes one way in; the tests in
+ * `../tests/` name them.
+ */
+import { timingSafeEqual } from "node:crypto";
+import { MARKER, urlUpstream } from "@statewalker/webrun-http-proxy";
+import { checkTarget, isPrivateAddress } from "../targets.js";
+import { BRIDGE_COOKIES_KEPT_HEADER, BRIDGE_GUEST_HEADER, BRIDGE_MARKER, BRIDGE_REDIRECT_LOCATION_HEADER, BRIDGE_REDIRECT_STATUS_HEADER, BRIDGE_SET_COOKIE_HEADER, BRIDGE_TARGET_HEADER, BRIDGE_TOKEN_HEADER, } from "../upstreams.js";
+import { socketGate } from "./sockets.js";
+/** Whether the Bridge may relay to `target` (rung 02 rules): `ok`, `forbidden` or `unreachable`. */
+export async function reachable(target, resolveHost) {
+    const verdict = checkTarget(target);
+    if (verdict === "forbidden")
+        return "forbidden";
+    if (verdict === "allowed")
+        return "ok";
+    const addresses = await resolveHost(verdict.resolve).catch(() => []);
+    if (addresses.length === 0)
+        return "unreachable";
+    return addresses.every(isPrivateAddress) ? "ok" : "forbidden";
+}
+export async function systemResolve(name) {
+    const { lookup } = await import("node:dns/promises");
+    return (await lookup(name, { all: true })).map((a) => a.address);
+}
+export function createBridge(init) {
+    const resolveHost = init.resolveHost ?? systemResolve;
+    const jars = new Map();
+    const handler = async (incoming) => {
+        const guest = init.cookieJars === true ? incoming.headers.get(BRIDGE_GUEST_HEADER) : null;
+        const jar = guest == null ? undefined : (jars.get(guest) ?? jars.set(guest, new Map()).get(guest));
+        const request = jar == null ? incoming : withCookies(incoming, jar);
+        // A page on another site carries its own `Origin`. No `Origin` at all is
+        // a local process (curl, the Probe's CLI): the token alone admits it.
+        const origin = request.headers.get("origin");
+        if (origin != null && origin !== init.allowedOrigin)
+            return refuse(403, "origin-forbidden");
+        // A preflight never carries custom headers, so it cannot carry the token:
+        // the origin check above is all that guards it, and it grants nothing
+        // but permission to send the real, token-bearing request.
+        if (origin != null &&
+            request.method === "OPTIONS" &&
+            request.headers.has("access-control-request-method")) {
+            return preflight(request, origin);
+        }
+        if (!sameSecret(request.headers.get(BRIDGE_TOKEN_HEADER), init.token)) {
+            return refuse(401, "bad-token", origin);
+        }
+        // No target: the page is asking whether its Bridge is there and its
+        // token is right (the token check above already passed).
+        const target = request.headers.get(BRIDGE_TARGET_HEADER) || null;
+        if (target == null) {
+            const headers = new Headers({ "content-type": "application/json" });
+            if (origin != null)
+                grantTo(headers, origin);
+            return new Response(JSON.stringify({ bridge: "peershare" }), { headers });
+        }
+        // The page passed both checks, so it may read WHY the target was refused.
+        const reach = await reachable(target, resolveHost);
+        if (reach !== "ok")
+            return refuse(reach === "forbidden" ? 403 : 502, `target-${reach}`, origin);
+        // The same re-issuing the page itself does (rung 01): hop-by-hop headers
+        // dropped, body streamed, redirects reported. The Bridge's own headers
+        // are consumed by this hop.
+        const upstream = urlUpstream({
+            base: target,
+            stripRequestHeaders: [BRIDGE_TARGET_HEADER, BRIDGE_TOKEN_HEADER, BRIDGE_GUEST_HEADER],
+            ...(init.fetchImpl != null ? { fetchImpl: init.fetchImpl } : {}),
+        });
+        const response = await upstream(request);
+        // The proxy's own "unreachable" is about the SERVICE here. Passed on as
+        // is, the page's upstream (to which the Bridge is the upstream) would
+        // read it as "the Bridge is down" — so it is restated in the contract's
+        // words, and the proxy's marker removed.
+        if (response.headers.get(MARKER) === "upstream-unreachable") {
+            return refuse(502, "target-unreachable", origin);
+        }
+        const headers = new Headers(response.headers);
+        headers.set(BRIDGE_MARKER, "relayed");
+        const cookies = response.headers.getSetCookie();
+        if (cookies.length > 0)
+            headers.set(BRIDGE_SET_COOKIE_HEADER, String(cookies.length));
+        if (jar != null) {
+            for (const cookie of cookies)
+                keep(jar, cookie);
+            headers.delete("set-cookie");
+            if (cookies.length > 0)
+                headers.set(BRIDGE_COOKIES_KEPT_HEADER, "kept");
+        }
+        const location = response.headers.get("location");
+        if (response.status >= 300 && response.status < 400 && location != null) {
+            headers.delete("location");
+            headers.set(BRIDGE_REDIRECT_STATUS_HEADER, String(response.status));
+            headers.set(BRIDGE_REDIRECT_LOCATION_HEADER, withinService(location, target));
+            if (origin != null)
+                grantTo(headers, origin);
+            return new Response(null, { status: 200, headers });
+        }
+        if (origin != null)
+            grantTo(headers, origin);
+        return new Response(response.body, { status: response.status, headers });
+    };
+    return Object.assign(handler, { sockets: socketGate(init, resolveHost) });
+}
+/**
+ * A location on the Service itself, as a path: the Guest sees the Service at
+ * the root of their own origin, so `http://127.0.0.1:5173/login` must become
+ * `/login`. Anywhere else stays absolute.
+ */
+function withinService(location, target) {
+    const resolved = new URL(location, target);
+    if (resolved.origin !== new URL(target).origin)
+        return resolved.href;
+    return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+}
+function preflight(request, origin) {
+    const headers = new Headers({
+        "access-control-allow-origin": origin,
+        vary: "Origin",
+        // Echoed: Guests' requests carry whatever headers the shared app uses.
+        "access-control-allow-methods": request.headers.get("access-control-request-method") ?? "GET",
+        "access-control-allow-headers": request.headers.get("access-control-request-headers") ?? "",
+        "access-control-max-age": "600",
+    });
+    // Chromium's Private Network Access preflight: a public page asking for loopback.
+    if (request.headers.get("access-control-request-private-network") === "true") {
+        headers.set("access-control-allow-private-network", "true");
+    }
+    return new Response(null, { status: 204, headers });
+}
+/**
+ * Cross-origin permission for exactly one origin. Whatever the Service itself
+ * sends (`*`, credentials) is replaced: the Service's CORS policy was written
+ * for its own pages, not for a relay that every website can try to reach.
+ */
+function grantTo(headers, origin) {
+    for (const name of [...headers.keys()]) {
+        if (name.startsWith("access-control-"))
+            headers.delete(name);
+    }
+    headers.set("access-control-allow-origin", origin);
+    headers.append("vary", "Origin");
+    // Every response header, the marker included, readable by the page.
+    headers.set("access-control-expose-headers", [...headers.keys()].join(", "));
+}
+/**
+ * A refusal carries no CORS headers unless `grantTo` is given: a foreign page
+ * cannot even read why it was refused.
+ */
+function refuse(status, reason, grantToOrigin) {
+    const headers = new Headers({ [BRIDGE_MARKER]: reason });
+    if (grantToOrigin != null)
+        grantTo(headers, grantToOrigin);
+    return new Response(null, { status, headers });
+}
+export function sameSecret(given, expected) {
+    if (given == null)
+        return false;
+    const a = new TextEncoder().encode(given);
+    const b = new TextEncoder().encode(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** `request` with `jar`'s cookies as its `Cookie` header (the page cannot send one itself). */
+function withCookies(request, jar) {
+    if (jar.size === 0)
+        return request;
+    const headers = new Headers(request.headers);
+    headers.set("cookie", [...jar].map(([name, value]) => `${name}=${value}`).join("; "));
+    // Rebuilt from its parts: the server's own request object (e.g.
+    // @hono/node-server's) need not be one the global Request can copy.
+    const body = request.method === "GET" || request.method === "HEAD" ? null : request.body;
+    return new Request(request.url, {
+        method: request.method,
+        headers,
+        body,
+        ...(body != null ? { duplex: "half" } : {}),
+        signal: request.signal,
+    });
+}
+/** A spike's cookie jar: name and value only; `Max-Age=0` deletes. Path, domain and expiry are ignored. */
+function keep(jar, setCookie) {
+    const [pair = "", ...attributes] = setCookie.split(";");
+    const at = pair.indexOf("=");
+    if (at <= 0)
+        return;
+    const name = pair.slice(0, at).trim();
+    if (attributes.some((a) => /^\s*max-age\s*=\s*0\s*$/i.test(a)))
+        jar.delete(name);
+    else
+        jar.set(name, pair.slice(at + 1).trim());
+}

package/dist/bridge/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The Bridge (Node and Bun only): a locked-down loopback relay from the
+ * PeerShare page to the Sharer's local Services, with per-Guest cookie jars.
+ */
+export { type BridgeHandler, type BridgeInit, createBridge } from "./bridge.js";
+export { type Listening, listenLoopback } from "./serve.js";
+export { acceptedProtocol, connectApp, type InboundSocket, relaySocket, SOCKET_PATH, type SocketGate, type SocketPlan, TOKEN_PROTOCOL_PREFIX, } from "./sockets.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/bridge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bridge/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,KAAK,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,KAAK,aAAa,EAClB,WAAW,EACX,WAAW,EACX,KAAK,UAAU,EACf,KAAK,UAAU,EACf,qBAAqB,GACtB,MAAM,cAAc,CAAC"}

package/dist/bridge/index.js

@@ -0,0 +1,7 @@
+/**
+ * The Bridge (Node and Bun only): a locked-down loopback relay from the
+ * PeerShare page to the Sharer's local Services, with per-Guest cookie jars.
+ */
+export { createBridge } from "./bridge.js";
+export { listenLoopback } from "./serve.js";
+export { acceptedProtocol, connectApp, relaySocket, SOCKET_PATH, TOKEN_PROTOCOL_PREFIX, } from "./sockets.js";

package/dist/bridge/serve.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The Bridge on a port, under Node. Under Bun, `main.ts` hands the same
+ * handler to `Bun.serve`.
+ */
+import type { FetchHandler } from "@statewalker/webrun-http-proxy";
+import { type SocketGate } from "./sockets.js";
+export interface Listening {
+    origin: string;
+    /** The interface actually bound. */
+    address: string;
+    close(): Promise<void>;
+}
+/**
+ * Binds 127.0.0.1 only: the Bridge is never reachable from the network. A
+ * handler carrying a socket gate (`createBridge`'s) also relays WebSockets.
+ */
+export declare function listenLoopback(handler: FetchHandler & {
+    sockets?: SocketGate;
+}, port?: number): Promise<Listening>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/bridge/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/bridge/serve.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAEnE,OAAO,EAA6C,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1F,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,GAAG;IAAE,OAAO,CAAC,EAAE,UAAU,CAAA;CAAE,EAChD,IAAI,SAAI,GACP,OAAO,CAAC,SAAS,CAAC,CA6DpB"}

package/dist/bridge/serve.js

@@ -0,0 +1,66 @@
+/**
+ * The Bridge on a port, under Node. Under Bun, `main.ts` hands the same
+ * handler to `Bun.serve`.
+ */
+import { serve } from "@hono/node-server";
+import { WebSocketServer } from "ws";
+import { acceptedProtocol, connectApp, relaySocket } from "./sockets.js";
+/**
+ * Binds 127.0.0.1 only: the Bridge is never reachable from the network. A
+ * handler carrying a socket gate (`createBridge`'s) also relays WebSockets.
+ */
+export function listenLoopback(handler, port = 0) {
+    return new Promise((resolve) => {
+        // `overrideGlobalObjects: false`: by default @hono/node-server swaps the
+        // process's global Request and Response for its own, which breaks streaming
+        // request bodies for everything else in the process (found in M9: the mesh
+        // member's full-duplex fetch stalled while a Bridge ran in the same process).
+        const server = serve({ fetch: handler, port, hostname: "127.0.0.1", overrideGlobalObjects: false }, (info) => {
+            resolve({
+                origin: `http://127.0.0.1:${info.port}`,
+                address: info.address,
+                close: () => new Promise((done) => {
+                    for (const client of wss.clients)
+                        client.terminate();
+                    if ("closeAllConnections" in server)
+                        server.closeAllConnections();
+                    server.close(() => done());
+                }),
+            });
+        });
+        // The subprotocol to accept travels on the request itself, so concurrent
+        // upgrades cannot take each other's.
+        const accepts = new WeakMap();
+        const wss = new WebSocketServer({
+            noServer: true,
+            handleProtocols: (_offered, req) => accepts.get(req) ?? false,
+        });
+        server.on("upgrade", async (req, socket, head) => {
+            const gate = handler.sockets;
+            const headers = new Headers();
+            for (const [k, v] of Object.entries(req.headers))
+                if (typeof v === "string")
+                    headers.set(k, v);
+            const verdict = gate == null
+                ? { ok: false, status: 400 }
+                : await gate(new URL(req.url ?? "/", "http://bridge"), headers);
+            if (!verdict.ok) {
+                socket.end(`HTTP/1.1 ${verdict.status} Refused\r\nconnection: close\r\n\r\n`);
+                return;
+            }
+            const plan = verdict.plan;
+            const app = await connectApp(plan).catch(() => null);
+            if (app == null) {
+                socket.end("HTTP/1.1 502 Refused\r\nconnection: close\r\n\r\n");
+                return;
+            }
+            const offered = (req.headers["sec-websocket-protocol"] ?? "").split(",").map((p) => p.trim());
+            accepts.set(req, acceptedProtocol(plan, app, offered));
+            wss.handleUpgrade(req, socket, head, (ws) => {
+                const relay = relaySocket({ send: (data) => ws.send(data), close: (code, reason) => ws.close(code, reason) }, app);
+                ws.on("message", (data, isBinary) => relay.message(isBinary ? new Uint8Array(data).buffer : String(data)));
+                ws.on("close", (code, reason) => relay.close(code, String(reason)));
+            });
+        });
+    });
+}

package/dist/bridge/sockets.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The Bridge's WebSockets (M9): `/.peershare/socket?target=<url>&protocols=a,b`.
+ *
+ * Guarded exactly like HTTP (rung 02): the PeerShare origin only, the
+ * Pairing token (as the subprotocol `peershare.<token>`, because a browser
+ * cannot set headers on a WebSocket), and the same target rules. Then one
+ * socket to the app is relayed message for message, both ways.
+ */
+import type { BridgeInit } from "./bridge.js";
+export declare const SOCKET_PATH = "/.peershare/socket";
+export declare const TOKEN_PROTOCOL_PREFIX = "peershare.";
+export interface SocketPlan {
+    /** The app's WebSocket URL. */
+    target: string;
+    /** The subprotocols to offer the app. */
+    protocols: string[];
+    /** The one the Bridge accepts from the page (its token protocol). */
+    accept: string;
+}
+export type SocketGate = (url: URL, headers: Headers) => Promise<{
+    ok: true;
+    plan: SocketPlan;
+} | {
+    ok: false;
+    status: 400 | 401 | 403 | 502;
+}>;
+export declare function socketGate(init: Pick<BridgeInit, "token" | "allowedOrigin">, resolveHost: (name: string) => Promise<string[]>): SocketGate;
+/** The page's side of a relayed socket, whatever server accepted it. */
+export interface InboundSocket {
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Open the app's socket first: the page's upgrade is completed only once the
+ * app has accepted, so the page can be given the subprotocol the APP chose
+ * (a WebSocket's protocol is fixed by its handshake). Rejects if the app
+ * refuses or cannot be reached.
+ */
+export declare function connectApp(plan: SocketPlan): Promise<WebSocket>;
+/** The subprotocol to accept from the page: the app's choice when the page offered it, else the token's. */
+export declare function acceptedProtocol(plan: SocketPlan, app: WebSocket, offered: string[]): string;
+/** Relay two open sockets, message for message, both ways; returns the inbound side's event sinks. */
+export declare function relaySocket(inbound: InboundSocket, app: WebSocket): {
+    message(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+};
+//# sourceMappingURL=sockets.d.ts.map

package/dist/bridge/sockets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sockets.d.ts","sourceRoot":"","sources":["../../src/bridge/sockets.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,eAAO,MAAM,WAAW,uBAAuB,CAAC;AAChD,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD,MAAM,WAAW,UAAU;IACzB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,CACvB,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,OAAO,KACb,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;CAAE,CAAC,CAAC;AAE5F,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,EACjD,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GAC/C,UAAU,CA6BZ;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAY/D;AAED,4GAA4G;AAC5G,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAE5F;AAID,sGAAsG;AACtG,wBAAgB,WAAW,CACzB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,SAAS,GACb;IAAE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAa5F"}

package/dist/bridge/sockets.js

@@ -0,0 +1,86 @@
+/**
+ * The Bridge's WebSockets (M9): `/.peershare/socket?target=<url>&protocols=a,b`.
+ *
+ * Guarded exactly like HTTP (rung 02): the PeerShare origin only, the
+ * Pairing token (as the subprotocol `peershare.<token>`, because a browser
+ * cannot set headers on a WebSocket), and the same target rules. Then one
+ * socket to the app is relayed message for message, both ways.
+ */
+import { reachable, sameSecret } from "./bridge.js";
+export const SOCKET_PATH = "/.peershare/socket";
+export const TOKEN_PROTOCOL_PREFIX = "peershare.";
+export function socketGate(init, resolveHost) {
+    return async (url, headers) => {
+        if (url.pathname !== SOCKET_PATH)
+            return { ok: false, status: 400 };
+        const origin = headers.get("origin");
+        if (origin != null && origin !== init.allowedOrigin)
+            return { ok: false, status: 403 };
+        const offered = (headers.get("sec-websocket-protocol") ?? "").split(",").map((p) => p.trim());
+        const accept = offered.find((p) => p.startsWith(TOKEN_PROTOCOL_PREFIX) &&
+            sameSecret(p.slice(TOKEN_PROTOCOL_PREFIX.length), init.token));
+        if (accept == null)
+            return { ok: false, status: 401 };
+        const target = url.searchParams.get("target") ?? "";
+        let http;
+        try {
+            http = new URL(target);
+        }
+        catch {
+            return { ok: false, status: 400 };
+        }
+        const reach = await reachable(http.href.replace(/^ws/, "http"), resolveHost);
+        if (reach !== "ok")
+            return { ok: false, status: reach === "forbidden" ? 403 : 502 };
+        const ws = new URL(http);
+        ws.protocol = http.protocol === "https:" || http.protocol === "wss:" ? "wss:" : "ws:";
+        const protocols = (url.searchParams.get("protocols") ?? "").split(",").filter(Boolean);
+        return { ok: true, plan: { target: ws.href, protocols, accept } };
+    };
+}
+/**
+ * Open the app's socket first: the page's upgrade is completed only once the
+ * app has accepted, so the page can be given the subprotocol the APP chose
+ * (a WebSocket's protocol is fixed by its handshake). Rejects if the app
+ * refuses or cannot be reached.
+ */
+export function connectApp(plan) {
+    return new Promise((resolve, reject) => {
+        const app = new WebSocket(plan.target, plan.protocols);
+        app.binaryType = "arraybuffer";
+        // An app often speaks first ("hello" on connect), before the page's side
+        // is upgraded and relaying: held here, delivered first by `relaySocket`.
+        const held = [];
+        early.set(app, held);
+        app.onmessage = (e) => held.push(e.data);
+        app.onopen = () => resolve(app);
+        app.onerror = () => reject(new Error(`the app's socket at ${plan.target} refused`));
+    });
+}
+/** The subprotocol to accept from the page: the app's choice when the page offered it, else the token's. */
+export function acceptedProtocol(plan, app, offered) {
+    return app.protocol !== "" && offered.includes(app.protocol) ? app.protocol : plan.accept;
+}
+const early = new WeakMap();
+/** Relay two open sockets, message for message, both ways; returns the inbound side's event sinks. */
+export function relaySocket(inbound, app) {
+    for (const data of early.get(app)?.splice(0) ?? [])
+        inbound.send(data);
+    app.onmessage = (e) => inbound.send(e.data);
+    app.onclose = (e) => inbound.close(closable(e.code), e.reason);
+    app.onerror = () => inbound.close(1011, "the app's socket failed");
+    return {
+        message(data) {
+            if (app.readyState === WebSocket.OPEN)
+                app.send(data);
+        },
+        close(code, reason) {
+            if (app.readyState <= WebSocket.OPEN)
+                app.close(closable(code), reason);
+        },
+    };
+}
+/** A code `close()` may be called with (1000, or 3000–4999); anything else becomes 1000. */
+function closable(code) {
+    return code === 1000 || (code != null && code >= 3000 && code <= 4999) ? code : 1000;
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Sharing an HTTP service with the members of an httpeers mesh: how the
+ * Sharer reaches it (upstream kinds), what may be shared (policy), whether it
+ * works for Guests (probe), how Guests see it (service table), how they are
+ * invited (invite link), and what a failed join means (join outcome).
+ *
+ * Isomorphic and UI-free: no DOM, no `node:` module.
+ */
+export { decodeInvite, encodeInvite, type InviteLink } from "./invite-link.js";
+export { type JoinOutcome, joinOutcome } from "./join-outcome.js";
+export { isSharerOffline, revokeGuest } from "./lifecycle.js";
+export { checkServiceTarget, type ServiceKind, type TargetCheck, type TargetRefusal, } from "./policy.js";
+export { type Health, type ProbeCause, type ProbeReport, type ProbeWarning, probe, SLOW_MS, } from "./probe.js";
+export { type CatalogEntry, SERVICE_MARKER, type ServiceEntry, serviceTable, } from "./service-table.js";
+export { decodeFrames, encodeFrame, SOCKET_HEADER, type SocketFrame } from "./socket-frames.js";
+export { openTunnel, sharerSocket, TunnelSocket } from "./socket-tunnel.js";
+export { stampGuest } from "./stamp-guest.js";
+export { checkTarget, isPrivateAddress, type TargetVerdict } from "./targets.js";
+export { BRIDGE_COOKIES_KEPT_HEADER, BRIDGE_GUEST_HEADER, BRIDGE_MARKER, BRIDGE_REDIRECT_LOCATION_HEADER, BRIDGE_REDIRECT_STATUS_HEADER, BRIDGE_SET_COOKIE_HEADER, BRIDGE_TARGET_HEADER, BRIDGE_TOKEN_HEADER, createUpstream, PROBE_GUEST, type UpstreamConfig, unreachable, } from "./upstreams.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAAE,KAAK,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EACL,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,EACL,OAAO,GACR,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,YAAY,EACjB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,aAAa,EACb,+BAA+B,EAC/B,6BAA6B,EAC7B,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,KAAK,cAAc,EACnB,WAAW,GACZ,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * Sharing an HTTP service with the members of an httpeers mesh: how the
+ * Sharer reaches it (upstream kinds), what may be shared (policy), whether it
+ * works for Guests (probe), how Guests see it (service table), how they are
+ * invited (invite link), and what a failed join means (join outcome).
+ *
+ * Isomorphic and UI-free: no DOM, no `node:` module.
+ */
+export { decodeInvite, encodeInvite } from "./invite-link.js";
+export { joinOutcome } from "./join-outcome.js";
+export { isSharerOffline, revokeGuest } from "./lifecycle.js";
+export { checkServiceTarget, } from "./policy.js";
+export { probe, SLOW_MS, } from "./probe.js";
+export { SERVICE_MARKER, serviceTable, } from "./service-table.js";
+export { decodeFrames, encodeFrame, SOCKET_HEADER } from "./socket-frames.js";
+export { openTunnel, sharerSocket, TunnelSocket } from "./socket-tunnel.js";
+export { stampGuest } from "./stamp-guest.js";
+export { checkTarget, isPrivateAddress } from "./targets.js";
+export { BRIDGE_COOKIES_KEPT_HEADER, BRIDGE_GUEST_HEADER, BRIDGE_MARKER, BRIDGE_REDIRECT_LOCATION_HEADER, BRIDGE_REDIRECT_STATUS_HEADER, BRIDGE_SET_COOKIE_HEADER, BRIDGE_TARGET_HEADER, BRIDGE_TOKEN_HEADER, createUpstream, PROBE_GUEST, unreachable, } from "./upstreams.js";