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

package/src/operations/snowflake.cjs

@@ -0,0 +1,166 @@
+const {
+  DEFAULT_SNOWFLAKE_EPOCH,
+  SNOWFLAKE_MAX_ID,
+  SNOWFLAKE_MAX_NODE_ID,
+  SNOWFLAKE_MAX_SEQUENCE,
+  SNOWFLAKE_NODE_SHIFT,
+  SNOWFLAKE_RE,
+  SNOWFLAKE_TIMESTAMP_SHIFT,
+  finiteInteger,
+  normalizeSnowflakeEpoch,
+  normalizeSnowflakeTimestamp,
+  stableSnowflakeNodeId,
+  stableSnowflakeSequence
+} = require("./snowflakeParts.cjs");
+
+function snowflakeIdFromParts({ timestampMs = Date.now(), nodeId = 0, sequence = 0, epoch = DEFAULT_SNOWFLAKE_EPOCH } = {}) {
+  const normalizedEpoch = normalizeSnowflakeEpoch(epoch);
+  const { elapsed } = normalizeSnowflakeTimestamp(timestampMs, normalizedEpoch);
+  const normalizedNodeId = stableSnowflakeNodeId(nodeId);
+  const normalizedSequence = stableSnowflakeSequence(sequence);
+  return ((elapsed << SNOWFLAKE_TIMESTAMP_SHIFT) | (BigInt(normalizedNodeId) << SNOWFLAKE_NODE_SHIFT) | BigInt(normalizedSequence)).toString();
+}
+
+function snowflakeIdFromTimestamp(timestampMs = Date.now(), options = {}) {
+  return snowflakeIdFromParts({ timestampMs, ...options });
+}
+
+function isSnowflakeId(value) {
+  if (typeof value !== "string" && typeof value !== "number" && typeof value !== "bigint") return false;
+  const text = String(value);
+  if (!SNOWFLAKE_RE.test(text)) return false;
+  try {
+    const parsed = BigInt(text);
+    return parsed >= 0n && parsed <= SNOWFLAKE_MAX_ID;
+  } catch {
+    return false;
+  }
+}
+
+function parseSnowflakeId(value, options = {}) {
+  if (!isSnowflakeId(value)) return undefined;
+  const epoch = normalizeSnowflakeEpoch(options.epoch);
+  const id = BigInt(String(value));
+  const elapsed = id >> SNOWFLAKE_TIMESTAMP_SHIFT;
+  const timestampMs = Number(elapsed) + epoch;
+  const nodeId = Number((id >> SNOWFLAKE_NODE_SHIFT) & BigInt(SNOWFLAKE_MAX_NODE_ID));
+  const sequence = Number(id & BigInt(SNOWFLAKE_MAX_SEQUENCE));
+  return { id: id.toString(), timestampMs, nodeId, sequence, epoch };
+}
+
+function snowflakeTimestamp(value, options = {}) {
+  return parseSnowflakeId(value, options)?.timestampMs;
+}
+
+function compareSnowflakeIds(left, right) {
+  const a = BigInt(String(left));
+  const b = BigInt(String(right));
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function compareMaybeSnowflakeIds(left, right) {
+  if (isSnowflakeId(left) && isSnowflakeId(right)) return compareSnowflakeIds(left, right);
+  const a = String(left || "");
+  const b = String(right || "");
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function extractSnowflakeId(value) {
+  if (isSnowflakeId(value)) return String(value);
+  if (typeof value !== "string") return undefined;
+  const match = /(?:^|_)([1-9][0-9]{12,18}|0)$/.exec(value);
+  return match && isSnowflakeId(match[1]) ? match[1] : undefined;
+}
+
+function compareEntityIdsBySnowflake(left, right) {
+  const a = extractSnowflakeId(left);
+  const b = extractSnowflakeId(right);
+  if (a && b) return compareSnowflakeIds(a, b);
+  if (a) return -1;
+  if (b) return 1;
+  return compareMaybeSnowflakeIds(left, right);
+}
+
+function snowflakeBoundsForTimestamp(timestampMs, options = {}) {
+  const epoch = normalizeSnowflakeEpoch(options.epoch);
+  return {
+    min: snowflakeIdFromParts({ timestampMs, nodeId: 0, sequence: 0, epoch }),
+    max: snowflakeIdFromParts({ timestampMs, nodeId: SNOWFLAKE_MAX_NODE_ID, sequence: SNOWFLAKE_MAX_SEQUENCE, epoch })
+  };
+}
+
+function createSnowflakeGenerator(options = {}) {
+  const epoch = normalizeSnowflakeEpoch(options.epoch);
+  const nodeId = stableSnowflakeNodeId(options.nodeId ?? "matterhorn-sdk");
+  const now = typeof options.now === "function" ? options.now : () => Date.now();
+  let lastTimestamp = -1;
+  let sequence = 0;
+  return {
+    epoch,
+    nodeId,
+    next(timestampMs) {
+      const wall = Number.isFinite(Number(timestampMs)) ? finiteInteger(timestampMs, "timestampMs") : finiteInteger(now(), "now");
+      let timestamp = Math.max(wall, lastTimestamp, epoch);
+      if (timestamp === lastTimestamp) {
+        sequence += 1;
+        if (sequence > SNOWFLAKE_MAX_SEQUENCE) {
+          timestamp += 1;
+          sequence = 0;
+        }
+      } else {
+        sequence = 0;
+      }
+      lastTimestamp = timestamp;
+      return snowflakeIdFromParts({ timestampMs: timestamp, nodeId, sequence, epoch });
+    },
+    fromTimestamp(timestampMs, sequenceHint = 0) {
+      return snowflakeIdFromParts({ timestampMs, nodeId, sequence: sequenceHint, epoch });
+    },
+    inspect(id) {
+      return parseSnowflakeId(id, { epoch });
+    }
+  };
+}
+
+function snowflakeIdForOperation(operation = {}, options = {}) {
+  if (operation.ledgerId && isSnowflakeId(operation.ledgerId)) return String(operation.ledgerId);
+  if (operation.snowflakeId && isSnowflakeId(operation.snowflakeId)) return String(operation.snowflakeId);
+  const epoch = normalizeSnowflakeEpoch(options.epoch);
+  const rawTimestampMs = Number.isFinite(Number(operation.createdAt)) ? Number(operation.createdAt) : Date.now();
+  const timestampMs = Math.max(rawTimestampMs, epoch);
+  const nodeSource = options.nodeId ?? operation.actor?.deviceId ?? operation.actor?.memberId ?? operation.roomId ?? operation.id ?? "operation";
+  const sequenceSource = options.sequence ?? operation.id ?? operation.clientOperationId ?? operation.hlc ?? `${operation.type || "operation"}:${timestampMs}`;
+  return snowflakeIdFromParts({
+    timestampMs,
+    nodeId: stableSnowflakeNodeId(nodeSource),
+    sequence: stableSnowflakeSequence(sequenceSource),
+    epoch
+  });
+}
+
+function prefixedSnowflakeId(prefix = "id", snowflakeId) {
+  const cleanPrefix = String(prefix || "id").replace(/[^A-Za-z0-9_-]/g, "_") || "id";
+  const id = snowflakeId && isSnowflakeId(snowflakeId) ? String(snowflakeId) : snowflakeIdFromTimestamp(Date.now());
+  return `${cleanPrefix}_${id}`;
+}
+
+module.exports = {
+  DEFAULT_SNOWFLAKE_EPOCH,
+  SNOWFLAKE_MAX_NODE_ID,
+  SNOWFLAKE_MAX_SEQUENCE,
+  compareEntityIdsBySnowflake,
+  compareMaybeSnowflakeIds,
+  compareSnowflakeIds,
+  createSnowflakeGenerator,
+  extractSnowflakeId,
+  isSnowflakeId,
+  parseSnowflakeId,
+  prefixedSnowflakeId,
+  snowflakeBoundsForTimestamp,
+  snowflakeIdForOperation,
+  snowflakeIdFromParts,
+  snowflakeIdFromTimestamp,
+  snowflakeTimestamp,
+  stableSnowflakeNodeId,
+  stableSnowflakeSequence
+};

package/src/operations/snowflakeParts.cjs

@@ -0,0 +1,71 @@
+const DEFAULT_SNOWFLAKE_EPOCH = Date.UTC(2024, 0, 1);
+const SNOWFLAKE_TIMESTAMP_BITS = 41n;
+const SNOWFLAKE_NODE_BITS = 10n;
+const SNOWFLAKE_SEQUENCE_BITS = 12n;
+const SNOWFLAKE_NODE_SHIFT = SNOWFLAKE_SEQUENCE_BITS;
+const SNOWFLAKE_TIMESTAMP_SHIFT = SNOWFLAKE_NODE_BITS + SNOWFLAKE_SEQUENCE_BITS;
+const SNOWFLAKE_MAX_TIMESTAMP = (1n << SNOWFLAKE_TIMESTAMP_BITS) - 1n;
+const SNOWFLAKE_MAX_NODE_ID = Number((1n << SNOWFLAKE_NODE_BITS) - 1n);
+const SNOWFLAKE_MAX_SEQUENCE = Number((1n << SNOWFLAKE_SEQUENCE_BITS) - 1n);
+const SNOWFLAKE_MAX_ID = (1n << 63n) - 1n;
+const SNOWFLAKE_RE = /^(0|[1-9][0-9]{0,18})$/;
+
+function finiteInteger(value, name) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || !Number.isInteger(number)) throw new Error(`${name} must be an integer`);
+  return number;
+}
+
+function clampInteger(value, min, max, name) {
+  const number = finiteInteger(value, name);
+  if (number < min || number > max) throw new Error(`${name} must be between ${min} and ${max}`);
+  return number;
+}
+
+function fnv1a32(value) {
+  const text = String(value || "");
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+function stableSnowflakeNodeId(value) {
+  if (Number.isFinite(Number(value)) && String(value).trim() !== "") return clampInteger(Number(value), 0, SNOWFLAKE_MAX_NODE_ID, "nodeId");
+  return fnv1a32(value) & SNOWFLAKE_MAX_NODE_ID;
+}
+
+function stableSnowflakeSequence(value) {
+  if (Number.isFinite(Number(value)) && String(value).trim() !== "") return clampInteger(Number(value), 0, SNOWFLAKE_MAX_SEQUENCE, "sequence");
+  return fnv1a32(value) & SNOWFLAKE_MAX_SEQUENCE;
+}
+
+function normalizeSnowflakeEpoch(epoch) {
+  return Number.isFinite(Number(epoch)) ? finiteInteger(epoch, "epoch") : DEFAULT_SNOWFLAKE_EPOCH;
+}
+
+function normalizeSnowflakeTimestamp(timestampMs, epoch = DEFAULT_SNOWFLAKE_EPOCH) {
+  const timestamp = finiteInteger(timestampMs, "timestampMs");
+  const elapsed = BigInt(timestamp - normalizeSnowflakeEpoch(epoch));
+  if (elapsed < 0n) throw new Error("timestampMs is before the Snowflake epoch");
+  if (elapsed > SNOWFLAKE_MAX_TIMESTAMP) throw new Error("timestampMs exceeds the Snowflake timestamp range");
+  return { timestamp, elapsed };
+}
+
+module.exports = {
+  DEFAULT_SNOWFLAKE_EPOCH,
+  SNOWFLAKE_MAX_ID,
+  SNOWFLAKE_MAX_NODE_ID,
+  SNOWFLAKE_MAX_SEQUENCE,
+  SNOWFLAKE_NODE_SHIFT,
+  SNOWFLAKE_RE,
+  SNOWFLAKE_SEQUENCE_BITS,
+  SNOWFLAKE_TIMESTAMP_SHIFT,
+  finiteInteger,
+  normalizeSnowflakeEpoch,
+  normalizeSnowflakeTimestamp,
+  stableSnowflakeNodeId,
+  stableSnowflakeSequence
+};

package/src/parsers/hostOperationBatch.cjs

@@ -0,0 +1,49 @@
+const { HOST_OPERATION_BATCH_KIND, HOST_SNAPSHOT_KIND } = require("../constants.cjs");
+const { assertArray, assertInteger, assertRecord, assertString } = require("../assertions.cjs");
+const { invalid } = require("../errors.cjs");
+const { validateRoomOperation } = require("../validators/operations.cjs");
+
+function validateHostOperationBatch(message) {
+  const value = assertRecord(message, "host-operation-batch");
+  if (value.kind !== undefined && value.kind !== HOST_OPERATION_BATCH_KIND) throw invalid("host-operation-batch.kind", "is invalid");
+  assertString(value.roomId, "host-operation-batch.roomId");
+  assertString(value.appPackId, "host-operation-batch.appPackId");
+  assertString(value.appPackHash, "host-operation-batch.appPackHash");
+  if (value.baseVersion !== undefined) assertInteger(value.baseVersion, "host-operation-batch.baseVersion", 0);
+  if (value.headVersion !== undefined) assertInteger(value.headVersion, "host-operation-batch.headVersion", 0);
+  assertArray(value.operations, "host-operation-batch.operations").forEach((op, index) => {
+    validateRoomOperation(op, {
+      roomId: value.roomId,
+      appPackId: value.appPackId,
+      appPackHash: value.appPackHash
+    });
+    if (op.seq !== undefined) assertInteger(op.seq, `host-operation-batch.operations[${index}].seq`, 1);
+  });
+  return value;
+}
+
+function parseHostOperationBatch(message) {
+  return validateHostOperationBatch(message);
+}
+
+function validateHostSnapshot(message) {
+  const value = assertRecord(message, "host-snapshot");
+  if (value.kind !== undefined && value.kind !== HOST_SNAPSHOT_KIND) throw invalid("host-snapshot.kind", "is invalid");
+  assertString(value.roomId, "host-snapshot.roomId");
+  assertString(value.appPackId, "host-snapshot.appPackId");
+  assertString(value.appPackHash, "host-snapshot.appPackHash");
+  assertInteger(value.version, "host-snapshot.version", 0);
+  assertRecord(value.state, "host-snapshot.state");
+  return value;
+}
+
+function parseHostSnapshot(message) {
+  return validateHostSnapshot(message);
+}
+
+module.exports = {
+  parseHostOperationBatch,
+  parseHostSnapshot,
+  validateHostOperationBatch,
+  validateHostSnapshot
+};

package/src/validators/bounds.cjs

@@ -0,0 +1,77 @@
+const { MAX_OPERATION_BYTES, MAX_OPERATION_DEPTH, MAX_PUSH_PAYLOAD_BYTES } = require("../constants.cjs");
+const { invalid } = require("../errors.cjs");
+
+function optionLimit(value, fallback) {
+  if (value === false || value === Infinity) return Infinity;
+  if (Number.isFinite(value) && value >= 0) return value;
+  return fallback;
+}
+
+function isObjectLike(value) {
+  return Boolean(value) && typeof value === "object";
+}
+
+function assertJsonDepth(value, path = "value", maxDepth = MAX_OPERATION_DEPTH) {
+  const limit = optionLimit(maxDepth, MAX_OPERATION_DEPTH);
+  if (!Number.isFinite(limit)) return;
+  const stack = [{ value, depth: 0 }];
+  const seen = new WeakSet();
+  while (stack.length) {
+    const current = stack.pop();
+    const item = current.value;
+    if (item === null || item === undefined) continue;
+    const type = typeof item;
+    if (type === "string" || type === "number" || type === "boolean") continue;
+    if (type === "bigint" || type === "function" || type === "symbol") throw invalid(path, "must be JSON serializable");
+    if (!isObjectLike(item)) continue;
+    if (current.depth > limit) throw invalid(path, "max depth exceeded");
+    if (seen.has(item)) throw invalid(path, "must be JSON serializable");
+    seen.add(item);
+    const nextDepth = current.depth + 1;
+    if (Array.isArray(item)) {
+      for (let index = item.length - 1; index >= 0; index -= 1) stack.push({ value: item[index], depth: nextDepth });
+    } else {
+      for (const key of Object.keys(item)) stack.push({ value: item[key], depth: nextDepth });
+    }
+  }
+}
+
+function jsonByteLength(value, path = "value") {
+  let encoded;
+  try {
+    encoded = JSON.stringify(value);
+  } catch {
+    throw invalid(path, "must be JSON serializable");
+  }
+  if (encoded === undefined) throw invalid(path, "must be JSON serializable");
+  return Buffer.byteLength(encoded, "utf8");
+}
+
+function assertJsonByteLength(value, path = "value", maxBytes = MAX_OPERATION_BYTES) {
+  const limit = optionLimit(maxBytes, MAX_OPERATION_BYTES);
+  if (!Number.isFinite(limit)) return jsonByteLength(value, path);
+  const bytes = jsonByteLength(value, path);
+  if (bytes > limit) throw invalid(path, "is too large");
+  return bytes;
+}
+
+function assertJsonBounds(value, path = "value", options = {}) {
+  assertJsonDepth(value, path, options.maxDepth);
+  return assertJsonByteLength(value, path, options.maxBytes);
+}
+
+function assertOperationBounds(operation, options = {}) {
+  return assertJsonBounds(operation, "operation", {
+    maxBytes: options.maxOperationBytes,
+    maxDepth: options.maxOperationDepth
+  });
+}
+
+module.exports = {
+  assertJsonBounds,
+  assertJsonByteLength,
+  assertJsonDepth,
+  assertOperationBounds,
+  jsonByteLength,
+  MAX_PUSH_PAYLOAD_BYTES
+};

package/src/validators/client.cjs

@@ -0,0 +1,129 @@
+const { assertInteger, assertNumber, assertOptionalString, assertProtocol, assertRecord, assertString, isRecord } = require("../assertions.cjs");
+const { CLIENT_PUSH_GRANT, CLIENT_PUSH_REGISTER } = require("../constants.cjs");
+const { invalid } = require("../errors.cjs");
+const { validateProfile, validateRelayAddresses } = require("./shared.cjs");
+
+function validateClientHello(message) {
+  const value = assertRecord(message, "client/hello");
+  if (value.type !== "client/hello") throw invalid("client/hello.type", "is invalid");
+  assertProtocol(value, "client/hello");
+  assertString(value.roomName, "client/hello.roomName");
+  assertString(value.clientId, "client/hello.clientId");
+  if (value.profile !== undefined) validateProfile(value.profile, "client/hello.profile");
+  if (value.relayHints !== undefined) validateRelayAddresses(value.relayHints, "client/hello.relayHints");
+  return value;
+}
+
+function validateClientMutation(message) {
+  const value = assertRecord(message, "client/mutation");
+  if (value.type !== "client/mutation") throw invalid("client/mutation.type", "is invalid");
+  assertProtocol(value, "client/mutation");
+  assertString(value.roomName, "client/mutation.roomName");
+  const mutation = assertRecord(value.mutation, "client/mutation.mutation");
+  assertString(mutation.id, "client/mutation.mutation.id");
+  assertString(mutation.clientId, "client/mutation.mutation.clientId");
+  assertInteger(mutation.seq, "client/mutation.mutation.seq", 1);
+  assertNumber(mutation.ts, "client/mutation.mutation.ts");
+  assertString(mutation.op, "client/mutation.mutation.op");
+  if (mutation.payload !== undefined && !isRecord(mutation.payload)) throw invalid("client/mutation.mutation.payload", "must be an object");
+  return value;
+}
+
+function validateClientSnapshotRequest(message) {
+  const value = assertRecord(message, "client/snapshot-request");
+  if (value.type !== "client/snapshot-request") throw invalid("client/snapshot-request.type", "is invalid");
+  assertProtocol(value, "client/snapshot-request");
+  assertString(value.roomName, "client/snapshot-request.roomName");
+  assertString(value.clientId, "client/snapshot-request.clientId");
+  assertOptionalString(value.reason, "client/snapshot-request.reason");
+  return value;
+}
+
+function validateCallSignal(signal, path) {
+  const value = assertRecord(signal, path);
+  assertString(value.type, `${path}.type`);
+  assertString(value.sessionId, `${path}.sessionId`);
+  return value;
+}
+
+function validateClientPeerSignal(message) {
+  const value = assertRecord(message, "client/peer-signal");
+  if (value.type !== "client/peer-signal") throw invalid("client/peer-signal.type", "is invalid");
+  assertProtocol(value, "client/peer-signal");
+  assertString(value.roomName, "client/peer-signal.roomName");
+  assertString(value.clientId, "client/peer-signal.clientId");
+  if (value.targetClientId === undefined && value.targetPeerId === undefined) throw invalid("client/peer-signal.target", "is required");
+  assertOptionalString(value.targetClientId, "client/peer-signal.targetClientId");
+  assertOptionalString(value.targetPeerId, "client/peer-signal.targetPeerId");
+  validateCallSignal(value.signal, "client/peer-signal.signal");
+  return value;
+}
+
+function validatePushSubscription(subscription, path) {
+  const value = assertRecord(subscription, path);
+  assertString(value.endpoint, `${path}.endpoint`, 2048);
+  const keys = assertRecord(value.keys, `${path}.keys`);
+  assertString(keys.p256dh, `${path}.keys.p256dh`, 512);
+  assertString(keys.auth, `${path}.keys.auth`, 512);
+  return value;
+}
+
+function validateVapidGrant(grant, path) {
+  const value = assertRecord(grant, path);
+  if (value.kind !== "matterhorn.vapid-grant") throw invalid(`${path}.kind`, "is invalid");
+  if (value.version !== 1) throw invalid(`${path}.version`, "is invalid");
+  assertString(value.relayPublicKey, `${path}.relayPublicKey`, 2048);
+  assertNumber(value.createdAt, `${path}.createdAt`);
+  const wrap = assertRecord(value.wrap, `${path}.wrap`);
+  if (wrap.alg !== "x25519+hkdf-sha256+aes-256-gcm") throw invalid(`${path}.wrap.alg`, "is invalid");
+  assertString(wrap.ephemeralPublicKey, `${path}.wrap.ephemeralPublicKey`, 2048);
+  assertString(wrap.iv, `${path}.wrap.iv`, 128);
+  assertString(value.wrappedVapidPrivateKey, `${path}.wrappedVapidPrivateKey`, 1024);
+  return value;
+}
+
+function validateClientPushRegister(message) {
+  const value = assertRecord(message, CLIENT_PUSH_REGISTER);
+  if (value.type !== CLIENT_PUSH_REGISTER) throw invalid(`${CLIENT_PUSH_REGISTER}.type`, "is invalid");
+  assertProtocol(value, CLIENT_PUSH_REGISTER);
+  assertString(value.roomName, `${CLIENT_PUSH_REGISTER}.roomName`);
+  assertString(value.clientId, `${CLIENT_PUSH_REGISTER}.clientId`);
+  assertString(value.userId, `${CLIENT_PUSH_REGISTER}.userId`);
+  validatePushSubscription(value.subscription, `${CLIENT_PUSH_REGISTER}.subscription`);
+  return value;
+}
+
+function validateClientPushGrant(message) {
+  const value = assertRecord(message, CLIENT_PUSH_GRANT);
+  if (value.type !== CLIENT_PUSH_GRANT) throw invalid(`${CLIENT_PUSH_GRANT}.type`, "is invalid");
+  assertProtocol(value, CLIENT_PUSH_GRANT);
+  assertString(value.clientId, `${CLIENT_PUSH_GRANT}.clientId`);
+  assertString(value.userId, `${CLIENT_PUSH_GRANT}.userId`);
+  assertString(value.relayId, `${CLIENT_PUSH_GRANT}.relayId`);
+  validateVapidGrant(value.grant, `${CLIENT_PUSH_GRANT}.grant`);
+  return value;
+}
+
+function validateClientMessage(message) {
+  const value = assertRecord(message, "client");
+  switch (value.type) {
+    case "client/hello": return validateClientHello(value);
+    case "client/mutation": return validateClientMutation(value);
+    case "client/snapshot-request": return validateClientSnapshotRequest(value);
+    case "client/peer-signal": return validateClientPeerSignal(value);
+    case CLIENT_PUSH_REGISTER: return validateClientPushRegister(value);
+    case CLIENT_PUSH_GRANT: return validateClientPushGrant(value);
+    default: throw invalid("client.type", "is invalid");
+  }
+}
+
+module.exports = {
+  validateCallSignal,
+  validateClientHello,
+  validateClientMessage,
+  validateClientMutation,
+  validateClientPeerSignal,
+  validateClientPushGrant,
+  validateClientPushRegister,
+  validateClientSnapshotRequest
+};

package/src/validators/host.cjs

@@ -0,0 +1,60 @@
+const { assertArray, assertInteger, assertNumber, assertProtocol, assertRecord, assertString, isRecord } = require("../assertions.cjs");
+const { invalid } = require("../errors.cjs");
+const { validateOperationKeyPin, validateRelayAddresses } = require("./shared.cjs");
+const { validateHostOperationEntry } = require("./operations.cjs");
+
+function validateHostInfo(message) {
+  const value = assertRecord(message, "host-info");
+  if (value.kind !== "matterhorn.host-info") throw invalid("host-info.kind", "is invalid");
+  assertString(value.version, "host-info.version");
+  assertString(value.roomId, "host-info.roomId");
+  assertInteger(value.roomVersion, "host-info.roomVersion", 0);
+  const appPack = assertRecord(value.appPack, "host-info.appPack");
+  assertString(appPack.id, "host-info.appPack.id");
+  assertString(appPack.hash, "host-info.appPack.hash");
+  assertString(appPack.protocolHash, "host-info.appPack.protocolHash");
+  assertArray(value.plugins, "host-info.plugins");
+  validateRelayAddresses(value.relays || [], "host-info.relays");
+  return value;
+}
+
+function validateOperationTrustPin(value, path = "operationTrustPin") {
+  const pin = assertRecord(value, path);
+  if (pin.kind !== "matterhorn.operation-key-pin") throw invalid(`${path}.kind`, "is invalid");
+  if (pin.version !== 1) throw invalid(`${path}.version`, "is invalid");
+  assertString(pin.roomName, `${path}.roomName`);
+  assertString(pin.signer, `${path}.signer`);
+  if (pin.alg !== "ed25519") throw invalid(`${path}.alg`, "is invalid");
+  assertString(pin.publicKeyPem, `${path}.publicKeyPem`, 8192);
+  assertString(pin.fingerprint, `${path}.fingerprint`);
+  assertNumber(pin.pinnedAt, `${path}.pinnedAt`);
+  return pin;
+}
+
+function validateHostOperations(message) {
+  const value = assertRecord(message, "host/operations");
+  if (value.type !== "host/operations") throw invalid("host/operations.type", "is invalid");
+  assertProtocol(value, "host/operations");
+  assertInteger(value.baseVersion, "host/operations.baseVersion", 0);
+  assertArray(value.operations, "host/operations.operations").forEach((op, index) => validateHostOperationEntry(op, `host/operations.operations[${index}]`));
+  if (value.publicKeys !== undefined && !isRecord(value.publicKeys)) throw invalid("host/operations.publicKeys", "must be an object");
+  if (value.operationKeyPin !== undefined) validateOperationKeyPin(value.operationKeyPin, "host/operations.operationKeyPin");
+  if (value.operationTrustPin !== undefined) validateOperationTrustPin(value.operationTrustPin, "host/operations.operationTrustPin");
+  return value;
+}
+
+function validateHostMessage(message, path = "host") {
+  const value = assertRecord(message, path);
+  const type = assertString(value.type, `${path}.type`);
+  if (!type.startsWith("host/")) throw invalid(`${path}.type`, "is invalid");
+  if (value.protocol !== undefined) assertProtocol(value, path);
+  if (type === "host/operations") validateHostOperations(value);
+  return value;
+}
+
+module.exports = {
+  validateHostInfo,
+  validateHostMessage,
+  validateHostOperations,
+  validateOperationTrustPin
+};

package/src/validators/operations.cjs

@@ -0,0 +1,110 @@
+const { LEGACY_ROOM_OPERATION_KIND, LEGACY_ROOM_OPERATION_VERSION } = require("../constants.cjs");
+const { operationContentHash, validateHlc } = require("../operations/identity.cjs");
+const { isSnowflakeId } = require("../operations/snowflake.cjs");
+const { assertOperationBounds } = require("./bounds.cjs");
+const { assertInteger, assertNumber, assertRecord, assertString, isRecord } = require("../assertions.cjs");
+const { invalid } = require("../errors.cjs");
+const { MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME } = require("../operations/roomDeviceSigning.cjs");
+
+function validateRoomOperation(operation, options = {}) {
+  const op = assertRecord(operation, "operation");
+  assertOperationBounds(op, options);
+  assertString(op.id, "operation.id");
+  assertString(op.hlc, "operation.hlc");
+  const hlcValidation = validateHlc(op.hlc, { now: options.now, maxFutureSkewMs: options.maxFutureSkewMs });
+  if (!hlcValidation.ok) throw invalid("operation.hlc", hlcValidation.error.replace(/^operation\.hlc /, ""));
+  assertString(op.roomId, "operation.roomId");
+  assertString(op.appPackId, "operation.appPackId");
+  assertString(op.appPackHash, "operation.appPackHash");
+  assertString(op.pluginId, "operation.pluginId");
+  if (op.ledgerId !== undefined) {
+    assertString(op.ledgerId, "operation.ledgerId");
+    if (!isSnowflakeId(op.ledgerId)) throw invalid("operation.ledgerId", "must be a Snowflake ID");
+  }
+  if (op.snowflakeId !== undefined) {
+    assertString(op.snowflakeId, "operation.snowflakeId");
+    if (!isSnowflakeId(op.snowflakeId)) throw invalid("operation.snowflakeId", "must be a Snowflake ID");
+  }
+  assertString(op.type, "operation.type");
+  if (op.schemaAction !== undefined) assertString(op.schemaAction, "operation.schemaAction");
+  const actor = assertRecord(op.actor, "operation.actor");
+  assertString(actor.memberId, "operation.actor.memberId");
+  assertString(actor.deviceId, "operation.actor.deviceId");
+  assertString(actor.role, "operation.actor.role");
+  assertInteger(op.seq, "operation.seq", 1);
+  assertNumber(op.createdAt, "operation.createdAt");
+  if (op.payload !== undefined && !isRecord(op.payload)) throw invalid("operation.payload", "must be an object");
+  const auth = assertRecord(op.auth, "operation.auth");
+  if (auth.scheme === MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME) {
+    assertString(auth.scheme, "operation.auth.scheme");
+    assertString(auth.alg, "operation.auth.alg");
+    assertString(auth.credentialId, "operation.auth.credentialId");
+    assertString(auth.memberId, "operation.auth.memberId");
+    assertString(auth.deviceId, "operation.auth.deviceId");
+    assertString(auth.keyId, "operation.auth.keyId");
+    assertString(auth.rootPublicKey, "operation.auth.rootPublicKey");
+    assertString(auth.publicKey, "operation.auth.publicKey");
+    assertString(auth.publicKeyFingerprint, "operation.auth.publicKeyFingerprint");
+    assertString(auth.signature, "operation.auth.signature");
+    if (auth.signatureEventId !== undefined) assertString(auth.signatureEventId, "operation.auth.signatureEventId");
+    if (auth.eventId !== undefined) assertString(auth.eventId, "operation.auth.eventId");
+    if (auth.signatureEventId === undefined && auth.eventId === undefined) throw invalid("operation.auth.signatureEventId", "is required");
+    assertNumber(auth.issuedAt, "operation.auth.issuedAt");
+    assertNumber(auth.signedAt, "operation.auth.signedAt");
+    if (auth.claim !== undefined && !isRecord(auth.claim)) throw invalid("operation.auth.claim", "must be an object");
+    if (auth.memberId !== actor.memberId) throw invalid("operation.auth.memberId", "does not match actor memberId");
+    if (auth.deviceId !== actor.deviceId) throw invalid("operation.auth.deviceId", "does not match actor deviceId");
+  } else {
+    assertString(auth.credentialId, "operation.auth.credentialId");
+    assertString(auth.signature, "operation.auth.signature");
+    if (auth.kind !== undefined) assertString(auth.kind, "operation.auth.kind");
+    if (auth.alg !== undefined) assertString(auth.alg, "operation.auth.alg");
+    if (auth.keyRole !== undefined) assertString(auth.keyRole, "operation.auth.keyRole");
+    if (auth.publicKeyFingerprint !== undefined) assertString(auth.publicKeyFingerprint, "operation.auth.publicKeyFingerprint");
+    if (auth.issuedAt !== undefined) assertNumber(auth.issuedAt, "operation.auth.issuedAt");
+  }
+  const hashOperation = typeof options.operationContentHash === "function" ? options.operationContentHash : operationContentHash;
+  if (options.validateId !== false && op.id !== hashOperation(op)) throw invalid("operation.id", "does not match operation content hash");
+  if (options.roomId && op.roomId !== options.roomId) throw invalid("operation.roomId", "does not match expected room");
+  if (options.appPackId && op.appPackId !== options.appPackId) throw invalid("operation.appPackId", "does not match expected app pack");
+  if (options.appPackHash && op.appPackHash !== options.appPackHash) throw invalid("operation.appPackHash", "does not match expected app pack hash");
+  return op;
+}
+
+function validateLegacyRoomOperation(operation, path = "operation") {
+  const op = assertRecord(operation, path);
+  if (op.kind !== LEGACY_ROOM_OPERATION_KIND) throw invalid(`${path}.kind`, "is invalid");
+  if (op.version !== LEGACY_ROOM_OPERATION_VERSION) throw invalid(`${path}.version`, "is invalid");
+  assertString(op.roomName, `${path}.roomName`);
+  assertInteger(op.baseVersion, `${path}.baseVersion`, 0);
+  assertInteger(op.sequence, `${path}.sequence`, 1);
+  assertNumber(op.issuedAt, `${path}.issuedAt`);
+  assertString(op.signer, `${path}.signer`);
+  if (op.role !== "admin" && op.role !== "guest") throw invalid(`${path}.role`, "is invalid");
+  const mutation = assertRecord(op.mutation, `${path}.mutation`);
+  assertString(mutation.id, `${path}.mutation.id`);
+  assertString(mutation.clientId, `${path}.mutation.clientId`);
+  assertInteger(mutation.seq, `${path}.mutation.seq`, 1);
+  assertNumber(mutation.ts, `${path}.mutation.ts`);
+  assertString(mutation.op, `${path}.mutation.op`);
+  if (mutation.payload !== undefined && !isRecord(mutation.payload)) throw invalid(`${path}.mutation.payload`, "must be an object");
+  assertString(op.signature, `${path}.signature`, 8192);
+  return op;
+}
+
+function validateHostOperationEntry(operation, path) {
+  const op = assertRecord(operation, path);
+  if (op.kind === LEGACY_ROOM_OPERATION_KIND) return validateLegacyRoomOperation(op, path);
+  return validateRoomOperation(op);
+}
+
+function parseRoomOperation(operation, options = {}) {
+  return validateRoomOperation(operation, options);
+}
+
+module.exports = {
+  parseRoomOperation,
+  validateHostOperationEntry,
+  validateLegacyRoomOperation,
+  validateRoomOperation
+};