relaybrain 0.0.0-stage → 0.2.0

package/backend/lib/roomAuth.js

@@ -0,0 +1,215 @@
+const crypto = require("crypto");
+
+// A shared room is reachable by anyone who learns the tunnel URL, and it hands
+// out the whole working tree, every agent transcript, and write access to the
+// lock table. Membership therefore has to be proven, not assumed.
+//
+// Two credentials, with different lifetimes:
+//   invite code  — issued by the host to one named person, single use, expires.
+//   member token — minted when an invite is redeemed, presented on every
+//                  subsequent request for as long as the room lasts.
+// Only hashes are ever written to room.json, so a leaked room file cannot be
+// replayed to rejoin the room.
+
+const INVITE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const SECRET_BYTES = 24;
+
+function hash(raw) {
+  return crypto.createHash("sha256").update(String(raw)).digest("hex");
+}
+
+function mint(prefix) {
+  return `${prefix}_${crypto.randomBytes(SECRET_BYTES).toString("hex")}`;
+}
+
+function sameSecret(a, b) {
+  const left = Buffer.from(String(a || ""), "utf8");
+  const right = Buffer.from(String(b || ""), "utf8");
+  if (left.length !== right.length || !left.length) return false;
+  return crypto.timingSafeEqual(left, right);
+}
+
+function normLogin(login) {
+  return String(login || "").trim().toLowerCase();
+}
+
+function invitesOf(room) {
+  return Array.isArray(room?.invites) ? room.invites : [];
+}
+
+function inviteState(invite, now = Date.now()) {
+  if (invite.revokedAt) return "revoked";
+  if (invite.acceptedAt) return "accepted";
+  if (invite.expiresAt && now > invite.expiresAt) return "expired";
+  return "pending";
+}
+
+function createInvite(room, { login, ttlMs, invitedBy } = {}) {
+  const target = normLogin(login);
+  if (!target) return { ok: false, error: "login_required" };
+  const code = mint("rli");
+  const now = Date.now();
+  const invite = {
+    id: `inv_${crypto.randomBytes(6).toString("hex")}`,
+    login: target,
+    codeHash: hash(code),
+    createdAt: now,
+    expiresAt: now + (Number(ttlMs) || INVITE_TTL_MS),
+    invitedBy: normLogin(invitedBy) || null,
+    acceptedAt: null,
+    revokedAt: null,
+  };
+  room.invites = [...invitesOf(room).filter((i) => inviteState(i) !== "expired"), invite];
+  return { ok: true, invite, code };
+}
+
+function revokeInvite(room, id) {
+  const invite = invitesOf(room).find((i) => i.id === id);
+  if (!invite) return { ok: false, error: "not_found" };
+  invite.revokedAt = Date.now();
+  return { ok: true, invite };
+}
+
+/** Safe to send to a client: never includes the code or its hash. */
+function inviteView(room) {
+  return invitesOf(room).map((i) => ({
+    id: i.id,
+    login: i.login,
+    state: inviteState(i),
+    createdAt: i.createdAt,
+    expiresAt: i.expiresAt,
+    invitedBy: i.invitedBy,
+    acceptedAt: i.acceptedAt,
+  }));
+}
+
+function pendingInviteFor(room, login) {
+  const claimed = normLogin(login);
+  return invitesOf(room).find((i) => normLogin(i.login) === claimed && inviteState(i) === "pending") || null;
+}
+
+function acceptedInviteFor(room, login) {
+  const claimed = normLogin(login);
+  return invitesOf(room).find((i) => normLogin(i.login) === claimed && inviteState(i) === "accepted") || null;
+}
+
+/**
+ * Checks an invite code against the room. `login` is who is claiming it — an
+ * invite addressed to one person must not be usable by another, otherwise a
+ * forwarded link is as good as an open door. A code-less redeem is only safe
+ * after GitHub identity proof (see /api/room/redeem).
+ */
+function redeemInvite(room, code, login) {
+  const claimed = normLogin(login);
+  if (!claimed) return { ok: false, reason: "login_required" };
+  if (code) {
+    const hashed = hash(code);
+    const invite = invitesOf(room).find((i) => sameSecret(i.codeHash, hashed));
+    if (!invite) return { ok: false, reason: "invite_invalid" };
+    const state = inviteState(invite);
+    if (state === "revoked") return { ok: false, reason: "invite_revoked" };
+    if (state === "expired") return { ok: false, reason: "invite_expired" };
+    if (state === "accepted") return { ok: false, reason: "invite_already_used" };
+    if (normLogin(invite.login) !== claimed) {
+      return { ok: false, reason: "invite_wrong_user", invitedLogin: invite.login };
+    }
+    return { ok: true, invite };
+  }
+  // Code-less redeem is only safe after GitHub identity proof (see /api/room/redeem).
+  const pending = pendingInviteFor(room, claimed);
+  if (pending) return { ok: true, invite: pending };
+  const accepted = acceptedInviteFor(room, claimed);
+  if (accepted) return { ok: true, invite: accepted, rejoin: true };
+  return { ok: false, reason: "invite_required" };
+}
+
+function markAccepted(invite, login) {
+  invite.acceptedAt = Date.now();
+  invite.acceptedBy = normLogin(login);
+  return invite;
+}
+
+/** Mints the long-lived credential a member presents on every later request. */
+function issueMemberToken(room, login) {
+  const target = normLogin(login);
+  const token = mint("rlm");
+  room.memberTokens = (Array.isArray(room.memberTokens) ? room.memberTokens : []).filter(
+    (t) => normLogin(t.login) !== target
+  );
+  room.memberTokens.push({ login: target, tokenHash: hash(token), issuedAt: Date.now() });
+  return token;
+}
+
+function authorizeMember(room, token) {
+  if (!token) return null;
+  const hashed = hash(token);
+  const row = (Array.isArray(room?.memberTokens) ? room.memberTokens : []).find((t) =>
+    sameSecret(t.tokenHash, hashed)
+  );
+  return row ? { login: row.login, issuedAt: row.issuedAt } : null;
+}
+
+function revokeMember(room, login) {
+  const target = normLogin(login);
+  room.memberTokens = (Array.isArray(room.memberTokens) ? room.memberTokens : []).filter(
+    (t) => normLogin(t.login) !== target
+  );
+  room.invites = invitesOf(room).map((i) =>
+    normLogin(i.login) === target && !i.revokedAt ? { ...i, revokedAt: Date.now() } : i
+  );
+  return room;
+}
+
+/**
+ * The room as it is safe to hand to any client. /api/health and /api/room are
+ * both reachable through the tunnel without credentials, and the raw room
+ * carries invite and member token hashes.
+ */
+function publicRoom(room) {
+  if (!room) return null;
+  const { invites, memberTokens, members, memberToken, nonce, ...rest } = room;
+  return { ...rest, memberCount: Array.isArray(members) ? members.length : 0 };
+}
+
+/** Reads the member credential off a request. */
+function roomToken(req) {
+  const header = req.headers?.["x-relay-room-token"];
+  if (header) return String(header);
+  const auth = String(req.headers?.authorization || "");
+  if (/^Room\s+/i.test(auth)) return auth.replace(/^Room\s+/i, "").trim();
+  return req.query?.token ? String(req.query.token) : null;
+}
+
+/**
+ * True when the request arrived from somewhere other than this machine. ngrok
+ * (and any reverse proxy) stamps X-Forwarded-For, which a remote caller cannot
+ * strip. Local Mission Control and local hooks stay unauthenticated so adding
+ * room security never breaks solo use.
+ */
+function isRemoteRequest(req) {
+  if (req.headers?.["x-forwarded-for"] || req.headers?.["x-original-forwarded-for"]) return true;
+  const addr = String(req.socket?.remoteAddress || req.connection?.remoteAddress || "");
+  if (!addr) return false;
+  const bare = addr.replace(/^::ffff:/, "");
+  return bare !== "127.0.0.1" && bare !== "::1" && bare !== "localhost";
+}
+
+module.exports = {
+  INVITE_TTL_MS,
+  hash,
+  normLogin,
+  createInvite,
+  revokeInvite,
+  inviteView,
+  inviteState,
+  invitesOf,
+  redeemInvite,
+  pendingInviteFor,
+  markAccepted,
+  issueMemberToken,
+  authorizeMember,
+  revokeMember,
+  publicRoom,
+  roomToken,
+  isRemoteRequest,
+};

package/backend/lib/roomControl.js

@@ -0,0 +1,226 @@
+const { WebSocket } = require("ws");
+
+// A guest that releases a lock while the tunnel is down must still be able to
+// tell the host about it, or the file stays locked room-wide until the TTL runs
+// out (up to MAX_TTL_MS, five minutes). The queue is bounded because an outage
+// has no upper bound: past this many pending mutations the oldest are dropped,
+// since a release that stale has been overtaken by TTL expiry anyway.
+const MAX_QUEUED = 200;
+
+/**
+ * Guest-side RPC over the dedicated control socket.
+ * Locks are game inputs: tiny, ordered, never queued behind chat snapshots.
+ */
+class RoomControl {
+  constructor() {
+    this.socket = null;
+    this.pending = new Map();
+    this.seq = 0;
+    this.onLocks = null;
+    // Mutations issued while `open` was false, replayed in order on reconnect.
+    this.queue = [];
+    this.queueSeq = 0;
+    this.onReplay = null;
+    this.flushing = null;
+  }
+
+  attach(socket) {
+    this.socket = socket;
+  }
+
+  get open() {
+    return Boolean(this.socket && this.socket.readyState === WebSocket.OPEN);
+  }
+
+  handle(msg) {
+    if (!msg || typeof msg !== "object") return false;
+    if (msg.type === "locks" && this.onLocks) {
+      this.onLocks(msg);
+      return true;
+    }
+    if ((msg.type === "rpc-ok" || msg.type === "rpc-err") && this.pending.has(msg.id)) {
+      const done = this.pending.get(msg.id);
+      this.pending.delete(msg.id);
+      let error = null;
+      if (msg.type === "rpc-err") {
+        error = new Error(msg.error || "rpc_failed");
+        // The host answered, and said no. Everything else that can reject an
+        // rpc — a dead socket, a timeout, a send that throws — is the tunnel
+        // failing rather than a verdict, and replay treats the two oppositely.
+        error.fromHost = true;
+      }
+      done(error, msg.result);
+      return true;
+    }
+    return false;
+  }
+
+  rpc(op, body, timeoutMs = 700) {
+    return new Promise((resolve, reject) => {
+      if (!this.open) {
+        reject(new Error("control_offline"));
+        return;
+      }
+      const id = String(++this.seq);
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error("control_timeout"));
+      }, timeoutMs);
+      this.pending.set(id, (err, result) => {
+        clearTimeout(timer);
+        if (err) reject(err);
+        else resolve(result);
+      });
+      try {
+        this.socket.send(JSON.stringify({ type: "rpc", op, id, body }));
+      } catch (err) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Park a mutation that could not be sent, for replay on reconnect.
+   *
+   * Deliberately not used for `claim`: a claim is a question ("may I?"), and
+   * replaying it minutes later would answer a question nobody is still asking —
+   * the agent has long since been told no and moved on. Only the mutations that
+   * are statements of fact ("I am done with this file") are worth replaying.
+   *
+   * Deliberately not used for `heartbeat` either: a heartbeat is a liveness
+   * claim about *now*. Replaying a stale one would resurrect a lock the host has
+   * already expired, which is the opposite of what the sender meant.
+   */
+  enqueue(op, body) {
+    if (op !== "release" && op !== "release-all") return false;
+    const key = dedupeKey(op, body);
+    const existing = this.queue.findIndex((item) => item.key === key);
+    if (existing !== -1) this.queue.splice(existing, 1);
+    this.queue.push({ key, op, body, seq: ++this.queueSeq, at: Date.now() });
+    while (this.queue.length > MAX_QUEUED) this.queue.shift();
+    return true;
+  }
+
+  get queued() {
+    return this.queue.length;
+  }
+
+  /**
+   * Replay the parked mutations, oldest first, and hand back what the host made
+   * of them.
+   *
+   * A host *verdict* (an `rpc-err`, tagged `fromHost`) is final and the entry is
+   * dropped, so a release the host keeps refusing is not retried forever. Any
+   * other rejection — dead socket, timeout, a send that throws — is the tunnel
+   * failing rather than an answer, so those entries go back on the queue for the
+   * next reconnect rather than being silently lost.
+   */
+  flush() {
+    // Concurrent callers share one pass: a second flush would race the first for
+    // the same entries and could replay one twice. This is checked before the
+    // empty-queue guard because #flush drains the queue up front — by the time a
+    // second caller arrives the queue is already empty, and returning a fresh
+    // resolved promise there would report "done" while the replay is still in
+    // flight, which is exactly what settled() must not do.
+    if (this.flushing) return this.flushing;
+    if (!this.queue.length) return Promise.resolve({ replayed: [], rejected: [], requeued: [] });
+    this.flushing = this.#flush().finally(() => {
+      this.flushing = null;
+    });
+    return this.flushing;
+  }
+
+  /**
+   * Resolves once any in-flight replay has finished.
+   *
+   * Anything that claims a lock must wait on this. A queued release and a fresh
+   * claim for the same file both travel this socket, and `release` on the host
+   * only checks `sameOwner` — so if a re-claim lands first, the replayed release
+   * that follows deletes the lock the agent has just been granted and still
+   * believes it holds.
+   */
+  settled() {
+    return this.flushing || Promise.resolve(null);
+  }
+
+  async #flush() {
+    const batch = this.queue.slice().sort((a, b) => a.seq - b.seq);
+    this.queue = [];
+    const replayed = [];
+    const rejected = [];
+    const requeued = [];
+    for (const item of batch) {
+      if (!this.open) {
+        this.#requeue(item);
+        requeued.push({ ...item, error: "control_offline" });
+        continue;
+      }
+      try {
+        const result = await this.rpc(item.op, item.body);
+        replayed.push({ ...item, result });
+      } catch (err) {
+        const error = err?.message || String(err);
+        if (err?.fromHost) rejected.push({ ...item, error });
+        else {
+          this.#requeue(item);
+          requeued.push({ ...item, error });
+        }
+      }
+    }
+    const outcome = { replayed, rejected, requeued };
+    if (this.onReplay) {
+      try {
+        this.onReplay(outcome);
+      } catch {
+        /* a reporting failure must not break reconnection */
+      }
+    }
+    return outcome;
+  }
+
+  // Keeps the original seq, so a re-queued entry still replays ahead of
+  // mutations issued after it.
+  #requeue(item) {
+    if (this.queue.some((q) => q.key === item.key)) return;
+    this.queue.push(item);
+    while (this.queue.length > MAX_QUEUED) this.queue.shift();
+  }
+
+  send(obj) {
+    if (!this.open) return false;
+    try {
+      this.socket.send(JSON.stringify(obj));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+// release-all is per agent, not per file, so it collapses to one entry per
+// agent+workspace; a per-file release collapses to one entry per file.
+function dedupeKey(op, body = {}) {
+  const ws = String(body.workspaceId || "");
+  if (op === "release-all") return `release-all::${ws}::${String(body.agentId || "")}`;
+  return `${op}::${ws}::${String(body.file || "")}::${String(body.agentId || "")}`;
+}
+
+function sendSocket(socket, obj) {
+  if (!socket || socket.readyState !== 1) return false;
+  try {
+    socket.send(typeof obj === "string" ? obj : JSON.stringify(obj));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function broadcast(wss, obj) {
+  if (!wss) return;
+  const msg = JSON.stringify(obj);
+  for (const client of wss.clients) sendSocket(client, msg);
+}
+
+module.exports = { RoomControl, sendSocket, broadcast };

package/backend/lib/roomLocks.js

@@ -0,0 +1,201 @@
+const { EventEmitter } = require("events");
+
+const POLL_MS = 4000;
+// How long a lock may sit past its own expiry before the mirror drops it. Locks
+// carry a TTL of a few seconds and are renewed by heartbeat, so this is only
+// what keeps a lock from flickering out between two polls.
+const EXPIRY_GRACE_MS = 4000;
+// Consecutive failed polls before the host counts as unreachable. One dropped
+// tunnel request is normal; three in a row (~6s) is not.
+const MAX_MISSES = 3;
+// How long a push keeps the poller quiet. Long enough that a live socket does
+// all the work, short enough that a socket which dies without closing cleanly
+// (the normal way a tunnel disappears) is covered within one interval.
+const PUSH_TRUST_MS = 8000;
+
+/**
+ * A guest's own lock table is empty: its hooks claim against the host's
+ * coordinator (see coordinator/client.js), which is the whole point of a shared
+ * room. Without a mirror, every local read of the lock table — /api/locks, the
+ * SSE stream the Coordinator tab subscribes to, the dashboard — reports "no
+ * locks" and overwrites the host snapshot the dashboard just fetched.
+ *
+ * Two ways in, one authority. The host's lock table is the only writer; every
+ * change it makes is pushed down the room WebSocket and lands here via accept().
+ * That makes granting a lock and drawing it the SAME event rather than two
+ * subsystems that can disagree — which is exactly how a guest ended up with
+ * working locks and a permanently empty board. The poll below is no longer the
+ * delivery path, only reconciliation for whenever the socket is down.
+ *
+ * Only runs while a room is joined as a guest. Solo and host installs keep
+ * reading their own table exactly as before.
+ */
+class RoomLockMirror extends EventEmitter {
+  constructor({ fetchLocks }) {
+    super();
+    this.fetchLocks = fetchLocks;
+    this.locks = [];
+    this.reads = [];
+    this.updatedAt = 0;
+    this.timer = null;
+    this.room = null;
+    this.failures = 0;
+    this.lastPushAt = 0;
+  }
+
+  /**
+   * Whether the host is answering. The board is otherwise indistinguishable
+   * between "nobody is editing" and "the tunnel is down", which is exactly the
+   * confusion a guest hits when their Coordinator screen stays empty.
+   */
+  get health() {
+    if (!this.active) return { joined: false, reachable: true, lastContactAt: null };
+    return {
+      joined: true,
+      reachable: this.updatedAt > 0 && this.failures < MAX_MISSES,
+      lastContactAt: this.updatedAt || null,
+    };
+  }
+
+  get active() {
+    return Boolean(this.room?.url && this.room.role === "guest" && this.room.hostProjectId);
+  }
+
+  /** Has the host ever answered? Until it has, there is nothing to prefer. */
+  get fresh() {
+    return this.active && this.updatedAt > 0;
+  }
+
+  start(room) {
+    const sameRoom =
+      this.room?.url === room?.url &&
+      this.room?.hostProjectId === room?.hostProjectId &&
+      this.room?.memberToken === room?.memberToken;
+    // Nothing below may touch this.room while it is still the same room.
+    //
+    // loadRoom() re-parses room.json and hands back a NEW object every call, and
+    // the dashboard calls syncRoomLocks() on every poll — so this used to swap
+    // this.room's identity every few seconds. poll() drops any response whose
+    // room is no longer current, which meant a poll still in flight at that
+    // moment was thrown away. Over loopback a poll finishes in milliseconds and
+    // nothing is lost; over an ngrok tunnel it takes long enough that every poll
+    // could land inside that window, leaving updatedAt at 0 forever — a guest
+    // whose locks worked fine but whose Coordinator board never filled in.
+    if (sameRoom && this.timer) return undefined;
+    const sameHost =
+      this.room?.role === "guest" &&
+      room?.role === "guest" &&
+      this.room?.hostProjectId &&
+      this.room.hostProjectId === room.hostProjectId;
+    if (sameHost && this.timer) {
+      // Tunnel URL changed (ngrok recycle). Keep the last snapshot so the
+      // Coordinator board does not flash empty while we retarget.
+      this.room = room;
+      this.failures = 0;
+      this.poll();
+      return undefined;
+    }
+    this.room = room || null;
+    if (!this.active) {
+      this.stop({ clear: true });
+      return undefined;
+    }
+    this.stop();
+    this.room = room;
+    this.timer = setInterval(() => this.poll(), POLL_MS);
+    if (this.timer.unref) this.timer.unref();
+    this.poll();
+    return undefined;
+  }
+
+  stop({ clear } = {}) {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.failures = 0;
+    this.lastPushAt = 0;
+    if (clear && (this.locks.length || this.reads.length)) {
+      this.locks = [];
+      this.reads = [];
+      this.updatedAt = 0;
+      this.emit("change", { locks: [], reads: [] });
+    }
+    return undefined;
+  }
+
+  /**
+   * A lock change pushed straight from the host's table over the room socket.
+   * Same commit path as a successful poll, so both routes leave the mirror in
+   * exactly one state.
+   */
+  accept(locks, extras = {}) {
+    if (!this.active || !Array.isArray(locks)) return false;
+    this.lastPushAt = Date.now();
+    const readsChanged =
+      Array.isArray(extras.reads) && JSON.stringify(extras.reads) !== JSON.stringify(this.reads);
+    if (Array.isArray(extras.reads)) this.reads = extras.reads;
+    return this.commit(locks, readsChanged);
+  }
+
+  commit(locks, readsChanged = false) {
+    const changed = JSON.stringify(locks) !== JSON.stringify(this.locks) || readsChanged;
+    const wasDown = this.failures >= MAX_MISSES;
+    this.locks = locks;
+    this.updatedAt = Date.now();
+    this.failures = 0;
+    if (changed || wasDown) this.emit("change", { locks, reads: this.reads || [] });
+    return changed;
+  }
+
+  async poll() {
+    if (!this.active) return;
+    // The socket is delivering; a poll would only re-fetch what we already have.
+    if (Date.now() - this.lastPushAt < PUSH_TRUST_MS) return;
+    const room = this.room;
+    try {
+      const snap = await this.fetchLocks(room);
+      if (!snap || this.room !== room) return;
+      if (Array.isArray(snap)) {
+        this.commit(snap);
+        return;
+      }
+      if (!Array.isArray(snap.locks)) return;
+      const readsChanged =
+        Array.isArray(snap.reads) && JSON.stringify(snap.reads) !== JSON.stringify(this.reads);
+      if (Array.isArray(snap.reads)) this.reads = snap.reads;
+      this.commit(snap.locks, readsChanged);
+    } catch {
+      // Host unreachable: keep the last snapshot and let each lock age out on
+      // its own TTL, rather than flashing "all locks released" on every dropped
+      // tunnel request.
+      this.failures += 1;
+      if (this.failures === MAX_MISSES) this.emit("change", { locks: this.list() || [] });
+    }
+  }
+
+  /**
+   * The host's locks, minus anything that has since run out of TTL.
+   *
+   * A dropped poll used to blank this after 15s, which took the guest's whole
+   * Coordinator board down with it — including locks the host was still
+   * heartbeating. Ageing entries out by their own expiry instead means an
+   * unreachable host decays the board file by file, exactly as a host that went
+   * quiet would, and one slow tunnel request changes nothing.
+   */
+  list() {
+    if (!this.fresh) return null;
+    const cutoff = Date.now() - EXPIRY_GRACE_MS;
+    return this.locks.filter((l) => !l.expiresAt || l.expiresAt > cutoff);
+  }
+
+  /** Host reads, minus anything that has aged out of its own TTL. */
+  listReads() {
+    if (!this.fresh) return null;
+    const now = Date.now();
+    return (this.reads || []).filter((r) => {
+      const exp = r.expiresAt || (r.at || 0) + 30000;
+      return exp > now;
+    });
+  }
+}
+
+module.exports = { RoomLockMirror };