@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-node/src/coordinator/facadeAccess.ts

@@ -0,0 +1,426 @@
+import { CloudBoardConfig, isRemoteRuntime } from "./types";
+
+/**
+ * What a board's facade lets a member of the board do and see.
+ *
+ * A member is not handed the board. They are handed its facade, and the facade
+ * is therefore the whole of their reach: the services it asks to process are
+ * the ones a member may ask, and the services it reads from are the ones a
+ * member hears. Everything else on the board — its other services, their
+ * configuration, whatever credentials that configuration names — stays with
+ * the owner.
+ *
+ * Read here from the facade document itself rather than from a list a board
+ * author keeps beside it, so that what a member can do is exactly what the
+ * facade they are shown does.
+ *
+ * The vocabulary is the frontend's (`hkp-frontend/src/facade/types.ts`). Found
+ * by shape, the way `widgetServices.ts` finds references there, so a widget
+ * added later is covered without this being edited.
+ */
+
+export type FacadeAccess = {
+  /**
+   * The facade as a member is shown it: the board's, without what it keeps for
+   * its owner. Everything below is read from this, so an item kept for the
+   * owner grants a member nothing, and is not sent to them either.
+   */
+  facade: unknown;
+  /**
+   * Services a `process` action names. Naming one makes it callable by a
+   * member with *any* payload — the entry point is the capability, not what
+   * the widget would have sent — so whatever matters is checked behind it.
+   */
+  processTargets: Set<string>;
+  /**
+   * Services a widget or a notice reads, with the paths read from each. An
+   * empty string stands for a source with no path: the whole notification.
+   */
+  sources: Map<string, Set<string>>;
+  /** Every service the facade names, for whatever reason. */
+  named: Set<string>;
+  /**
+   * Source paths that name an object's machinery rather than its data
+   * (`isPlainPath`). They grant nothing; a board whose facade has one is not
+   * taken in the first place (`refusedFacadePaths`).
+   */
+  refused: Set<string>;
+};
+
+/**
+ * What an action carries to its service. A uuid in there is a value being
+ * sent, not an address this facade dials.
+ */
+const PAYLOADS = new Set(["configure", "payload"]);
+
+function isReference(name: string): boolean {
+  return name === "serviceUuid" || name.endsWith("ServiceUuid");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Segments that lead from a value into what every object inherits. A path
+ * through one reaches `Object.prototype`, so writing along it changes every
+ * object in the process, for every tenant.
+ */
+const MACHINERY = new Set(["__proto__", "constructor", "prototype"]);
+
+/** Whether a dotted path names only data: no segment is `MACHINERY`. */
+export function isPlainPath(path: string): boolean {
+  return path.split(".").every((key) => !MACHINERY.has(key));
+}
+
+/** An address a template has yet to fill in names nothing a member may call. */
+function isLiteral(address: string): boolean {
+  return !!address && !address.includes("{{");
+}
+
+/** Where a facade says what it reads: a widget's or a notice's source, and a
+ *  fold's live count. */
+const SOURCES = new Set(["source", "summary"]);
+
+function walk(value: unknown, access: FacadeAccess, under = ""): void {
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      walk(entry, access, under);
+    }
+    return;
+  }
+  if (!isRecord(value)) {
+    return;
+  }
+
+  const uuid = value.serviceUuid;
+  if (typeof uuid === "string" && isLiteral(uuid)) {
+    if (value.type === "process") {
+      access.processTargets.add(uuid);
+    } else if (SOURCES.has(under)) {
+      const path = typeof value.path === "string" ? value.path : "";
+      // Refused rather than kept: it would read nothing a member may see, and
+      // projecting it would write through to every object in the process.
+      if (isPlainPath(path)) {
+        const paths = access.sources.get(uuid) ?? new Set<string>();
+        paths.add(path);
+        access.sources.set(uuid, paths);
+      } else {
+        access.refused.add(path);
+      }
+    }
+  }
+
+  for (const [name, entry] of Object.entries(value)) {
+    if (PAYLOADS.has(name)) {
+      continue;
+    }
+    if (typeof entry === "string") {
+      if (isReference(name) && isLiteral(entry)) {
+        access.named.add(entry);
+      }
+      continue;
+    }
+    walk(entry, access, name);
+  }
+}
+
+function emptyAccess(facade: unknown): FacadeAccess {
+  return {
+    facade,
+    processTargets: new Set(),
+    sources: new Map(),
+    named: new Set(),
+    refused: new Set(),
+  };
+}
+
+export function readFacadeAccess(facade: unknown): FacadeAccess {
+  const shown = facadeForMembers(facade);
+  const access = emptyAccess(shown);
+  walk(shown, access);
+  return access;
+}
+
+/**
+ * The source paths a facade may not have, anywhere in it — kept for the owner
+ * or not, since what the owner keeps today a member may be shown tomorrow.
+ * Asked where a board is taken in, so that one carrying them is refused there
+ * rather than run with those sources silently reading nothing.
+ */
+export function refusedFacadePaths(facade: unknown): string[] {
+  const access = emptyAccess(facade);
+  walk(facade, access);
+  return [...access.refused];
+}
+
+/** Whether an entry is one a facade keeps for the board's owner. */
+function isOwners(value: unknown): boolean {
+  return isRecord(value) && value.visibleTo === "owner";
+}
+
+/** A value with every entry kept for the owner left out, at any depth. */
+function withoutOwners(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.filter((entry) => !isOwners(entry)).map(withoutOwners);
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  const out: Record<string, unknown> = {};
+  for (const [name, entry] of Object.entries(value)) {
+    if (!isOwners(entry)) {
+      out[name] = withoutOwners(entry);
+    }
+  }
+  return out;
+}
+
+/**
+ * The facade without the panels only an owner's tab names. A panel no tab
+ * names is on screen whatever tab is chosen, so leaving out the tab alone
+ * would put its panels in front of a member rather than keep them from one.
+ */
+function withoutOwnersPanels(facade: unknown): unknown {
+  if (!isRecord(facade) || !Array.isArray(facade.tabs) || !Array.isArray(facade.panels)) {
+    return facade;
+  }
+  const named = (owners: boolean) =>
+    new Set(
+      (facade.tabs as unknown[])
+        .filter((tab) => isRecord(tab) && isOwners(tab) === owners)
+        .flatMap((tab) => (isRecord(tab) && Array.isArray(tab.panels) ? tab.panels : [])),
+    );
+  const everybodys = named(false);
+  const owners = named(true);
+  return {
+    ...facade,
+    panels: facade.panels.filter(
+      (panel) =>
+        !isRecord(panel) || !owners.has(panel.id) || everybodys.has(panel.id),
+    ),
+  };
+}
+
+/**
+ * The facade without what `visibleTo: "owner"` keeps for the board's owner —
+ * a widget, a container, a panel, a tab, a notice.
+ *
+ * Left out of what a member is sent rather than hidden by the page they are
+ * shown it on: a control a member cannot see but is sent still names its
+ * service and what it would send there, and a value only the owner reads
+ * would still be projected to them. A tab left with none of its panels goes
+ * with them, a panel only an owner's tab names goes with that tab, and so does
+ * a default naming a tab that went.
+ */
+export function facadeForMembers(facade: unknown): unknown {
+  const shown = withoutOwners(withoutOwnersPanels(facade));
+  if (!isRecord(shown) || !Array.isArray(shown.tabs)) {
+    return shown;
+  }
+  const panels = new Set(
+    (Array.isArray(shown.panels) ? shown.panels : [])
+      .map((panel) => (isRecord(panel) ? panel.id : undefined))
+      .filter((id): id is string => typeof id === "string"),
+  );
+  const tabs = shown.tabs.flatMap((tab) => {
+    if (!isRecord(tab) || !Array.isArray(tab.panels)) {
+      return [tab];
+    }
+    const kept = tab.panels.filter((id) => panels.has(id as string));
+    // A tab that never named a panel is the board's to have; one that lost
+    // all of them to the owner is the owner's.
+    return kept.length === 0 && tab.panels.length > 0 ? [] : [{ ...tab, panels: kept }];
+  });
+  const result: Record<string, unknown> = { ...shown, tabs };
+  if (!tabs.some((tab) => isRecord(tab) && tab.id === shown.defaultTab)) {
+    delete result.defaultTab;
+  }
+  return result;
+}
+
+/** The first segment of an address: the service a board lists. */
+function rootOf(address: string): string {
+  const dot = address.indexOf(".");
+  return dot < 0 ? address : address.slice(0, dot);
+}
+
+/**
+ * The value at a dotted path, through own properties only: what a value
+ * inherits is not part of it, and is not a member's to be sent.
+ */
+function readPath(value: unknown, path: string): unknown {
+  let current = value;
+  for (const key of path.split(".")) {
+    if (!isRecord(current) && !Array.isArray(current)) {
+      return undefined;
+    }
+    if (MACHINERY.has(key) || !Object.hasOwn(current, key)) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+/**
+ * Sets a dotted path in an object `pick` built, creating what leads to it.
+ * Every object it creates has no prototype, and a path through `MACHINERY` is
+ * written nowhere — the checks here stand even where a path was let through
+ * on its way in.
+ */
+function writePath(
+  target: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  if (!isPlainPath(path)) {
+    return;
+  }
+  const keys = path.split(".");
+  let current = target;
+  for (const key of keys.slice(0, -1)) {
+    const next = Object.hasOwn(current, key) ? current[key] : undefined;
+    if (!isRecord(next)) {
+      current[key] = Object.create(null);
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+  current[keys[keys.length - 1]] = value;
+}
+
+/**
+ * Of a service's state, only what the facade's sources read from it.
+ *
+ * A source without a path reads whatever the service next says, which is a
+ * notification and not its state; nothing of the state is given for it. So a
+ * service the facade only acts on, or only listens to, has an empty state
+ * here — its statement, its address, its credentials' names are not a
+ * member's to see.
+ */
+export function projectState(
+  access: FacadeAccess,
+  serviceUuid: string,
+  state: unknown,
+): Record<string, unknown> {
+  return pick(state, access.sources.get(serviceUuid) ?? []);
+}
+
+/**
+ * Of what a service said, only what the facade's sources read from it.
+ *
+ * A source without a path reads the notification whole, so the whole of it is
+ * given. Otherwise it is cut down to the paths read: each of them resolves in
+ * what is returned to exactly what it resolved to in what was said, and
+ * nothing beside them is there. A notification holding none of them is not a
+ * notification for this facade: forwarding an empty object would reveal that
+ * the service spoke but would not clear a widget, since none of its source
+ * paths changed. A service clears a value explicitly (`rows: []`, for example).
+ */
+export function projectNotification(
+  access: FacadeAccess,
+  serviceUuid: string,
+  payload: unknown,
+): unknown | undefined {
+  const paths = access.sources.get(serviceUuid) ?? new Set<string>();
+  if (paths.has("")) {
+    return payload;
+  }
+  const projected = pick(payload, paths);
+  return Object.keys(projected).length > 0 ? projected : undefined;
+}
+
+/** The values at `paths` in `value`, at the same paths in an object of their
+ *  own. A pathless entry names no part of it and picks nothing.
+ *
+ *  A path inside one that is picked whole adds nothing and is skipped: given
+ *  `rows` and `rows.0.day`, the rows are already there, and writing the second
+ *  would build `rows` again as an object holding `0` — a calendar reading the
+ *  list would then be given none. */
+function pick(value: unknown, paths: Iterable<string>): Record<string, unknown> {
+  const picked: Record<string, unknown> = Object.create(null);
+  const all = [...paths].filter(Boolean);
+  const covered = (path: string) =>
+    all.some((other) => other !== path && path.startsWith(`${other}.`));
+  for (const path of all) {
+    if (covered(path)) {
+      continue;
+    }
+    const found = readPath(value, path);
+    if (found !== undefined) {
+      writePath(picked, path, found);
+    }
+  }
+  return picked;
+}
+
+/**
+ * The runtime a facade's service is on: the first of the board's remote
+ * runtimes listing it, which is how a facade's bare uuid is resolved
+ * everywhere. A browser runtime's services are not a member's to reach — that
+ * runtime runs in its owner's browser.
+ */
+export function runtimeHolding(
+  config: CloudBoardConfig,
+  serviceUuid: string,
+): string | undefined {
+  const root = rootOf(serviceUuid);
+  for (const runtime of config.runtimes) {
+    if (!isRemoteRuntime(runtime)) {
+      continue;
+    }
+    if ((config.services[runtime.id] ?? []).some((svc) => svc.uuid === root)) {
+      return runtime.id;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The board as a member is sent it: the facade, and of the board only the
+ * services the facade names — what each one is, never how it is configured.
+ *
+ * Shaped as a board, so a client renders the facade from it the way it would
+ * from the real one. There is no board underneath: the runtimes carry no
+ * address and no settings, and a service nobody named is not there at all.
+ */
+export function projectConfig(
+  config: CloudBoardConfig,
+  access: FacadeAccess,
+  stateOf: (runtimeId: string, serviceUuid: string) => unknown,
+): CloudBoardConfig {
+  const services: CloudBoardConfig["services"] = {};
+  for (const address of access.named) {
+    const runtimeId = runtimeHolding(config, address);
+    if (!runtimeId) {
+      continue;
+    }
+    const uuid = rootOf(address);
+    const listed = services[runtimeId] ?? [];
+    if (listed.some((svc) => svc.uuid === uuid)) {
+      continue;
+    }
+    const svc = (config.services[runtimeId] ?? []).find(
+      (entry) => entry.uuid === uuid,
+    );
+    if (!svc) {
+      continue;
+    }
+    listed.push({
+      uuid,
+      serviceId: svc.serviceId,
+      serviceName: svc.serviceName ?? svc.name ?? svc.serviceId,
+      state: projectState(access, uuid, stateOf(runtimeId, uuid)),
+    });
+    services[runtimeId] = listed;
+  }
+
+  return {
+    boardName: config.boardName,
+    runtimes: config.runtimes
+      .filter((runtime) => runtime.id in services)
+      .map(({ id, name, type }) => ({ id, name, type })),
+    services,
+    facade: access.facade,
+  };
+}

package/bundle/hkp-node/src/coordinator/fileBoardStore.ts

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+import { BoardStore, PersistedBoard } from "./boardStore";
+import { CloudBoardConfig } from "./types";
+import { readMembers } from "./members";
+
+/**
+ * Boards kept as one JSON file each, under a directory this coordinator owns.
+ *
+ * ```
+ * <root>/<sha256(userId)>/<sha256(boardName)>.json
+ * ```
+ *
+ * The names in those paths are **derived, never used directly**. Both come from
+ * the wire: a board name is whatever the client sent, and an Auth0 `sub`
+ * contains characters (`|`) that have no business in a path. Hashing settles
+ * two problems at once — a board called `../../etc/passwd` cannot escape the
+ * root, and `Foo` and `foo`, which are two boards to the coordinator, cannot
+ * become one file on a case-insensitive filesystem. The real names are inside.
+ */
+
+/** Bumped only when the shape on disk changes; an unknown one is left alone. */
+const FORMAT_VERSION = 1;
+
+type BoardFile = PersistedBoard & { version: number };
+
+function fileNameFor(value: string): string {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+function isBoardFile(value: unknown): value is BoardFile {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const board = value as Record<string, unknown>;
+  return (
+    typeof board.userId === "string" &&
+    typeof board.boardName === "string" &&
+    typeof board.createdAt === "string" &&
+    !!board.config &&
+    typeof board.config === "object"
+  );
+}
+
+export function createFileBoardStore(root: string): BoardStore {
+  const userDir = (userId: string) => path.join(root, fileNameFor(userId));
+  const boardPath = (userId: string, boardName: string) =>
+    path.join(userDir(userId), `${fileNameFor(boardName)}.json`);
+
+  async function readBoard(file: string): Promise<PersistedBoard | null> {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(await fs.readFile(file, "utf8"));
+    } catch (err) {
+      // One unreadable board must not stop a coordinator from starting: the
+      // others are still good, and the operator can see which one is not.
+      console.error(
+        `[coordinator] Ignoring unreadable board file ${file}:`,
+        err instanceof Error ? err.message : err,
+      );
+      return null;
+    }
+    if (!isBoardFile(parsed)) {
+      console.error(`[coordinator] Ignoring malformed board file ${file}`);
+      return null;
+    }
+    if (parsed.version !== FORMAT_VERSION) {
+      // Written by a newer coordinator. Guessing at it could hand a board back
+      // in a shape it never had; leaving it be keeps it intact for that one.
+      console.error(
+        `[coordinator] Ignoring board file ${file}: format version ${parsed.version}`,
+      );
+      return null;
+    }
+    const { userId, boardName, createdAt, config, stopped, tickets, members } =
+      parsed;
+    return {
+      userId,
+      boardName,
+      createdAt,
+      config: config as CloudBoardConfig,
+      stopped: typeof stopped === "boolean" ? stopped : undefined,
+      tickets: Array.isArray(tickets)
+        ? tickets.filter(
+            (ticket) =>
+              !!ticket &&
+              typeof ticket.runtimeId === "string" &&
+              typeof ticket.hash === "string" &&
+              typeof ticket.issuedAt === "string",
+          )
+        : undefined,
+      // Absent in a file written before boards could be shared.
+      members: Array.isArray(members) ? readMembers(members) : undefined,
+    };
+  }
+
+  return {
+    async load(): Promise<PersistedBoard[]> {
+      let userDirs: string[];
+      try {
+        userDirs = await fs.readdir(root);
+      } catch {
+        // Nothing has been deployed yet — the directory appears on first save.
+        return [];
+      }
+      const boards: PersistedBoard[] = [];
+      for (const dir of userDirs) {
+        let entries: string[];
+        try {
+          entries = await fs.readdir(path.join(root, dir));
+        } catch {
+          continue;
+        }
+        for (const entry of entries) {
+          // Only finished files: a half-written one is still under its
+          // temporary name, which does not end in .json.
+          if (!entry.endsWith(".json")) {
+            continue;
+          }
+          const board = await readBoard(path.join(root, dir, entry));
+          if (board) {
+            boards.push(board);
+          }
+        }
+      }
+      return boards;
+    },
+
+    async save(board: PersistedBoard): Promise<void> {
+      const dir = userDir(board.userId);
+      // A board config carries service state, which can carry credentials —
+      // so this is the owner's to read, and nobody else's.
+      await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+      const file = boardPath(board.userId, board.boardName);
+      const contents: BoardFile = { version: FORMAT_VERSION, ...board };
+      // Write beside the target, then rename: a rename within one directory is
+      // atomic, so a crash mid-write leaves the previous board intact rather
+      // than half of the new one.
+      const temporary = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+      await fs.writeFile(temporary, JSON.stringify(contents, null, 2), {
+        mode: 0o600,
+      });
+      try {
+        await fs.rename(temporary, file);
+      } catch (err) {
+        await fs.rm(temporary, { force: true });
+        throw err;
+      }
+    },
+
+    async remove(userId: string, boardName: string): Promise<void> {
+      // Already gone is the outcome asked for.
+      await fs.rm(boardPath(userId, boardName), { force: true });
+    },
+  };
+}

package/bundle/hkp-node/src/coordinator/frameLimits.ts

@@ -0,0 +1,41 @@
+/**
+ * How large one message between a coordinator and what is connected to it may
+ * be.
+ *
+ * Two limits, one derived from the other:
+ *
+ * - **The frame limit** is what a coordinator lets through: a value larger than
+ *   it is dropped and logged as `frame-dropped`, and the connection stays — a
+ *   board that lost a runtime over one large value would be wrong about what
+ *   happened. `HKP_COORDINATOR_MAX_FRAME_BYTES` raises or lowers it; it is never
+ *   off, because a socket that accepts anything buffers anything before a
+ *   handler can look at it.
+ * - **The socket ceiling** is what the WebSocket library itself accepts, on
+ *   every coordinator connection — a runtime server joining, a browser
+ *   attaching, and this server's own link out to a coordinator. It sits above
+ *   the frame limit by a margin, so the library only refuses what the frame
+ *   limit would have dropped anyway, plus the room an introduction needs: a
+ *   runtime server's hello carries its registry and is not held to the frame
+ *   limit. Past the ceiling the library closes the connection, which is the
+ *   one answer left for a message nobody should have sent.
+ *
+ * The same numbers are in hkp-python (`coordinator_links.py`) and hkp-rt
+ * (`link_socket.cpp`), which connect to a coordinator the way this server's
+ * links do.
+ */
+
+/** As large as an asset may be on hkp-rt: room for a sample or a recording. */
+export const DEFAULT_MAX_FRAME_BYTES = 64 * 1024 * 1024;
+
+/** What an introduction may need beyond a value. */
+const SOCKET_HEADROOM_BYTES = 16 * 1024 * 1024;
+
+/** The frame limit an operator's setting names; unset or 0 is the default. */
+export function frameLimitFrom(value: number | undefined): number {
+  return value && value > 0 ? value : DEFAULT_MAX_FRAME_BYTES;
+}
+
+/** What the WebSocket library accepts, for a frame limit. */
+export function socketCeiling(frameLimit: number = DEFAULT_MAX_FRAME_BYTES): number {
+  return frameLimitFrom(frameLimit) + SOCKET_HEADROOM_BYTES;
+}

package/bundle/hkp-node/src/coordinator/index.ts

@@ -0,0 +1,12 @@
+export { createCoordinatorRouter } from "./router";
+export { BoardCoordinator } from "./coordinator";
+export { attachCoordinatorJoin } from "./join";
+export { createBridgeHandler } from "./bridge";
+export { SHARED_BOARDS_PATH } from "./router";
+export type {
+  CloudBoardConfig,
+  CloudRuntimeDescriptor,
+  CloudServiceDescriptor,
+  BoardSessionInfo,
+  BoardSessionStatus,
+} from "./types";

package/bundle/hkp-node/src/coordinator/join.ts

@@ -0,0 +1,62 @@
+import http from "node:http";
+import { Duplex } from "node:stream";
+
+import { WebSocketServer } from "ws";
+
+import { BoardCoordinator } from "./coordinator";
+import { JOIN_PATH } from "./participantProtocol";
+import { socketCeiling } from "./frameLimits";
+
+/**
+ * Where runtime servers connect in.
+ *
+ * The one endpoint of a coordinator that a user's token does not open: what
+ * connects here is a machine holding a ticket, possibly long after the person
+ * who deployed the board has gone. The ticket is presented as a bearer token on
+ * the upgrade and decides everything — which person, which board, which
+ * runtime — so the connection is told nothing and asks for nothing else.
+ */
+
+type UpgradeHost = {
+  addUpgradeRoute(
+    pathname: string,
+    handler: (
+      request: http.IncomingMessage,
+      socket: Duplex,
+      head: Buffer,
+    ) => void,
+  ): void;
+};
+
+export function attachCoordinatorJoin(
+  host: UpgradeHost,
+  coordinator: BoardCoordinator,
+  basePath = "/coordinator",
+): void {
+  // What a coordinator's operator allows is decided per frame, and an
+  // oversized value is dropped without closing anything (ParticipantRegistry).
+  // The library's own ceiling sits above that, so it refuses only what the
+  // frame limit would have dropped anyway; see frameLimits.ts.
+  const wss = new WebSocketServer({
+    noServer: true,
+    maxPayload: socketCeiling(coordinator.maxFrameBytes),
+  });
+
+  host.addUpgradeRoute(`${basePath}${JOIN_PATH}`, (request, socket, head) => {
+    const header = request.headers.authorization;
+    const ticket = header?.startsWith("Bearer ") ? header.slice(7) : undefined;
+    // Decided before the upgrade, so a ticket this coordinator does not hold is
+    // refused as an HTTP answer — which is what tells its holder to stop
+    // presenting it, rather than to try again.
+    if (!ticket || !coordinator.participants.resolve(ticket)) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(request, socket, head, (ws) => {
+      if (!coordinator.participants.accept(ws, ticket)) {
+        ws.close();
+      }
+    });
+  });
+}