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

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@mh-gg/protocol",
+  "version": "0.1.1-alpha.20260613T085325975Z",
+  "description": "Shared Matterhorn wire protocol validators and operation schemas.",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "dependencies": {
+    "nostr-tools": "^2.23.5",
+    "@mh-gg/event": "^0.1.1-alpha.20260613T085325975Z"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 --test-coverage-include=src/**/*.cjs test/*.test.cjs"
+  }
+}

package/src/assertions.cjs

@@ -0,0 +1,52 @@
+const { MAX_ID_LENGTH, PROTOCOL_VERSION } = require("./constants.cjs");
+const { invalid } = require("./errors.cjs");
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertRecord(value, path) {
+  if (!isRecord(value)) throw invalid(path, "must be an object");
+  return value;
+}
+
+function assertString(value, path, maxLength = MAX_ID_LENGTH) {
+  if (typeof value !== "string" || value.length === 0) throw invalid(path, "must be a non-empty string");
+  if (value.length > maxLength) throw invalid(path, "is too large");
+  return value;
+}
+
+function assertOptionalString(value, path, maxLength = MAX_ID_LENGTH) {
+  if (value === undefined) return undefined;
+  return assertString(value, path, maxLength);
+}
+
+function assertNumber(value, path) {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw invalid(path, "must be a finite number");
+  return value;
+}
+
+function assertInteger(value, path, min = 0) {
+  if (!Number.isInteger(value) || value < min) throw invalid(path, `must be an integer >= ${min}`);
+  return value;
+}
+
+function assertArray(value, path) {
+  if (!Array.isArray(value)) throw invalid(path, "must be an array");
+  return value;
+}
+
+function assertProtocol(value, path) {
+  if (value.protocol !== PROTOCOL_VERSION) throw invalid(path, "protocol is invalid");
+}
+
+module.exports = {
+  assertArray,
+  assertInteger,
+  assertNumber,
+  assertOptionalString,
+  assertProtocol,
+  assertRecord,
+  assertString,
+  isRecord
+};

package/src/constants.cjs

@@ -0,0 +1,35 @@
+const { MAX_CANONICAL_DEPTH } = require("@mh-gg/event/canonicalJson");
+
+const PROTOCOL_VERSION = 1;
+const MAX_ID_LENGTH = 240;
+const MAX_RELAY_ADDRESS_LENGTH = 2048;
+const MATTERHORN_OPERATION_KIND = "matterhorn.operation";
+const MATTERHORN_OPERATION_VERSION = 1;
+const LEGACY_ROOM_OPERATION_KIND = "matterhorn.room-operation";
+const LEGACY_ROOM_OPERATION_VERSION = 1;
+const HOST_OPERATION_BATCH_KIND = "matterhorn.host-operation-batch";
+const HOST_SNAPSHOT_KIND = "matterhorn.host-snapshot";
+const MAX_OPERATION_BYTES = 64 * 1024;
+const MAX_OPERATION_DEPTH = MAX_CANONICAL_DEPTH;
+const MAX_PUSH_PAYLOAD_BYTES = 3 * 1024;
+const CLIENT_PUSH_GRANT = "client/push-grant";
+const CLIENT_PUSH_REGISTER = "client/push-register";
+const RELAY_PUSH = "relay.push";
+
+module.exports = {
+  HOST_OPERATION_BATCH_KIND,
+  HOST_SNAPSHOT_KIND,
+  CLIENT_PUSH_GRANT,
+  CLIENT_PUSH_REGISTER,
+  LEGACY_ROOM_OPERATION_KIND,
+  LEGACY_ROOM_OPERATION_VERSION,
+  MAX_ID_LENGTH,
+  MAX_OPERATION_BYTES,
+  MAX_OPERATION_DEPTH,
+  MAX_PUSH_PAYLOAD_BYTES,
+  MAX_RELAY_ADDRESS_LENGTH,
+  PROTOCOL_VERSION,
+  MATTERHORN_OPERATION_KIND,
+  RELAY_PUSH,
+  MATTERHORN_OPERATION_VERSION
+};

package/src/errors.cjs

@@ -0,0 +1,23 @@
+class MatterhornProtocolError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "MatterhornProtocolError";
+    this.code = details.code || "invalid-message";
+    this.path = details.path;
+  }
+}
+
+function invalid(path, message) {
+  return new MatterhornProtocolError(`${path}: ${message}`, { path });
+}
+
+function safeValidate(fn, value, ...args) {
+  try {
+    return { ok: true, value: fn(value, ...args) };
+  } catch (error) {
+    if (error instanceof MatterhornProtocolError) return { ok: false, code: error.code, message: error.message, path: error.path };
+    return { ok: false, code: "invalid-message", message: error?.message || String(error) };
+  }
+}
+
+module.exports = { MatterhornProtocolError, invalid, safeValidate };

package/src/index.cjs

@@ -0,0 +1,14 @@
+module.exports = {
+  ...require("./constants.cjs"),
+  ...require("./errors.cjs"),
+  ...require("./validators/shared.cjs"),
+  ...require("./validators/bounds.cjs"),
+  ...require("./validators/operations.cjs"),
+  ...require("./validators/client.cjs"),
+  ...require("./validators/host.cjs"),
+  ...require("./validators/relay.cjs"),
+  ...require("./operations/identity.cjs"),
+  ...require("./operations/snowflake.cjs"),
+  ...require("./operations/roomDeviceSigning.cjs"),
+  ...require("./parsers/hostOperationBatch.cjs")
+};

package/src/operations/identity.cjs

@@ -0,0 +1,141 @@
+const crypto = require("node:crypto");
+const { canonicalJson } = require("@mh-gg/event/canonicalJson");
+
+const HLC_PHYSICAL_WIDTH = 15;
+const HLC_LOGICAL_WIDTH = 6;
+const DEFAULT_MAX_HLC_FUTURE_SKEW_MS = 5 * 60 * 1000;
+const HLC_RE = /^([0-9]{15}):([0-9]{6}):([A-Za-z0-9_.:-]{1,128})$/;
+
+function codePointCompare(left = "", right = "") {
+  const a = String(left);
+  const b = String(right);
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function padNumber(value, width, name) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${name} must be a non-negative safe integer`);
+  const text = String(value);
+  if (text.length > width) throw new Error(`${name} exceeds HLC width`);
+  return text.padStart(width, "0");
+}
+
+function parseHlc(hlc) {
+  if (typeof hlc !== "string") return undefined;
+  const match = HLC_RE.exec(hlc);
+  if (!match) return undefined;
+  return { physical: Number(match[1]), logical: Number(match[2]), nodeId: match[3], value: hlc };
+}
+
+function formatHlc({ physical, logical = 0, nodeId } = {}) {
+  if (typeof nodeId !== "string" || nodeId.length === 0 || !/^[A-Za-z0-9_.:-]{1,128}$/.test(nodeId)) throw new Error("nodeId is invalid");
+  return `${padNumber(physical, HLC_PHYSICAL_WIDTH, "physical")}:${padNumber(logical, HLC_LOGICAL_WIDTH, "logical")}:${nodeId}`;
+}
+
+function validateHlc(hlc, options = {}) {
+  const parsed = parseHlc(hlc);
+  if (!parsed) return { ok: false, error: "operation.hlc is invalid" };
+  const now = Number.isFinite(options.now) ? options.now : (typeof options.now === "function" ? options.now() : Date.now());
+  const skew = Number.isFinite(options.maxFutureSkewMs) ? options.maxFutureSkewMs : DEFAULT_MAX_HLC_FUTURE_SKEW_MS;
+  if (Number.isFinite(now) && parsed.physical > now + skew) return { ok: false, error: "operation.hlc exceeds allowed future skew" };
+  return { ok: true, parsed };
+}
+
+function compareHlc(left, right) { return codePointCompare(left, right); }
+function maxHlc(left, right) {
+  if (!left) return right || "";
+  if (!right) return left || "";
+  return compareHlc(left, right) >= 0 ? left : right;
+}
+function advanceHlc(lastSeen, { now = Date.now(), nodeId = "node" } = {}) {
+  const observed = parseHlc(lastSeen);
+  const wall = Number.isFinite(Number(now)) ? Math.max(0, Math.floor(Number(now))) : 0;
+  const physical = Math.max(wall, observed?.physical || 0);
+  const logical = observed && physical === observed.physical ? observed.logical + 1 : 0;
+  return formatHlc({ physical, logical, nodeId });
+}
+function createHlcClock({ nodeId = "node", now = () => Date.now(), initialHlc } = {}) {
+  let lastSeen = parseHlc(initialHlc)?.value || "";
+  return {
+    observe(hlc) { const parsed = parseHlc(hlc); if (parsed) lastSeen = maxHlc(lastSeen, parsed.value); return lastSeen; },
+    next() { lastSeen = advanceHlc(lastSeen, { now: typeof now === "function" ? now() : now, nodeId }); return lastSeen; },
+    lastSeen() { return lastSeen; }
+  };
+}
+
+function clone(value) {
+  if (value === undefined) return undefined;
+  const encoded = JSON.stringify(value);
+  return encoded === undefined ? undefined : JSON.parse(encoded);
+}
+function unsignedOperationBodyForId(operation) {
+  const next = clone(operation || {});
+  delete next.id;
+  delete next.committedRoomVersion;
+  delete next.committedAt;
+  delete next.receivedAt;
+  delete next.relayId;
+  delete next.ledgerId;
+  delete next.snowflakeId;
+  if (next.auth && typeof next.auth === "object") {
+    delete next.auth.signature;
+    delete next.auth.signatureEventId;
+    delete next.auth.eventId;
+    delete next.auth.signedAt;
+  }
+  return next;
+}
+function operationContentHash(operation) {
+  return `sha256:${crypto.createHash("sha256").update(canonicalJson(unsignedOperationBodyForId(operation))).digest("hex")}`;
+}
+function unsignedHeaderForId(header) {
+  const next = {};
+  for (const [key, value] of Object.entries(header || {})) {
+    if (key === "opId") continue;
+    if (value !== undefined) next[key] = value;
+  }
+  return next;
+}
+function operationHeaderHash(header) {
+  return `sha256:${crypto.createHash("sha256").update(canonicalJson(unsignedHeaderForId(header))).digest("hex")}`;
+}
+function operationHash(operation, header) {
+  if (header && (header.scheme === "matterhorn.operation.v2" || operation?.scheme === "matterhorn.operation.v2")) {
+    return operationHeaderHash(header);
+  }
+  return operationContentHash(operation);
+}
+function assignOperationId(operation, header) { const next = clone(operation || {}); next.id = operationHash(next, header); return next; }
+function operationIdMatchesContent(operation, header) { return Boolean(operation && typeof operation === "object" && operation.id === operationHash(operation, header)); }
+function ensureOperationIdentity(operation, options = {}) {
+  const next = clone(operation || {});
+  if (!parseHlc(next.hlc)) {
+    next.hlc = advanceHlc(options.lastSeenHlc, {
+      now: typeof options.now === "function" ? options.now() : (Number.isFinite(options.now) ? options.now : Date.now()),
+      nodeId: options.nodeId || next.actor?.deviceId || next.actor?.memberId || "node"
+    });
+  }
+  next.id = operationHash(next, options.header);
+  return next;
+}
+
+module.exports = {
+  DEFAULT_MAX_HLC_FUTURE_SKEW_MS,
+  HLC_LOGICAL_WIDTH,
+  HLC_PHYSICAL_WIDTH,
+  advanceHlc,
+  assignOperationId,
+  codePointCompare,
+  compareHlc,
+  createHlcClock,
+  ensureOperationIdentity,
+  formatHlc,
+  maxHlc,
+  operationContentHash,
+  operationHeaderHash,
+  operationHash,
+  operationIdMatchesContent,
+  parseHlc,
+  unsignedHeaderForId,
+  unsignedOperationBodyForId,
+  validateHlc
+};

package/src/operations/roomDeviceSigning.cjs

@@ -0,0 +1,159 @@
+const { canonicalJson } = require("@mh-gg/event/canonicalJson");
+const {
+  MATTERHORN_DEVICE_SIGNATURE_NOSTR_KIND,
+  MATTERHORN_ROOM_DEVICE_SIGNING_ALG,
+  MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME
+} = require("./roomDeviceSigningConstants.cjs");
+const {
+  validateRoomDeviceSignedOperationAuth,
+  validateRoomMemberKeyClaim
+} = require("./roomDeviceSigningValidation.cjs");
+
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function eventForSignature({ purpose, roomName, memberId, deviceId, keyId, publicKey, content, eventId, sig, createdAt }) {
+  return {
+    kind: MATTERHORN_DEVICE_SIGNATURE_NOSTR_KIND,
+    created_at: createdAt || Math.floor(Date.now() / 1000),
+    tags: [
+      ["protocol", "matterhorn-sdk"],
+      ["scheme", MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME],
+      ["purpose", purpose],
+      ["room", roomName],
+      ["member", memberId],
+      ["device", deviceId],
+      ["key", keyId]
+    ],
+    content,
+    pubkey: publicKey,
+    id: eventId || "",
+    sig: sig || ""
+  };
+}
+
+function verifyEvent(event) {
+  const nostr = require("nostr-tools");
+  if (typeof nostr.verifyEvent === "function") return nostr.verifyEvent(event) === true;
+  if (typeof nostr.validateEvent === "function" && typeof nostr.verifySignature === "function") return nostr.validateEvent(event) && nostr.verifySignature(event);
+  throw new Error("nostr-tools does not expose a supported event verifier");
+}
+
+function unsignedRoomOperationForDeviceSignature(operation) {
+  const next = clone(operation || {});
+  if (next.auth && typeof next.auth === "object") {
+    delete next.auth.signature;
+    delete next.auth.signatureEventId;
+    delete next.auth.eventId;
+    delete next.auth.signedAt;
+  }
+  delete next.ledgerId;
+  delete next.snowflakeId;
+  delete next.committedRoomVersion;
+  delete next.committedAt;
+  delete next.receivedAt;
+  delete next.relayId;
+  // For matterhorn.operation.v2, the device signature binds the plaintext header so that
+  // tampering with any header tag invalidates the device proof.
+  if (next.header && next.header.scheme === "matterhorn.operation.v2") {
+    return { header: next.header, payloadHash: next.header.payloadHash };
+  }
+  return next;
+}
+
+function unsignedMemberKeyClaim(claim) {
+  const next = clone(claim || {});
+  delete next.proof;
+  delete next.rootProof;
+  return next;
+}
+
+function verifyRoomMemberKeyClaim(claim) {
+  const validation = validateRoomMemberKeyClaim(claim);
+  if (!validation.ok) return validation;
+  const content = canonicalJson(unsignedMemberKeyClaim(claim));
+  try {
+    const rootOk = verifyEvent(eventForSignature({
+      purpose: "member-key",
+      roomName: validation.roomName,
+      memberId: claim.memberId,
+      deviceId: claim.deviceId,
+      keyId: claim.keyId,
+      publicKey: claim.rootPublicKey,
+      content,
+      eventId: claim.rootProof.eventId,
+      sig: claim.rootProof.sig,
+      createdAt: claim.rootProof.createdAt
+    }));
+    if (!rootOk) return { ok: false, error: "member key root proof is invalid" };
+    const deviceOk = verifyEvent(eventForSignature({
+      purpose: "member-key",
+      roomName: validation.roomName,
+      memberId: claim.memberId,
+      deviceId: claim.deviceId,
+      keyId: claim.keyId,
+      publicKey: claim.publicKey,
+      content,
+      eventId: claim.proof.eventId,
+      sig: claim.proof.sig,
+      createdAt: claim.proof.createdAt
+    }));
+    return deviceOk ? { ok: true, claim } : { ok: false, error: "member key device proof is invalid" };
+  } catch (error) {
+    return { ok: false, error: error && error.message ? error.message : String(error) };
+  }
+}
+
+function verifyRoomDeviceKeyClaim(claim) {
+  return verifyRoomMemberKeyClaim(claim).ok;
+}
+
+function verifyRoomDeviceOperationSignature(operation, claim) {
+  return verifyRoomDeviceSignedOperation(operation, claim);
+}
+
+function verifyRoomDeviceSignedOperation(operation, claim = operation && operation.auth && operation.auth.claim) {
+  const authValidation = validateRoomDeviceSignedOperationAuth(operation);
+  if (!authValidation.ok) return authValidation;
+  const auth = authValidation.auth;
+  const memberClaim = claim || auth.claim;
+  const claimVerification = verifyRoomMemberKeyClaim(memberClaim);
+  if (!claimVerification.ok) return claimVerification;
+  const roomName = String(operation.roomId || memberClaim.roomName || memberClaim.roomId || "");
+  if (roomName.length === 0) return { ok: false, error: "operation room is required" };
+  if (memberClaim.keyId !== auth.keyId) return { ok: false, error: "operation key does not match member key claim" };
+  if (memberClaim.memberId !== auth.memberId || memberClaim.deviceId !== auth.deviceId) return { ok: false, error: "operation actor does not match member key claim" };
+  if (memberClaim.rootPublicKey !== auth.rootPublicKey) return { ok: false, error: "operation root public key does not match member key claim" };
+  if (memberClaim.publicKey !== auth.publicKey || memberClaim.publicKeyFingerprint !== auth.publicKeyFingerprint) return { ok: false, error: "operation public key does not match member key claim" };
+  try {
+    const ok = verifyEvent(eventForSignature({
+      purpose: "operation",
+      roomName,
+      memberId: auth.memberId,
+      deviceId: auth.deviceId,
+      keyId: auth.keyId,
+      publicKey: auth.publicKey,
+      content: canonicalJson(unsignedRoomOperationForDeviceSignature(operation)),
+      eventId: authValidation.eventId,
+      sig: auth.signature,
+      createdAt: auth.signedAt
+    }));
+    return ok ? { ok: true, auth, claim: memberClaim } : { ok: false, error: "operation room-device signature is invalid" };
+  } catch (error) {
+    return { ok: false, error: error && error.message ? error.message : String(error) };
+  }
+}
+
+module.exports = {
+  MATTERHORN_DEVICE_SIGNATURE_NOSTR_KIND,
+  MATTERHORN_ROOM_DEVICE_SIGNING_ALG,
+  MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME,
+  unsignedRoomOperationForDeviceSignature,
+  validateRoomDeviceSignedOperationAuth,
+  validateRoomMemberKeyClaim,
+  verifyRoomDeviceKeyClaim,
+  verifyRoomDeviceOperationSignature,
+  verifyRoomDeviceSignedOperation,
+  verifyRoomMemberKeyClaim
+};

package/src/operations/roomDeviceSigningConstants.cjs

@@ -0,0 +1,9 @@
+const MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME = "matterhorn.device-signing.v1";
+const MATTERHORN_ROOM_DEVICE_SIGNING_ALG = "nostr-secp256k1";
+const MATTERHORN_DEVICE_SIGNATURE_NOSTR_KIND = 24313;
+
+module.exports = {
+  MATTERHORN_DEVICE_SIGNATURE_NOSTR_KIND,
+  MATTERHORN_ROOM_DEVICE_SIGNING_ALG,
+  MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME
+};

package/src/operations/roomDeviceSigningValidation.cjs

@@ -0,0 +1,63 @@
+const {
+  MATTERHORN_ROOM_DEVICE_SIGNING_ALG,
+  MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME
+} = require("./roomDeviceSigningConstants.cjs");
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isHex(value, length) {
+  return typeof value === "string" && value.length === length && new RegExp(`^[0-9a-f]{${length}}$`, "i").test(value);
+}
+
+function validateRoomMemberKeyClaim(claim) {
+  if (!isRecord(claim)) return { ok: false, error: "member key claim is required" };
+  if (claim.kind !== "matterhorn.member-key-claim") return { ok: false, error: "member key claim kind is invalid" };
+  if (claim.type !== undefined && claim.type !== "matterhorn/member-key/v1") return { ok: false, error: "member key claim type is invalid" };
+  if (claim.version !== 1) return { ok: false, error: "member key claim version is invalid" };
+  if (claim.scheme !== MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME) return { ok: false, error: "member key claim scheme is invalid" };
+  if (claim.alg !== MATTERHORN_ROOM_DEVICE_SIGNING_ALG) return { ok: false, error: "member key claim alg is invalid" };
+  for (const field of ["memberId", "deviceId", "keyId", "rootPublicKey", "publicKey", "publicKeyFingerprint", "encryptionKeyId", "encryptionPublicKey"]) {
+    if (typeof claim[field] !== "string" || claim[field].length === 0) return { ok: false, error: `member key claim ${field} is required` };
+  }
+  if (claim.encryptionAlg !== "x25519") return { ok: false, error: "member key claim encryptionAlg is invalid" };
+  const roomName = claim.roomName || claim.roomId;
+  if (typeof roomName !== "string" || roomName.length === 0) return { ok: false, error: "member key claim room is required" };
+  if (!isHex(claim.rootPublicKey, 64)) return { ok: false, error: "member key claim rootPublicKey is invalid" };
+  if (!isHex(claim.publicKey, 64)) return { ok: false, error: "member key claim publicKey is invalid" };
+  if (!Number.isFinite(Number(claim.createdAt))) return { ok: false, error: "member key claim createdAt is invalid" };
+  if (!isRecord(claim.rootProof)) return { ok: false, error: "member key root proof is required" };
+  if (claim.rootProof.alg !== MATTERHORN_ROOM_DEVICE_SIGNING_ALG) return { ok: false, error: "member key root proof alg is invalid" };
+  if (!isHex(claim.rootProof.eventId, 64) || !isHex(claim.rootProof.sig, 128)) return { ok: false, error: "member key root proof shape is invalid" };
+  if (!isRecord(claim.proof)) return { ok: false, error: "member key device proof is required" };
+  if (claim.proof.alg !== MATTERHORN_ROOM_DEVICE_SIGNING_ALG) return { ok: false, error: "member key device proof alg is invalid" };
+  if (!isHex(claim.proof.eventId, 64) || !isHex(claim.proof.sig, 128)) return { ok: false, error: "member key device proof shape is invalid" };
+  return { ok: true, claim, roomName };
+}
+
+function validateRoomDeviceSignedOperationAuth(operation) {
+  if (!isRecord(operation)) return { ok: false, error: "operation is required" };
+  const auth = operation.auth;
+  if (!isRecord(auth)) return { ok: false, error: "operation auth is required" };
+  if (auth.scheme !== MATTERHORN_ROOM_DEVICE_SIGNING_SCHEME) return { ok: false, error: "operation auth scheme is invalid" };
+  if (auth.alg !== MATTERHORN_ROOM_DEVICE_SIGNING_ALG) return { ok: false, error: "operation auth alg is invalid" };
+  if (auth.kind !== undefined && auth.kind !== "matterhorn.operation-device-signature") return { ok: false, error: "operation auth kind is invalid" };
+  for (const field of ["memberId", "deviceId", "keyId", "credentialId", "rootPublicKey", "publicKey", "publicKeyFingerprint", "signature"]) {
+    if (typeof auth[field] !== "string" || auth[field].length === 0) return { ok: false, error: `operation auth ${field} is required` };
+  }
+  const eventId = auth.signatureEventId || auth.eventId;
+  if (!isHex(auth.rootPublicKey, 64) || !isHex(auth.publicKey, 64) || !isHex(auth.signature, 128) || !isHex(eventId, 64)) return { ok: false, error: "operation device signature shape is invalid" };
+  if (!Number.isFinite(Number(auth.issuedAt))) return { ok: false, error: "operation auth issuedAt is invalid" };
+  if (!Number.isFinite(Number(auth.signedAt))) return { ok: false, error: "operation auth signedAt is invalid" };
+  if (auth.credentialId !== auth.keyId) return { ok: false, error: "operation auth credentialId must match keyId" };
+  const actor = operation.actor || {};
+  if (actor.memberId !== auth.memberId) return { ok: false, error: "operation auth member mismatch" };
+  if (actor.deviceId !== auth.deviceId) return { ok: false, error: "operation auth device mismatch" };
+  return { ok: true, auth, eventId };
+}
+
+module.exports = {
+  validateRoomDeviceSignedOperationAuth,
+  validateRoomMemberKeyClaim
+};