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

package/src/security/roleKeys/signatures.cjs

@@ -0,0 +1,126 @@
+const crypto = require("node:crypto");
+const { clone } = require("../../shared.cjs");
+const { OPERATION_ROLE_KEY_PROOF_KIND, OPERATION_ROLE_KEY_VERSION, ROLE_ALG } = require("./constants.cjs");
+const { canonicalJson } = require("@mh-gg/event/canonicalJson");
+const { ensureOperationIdentity } = require("@mh-gg/protocol");
+const { ensureText, grantArray, isOperationRoleKeyGrant, publicOperationRoleKeyGrant } = require("./grants.cjs");
+const { verifyOperationRoleKeyGrant } = require("./authorities/index.cjs");
+const { normalizeOperationKeyRole, operationKeyRoleToActorRole } = require("./roles.cjs");
+
+function unsignedOperationForRoleKey(operation) {
+  const next = clone(operation);
+  if (!next.auth || typeof next.auth !== "object") next.auth = {};
+  delete next.ledgerId;
+  delete next.snowflakeId;
+  delete next.committedRoomVersion;
+  delete next.committedAt;
+  delete next.receivedAt;
+  delete next.relayId;
+  delete next.auth.signature;
+  delete next.auth.eventId;
+  delete next.auth.signatureEventId;
+  delete next.auth.signedAt;
+  return next;
+}
+
+function operationPayloadForRoleKey(operation) {
+  return Buffer.from(canonicalJson(unsignedOperationForRoleKey(operation)));
+}
+
+function signOperationWithRoleKey(operation, options = {}) {
+  const grant = options.grant;
+  if (!isOperationRoleKeyGrant(grant)) throw new Error("A valid operation role-key grant is required");
+  const privateKeyPem = ensureText(options.privateKeyPem || options.privateKey, "privateKeyPem");
+  const next = clone(operation);
+  next.auth = {
+    ...(next.auth || {}),
+    kind: OPERATION_ROLE_KEY_PROOF_KIND,
+    version: OPERATION_ROLE_KEY_VERSION,
+    alg: ROLE_ALG,
+    credentialId: grant.credentialId,
+    keyRole: grant.role,
+    publicKeyFingerprint: grant.publicKeyFingerprint,
+    issuedAt: Number.isFinite(options.issuedAt) ? options.issuedAt : (typeof options.now === "function" ? options.now() : Date.now())
+  };
+  delete next.auth.signature;
+  delete next.auth.eventId;
+  delete next.auth.signatureEventId;
+  delete next.auth.signedAt;
+  const withIdentity = ensureOperationIdentity(next, {
+    nodeId: next.actor?.deviceId || next.actor?.memberId || grant.deviceId || grant.memberId || "role-key",
+    now: Number.isFinite(options.issuedAt) ? options.issuedAt : (typeof options.now === "function" ? options.now() : Date.now()),
+    lastSeenHlc: options.lastSeenHlc
+  });
+  withIdentity.auth.signature = crypto.sign(null, operationPayloadForRoleKey(withIdentity), privateKeyPem).toString("base64url");
+  return withIdentity;
+}
+
+function findGrantForOperation(operation, grants) {
+  const auth = operation?.auth || {};
+  return grantArray(grants).find((grant) => {
+    if (!isOperationRoleKeyGrant(grant)) return false;
+    if (auth.credentialId && grant.credentialId === auth.credentialId) return true;
+    if (auth.publicKeyFingerprint && grant.publicKeyFingerprint === auth.publicKeyFingerprint) return true;
+    return false;
+  });
+}
+
+function grantAllowsOperation(grant, operation, options = {}) {
+  const auth = operation.auth || {};
+  if (!isOperationRoleKeyGrant(grant, options)) return "Operation role key grant is invalid.";
+  if (auth.kind !== undefined && auth.kind !== OPERATION_ROLE_KEY_PROOF_KIND) return "Operation role-key proof kind is invalid.";
+  if (auth.version !== undefined && auth.version !== OPERATION_ROLE_KEY_VERSION) return "Operation role-key proof version is invalid.";
+  if (auth.alg !== undefined && auth.alg !== ROLE_ALG) return "Operation role-key proof algorithm is invalid.";
+  if (auth.keyRole !== undefined && normalizeOperationKeyRole(auth.keyRole) !== grant.role) return "Operation role-key role mismatch.";
+  if (auth.publicKeyFingerprint !== undefined && auth.publicKeyFingerprint !== grant.publicKeyFingerprint) return "Operation role-key fingerprint mismatch.";
+  if (operation.roomId !== grant.roomId) return "Operation role key is for a different room.";
+  if (operation.appPackId !== grant.appPackId) return "Operation role key is for a different app pack.";
+  if (grant.appPackHash && operation.appPackHash !== grant.appPackHash) return "Operation role key is for a different app pack hash.";
+  if (grant.memberId && operation.actor?.memberId !== grant.memberId) return "Operation role key member mismatch.";
+  if (grant.deviceId && operation.actor?.deviceId !== grant.deviceId) return "Operation role key device mismatch.";
+  if (grant.allowedPluginIds && !grant.allowedPluginIds.includes(operation.pluginId)) return "Operation role key is not valid for this plugin.";
+  if (grant.allowedOperations && !grant.allowedOperations.includes(operation.type)) return "Operation role key is not valid for this operation.";
+  const now = Number.isFinite(options.now) ? options.now : (typeof options.now === "function" ? options.now() : Date.now());
+  if (grant.expiresAt !== undefined && now > grant.expiresAt) return "Operation role key has expired.";
+  if (Number.isFinite(auth.issuedAt) && auth.issuedAt < grant.issuedAt) return "Operation role-key proof predates grant.";
+  return undefined;
+}
+
+function verifyOperationRoleKey(operation, grants, options = {}) {
+  if (!operation || typeof operation !== "object" || Array.isArray(operation)) return { ok: false, error: "Operation is required." };
+  if (!operation.auth || typeof operation.auth !== "object" || Array.isArray(operation.auth)) return { ok: false, error: "Operation auth is required." };
+  if (typeof operation.auth.signature !== "string" || operation.auth.signature.length === 0) return { ok: false, error: "Operation role-key signature is required." };
+  const grant = findGrantForOperation(operation, grants);
+  if (!grant) return { ok: false, error: "Operation role key is unknown." };
+  const grantVerification = verifyOperationRoleKeyGrant(grant, options.grantAuthorities || options.operationGrantAuthorities || options.authorities, options);
+  if (!grantVerification.ok) return { ok: false, error: grantVerification.error };
+  const grantError = grantAllowsOperation(grant, operation, options);
+  if (grantError) return { ok: false, error: grantError };
+  try {
+    const ok = crypto.verify(null, operationPayloadForRoleKey(operation), grant.publicKeyPem, Buffer.from(operation.auth.signature, "base64url"));
+    if (!ok) return { ok: false, error: "Operation role-key signature is invalid." };
+  } catch (error) {
+    return { ok: false, error: error?.message || "Operation role-key signature verification failed." };
+  }
+  return {
+    ok: true,
+    grant: publicOperationRoleKeyGrant(grant),
+    actor: {
+      ...(operation.actor || {}),
+      memberId: grant.memberId || operation.actor?.memberId,
+      deviceId: grant.deviceId || operation.actor?.deviceId,
+      role: operationKeyRoleToActorRole(grant.role),
+      keyRole: grant.role,
+      credentialId: grant.credentialId
+    }
+  };
+}
+
+module.exports = {
+  findGrantForOperation,
+  grantAllowsOperation,
+  operationPayloadForRoleKey,
+  signOperationWithRoleKey,
+  unsignedOperationForRoleKey,
+  verifyOperationRoleKey
+};

package/src/security/roles.cjs

@@ -0,0 +1,10 @@
+const authority = require("@mh-gg/authority");
+
+module.exports = {
+  ROLE_RANKS: authority.ROLE_RANKS,
+  effectiveRoleFor: authority.effectiveRoleFor,
+  minRoleByRank: authority.minRoleByRank,
+  normalizeRoomRole: authority.normalizeRoomRole,
+  roleMeetsRequirement: authority.roleMeetsRequirement,
+  roleRank: authority.roleRank
+};

package/src/security/roomDeviceKeys.cjs

@@ -0,0 +1,41 @@
+const { verifyRoomDeviceSignedOperation } = require("@mh-gg/protocol");
+const { runtimeError } = require("../errors.cjs");
+
+function isRoomDeviceSignedOperation(operation) {
+  return operation?.auth?.scheme === "matterhorn.device-signing.v1";
+}
+
+function actorFromRoomDeviceSignature(operation) {
+  const verification = verifyRoomDeviceSignedOperation(operation, operation?.auth?.claim);
+  if (!verification.ok) {
+    throw runtimeError("INVALID_ROOM_DEVICE_SIGNATURE", verification.error || "Room device signature is invalid");
+  }
+  const auth = verification.auth;
+  const actor = operation.actor || {};
+  return {
+    ...actor,
+    memberId: auth.memberId,
+    deviceId: auth.deviceId,
+    credentialId: auth.credentialId,
+    keyId: auth.keyId,
+    rootPublicKey: auth.rootPublicKey,
+    publicKey: auth.publicKey,
+    publicKeyFingerprint: auth.publicKeyFingerprint
+  };
+}
+
+function createRoomDeviceKeyAuthenticator() {
+  return async function authenticateRoomDeviceKey(authOrOperation, _actor, operation) {
+    const signedOperation = operation || authOrOperation;
+    if (!isRoomDeviceSignedOperation(signedOperation)) {
+      throw runtimeError("ROOM_DEVICE_SIGNATURE_REQUIRED", "Operation is not signed with a Matterhorn room-device key");
+    }
+    return actorFromRoomDeviceSignature(signedOperation);
+  };
+}
+
+module.exports = {
+  actorFromRoomDeviceSignature,
+  createRoomDeviceKeyAuthenticator,
+  isRoomDeviceSignedOperation
+};

package/src/security/scopedRoles/access.cjs

@@ -0,0 +1,123 @@
+const { runtimeError } = require("../../errors.cjs");
+const { actorWithStanding } = require("../standingAuthority.cjs");
+const {
+  normalizeScopedRole,
+  normalizeScopedRolesState,
+  optionalBoundedString,
+  scopedRoleFromGlobalRole,
+  scopedRoleMeets,
+  scopedRoleRank,
+  scopeKey
+} = require("./normalize.cjs");
+
+function grantSpecificity(grant, scopeType, scopeId) {
+  if (grant.scopeType === scopeType && grant.scopeId === scopeId) return 3;
+  if (grant.scopeType === scopeType && grant.scopeId === "*") return 2;
+  if (grant.scopeType === "*" && grant.scopeId === "*") return 1;
+  return 0;
+}
+
+function compoundRoleForActor(scopedState, actor = {}, scopeType, scopeId) {
+  const roleIds = actor.memberId ? scopedState.assignments?.[actor.memberId] || [] : [];
+  let selectedRole;
+  let selectedSpecificity = 0;
+  for (const roleId of roleIds) {
+    const compoundRole = scopedState.roles?.[roleId];
+    for (const grant of compoundRole?.grants || []) {
+      const specificity = grantSpecificity(grant, scopeType, scopeId);
+      if (specificity === 0) continue;
+      if (specificity > selectedSpecificity || (specificity === selectedSpecificity && scopedRoleRank(grant.role) > scopedRoleRank(selectedRole))) {
+        selectedRole = grant.role;
+        selectedSpecificity = specificity;
+      }
+    }
+  }
+  return selectedRole;
+}
+
+function scopedRoleForActor(roomState, actor = {}, scopeType, scopeId) {
+  if (!actor || actor.standing && actor.standing !== "active") return "none";
+  const globalRole = scopedRoleFromGlobalRole(actor.role);
+  if (scopedRoleRank(globalRole) >= scopedRoleRank("admin")) return globalRole;
+  const scopedState = normalizeScopedRolesState(roomState?.scopedRoles);
+  const entry = scopedState.scopes[scopeKey(scopeType, scopeId)];
+  const compoundRole = compoundRoleForActor(scopedState, actor, scopeType, scopeId);
+  if (!entry) return compoundRole || globalRole;
+  const explicitRole = actor.memberId ? normalizeScopedRole(entry.roles?.[actor.memberId], undefined) : undefined;
+  if (explicitRole) return explicitRole;
+  return compoundRole || normalizeScopedRole(entry.defaultRole, "none");
+}
+
+function canAccessScope(roomState, actor, scopeType, scopeId, requiredRole) {
+  return scopedRoleMeets(scopedRoleForActor(roomState, actor, scopeType, scopeId), requiredRole);
+}
+
+function canViewScope(roomState, actor, scopeType, scopeId) {
+  return canAccessScope(roomState, actor, scopeType, scopeId, "viewer");
+}
+
+function canEditScope(roomState, actor, scopeType, scopeId) {
+  return canAccessScope(roomState, actor, scopeType, scopeId, "editor");
+}
+
+function evaluateScopeValue(value, { operation, actor, roomState, plugin }) {
+  if (typeof value !== "string") return value;
+  if (value === "$app.id") return operation?.appPackId;
+  if (value === "$room.id") return roomState?.roomId || operation?.roomId;
+  if (value === "$plugin.id") return plugin?.id || operation?.pluginId;
+  if (value.startsWith("$payload.")) return operation?.payload?.[value.slice("$payload.".length)];
+  if (value.startsWith("$actor.")) return actor?.[value.slice("$actor.".length)];
+  return value;
+}
+
+function normalizeScopePolicy(policy, ctx) {
+  const scopeType = evaluateScopeValue(policy.scopeType || policy.type, ctx);
+  const scopeId = evaluateScopeValue(policy.scopeId || policy.id, ctx);
+  return {
+    scopeType: optionalBoundedString(scopeType, "scopeType", 80),
+    scopeId: optionalBoundedString(scopeId, "scopeId", 180),
+    action: policy.action === "view" ? "view" : "edit"
+  };
+}
+
+function operationScopePolicies(authorize = {}) {
+  const policy = authorize.scope || authorize.scopes;
+  if (!policy) return [];
+  return Array.isArray(policy) ? policy : [policy];
+}
+
+function assertOperationScopeAccess({ roomState, actor, operation, plugin, authorize = {}, operationLabel }) {
+  const ctx = { roomState, actor, operation, plugin };
+  for (const rawPolicy of operationScopePolicies(authorize)) {
+    const policy = normalizeScopePolicy(rawPolicy || {}, ctx);
+    if (!policy.scopeType || !policy.scopeId) {
+      throw runtimeError("FORBIDDEN", `${operationLabel || `${plugin.id}.${operation.type}`} requires scoped ${policy.action} access`);
+    }
+    const requiredRole = policy.action === "view" ? "viewer" : "editor";
+    if (!canAccessScope(roomState, actor, policy.scopeType, policy.scopeId, requiredRole)) {
+      throw runtimeError("FORBIDDEN", `${operationLabel || `${plugin.id}.${operation.type}`} requires ${policy.action} access to ${policy.scopeType}:${policy.scopeId}`);
+    }
+  }
+}
+
+async function effectiveActorForRoom(runtime, { actor = {}, state, operation } = {}) {
+  const standing = await runtime.standingAuthority.evaluate({
+    memberId: actor?.memberId || operation?.actor?.memberId,
+    deviceId: actor?.deviceId || operation?.actor?.deviceId,
+    credentialId: actor?.credentialId || operation?.auth?.credentialId,
+    actor,
+    operation,
+    roomState: state,
+    now: operation?.createdAt || runtime.now()
+  });
+  return actorWithStanding({ ...(operation?.actor || {}), ...actor, credentialId: actor?.credentialId || operation?.auth?.credentialId }, standing);
+}
+
+module.exports = {
+  assertOperationScopeAccess,
+  canAccessScope,
+  canEditScope,
+  canViewScope,
+  effectiveActorForRoom,
+  scopedRoleForActor
+};

package/src/security/scopedRoles/constants.cjs

@@ -0,0 +1,23 @@
+const CORE_SCOPE_ROLE_SET_TYPE = "scope.role.set";
+const CORE_ACCESS_ROLE_DEFINE_TYPE = "access.role.define";
+const CORE_ACCESS_ROLE_ASSIGN_TYPE = "access.role.assign";
+const CORE_ACCESS_ROLE_UNASSIGN_TYPE = "access.role.unassign";
+const SCOPED_ROLES_STATE_VERSION = 1;
+
+const SCOPED_ROLE_RANKS = Object.freeze({
+  none: -1,
+  viewer: 0,
+  editor: 1,
+  moderator: 2,
+  admin: 3,
+  owner: 4
+});
+
+module.exports = {
+  CORE_ACCESS_ROLE_ASSIGN_TYPE,
+  CORE_ACCESS_ROLE_DEFINE_TYPE,
+  CORE_ACCESS_ROLE_UNASSIGN_TYPE,
+  CORE_SCOPE_ROLE_SET_TYPE,
+  SCOPED_ROLE_RANKS,
+  SCOPED_ROLES_STATE_VERSION
+};

package/src/security/scopedRoles/metadata.cjs

@@ -0,0 +1,39 @@
+const { normalizeGrantRecord, normalizeRevocationRecord } = require("./normalize.cjs");
+
+function grantMetadata(operation, actor = {}, payload = {}, updatedAt = Date.now(), action = "grant") {
+  return normalizeGrantRecord({
+    id: operation?.id || `${action}_${updatedAt}`,
+    action,
+    target: payload.target,
+    roleId: payload.roleId,
+    scopeType: payload.scopeType,
+    scopeId: payload.scopeId,
+    role: payload.role,
+    defaultRole: payload.defaultRole,
+    grantedBy: actor.memberId,
+    grantedAt: updatedAt,
+    grantHlc: operation?.hlc,
+    credentialId: operation?.auth?.credentialId,
+    signature: operation?.auth?.signature
+  });
+}
+
+function revocationMetadata(operation, actor = {}, payload = {}, updatedAt = Date.now(), voidGrantIds = []) {
+  return normalizeRevocationRecord({
+    id: operation?.id || `revoke_${updatedAt}`,
+    action: "access.role.unassign",
+    target: payload.target,
+    roleId: payload.roleId,
+    voidGrantIds,
+    revokedBy: actor.memberId,
+    revokedAt: updatedAt,
+    revocationHlc: operation?.hlc,
+    credentialId: operation?.auth?.credentialId,
+    signature: operation?.auth?.signature
+  });
+}
+
+module.exports = {
+  grantMetadata,
+  revocationMetadata
+};

package/src/security/scopedRoles/normalize.cjs

@@ -0,0 +1,179 @@
+const { runtimeError } = require("../../errors.cjs");
+const { roleRank } = require("../roles.cjs");
+const { SCOPED_ROLE_RANKS, SCOPED_ROLES_STATE_VERSION } = require("./constants.cjs");
+
+function boundedString(value, name, max = 240) {
+  if (typeof value !== "string" || value.trim() === "") throw runtimeError("SCHEMA_INVALID", `${name} must be a non-empty string`);
+  const trimmed = value.trim();
+  if (trimmed.length > max) throw runtimeError("SCHEMA_INVALID", `${name} is too long`);
+  return trimmed;
+}
+
+function optionalBoundedString(value, name, max = 240) {
+  if (value === undefined || value === null || value === "") return undefined;
+  return boundedString(value, name, max);
+}
+
+function scopeKey(scopeType, scopeId) {
+  return `${encodeURIComponent(scopeType)}:${encodeURIComponent(scopeId)}`;
+}
+
+function normalizeScopedRole(role, fallback = undefined) {
+  if (role === "none") return "none";
+  if (role === "view" || role === "viewer" || role === "read" || role === "reader") return "viewer";
+  if (role === "edit" || role === "editor" || role === "member" || role === "user") return "editor";
+  if (role === "moderator" || role === "admin" || role === "owner") return role;
+  return fallback;
+}
+
+function scopedRoleRank(role) {
+  return SCOPED_ROLE_RANKS[normalizeScopedRole(role, "none")] ?? SCOPED_ROLE_RANKS.none;
+}
+
+function scopedRoleMeets(role, requiredRole) {
+  return scopedRoleRank(role) >= scopedRoleRank(requiredRole);
+}
+
+function scopedRoleFromGlobalRole(role) {
+  if (roleRank(role) >= roleRank("owner")) return "owner";
+  if (roleRank(role) >= roleRank("admin")) return "admin";
+  if (roleRank(role) >= roleRank("moderator")) return "moderator";
+  if (roleRank(role) >= roleRank("member")) return "editor";
+  return "none";
+}
+
+function normalizeScopeEntry(value = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const scopeType = optionalBoundedString(value.scopeType, "scopeType", 80);
+  const scopeId = optionalBoundedString(value.scopeId, "scopeId", 180);
+  if (!scopeType || !scopeId) return undefined;
+  const roles = {};
+  for (const [memberId, role] of Object.entries(value.roles || {})) {
+    const normalized = normalizeScopedRole(role, undefined);
+    if (memberId && normalized) roles[memberId] = normalized;
+  }
+  return {
+    scopeType,
+    scopeId,
+    defaultRole: normalizeScopedRole(value.defaultRole, "editor"),
+    roles,
+    ...(Number.isFinite(Number(value.updatedAt)) ? { updatedAt: Number(value.updatedAt) } : {}),
+    ...(optionalBoundedString(value.updatedBy, "updatedBy", 240) ? { updatedBy: value.updatedBy } : {})
+  };
+}
+
+function normalizeGrantRecord(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
+  const id = optionalBoundedString(input.id || input.operationId, "grantId", 240);
+  const grantedBy = optionalBoundedString(input.grantedBy || input.actorId, "grantedBy", 240);
+  if (!id || !grantedBy) return undefined;
+  const role = normalizeScopedRole(input.role, undefined);
+  const defaultRole = normalizeScopedRole(input.defaultRole, undefined);
+  return {
+    id,
+    action: optionalBoundedString(input.action, "grant action", 120) || "grant",
+    ...(optionalBoundedString(input.target, "target", 240) ? { target: input.target } : {}),
+    ...(optionalBoundedString(input.roleId, "roleId", 120) ? { roleId: input.roleId } : {}),
+    ...(optionalBoundedString(input.scopeType, "scopeType", 80) ? { scopeType: input.scopeType } : {}),
+    ...(optionalBoundedString(input.scopeId, "scopeId", 180) ? { scopeId: input.scopeId } : {}),
+    ...(role ? { role } : {}),
+    ...(defaultRole ? { defaultRole } : {}),
+    grantedBy,
+    grantedAt: Number.isFinite(Number(input.grantedAt)) ? Number(input.grantedAt) : 0,
+    ...(optionalBoundedString(input.grantHlc, "grantHlc", 240) ? { grantHlc: input.grantHlc } : {}),
+    ...(optionalBoundedString(input.credentialId, "credentialId", 240) ? { credentialId: input.credentialId } : {}),
+    ...(optionalBoundedString(input.signature, "signature", 2048) ? { signature: input.signature } : {})
+  };
+}
+
+function normalizeRevocationRecord(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
+  const id = optionalBoundedString(input.id || input.operationId, "revocationId", 240);
+  const revokedBy = optionalBoundedString(input.revokedBy || input.actorId, "revokedBy", 240);
+  if (!id || !revokedBy) return undefined;
+  return {
+    id,
+    action: optionalBoundedString(input.action, "revocation action", 120) || "revoke",
+    ...(optionalBoundedString(input.target, "target", 240) ? { target: input.target } : {}),
+    ...(optionalBoundedString(input.roleId, "roleId", 120) ? { roleId: input.roleId } : {}),
+    voidGrantIds: (Array.isArray(input.voidGrantIds) ? input.voidGrantIds : []).filter((item) => typeof item === "string" && item.length > 0).slice(0, 500),
+    revokedBy,
+    revokedAt: Number.isFinite(Number(input.revokedAt)) ? Number(input.revokedAt) : 0,
+    ...(optionalBoundedString(input.revocationHlc, "revocationHlc", 240) ? { revocationHlc: input.revocationHlc } : {}),
+    ...(optionalBoundedString(input.credentialId, "credentialId", 240) ? { credentialId: input.credentialId } : {}),
+    ...(optionalBoundedString(input.signature, "signature", 2048) ? { signature: input.signature } : {})
+  };
+}
+
+function normalizeRoleGrant(input = {}, index = 0) {
+  const scopeType = optionalBoundedString(input.scopeType, `grants[${index}].scopeType`, 80);
+  const scopeId = optionalBoundedString(input.scopeId, `grants[${index}].scopeId`, 180);
+  const role = normalizeScopedRole(input.role, undefined);
+  if (!scopeType || !scopeId || !role) return undefined;
+  return { scopeType, scopeId, role };
+}
+
+function normalizeCompoundRole(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
+  const id = optionalBoundedString(input.id || input.roleId, "roleId", 120);
+  if (!id) return undefined;
+  const grants = (Array.isArray(input.grants) ? input.grants : []).map(normalizeRoleGrant).filter(Boolean);
+  return {
+    id,
+    name: optionalBoundedString(input.name, "role name", 120) || id,
+    grants,
+    ...(normalizeGrantRecord(input.authority) ? { authority: normalizeGrantRecord(input.authority) } : {}),
+    ...(Number.isFinite(Number(input.updatedAt)) ? { updatedAt: Number(input.updatedAt) } : {}),
+    ...(optionalBoundedString(input.updatedBy, "updatedBy", 240) ? { updatedBy: input.updatedBy } : {})
+  };
+}
+
+function normalizeScopedRolesState(value = {}) {
+  const scopes = {};
+  const input = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  for (const entry of Object.values(input.scopes || {})) {
+    const normalized = normalizeScopeEntry(entry);
+    if (normalized) scopes[scopeKey(normalized.scopeType, normalized.scopeId)] = normalized;
+  }
+  const roles = {};
+  for (const role of Object.values(input.roles || {})) {
+    const normalized = normalizeCompoundRole(role);
+    if (normalized) roles[normalized.id] = normalized;
+  }
+  const assignments = {};
+  for (const [memberId, roleIds] of Object.entries(input.assignments || {})) {
+    const ids = (Array.isArray(roleIds) ? roleIds : []).filter((id) => typeof id === "string" && roles[id]);
+    if (memberId && ids.length) assignments[memberId] = [...new Set(ids)].sort();
+  }
+  const grants = {};
+  for (const grant of Object.values(input.grants || {})) {
+    const normalized = normalizeGrantRecord(grant);
+    if (normalized) grants[normalized.id] = normalized;
+  }
+  const revocations = {};
+  for (const revocation of Object.values(input.revocations || {})) {
+    const normalized = normalizeRevocationRecord(revocation);
+    if (normalized) revocations[normalized.id] = normalized;
+  }
+  const assignmentGrants = {};
+  for (const [target, byRole] of Object.entries(input.assignmentGrants || {})) {
+    if (!target || !byRole || typeof byRole !== "object" || Array.isArray(byRole)) continue;
+    const entries = Object.entries(byRole).filter(([roleId, grantId]) => roles[roleId] && typeof grantId === "string" && grants[grantId]);
+    if (entries.length) assignmentGrants[target] = Object.fromEntries(entries);
+  }
+  return { version: SCOPED_ROLES_STATE_VERSION, scopes, roles, assignments, grants, revocations, assignmentGrants };
+}
+
+module.exports = {
+  boundedString,
+  normalizeGrantRecord,
+  normalizeRoleGrant,
+  normalizeRevocationRecord,
+  normalizeScopedRole,
+  normalizeScopedRolesState,
+  optionalBoundedString,
+  scopedRoleFromGlobalRole,
+  scopedRoleMeets,
+  scopedRoleRank,
+  scopeKey
+};

package/src/security/scopedRoles/publicView.cjs

@@ -0,0 +1,31 @@
+const { normalizeScopedRolesState, scopedRoleMeets, scopeKey } = require("./normalize.cjs");
+const { scopedRoleForActor } = require("./access.cjs");
+const { SCOPED_ROLES_STATE_VERSION } = require("./constants.cjs");
+
+function publicScopedRolesView(roomState, actor = {}) {
+  const state = normalizeScopedRolesState(roomState?.scopedRoles);
+  const visibleScopeKeys = new Set(Object.keys(state.scopes));
+  for (const role of Object.values(state.roles)) {
+    for (const grant of role.grants || []) {
+      if (grant.scopeType !== "*" && grant.scopeId !== "*") visibleScopeKeys.add(scopeKey(grant.scopeType, grant.scopeId));
+    }
+  }
+  const scopes = {};
+  for (const key of visibleScopeKeys) {
+    const entry = state.scopes[key] || {};
+    const [encodedScopeType, encodedScopeId] = key.split(":");
+    const scopeType = entry.scopeType || decodeURIComponent(encodedScopeType || "");
+    const scopeId = entry.scopeId || decodeURIComponent(encodedScopeId || "");
+    const role = scopedRoleForActor(roomState, actor, scopeType, scopeId);
+    scopes[key] = {
+      scopeType,
+      scopeId,
+      role,
+      canView: scopedRoleMeets(role, "viewer"),
+      canEdit: scopedRoleMeets(role, "editor")
+    };
+  }
+  return { version: SCOPED_ROLES_STATE_VERSION, scopes };
+}
+
+module.exports = { publicScopedRolesView };