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

package/runtime/host/relay/config.cjs

@@ -0,0 +1,179 @@
+const { createNodePeer } = require("../nodePeer.cjs");
+const { userDataDir } = require("../matterhornrc.cjs");
+const { peerJsSignalingConfig } = require("../peerJsConfig.cjs");
+const { DEFAULT_RELAY_IPC_HOST, DEFAULT_RELAY_IPC_PORT, ensureRelayConfig, rotateRelayConfigPeerId } = require("../relayConfig.cjs");
+const { createRelayTrustStore, signRelayClaim } = require("../relayIdentity.cjs");
+const {
+  DEFAULT_RELAY_ACTIVE_FANOUT,
+  DEFAULT_RELAY_MAX_CALL_SIGNAL_BYTES,
+  DEFAULT_RELAY_MAX_BYTES_PER_ROOM,
+  DEFAULT_RELAY_MAX_EVENT_BYTES,
+  DEFAULT_RELAY_MAX_EVENTS,
+  DEFAULT_RELAY_MAX_EVENTS_PER_PUBKEY_WINDOW,
+  DEFAULT_RELAY_MAX_EVENTS_PER_ROOM,
+  DEFAULT_RELAY_MAX_FUTURE_SECONDS,
+  DEFAULT_RELAY_MAX_HOST_IPC_MESSAGE_BYTES,
+  DEFAULT_RELAY_MAX_HOST_IPC_MESSAGES_PER_WINDOW,
+  DEFAULT_RELAY_HEARTBEAT_MS,
+  DEFAULT_RELAY_HEARTBEAT_TIMEOUT_MS,
+  DEFAULT_RELAY_FAILOVER_MS,
+  DEFAULT_RELAY_MAX_MESH_MESSAGE_BYTES,
+  DEFAULT_RELAY_MAX_MESH_MESSAGES_PER_WINDOW,
+  DEFAULT_RELAY_MAX_NOSTR_MESSAGE_BYTES,
+  DEFAULT_RELAY_MAX_ROOM_MESSAGE_BYTES,
+  DEFAULT_RELAY_MAX_ROOM_MESSAGES_PER_WINDOW,
+  DEFAULT_RELAY_MAX_UNAUTHENTICATED_MESSAGES_PER_WINDOW,
+  DEFAULT_RELAY_PUBKEY_QUOTA_WINDOW_SECONDS,
+  DEFAULT_RELAY_RATE_WINDOW_MS,
+  DEFAULT_RELAY_SFU_MAX_PARTICIPANTS,
+  defaultRelayStoragePath,
+  parseRelayArgs,
+  parseIceServers,
+  resolveStoragePath
+} = require("@mh-gg/host-config");
+const { relayAddressForPeerId, relayMeshAddressForPeerId, relayMeshPeerIdForRoomPeerId } = require("@mh-gg/relay-core");
+
+function defaultStoragePath() {
+  return defaultRelayStoragePath(userDataDir());
+}
+
+function parseArgs(argv) {
+  return parseRelayArgs(argv, {
+    defaultIpcHost: DEFAULT_RELAY_IPC_HOST,
+    defaultIpcPort: DEFAULT_RELAY_IPC_PORT,
+    defaultStoragePath: defaultStoragePath()
+  });
+}
+
+function positiveInteger(value, fallback) {
+  return Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+function nonNegativeInteger(value, fallback) {
+  return Number.isInteger(value) && value >= 0 ? value : fallback;
+}
+
+function createRelayRuntimeConfig(options = {}) {
+  const peerJsSignaling = options.peerJsSignaling || peerJsSignalingConfig();
+  const dataDir = options.dataDir || userDataDir();
+  const relayConfig = ensureRelayConfig({
+    dataDir,
+    ipcHost: options.ipcHost || options.host,
+    ipcPort: options.ipcPort ?? options.port,
+    relayPeerId: options.relayPeerId,
+    relayName: options.relayName,
+    peerJsSignaling
+  });
+  const relayTrustStore = createRelayTrustStore({ dataDir, defaultSignaling: peerJsSignaling });
+  const relayPeerId = options.relayPeerId || relayConfig.relayPeerId;
+  const relayMeshPeerId = relayMeshPeerIdForRoomPeerId(relayPeerId);
+  const sfuPeerId = options.sfuPeerId || `${relayPeerId}-sfu`;
+  const resolvedRelayRefs = [];
+  for (const ref of options.relayRefs || []) {
+    const resolved = relayTrustStore.resolveReference(ref);
+    if (!resolved.ok) throw new Error(resolved.message);
+    resolvedRelayRefs.push(resolved.relayAddress);
+  }
+  const runtimeConfig = {
+    ipcHost: options.ipcHost || options.host || relayConfig.ipcHost,
+    ipcPort: Number.isInteger(options.ipcPort) ? options.ipcPort : Number.isInteger(options.port) ? options.port : relayConfig.ipcPort,
+    ipcSecret: relayConfig.ipcSecret,
+    storagePath: options.storagePath || defaultStoragePath(),
+    peerJsSignaling,
+    relayPeerId,
+    relayMeshPeerId,
+    relayAddress: relayMeshAddressForPeerId(relayPeerId, peerJsSignaling),
+    relayIdentity: relayConfig.relayIdentity,
+    relayTrustStore,
+    sfuEnabled: Boolean(options.sfuEnabled),
+    sfuPeerId,
+    sfuPeerAddress: relayAddressForPeerId(sfuPeerId, peerJsSignaling),
+    sfuMaxParticipants: positiveInteger(options.sfuMaxParticipants, DEFAULT_RELAY_SFU_MAX_PARTICIPANTS),
+    relayPeers: [...(options.relayPeers || []), ...resolvedRelayRefs],
+    activeRelayFanout: positiveInteger(options.activeRelayFanout, DEFAULT_RELAY_ACTIVE_FANOUT),
+    relayHeartbeatMs: positiveInteger(options.relayHeartbeatMs, DEFAULT_RELAY_HEARTBEAT_MS),
+    relayHeartbeatTimeoutMs: positiveInteger(options.relayHeartbeatTimeoutMs, DEFAULT_RELAY_HEARTBEAT_TIMEOUT_MS),
+    relayFailoverMs: positiveInteger(options.relayFailoverMs, DEFAULT_RELAY_FAILOVER_MS),
+    maxEvents: options.maxEvents || DEFAULT_RELAY_MAX_EVENTS,
+    maxEventsPerRoom: options.maxEventsPerRoom || DEFAULT_RELAY_MAX_EVENTS_PER_ROOM,
+    maxEventsPerStream: Number.isInteger(options.maxEventsPerStream) && options.maxEventsPerStream > 0 ? options.maxEventsPerStream : 10000,
+    maxBytesPerRoom: options.maxBytesPerRoom || DEFAULT_RELAY_MAX_BYTES_PER_ROOM,
+    maxEventsPerPubkeyWindow: options.maxEventsPerPubkeyWindow || DEFAULT_RELAY_MAX_EVENTS_PER_PUBKEY_WINDOW,
+    pubkeyQuotaWindowSeconds: options.pubkeyQuotaWindowSeconds || DEFAULT_RELAY_PUBKEY_QUOTA_WINDOW_SECONDS,
+    maxEventBytes: positiveInteger(options.maxEventBytes, DEFAULT_RELAY_MAX_EVENT_BYTES),
+    maxFutureSeconds: nonNegativeInteger(options.maxFutureSeconds, DEFAULT_RELAY_MAX_FUTURE_SECONDS),
+    maxHostIpcMessageBytes: positiveInteger(options.maxHostIpcMessageBytes, DEFAULT_RELAY_MAX_HOST_IPC_MESSAGE_BYTES),
+    maxRoomMessageBytes: positiveInteger(options.maxRoomMessageBytes, DEFAULT_RELAY_MAX_ROOM_MESSAGE_BYTES),
+    maxMeshMessageBytes: positiveInteger(options.maxMeshMessageBytes, DEFAULT_RELAY_MAX_MESH_MESSAGE_BYTES),
+    maxNostrMessageBytes: positiveInteger(options.maxNostrMessageBytes, DEFAULT_RELAY_MAX_NOSTR_MESSAGE_BYTES),
+    maxCallSignalBytes: positiveInteger(options.maxCallSignalBytes, DEFAULT_RELAY_MAX_CALL_SIGNAL_BYTES),
+    rateWindowMs: positiveInteger(options.rateWindowMs, DEFAULT_RELAY_RATE_WINDOW_MS),
+    maxUnauthenticatedMessagesPerWindow: positiveInteger(options.maxUnauthenticatedMessagesPerWindow, DEFAULT_RELAY_MAX_UNAUTHENTICATED_MESSAGES_PER_WINDOW),
+    maxRoomMessagesPerWindow: positiveInteger(options.maxRoomMessagesPerWindow, DEFAULT_RELAY_MAX_ROOM_MESSAGES_PER_WINDOW),
+    maxMeshMessagesPerWindow: positiveInteger(options.maxMeshMessagesPerWindow, DEFAULT_RELAY_MAX_MESH_MESSAGES_PER_WINDOW),
+    maxHostIpcMessagesPerWindow: positiveInteger(options.maxHostIpcMessagesPerWindow, DEFAULT_RELAY_MAX_HOST_IPC_MESSAGES_PER_WINDOW),
+    iceServers: options.iceServers || [{ urls: "stun:stun.l.google.com:19302" }],
+    startPeer: options.startPeer !== false,
+    createPeer: options.createPeer || createNodePeer
+  };
+  runtimeConfig.relayClaim = signRelayClaim(runtimeConfig.relayIdentity, {
+    relayAddress: runtimeConfig.relayAddress,
+    roomPeerId: runtimeConfig.relayPeerId,
+    relayMeshPeerId: runtimeConfig.relayMeshPeerId
+  });
+  runtimeConfig.rotateRelayTransportIdentity = (reason) => {
+    const previousRelayAddress = runtimeConfig.relayAddress;
+    const rotated = rotateRelayConfigPeerId(runtimeConfig, { dataDir, peerJsSignaling });
+    runtimeConfig.relayPeerId = rotated.relayPeerId;
+    runtimeConfig.relayMeshPeerId = rotated.relayMeshPeerId;
+    runtimeConfig.relayAddress = rotated.relayAddress;
+    runtimeConfig.relayIdentity = rotated.relayIdentity;
+    runtimeConfig.sfuPeerId = options.sfuPeerId || `${rotated.relayPeerId}-sfu`;
+    runtimeConfig.sfuPeerAddress = relayAddressForPeerId(runtimeConfig.sfuPeerId, peerJsSignaling);
+    runtimeConfig.relayClaim = signRelayClaim(runtimeConfig.relayIdentity, {
+      relayAddress: runtimeConfig.relayAddress,
+      roomPeerId: runtimeConfig.relayPeerId,
+      relayMeshPeerId: runtimeConfig.relayMeshPeerId,
+      previousRelayAddress
+    });
+    if (reason) runtimeConfig.lastRelayTransportRotationReason = reason?.message || String(reason);
+    return runtimeConfig;
+  };
+  return runtimeConfig;
+}
+
+function createRelayOptionsFromArgs(args) {
+  return {
+    ipcHost: args.ipcHost,
+    ipcPort: args.ipcPort,
+    storagePath: args.storagePath,
+    relayPeerId: args.relayPeerId,
+    relayName: args.relayName,
+    relayPeers: args.relayPeers,
+    relayRefs: args.relayRefs,
+    activeRelayFanout: args.activeRelayFanout,
+    relayHeartbeatMs: args.relayHeartbeatMs,
+    relayHeartbeatTimeoutMs: args.relayHeartbeatTimeoutMs,
+    relayFailoverMs: args.relayFailoverMs,
+    maxEvents: args.maxEvents,
+    maxEventsPerRoom: args.maxEventsPerRoom,
+    maxBytesPerRoom: args.maxBytesPerRoom,
+    maxEventsPerPubkeyWindow: args.maxEventsPerPubkeyWindow,
+    pubkeyQuotaWindowSeconds: args.pubkeyQuotaWindowSeconds,
+    maxEventBytes: args.maxEventBytes,
+    maxFutureSeconds: args.maxFutureSeconds,
+    sfuEnabled: args.sfuEnabled,
+    sfuPeerId: args.sfuPeerId,
+    sfuMaxParticipants: args.sfuMaxParticipants,
+    iceServers: parseIceServers(args.iceServers),
+    localPeerjs: args.localPeerjs
+  };
+}
+
+module.exports = {
+  createRelayOptionsFromArgs,
+  createRelayRuntimeConfig,
+  defaultStoragePath,
+  parseArgs,
+  resolveStoragePath
+};

package/runtime/host/relay/connectionCleanup.cjs

@@ -0,0 +1,34 @@
+const { sendMessage } = require("@mh-gg/relay-core");
+
+function createConnectionCleanup({
+  clientConnections,
+  clientRooms,
+  hostConnections,
+  incomingGate,
+  mesh,
+  relayClientRouting
+}) {
+  return function cleanupConnection(conn) {
+    if (conn.MatterhornCleaned) return;
+    conn.MatterhornCleaned = true;
+    incomingGate.cleanup(conn);
+    const peerId = conn.MatterhornPeerId;
+    if (peerId) {
+      clientConnections.delete(peerId);
+    }
+    mesh.cleanupConnection(conn);
+    const roomName = clientRooms.get(conn);
+    relayClientRouting?.dropClientEphemeralTokens?.(conn);
+    clientRooms.delete(conn);
+    if (roomName && peerId && conn.MatterhornNotifyHostOnClose) {
+      const host = hostConnections.get(roomName);
+      if (host) sendMessage(host, { type: "relay/client-close", peerId });
+      else mesh.sendEnvelope({ type: "relay.client.close", roomName, peerId }, conn);
+    }
+    if (conn.hostRoomName && hostConnections.get(conn.hostRoomName) === conn) {
+      hostConnections.delete(conn.hostRoomName);
+    }
+  };
+}
+
+module.exports = { createConnectionCleanup };

package/runtime/host/relay/connectionDispatcher.cjs

@@ -0,0 +1,140 @@
+const { verifyRelayControl } = require("../relayIdentity.cjs");
+const { sendMessage } = require("@mh-gg/relay-core");
+
+function createConnectionDataHandler({
+  hostAuth,
+  isNostrMessage,
+  isRelayEnvelopeMessage,
+  mesh,
+  promoteRelayConnection,
+  relayClientRouting,
+  relayHostMessages,
+  relayMeshEnvelopes,
+  relayStatus,
+  relayTrust,
+  validateRelayHints
+}) {
+  const relayControlNonces = new Set();
+
+  function rememberRelayClaim(claim, options = {}) {
+    if (!claim || typeof relayTrust?.rememberClaim !== "function") return { ok: true };
+    const result = relayTrust.rememberClaim(claim, options);
+    if (result.ok && result.claim?.relayAddress) mesh.learnRelayAddress(result.claim.relayAddress);
+    return result;
+  }
+
+  function rememberRelayClaims(message) {
+    if (Array.isArray(message.relayClaims)) {
+      for (const claim of message.relayClaims) rememberRelayClaim(claim);
+    }
+  }
+
+  function rejectRelayClaim(conn, result) {
+    sendMessage(conn, {
+      type: "relay.error",
+      code: result.code || "invalid-relay-claim",
+      message: result.message || "Relay claim is invalid."
+    });
+    conn.close?.();
+  }
+
+  return function handleConnectionData(conn, message) {
+    if (isNostrMessage(message)) {
+      if (!mesh.hasRelayConnection(conn) && mesh.connectionHasRelayMetadata(conn) && conn.MatterhornRelayAddress) promoteRelayConnection(conn);
+      return;
+    }
+    if (!message || typeof message !== "object") return;
+    if (isRelayEnvelopeMessage(message)) {
+      relayMeshEnvelopes.handleRelayEnvelope(conn, message);
+      return;
+    }
+    if (message.type === "relay.status.ok") {
+      if (message.relayAddress && !message.relayClaim && relayTrust?.pinForAddress?.(message.relayAddress)) {
+        rejectRelayClaim(conn, { code: "relay-claim-required", message: "Pinned relay address did not present a signed relay claim." });
+        return;
+      }
+      const claimResult = rememberRelayClaim(message.relayClaim, { expectedRelayAddress: message.relayAddress });
+      if (!claimResult.ok) {
+        rejectRelayClaim(conn, claimResult);
+        return;
+      }
+      rememberRelayClaims(message);
+      if (message.load) {
+        conn.MatterhornRelayLoad = message.load;
+      }
+      if (message.relayAddress && mesh.bindConnectionAddress(conn, message.relayAddress)) promoteRelayConnection(conn);
+      mesh.recordRelayLiveness?.(conn, message.relayAddress);
+      if (!mesh.hasRelayConnection(conn)) mesh.learnRelayHints(message.relayHints);
+      return;
+    }
+    if (message.type === "relay.add") {
+      if (!hostAuth.requireHostIpcAuth(conn, message)) return;
+      let relayAddress = message.relayAddress;
+      if (message.relayRef && typeof relayTrust?.resolveReference === "function") {
+        const resolved = relayTrust.resolveReference(message.relayRef);
+        if (!resolved.ok) {
+          sendMessage(conn, { type: "relay.add.error", requestId: message.requestId, code: resolved.code, message: resolved.message });
+          return;
+        }
+        relayAddress = resolved.relayAddress;
+        if (resolved.relayClaim) rememberRelayClaim(resolved.relayClaim);
+      }
+      if (message.relayClaim) {
+        const claimResult = rememberRelayClaim(message.relayClaim, { expectedRelayAddress: relayAddress });
+        if (!claimResult.ok) {
+          sendMessage(conn, { type: "relay.add.error", requestId: message.requestId, code: claimResult.code, message: claimResult.message });
+          return;
+        }
+        relayAddress = claimResult.claim.relayAddress;
+      }
+      if (!relayAddress) {
+        sendMessage(conn, { type: "relay.add.error", requestId: message.requestId, code: "missing-relay-reference", message: "Relay address or reference is required." });
+        return;
+      }
+      mesh.learnRelayAddress(relayAddress);
+      sendMessage(conn, { type: "relay.add.ok", requestId: message.requestId, relayAddress: mesh.normalizeRelayAddress(relayAddress) });
+      return;
+    }
+    if (message.type === "relay.status") {
+      if (!hostAuth.requireHostIpcAuth(conn, message)) return;
+      sendMessage(conn, relayStatus.relayStatusMessage(message.requestId));
+      return;
+    }
+    if (message.type === "relay.disconnecting") {
+      if (!mesh.hasRelayConnection(conn) && !mesh.connectionHasRelayMetadata(conn)) return;
+      const expectedRelayAddress = conn.MatterhornRelayAddress || message.relayAddress;
+      const verification = verifyRelayControl(message.relayControl, message.relayClaim, { expectedRelayAddress });
+      if (!verification.ok) return;
+      const replayKey = `${verification.control.relayAddress}:${verification.control.nonce}`;
+      if (relayControlNonces.has(replayKey)) return;
+      relayControlNonces.add(replayKey);
+      const claimResult = rememberRelayClaim(message.relayClaim, { expectedRelayAddress: verification.control.relayAddress });
+      if (!claimResult.ok) return;
+      mesh.iceAddress(verification.control.relayAddress);
+      relayClientRouting.broadcastToRoom(message.roomName, relayClientRouting.relayHintMessage(message.roomName));
+      return;
+    }
+    if (typeof message.type === "string" && message.type.startsWith("relay.") && mesh.hasRelayConnection(conn)) {
+      relayMeshEnvelopes.handleRelayEnvelope(conn, message);
+      return;
+    }
+    if (message.type === "relay.hints") {
+      const validation = validateRelayHints(message);
+      if (!validation.ok) return;
+      mesh.recordRelayLiveness?.(conn);
+      mesh.learnRelayHints(message.relayHints);
+      rememberRelayClaim(message.relayClaim);
+      rememberRelayClaims(message);
+      if (typeof message.roomName === "string") relayClientRouting.broadcastToRoom(message.roomName, relayClientRouting.relayHintMessage(message.roomName));
+      return;
+    }
+    if (typeof message.type === "string" && message.type.startsWith("host.")) {
+      if (!hostAuth.requireHostIpcAuth(conn, message)) return;
+      relayHostMessages.handleHostMessage(conn, message);
+      return;
+    }
+    relayClientRouting.routeClientMessage(conn, message);
+  };
+}
+
+module.exports = { createConnectionDataHandler };

package/runtime/host/relay/matterhornOperationEvents.cjs

@@ -0,0 +1,100 @@
+const {
+  decryptPartyPayload,
+  isEncryptedPayload,
+  nostrEventToPartyEvent,
+  MATTERHORN_OPERATION_NOSTR_KIND
+} = require("@mh-gg/event");
+const { safeValidate, validateRoomOperation } = require("@mh-gg/protocol");
+
+function tagValue(tags, name) {
+  const tag = Array.isArray(tags) ? tags.find((item) => Array.isArray(item) && item[0] === name) : undefined;
+  return tag ? tag[1] : undefined;
+}
+
+function roomNameFromOperationEvent(nostrEvent) {
+  if (nostrEvent?.kind !== MATTERHORN_OPERATION_NOSTR_KIND) return undefined;
+  return tagValue(nostrEvent.tags, "d");
+}
+
+function parseOperationPayload(event, roomSecret) {
+  if (!isEncryptedPayload(event.payload)) return event.payload;
+  if (!roomSecret) return undefined;
+  return decryptPartyPayload({
+    roomSecret,
+    partyId: event.partyId,
+    kind: event.kind,
+    payload: event.payload,
+    header: event.header
+  });
+}
+
+function parseMatterhornOperationEvent(nostrEvent, options = {}) {
+  let event;
+  try {
+    event = nostrEventToPartyEvent(nostrEvent);
+  } catch {
+    return { ok: false, reason: "invalid-matterhorn-event" };
+  }
+  if (event.kind !== "room.operation") return { ok: false, reason: "not-room-operation" };
+
+  const header = event.header;
+  const isV2 = header && header.scheme === "matterhorn.operation.v2";
+
+  // v2 events carry a plaintext header in Nostr tags. Relays MUST NOT need a room secret
+  // to validate and store them. Decryption is a client-only concern.
+  if (isV2) {
+    return {
+      ok: true,
+      roomName: event.partyId,
+      header,
+      encryptedPayload: event.payload,
+      // Decrypted application payload only available when a roomSecret is explicitly supplied.
+      payload: options.roomSecret ? parseOperationPayload(event, options.roomSecret) : undefined
+    };
+  }
+
+  // Legacy plaintext/encrypted path (kept for transitional tooling). This path is only
+  // usable when the caller can supply a roomSecret for encrypted legacy payloads.
+  let payload;
+  try {
+    payload = parseOperationPayload(event, options.roomSecret);
+  } catch {
+    return { ok: false, reason: "operation-decrypt-failed" };
+  }
+
+  const operation = payload?.operation;
+  const validation = safeValidate(validateRoomOperation, operation);
+  if (!validation.ok) return { ok: false, reason: validation.message || "invalid-operation" };
+  if (operation.roomId !== event.partyId) return { ok: false, reason: "operation-room-mismatch" };
+  if (!isEncryptedPayload(event.payload) && operation.auth?.publicKey && nostrEvent?.pubkey && operation.auth.publicKey !== nostrEvent.pubkey) {
+    return { ok: false, reason: "operation-event-signer-mismatch" };
+  }
+  return { ok: true, roomName: event.partyId, operation };
+}
+
+function operationSortValue(operation) {
+  const createdAt = Number(operation?.createdAt || 0);
+  return Number.isFinite(createdAt) ? createdAt : 0;
+}
+
+function compareMatterhornOperations(left, right) {
+  const byCreatedAt = operationSortValue(left.operation) - operationSortValue(right.operation);
+  if (byCreatedAt !== 0) return byCreatedAt;
+  return String(left.operation.id).localeCompare(String(right.operation.id));
+}
+
+function parseMatterhornOperationEvents(events, options = {}) {
+  const parsed = [];
+  for (const event of events) {
+    const result = parseMatterhornOperationEvent(event, options);
+    if (result.ok) parsed.push(result);
+  }
+  return parsed.sort(compareMatterhornOperations);
+}
+
+module.exports = {
+  MATTERHORN_OPERATION_NOSTR_KIND,
+  parseMatterhornOperationEvent,
+  parseMatterhornOperationEvents,
+  roomNameFromOperationEvent
+};

package/runtime/host/relay/matterhornRuntimeEventBridge.cjs

@@ -0,0 +1,182 @@
+const { PROTOCOL } = require("@mh-gg/host-config");
+const { generatePartyIdentity, MATTERHORN_INDEX_NGRAM_NOSTR_KIND } = require("@mh-gg/event");
+const {
+  MATTERHORN_OPERATION_NOSTR_KIND,
+  parseMatterhornOperationEvent,
+  parseMatterhornOperationEvents,
+  roomNameFromOperationEvent
+} = require("./matterhornOperationEvents.cjs");
+
+function createMatterhornRuntimeEventBridge(options) {
+  const operationEventIdentity = options.operationEventIdentity || generatePartyIdentity(options.startedAt);
+  const runtimeEventOrigin = {};
+  const debug = options.debug || (() => {});
+  const encryptedRoomRuntimes = options.encryptedRoomRuntimes;
+
+  function relay() {
+    return options.relay();
+  }
+
+  function relayPluginRuntimes() {
+    return options.relayPluginRuntimes();
+  }
+
+  function relayClientRouting() {
+    return options.relayClientRouting();
+  }
+
+  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 roomNameFromControlPlaneEvent(event) {
+    return tagValue(event?.tags, "d") || tagValue(event?.tags, "room");
+  }
+
+  function handleRoomIndexNgramEvent(event, context = {}) {
+    if (context.originConn === runtimeEventOrigin) return;
+    if (event?.kind !== MATTERHORN_INDEX_NGRAM_NOSTR_KIND) return;
+    const roomName = roomNameFromControlPlaneEvent(event);
+    if (!roomName) return;
+    encryptedRoomRuntimes?.insertEvent?.(roomName, event);
+  }
+
+  // publishMatterhornOperation is a LEGACY path for plaintext relay-as-host rooms.
+  // Encrypted v2 rooms send pre-encrypted events directly; this function is not used for them.
+  // The bridge itself never holds or accesses room secrets.
+  function publishMatterhornOperation(roomName, operation) {
+    let event;
+    try {
+      // For legacy plaintext operations, wrap them in the simple envelope the relay can sign.
+      // This intentionally does not encrypt; durable encryption for encrypted rooms is done client-side.
+      event = {
+        kind: MATTERHORN_OPERATION_NOSTR_KIND,
+        created_at: Math.floor(operation.createdAt / 1000),
+        tags: [
+          ["protocol", PROTOCOL],
+          ["version", "1"],
+          ["d", roomName],
+          ["created-at-ms", String(operation.createdAt)]
+        ],
+        content: JSON.stringify({ payload: { operation } }),
+        pubkey: operationEventIdentity.pubkey
+      };
+    } catch (error) {
+      debug(`matterhorn operation event creation failed for ${roomName}: ${error?.message || String(error)}`);
+      return;
+    }
+    const result = relay().publish(event, runtimeEventOrigin);
+    if (!result.ok) debug(`matterhorn operation event publish failed for ${roomName}: ${result.message || "unknown error"}`);
+  }
+
+  async function applyMatterhornOperation(operation, options = {}) {
+    const runtimes = relayPluginRuntimes();
+    if (!runtimes?.hasRoom?.(operation.roomId)) return;
+    const result = await runtimes.handleRelayOperation({
+      roomName: operation.roomId,
+      operation
+    });
+    if (!options.broadcast || !result?.ok || !result.state) return;
+    relayClientRouting()?.broadcastToRoom(operation.roomId, {
+      type: "host/matterhorn-state",
+      protocol: PROTOCOL,
+      roomName: operation.roomId,
+      acceptedOperationId: operation.id,
+      state: result.state
+    });
+  }
+
+  function operationFromV2(header, payload, roomName) {
+    return {
+      id: header.opId,
+      hlc: header.hlc,
+      roomId: roomName,
+      pluginId: header.plugin,
+      type: header.type,
+      schemaAction: header.action,
+      actor: {
+        memberId: header.member,
+        deviceId: header.device,
+        role: header.role
+      },
+      grants: header.grants,
+      epoch: header.epoch,
+      stream: header.stream,
+      seq: header.seq,
+      appPackId: header.appPackId,
+      appPackHash: header.appPackHash,
+      payload
+    };
+  }
+
+  async function applyMatterhornOperationEvent(event, options = {}) {
+    const roomName = roomNameFromOperationEvent(event);
+    if (!roomName) return;
+
+    // Parse WITHOUT a room secret. Relays must never hold room secrets for the operation event path.
+    const parsed = parseMatterhornOperationEvent(event);
+    if (!parsed.ok) {
+      debug(`matterhorn operation event ignored for ${roomName}: ${parsed.reason}`);
+      return;
+    }
+
+    if (parsed.operation) {
+      // Legacy plaintext operation path. Only apply if the room has a plugin runtime.
+      const runtimes = relayPluginRuntimes();
+      if (!runtimes?.hasRoom?.(roomName)) return;
+      await applyMatterhornOperation(parsed.operation, options);
+      return;
+    }
+
+    if (parsed.header) {
+      // v2 encrypted event: verify-and-store only. The relay never decrypts the payload.
+      if (parsed.payload) {
+        // A payload here means this was called with a roomSecret (legacy/config error). Do not apply.
+        debug(`matterhorn v2 operation event ignored for ${roomName}: relay was given a room secret`);
+      } else {
+        debug(`matterhorn v2 operation event stored without decryption for ${roomName}: ${parsed.header.opId}`);
+        encryptedRoomRuntimes?.insertEvent?.(roomName, event);
+      }
+    }
+  }
+
+  function handleMatterhornOperationEvent(event, context = {}) {
+    if (context.originConn === runtimeEventOrigin) return;
+    if (event?.kind === MATTERHORN_INDEX_NGRAM_NOSTR_KIND) {
+      handleRoomIndexNgramEvent(event, context);
+      return;
+    }
+    void applyMatterhornOperationEvent(event, { broadcast: true }).catch((error) => {
+      debug(`matterhorn operation event apply failed: ${error?.message || String(error)}`);
+    });
+  }
+
+  async function catchUpMatterhornRuntime(roomName, roomSecret) {
+    const runtimes = relayPluginRuntimes();
+    if (!runtimes?.hasRoom?.(roomName)) return;
+    const events = relay().query([{ kinds: [MATTERHORN_OPERATION_NOSTR_KIND], "#d": [roomName] }]);
+
+    // Parse WITHOUT a room secret. v2 encrypted events are header-only; legacy events are plaintext.
+    for (const parsed of parseMatterhornOperationEvents(events)) {
+      if (parsed.operation) {
+        // Legacy plaintext operation path.
+        await applyMatterhornOperation(parsed.operation, { broadcast: false });
+      } else if (parsed.header) {
+        // v2 encrypted event: stored by the relay event policy. No replay needed.
+        debug(`matterhorn v2 operation event caught up without decryption for ${roomName}: ${parsed.header.opId}`);
+      }
+    }
+  }
+
+  return {
+    catchUpMatterhornRuntime,
+    handleMatterhornOperationEvent,
+    publishMatterhornOperation
+  };
+}
+
+module.exports = {
+  createMatterhornRuntimeEventBridge
+};

package/runtime/host/relay/nostrRelay.cjs

@@ -0,0 +1,30 @@
+const { MatterhornNostrRelay } = require("@mh-gg/relay-core");
+const { createPartyEventPolicy } = require("@mh-gg/event");
+const { createSqliteRelayStorage } = require("../sqliteRelayStorage.cjs");
+
+function createRelayEventStore(config, options = {}) {
+  const storage = options.storage || createSqliteRelayStorage(config.storagePath);
+  const relay = new MatterhornNostrRelay({
+    eventPolicy: createPartyEventPolicy({
+      maxEventBytes: config.maxEventBytes,
+      maxFutureMs: config.maxFutureSeconds * 1000
+    }),
+    maxEventBytes: config.maxEventBytes,
+    maxEvents: config.maxEvents,
+    maxEventsPerRoom: config.maxEventsPerRoom,
+    maxBytesPerRoom: config.maxBytesPerRoom,
+    maxEventsPerPubkeyWindow: config.maxEventsPerPubkeyWindow,
+    pubkeyQuotaWindowSeconds: config.pubkeyQuotaWindowSeconds,
+    maxFutureSeconds: config.maxFutureSeconds,
+    maxMessageBytes: config.maxNostrMessageBytes,
+    onEvent: options.onEvent,
+    storage,
+    lazyStorage: options.lazyStorage !== false
+  });
+  return { relay, storage };
+}
+
+module.exports = {
+  createRelayEventStore,
+  createRelayEventPolicy: createPartyEventPolicy
+};