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

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@mh-gg/event",
+  "version": "0.1.1-alpha.20260613T085325975Z",
+  "description": "Signed, encrypted party event protocol helpers for matterhorn.",
+  "type": "module",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs",
+      "default": "./src/index.js"
+    },
+    "./canonicalJson": {
+      "types": "./src/canonicalJson.d.ts",
+      "import": "./src/canonicalJson.js",
+      "require": "./src/canonicalJson.cjs",
+      "default": "./src/canonicalJson.js"
+    },
+    "./matterhornOperationBuilder": {
+      "types": "./src/matterhornOperationBuilder.d.ts",
+      "import": "./src/matterhornOperationBuilder.js",
+      "require": "./src/matterhornOperationBuilder.cjs",
+      "default": "./src/matterhornOperationBuilder.js"
+    },
+    "./ngramIndex": {
+      "types": "./src/ngramIndex.d.ts",
+      "import": "./src/ngramIndex.js",
+      "require": "./src/ngramIndex.cjs",
+      "default": "./src/ngramIndex.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "canonicalJson": [
+        "src/canonicalJson.d.ts"
+      ],
+      "matterhornOperationBuilder": [
+        "src/matterhornOperationBuilder.d.ts"
+      ],
+      "*": [
+        "src/index.d.ts"
+      ],
+      "ngramIndex": [
+        "src/ngramIndex.d.ts"
+      ]
+    }
+  },
+  "dependencies": {
+    "nostr-tools": "^2.23.5"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "types": "src/index.d.ts",
+  "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/canonicalJson.cjs

@@ -0,0 +1,63 @@
+const MAX_CANONICAL_DEPTH = 64;
+
+function maxDepthFromOptions(options = {}) {
+  if (Number.isInteger(options.maxDepth) && options.maxDepth >= 0) return options.maxDepth;
+  return MAX_CANONICAL_DEPTH;
+}
+
+function canonicalJson(value, options = {}) {
+  return canonicalJsonInner(value, new WeakSet(), 0, maxDepthFromOptions(options));
+}
+
+function requireDepth(depth, maxDepth) {
+  if (depth > maxDepth) throw new Error("Cannot canonicalize: max depth exceeded");
+}
+
+function canonicalJsonInner(value, seen, depth, maxDepth) {
+  requireDepth(depth, maxDepth);
+
+  if (value === null) return "null";
+  if (typeof value === "string") return JSON.stringify(value.normalize("NFC"));
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("Invalid number");
+    return JSON.stringify(value);
+  }
+  if (typeof value === "boolean") return value ? "true" : "false";
+
+  if (Array.isArray(value)) {
+    if (seen.has(value)) throw new Error("Cannot canonicalize cyclic values");
+    seen.add(value);
+    try {
+      return `[${value.map((item) => canonicalJsonInner(item, seen, depth + 1, maxDepth)).join(",")}]`;
+    } finally {
+      seen.delete(value);
+    }
+  }
+
+  if (typeof value === "object") {
+    if (seen.has(value)) throw new Error("Cannot canonicalize cyclic values");
+    seen.add(value);
+    try {
+      const entries = [];
+      const normalizedKeys = new Set();
+      for (const key of Object.keys(value)) {
+        if (value[key] === undefined) continue;
+        const normalizedKey = key.normalize("NFC");
+        if (normalizedKeys.has(normalizedKey)) throw new Error("Cannot canonicalize duplicate normalized object keys");
+        normalizedKeys.add(normalizedKey);
+        entries.push([normalizedKey, value[key]]);
+      }
+      entries.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+      return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${canonicalJsonInner(entryValue, seen, depth + 1, maxDepth)}`).join(",")}}`;
+    } finally {
+      seen.delete(value);
+    }
+  }
+
+  throw new Error("Unsupported value");
+}
+
+module.exports = {
+  MAX_CANONICAL_DEPTH,
+  canonicalJson
+};

package/src/canonicalJson.d.ts

@@ -0,0 +1,2 @@
+export const MAX_CANONICAL_DEPTH: number;
+export function canonicalJson(value: unknown, options?: { maxDepth?: number }): string;

package/src/canonicalJson.js

@@ -0,0 +1,58 @@
+export const MAX_CANONICAL_DEPTH = 64;
+
+function maxDepthFromOptions(options = {}) {
+  if (Number.isInteger(options.maxDepth) && options.maxDepth >= 0) return options.maxDepth;
+  return MAX_CANONICAL_DEPTH;
+}
+
+export function canonicalJson(value, options = {}) {
+  return canonicalJsonInner(value, new WeakSet(), 0, maxDepthFromOptions(options));
+}
+
+function requireDepth(depth, maxDepth) {
+  if (depth > maxDepth) throw new Error("Cannot canonicalize: max depth exceeded");
+}
+
+function canonicalJsonInner(value, seen, depth, maxDepth) {
+  requireDepth(depth, maxDepth);
+
+  if (value === null) return "null";
+  if (typeof value === "string") return JSON.stringify(value.normalize("NFC"));
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("Invalid number");
+    return JSON.stringify(value);
+  }
+  if (typeof value === "boolean") return value ? "true" : "false";
+
+  if (Array.isArray(value)) {
+    if (seen.has(value)) throw new Error("Cannot canonicalize cyclic values");
+    seen.add(value);
+    try {
+      return `[${value.map((item) => canonicalJsonInner(item, seen, depth + 1, maxDepth)).join(",")}]`;
+    } finally {
+      seen.delete(value);
+    }
+  }
+
+  if (typeof value === "object") {
+    if (seen.has(value)) throw new Error("Cannot canonicalize cyclic values");
+    seen.add(value);
+    try {
+      const entries = [];
+      const normalizedKeys = new Set();
+      for (const key of Object.keys(value)) {
+        if (value[key] === undefined) continue;
+        const normalizedKey = key.normalize("NFC");
+        if (normalizedKeys.has(normalizedKey)) throw new Error("Cannot canonicalize duplicate normalized object keys");
+        normalizedKeys.add(normalizedKey);
+        entries.push([normalizedKey, value[key]]);
+      }
+      entries.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+      return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${canonicalJsonInner(entryValue, seen, depth + 1, maxDepth)}`).join(",")}}`;
+    } finally {
+      seen.delete(value);
+    }
+  }
+
+  throw new Error("Unsupported value");
+}

package/src/chat.cjs

@@ -0,0 +1,28 @@
+const { DEFAULT_MAX_MESSAGE_CHARS } = require("./constants.cjs");
+const { createSignedPartyEvent } = require("./signing.cjs");
+const { validateChatMessagePayload } = require("./validation.cjs");
+
+function createChatMessageEvent(input) {
+  const payload = {
+    text: String(input.text || "")
+  };
+  if (input.displayName !== undefined) payload.displayName = String(input.displayName);
+  if (input.replyTo !== undefined) payload.replyTo = String(input.replyTo);
+
+  const validation = validateChatMessagePayload(payload, DEFAULT_MAX_MESSAGE_CHARS);
+  if (!validation.ok) throw new Error(validation.message);
+
+  return createSignedPartyEvent({
+    kind: "chat.message",
+    partyId: input.partyId,
+    identity: input.identity,
+    payload,
+    roomSecret: input.roomSecret,
+    epochId: input.epochId,
+    createdAt: input.createdAt
+  });
+}
+
+module.exports = {
+  createChatMessageEvent
+};

package/src/constants.cjs

@@ -0,0 +1,59 @@
+const kinds = require("nostr-tools/kinds");
+
+const PROTOCOL = "matterhorn-sdk";
+const VERSION = 1;
+const MATTERHORN_NOSTR_KIND_BY_EVENT_KIND = Object.freeze({
+  "party.created": kinds.Time,
+  "chat.message": kinds.ChannelMessage,
+  "chat.delete": kinds.EventDeletion,
+  "relay.announce": kinds.RelayList,
+  "room.operation": 9001,
+  "file.upload": 1063,
+  "push.home-relays": 9002,
+  "room.key.epoch": 9010,
+  "room.key.epoch.grant": 9011,
+  "room.index.key.grant": 9012,
+  "room.index.ngram": 9013
+});
+const MATTERHORN_EVENT_KIND_BY_NOSTR_KIND = Object.freeze(Object.fromEntries(
+  Object.entries(MATTERHORN_NOSTR_KIND_BY_EVENT_KIND).map(([eventKind, nostrKind]) => [nostrKind, eventKind])
+));
+const MATTERHORN_NOSTR_KINDS = Object.freeze(Array.from(new Set(Object.values(MATTERHORN_NOSTR_KIND_BY_EVENT_KIND))));
+const MATTERHORN_NOSTR_KIND = MATTERHORN_NOSTR_KIND_BY_EVENT_KIND["chat.message"];
+const MATTERHORN_OPERATION_NOSTR_KIND = MATTERHORN_NOSTR_KIND_BY_EVENT_KIND["room.operation"];
+const MATTERHORN_FILE_NOSTR_KIND = MATTERHORN_NOSTR_KIND_BY_EVENT_KIND["file.upload"];
+const MATTERHORN_CALL_SIGNAL_NOSTR_KIND = 24242;
+const MATTERHORN_PRESENCE_NOSTR_KIND = 24312;
+const ENCRYPTION_ALG = "A256GCM";
+const MATTERHORN_EVENT_KINDS = new Set(["party.created", "chat.message", "chat.delete", "relay.announce", "room.operation", "file.upload", "push.home-relays", "room.key.epoch", "room.key.epoch.grant", "room.index.key.grant", "room.index.ngram"]);
+const MATTERHORN_PUSH_HOME_RELAYS_NOSTR_KIND = MATTERHORN_NOSTR_KIND_BY_EVENT_KIND["push.home-relays"];
+const MATTERHORN_INDEX_NGRAM_NOSTR_KIND = MATTERHORN_NOSTR_KIND_BY_EVENT_KIND["room.index.ngram"];
+const MATTERHORN_ID_PATTERN = /^[a-zA-Z0-9_-]{3,128}$/;
+const HEX_32_PATTERN = /^[0-9a-f]{64}$/i;
+const HEX_64_PATTERN = /^[0-9a-f]{128}$/i;
+const DEFAULT_MAX_EVENT_BYTES = 8 * 1024;
+const DEFAULT_MAX_MESSAGE_CHARS = 2000;
+const DEFAULT_MAX_FUTURE_MS = 10 * 60 * 1000;
+
+module.exports = {
+  DEFAULT_MAX_EVENT_BYTES,
+  DEFAULT_MAX_FUTURE_MS,
+  DEFAULT_MAX_MESSAGE_CHARS,
+  ENCRYPTION_ALG,
+  HEX_32_PATTERN,
+  HEX_64_PATTERN,
+  MATTERHORN_CALL_SIGNAL_NOSTR_KIND,
+  MATTERHORN_EVENT_KIND_BY_NOSTR_KIND,
+  MATTERHORN_EVENT_KINDS,
+  MATTERHORN_FILE_NOSTR_KIND,
+  MATTERHORN_INDEX_NGRAM_NOSTR_KIND,
+  MATTERHORN_ID_PATTERN,
+  MATTERHORN_NOSTR_KIND,
+  MATTERHORN_NOSTR_KIND_BY_EVENT_KIND,
+  MATTERHORN_NOSTR_KINDS,
+  MATTERHORN_OPERATION_NOSTR_KIND,
+  MATTERHORN_PUSH_HOME_RELAYS_NOSTR_KIND,
+  MATTERHORN_PRESENCE_NOSTR_KIND,
+  PROTOCOL,
+  VERSION
+};

package/src/encoding.cjs

@@ -0,0 +1,19 @@
+const crypto = require("node:crypto");
+
+function sha256Hex(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function base64url(bytes) {
+  return Buffer.from(bytes).toString("base64url");
+}
+
+function fromBase64url(value) {
+  return Buffer.from(String(value), "base64url");
+}
+
+module.exports = {
+  base64url,
+  fromBase64url,
+  sha256Hex
+};

package/src/encryption.cjs

@@ -0,0 +1,141 @@
+const crypto = require("node:crypto");
+const { canonicalJson } = require("./canonicalJson.cjs");
+const { ENCRYPTION_ALG, MATTERHORN_EVENT_KINDS, PROTOCOL, VERSION } = require("./constants.cjs");
+const { base64url, fromBase64url } = require("./encoding.cjs");
+const { isEncryptedPayload } = require("./payload.cjs");
+const { isValidPartyId } = require("./ids.cjs");
+
+const DERIVED_ROOM_KEY_CACHE_MAX = 256;
+const derivedRoomKeyCache = new Map();
+
+function derivedRoomKeyCacheKey(roomSecret, partyId, epochId) {
+  const secretHash = crypto.createHash("sha256").update(String(roomSecret)).digest("hex");
+  return `${secretHash}:${partyId}:${epochId || ""}`;
+}
+
+function setCachedRoomKey(cacheKey, keyBytes) {
+  if (derivedRoomKeyCache.has(cacheKey)) derivedRoomKeyCache.delete(cacheKey);
+  derivedRoomKeyCache.set(cacheKey, Buffer.from(keyBytes));
+  while (derivedRoomKeyCache.size > DERIVED_ROOM_KEY_CACHE_MAX) {
+    const oldestKey = derivedRoomKeyCache.keys().next().value;
+    derivedRoomKeyCache.delete(oldestKey);
+  }
+}
+
+function roomKeySalt(partyId, epochId) {
+  return epochId ? `matterhorn:${partyId}:epoch:${epochId}` : `matterhorn:${partyId}`;
+}
+
+function deriveRoomKeyBytes(roomSecret, partyId, epochId) {
+  const cacheKey = derivedRoomKeyCacheKey(roomSecret, partyId, epochId);
+  const cached = derivedRoomKeyCache.get(cacheKey);
+  if (cached) {
+    derivedRoomKeyCache.delete(cacheKey);
+    derivedRoomKeyCache.set(cacheKey, cached);
+    return Buffer.from(cached);
+  }
+  const keyBytes = crypto.pbkdf2Sync(
+    String(roomSecret),
+    roomKeySalt(partyId, epochId),
+    120000,
+    32,
+    "sha256"
+  );
+  setCachedRoomKey(cacheKey, keyBytes);
+  return Buffer.from(keyBytes);
+}
+
+function clearDerivedRoomKeyCache() {
+  derivedRoomKeyCache.clear();
+}
+
+function derivedRoomKeyCacheSize() {
+  return derivedRoomKeyCache.size;
+}
+
+function legacyEncryptionAad(partyId, kind, epochId) {
+  const suffix = epochId ? `:${epochId}` : "";
+  return Buffer.from(`${PROTOCOL}:v${VERSION}:${partyId}:${kind}${suffix}`, "utf8");
+}
+
+function headerEncryptionAad(header) {
+  if (!header || typeof header !== "object") {
+    throw new Error("header is required for room.operation v2 AAD");
+  }
+  // AAD excludes op-id and payload-hash to avoid circularity.
+  const aadHeader = {};
+  for (const [key, value] of Object.entries(header)) {
+    if (key === "opId" || key === "payloadHash") continue;
+    aadHeader[key] = value;
+  }
+  return Buffer.from(canonicalJson(aadHeader), "utf8");
+}
+
+function encryptionAad({ partyId, kind, epochId, header }) {
+  if (kind === "room.operation" && header) {
+    return headerEncryptionAad(header);
+  }
+  return legacyEncryptionAad(partyId, kind, epochId);
+}
+
+function encryptPartyPayload({ roomSecret, partyId, kind, payload, epochId, header }) {
+  if (!roomSecret) throw new Error("roomSecret is required to encrypt party payloads");
+  if (!isValidPartyId(partyId)) throw new Error("Invalid partyId");
+  if (!MATTERHORN_EVENT_KINDS.has(kind)) throw new Error("Invalid party event kind");
+
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv("aes-256-gcm", deriveRoomKeyBytes(roomSecret, partyId, epochId), iv);
+  cipher.setAAD(encryptionAad({ partyId, kind, epochId, header }));
+  const plaintext = Buffer.from(canonicalJson(payload), "utf8");
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+
+  return {
+    encrypted: true,
+    alg: ENCRYPTION_ALG,
+    epochId,
+    iv: base64url(iv),
+    data: base64url(ciphertext)
+  };
+}
+
+function payloadHashFromCiphertext(dataBase64) {
+  const bytes = fromBase64url(dataBase64);
+  if (bytes.length < 16) return undefined;
+  const ciphertext = bytes.subarray(0, bytes.length - 16);
+  return `sha256:${crypto.createHash("sha256").update(ciphertext).digest("hex")}`;
+}
+
+function decryptPartyPayload({ roomSecret, partyId, kind, payload, header }) {
+  if (!isEncryptedPayload(payload)) throw new Error("Payload is not encrypted");
+
+  // For v2 operations, verify the ciphertext matches the header's payload-hash before decrypting.
+  if (kind === "room.operation" && header && header.scheme === "matterhorn.operation.v2" && header.payloadHash) {
+    const actualHash = payloadHashFromCiphertext(payload.data);
+    if (actualHash !== header.payloadHash) {
+      throw new Error("payload-hash mismatch: ciphertext does not match header");
+    }
+  }
+
+  const bytes = fromBase64url(payload.data);
+  if (bytes.length < 17) throw new Error("Invalid encrypted payload");
+
+  const ciphertext = bytes.subarray(0, bytes.length - 16);
+  const authTag = bytes.subarray(bytes.length - 16);
+  const decipher = crypto.createDecipheriv("aes-256-gcm", deriveRoomKeyBytes(roomSecret, partyId, payload.epochId), fromBase64url(payload.iv));
+  decipher.setAAD(encryptionAad({ partyId, kind, epochId: payload.epochId, header }));
+  decipher.setAuthTag(authTag);
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return JSON.parse(plaintext.toString("utf8"));
+}
+
+module.exports = {
+  DERIVED_ROOM_KEY_CACHE_MAX,
+  clearDerivedRoomKeyCache,
+  decryptPartyPayload,
+  deriveRoomKeyBytes,
+  derivedRoomKeyCacheSize,
+  encryptPartyPayload,
+  encryptionAad,
+  headerEncryptionAad,
+  legacyEncryptionAad
+};

package/src/epochFilter.cjs

@@ -0,0 +1,14 @@
+const { isEncryptedPayload } = require("./payload.cjs");
+
+function isPartyEventAllowedForKeyEpochs(event, keyEpochs = []) {
+  if (!isEncryptedPayload(event?.payload)) return true;
+  const epochId = event.payload.epochId;
+  if (!epochId) return true;
+  const epoch = keyEpochs.find((item) => item.id === epochId);
+  if (!epoch) return false;
+  return !epoch.retiredAt || event.createdAt <= epoch.retiredAt;
+}
+
+module.exports = {
+  isPartyEventAllowedForKeyEpochs
+};

package/src/identity.cjs

@@ -0,0 +1,16 @@
+const { generateSecretKey, getPublicKey } = require("nostr-tools/pure");
+const { bytesToHex } = require("nostr-tools/utils");
+
+function generatePartyIdentity(createdAt = Date.now()) {
+  const privateKeyBytes = generateSecretKey();
+  const privateKey = bytesToHex(privateKeyBytes);
+  return {
+    pubkey: getPublicKey(privateKeyBytes),
+    privateKey,
+    createdAt
+  };
+}
+
+module.exports = {
+  generatePartyIdentity
+};

package/src/ids.cjs

@@ -0,0 +1,9 @@
+const { MATTERHORN_ID_PATTERN } = require("./constants.cjs");
+
+function isValidPartyId(value) {
+  return typeof value === "string" && MATTERHORN_ID_PATTERN.test(value);
+}
+
+module.exports = {
+  isValidPartyId
+};

package/src/index.cjs

@@ -0,0 +1,16 @@
+module.exports = {
+  ...require("./canonicalJson.cjs"),
+  ...require("./chat.cjs"),
+  ...require("./constants.cjs"),
+  ...require("./encoding.cjs"),
+  ...require("./encryption.cjs"),
+  ...require("./epochFilter.cjs"),
+  ...require("./identity.cjs"),
+  ...require("./ids.cjs"),
+  ...require("./nostrMapping.cjs"),
+  ...require("./ngramIndex.cjs"),
+  ...require("./payload.cjs"),
+  ...require("./relayPolicy.cjs"),
+  ...require("./signing.cjs"),
+  ...require("./validation.cjs")
+};

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./canonicalJson";
+export const MATTERHORN_CALL_SIGNAL_NOSTR_KIND: number;
+export const MATTERHORN_FILE_NOSTR_KIND: number;
+export const MATTERHORN_PRESENCE_NOSTR_KIND: number;
+export const MATTERHORN_PUSH_HOME_RELAYS_NOSTR_KIND: number;
+export const MATTERHORN_INDEX_NGRAM_NOSTR_KIND: number;

package/src/index.js

@@ -0,0 +1,6 @@
+export { MAX_CANONICAL_DEPTH, canonicalJson } from "./canonicalJson.js";
+export const MATTERHORN_CALL_SIGNAL_NOSTR_KIND = 24242;
+export const MATTERHORN_FILE_NOSTR_KIND = 1063;
+export const MATTERHORN_PRESENCE_NOSTR_KIND = 24312;
+export const MATTERHORN_PUSH_HOME_RELAYS_NOSTR_KIND = 9002;
+export const MATTERHORN_INDEX_NGRAM_NOSTR_KIND = 9013;

package/src/matterhornOperationBuilder.cjs

@@ -0,0 +1,101 @@
+const {
+  createSignedPartyEvent,
+  partyEventToNostrEvent
+} = require("./index.cjs");
+const { createRoomIndexNgramEvents } = require("./ngramIndex.cjs");
+
+function createMatterhornOperationEvent({ identity, operation, roomName, roomSecret, createdAt = Date.now() }) {
+  if (!roomSecret) throw new Error("roomSecret is required to create encrypted room operation events");
+
+  // Build the v2 plaintext header from the operation metadata.
+  const header = {
+    scheme: "matterhorn.operation.v2",
+    opId: operation.opId || operation.id,
+    hlc: operation.hlc,
+    plugin: operation.pluginId,
+    type: operation.type,
+    action: operation.schemaAction,
+    member: operation.actor?.memberId,
+    device: operation.actor?.deviceId,
+    role: operation.actor?.role,
+    grants: operation.grants,
+    epoch: operation.epoch,
+    stream: operation.stream,
+    seq: operation.seq,
+    appPackId: operation.appPackId,
+    appPackHash: operation.appPackHash
+  };
+
+  // Encrypt only the application payload.
+  const event = createSignedPartyEvent({
+    kind: "room.operation",
+    partyId: roomName,
+    identity,
+    header,
+    payload: operation.payload,
+    roomSecret,
+    epochId: operation.epoch,
+    createdAt
+  });
+  return partyEventToNostrEvent(event);
+}
+
+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 valueAtPath(value, path) {
+  if (!path || typeof path !== "string") return undefined;
+  let current = value;
+  for (const part of path.split(".")) {
+    if (!part) continue;
+    if (!current || typeof current !== "object") return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+function stringifySearchValue(value) {
+  if (value === undefined || value === null) return "";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return value.map(stringifySearchValue).filter(Boolean).join(" ");
+  return "";
+}
+
+function searchTextFromOptions(operation, options) {
+  if (Array.isArray(options.indexText)) return options.indexText.map(stringifySearchValue).filter(Boolean).join(" ");
+  if (options.indexText !== undefined) return stringifySearchValue(options.indexText);
+  if (Array.isArray(options.indexPaths)) {
+    return options.indexPaths
+      .map((path) => stringifySearchValue(valueAtPath(operation.payload, path)))
+      .filter(Boolean)
+      .join(" ");
+  }
+  return "";
+}
+
+function createMatterhornOperationEventBundle(options = {}) {
+  const event = createMatterhornOperationEvent(options);
+  const operation = options.operation || {};
+  const text = searchTextFromOptions(operation, options);
+  const indexEvents = options.roomIndexKey && text ? createRoomIndexNgramEvents({
+    identity: options.identity,
+    roomIndexKey: options.roomIndexKey,
+    roomName: options.roomName,
+    targetEventId: event.id,
+    targetOperationId: tagValue(event.tags, "op-id") || operation.opId || operation.id,
+    targetHlc: tagValue(event.tags, "hlc") || operation.hlc,
+    stream: tagValue(event.tags, "stream") || operation.stream,
+    field: Array.isArray(options.indexPaths) ? options.indexPaths.join(",") : options.indexField,
+    text,
+    minGram: options.minGram,
+    maxGram: options.maxGram,
+    maxTokensPerEvent: options.maxTokensPerEvent,
+    createdAt: (Number.isInteger(options.createdAt) ? options.createdAt : Date.now()) + 1
+  }) : [];
+  return { event, indexEvents, events: [event, ...indexEvents] };
+}
+
+module.exports = { createMatterhornOperationEvent, createMatterhornOperationEventBundle };

package/src/matterhornOperationBuilder.d.ts

@@ -0,0 +1,39 @@
+export interface MatterhornOperationEventOptions {
+  identity: unknown;
+  operation: {
+    id?: string;
+    opId?: string;
+    hlc?: unknown;
+    pluginId?: string;
+    type?: string;
+    schemaAction?: string;
+    actor?: {
+      memberId?: string;
+      deviceId?: string;
+      role?: string;
+    };
+    grants?: unknown;
+    epoch?: unknown;
+    stream?: unknown;
+    seq?: unknown;
+    appPackId?: string;
+    appPackHash?: string;
+    payload?: unknown;
+  };
+  roomName: string;
+  roomSecret: string;
+  createdAt?: number;
+}
+
+export interface MatterhornOperationEventBundleOptions extends MatterhornOperationEventOptions {
+  roomIndexKey?: string;
+  indexText?: unknown | unknown[];
+  indexPaths?: string[];
+  indexField?: string;
+  minGram?: number;
+  maxGram?: number;
+  maxTokensPerEvent?: number;
+}
+
+export function createMatterhornOperationEvent(options: MatterhornOperationEventOptions): unknown;
+export function createMatterhornOperationEventBundle(options: MatterhornOperationEventBundleOptions): { event: unknown; indexEvents: unknown[]; events: unknown[] };

package/src/matterhornOperationBuilder.js

@@ -0,0 +1,9 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const {
+  createMatterhornOperationEvent,
+  createMatterhornOperationEventBundle
+} = require("./matterhornOperationBuilder.cjs");
+
+export { createMatterhornOperationEvent, createMatterhornOperationEventBundle };