@mh-gg/cli 0.1.1-alpha.20260613T085325975Z

package/runtime/host/relayClientRouting.cjs

@@ -0,0 +1,1054 @@
+const { PROTOCOL } = require("@mh-gg/host-config");
+const { createMemberRootRegistry } = require("./memberRootRegistry.cjs");
+const { validateClientMessage } = require("./wireValidation/index.cjs");
+const { MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME, verifyRoomDeviceKeyClaim, verifyRoomDeviceOperationSignature, verifyRoomDeviceSignedOperation, verifyRoomMemberKeyClaim } = require("@mh-gg/protocol");
+const { sendMessage, relayMeshPeerIdForRoomPeerId } = require("@mh-gg/relay-core");
+const crypto = require("node:crypto");
+const { unwrapVapidGrant, vapidPublicKeyFromPrivateKey } = require("@mh-gg/push");
+
+const PRESENCE_STATUSES = new Set(["online", "away", "busy", "invisible", "offline"]);
+const PRESENCE_REPLAY_TTL_MS = 90_000;
+const EPHEMERAL_TOKEN_REPLAY_TTL_MS = 60_000;
+
+function createRelayClientRouting({
+  clientConnections,
+  clientRooms,
+  config,
+  debug,
+  hostConnections,
+  isClosing,
+  mesh,
+  peerSignals,
+  publishMatterhornOperation = () => {},
+  relayPluginRuntimes,
+  encryptedRoomRuntimes,
+  sfu,
+  memberRootRegistry = createMemberRootRegistry(config),
+  pushStorage,
+  pushEgress,
+  eventStorage
+}) {
+  const clientActors = new Map();
+  const presenceCache = new Map();
+  const ephemeralTokenCache = new Map();
+  const ephemeralTokensByConn = new Map();
+  const personalStateCache = new Map();
+  const deviceKeyClaims = new Map();
+
+  function sendClientMessage(conn, peerId, message) {
+    if (conn && typeof peerId === "string" && peerId && !conn.MatterhornPeerId) conn.MatterhornPeerId = peerId;
+    sendMessage(conn, message);
+  }
+
+  function actorFromClientMessage(message) {
+    const actor = message?.operation?.actor || message?.actor;
+    if (!actor || typeof actor !== "object" || Array.isArray(actor)) return undefined;
+    if (typeof actor.memberId !== "string" || typeof actor.role !== "string") return undefined;
+    return actor;
+  }
+
+  function rememberClientActor(conn, peerId, message) {
+    const actor = actorFromClientMessage(message);
+    if (!actor) return;
+    clientActors.set(conn, actor);
+    clientActors.set(peerId, actor);
+  }
+
+  function deviceKeyClaimKey(claim) {
+    if (!claim) return undefined;
+    const room = claim.roomId || claim.roomName;
+    if (!room || !claim.memberId || !claim.deviceId || !claim.keyId) return undefined;
+    return `${room}:${claim.memberId}:${claim.deviceId}:${claim.keyId}`;
+  }
+
+  function operationDeviceKeyClaimKey(operation) {
+    const auth = operation?.auth;
+    if (!auth || auth.scheme !== MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME) return undefined;
+    return `${operation.roomId}:${auth.memberId}:${auth.deviceId}:${auth.keyId}`;
+  }
+
+  function rememberDeviceKeyClaim(claim) {
+    const verification = verifyRoomMemberKeyClaim(claim);
+    if (!verification.ok) return false;
+    const key = deviceKeyClaimKey(claim);
+    if (!key) return false;
+    const rootResult = memberRootRegistry.remember(claim);
+    if (!rootResult.ok) return false;
+    deviceKeyClaims.set(key, clonePlain(claim));
+    return true;
+  }
+
+  function claimForOperation(message) {
+    const candidates = [message?.memberKey, message?.deviceKeyClaim, message?.operation?.auth?.claim];
+    for (const claim of candidates) {
+      if (claim && rememberDeviceKeyClaim(claim)) return claim;
+    }
+    const key = operationDeviceKeyClaimKey(message?.operation);
+    return key ? deviceKeyClaims.get(key) : undefined;
+  }
+
+  function validateOperationDeviceSignature(message) {
+    const auth = message?.operation?.auth;
+    if (!auth || auth.scheme !== MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME) return { ok: true, legacy: true };
+    const claim = claimForOperation(message);
+    if (!claim) return { ok: false, error: "Operation member key claim is missing." };
+    return verifyRoomDeviceOperationSignature(message.operation, claim);
+  }
+
+  function presenceText(value, max) {
+    if (typeof value !== "string") return undefined;
+    const text = value.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+    if (!text) return undefined;
+    return text.slice(0, max);
+  }
+
+  function clonePlain(value) {
+    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+  }
+
+  function tagValue(tags, name) {
+    if (!Array.isArray(tags)) return undefined;
+    const tag = tags.find((item) => Array.isArray(item) && item[0] === name && typeof item[1] === "string");
+    return tag?.[1];
+  }
+
+  function cachedPresenceKey(message) {
+    return presenceText(message?.clientId, 120)
+      || presenceText(message?.presence?.memberId, 120)
+      || presenceText(tagValue(message?.presenceEvent?.tags, "client"), 120);
+  }
+
+  function cachedPresenceExpiresAt(message, now = Date.now()) {
+    const taggedExpiration = Number(tagValue(message?.presenceEvent?.tags, "expiration"));
+    if (Number.isFinite(taggedExpiration) && taggedExpiration > 0) return taggedExpiration * 1000;
+    const lastPingAt = Number(message?.presence?.lastPingAt || message?.presence?.updatedAt);
+    if (Number.isFinite(lastPingAt) && lastPingAt > 0) return lastPingAt + PRESENCE_REPLAY_TTL_MS;
+    return now + PRESENCE_REPLAY_TTL_MS;
+  }
+
+  function prunePresenceCache(roomName, now = Date.now()) {
+    const roomCache = presenceCache.get(roomName);
+    if (!roomCache) return undefined;
+    for (const [key, item] of roomCache) {
+      if (item.expiresAt <= now) roomCache.delete(key);
+    }
+    if (roomCache.size === 0) {
+      presenceCache.delete(roomName);
+      return undefined;
+    }
+    return roomCache;
+  }
+
+  function tokenKey(message) {
+    const id = presenceText(message?.token?.id || message?.tokenId, 160);
+    const clientId = presenceText(message?.clientId || message?.token?.clientId, 120);
+    if (!id || !clientId) return undefined;
+    return `${clientId}:${id}`;
+  }
+
+  function tokenExpiresAt(message, now = Date.now()) {
+    const expiresAt = Number(message?.token?.expiresAt);
+    if (Number.isFinite(expiresAt) && expiresAt > 0) return expiresAt;
+    return now + EPHEMERAL_TOKEN_REPLAY_TTL_MS;
+  }
+
+  function pruneEphemeralTokenCache(roomName, now = Date.now()) {
+    const roomCache = ephemeralTokenCache.get(roomName);
+    if (!roomCache) return undefined;
+    for (const [key, item] of roomCache) {
+      if (item.expiresAt <= now) roomCache.delete(key);
+    }
+    if (roomCache.size === 0) {
+      ephemeralTokenCache.delete(roomName);
+      return undefined;
+    }
+    return roomCache;
+  }
+
+  function cachePresenceMessage(roomName, message) {
+    if (!roomName || message?.type !== "host/presence") return;
+    const key = cachedPresenceKey(message);
+    if (!key) return;
+    const now = Date.now();
+    const expiresAt = cachedPresenceExpiresAt(message, now);
+    if (expiresAt <= now) return;
+    const roomCache = prunePresenceCache(roomName, now) || new Map();
+    roomCache.set(key, { message: clonePlain(message), expiresAt });
+    presenceCache.set(roomName, roomCache);
+  }
+
+  function replayPresenceCache(conn, peerId, roomName) {
+    const roomCache = prunePresenceCache(roomName);
+    if (!roomCache) return;
+    for (const item of roomCache.values()) sendClientMessage(conn, peerId, clonePlain(item.message));
+  }
+
+  function replayEphemeralTokenCache(conn, peerId, roomName) {
+    const roomCache = pruneEphemeralTokenCache(roomName);
+    if (!roomCache) return;
+    for (const item of roomCache.values()) sendClientMessage(conn, peerId, clonePlain(item.message));
+  }
+
+  function rememberConnToken(conn, key, roomName, message) {
+    const tokens = ephemeralTokensByConn.get(conn) || new Map();
+    tokens.set(key, { roomName, message: clonePlain(message) });
+    ephemeralTokensByConn.set(conn, tokens);
+  }
+
+  function forgetConnToken(conn, key) {
+    const tokens = ephemeralTokensByConn.get(conn);
+    if (!tokens) return;
+    tokens.delete(key);
+    if (tokens.size === 0) ephemeralTokensByConn.delete(conn);
+  }
+
+  function cacheEphemeralTokenMessage(conn, roomName, message) {
+    if (!roomName || message?.type !== "host/ephemeral-token") return;
+    const key = tokenKey(message);
+    if (!key) return;
+    const roomCache = pruneEphemeralTokenCache(roomName) || new Map();
+    if (message.action === "release") {
+      roomCache.delete(key);
+      forgetConnToken(conn, key);
+      if (roomCache.size === 0) ephemeralTokenCache.delete(roomName);
+      return;
+    }
+    const now = Date.now();
+    const expiresAt = tokenExpiresAt(message, now);
+    if (expiresAt <= now) return;
+    roomCache.set(key, { message: clonePlain(message), expiresAt });
+    ephemeralTokenCache.set(roomName, roomCache);
+    if (conn) rememberConnToken(conn, key, roomName, message);
+  }
+
+  function presenceMemberId(message) {
+    return presenceText(message?.actor?.memberId, 120)
+      || presenceText(message?.memberId, 120)
+      || presenceText(message?.clientId, 120);
+  }
+
+  function actorDisplayName(actor, memberId) {
+    return presenceText(actor?.displayName, 80)
+      || presenceText(actor?.name, 80)
+      || memberId;
+  }
+
+  function canSeeInvisiblePresence(actor, memberId) {
+    return actor?.memberId === memberId || actor?.role === "moderator" || actor?.role === "admin" || actor?.role === "owner";
+  }
+
+  function hostPresenceMessage(message, recipientActor) {
+    if (message.presenceEvent) {
+      return {
+        type: "host/presence",
+        protocol: PROTOCOL,
+        roomName: message.roomName,
+        clientId: message.clientId,
+        presenceEvent: message.presenceEvent
+      };
+    }
+    const actor = actorFromClientMessage(message) || {};
+    const memberId = presenceMemberId(message);
+    if (!memberId) return undefined;
+    const declaredStatus = PRESENCE_STATUSES.has(message.status) ? message.status : "online";
+    const hiddenForRecipient = declaredStatus === "invisible" && !canSeeInvisiblePresence(recipientActor, memberId);
+    const status = hiddenForRecipient ? "offline" : declaredStatus;
+    const now = Number.isFinite(Number(message.at)) ? Number(message.at) : Date.now();
+    const presence = {
+      memberId,
+      name: actorDisplayName(actor, memberId),
+      status,
+      activity: hiddenForRecipient ? null : presenceText(message.activity, 160) || null,
+      updatedAt: now,
+      lastPingAt: now,
+      visible: status !== "offline" && status !== "invisible"
+    };
+    if (!hiddenForRecipient) presence.declaredStatus = declaredStatus;
+    return {
+      type: "host/presence",
+      protocol: PROTOCOL,
+      roomName: message.roomName,
+      clientId: message.clientId,
+      presence
+    };
+  }
+
+  function meshPresenceMessage(message) {
+    if (message.presenceEvent) return hostPresenceMessage(message);
+    if (message.status !== "invisible") return hostPresenceMessage(message);
+    return hostPresenceMessage({ ...message, status: "offline", activity: undefined });
+  }
+
+  function sendHostUnavailable(conn, peerId) {
+    sendClientMessage(conn, peerId, {
+      type: "host/error",
+      protocol: PROTOCOL,
+      code: "host-unavailable",
+      message: "The room runtime is not connected to this relay."
+    });
+  }
+
+  function sendMatterhornSnapshot(conn, peerId, roomName, actor) {
+    if (!relayPluginRuntimes?.hasRoom?.(roomName)) {
+      debug(`matterhorn-state unavailable ${roomName}: runtime missing`);
+      return false;
+    }
+    debug(`matterhorn-state snapshot requested ${roomName}`);
+    void relayPluginRuntimes.snapshot(roomName, actor).then((snapshot) => {
+      if (!snapshot) {
+        debug(`matterhorn-state unavailable ${roomName}: empty snapshot`);
+        sendHostUnavailable(conn, peerId);
+        return;
+      }
+      debug(`matterhorn-state snapshot sent ${roomName} version=${snapshot.state?.version ?? "unknown"}`);
+      sendClientMessage(conn, peerId, {
+        type: "host/matterhorn-state",
+        protocol: PROTOCOL,
+        roomName,
+        state: snapshot.state
+      });
+    }).catch((error) => {
+      debug(`matterhorn-state snapshot failed ${roomName}: ${error?.message || String(error)}`);
+      sendClientMessage(conn, peerId, {
+        type: "host/error",
+        protocol: PROTOCOL,
+        code: "matterhorn-state-unavailable",
+        message: error?.message || "Matterhorn state is unavailable."
+      });
+    });
+    return true;
+  }
+
+  function messageDebugSummary(conn, message) {
+    const keys = message && typeof message === "object" && !Array.isArray(message) ? Object.keys(message).sort() : [];
+    return JSON.stringify({
+      peerId: conn.MatterhornPeerId || conn.peer || conn.id || "unknown",
+      type: message?.type,
+      roomName: message?.roomName,
+      clientId: message?.clientId,
+      keys
+    });
+  }
+
+  function sendInvalidClientMessage(conn, message, validation) {
+    debug(`invalid client message ${validation.message}; ${messageDebugSummary(conn, message)}`);
+    sendClientMessage(conn, conn.MatterhornPeerId || mesh.scopedPeerId(conn), {
+      type: "host/error",
+      protocol: PROTOCOL,
+      code: validation.code,
+      message: validation.message
+    });
+  }
+
+  function sendRelayHostEnvelope(relayConn, peerId, roomName, message) {
+    sendMessage(relayConn, {
+      type: "relay.host",
+      id: mesh.nextMessageId("relay.host"),
+      roomName,
+      peerId,
+      message
+    });
+  }
+
+  function sendToClient(peerId, message, roomName) {
+    const conn = clientConnections.get(peerId);
+    if (conn && conn.open !== false) {
+      debug(`client.send direct ${peerId} ${message?.type || "message"}`);
+      sendClientMessage(conn, peerId, message);
+      return;
+    }
+
+    if (mesh.sendDiscoveredClientRoute(peerId, message, undefined, roomName)) {
+      return;
+    }
+
+    const relayConn = mesh.remoteClientRoute(peerId);
+    if (relayConn && relayConn.open !== false) {
+      debug(`client.send relay route ${peerId} ${message?.type || "message"}`);
+      sendRelayHostEnvelope(relayConn, peerId, roomName, message);
+      return;
+    }
+
+    const latestRoute = mesh.latestClientRoute(roomName, message?.clientId);
+    if (latestRoute?.conn) {
+      if (clientConnections.get(latestRoute.peerId) === latestRoute.conn) {
+        debug(`client.send latest direct ${latestRoute.peerId} ${message?.type || "message"}`);
+        sendClientMessage(latestRoute.conn, latestRoute.peerId, message);
+        return;
+      }
+      debug(`client.send latest relay route ${latestRoute.peerId} ${message?.type || "message"}`);
+      sendRelayHostEnvelope(latestRoute.conn, latestRoute.peerId, roomName, message);
+      return;
+    }
+
+    debug(`client.send relay envelope ${peerId} ${message?.type || "message"}`);
+    mesh.sendEnvelope({
+      type: "relay.host",
+      id: mesh.nextMessageId("relay.host"),
+      roomName,
+      peerId,
+      message
+    });
+  }
+
+  function broadcastToRoom(roomName, message) {
+    cachePresenceMessage(roomName, message);
+    cacheEphemeralTokenMessage(undefined, roomName, message);
+    for (const [conn, clientRoomName] of clientRooms) {
+      if (clientRoomName === roomName && conn.open !== false) sendClientMessage(conn, conn.MatterhornPeerId || mesh.scopedPeerId(conn), message);
+    }
+  }
+
+  async function materializeBroadcastMessage(message, actor) {
+    return typeof message === "function" ? await message(actor) : message;
+  }
+
+  async function sendBroadcastRoute(route, roomName, message, sentConns, sentPeerIds) {
+    if (!route?.conn || route.conn.open === false || sentPeerIds.has(route.peerId)) return;
+    sentPeerIds.add(route.peerId);
+    const actor = clientActors.get(route.peerId) || clientActors.get(route.conn);
+    const resolvedMessage = await materializeBroadcastMessage(message, actor);
+    if (!resolvedMessage) return;
+    if (clientConnections.get(route.peerId) === route.conn) {
+      if (!sentConns.has(route.conn)) {
+        debug(`client.broadcast latest direct ${route.peerId} ${resolvedMessage?.type || "message"}`);
+        sendClientMessage(route.conn, route.peerId, resolvedMessage);
+        sentConns.add(route.conn);
+      }
+      return;
+    }
+    debug(`client.broadcast latest relay route ${route.peerId} ${resolvedMessage?.type || "message"}`);
+    sendRelayHostEnvelope(route.conn, route.peerId, roomName, resolvedMessage);
+  }
+
+  async function broadcastHostToRoom(roomName, message) {
+    const sentConns = new Set();
+    const sentPeerIds = new Set();
+    const sends = [];
+    for (const [conn, clientRoomName] of clientRooms) {
+      if (clientRoomName !== roomName || conn.open === false) continue;
+      const actor = clientActors.get(conn);
+      sends.push(materializeBroadcastMessage(message, actor).then((resolvedMessage) => {
+        if (!resolvedMessage) return;
+        debug(`client.broadcast direct ${conn.MatterhornPeerId || conn.peer || "unknown"} ${resolvedMessage?.type || "message"}`);
+        sendClientMessage(conn, conn.MatterhornPeerId || mesh.scopedPeerId(conn), resolvedMessage);
+      }));
+      sentConns.add(conn);
+      if (conn.MatterhornPeerId) sentPeerIds.add(conn.MatterhornPeerId);
+    }
+
+    for (const route of mesh.clientRoutesForRoom(roomName)) {
+      sends.push(sendBroadcastRoute(route, roomName, message, sentConns, sentPeerIds));
+    }
+    await Promise.all(sends);
+  }
+
+  function relayHints() {
+    return mesh.relayHints();
+  }
+
+  function relayClaims() {
+    return [
+      config.relayClaim,
+      ...(typeof config.relayTrustStore?.claims === "function" ? config.relayTrustStore.claims() : [])
+    ].filter(Boolean);
+  }
+
+  function relayHintMessage(roomName) {
+    const roomApp = relayPluginRuntimes?.roomApp?.(roomName);
+    const runtimeCapabilities = relayPluginRuntimes?.runtimeCapabilities?.(roomName);
+    const message = {
+      type: "relay.hints",
+      roomName,
+      relayHints: relayHints(),
+      icedRelayHints: mesh.icedRelayHints(),
+      relayClaim: config.relayClaim,
+      relayClaims: relayClaims(),
+      relayHealth: typeof mesh.relayHealth === "function" ? mesh.relayHealth() : [],
+      iceServers: config.iceServers,
+      sfu: sfu.status(roomName)
+    };
+    if (roomApp) message.roomApp = roomApp;
+    if (runtimeCapabilities) message.runtimeCapabilities = runtimeCapabilities;
+    return message;
+  }
+
+  function relayRuntimeOwnsRoom(roomName) {
+    return Boolean(relayPluginRuntimes?.hasRoom?.(roomName));
+  }
+
+  function cachedFrontendProof(message) {
+    const proof = message?.cachedFrontend;
+    if (!proof || typeof proof !== "object" || Array.isArray(proof)) return undefined;
+    if (typeof proof.id !== "string" || !proof.id) return undefined;
+    if (typeof proof.integrity !== "string" || !proof.integrity) return undefined;
+    const result = { id: proof.id, integrity: proof.integrity };
+    if (Number.isInteger(proof.byteLength) && proof.byteLength >= 0) result.byteLength = proof.byteLength;
+    return result;
+  }
+
+  function frontendCacheStatus(roomApp, message) {
+    const frontend = Array.isArray(roomApp?.frontends) ? roomApp.frontends[0] : undefined;
+    if (!frontend?.id) return undefined;
+    const proof = cachedFrontendProof(message);
+    const sameFrontend = proof?.id === frontend.id && proof.integrity === frontend.integrity;
+    const sameLength = proof?.byteLength === undefined || frontend.byteLength === undefined || proof.byteLength === frontend.byteLength;
+    return {
+      frontendId: frontend.id,
+      integrity: frontend.integrity,
+      byteLength: frontend.byteLength,
+      clientHasCurrentBundle: Boolean(sameFrontend && sameLength)
+    };
+  }
+
+  function roomInfoMessage(roomName, request) {
+    const roomApp = relayPluginRuntimes?.roomApp?.(roomName);
+    if (!roomApp) return undefined;
+    const runtimeCapabilities = relayPluginRuntimes?.runtimeCapabilities?.(roomName);
+    const message = {
+      type: "room.info",
+      protocol: PROTOCOL,
+      roomName,
+      roomApp,
+      relayHints: relayHints(),
+      icedRelayHints: mesh.icedRelayHints(),
+      relayClaim: config.relayClaim,
+      relayClaims: relayClaims(),
+      relayHealth: typeof mesh.relayHealth === "function" ? mesh.relayHealth() : [],
+      iceServers: config.iceServers,
+      sfu: sfu.status(roomName)
+    };
+    if (request?.clientId) message.clientId = request.clientId;
+    if (runtimeCapabilities) message.runtimeCapabilities = runtimeCapabilities;
+    const cache = frontendCacheStatus(roomApp, request);
+    if (cache) message.frontendCache = cache;
+    return message;
+  }
+
+  function shouldForwardRoomInfoToHost(roomName) {
+    if (!hostConnections.get(roomName)) return false;
+    const roomApp = relayPluginRuntimes?.roomApp?.(roomName);
+    const frontend = Array.isArray(roomApp?.frontends) ? roomApp.frontends[0] : undefined;
+    return frontend?.dynamic === true;
+  }
+
+  function relaySfuMessage(roomName) {
+    return {
+      type: "relay.sfu",
+      roomName,
+      sfu: sfu.status(roomName)
+    };
+  }
+
+  function broadcastSfuStatus(roomName) {
+    if (isClosing() || !roomName) return;
+    broadcastToRoom(roomName, relaySfuMessage(roomName));
+  }
+
+  function forwardClientToMesh(conn, peerId, roomName, message) {
+    if (mesh.relayConnectionCount() === 0) return false;
+    mesh.sendEnvelope({
+      type: "relay.client",
+      id: mesh.nextMessageId("relay.client"),
+      roomName,
+      peerId,
+      message
+    }, conn);
+    return true;
+  }
+
+  function forwardClientRequest(conn, peerId, roomName, message) {
+    const host = hostConnections.get(roomName);
+    if (host) {
+      sendMessage(host, {
+        type: "relay/client-message",
+        peerId,
+        message
+      });
+      return true;
+    }
+    return forwardClientToMesh(conn, peerId, roomName, message);
+  }
+
+  function roomIndexSearchResultsMessage(roomName, request, result) {
+    return {
+      type: "host/room-index-search-results",
+      protocol: PROTOCOL,
+      roomName,
+      clientId: request.clientId,
+      requestId: request.requestId,
+      suite: request.suite,
+      keyId: request.keyId,
+      stream: request.stream,
+      mode: request.mode || "all",
+      events: Array.isArray(result?.events) ? result.events : [],
+      matches: Array.isArray(result?.matches) ? result.matches : [],
+      total: Number.isInteger(result?.total) ? result.total : 0,
+      queryTokenCount: Number.isInteger(result?.queryTokenCount) ? result.queryTokenCount : 0
+    };
+  }
+
+  function handleRoomIndexSearch(conn, peerId, roomName, message) {
+    const runtime = encryptedRoomRuntimes?.getRoom?.(roomName);
+    if (!runtime || typeof runtime.searchNgrams !== "function") return false;
+    const result = runtime.searchNgrams({
+      suite: message.suite,
+      keyId: message.keyId,
+      tokens: message.tokens,
+      stream: message.stream,
+      mode: message.mode,
+      minScore: message.minScore,
+      limit: message.limit,
+      offset: message.offset,
+      order: message.order
+    });
+    sendClientMessage(conn, peerId, roomIndexSearchResultsMessage(roomName, message, result));
+    return true;
+  }
+
+  function handleRelayPluginOperation(conn, peerId, roomName, message) {
+    if (!relayPluginRuntimes?.hasRoom?.(roomName)) return false;
+    void relayPluginRuntimes.handleClientOperation({
+      roomName,
+      peerId,
+      message,
+      sendToClient,
+      broadcastToRoom: broadcastHostToRoom,
+      broadcastToMesh: (envelope) => mesh.sendEnvelope(envelope)
+    }).then((result) => {
+      if (result?.ok && !result.duplicate && message.operation?.auth?.scheme !== MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME) {
+        publishMatterhornOperation(roomName, message.operation);
+      }
+    }).catch((error) => {
+      sendClientMessage(conn, peerId, {
+        type: "host/error",
+        protocol: PROTOCOL,
+        code: "operation-runtime-error",
+        message: error?.message || "Relay operation runtime failed."
+      });
+    });
+    return true;
+  }
+
+  function handleClientPresence(peerId, roomName, message) {
+    const relayMessage = meshPresenceMessage(message);
+    if (relayMessage) cachePresenceMessage(roomName, relayMessage);
+    void broadcastHostToRoom(roomName, (actor) => hostPresenceMessage(message, actor));
+    if (relayMessage) {
+      mesh.sendEnvelope({
+        type: "relay.broadcast",
+        id: mesh.nextMessageId("relay.broadcast"),
+        roomName,
+        message: relayMessage
+      });
+    }
+  }
+
+  function hostEphemeralTokenMessage(message) {
+    if (message.action === "release") {
+      return {
+        type: "host/ephemeral-token",
+        protocol: PROTOCOL,
+        roomName: message.roomName,
+        clientId: message.clientId,
+        action: "release",
+        tokenId: message.tokenId
+      };
+    }
+    return {
+      type: "host/ephemeral-token",
+      protocol: PROTOCOL,
+      roomName: message.roomName,
+      clientId: message.clientId,
+      action: "upsert",
+      token: message.token
+    };
+  }
+
+  function handleClientEphemeralToken(conn, roomName, message) {
+    const relayMessage = hostEphemeralTokenMessage(message);
+    cacheEphemeralTokenMessage(conn, roomName, relayMessage);
+    broadcastHostToRoom(roomName, relayMessage);
+    mesh.sendEnvelope({
+      type: "relay.broadcast",
+      id: mesh.nextMessageId("relay.broadcast"),
+      roomName,
+      message: relayMessage
+    });
+  }
+
+  function hostPersonalStateMessage(message) {
+    return {
+      type: "host/personal-state",
+      protocol: PROTOCOL,
+      roomName: message.roomName,
+      clientId: message.clientId,
+      stateId: message.stateId,
+      updatedAt: message.updatedAt,
+      payload: message.payload
+    };
+  }
+
+  function pendingPushTtlSeconds(message) {
+    return Number.isInteger(message?.ttlSeconds) && message.ttlSeconds > 0 ? message.ttlSeconds : 60 * 60;
+  }
+
+  function persistPendingPush(relayPush, reason) {
+    const userId = relayPush?.target?.userId;
+    if (!pushStorage?.upsertPendingPush || !relayPush?.pushId || !userId) return;
+    pushStorage.upsertPendingPush({
+      pushId: relayPush.pushId,
+      userId,
+      payload: relayPush,
+      ttlSeconds: pendingPushTtlSeconds(relayPush)
+    });
+    debug(`push pending ${relayPush.pushId} ${reason || "deferred"}`);
+  }
+
+  function rememberPersonalState(roomName, message) {
+    const previous = personalStateCache.get(roomName);
+    if (previous && Number(previous.updatedAt) > Number(message.updatedAt)) return previous;
+    personalStateCache.set(roomName, message);
+    return message;
+  }
+
+  function rememberPersonalStateFromHostMessage(roomName, message) {
+    if (message?.type !== "host/personal-state") return;
+    rememberPersonalState(roomName, message);
+  }
+
+  function replayPersonalStateCache(conn, peerId, roomName) {
+    const cached = personalStateCache.get(roomName);
+    if (cached) sendClientMessage(conn, peerId, cached);
+  }
+
+  function personalStateHostMessageForRoom(roomName) {
+    return personalStateCache.get(roomName);
+  }
+
+  function handleClientPersonalState(conn, peerId, roomName, message) {
+    if (message.action === "subscribe") {
+      sendClientMessage(conn, peerId, relayHintMessage(roomName));
+      replayPersonalStateCache(conn, peerId, roomName);
+      forwardClientToMesh(conn, peerId, roomName, message);
+      return;
+    }
+    const relayMessage = rememberPersonalState(roomName, hostPersonalStateMessage(message));
+    broadcastHostToRoom(roomName, relayMessage);
+    mesh.sendEnvelope({
+      type: "relay.broadcast",
+      id: mesh.nextMessageId("relay.broadcast"),
+      roomName,
+      message: relayMessage
+    });
+  }
+
+  function dropClientEphemeralTokens(conn) {
+    const tokens = ephemeralTokensByConn.get(conn);
+    if (!tokens) return;
+    ephemeralTokensByConn.delete(conn);
+    for (const [key, item] of tokens) {
+      const roomCache = ephemeralTokenCache.get(item.roomName);
+      roomCache?.delete(key);
+      if (roomCache?.size === 0) ephemeralTokenCache.delete(item.roomName);
+      const releaseMessage = {
+        ...item.message,
+        action: "release",
+        tokenId: item.message.token?.id || item.message.tokenId,
+        token: undefined
+      };
+      broadcastHostToRoom(item.roomName, releaseMessage);
+      mesh.sendEnvelope({
+        type: "relay.broadcast",
+        id: mesh.nextMessageId("relay.broadcast"),
+        roomName: item.roomName,
+        message: releaseMessage
+      });
+    }
+  }
+
+  function handleClientPushGrant(conn, message) {
+    const isTargetLocal = (message.relayId === config.relayPeerId || message.relayId === config.relayMeshPeerId);
+    if (isTargetLocal) {
+      try {
+        // VAPID grants are X25519-wrapped, so unwrap with the relay's X25519
+        // grant key — not the Ed25519 identity key (which can't do ECDH).
+        const relayPrivateKey = crypto.createPrivateKey(config.relayIdentity.grantPrivateKeyPem);
+        const { vapidPrivateKey } = unwrapVapidGrant({
+          grant: message.grant,
+          relayPrivateKey
+        });
+        const vapidPublicKey = vapidPublicKeyFromPrivateKey(vapidPrivateKey);
+        pushStorage?.upsertGrant({
+          userId: message.userId,
+          vapidPrivateKey,
+          vapidPublicKey
+        });
+        return { ok: true };
+      } catch (err) {
+        if (process.env.MATTERHORN_DEBUG === "1") {
+          console.error("Failed to unwrap VAPID grant:", err);
+        }
+        return { ok: false, code: "grant-unwrap-failed", message: err?.message || "Failed to unwrap push grant." };
+      }
+    } else {
+      const targetMeshPeerId = message.relayId.endsWith("-relay") ? message.relayId : relayMeshPeerIdForRoomPeerId(message.relayId);
+      const targetConn = mesh.connections().find(c => c.peer === targetMeshPeerId || c.MatterhornRelayAddress === message.relayId);
+      const envelope = {
+        type: "relay.client",
+        id: mesh.nextMessageId("relay.client"),
+        roomName: "push",
+        peerId: mesh.scopedPeerId(conn),
+        message: { ...message, roomName: "push" }
+      };
+      if (targetConn && targetConn.open !== false) {
+        sendMessage(targetConn, envelope);
+      } else {
+        mesh.sendEnvelope(envelope);
+      }
+      return { ok: true };
+    }
+  }
+
+  // A client asked the relay to deliver a push to other users. The relay only
+  // routes/delivers it — it does not read room operations or decrypt anything.
+  // The opaque payload is delivered locally if this relay holds the user's grant,
+  // otherwise it is fanned out over the mesh for the user's home relay to deliver.
+  function handleClientPushSend(message) {
+    const userIds = Array.isArray(message.userIds) ? message.userIds : [];
+    const pushIds = [];
+    for (const userId of userIds) {
+      if (typeof userId !== "string" || !userId) continue;
+      const pushId = `${message.pushId || mesh.nextMessageId("push")}:${userId}`;
+      pushIds.push(pushId);
+      const relayPush = {
+        type: "relay.push",
+        id: pushId,
+        pushId,
+        target: { userId },
+        payload: message.payload,
+        ttlSeconds: message.ttlSeconds,
+        urgency: message.urgency
+      };
+      const grant = pushStorage?.selectGrant(userId);
+      if (grant) {
+        pushEgress?.sendRelayPush(relayPush).then((result) => {
+          if (!result || result.delivered <= 0) persistPendingPush(relayPush, result?.reason || "local-egress-deferred");
+        }).catch((err) => {
+          if (process.env.MATTERHORN_DEBUG === "1") console.error(`Failed to send web push for user ${userId}:`, err);
+          persistPendingPush(relayPush, "local-egress-error");
+        });
+      } else {
+        persistPendingPush(relayPush, "mesh-pending-ack");
+        const fanout = mesh.sendEnvelope(relayPush);
+        if (!fanout) debug(`push pending ${pushId} mesh-unavailable`);
+      }
+    }
+    return pushIds;
+  }
+
+  function routeClientMessage(conn, message) {
+    const validation = validateClientMessage(message);
+    if (!validation.ok) {
+      sendInvalidClientMessage(conn, message, validation);
+      return;
+    }
+    if (message.type === "client/push-grant") {
+      const peerId = mesh.scopedPeerId(conn);
+      clientConnections.set(peerId, conn);
+      rememberClientActor(conn, peerId, message);
+      const result = handleClientPushGrant(conn, message);
+      if (result?.ok === false) {
+        sendClientMessage(conn, peerId, {
+          type: "client/push-grant.error",
+          protocol: PROTOCOL,
+          code: result.code || "push-grant-error",
+          message: result.message || "Push grant failed."
+        });
+      } else {
+        sendClientMessage(conn, peerId, {
+          type: "client/push-grant.ok",
+          protocol: PROTOCOL
+        });
+      }
+      return;
+    }
+    if (message.type === "client/push-send") {
+      const peerId = mesh.scopedPeerId(conn);
+      clientConnections.set(peerId, conn);
+      rememberClientActor(conn, peerId, message);
+      const pushIds = handleClientPushSend(message);
+      sendClientMessage(conn, peerId, {
+        type: "client/push-send.ok",
+        protocol: PROTOCOL,
+        pushIds
+      });
+      return;
+    }
+    const roomName = typeof message.roomName === "string" ? message.roomName : undefined;
+    if (message.type === "client/push-register") {
+      const peerId = mesh.scopedPeerId(conn);
+      clientConnections.set(peerId, conn);
+      rememberClientActor(conn, peerId, message);
+      if (roomName) {
+        clientRooms.set(conn, roomName);
+        mesh.rememberClientRoute(conn, roomName, message.clientId, peerId);
+      }
+      pushStorage?.upsertSubscription({
+        userId: message.userId,
+        deviceId: message.clientId,
+        subscription: message.subscription
+      });
+      const grant = pushStorage?.selectGrant(message.userId);
+      sendClientMessage(conn, peerId, {
+        type: "client/push-register.ok",
+        protocol: PROTOCOL,
+        hasGrant: Boolean(grant)
+      });
+      const events = eventStorage ? eventStorage.queryEvents([{ kinds: [9002] }]) : [];
+      let latestPayload = null;
+      for (const event of events) {
+        try {
+          const content = JSON.parse(event.content || "{}");
+          const payload = content.payload;
+          if (payload && payload.userId === message.userId) {
+            if (!latestPayload || payload.updatedAt > latestPayload.updatedAt) {
+              latestPayload = payload;
+            }
+          }
+        } catch {}
+      }
+      if (latestPayload && Array.isArray(latestPayload.relayIds)) {
+        const localAddresses = [config.relayAddress, config.relayPeerId, config.relayMeshPeerId];
+        for (const relayId of latestPayload.relayIds) {
+          if (localAddresses.includes(relayId)) continue;
+          const targetMeshPeerId = relayId.endsWith("-relay") ? relayId : relayMeshPeerIdForRoomPeerId(relayId);
+          const targetConn = mesh.connections().find(c => c.peer === targetMeshPeerId || c.MatterhornRelayAddress === relayId);
+          const envelope = {
+            type: "relay.client",
+            id: mesh.nextMessageId("relay.client"),
+            roomName: roomName || "push",
+            peerId: peerId,
+            message: { ...message, roomName: roomName || "push" }
+          };
+          if (targetConn && targetConn.open !== false) {
+            sendMessage(targetConn, envelope);
+          } else {
+            mesh.sendEnvelope(envelope);
+          }
+        }
+      }
+      return;
+    }
+    if (!roomName) return;
+    mesh.learnRelayHints(message.relayHints);
+    if (message.type === "client/peer-signal") {
+      peerSignals.routePeerSignalMessage(conn, message);
+      return;
+    }
+
+    const peerId = mesh.scopedPeerId(conn);
+    clientConnections.set(peerId, conn);
+    clientRooms.set(conn, roomName);
+    mesh.rememberClientRoute(conn, roomName, message.clientId, peerId);
+    rememberClientActor(conn, peerId, message);
+
+    if (message.type === "client/hello") {
+      if (message.memberKey) rememberDeviceKeyClaim(message.memberKey);
+      if (message.deviceKeyClaim) rememberDeviceKeyClaim(message.deviceKeyClaim);
+      sendClientMessage(conn, peerId, relayHintMessage(roomName));
+      replayPresenceCache(conn, peerId, roomName);
+      replayEphemeralTokenCache(conn, peerId, roomName);
+      if (relayRuntimeOwnsRoom(roomName)) return;
+      forwardClientRequest(conn, peerId, roomName, message);
+      return;
+    }
+
+    if (message.type === "client/member-key") {
+      if (!rememberDeviceKeyClaim(message.claim)) {
+        sendClientMessage(conn, peerId, { type: "host/error", protocol: PROTOCOL, code: "invalid-member-key", message: "Matterhorn member key claim is invalid." });
+      }
+      return;
+    }
+
+    if (message.type === "client/room-info") {
+      const hints = relayHintMessage(roomName);
+      const info = roomInfoMessage(roomName, message);
+      const shouldForward = shouldForwardRoomInfoToHost(roomName);
+      sendClientMessage(conn, peerId, hints);
+      if (shouldForward) {
+        if (forwardClientRequest(conn, peerId, roomName, message)) return;
+      }
+      if (info) {
+        sendClientMessage(conn, peerId, info);
+        return;
+      }
+      if (forwardClientToMesh(conn, peerId, roomName, message)) return;
+      sendHostUnavailable(conn, peerId);
+      return;
+    }
+
+    if (message.type === "client/matterhorn-state" || message.type === "client/snapshot-request") {
+      replayPresenceCache(conn, peerId, roomName);
+      replayEphemeralTokenCache(conn, peerId, roomName);
+      if (sendMatterhornSnapshot(conn, peerId, roomName, clientActors.get(conn) || actorFromClientMessage(message))) return;
+      if (!forwardClientToMesh(conn, peerId, roomName, message)) sendHostUnavailable(conn, peerId);
+      return;
+    }
+
+    if (message.type === "client/presence") {
+      handleClientPresence(peerId, roomName, message);
+      return;
+    }
+
+    if (message.type === "client/ephemeral-token") {
+      handleClientEphemeralToken(conn, roomName, message);
+      return;
+    }
+
+    if (message.type === "client/personal-state") {
+      handleClientPersonalState(conn, peerId, roomName, message);
+      return;
+    }
+
+    if (message.type === "client/room-index-search") {
+      if (handleRoomIndexSearch(conn, peerId, roomName, message)) return;
+      if (!forwardClientToMesh(conn, peerId, roomName, message)) {
+        sendClientMessage(conn, peerId, roomIndexSearchResultsMessage(roomName, message, { events: [], matches: [], total: 0, queryTokenCount: message.tokens.length }));
+      }
+      return;
+    }
+
+    if (message.type === "client/operation") {
+      const signatureCheck = validateOperationDeviceSignature(message);
+      if (!signatureCheck.ok) {
+        sendClientMessage(conn, peerId, { type: "host/error", protocol: PROTOCOL, code: "invalid-operation-signature", message: signatureCheck.error || "Matterhorn operation signature is invalid." });
+        return;
+      }
+      if (handleRelayPluginOperation(conn, peerId, roomName, message)) return;
+      if (!forwardClientToMesh(conn, peerId, roomName, message)) sendHostUnavailable(conn, peerId);
+      return;
+    }
+
+    if (message.type === "client/frontend-manifest" || message.type === "client/frontend-chunk") {
+      if (!forwardClientRequest(conn, peerId, roomName, message)) sendHostUnavailable(conn, peerId);
+    }
+  }
+
+  return {
+    broadcastHostToRoom,
+    broadcastSfuStatus,
+    broadcastToRoom,
+    relayHintMessage,
+    relaySfuMessage,
+    routeClientMessage,
+    dropClientEphemeralTokens,
+    rememberPersonalStateFromHostMessage,
+    personalStateHostMessageForRoom,
+    sendToClient
+  };
+}
+
+module.exports = {
+  createRelayClientRouting
+};