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

package/src/security/scopedRoles/stateOps.cjs

@@ -0,0 +1,167 @@
+const { runtimeError } = require("../../errors.cjs");
+const {
+  boundedString,
+  normalizeRoleGrant,
+  normalizeScopedRole,
+  normalizeScopedRolesState,
+  optionalBoundedString,
+  scopedRoleFromGlobalRole,
+  scopedRoleRank,
+  scopeKey
+} = require("./normalize.cjs");
+const { SCOPED_ROLES_STATE_VERSION } = require("./constants.cjs");
+const { grantMetadata, revocationMetadata } = require("./metadata.cjs");
+
+function parseScopeRoleSetPayload(operation) {
+  const payload = operation.payload || {};
+  const target = optionalBoundedString(payload.target, "target", 240);
+  const role = normalizeScopedRole(payload.role, undefined);
+  const defaultRole = normalizeScopedRole(payload.defaultRole, undefined);
+  if (target && !role) throw runtimeError("SCHEMA_INVALID", "scope.role.set role is invalid");
+  if (!target && !defaultRole) throw runtimeError("SCHEMA_INVALID", "scope.role.set requires target+role or defaultRole");
+  return {
+    scopeType: boundedString(payload.scopeType, "scopeType", 80),
+    scopeId: boundedString(payload.scopeId, "scopeId", 180),
+    ...(target ? { target, role } : {}),
+    ...(defaultRole ? { defaultRole } : {}),
+    ...(optionalBoundedString(payload.reason, "reason", 500) ? { reason: payload.reason.trim().slice(0, 500) } : {})
+  };
+}
+
+function parseAccessRoleDefinePayload(operation) {
+  const payload = operation.payload || {};
+  const roleId = boundedString(payload.roleId || payload.id, "roleId", 120);
+  const grantsInput = Array.isArray(payload.grants) ? payload.grants : [];
+  if (grantsInput.length === 0) throw runtimeError("SCHEMA_INVALID", "access.role.define requires at least one grant");
+  return {
+    roleId,
+    name: optionalBoundedString(payload.name, "name", 120) || roleId,
+    grants: grantsInput.map((grant, index) => {
+      const parsed = normalizeRoleGrant(grant, index);
+      if (!parsed) throw runtimeError("SCHEMA_INVALID", `grants[${index}] is invalid`);
+      return parsed;
+    }),
+    ...(optionalBoundedString(payload.reason, "reason", 500) ? { reason: payload.reason.trim().slice(0, 500) } : {})
+  };
+}
+
+function parseAccessRoleAssignmentPayload(operation) {
+  const payload = operation.payload || {};
+  return {
+    target: boundedString(payload.target, "target", 240),
+    roleId: boundedString(payload.roleId || payload.id, "roleId", 120),
+    ...(optionalBoundedString(payload.reason, "reason", 500) ? { reason: payload.reason.trim().slice(0, 500) } : {})
+  };
+}
+
+function nextScopedRolesState(currentState, payload, actor = {}, updatedAt = Date.now(), operation) {
+  const state = normalizeScopedRolesState(currentState);
+  const key = scopeKey(payload.scopeType, payload.scopeId);
+  const current = state.scopes[key] || { scopeType: payload.scopeType, scopeId: payload.scopeId, defaultRole: "editor", roles: {} };
+  const roles = { ...(current.roles || {}) };
+  if (payload.target) roles[payload.target] = payload.role;
+  const grant = grantMetadata(operation, actor, payload, updatedAt, "scope.role.set");
+  const grants = grant ? { ...state.grants, [grant.id]: grant } : state.grants;
+  return {
+    version: SCOPED_ROLES_STATE_VERSION,
+    roles: state.roles,
+    assignments: state.assignments,
+    assignmentGrants: state.assignmentGrants,
+    grants,
+    revocations: state.revocations,
+    scopes: {
+      ...state.scopes,
+      [key]: {
+        ...current,
+        ...(payload.defaultRole ? { defaultRole: payload.defaultRole } : {}),
+        roles,
+        updatedAt,
+        updatedBy: actor.memberId
+      }
+    }
+  };
+}
+
+function nextCompoundRoleState(currentState, payload, actor = {}, updatedAt = Date.now(), operation) {
+  const state = normalizeScopedRolesState(currentState);
+  const grant = grantMetadata(operation, actor, payload, updatedAt, "access.role.define");
+  return {
+    ...state,
+    grants: grant ? { ...state.grants, [grant.id]: grant } : state.grants,
+    roles: {
+      ...state.roles,
+      [payload.roleId]: {
+        id: payload.roleId,
+        name: payload.name,
+        grants: payload.grants,
+        ...(grant ? { authority: grant } : {}),
+        updatedAt,
+        updatedBy: actor.memberId
+      }
+    }
+  };
+}
+
+function nextRoleAssignmentState(currentState, payload, assigned, actor = {}, updatedAt = Date.now(), operation) {
+  const state = normalizeScopedRolesState(currentState);
+  if (!state.roles[payload.roleId]) throw runtimeError("SCHEMA_INVALID", `Compound role ${payload.roleId} is not defined`);
+  const current = new Set(state.assignments[payload.target] || []);
+  if (assigned) current.add(payload.roleId);
+  else current.delete(payload.roleId);
+  const assignments = { ...state.assignments };
+  if (current.size) assignments[payload.target] = [...current].sort();
+  else delete assignments[payload.target];
+  const assignmentGrants = {
+    ...state.assignmentGrants,
+    [payload.target]: { ...(state.assignmentGrants[payload.target] || {}) }
+  };
+  const grants = { ...state.grants };
+  const revocations = { ...state.revocations };
+  if (assigned) {
+    const grant = grantMetadata(operation, actor, payload, updatedAt, "access.role.assign");
+    if (grant) {
+      grants[grant.id] = grant;
+      assignmentGrants[payload.target][payload.roleId] = grant.id;
+    }
+  } else {
+    const priorGrantId = assignmentGrants[payload.target][payload.roleId];
+    delete assignmentGrants[payload.target][payload.roleId];
+    if (Object.keys(assignmentGrants[payload.target]).length === 0) delete assignmentGrants[payload.target];
+    const revocation = revocationMetadata(operation, actor, payload, updatedAt, priorGrantId ? [priorGrantId] : []);
+    if (revocation) revocations[revocation.id] = revocation;
+  }
+  return { ...state, assignments, assignmentGrants, grants, revocations, updatedAt, updatedBy: actor.memberId };
+}
+
+function applyScopeRoleSetToRoomState(roomState, payload, actor, updatedAt, operation) {
+  return { ...roomState, scopedRoles: nextScopedRolesState(roomState?.scopedRoles, payload, actor, updatedAt, operation) };
+}
+
+function applyAccessRoleDefineToRoomState(roomState, payload, actor, updatedAt, operation) {
+  return { ...roomState, scopedRoles: nextCompoundRoleState(roomState?.scopedRoles, payload, actor, updatedAt, operation) };
+}
+
+function applyAccessRoleAssignmentToRoomState(roomState, payload, assigned, actor, updatedAt, operation) {
+  return { ...roomState, scopedRoles: nextRoleAssignmentState(roomState?.scopedRoles, payload, assigned, actor, updatedAt, operation) };
+}
+
+function assertScopedRoleManagerCanApply(actor, payload) {
+  if (scopedRoleRank(scopedRoleFromGlobalRole(actor?.role)) >= scopedRoleRank("admin")) return;
+  if (scopedRoleRank(scopedRoleFromGlobalRole(actor?.role)) < scopedRoleRank("moderator")) throw runtimeError("FORBIDDEN", "Scoped roles require moderator authority");
+  if ((payload.grants || []).some((grant) => scopedRoleRank(grant.role) > scopedRoleRank("moderator"))) {
+    throw runtimeError("FORBIDDEN", "Moderators cannot define scoped roles above moderator");
+  }
+}
+
+module.exports = {
+  applyAccessRoleAssignmentToRoomState,
+  applyAccessRoleDefineToRoomState,
+  applyScopeRoleSetToRoomState,
+  assertScopedRoleManagerCanApply,
+  nextCompoundRoleState,
+  nextRoleAssignmentState,
+  nextScopedRolesState,
+  parseAccessRoleAssignmentPayload,
+  parseAccessRoleDefinePayload,
+  parseScopeRoleSetPayload
+};

package/src/security/scopedRoles.cjs

@@ -0,0 +1,7 @@
+module.exports = {
+  ...require("./scopedRoles/constants.cjs"),
+  ...require("./scopedRoles/normalize.cjs"),
+  ...require("./scopedRoles/access.cjs"),
+  ...require("./scopedRoles/stateOps.cjs"),
+  ...require("./scopedRoles/publicView.cjs")
+};

package/src/security/standingAuthority.cjs

@@ -0,0 +1,76 @@
+const { effectiveRoleFor, normalizeRoomRole } = require("./roles.cjs");
+const { authorityEnabled, roleFromAuthority } = require("@mh-gg/authority");
+
+function asRevokedSet(value) {
+  if (!value) return new Set();
+  if (Array.isArray(value)) return new Set(value.filter((item) => typeof item === "string" && item.length > 0));
+  if (value instanceof Set) return new Set([...value].filter((item) => typeof item === "string" && item.length > 0));
+  if (typeof value === "object") return new Set(Object.entries(value).filter(([, enabled]) => Boolean(enabled)).map(([id]) => id));
+  return new Set();
+}
+
+function findGuest(roomState, memberId) {
+  const guests = roomState?.guests;
+  if (!guests || typeof guests !== "object") return undefined;
+  if (guests[memberId]) return guests[memberId];
+  return Object.values(guests).find((guest) => guest?.id === memberId || guest?.memberId === memberId);
+}
+
+function hasMembershipRecords(roomState) {
+  const members = Object.values(roomState?.members || {});
+  return members.some((member) => member?.profileOnly !== true) || Object.keys(roomState?.guests || {}).length > 0;
+}
+
+function evaluateRoomStateStanding({ memberId, deviceId, credentialId, actor, roomState, strict = false } = {}) {
+  const id = memberId || actor?.memberId;
+  if (typeof id !== "string" || id.length === 0) return { standing: "unknown", role: "guest" };
+
+  const revoked = asRevokedSet(roomState?.revokedCredentialIds);
+  if (credentialId && revoked.has(credentialId)) return { standing: "revoked", role: normalizeRoomRole(actor?.role) };
+
+  const member = roomState?.members?.[id];
+  const guest = findGuest(roomState, id);
+  if (member?.bannedAt || guest?.bannedAt) return { standing: "banned", role: normalizeRoomRole(member?.role || guest?.role || actor?.role) };
+
+  if (authorityEnabled(roomState)) {
+    const authorityRole = roleFromAuthority(roomState.authority, id);
+    if (!authorityRole) return { standing: "unknown", role: "guest", member, guest, deviceId };
+    return { standing: "active", role: authorityRole, member, guest, deviceId, authority: roomState.authority };
+  }
+
+  if (!member && !guest) {
+    if (strict || hasMembershipRecords(roomState)) return { standing: "unknown", role: "guest" };
+    return { standing: "active", role: normalizeRoomRole(actor?.role || "guest") };
+  }
+
+  const stateRole = normalizeRoomRole(member?.role || guest?.role || actor?.role || "guest");
+  return { standing: "active", role: stateRole, member, guest, deviceId };
+}
+
+function createRoomStateStandingAuthority(options = {}) {
+  const strict = options.strict === true;
+  return {
+    evaluate(input = {}) {
+      return evaluateRoomStateStanding({ ...input, strict: input.strict ?? strict });
+    }
+  };
+}
+
+function actorWithStanding(actor = {}, standing = {}) {
+  const stateRole = standing.role;
+  const keyRole = actor.keyRole || actor.role;
+  const role = effectiveRoleFor({ keyRole, stateRole, actorRole: actor.role });
+  return Object.freeze({
+    ...actor,
+    role,
+    keyRole,
+    standing: standing.standing || "unknown"
+  });
+}
+
+module.exports = {
+  actorWithStanding,
+  asRevokedSet,
+  createRoomStateStandingAuthority,
+  evaluateRoomStateStanding
+};

package/src/shared.cjs

@@ -0,0 +1,14 @@
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function rememberBounded(list, id, max) {
+  const next = Array.isArray(list) ? [...list, id] : [id];
+  return next.slice(-max);
+}
+
+function pruneMap(map, max) {
+  while (map.size > max) map.delete(map.keys().next().value);
+}
+
+module.exports = { clone, pruneMap, rememberBounded };

package/src/state.cjs

@@ -0,0 +1,54 @@
+const { ROOM_STATE_SCHEMA_VERSION } = require("./constants.cjs");
+const { runtimeError, MatterhornRuntimeError } = require("./errors.cjs");
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw runtimeError("ROOM_STATE_INVALID", `${name} must be an object`);
+  return value;
+}
+
+function assertString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw runtimeError("ROOM_STATE_INVALID", `${name} must be a non-empty string`);
+  return value;
+}
+
+function assertNumber(value, name) {
+  if (!Number.isFinite(value)) throw runtimeError("ROOM_STATE_INVALID", `${name} must be a finite number`);
+  return value;
+}
+
+function parseRoomState(value) {
+  const state = assertPlainObject(value, "room state");
+  if (state.schemaVersion !== ROOM_STATE_SCHEMA_VERSION) throw runtimeError("ROOM_STATE_INVALID", `room state schemaVersion must be ${ROOM_STATE_SCHEMA_VERSION}`);
+  assertString(state.roomId, "room state roomId");
+  const appPack = assertPlainObject(state.appPack, "room state appPack");
+  assertString(appPack.id, "room state appPack.id");
+  assertString(appPack.hash, "room state appPack.hash");
+  if (appPack.protocolHash !== undefined) assertString(appPack.protocolHash, "room state appPack.protocolHash");
+  if (!Number.isInteger(state.version) || state.version < 0) throw runtimeError("ROOM_STATE_INVALID", "room state version must be a non-negative integer");
+  assertNumber(state.createdAt, "room state createdAt");
+  assertNumber(state.updatedAt, "room state updatedAt");
+  assertPlainObject(state.members, "room state members");
+  assertPlainObject(state.pluginVersions, "room state pluginVersions");
+  assertPlainObject(state.plugins, "room state plugins");
+  if (!Array.isArray(state.seenOperations)) throw runtimeError("ROOM_STATE_INVALID", "room state seenOperations must be an array");
+  for (const [index, operationId] of state.seenOperations.entries()) assertString(operationId, `room state seenOperations[${index}]`);
+  return state;
+}
+
+const RoomStateSchema = { parse: parseRoomState };
+
+function parseWithSchema(schema, value, name) {
+  if (!schema || typeof schema.parse !== "function") throw runtimeError("SCHEMA_MISSING", `${name} schema is missing`);
+  try {
+    return schema.parse(value);
+  } catch (error) {
+    if (error instanceof MatterhornRuntimeError) throw error;
+    throw runtimeError("SCHEMA_INVALID", `${name} did not validate: ${error?.message || error}`);
+  }
+}
+
+module.exports = {
+  RoomStateSchema,
+  parseRoomState,
+  parseWithSchema
+};

package/test/authority-ordering-hardening.test.cjs

@@ -0,0 +1,101 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const test = require("node:test");
+
+const {
+  adminIdsFromDerivedRoles,
+  applyAuthorityProjection,
+  createAuthorityState,
+  grantRecordMap,
+  grantsMatchingRevocation,
+  sortOperations
+} = require("../src/index.cjs");
+const { ensureOperationIdentity, formatHlc, validateRoomOperation } = require("@mh-gg/protocol");
+
+function op({ memberId = "alice", pluginId = "matterhorn.core", type = "authority.grant", payload = { target: "bob", role: "admin" }, hlc, createdAt = 1000, id } = {}) {
+  const operation = {
+    ...(id ? { id } : {}),
+    roomId: "room",
+    appPackId: "app",
+    appPackHash: "sha256-app",
+    pluginId,
+    type,
+    actor: { memberId, deviceId: `dev_${memberId}`, role: "admin" },
+    seq: 1,
+    createdAt,
+    hlc,
+    payload,
+    auth: { credentialId: `${memberId}_cred`, signature: "sig" }
+  };
+  return id ? operation : ensureOperationIdentity(operation, { now: createdAt, nodeId: `dev_${memberId}` });
+}
+
+test("authority ordering uses HLC then bytewise content id, never createdAt or locale", () => {
+  const commonHlc = formatHlc({ physical: 1000, logical: 0, nodeId: "dev" });
+  const earlierHlc = formatHlc({ physical: 999, logical: 0, nodeId: "dev" });
+  const lateClock = { id: "a", hlc: commonHlc, createdAt: 1 };
+  const earlyClock = { id: "b", hlc: commonHlc, createdAt: 999999 };
+  const causalFirst = { id: "z", hlc: earlierHlc, createdAt: 999999999 };
+
+  const ordered = sortOperations([earlyClock, lateClock, causalFirst]);
+  assert.deepEqual(ordered.map((entry) => entry.id), ["z", "a", "b"]);
+
+  const oldLocale = process.env.LC_ALL;
+  process.env.LC_ALL = "tr_TR.UTF-8";
+  try {
+    assert.deepEqual(sortOperations([lateClock, causalFirst, earlyClock]).map((entry) => entry.id), ["z", "a", "b"]);
+  } finally {
+    if (oldLocale === undefined) delete process.env.LC_ALL;
+    else process.env.LC_ALL = oldLocale;
+  }
+
+  const orderingSource = fs.readFileSync(path.join(__dirname, "../../authority/src/ordering.cjs"), "utf8");
+  assert.equal(orderingSource.includes("localeCompare"), false);
+});
+
+test("content hash operation ids are required on room operations", () => {
+  const signed = op({ hlc: formatHlc({ physical: 1000, logical: 0, nodeId: "dev_alice" }) });
+  validateRoomOperation(signed, { now: 1000 });
+  assert.throws(() => validateRoomOperation({ ...signed, id: "sha256:attacker" }, { now: 1000 }), /operation.id/);
+});
+
+test("from-point authority revocation uses HLC, not signer-controlled createdAt", () => {
+  const beforeHlc = formatHlc({ physical: 1000, logical: 0, nodeId: "alice" });
+  const cutHlc = formatHlc({ physical: 1001, logical: 0, nodeId: "alice" });
+  const afterHlc = formatHlc({ physical: 1002, logical: 0, nodeId: "alice" });
+  const grantsById = new Map([
+    ["grant_backdated_but_after", { id: "grant_backdated_but_after", granter: "alice", target: "bob", role: "admin", createdAt: 1, hlc: afterHlc }],
+    ["grant_future_dated_but_before", { id: "grant_future_dated_but_before", granter: "alice", target: "carol", role: "admin", createdAt: 999999, hlc: beforeHlc }]
+  ]);
+
+  const matches = grantsMatchingRevocation({ target: "alice", scope: "from-point", voidFrom: cutHlc }, grantsById).map((grant) => grant.id);
+  assert.deepEqual(matches, ["grant_backdated_but_after"]);
+});
+
+test("adminIds is a derived projection of the authority chain", () => {
+  const authority = createAuthorityState({
+    ownerIds: ["olivia"],
+    grants: [
+      { id: "grant_alice_admin", granter: "olivia", target: "alice", role: "admin", hlc: formatHlc({ physical: 1, logical: 0, nodeId: "olivia" }) },
+      { id: "grant_bob_member", granter: "olivia", target: "bob", role: "member", hlc: formatHlc({ physical: 2, logical: 0, nodeId: "olivia" }) }
+    ]
+  });
+  const projected = applyAuthorityProjection(authority, {
+    olivia: { id: "olivia", role: "member", profileOnly: true, displayName: "Olivia" },
+    stale: { id: "stale", role: "admin" }
+  });
+  assert.deepEqual(adminIdsFromDerivedRoles(projected.authority.derivedRoles), ["alice", "olivia"]);
+  assert.deepEqual(projected.adminIds, ["alice", "olivia"]);
+  assert.equal(projected.members.olivia.profileOnly, undefined);
+  assert.equal(projected.members.olivia.displayName, "Olivia");
+  assert.equal(projected.members.stale.role, "member");
+});
+
+test("operation id tiebreak is deterministic for genuinely concurrent operations", () => {
+  const sharedHlc = formatHlc({ physical: 2000, logical: 0, nodeId: "dev" });
+  const left = op({ hlc: sharedHlc, payload: { target: "bob", role: "admin" }, createdAt: 2000 });
+  const right = op({ hlc: sharedHlc, payload: { target: "carol", role: "admin" }, createdAt: 1 });
+  const expected = [left, right].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0).map((entry) => entry.id);
+  assert.deepEqual(sortOperations([right, left]).map((entry) => entry.id), expected);
+});