@mh-gg/relay 0.1.1-alpha.20260626T104441232Z

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matterhorn contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @mh-gg/relay
+
+Matterhorn relay: signaling and forwarding server runtime for matterhorn rooms. Owns the relay process entry point, client/host message routing, mesh and SFU bindings, push storage, relay identity/trust, and the shared wire-validation and config primitives consumed by both the relay and the host.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@mh-gg/relay",
+  "version": "0.1.1-alpha.20260626T104441232Z",
+  "description": "Matterhorn relay: signaling and forwarding server runtime for matterhorn rooms.",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs",
+    "./src/*": "./src/*",
+    "./relay.cjs": "./src/relay.cjs",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@roamhq/wrtc": "^0.10.0",
+    "nostr-tools": "^2.23.5",
+    "peer": "^1.0.2",
+    "peerjs": "^1.5.5",
+    "ws": "^8.21.0",
+    "xhr2": "^0.2.1",
+    "@mh-gg/host-runtime": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/base": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/host-config": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/relay-core": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/host-store": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/event": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/protocol": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/relay-runtime": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/push": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/host-ipc": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/relay-mesh": "^0.1.1-alpha.20260626T104441232Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=60 --test-coverage-include=src/**/*.cjs test/*.test.cjs"
+  }
+}

package/src/callAuth.cjs

@@ -0,0 +1,76 @@
+const { canonicalJson, MATTERHORN_CALL_SIGNAL_NOSTR_KIND } = require("@mh-gg/event");
+const { finalizeEvent, verifyEvent } = require("nostr-tools/pure");
+const { hexToBytes } = require("nostr-tools/utils");
+
+const CALL_SIGNAL_MAX_AGE_SECONDS = 10 * 60;
+const CALL_SIGNAL_FUTURE_SKEW_SECONDS = 60;
+
+function isHex(value, length) {
+  return typeof value === "string" && new RegExp(`^[0-9a-f]{${length}}$`, "i").test(value);
+}
+
+function signedContent(input) {
+  return canonicalJson({
+    protocol: "matterhorn-sdk",
+    version: 1,
+    kind: "call-signal",
+    roomName: input.roomName,
+    sourceClientId: input.sourceClientId,
+    targetClientId: input.targetClientId,
+    signal: input.signal
+  });
+}
+
+function eventTemplate(input, createdAt) {
+  return {
+    kind: MATTERHORN_CALL_SIGNAL_NOSTR_KIND,
+    created_at: createdAt,
+    tags: [
+      ["protocol", "matterhorn-sdk"],
+      ["room", input.roomName],
+      ["source", input.sourceClientId],
+      ["target", input.targetClientId],
+      ["session", input.signal.sessionId]
+    ],
+    content: signedContent(input)
+  };
+}
+
+function eventForSignature(input) {
+  return {
+    ...eventTemplate(input, input.auth.createdAt),
+    pubkey: input.auth.pubkey,
+    id: input.auth.eventId,
+    sig: input.auth.sig
+  };
+}
+
+function verifyCallSignal(input) {
+  const auth = input.auth;
+  if (!auth || auth.alg !== "nostr-secp256k1") return false;
+  if (!isHex(input.expectedPubkey, 64) || auth.pubkey.toLowerCase() !== input.expectedPubkey.toLowerCase()) return false;
+  if (!isHex(auth.pubkey, 64) || !isHex(auth.eventId, 64) || !isHex(auth.sig, 128)) return false;
+  if (!Number.isInteger(auth.createdAt) || auth.createdAt <= 0) return false;
+  const now = Math.floor(Date.now() / 1000);
+  if (auth.createdAt < now - CALL_SIGNAL_MAX_AGE_SECONDS || auth.createdAt > now + CALL_SIGNAL_FUTURE_SKEW_SECONDS) return false;
+  return verifyEvent(eventForSignature(input));
+}
+
+function signCallSignal(input) {
+  const event = finalizeEvent(
+    eventTemplate(input, Math.floor(Date.now() / 1000)),
+    hexToBytes(input.privateKey)
+  );
+  return {
+    alg: "nostr-secp256k1",
+    pubkey: event.pubkey,
+    eventId: event.id,
+    sig: event.sig,
+    createdAt: event.created_at
+  };
+}
+
+module.exports = {
+  signCallSignal,
+  verifyCallSignal
+};

package/src/index.cjs

@@ -0,0 +1,45 @@
+// Public barrel for @mh-gg/relay.
+// Re-exports the relay runtime plus the shared primitives (config, identity,
+// peer signaling, rc-file defaults, wire validation) that the host package and
+// the matterhorn CLI consume.
+
+const relay = require("./relay.cjs");
+const relayConfig = require("./relayConfig.cjs");
+const logging = require("./logging.cjs");
+const metrics = require("./metrics.cjs");
+const peerJsConfig = require("./peerJsConfig.cjs");
+const localPeerServer = require("./localPeerServer.cjs");
+const matterhornrc = require("./matterhornrc.cjs");
+const relayIdentity = require("./relayIdentity.cjs");
+const relayPolicy = require("./roomRelayPolicy.cjs");
+const relaySetPropagation = require("./relaySetPropagation.cjs");
+const relayTrustHandshake = require("./relayTrustHandshake.cjs");
+const relayWrapKeys = require("./relayWrapKeys.cjs");
+const mlsDeliveryService = require("./mlsDeliveryService.cjs");
+const sqliteRelayStorage = require("./sqliteRelayStorage.cjs");
+const wireValidation = require("./wireValidation/index.cjs");
+
+module.exports = {
+  // relay runtime (host/relay.cjs)
+  ...relay,
+  // relay config primitives
+  ...relayConfig,
+  ...logging,
+  ...metrics,
+  // peerjs signaling config
+  ...peerJsConfig,
+  // local peerjs server
+  ...localPeerServer,
+  // rc-file defaults / data dir
+  ...matterhornrc,
+  // relay identity / trust
+  ...relayIdentity,
+  ...relayPolicy,
+  ...relaySetPropagation,
+  ...relayTrustHandshake,
+  ...relayWrapKeys,
+  ...mlsDeliveryService,
+  ...sqliteRelayStorage,
+  // wire validation barrel
+  ...wireValidation
+};

package/src/localPeerServer.cjs

@@ -0,0 +1,116 @@
+const { setTimeout: delay } = require("node:timers/promises");
+
+const DEFAULT_LOCAL_PEERJS_HOST = "127.0.0.1";
+const DEFAULT_LOCAL_PEERJS_PORT = 9000;
+const DEFAULT_LOCAL_PEERJS_PATH = "/peerjs";
+
+function localPeerServerConfig(options = {}) {
+  return {
+    host: options.host || process.env.MATTERHORN_PEERJS_LOCAL_HOST || DEFAULT_LOCAL_PEERJS_HOST,
+    port: Number(options.port || process.env.MATTERHORN_PEERJS_LOCAL_PORT || DEFAULT_LOCAL_PEERJS_PORT),
+    path: options.path || process.env.MATTERHORN_PEERJS_LOCAL_PATH || DEFAULT_LOCAL_PEERJS_PATH,
+    secure: false
+  };
+}
+
+function applyPeerServerEnv(peerServer) {
+  process.env.MATTERHORN_PEERJS_HOST = peerServer.host;
+  process.env.MATTERHORN_PEERJS_PORT = String(peerServer.port);
+  process.env.MATTERHORN_PEERJS_PATH = peerServer.path;
+  process.env.MATTERHORN_PEERJS_SECURE = String(peerServer.secure);
+}
+
+function peerServerUrl(config) {
+  return `http://${config.host}:${config.port}${config.path}`;
+}
+
+function peerServerIdUrl(config) {
+  const base = peerServerUrl(config).replace(/\/$/, "");
+  return `${base}/peerjs/id`;
+}
+
+async function waitForPeerServer(config, options = {}) {
+  const timeoutMs = Number(options.timeoutMs || 5000);
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(peerServerIdUrl(config));
+      if (response.ok) return true;
+      lastError = new Error(`PeerJS health returned ${response.status}`);
+    } catch (error) {
+      lastError = error;
+    }
+    await delay(100);
+  }
+  throw lastError || new Error("Timed out waiting for local PeerJS server");
+}
+
+function closePeerServer(server) {
+  const target = server?.close ? server : server?._server;
+  if (!target?.close) return Promise.resolve();
+  return new Promise((resolve) => target.close(() => resolve()));
+}
+
+async function startLocalPeerServer(options = {}) {
+  const config = localPeerServerConfig(options);
+  if (options.reuseExisting !== false) {
+    try {
+      await waitForPeerServer(config, { timeoutMs: options.reuseTimeoutMs || 300 });
+      applyPeerServerEnv(config);
+      return {
+        ...config,
+        url: peerServerUrl(config),
+        reused: true,
+        server: undefined,
+        close: () => Promise.resolve()
+      };
+    } catch (matterhornIgnoredError) {
+      globalThis.__matterhornIgnoredError?.(matterhornIgnoredError, "host/localPeerServer.cjs");
+    }
+  }
+
+  let PeerServer;
+  try {
+    ({ PeerServer } = require("peer"));
+  } catch (error) {
+    throw new Error(`The local PeerJS server requires the peer package. Run pnpm install once at the Matterhorn workspace root. ${error.message}`);
+  }
+  if (typeof PeerServer !== "function") throw new Error("The peer package did not export PeerServer.");
+  const server = PeerServer({
+    host: config.host,
+    port: config.port,
+    path: config.path,
+    proxied: false
+  });
+  let startupError;
+  server?.once?.("error", (error) => {
+    startupError = error;
+  });
+  applyPeerServerEnv(config);
+  try {
+    await waitForPeerServer(config, options);
+  } catch (error) {
+    await closePeerServer(server).catch(() => undefined);
+    throw startupError || error;
+  }
+  return {
+    ...config,
+    url: peerServerUrl(config),
+    reused: false,
+    server,
+    close: () => closePeerServer(server)
+  };
+}
+
+module.exports = {
+  DEFAULT_LOCAL_PEERJS_HOST,
+  DEFAULT_LOCAL_PEERJS_PATH,
+  DEFAULT_LOCAL_PEERJS_PORT,
+  applyPeerServerEnv,
+  localPeerServerConfig,
+  peerServerIdUrl,
+  peerServerUrl,
+  startLocalPeerServer,
+  waitForPeerServer
+};

package/src/logging.cjs

@@ -0,0 +1,164 @@
+const crypto = require("node:crypto");
+
+const REDACTED = "<redacted>";
+const LEVELS = Object.freeze({ debug: 10, info: 20, warn: 30, error: 40 });
+const SENSITIVE_KEYS = new Set([
+  "adminToken",
+  "auth",
+  "bearer",
+  "credential",
+  "grantPrivateKeyPem",
+  "inviteSecret",
+  "ipcSecret",
+  "memberSecret",
+  "operation",
+  "passphrase",
+  "payload",
+  "privateKey",
+  "privateKeyPem",
+  "roomSecret",
+  "secret",
+  "signature",
+  "token",
+  "turnCredential",
+  "vapidPrivateKey"
+].map((key) => key.toLowerCase()));
+
+const QUERY_SECRET_KEYS = new Set([
+  "access_token",
+  "admin",
+  "adminToken",
+  "code",
+  "credential",
+  "invite",
+  "key",
+  "passphrase",
+  "password",
+  "secret",
+  "sig",
+  "signature",
+  "token"
+].map((key) => key.toLowerCase()));
+
+function fingerprint(value, length = 12) {
+  return crypto.createHash("sha256").update(String(value)).digest("hex").slice(0, length);
+}
+
+function safeIdentifier(value, options = {}) {
+  const text = String(value || "");
+  if (!text) return "";
+  const prefix = Number.isInteger(options.prefix) ? options.prefix : 8;
+  return `${text.slice(0, prefix)}#${fingerprint(text, 8)}`;
+}
+
+function redactUrl(text) {
+  try {
+    const url = new URL(text);
+    if (url.username) url.username = REDACTED;
+    if (url.password) url.password = REDACTED;
+    for (const key of Array.from(url.searchParams.keys())) {
+      if (QUERY_SECRET_KEYS.has(key.toLowerCase())) url.searchParams.set(key, REDACTED);
+    }
+    if (url.hash && /(?:invite|secret|token|key|admin|passphrase|credential)=/i.test(url.hash)) {
+      url.hash = "#<redacted>";
+    }
+    return url.toString();
+  } catch {
+    return text;
+  }
+}
+
+function redactString(value) {
+  let text = String(value);
+  text = redactUrl(text);
+  text = text.replace(/matterhorn-relay:[A-Za-z0-9._~+/=-]+/g, "matterhorn-relay:<redacted>");
+  text = text.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer <redacted>");
+  text = text.replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?-----END [^-]*PRIVATE KEY-----/g, REDACTED);
+  text = text.replace(/\b(roomSecret|inviteSecret|ipcSecret|passphrase|token|secret|credential)=([^&\s]+)/gi, "$1=<redacted>");
+  return text;
+}
+
+function shouldRedactKey(key) {
+  const normalized = String(key || "").toLowerCase();
+  if (SENSITIVE_KEYS.has(normalized)) return true;
+  return /(secret|privatekey|token|passphrase|credential|signature|plaintext|payload|operation)/i.test(normalized);
+}
+
+function redactLogValue(value, seen = new WeakSet()) {
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: redactString(value.message || ""),
+      code: value.code
+    };
+  }
+  if (typeof value === "string") return redactString(value);
+  if (typeof value !== "object" || value === null) return value;
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  if (Array.isArray(value)) return value.map((item) => redactLogValue(item, seen));
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    out[key] = shouldRedactKey(key) ? REDACTED : redactLogValue(item, seen);
+  }
+  return out;
+}
+
+function normalizeLevel(level, fallback = "info") {
+  return Object.prototype.hasOwnProperty.call(LEVELS, level) ? level : fallback;
+}
+
+function createStructuredLogger(options = {}) {
+  const level = normalizeLevel(options.level || process.env.MATTERHORN_LOG_LEVEL, "info");
+  const json = options.json === true || process.env.MATTERHORN_LOG_FORMAT === "json" || process.env.NODE_ENV === "production";
+  const sink = options.sink || console;
+
+  function enabled(entryLevel) {
+    return LEVELS[entryLevel] >= LEVELS[level];
+  }
+
+  function emit(entryLevel, event, fields = {}) {
+    if (!enabled(entryLevel)) return;
+    const entry = {
+      ts: new Date().toISOString(),
+      level: entryLevel,
+      event,
+      ...redactLogValue(fields)
+    };
+    const line = json ? JSON.stringify(entry) : formatTextEntry(entry);
+    const writer = entryLevel === "error" ? sink.error : entryLevel === "warn" ? sink.warn : sink.log;
+    (writer || sink.log || console.log).call(sink, line);
+  }
+
+  return {
+    debug: (event, fields) => emit("debug", event, fields),
+    info: (event, fields) => emit("info", event, fields),
+    warn: (event, fields) => emit("warn", event, fields),
+    error: (event, fields) => emit("error", event, fields)
+  };
+}
+
+function formatTextEntry(entry) {
+  const { ts, level, event, ...fields } = entry;
+  const suffix = Object.keys(fields).length > 0 ? ` ${JSON.stringify(fields)}` : "";
+  return `${ts} ${level} ${event}${suffix}`;
+}
+
+function wrapPrivacySafeLogger(logger = console) {
+  return {
+    log: (...args) => logger.log?.(...args.map((item) => redactLogValue(item))),
+    info: (...args) => (logger.info || logger.log)?.(...args.map((item) => redactLogValue(item))),
+    warn: (...args) => logger.warn?.(...args.map((item) => redactLogValue(item))),
+    error: (...args) => logger.error?.(...args.map((item) => redactLogValue(item)))
+  };
+}
+
+module.exports = {
+  LEVELS,
+  REDACTED,
+  createStructuredLogger,
+  fingerprint,
+  redactLogValue,
+  safeIdentifier,
+  wrapPrivacySafeLogger
+};

package/src/matterhornrc.cjs

@@ -0,0 +1,79 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+function userDataDir() {
+  return process.env.MATTERHORN_HOME || path.join(os.homedir(), ".matterhorn");
+}
+
+function usermatterhornrcFile() {
+  return path.join(userDataDir(), ".matterhornrc");
+}
+
+function parseKeyValueText(text) {
+  const values = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const match = /^([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*(.*)$/.exec(line);
+    if (!match) continue;
+    values[match[1]] = match[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return values;
+}
+
+function normalizematterhornrc(values) {
+  const host = values.host || values.HOST_URL || values.appUrl || values.app_url;
+  const normalized = host ? { host: String(host).trim() } : {};
+  const players = Array.isArray(values.players) ? values.players : values.playerPacks;
+  if (Array.isArray(players)) {
+    normalized.players = players
+      .filter((player) => player && typeof player === "object" && typeof player.url === "string")
+      .map((player) => ({
+        url: player.url,
+        ...(player.integrity === undefined ? {} : { integrity: String(player.integrity) }),
+        ...(player.id === undefined ? {} : { id: String(player.id) }),
+        ...(player.name === undefined ? {} : { name: String(player.name) }),
+        ...(player.version === undefined ? {} : { version: String(player.version) }),
+        ...(player.addedAt === undefined ? {} : { addedAt: String(player.addedAt) })
+      }));
+  }
+  return normalized;
+}
+
+function parsematterhornrc(text) {
+  try {
+    return normalizematterhornrc(JSON.parse(text));
+  } catch {
+    return normalizematterhornrc(parseKeyValueText(text));
+  }
+}
+
+function readmatterhornrc(file = usermatterhornrcFile()) {
+  try {
+    return parsematterhornrc(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    if (error && (error.code === "ENOENT" || error.code === "ENOTDIR")) return {};
+    throw error;
+  }
+}
+
+function writematterhornrc(values, file = usermatterhornrcFile()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(values, null, 2)}\n`);
+}
+
+function applymatterhornrcDefaults(target = process.env, file = usermatterhornrcFile()) {
+  const values = readmatterhornrc(file);
+  if (values.host && target.APP_URL === undefined && target.HOST_URL === undefined) {
+    target.HOST_URL = values.host;
+  }
+}
+
+module.exports = {
+  applymatterhornrcDefaults,
+  readmatterhornrc,
+  userDataDir,
+  usermatterhornrcFile,
+  writematterhornrc
+};

package/src/memberRootRegistry.cjs

@@ -0,0 +1,132 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+function registryPathFromOptions(options = {}) {
+  if (options.registryPath) return options.registryPath;
+  if (options.memberRootRegistryPath) return options.memberRootRegistryPath;
+  if (options.storagePath) return `${options.storagePath}.member-roots.json`;
+  if (options.dataDir) return path.join(options.dataDir, "member-roots.json");
+  return undefined;
+}
+
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function safeKeyPart(value) {
+  return String(value || "").replace(/[\u0000-\u001f\u007f:]/g, "_");
+}
+
+function rootKeyFor(roomName, memberId) {
+  return `${safeKeyPart(roomName)}:${safeKeyPart(memberId)}`;
+}
+
+function claimRoom(claim) {
+  return claim?.roomId || claim?.roomName;
+}
+
+function normalizeClaim(claim) {
+  const roomName = claimRoom(claim);
+  if (!roomName || !claim?.memberId || !claim?.rootPublicKey) return undefined;
+  return {
+    roomName,
+    memberId: claim.memberId,
+    rootPublicKey: claim.rootPublicKey,
+    firstSeenAt: Number.isFinite(Number(claim.createdAt)) ? Number(claim.createdAt) : Date.now(),
+    updatedAt: Date.now(),
+    lastDeviceId: claim.deviceId,
+    lastKeyId: claim.keyId
+  };
+}
+
+function createMemoryRegistry(initial = {}) {
+  const roots = new Map(Object.entries(initial));
+  return {
+    path: undefined,
+    entries() {
+      return Object.fromEntries(roots.entries());
+    },
+    get(roomName, memberId) {
+      return clone(roots.get(rootKeyFor(roomName, memberId)));
+    },
+    remember(claim) {
+      const normalized = normalizeClaim(claim);
+      if (!normalized) return { ok: false, error: "member root claim is incomplete" };
+      const key = rootKeyFor(normalized.roomName, normalized.memberId);
+      const existing = roots.get(key);
+      if (existing && existing.rootPublicKey !== normalized.rootPublicKey) {
+        return {
+          ok: false,
+          error: "member root public key changed",
+          existing: clone(existing),
+          incoming: clone(normalized)
+        };
+      }
+      const next = existing ? { ...existing, ...normalized, firstSeenAt: existing.firstSeenAt || normalized.firstSeenAt } : normalized;
+      roots.set(key, next);
+      return { ok: true, entry: clone(next) };
+    }
+  };
+}
+
+function readRegistryFile(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (parsed && parsed.version === 1 && parsed.roots && typeof parsed.roots === "object" && !Array.isArray(parsed.roots)) {
+      return parsed.roots;
+    }
+  } catch (error) {
+    if (error && error.code === "ENOENT") return {};
+  }
+  return {};
+}
+
+function writeRegistryFile(file, roots) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ version: 1, roots }, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+function createMemberRootRegistry(options = {}) {
+  const file = registryPathFromOptions(options);
+  if (!file) return createMemoryRegistry(options.initialRoots);
+  let roots = readRegistryFile(file);
+  function persist() {
+    writeRegistryFile(file, roots);
+  }
+  return {
+    path: file,
+    entries() {
+      roots = readRegistryFile(file);
+      return clone(roots);
+    },
+    get(roomName, memberId) {
+      roots = readRegistryFile(file);
+      return clone(roots[rootKeyFor(roomName, memberId)]);
+    },
+    remember(claim) {
+      const normalized = normalizeClaim(claim);
+      if (!normalized) return { ok: false, error: "member root claim is incomplete" };
+      roots = readRegistryFile(file);
+      const key = rootKeyFor(normalized.roomName, normalized.memberId);
+      const existing = roots[key];
+      if (existing && existing.rootPublicKey !== normalized.rootPublicKey) {
+        return {
+          ok: false,
+          error: "member root public key changed",
+          existing: clone(existing),
+          incoming: clone(normalized)
+        };
+      }
+      roots[key] = existing ? { ...existing, ...normalized, firstSeenAt: existing.firstSeenAt || normalized.firstSeenAt } : normalized;
+      persist();
+      return { ok: true, entry: clone(roots[key]) };
+    }
+  };
+}
+
+module.exports = {
+  createMemberRootRegistry,
+  rootKeyFor
+};