@readymadeit/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,85 @@
+import { Request, Response, NextFunction } from "express";
+import {
+  AuthConfig,
+  AuthMiddleware,
+  Authenticator,
+  createAuthenticator,
+} from "../auth";
+
+/**
+ * The check the owner's routes sit behind. `authenticator` is the server's
+ * own when there is one to share, so a token is verified by one party.
+ */
+export function createAuthMiddleware(
+  config: AuthConfig,
+  authenticator?: Authenticator,
+): AuthMiddleware {
+  if (config.mode === "none") {
+    // Development only: with no real identity available, trust the :username
+    // path param as the authenticated subject. resolveServerAuthConfig() only
+    // ever yields "none" for a local checkout that opted in via ALLOW_NO_AUTH.
+    return function trustMiddleware(req, res, next) {
+      const username = req.params.username as string | undefined;
+      if (!username) {
+        res.sendStatus(401);
+        return;
+      }
+      req.authenticatedUser = { sub: username };
+      next();
+    };
+  }
+
+  return (authenticator ?? createAuthenticator(config)).middleware;
+}
+
+/**
+ * The check a route sits behind that is open to anybody with a verified
+ * identity, whether or not the server's allowlist names them — a member
+ * asking which boards are shared with them.
+ *
+ * Such a route says who may do what by something of its own (a board's member
+ * list), so this establishes only who is asking. Without authentication
+ * nobody is anybody, and the route answers as it would to a stranger.
+ */
+export function createIdentifyMiddleware(
+  config: AuthConfig,
+  authenticator?: Authenticator,
+): AuthMiddleware {
+  if (config.mode === "none") {
+    return function nobodyMiddleware(_req, _res, next) {
+      next();
+    };
+  }
+  const { identifyToken } = authenticator ?? createAuthenticator(config);
+  return (req, res, next) => {
+    const header = req.headers.authorization;
+    const token = header?.startsWith("Bearer ") ? header.slice(7) : undefined;
+    void identifyToken(token).then((user) => {
+      if (!user) {
+        res.sendStatus(401);
+        return;
+      }
+      req.authenticatedUser = user;
+      next();
+    });
+  };
+}
+
+export function requireSelf(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): void {
+  const user = req.authenticatedUser;
+  if (!user) {
+    res.sendStatus(401);
+    return;
+  }
+  // In trust mode sub equals the requested username (missing username is rejected above).
+  // In JWT mode, sub must match the username param.
+  if (user.sub !== req.params.username) {
+    res.sendStatus(403);
+    return;
+  }
+  next();
+}

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

@@ -0,0 +1,189 @@
+/**
+ * How a value that is not JSON crosses a coordinator's connections.
+ *
+ * The link to a runtime server and the bridge to a browser both carry JSON as
+ * text frames. A value holding bytes travels as one **binary** frame instead:
+ *
+ *   [ 4 bytes: header length, big-endian ][ header: UTF-8 JSON ][ payload ]
+ *
+ * The header is the message that would have been sent as text, with the value
+ * left out and a `binary` field in its place saying what the payload is. The
+ * payload is the value's bytes and nothing else.
+ *
+ * A coordinator reads the header and forwards the payload untouched
+ * (`BinaryPayload`). It never interprets the bytes, so it cannot corrupt them,
+ * and a new shape is a change to the runtimes that produce and consume it.
+ *
+ * Three shapes, which are what the runtimes pass between services:
+ *
+ *   bytes            the payload is the value
+ *   floatRingBuffer  the payload is little-endian float32 samples; `id` and
+ *                    `ts` are in the header
+ *   mixed            an object with bytes in its `binary` field; the header
+ *                    carries the rest of the object, the payload those bytes
+ *
+ * Only what a runtime hands to the next one travels this way — `result` and
+ * `processRuntime`. A notification or a log entry is for a person to read.
+ */
+
+export type BinaryShape =
+  | { kind: "bytes" }
+  | { kind: "floatRingBuffer"; id: number; ts: number }
+  | { kind: "mixed"; json: Record<string, unknown> };
+
+/** Bytes in transit, with what they are. Opaque to whoever forwards them. */
+export class BinaryPayload {
+  constructor(
+    readonly shape: BinaryShape,
+    readonly bytes: Uint8Array,
+  ) {}
+}
+
+export type BinaryFrame = {
+  /** The message, without its value and without `binary`. */
+  header: Record<string, unknown>;
+  payload: BinaryPayload;
+};
+
+const LENGTH_BYTES = 4;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function readShape(value: unknown): BinaryShape | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  if (value.kind === "bytes") {
+    return { kind: "bytes" };
+  }
+  if (value.kind === "floatRingBuffer") {
+    return {
+      kind: "floatRingBuffer",
+      id: typeof value.id === "number" ? value.id : 0,
+      ts: typeof value.ts === "number" ? value.ts : 0,
+    };
+  }
+  if (value.kind === "mixed") {
+    return { kind: "mixed", json: isRecord(value.json) ? value.json : {} };
+  }
+  return null;
+}
+
+export function encodeBinaryFrame(
+  header: Record<string, unknown>,
+  payload: BinaryPayload,
+): Buffer {
+  const head = Buffer.from(
+    JSON.stringify({ ...header, binary: payload.shape }),
+    "utf8",
+  );
+  const length = Buffer.alloc(LENGTH_BYTES);
+  length.writeUInt32BE(head.length, 0);
+  return Buffer.concat([length, head, payload.bytes]);
+}
+
+/** Null for a frame that is not one of these; nothing is thrown at a peer. */
+export function decodeBinaryFrame(raw: Uint8Array): BinaryFrame | null {
+  const frame = Buffer.isBuffer(raw)
+    ? raw
+    : Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength);
+  if (frame.length < LENGTH_BYTES) {
+    return null;
+  }
+  const headLength = frame.readUInt32BE(0);
+  if (frame.length < LENGTH_BYTES + headLength) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(
+      frame.toString("utf8", LENGTH_BYTES, LENGTH_BYTES + headLength),
+    );
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) {
+    return null;
+  }
+  const { binary, ...header } = parsed;
+  const shape = readShape(binary);
+  if (!shape) {
+    return null;
+  }
+  return {
+    header,
+    payload: new BinaryPayload(
+      shape,
+      frame.subarray(LENGTH_BYTES + headLength),
+    ),
+  };
+}
+
+/** What `ws` hands a message listener, as one buffer. */
+export function frameBytes(raw: Buffer | ArrayBuffer | Buffer[]): Buffer {
+  if (Buffer.isBuffer(raw)) {
+    return raw;
+  }
+  if (Array.isArray(raw)) {
+    return Buffer.concat(raw);
+  }
+  return Buffer.from(raw);
+}
+
+// ── A runtime server's own values ───────────────────────────────────────────
+
+const RING_BUFFER_TYPE = "FloatRingBuffer";
+
+/**
+ * The payload a pipeline value travels as, or null when it is JSON and
+ * travels as text.
+ *
+ * hkp-node passes bytes between services as a `Uint8Array`, alone or in the
+ * `binary` field of an object. It has no ring buffer of its own, so one that
+ * arrives is held as `{ type: "FloatRingBuffer", id, ts, binary }` and leaves
+ * as a ring buffer again, unchanged, if no service touched it.
+ */
+export function toBinaryPayload(value: unknown): BinaryPayload | null {
+  if (value instanceof Uint8Array) {
+    return new BinaryPayload({ kind: "bytes" }, value);
+  }
+  if (!isRecord(value) || !(value.binary instanceof Uint8Array)) {
+    return null;
+  }
+  const { binary, ...json } = value;
+  const keys = Object.keys(json);
+  if (
+    json.type === RING_BUFFER_TYPE &&
+    typeof json.id === "number" &&
+    typeof json.ts === "number" &&
+    keys.length === 3
+  ) {
+    return new BinaryPayload(
+      { kind: "floatRingBuffer", id: json.id, ts: json.ts },
+      binary,
+    );
+  }
+  return new BinaryPayload({ kind: "mixed", json }, binary);
+}
+
+/** The pipeline value a payload stands for; see `toBinaryPayload`. */
+export function fromBinaryPayload(payload: BinaryPayload): unknown {
+  // A copy with its own backing store: the frame it was cut from is the
+  // socket's, and a service may keep what it is given.
+  const bytes = new Uint8Array(payload.bytes);
+  switch (payload.shape.kind) {
+    case "bytes":
+      return bytes;
+    case "floatRingBuffer":
+      return {
+        type: RING_BUFFER_TYPE,
+        id: payload.shape.id,
+        ts: payload.shape.ts,
+        binary: bytes,
+      };
+    case "mixed":
+      return { ...payload.shape.json, binary: bytes };
+  }
+}

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

@@ -0,0 +1,242 @@
+import { Duplex } from "node:stream";
+
+import { WebSocket } from "ws";
+
+import { AuthenticatedUser } from "../auth";
+import { Caller } from "../types";
+import { BoardCoordinator } from "./coordinator";
+import { findMember } from "./members";
+import { BridgeAttach } from "./session";
+
+/**
+ * Who may attach a browser to a board, and as what.
+ *
+ * A bridge names an owner and a board. Two kinds of people are admitted:
+ *
+ * - the **owner** — the token's `sub` is the owner named, and it passes the
+ *   server's allowlist, which is what gates who may own anything here;
+ * - a **member** — the token carries a verified email that the board's list
+ *   names. The allowlist is not asked of them: a board's list is what gates
+ *   that board, and it admits people the server's operator never heard of.
+ *
+ * Anybody else is closed on the way an unknown board is — after the same
+ * wait, with the same code — so that asking is not a way to learn which
+ * boards exist or who they are shared with.
+ */
+
+/**
+ * Closing a bridge because there is no such board for whoever asked: it does
+ * not exist, or it is not theirs and not shared with them. One code for both.
+ * Said as a code so that a client can tell an answer from a connection that
+ * merely dropped, which says nothing about the board.
+ */
+export const CLOSE_NO_SUCH_BOARD = 4404;
+
+/** Closing a member's bridge because they already hold as many as one member
+ *  may. Only ever said to somebody the board is shared with. */
+export const CLOSE_TOO_MANY_BRIDGES = 4429;
+
+export type BridgeAdmissionOptions = {
+  /**
+   * How this coordinator's server authenticates. Without authentication there
+   * is no identity to admit by: everybody is the one anonymous tenant, and a
+   * bridge is its owner's, as it always was on a development machine.
+   */
+  authMode: "jwt" | "none";
+  /** How often a board that is not there yet is looked for again. */
+  attempts?: number;
+  attemptDelayMs?: number;
+  /** How long a socket may stay open without saying which board it wants. */
+  connectTimeoutMs?: number;
+  /** How much a socket may send before it has been admitted to a board. */
+  maxConnectBytes?: number;
+  /** How many sockets one identity may have waiting to be admitted. */
+  maxPendingPerIdentity?: number;
+};
+
+/**
+ * What is allowed of a socket nobody has admitted yet. The upgrade establishes
+ * only who is asking, and that may be anybody able to sign in — so until a
+ * board has taken the socket it gets a short time, a small message and few
+ * siblings. Once admitted, what a bridge may carry is the board's to say.
+ */
+export const DEFAULT_ADMISSION_LIMITS = {
+  connectTimeoutMs: 10_000,
+  maxConnectBytes: 64 * 1024,
+  maxPendingPerIdentity: 8,
+};
+
+type ConnectMessage = {
+  type?: string;
+  userId?: string;
+  boardName?: string;
+  runtimeIds?: unknown;
+};
+
+export function createBridgeHandler(
+  coordinator: BoardCoordinator,
+  options: BridgeAdmissionOptions,
+): (
+  ws: WebSocket,
+  user: AuthenticatedUser,
+  mayOwn: boolean,
+  transport?: Duplex,
+) => void {
+  const attempts = options.attempts ?? 30;
+  const attemptDelayMs = options.attemptDelayMs ?? 100;
+  const connectTimeoutMs =
+    options.connectTimeoutMs ?? DEFAULT_ADMISSION_LIMITS.connectTimeoutMs;
+  const maxConnectBytes =
+    options.maxConnectBytes ?? DEFAULT_ADMISSION_LIMITS.maxConnectBytes;
+  const maxPendingPerIdentity =
+    options.maxPendingPerIdentity ??
+    DEFAULT_ADMISSION_LIMITS.maxPendingPerIdentity;
+  /** Sockets waiting to be admitted, counted by who opened them. */
+  const pending = new Map<string, number>();
+
+  /** What this person is to the board, or null when they are nothing to it. */
+  function admit(
+    user: AuthenticatedUser,
+    mayOwn: boolean,
+    userId: string,
+    boardName: string,
+  ): BridgeAttach | null {
+    if (options.authMode === "none") {
+      return { role: "owner" };
+    }
+    const listed = findMember(
+      coordinator.getMembers(userId, boardName),
+      user.email,
+    );
+    const caller: Caller = {
+      sub: user.sub,
+      ...(user.email ? { email: user.email } : {}),
+      // The owner is called what their own list calls them, when it names
+      // them: the name on a booking is the same for everybody.
+      ...(listed ? { name: listed.name } : {}),
+    };
+    if (user.sub === userId && mayOwn) {
+      return { role: "owner", caller: { ...caller, role: "owner" } };
+    }
+    return listed ? { role: "member", caller: { ...caller, role: "member" } } : null;
+  }
+
+  return (ws, user, mayOwn, transport) => {
+    // Without authentication everybody is the one anonymous tenant, and there
+    // is no identity to count by.
+    const counted = options.authMode !== "none";
+    const waiting = pending.get(user.sub) ?? 0;
+    if (counted && waiting >= maxPendingPerIdentity) {
+      console.warn(
+        `[bridge] Too many sockets waiting for "${user.sub}" — closing`,
+      );
+      ws.terminate();
+      return;
+    }
+    if (counted) {
+      pending.set(user.sub, waiting + 1);
+    }
+
+    // Counted on the connection rather than on the message: the socket has no
+    // ceiling of its own, so a message is only seen once all of it has been
+    // buffered, which is too late to refuse it.
+    let received = 0;
+    const count = (chunk: Buffer) => {
+      received += chunk.length;
+      if (received > maxConnectBytes) {
+        console.warn(
+          `[bridge] "${user.sub}" sent more than ${maxConnectBytes} bytes before being admitted — closing`,
+        );
+        ws.terminate();
+      }
+    };
+    transport?.on("data", count);
+
+    const deadline = setTimeout(() => {
+      console.warn(`[bridge] No connect message from "${user.sub}" — closing`);
+      ws.close(1008, "connect expected");
+    }, connectTimeoutMs);
+
+    let settled = false;
+    /** The socket stops waiting: a board took it, or it is gone. */
+    const settle = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(deadline);
+      transport?.off("data", count);
+      if (counted) {
+        const left = (pending.get(user.sub) ?? 1) - 1;
+        if (left > 0) {
+          pending.set(user.sub, left);
+        } else {
+          pending.delete(user.sub);
+        }
+      }
+    };
+    ws.once("close", settle);
+
+    ws.once("message", (raw) => {
+      // Said which board, or failed to: either way the wait for it is over.
+      // The rest of what applies to an unadmitted socket stays until `settle`.
+      clearTimeout(deadline);
+      let msg: ConnectMessage;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        console.warn("[bridge] Failed to parse connect message — closing");
+        ws.close();
+        return;
+      }
+      if (msg.type !== "connect" || !msg.userId || !msg.boardName) {
+        console.warn(
+          `[bridge] Invalid connect message (type=${msg.type}, boardName=${msg.boardName}) — closing`,
+        );
+        ws.close();
+        return;
+      }
+      const { userId, boardName } = msg;
+      const runtimeIds = Array.isArray(msg.runtimeIds)
+        ? msg.runtimeIds.filter((id): id is string => typeof id === "string")
+        : [];
+
+      // The session may not exist yet if the bridge connects before the board
+      // has been registered, so it is looked for a few times before giving up.
+      // Somebody who is not admitted waits just as long: a refusal that came
+      // sooner than "no such board" would say the board is there.
+      const look = (attemptsLeft: number) => {
+        if (ws.readyState !== WebSocket.OPEN) {
+          return;
+        }
+        const session = coordinator.getBoard(userId, boardName);
+        const attach = session ? admit(user, mayOwn, userId, boardName) : null;
+        if (session && attach) {
+          if (
+            attach.role === "member" &&
+            session.countMemberBridges(attach.caller?.email ?? "") >=
+              coordinator.maxBridgesPerMember
+          ) {
+            console.warn(
+              `[bridge] Too many bridges for one member of "${boardName}" — closing`,
+            );
+            ws.close(CLOSE_TOO_MANY_BRIDGES, "open in too many places");
+            return;
+          }
+          settle();
+          session.registerBrowserSocket(ws, runtimeIds, attach);
+          return;
+        }
+        if (attemptsLeft <= 0) {
+          console.warn(
+            `[bridge] No board "${boardName}" to attach "${user.sub}" to — closing`,
+          );
+          ws.close(CLOSE_NO_SUCH_BOARD, "no such board");
+          return;
+        }
+        setTimeout(() => look(attemptsLeft - 1), attemptDelayMs);
+      };
+      look(attempts);
+    });
+  };
+}