@mh-gg/host-store 0.1.1-alpha.20260613T085325975Z

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@mh-gg/host-store",
+  "version": "0.1.1-alpha.20260613T085325975Z",
+  "description": "Node host room store persistence for matterhorn.",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs"
+  },
+  "dependencies": {
+    "@mh-gg/room-link": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/room-security": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/room-state": "^0.1.1-alpha.20260613T085325975Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "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/index.cjs

@@ -0,0 +1,156 @@
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const { roomToPeerId } = require("@mh-gg/room-link");
+const { activeAdminProfileIds, ensureRoomSecurity } = require("@mh-gg/room-security");
+const { createAdminBootstrap, defaultState } = require("@mh-gg/room-state");
+const {
+  CURRENT_STORE_SCHEMA_VERSION,
+  migrateStore,
+  prepareStoreForSave
+} = require("./schema.cjs");
+const { ensureOperationSigningKey, operationKeyPin, operationPublicKeyHash } = require("./operationSigning.cjs");
+
+const PRIVATE_DIR_MODE = 0o700;
+const PRIVATE_FILE_MODE = 0o600;
+
+function attachDataDir(store, dataDir) {
+  Object.defineProperty(store, "dataDir", {
+    value: dataDir,
+    configurable: true,
+    writable: true
+  });
+  return store;
+}
+
+function randomSecret() {
+  return crypto.randomBytes(24).toString("base64url");
+}
+
+function attachAdminBootstrapToken(store, token) {
+  Object.defineProperty(store, "adminBootstrapToken", {
+    value: token,
+    configurable: true,
+    writable: true
+  });
+}
+
+function stateFile(dataDir, roomName) {
+  return path.join(dataDir, `${roomName}.json`);
+}
+
+function chmodPrivate(file, mode) {
+  try {
+    fs.chmodSync(file, mode);
+  } catch {}
+}
+
+function ensurePrivateDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: PRIVATE_DIR_MODE });
+  chmodPrivate(dir, PRIVATE_DIR_MODE);
+}
+
+function fsyncDir(dir) {
+  if (process.platform === "win32") return;
+  let fd;
+  try {
+    fd = fs.openSync(dir, "r");
+    fs.fsyncSync(fd);
+  } catch {
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function atomicWritePrivateFile(file, data) {
+  ensurePrivateDir(path.dirname(file));
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(tmp, "wx", PRIVATE_FILE_MODE);
+    fs.writeFileSync(fd, data);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    chmodPrivate(tmp, PRIVATE_FILE_MODE);
+    fs.renameSync(tmp, file);
+    chmodPrivate(file, PRIVATE_FILE_MODE);
+    fsyncDir(path.dirname(file));
+  } catch (error) {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch {}
+    }
+    try { fs.rmSync(tmp, { force: true }); } catch {}
+    throw error;
+  }
+}
+
+function hasStoredSecurity(store) {
+  return (Array.isArray(store.publicInvites) && store.publicInvites.length > 0)
+    || (Array.isArray(store.keyEpochs) && store.keyEpochs.length > 0);
+}
+
+function ensureAdminBootstrap(store) {
+  if (activeAdminProfileIds(store).length > 0) return false;
+  if (store.adminBootstrap?.tokenHash && store.adminBootstrapToken) return false;
+  attachAdminBootstrapToken(store, createAdminBootstrap(store));
+  return true;
+}
+
+function loadStore(args) {
+  ensurePrivateDir(args.dataDir);
+  const file = stateFile(args.dataDir, args.room);
+  if (fs.existsSync(file)) {
+    const store = attachDataDir(migrateStore(JSON.parse(fs.readFileSync(file, "utf8")), args), args.dataDir);
+    if (args.roomSecret && args.roomSecret !== store.roomSecret) {
+      if (hasStoredSecurity(store)) {
+        console.warn("Ignoring ROOM_SECRET/--secret because this room already has membership credentials.");
+      } else {
+        console.warn("Using ROOM_SECRET/--secret from CLI because this room has no membership credentials yet.");
+        store.roomSecret = args.roomSecret;
+      }
+    }
+    ensureRoomSecurity(store);
+    if (ensureAdminBootstrap(store)) saveStore(store);
+    return store;
+  }
+
+  const store = attachDataDir({
+    schemaVersion: CURRENT_STORE_SCHEMA_VERSION,
+    roomName: args.room,
+    roomPeerId: roomToPeerId(args.room),
+    roomSecret: args.roomSecret || randomSecret(),
+    admins: {},
+    seenMutations: [],
+    state: defaultState(args)
+  }, args.dataDir);
+  ensureRoomSecurity(store);
+  ensureAdminBootstrap(store);
+  saveStore(store);
+  return store;
+}
+
+function saveStore(store) {
+  atomicWritePrivateFile(stateFile(store.dataDir, store.roomName), JSON.stringify(prepareStoreForSave(store), null, 2));
+}
+
+function touchState(store, now = Date.now()) {
+  ensureRoomSecurity(store, now);
+  store.state.version += 1;
+  store.state.updatedAt = now;
+  saveStore(store);
+}
+
+module.exports = {
+  CURRENT_STORE_SCHEMA_VERSION,
+  attachDataDir,
+  ensureOperationSigningKey,
+  operationKeyPin,
+  operationPublicKeyHash,
+  loadStore,
+  migrateStore,
+  randomSecret,
+  saveStore,
+  stateFile,
+  touchState
+};

package/src/operationSigning.cjs

@@ -0,0 +1,58 @@
+const crypto = require("node:crypto");
+
+function operationPublicKeyHash(publicKeyPem) {
+  return `sha256-${crypto.createHash("sha256").update(publicKeyPem).digest("hex")}`;
+}
+
+function operationSignerId(publicKeyPem) {
+  const digest = crypto.createHash("sha256").update(publicKeyPem).digest("hex").slice(0, 16);
+  return `host_${digest}`;
+}
+
+function operationKeyPin(signingKey) {
+  if (!isOperationSigningKey(signingKey)) throw new Error("Operation signing key is invalid");
+  return {
+    alg: signingKey.alg,
+    signer: signingKey.id,
+    publicKeyHash: operationPublicKeyHash(signingKey.publicKeyPem)
+  };
+}
+
+function createOperationSigningKey(now = Date.now()) {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519");
+  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" });
+  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" });
+  return {
+    id: operationSignerId(publicKeyPem),
+    alg: "ed25519",
+    publicKeyPem,
+    privateKeyPem,
+    createdAt: now
+  };
+}
+
+function isOperationSigningKey(value) {
+  return Boolean(value)
+    && typeof value === "object"
+    && value.alg === "ed25519"
+    && typeof value.id === "string"
+    && value.id.length > 0
+    && typeof value.publicKeyPem === "string"
+    && value.publicKeyPem.length > 0
+    && typeof value.privateKeyPem === "string"
+    && value.privateKeyPem.length > 0;
+}
+
+function ensureOperationSigningKey(store) {
+  if (isOperationSigningKey(store.operationSigningKey)) return store.operationSigningKey;
+  store.operationSigningKey = createOperationSigningKey();
+  return store.operationSigningKey;
+}
+
+module.exports = {
+  createOperationSigningKey,
+  ensureOperationSigningKey,
+  operationKeyPin,
+  operationPublicKeyHash,
+  operationSignerId
+};

package/src/schema.cjs

@@ -0,0 +1,47 @@
+const { roomToPeerId } = require("@mh-gg/room-link");
+
+const CURRENT_STORE_SCHEMA_VERSION = 1;
+
+function unsupportedSchemaVersion(version) {
+  throw new Error(`Unsupported room store schema version ${version}; current version is ${CURRENT_STORE_SCHEMA_VERSION}.`);
+}
+
+function schemaVersionFor(store) {
+  if (store.schemaVersion === undefined) return 0;
+  if (!Number.isInteger(store.schemaVersion) || store.schemaVersion < 0) unsupportedSchemaVersion(String(store.schemaVersion));
+  if (store.schemaVersion > CURRENT_STORE_SCHEMA_VERSION) unsupportedSchemaVersion(store.schemaVersion);
+  return store.schemaVersion;
+}
+
+function migrateLegacyStoreToV1(store, args = {}) {
+  if (!store.roomName && args.room) store.roomName = args.room;
+  if (!store.roomPeerId && store.roomName) store.roomPeerId = roomToPeerId(store.roomName);
+  store.schemaVersion = 1;
+  return store;
+}
+
+function migrateStore(store, args = {}) {
+  if (!store || typeof store !== "object" || Array.isArray(store)) {
+    throw new Error("Invalid room store file.");
+  }
+  const version = schemaVersionFor(store);
+  if (version === 0) return migrateLegacyStoreToV1(store, args);
+  return store;
+}
+
+function prepareStoreForSave(store) {
+  if (!store || typeof store !== "object" || Array.isArray(store)) {
+    throw new Error("Invalid room store file.");
+  }
+  const version = schemaVersionFor(store);
+  if (version < CURRENT_STORE_SCHEMA_VERSION) migrateLegacyStoreToV1(store);
+  if (!store.roomPeerId && store.roomName) store.roomPeerId = roomToPeerId(store.roomName);
+  store.schemaVersion = CURRENT_STORE_SCHEMA_VERSION;
+  return store;
+}
+
+module.exports = {
+  CURRENT_STORE_SCHEMA_VERSION,
+  migrateStore,
+  prepareStoreForSave
+};

package/test/host-store.test.cjs

@@ -0,0 +1,277 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const test = require("node:test");
+const { activePublicInvite } = require("@mh-gg/room-security");
+const { CURRENT_STORE_SCHEMA_VERSION, attachDataDir, ensureOperationSigningKey, operationKeyPin, operationPublicKeyHash, loadStore, saveStore, stateFile, touchState } = require("..");
+
+const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "matterhorn-host-store-"));
+
+test.after(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+function args(roomName) {
+  return {
+    room: roomName,
+    title: "Store Test",
+    date: "2026-06-20",
+    time: "8:00 PM",
+    location: "Test Venue",
+    description: "",
+    roomSecret: "store-secret",
+    dataDir: fs.mkdtempSync(path.join(tmpRoot, "room-")),
+    theme: "sunset"
+  };
+}
+
+function captureWarnings(callback) {
+  const warnings = [];
+  const previousWarn = console.warn;
+  console.warn = (message) => warnings.push(message);
+  try {
+    return {
+      value: callback(),
+      warnings
+    };
+  } finally {
+    console.warn = previousWarn;
+  }
+}
+
+function legacyStore(config, overrides = {}) {
+  return {
+    roomName: config.room,
+    roomSecret: "saved-bootstrap-secret",
+    admins: {},
+    seenMutations: [],
+    state: {
+      version: 0,
+      updatedAt: 0,
+      details: {
+        id: `event_${config.room}`,
+        roomName: config.room,
+        title: "Credential Bootstrap Store Test",
+        date: "2026-06-20",
+        time: "8:00 PM",
+        location: "Test Venue",
+        description: "",
+        coverEmoji: "*",
+        dressCode: "",
+        hostNote: "",
+        theme: "sunset"
+      },
+      guests: {},
+      posts: [],
+      comments: [],
+      adminIds: []
+    },
+    ...overrides
+  };
+}
+
+function writeStore(config, store) {
+  fs.mkdirSync(config.dataDir, { recursive: true });
+  fs.writeFileSync(stateFile(config.dataDir, config.room), JSON.stringify(store, null, 2));
+}
+
+function writeUnsecuredStore(config) {
+  writeStore(config, legacyStore(config));
+}
+
+function assertPrivatePathModes(dir, file) {
+  if (process.platform === "win32") return;
+  assert.equal(fs.statSync(dir).mode & 0o777, 0o700);
+  assert.equal(fs.statSync(file).mode & 0o777, 0o600);
+}
+
+test("creates and persists secured room stores", () => {
+  const config = args("store-room");
+  const store = loadStore(config);
+  const file = stateFile(config.dataDir, config.room);
+  const saved = JSON.parse(fs.readFileSync(file, "utf8"));
+
+  assert.equal(fs.existsSync(file), true);
+  assertPrivatePathModes(config.dataDir, file);
+  assert.equal(fs.readdirSync(config.dataDir).some((name) => name.endsWith(".tmp")), false);
+  assert.equal(store.schemaVersion, CURRENT_STORE_SCHEMA_VERSION);
+  assert.equal(saved.schemaVersion, CURRENT_STORE_SCHEMA_VERSION);
+  assert.equal(store.roomPeerId, "matterhorn-store-room");
+  assert.equal(store.roomSecret, "store-secret");
+  assert.equal(saved.dataDir, undefined);
+  assert.equal(typeof activePublicInvite(store).id, "string");
+  assert.equal(typeof store.adminBootstrapToken, "string");
+  assert.equal(typeof saved.adminBootstrap.tokenHash, "string");
+  assert.equal(saved.adminBootstrapToken, undefined);
+  const firstBootstrapHash = store.adminBootstrap.tokenHash;
+
+  store.state.details.title = "Changed Store Test";
+  saveStore(store);
+  assertPrivatePathModes(config.dataDir, file);
+  assert.equal(fs.readdirSync(config.dataDir).some((name) => name.endsWith(".tmp")), false);
+  const reloaded = loadStore({ ...config, roomSecret: "" });
+  assert.equal(reloaded.schemaVersion, CURRENT_STORE_SCHEMA_VERSION);
+  assert.equal(reloaded.state.details.title, "Changed Store Test");
+  assert.equal(typeof reloaded.adminBootstrapToken, "string");
+  assert.notEqual(reloaded.adminBootstrap.tokenHash, firstBootstrapHash);
+});
+
+test("migrates legacy stores and preserves security fields", () => {
+  const config = args("legacy-secured-store-room");
+  const sharedSecret = "legacy-shared-secret";
+  writeStore(config, legacyStore(config, {
+    roomPeerId: "matterhorn-legacy-secured-store-room",
+    roomSecret: sharedSecret,
+    relayAddress: "peerjs:legacy-relay",
+    admins: {
+      admin: { tokenHash: "legacy-admin-hash", grantedAt: 10 }
+    },
+    adminBootstrap: {
+      tokenHash: "legacy-bootstrap-hash",
+      createdAt: 11
+    },
+    members: {
+      member_admin: {
+        id: "member_admin",
+        profileId: "admin",
+        role: "admin",
+        secret: "legacy-member-secret",
+        createdAt: 12,
+        lastSeenAt: 13
+      }
+    },
+    publicInvites: [{
+      id: "invite_legacy",
+      type: "public",
+      status: "active",
+      secret: sharedSecret,
+      createdAt: 14
+    }],
+    keyEpochs: [{
+      id: "epoch_legacy",
+      secret: sharedSecret,
+      createdAt: 15
+    }],
+    state: {
+      ...legacyStore(config).state,
+      adminIds: ["admin"],
+      guests: {
+        admin: {
+          id: "admin",
+          memberId: "member_admin",
+          name: "Admin",
+          avatar: "*",
+          rsvp: "yes",
+          role: "admin",
+          joinedAt: 12,
+          lastSeenAt: 13
+        }
+      }
+    }
+  }));
+
+  const store = loadStore(config);
+  assert.equal(store.schemaVersion, CURRENT_STORE_SCHEMA_VERSION);
+  assert.equal(store.relayAddress, "peerjs:legacy-relay");
+  assert.equal(store.admins.admin.tokenHash, "legacy-admin-hash");
+  assert.equal(store.adminBootstrap.tokenHash, "legacy-bootstrap-hash");
+  assert.equal(store.members.member_admin.role, "admin");
+  assert.equal(store.members.member_admin.secret, undefined);
+  assert.equal(typeof store.members.member_admin.secretHash, "string");
+  assert.equal(activePublicInvite(store).id, "invite_legacy");
+  assert.notEqual(store.keyEpochs[0].id, "epoch_legacy");
+  assert.equal(typeof store.keyEpochs[0].epochKey, "string");
+  assert.equal(store.security?.legacySharedInviteKey, undefined);
+
+  saveStore(store);
+  const saved = JSON.parse(fs.readFileSync(stateFile(config.dataDir, config.room), "utf8"));
+  assert.equal(saved.schemaVersion, CURRENT_STORE_SCHEMA_VERSION);
+  assert.equal(saved.relayAddress, "peerjs:legacy-relay");
+  assert.equal(saved.admins.admin.tokenHash, "legacy-admin-hash");
+});
+
+test("rejects future store schema versions", () => {
+  const config = args("future-store-room");
+  writeStore(config, legacyStore(config, { schemaVersion: CURRENT_STORE_SCHEMA_VERSION + 1 }));
+
+  assert.throws(
+    () => loadStore(config),
+    /Unsupported room store schema version/
+  );
+});
+
+test("rejects invalid store schema versions", () => {
+  const config = args("invalid-schema-store-room");
+  writeStore(config, legacyStore(config, { schemaVersion: "1" }));
+
+  assert.throws(
+    () => loadStore(config),
+    /Unsupported room store schema version/
+  );
+});
+
+test("saveStore upgrades in-memory legacy stores", () => {
+  const config = args("save-legacy-store-room");
+  const store = attachDataDir(legacyStore(config), config.dataDir);
+  saveStore(store);
+
+  const saved = JSON.parse(fs.readFileSync(stateFile(config.dataDir, config.room), "utf8"));
+  assert.equal(saved.schemaVersion, CURRENT_STORE_SCHEMA_VERSION);
+  assert.equal(saved.roomPeerId, "matterhorn-save-legacy-store-room");
+});
+
+test("ignores CLI secret overrides for stores with membership credentials", () => {
+  const config = args("modern-store-room");
+  loadStore(config);
+  const { value: store, warnings } = captureWarnings(() => loadStore({ ...config, roomSecret: "override-secret" }));
+
+  assert.equal(store.roomSecret, "store-secret");
+  assert.deepEqual(warnings, ["Ignoring ROOM_SECRET/--secret because this room already has membership credentials."]);
+});
+
+test("applies CLI secret overrides for stores without membership credentials", () => {
+  const config = args("credential-bootstrap-store-room");
+  writeUnsecuredStore(config);
+  const { value: store, warnings } = captureWarnings(() => loadStore({ ...config, roomSecret: "override-secret" }));
+
+  assert.equal(store.schemaVersion, CURRENT_STORE_SCHEMA_VERSION);
+  assert.equal(store.roomSecret, "override-secret");
+  assert.equal(activePublicInvite(store).secret, "override-secret");
+  assert.deepEqual(warnings, ["Using ROOM_SECRET/--secret from CLI because this room has no membership credentials yet."]);
+});
+
+test("touchState updates version, timestamp, and persisted file", () => {
+  const config = args("touch-store-room");
+  const store = loadStore(config);
+  touchState(store, 12345);
+
+  const saved = JSON.parse(fs.readFileSync(stateFile(config.dataDir, config.room), "utf8"));
+  assert.equal(saved.state.version, 1);
+  assert.equal(saved.state.updatedAt, 12345);
+});
+
+test("operation signing keys are generated once and persisted", () => {
+  const config = args("operation-signing-store-room");
+  const store = loadStore(config);
+
+  const key = ensureOperationSigningKey(store);
+  const savedAgain = ensureOperationSigningKey(store);
+  saveStore(store);
+  const reloaded = loadStore({ ...config, roomSecret: "" });
+
+  assert.equal(key.id.startsWith("host_"), true);
+  assert.equal(key.alg, "ed25519");
+  assert.equal(key.publicKeyPem.includes("PUBLIC KEY"), true);
+  assert.equal(key.privateKeyPem.includes("PRIVATE KEY"), true);
+  assert.equal(savedAgain.id, key.id);
+  assert.deepEqual(ensureOperationSigningKey(reloaded), key);
+
+  const pin = operationKeyPin(key);
+  assert.deepEqual(pin, {
+    alg: "ed25519",
+    signer: key.id,
+    publicKeyHash: operationPublicKeyHash(key.publicKeyPem)
+  });
+  assert.equal(pin.publicKeyHash.startsWith("sha256-"), true);
+});