@statewalker/httpeers-share 0.0.0-stage → 0.2.0

package/src/bridge/bridge.ts

@@ -0,0 +1,229 @@
+/**
+ * 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 { type FetchHandler, 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 { type SocketGate, 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 async function reachable(
+  target: string,
+  resolveHost: (name: string) => Promise<string[]>,
+): Promise<"ok" | "forbidden" | "unreachable"> {
+  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: string): Promise<string[]> {
+  const { lookup } = await import("node:dns/promises");
+  return (await lookup(name, { all: true })).map((a) => a.address);
+}
+
+/** The Bridge's HTTP handler, carrying its WebSocket gate for whichever server hosts it. */
+export type BridgeHandler = FetchHandler & { sockets: SocketGate };
+
+export function createBridge(init: BridgeInit): BridgeHandler {
+  const resolveHost = init.resolveHost ?? systemResolve;
+  const jars = new Map<string, Map<string, string>>();
+  const handler: FetchHandler = 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: string, target: string): string {
+  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: Request, origin: string): Response {
+  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: Headers, origin: string): void {
+  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: number, reason: string, grantToOrigin?: string | null): Response {
+  const headers = new Headers({ [BRIDGE_MARKER]: reason });
+  if (grantToOrigin != null) grantTo(headers, grantToOrigin);
+  return new Response(null, { status, headers });
+}
+
+export function sameSecret(given: string | null, expected: string): boolean {
+  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: Request, jar: Map<string, string>): Request {
+  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" as const } : {}),
+    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: Map<string, string>, setCookie: string): void {
+  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/src/bridge/index.ts

@@ -0,0 +1,17 @@
+/**
+ * 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";

package/src/bridge/serve.ts

@@ -0,0 +1,88 @@
+/**
+ * The Bridge on a port, under Node. Under Bun, `main.ts` hands the same
+ * handler to `Bun.serve`.
+ */
+
+import type { IncomingMessage } from "node:http";
+import type { AddressInfo, Socket } from "node:net";
+import { serve } from "@hono/node-server";
+import type { FetchHandler } from "@statewalker/webrun-http-proxy";
+import { WebSocketServer } from "ws";
+import { acceptedProtocol, connectApp, relaySocket, 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 function listenLoopback(
+  handler: FetchHandler & { sockets?: SocketGate },
+  port = 0,
+): Promise<Listening> {
+  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: AddressInfo) => {
+        resolve({
+          origin: `http://127.0.0.1:${info.port}`,
+          address: info.address,
+          close: () =>
+            new Promise<void>((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<IncomingMessage, string>();
+    const wss = new WebSocketServer({
+      noServer: true,
+      handleProtocols: (_offered, req) => accepts.get(req) ?? false,
+    });
+    server.on("upgrade", async (req: IncomingMessage, socket: Socket, head: Buffer) => {
+      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 as const, 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 as Buffer).buffer : String(data)),
+        );
+        ws.on("close", (code, reason) => relay.close(code, String(reason)));
+      });
+    });
+  });
+}

package/src/bridge/sockets.ts

@@ -0,0 +1,119 @@
+/**
+ * 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";
+import { reachable, sameSecret } from "./bridge.js";
+
+export const SOCKET_PATH = "/.peershare/socket";
+export 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 function socketGate(
+  init: Pick<BridgeInit, "token" | "allowedOrigin">,
+  resolveHost: (name: string) => Promise<string[]>,
+): SocketGate {
+  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: URL;
+    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 } };
+  };
+}
+
+/** 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 function connectApp(plan: SocketPlan): Promise<WebSocket> {
+  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: Array<string | ArrayBuffer> = [];
+    early.set(app, held);
+    app.onmessage = (e) => held.push(e.data as string | ArrayBuffer);
+    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: SocketPlan, app: WebSocket, offered: string[]): string {
+  return app.protocol !== "" && offered.includes(app.protocol) ? app.protocol : plan.accept;
+}
+
+const early = new WeakMap<WebSocket, Array<string | ArrayBuffer>>();
+
+/** Relay two open sockets, message for message, both ways; returns the inbound side's event sinks. */
+export function relaySocket(
+  inbound: InboundSocket,
+  app: WebSocket,
+): { message(data: string | ArrayBuffer): void; close(code?: number, reason?: string): void } {
+  for (const data of early.get(app)?.splice(0) ?? []) inbound.send(data);
+  app.onmessage = (e) => inbound.send(e.data as string | ArrayBuffer);
+  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?: number): number {
+  return code === 1000 || (code != null && code >= 3000 && code <= 4999) ? code : 1000;
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+/**
+ * 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";

package/src/invite-link.ts

@@ -0,0 +1,48 @@
+/**
+ * The Invite link: what the Sharer copies, and what the QR code holds.
+ *
+ * `https://tools.sandclaw.ai/peer-share/invite#join=<blob>&from=Dirk`
+ *
+ * The join blob is httpeers' own (`encodeJoinBlob`), so the existing join
+ * tooling can read it. But it travels in the FRAGMENT, not in httpeers'
+ * `?join=` query: a fragment never leaves the browser, so the page's server
+ * (and its logs, and any proxy) never sees an Invite, which is a bearer
+ * credential until it is spent.
+ */
+
+import { decodeJoinBlob, encodeJoinBlob } from "@statewalker/httpeers-member";
+
+export interface InviteLink {
+  relayAddrs: string[];
+  sharerPeerId: string;
+  invitationId: string;
+  /** Shown before joining: "Dirk invited you". */
+  sharerName: string;
+}
+
+export function encodeInvite(pageUrl: string, invite: InviteLink): string {
+  const url = new URL(pageUrl);
+  const fragment = new URLSearchParams({
+    join: encodeJoinBlob({
+      relayAddrs: invite.relayAddrs,
+      hubPeerId: invite.sharerPeerId,
+      invitationId: invite.invitationId,
+    }),
+    from: invite.sharerName,
+  });
+  url.hash = fragment.toString();
+  return url.toString();
+}
+
+export function decodeInvite(link: string): InviteLink {
+  const fragment = new URLSearchParams(new URL(link).hash.slice(1));
+  const join = fragment.get("join");
+  if (join == null) throw new Error("This is not a PeerShare invite link: it has no #join=… part.");
+  const blob = decodeJoinBlob(join);
+  return {
+    relayAddrs: blob.relayAddrs,
+    sharerPeerId: blob.hubPeerId,
+    invitationId: blob.invitationId,
+    sharerName: fragment.get("from") ?? "Someone",
+  };
+}

package/src/join-outcome.ts

@@ -0,0 +1,33 @@
+/**
+ * The Guest's side of a membership: join, come back, Close session.
+ */
+
+export type JoinOutcome = "joined" | "invite-used" | "invite-expired" | "machine-offline";
+
+/**
+ * What a failed join means to the Guest, for the Join screen.
+ *
+ * Measured against httpeers-member 0.1.6: a used and an expired Invite are
+ * both `MemberJoinError("invitation-refused")`, told apart only by the hub's
+ * answer quoted inside the message (`{"error":"invitation already-redeemed"}`
+ * / `{"error":"invitation expired"}`). An offline Sharer is a plain `Error`:
+ * the relay holds no reservation for it (`NO_RESERVATION`). Reading text is
+ * fragile; httpeers should carry the hub's reason as a field (see README).
+ */
+export function joinOutcome(error: unknown): JoinOutcome {
+  const text = describe(error);
+  if (/already-redeemed/.test(text)) return "invite-used";
+  if (/invitation expired/.test(text)) return "invite-expired";
+  // Everything else is the Sharer not being reachable: offline, tab closed,
+  // or the relay unable to find it. The Guest's next step is the same: wait.
+  return "machine-offline";
+}
+
+function describe(error: unknown): string {
+  const parts: string[] = [];
+  for (let e: unknown = error; e != null; e = (e as { cause?: unknown }).cause) {
+    parts.push(e instanceof Error ? e.message : String(e));
+    if (parts.length > 5) break;
+  }
+  return parts.join(" | ");
+}

package/src/lifecycle.ts

@@ -0,0 +1,31 @@
+/**
+ * Stop, reload and Revoke, as the Sharer drives them and a Guest sees them.
+ */
+
+import type { Hub } from "@statewalker/httpeers-hub";
+
+/**
+ * Two writes, as the hub's own `DELETE /admin/members/{peerId}` does: the
+ * member record goes, AND a revocation is recorded, so the token the Guest
+ * still holds stops verifying on its next call instead of lasting until it
+ * expires.
+ */
+export function revokeGuest(hub: Pick<Hub, "members" | "revocations">, guestPeerId: string): void {
+  hub.members.remove(guestPeerId);
+  hub.revocations.revoke(guestPeerId);
+}
+
+/** Whether a Guest's failed request means "the Sharer is offline" (Stop, closed tab). */
+/**
+ * Measured: once the Sharer stops, a Guest's request comes back within tens
+ * of ms as `502 {"kind":"peer-unreachable"}` from the Guest's own member,
+ * never as a hang. The body is read from a clone, so the caller keeps it.
+ */
+export async function isSharerOffline(response: Response): Promise<boolean> {
+  if (response.status !== 502) return false;
+  const body = (await response
+    .clone()
+    .json()
+    .catch(() => null)) as { kind?: unknown } | null;
+  return body?.kind === "peer-unreachable";
+}

package/src/policy.ts

@@ -0,0 +1,52 @@
+/**
+ * What can be shared in v1, and how.
+ *
+ * - **Bridged**: a service on the Sharer's machine or LAN, through the CORS
+ *   proxy on localhost (the Bridge). Its own target rules decide (rung 02).
+ * - **Direct**: a remote resource with a domain name, a certificate and its
+ *   own CORS headers. So: `https`, and a host NAME, never an address, and not
+ *   the Sharer's own machine or LAN (those go through the Bridge).
+ */
+
+import { checkTarget } from "./targets.js";
+
+export type ServiceKind = "bridged" | "direct";
+
+export type TargetRefusal =
+  | "not-a-url"
+  | "not-http"
+  | "needs-https"
+  | "needs-domain-name"
+  | "local-needs-bridge"
+  | "remote-is-direct"
+  | "not-local";
+
+export type TargetCheck = { ok: true } | { ok: false; reason: TargetRefusal };
+
+export function checkServiceTarget(kind: ServiceKind, target: string): TargetCheck {
+  let url: URL;
+  try {
+    url = new URL(target);
+  } catch {
+    return refused("not-a-url");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return refused("not-http");
+  const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  const isAddress = /^\d+\.\d+\.\d+\.\d+$/.test(host) || host.includes(":");
+  const isLocalName = host === "localhost" || host.endsWith(".local");
+
+  if (kind === "bridged") {
+    if (checkTarget(target) !== "forbidden") return { ok: true };
+    // A public https name is a remote resource: it is shared Direct.
+    return refused(url.protocol === "https:" && !isAddress ? "remote-is-direct" : "not-local");
+  }
+
+  if (isLocalName) return refused("local-needs-bridge");
+  if (isAddress) return refused("needs-domain-name");
+  if (url.protocol !== "https:") return refused("needs-https");
+  return { ok: true };
+}
+
+function refused(reason: TargetRefusal): TargetCheck {
+  return { ok: false, reason };
+}