@mh-gg/authority 0.1.1-alpha.20260626T104441232Z

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matterhorn contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @mh-gg/authority
+
+Shared room authority fold, policy, and validity ladder for host-optional encrypted rooms.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@mh-gg/authority",
+  "version": "0.1.1-alpha.20260626T104441232Z",
+  "description": "Shared room authority fold, policy, and validity ladder for host-optional encrypted rooms.",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "dependencies": {
+    "nostr-tools": "^2.23.5",
+    "@mh-gg/protocol": "^0.1.1-alpha.20260626T104441232Z",
+    "@mh-gg/event": "^0.1.1-alpha.20260626T104441232Z"
+  },
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "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/constants.cjs

@@ -0,0 +1,17 @@
+const AUTHORITY_STATE_KIND = "matterhorn.authority-chain";
+const AUTHORITY_STATE_VERSION = 1;
+const CORE_PLUGIN_ID = "matterhorn.core";
+const CORE_AUTHORITY_GRANT_TYPE = "authority.grant";
+const CORE_AUTHORITY_REVOKE_TYPE = "authority.revoke";
+const CORE_REVOKE_CREDENTIAL_TYPE = "credential.revoke";
+const AUTHORITY_SCOPES = Object.freeze(["future", "from-point", "all-by-target"]);
+
+module.exports = {
+  AUTHORITY_SCOPES,
+  AUTHORITY_STATE_KIND,
+  AUTHORITY_STATE_VERSION,
+  CORE_AUTHORITY_GRANT_TYPE,
+  CORE_AUTHORITY_REVOKE_TYPE,
+  CORE_PLUGIN_ID,
+  CORE_REVOKE_CREDENTIAL_TYPE
+};

package/src/index.cjs

@@ -0,0 +1,11 @@
+module.exports = {
+  ...require("./constants.cjs"),
+  ...require("./roles.cjs"),
+  ...require("./shared.cjs"),
+  ...require("./state.cjs"),
+  ...require("./ordering.cjs"),
+  ...require("./resolve/index.cjs"),
+  ...require("./receipts.cjs"),
+  ...require("./inviteGrants.cjs"),
+  ...require("./ladder.cjs")
+};

package/src/inviteGrants.cjs

@@ -0,0 +1,41 @@
+const {
+  INVITE_GRANT_ALG,
+  INVITE_GRANT_SIGNATURE_KIND,
+  INVITE_GRANT_TYPE,
+  INVITE_GRANT_VERSION,
+  INVITE_PROOF_VERSION,
+  INVITE_REVOKE_TYPE,
+  createInviteProof,
+  inviteProofMessage,
+  lengthPrefixedField,
+  normalizeInviteGrant,
+  normalizeInviteRevocation,
+  publicInviteGrant,
+  signInviteGrant,
+  unsignedInviteGrant,
+  validateInviteGrant,
+  validateInviteRevocation,
+  verifyInviteProof,
+  verifySignedInviteGrant
+} = require("@mh-gg/protocol");
+
+module.exports = {
+  INVITE_GRANT_ALG,
+  INVITE_GRANT_SIGNATURE_KIND,
+  INVITE_GRANT_TYPE,
+  INVITE_GRANT_VERSION,
+  INVITE_PROOF_VERSION,
+  INVITE_REVOKE_TYPE,
+  createInviteProof,
+  inviteProofMessage,
+  lengthPrefixedField,
+  normalizeInviteGrant,
+  normalizeInviteRevocation,
+  publicInviteGrant,
+  signInviteGrant,
+  unsignedInviteGrant,
+  validateInviteGrant,
+  validateInviteRevocation,
+  verifyInviteProof,
+  verifySignedInviteGrant
+};

package/src/ladder.cjs

@@ -0,0 +1,158 @@
+const { verifyEvent } = require("nostr-tools/pure");
+const { normalizeRoomRole, roleMeetsRequirement } = require("./roles.cjs");
+
+const TIERS = Object.freeze({
+  SIGNATURE_VALID: 1,
+  MEMBER_VALID: 2,
+  ADMISSIBLE: 3,
+  ROOM_VALID: 4
+});
+
+function isSignatureValid(nostrEvent) {
+  if (!nostrEvent || typeof nostrEvent !== "object") return false;
+  try {
+    return verifyEvent(nostrEvent) === true;
+  } catch {
+    return false;
+  }
+}
+
+function isMemberValid(nostrEvent, { grantChainValidator }) {
+  if (!isSignatureValid(nostrEvent)) return false;
+  if (typeof grantChainValidator !== "function") return false;
+  try {
+    return grantChainValidator(nostrEvent) === true;
+  } catch {
+    return false;
+  }
+}
+
+function eventHeader(nostrEvent) {
+  return nostrEvent?._header || nostrEvent?.header || {};
+}
+
+function callBoolean(name, fn, event, context) {
+  if (typeof fn !== "function") return true;
+  try {
+    return fn(event, context) === true;
+  } catch {
+    return false;
+  }
+}
+
+function verifyAdmissibilitySignature(nostrEvent, context) {
+  if (typeof context.verifySignature === "function") return context.verifySignature(nostrEvent, context) === true;
+  return isSignatureValid(nostrEvent);
+}
+
+function validateGrantChain(nostrEvent, context) {
+  if (typeof context.grantChainValidator === "function") return context.grantChainValidator(nostrEvent, context) === true;
+  if (typeof context.validateGrantChain === "function") return context.validateGrantChain(nostrEvent, context) === true;
+  return true;
+}
+
+function hasActiveEpoch(epoch, activeEpochIds) {
+  if (!epoch) return true;
+  if (!activeEpochIds) return false;
+  if (activeEpochIds instanceof Set) return activeEpochIds.has(epoch);
+  if (Array.isArray(activeEpochIds)) return activeEpochIds.includes(epoch);
+  if (typeof activeEpochIds === "object") return activeEpochIds[epoch] === true;
+  return false;
+}
+
+function credentialMemberId(header, credentials, credentialRequired) {
+  if (!header.credentialId) return credentialRequired ? { ok: false, reason: "missing-credential" } : { ok: true, memberId: header.memberId };
+  const credential = credentials?.[header.credentialId];
+  if (!credential) return { ok: false, reason: "missing-credential" };
+  if (credential.revokedAt) return { ok: false, reason: "revoked-credential" };
+  if (credential.active === false) return { ok: false, reason: "missing-credential" };
+  return { ok: true, memberId: credential.memberId || header.memberId };
+}
+
+function resolveProjectionMembers(authorityProjection) {
+  if (!authorityProjection || typeof authorityProjection !== "object" || Array.isArray(authorityProjection)) return undefined;
+  return authorityProjection.members;
+}
+
+function isActiveMember(member) {
+  if (!member) return false;
+  if (member.revokedAt) return false;
+  if (member.tombstoned) return false;
+  if (member.active === false) return false;
+  return true;
+}
+
+function ensureMemberActive(memberId, members) {
+  const member = members[memberId];
+  if (!member) return { ok: false, reason: "missing-member" };
+  if (member.active === false) return { ok: false, reason: "inactive-member" };
+  if (member.revokedAt || member.tombstoned) return { ok: false, reason: "revoked-member" };
+  return { ok: true, member };
+}
+
+function isMissingEpoch(entry, activeEpochIds) {
+  return Boolean(entry?.epoch && !hasActiveEpoch(entry.epoch, activeEpochIds));
+}
+
+function evaluateAdmissibility(nostrEvent, context = {}) {
+  const {
+    requiredRole,
+    activeEpochIds = new Set(),
+    authorityProjection,
+    credentialRequired = true,
+    rateLimiter,
+    sizeOk = true
+  } = context;
+
+  if (!sizeOk) return { ok: false, reason: "invalid-size" };
+  if (!verifyAdmissibilitySignature(nostrEvent, context)) return { ok: false, reason: "invalid-signature" };
+  if (!validateGrantChain(nostrEvent, context)) return { ok: false, reason: "invalid-member-chain" };
+
+  const members = resolveProjectionMembers(authorityProjection);
+  if (!members) return { ok: false, reason: "missing-member" };
+
+  const header = eventHeader(nostrEvent);
+  const credential = credentialMemberId(header, authorityProjection.credentials, credentialRequired);
+  if (!credential.ok) return credential;
+  const memberId = credential.memberId;
+  if (!memberId) return { ok: false, reason: "missing-member" };
+
+  const memberResult = ensureMemberActive(memberId, members);
+  if (!memberResult.ok) return memberResult;
+  const member = memberResult.member;
+  if (isMissingEpoch(header, activeEpochIds)) return { ok: false, reason: "inactive-epoch" };
+
+  const role = normalizeRoomRole(member.role, undefined);
+  if (!role) return { ok: false, reason: "missing-member" };
+  if (requiredRole && !roleMeetsRequirement(role, requiredRole)) return { ok: false, reason: "insufficient-role" };
+  if (!callBoolean("rateLimiter", rateLimiter, nostrEvent, context)) return { ok: false, reason: "rate-limited" };
+
+  return { ok: true, role, memberId };
+}
+
+function isAdmissible(nostrEvent, context = {}) {
+  return evaluateAdmissibility(nostrEvent, context).ok;
+}
+
+function isRoomValid(operation, { authorityState, tombstones = {} }) {
+  if (!operation || !operation.id) return false;
+  return !tombstones[operation.id];
+}
+
+function validityTier(nostrEvent, operation, context) {
+  if (!isSignatureValid(nostrEvent)) return { tier: 0, ok: false, reason: "invalid-signature" };
+  if (!isMemberValid(nostrEvent, context)) return { tier: TIERS.SIGNATURE_VALID, ok: false, reason: "invalid-member-chain" };
+  if (!isAdmissible(nostrEvent, context)) return { tier: TIERS.MEMBER_VALID, ok: false, reason: "not-admissible" };
+  if (!isRoomValid(operation, context)) return { tier: TIERS.ADMISSIBLE, ok: false, reason: "not-room-valid" };
+  return { tier: TIERS.ROOM_VALID, ok: true };
+}
+
+module.exports = {
+  TIERS,
+  evaluateAdmissibility,
+  isAdmissible,
+  isMemberValid,
+  isRoomValid,
+  isSignatureValid,
+  validityTier
+};

package/src/ordering.cjs

@@ -0,0 +1,55 @@
+const { codePointCompare, operationContentHash, parseHlc, validateHlc } = require("@mh-gg/protocol");
+
+function operationCreatedAt(operation) {
+  const createdAt = Number(operation?.createdAt ?? operation?.issuedAt ?? operation?.at ?? 0);
+  return Number.isFinite(createdAt) ? createdAt : 0;
+}
+
+function operationHlc(operation) {
+  const hlc = operation?.hlc ?? operation?.clock ?? operation?.causal?.hlc;
+  return typeof hlc === "string" ? hlc : "";
+}
+
+function requireOperationHlc(operation, options = {}) {
+  const validation = validateHlc(operationHlc(operation), options);
+  if (!validation.ok) throw new Error(validation.error);
+  return validation.parsed.value;
+}
+
+function operationIdHash(operation) {
+  if (typeof operation?.id === "string" && operation.id.length > 0) return operation.id;
+  return operationContentHash(operation || {});
+}
+
+function operationSortKey(operation) {
+  const hlc = operationHlc(operation);
+  const validation = validateHlc(hlc, { now: Number.MAX_SAFE_INTEGER, maxFutureSkewMs: Number.MAX_SAFE_INTEGER });
+  return [validation.ok ? validation.parsed.value : `~invalid:${operationIdHash(operation)}`, operationIdHash(operation)];
+}
+
+function compareOperations(left, right) {
+  const [leftHlc, leftId] = operationSortKey(left);
+  const [rightHlc, rightId] = operationSortKey(right);
+  const hlcOrder = codePointCompare(leftHlc, rightHlc);
+  if (hlcOrder !== 0) return hlcOrder;
+  return codePointCompare(leftId, rightId);
+}
+
+function sortOperations(operations = []) {
+  return operations.slice().sort(compareOperations);
+}
+
+function hasValidOperationHlc(operation, options = {}) {
+  return Boolean(parseHlc(operationHlc(operation)) && validateHlc(operationHlc(operation), options).ok);
+}
+
+module.exports = {
+  compareOperations,
+  hasValidOperationHlc,
+  operationCreatedAt,
+  operationHlc,
+  operationIdHash,
+  operationSortKey,
+  requireOperationHlc,
+  sortOperations
+};

package/src/receipts.cjs

@@ -0,0 +1,187 @@
+const { canonicalJson } = require("@mh-gg/event/canonicalJson");
+const crypto = require("node:crypto");
+
+const RECEIPT_KIND = "matterhorn.receipt-attestation";
+const RECEIPT_VERSION = 1;
+const INVITE_REVOCATION_PROPAGATION_BOUND_MS = 3_600_000;
+const INVITE_REVOCATION_RACE_ACCEPT = "accept";
+const INVITE_REVOCATION_RACE_PENDING = "pending";
+const INVITE_REVOCATION_RACE_REJECT = "reject";
+const INVITE_REVOCATION_RACE_TOMBSTONE_REASON = "revoked-invite-race";
+
+function receiptId(relayId, eventId) {
+  return `${relayId}:${eventId}`;
+}
+
+function createReceiptAttestation({ relayId, eventId, roomId, seenAt = Date.now() }) {
+  if (!relayId || !eventId || !roomId) throw new Error("relayId, eventId, and roomId are required");
+  return {
+    kind: RECEIPT_KIND,
+    version: RECEIPT_VERSION,
+    relayId,
+    eventId,
+    roomId,
+    seenAt
+  };
+}
+
+function receiptAttestationHash(attestation) {
+  return crypto.createHash("sha256").update(canonicalJson(attestation)).digest("hex");
+}
+
+function isReceiptAttestation(value) {
+  return (
+    value &&
+    typeof value === "object" &&
+    value.kind === RECEIPT_KIND &&
+    value.version === RECEIPT_VERSION &&
+    typeof value.relayId === "string" &&
+    typeof value.eventId === "string" &&
+    typeof value.roomId === "string" &&
+    Number.isFinite(value.seenAt)
+  );
+}
+
+function earliestAttestation(attestations = []) {
+  let earliest = undefined;
+  for (const a of attestations) {
+    if (!isReceiptAttestation(a)) continue;
+    if (!earliest || a.seenAt < earliest.seenAt) earliest = a;
+  }
+  return earliest;
+}
+
+function attestationsForEvent(attestationsById = {}, eventId) {
+  const out = [];
+  for (const att of Object.values(attestationsById)) {
+    if (att.eventId === eventId) out.push(att);
+  }
+  return out;
+}
+
+function backdatedFoldWindowMs(deltaMs = 3_600_000) {
+  return Math.max(0, Number(deltaMs) || 0);
+}
+
+function inviteIdFromJoinOperation(operation = {}) {
+  return (
+    operation.inviteId ||
+    operation.auth?.inviteId ||
+    operation.auth?.id ||
+    operation.join?.inviteId ||
+    operation.externalCommit?.inviteId ||
+    operation.payload?.inviteId ||
+    operation.payload?.auth?.inviteId ||
+    operation.payload?.auth?.id ||
+    operation.payload?.join?.inviteId ||
+    operation.payload?.externalCommit?.inviteId
+  );
+}
+
+function eventIdOf(value = {}) {
+  return value.eventId || value.id;
+}
+
+function receiptForEvent(attestations, eventId) {
+  if (!eventId) return undefined;
+  return earliestAttestation(attestationsForEvent(attestations, eventId));
+}
+
+function classifyInviteRevocationRace({ joinOperation, revocationEvent, attestations, deltaMs = INVITE_REVOCATION_PROPAGATION_BOUND_MS } = {}) {
+  const inviteId = inviteIdFromJoinOperation(joinOperation);
+  if (!inviteId || !revocationEvent?.inviteId || inviteId !== revocationEvent.inviteId) {
+    return { decision: INVITE_REVOCATION_RACE_ACCEPT, reason: "invite-not-revoked" };
+  }
+
+  const joinReceipt = receiptForEvent(attestations, eventIdOf(joinOperation));
+  const revocationReceipt = receiptForEvent(attestations, eventIdOf(revocationEvent));
+  if (!joinReceipt || !revocationReceipt) {
+    return {
+      decision: INVITE_REVOCATION_RACE_PENDING,
+      reason: "missing-receipt",
+      inviteId,
+      joinReceipt,
+      revocationReceipt
+    };
+  }
+
+  const window = backdatedFoldWindowMs(deltaMs);
+  if (joinReceipt.seenAt > revocationReceipt.seenAt + window) {
+    return {
+      decision: INVITE_REVOCATION_RACE_REJECT,
+      reason: INVITE_REVOCATION_RACE_TOMBSTONE_REASON,
+      inviteId,
+      joinReceipt,
+      revocationReceipt,
+      deltaMs: window
+    };
+  }
+
+  return {
+    decision: INVITE_REVOCATION_RACE_ACCEPT,
+    reason: "within-propagation-bound",
+    inviteId,
+    joinReceipt,
+    revocationReceipt,
+    deltaMs: window
+  };
+}
+
+function shouldRejectInviteJoinAfterRevocation(input) {
+  return classifyInviteRevocationRace(input).decision === INVITE_REVOCATION_RACE_REJECT;
+}
+
+function tombstoneInviteRevocationRaces({ operations = [], revocations = [], attestations, deltaMs = INVITE_REVOCATION_PROPAGATION_BOUND_MS } = {}) {
+  const tombstones = {};
+  for (const operation of operations) {
+    for (const revocationEvent of revocations) {
+      const result = classifyInviteRevocationRace({ joinOperation: operation, revocationEvent, attestations, deltaMs });
+      if (result.decision !== INVITE_REVOCATION_RACE_REJECT) continue;
+      tombstones[eventIdOf(operation)] = {
+        reason: INVITE_REVOCATION_RACE_TOMBSTONE_REASON,
+        inviteId: result.inviteId,
+        revocationId: eventIdOf(revocationEvent),
+        joinReceiptSeenAt: result.joinReceipt.seenAt,
+        revocationReceiptSeenAt: result.revocationReceipt.seenAt,
+        deltaMs: result.deltaMs
+      };
+      break;
+    }
+  }
+  return tombstones;
+}
+
+function isBackdatedOperation({ operation, revocationHlc, attestations, deltaMs }) {
+  const opHlc = operation?.hlc;
+  if (!opHlc || !revocationHlc) return false;
+  const revokeHlc = typeof revocationHlc === "string" ? revocationHlc : revocationHlc.hlc;
+  if (!revokeHlc || String(opHlc).localeCompare(String(revokeHlc)) >= 0) return false;
+  const opReceipt = earliestAttestation(attestationsForEvent(attestations, operation.eventId || operation.id));
+  const revocationReceipt = earliestAttestation(attestationsForEvent(attestations, revocationHlc.eventId || revocationHlc.id));
+  if (!opReceipt || !revocationReceipt) return false;
+  const window = backdatedFoldWindowMs(deltaMs);
+  // Operation HLC predates revocation, but receipt is after revocation receipt + window.
+  const opReceiptTooLate = opReceipt.seenAt > revocationReceipt.seenAt + window;
+  return opReceiptTooLate;
+}
+
+module.exports = {
+  INVITE_REVOCATION_PROPAGATION_BOUND_MS,
+  INVITE_REVOCATION_RACE_ACCEPT,
+  INVITE_REVOCATION_RACE_PENDING,
+  INVITE_REVOCATION_RACE_REJECT,
+  INVITE_REVOCATION_RACE_TOMBSTONE_REASON,
+  RECEIPT_KIND,
+  RECEIPT_VERSION,
+  backdatedFoldWindowMs,
+  classifyInviteRevocationRace,
+  createReceiptAttestation,
+  earliestAttestation,
+  inviteIdFromJoinOperation,
+  isBackdatedOperation,
+  isReceiptAttestation,
+  receiptAttestationHash,
+  receiptId,
+  shouldRejectInviteJoinAfterRevocation,
+  tombstoneInviteRevocationRaces
+};

package/src/resolve/fold.cjs

@@ -0,0 +1,67 @@
+const { applyAuthorityProjection, createAuthorityState, normalizeAuthorityState, roleFromAuthority } = require("../state.cjs");
+const { hasValidOperationHlc, sortOperations } = require("../ordering.cjs");
+const { grantFromOperation, isAuthorityGrantOperation, isAuthorityRevokeOperation, revocationFromOperation } = require("./operations.cjs");
+const { canSetRole, projectionFor } = require("./policy.cjs");
+const { computeVoidedGrantIds } = require("./voids.cjs");
+
+function tombstone(tombstones, id, reason, details = {}) {
+  if (!id || tombstones[id]) return;
+  tombstones[id] = { reason, ...details };
+}
+function authoritySeed(baseAuthority) {
+  return createAuthorityState({
+    ownerIds: baseAuthority.genesis?.ownerIds || [],
+    grants: baseAuthority.grants || [],
+    revocations: baseAuthority.revocations || [],
+    tombstones: baseAuthority.tombstones || {},
+    createdAt: baseAuthority.genesis?.createdAt || 0
+  });
+}
+
+function addBaseGrants(nextAuthority, voidedGrantIds, tombstones) {
+  const grants = [];
+  for (const baseGrant of nextAuthority.grants || []) {
+    if (voidedGrantIds.has(baseGrant.id)) tombstone(tombstones, baseGrant.id, "voided-by-revocation", { source: "base" });
+    else grants.push(baseGrant);
+  }
+  return grants;
+}
+
+function applyGrantOperation(operation, context) {
+  const { nextAuthority, grants, tombstones, voidedGrantIds } = context;
+  if (!hasValidOperationHlc(operation)) return tombstone(tombstones, operation.id, "invalid-authority-hlc");
+  const grant = grantFromOperation(operation);
+  if (!grant) return tombstone(tombstones, operation.id, "invalid-authority-grant");
+  if (voidedGrantIds.has(grant.id)) return tombstone(tombstones, grant.id, "voided-by-revocation");
+  const current = projectionFor({ ...nextAuthority, grants });
+  const granterRole = current[grant.granter] || roleFromAuthority(nextAuthority, grant.granter);
+  const targetRole = current[grant.target] || roleFromAuthority(nextAuthority, grant.target);
+  if (canSetRole(granterRole, grant.role, targetRole)) return grants.push(grant);
+  tombstone(tombstones, grant.id, "unauthorized-authority-grant", { granter: grant.granter, target: grant.target, role: grant.role });
+}
+
+function applyRevocationOperation(operation, context) {
+  const { revocations, tombstones, validRevocationIds } = context;
+  if (!hasValidOperationHlc(operation)) return tombstone(tombstones, operation.id, "invalid-authority-hlc");
+  const revocation = revocationFromOperation(operation);
+  if (!revocation) return tombstone(tombstones, operation.id, "invalid-authority-revocation");
+  if (validRevocationIds.has(revocation.id)) return revocations.push(revocation);
+  tombstone(tombstones, revocation.id, "unauthorized-authority-revocation", { revoker: revocation.revoker });
+}
+
+function resolveAuthorityOperations({ authority: authorityInput, operations = [] } = {}) {
+  const baseAuthority = normalizeAuthorityState(authorityInput) || createAuthorityState({ ownerIds: [] });
+  const sorted = sortOperations(operations);
+  const { voidedGrantIds, validRevocationIds } = computeVoidedGrantIds(baseAuthority, sorted);
+  const nextAuthority = authoritySeed(baseAuthority);
+  const tombstones = { ...(nextAuthority.tombstones || {}) };
+  const grants = addBaseGrants(nextAuthority, voidedGrantIds, tombstones);
+  const revocations = [...(nextAuthority.revocations || [])];
+  const context = { nextAuthority, grants, revocations, tombstones, voidedGrantIds, validRevocationIds };
+  for (const operation of sorted) {
+    if (isAuthorityGrantOperation(operation)) applyGrantOperation(operation, context);
+    else if (isAuthorityRevokeOperation(operation)) applyRevocationOperation(operation, context);
+  }
+  return applyAuthorityProjection({ ...nextAuthority, grants, revocations, tombstones }).authority;
+}
+module.exports = { resolveAuthorityOperations };

package/src/resolve/index.cjs

@@ -0,0 +1,6 @@
+module.exports = {
+  ...require("./operations.cjs"),
+  ...require("./policy.cjs"),
+  ...require("./voids.cjs"),
+  ...require("./fold.cjs")
+};

package/src/resolve/operations.cjs

@@ -0,0 +1,48 @@
+const { CORE_AUTHORITY_GRANT_TYPE, CORE_AUTHORITY_REVOKE_TYPE, CORE_PLUGIN_ID } = require("../constants.cjs");
+const { normalizeGrant, normalizeRevocation } = require("../state.cjs");
+const { operationCreatedAt } = require("../ordering.cjs");
+
+function isAuthorityGrantOperation(operation) {
+  return operation?.pluginId === CORE_PLUGIN_ID && operation?.type === CORE_AUTHORITY_GRANT_TYPE;
+}
+function isAuthorityRevokeOperation(operation) {
+  return operation?.pluginId === CORE_PLUGIN_ID && operation?.type === CORE_AUTHORITY_REVOKE_TYPE;
+}
+function actorId(operation) {
+  return operation?.actor?.memberId;
+}
+function grantFromOperation(operation) {
+  if (!isAuthorityGrantOperation(operation)) return undefined;
+  return normalizeGrant({
+    id: operation.id,
+    granter: actorId(operation),
+    target: operation.payload?.target,
+    role: operation.payload?.role,
+    createdAt: operationCreatedAt(operation),
+    hlc: operation.hlc,
+    reason: operation.payload?.reason,
+    source: "operation",
+    credentialId: operation.auth?.credentialId,
+    signature: operation.auth?.signature,
+    signedAt: operation.auth?.issuedAt || operation.auth?.createdAt
+  });
+}
+function revocationFromOperation(operation) {
+  if (!isAuthorityRevokeOperation(operation)) return undefined;
+  return normalizeRevocation({
+    id: operation.id,
+    revoker: actorId(operation),
+    target: operation.payload?.target,
+    voidGrantIds: operation.payload?.voidGrantIds,
+    voidFrom: operation.payload?.voidFrom,
+    scope: operation.payload?.scope,
+    cascade: operation.payload?.cascade,
+    createdAt: operationCreatedAt(operation),
+    hlc: operation.hlc,
+    reason: operation.payload?.reason,
+    credentialId: operation.auth?.credentialId,
+    signature: operation.auth?.signature,
+    signedAt: operation.auth?.issuedAt || operation.auth?.createdAt
+  });
+}
+module.exports = { grantFromOperation, isAuthorityGrantOperation, isAuthorityRevokeOperation, revocationFromOperation };

package/src/resolve/policy.cjs

@@ -0,0 +1,28 @@
+const { normalizeRoomRole, roleMeetsRequirement, roleRank } = require("../roles.cjs");
+const { applyAuthorityProjection } = require("../state.cjs");
+
+function projectionFor(authority, grants = []) {
+  return applyAuthorityProjection({ ...authority, grants }).authority.derivedRoles || {};
+}
+function roleInProjection(authority, grants, memberId) {
+  if (!memberId) return undefined;
+  return projectionFor(authority, grants)[memberId];
+}
+function canSetRole(granterRole, targetRole, targetCurrentRole) {
+  const granter = normalizeRoomRole(granterRole, undefined);
+  const target = normalizeRoomRole(targetRole, undefined);
+  const currentTarget = normalizeRoomRole(targetCurrentRole, undefined);
+  if (!granter || !target) return false;
+  if (granter === "owner") return true;
+  if (target === "owner" || currentTarget === "owner") return false;
+  return roleMeetsRequirement(granter, "admin") && roleRank(target) <= roleRank("admin");
+}
+function canVoidGrant(revokerRole, grant) {
+  const role = normalizeRoomRole(revokerRole, undefined);
+  if (!role || !grant) return false;
+  const grantRole = normalizeRoomRole(grant.role, undefined);
+  if (role === "owner") return true;
+  if (grantRole === "owner") return false;
+  return roleMeetsRequirement(role, "admin") && roleRank(grantRole) <= roleRank("admin");
+}
+module.exports = { canSetRole, canVoidGrant, projectionFor, roleInProjection };

package/src/resolve/voids.cjs

@@ -0,0 +1,88 @@
+const { roleMeetsRequirement } = require("../roles.cjs");
+const { createAuthorityState, normalizeAuthorityState } = require("../state.cjs");
+const { hasValidOperationHlc, operationHlc, sortOperations } = require("../ordering.cjs");
+const { codePointCompare, parseHlc } = require("@mh-gg/protocol");
+const { grantFromOperation, isAuthorityGrantOperation, isAuthorityRevokeOperation, revocationFromOperation } = require("./operations.cjs");
+const { canSetRole, canVoidGrant, roleInProjection } = require("./policy.cjs");
+
+function grantRecordMap(authority, operations = []) {
+  const records = new Map();
+  for (const grant of authority?.grants || []) records.set(grant.id, { ...grant, source: grant.source || "base" });
+  for (const operation of operations) {
+    if (!hasValidOperationHlc(operation)) continue;
+    const grant = grantFromOperation(operation);
+    if (grant) records.set(grant.id, grant);
+  }
+  return records;
+}
+
+function grantIsAtOrAfterHlc(grant, cutHlc) {
+  if (!parseHlc(cutHlc)) return true;
+  const grantHlc = grant?.hlc || "";
+  if (!parseHlc(grantHlc)) return false;
+  return codePointCompare(grantHlc, cutHlc) >= 0;
+}
+
+function grantsMatchingRevocation(revocation, grantsById) {
+  if (!revocation) return [];
+  const out = new Map((revocation.voidGrantIds || []).map((id) => grantsById.get(id)).filter(Boolean).map((grant) => [grant.id, grant]));
+  if (revocation.target && (revocation.scope === "from-point" || revocation.scope === "all-by-target")) {
+    for (const grant of grantsById.values()) {
+      if (grant.granter !== revocation.target) continue;
+      if (revocation.scope === "from-point" && revocation.voidFrom !== undefined && !grantIsAtOrAfterHlc(grant, revocation.voidFrom)) continue;
+      out.set(grant.id, grant);
+    }
+  }
+  return [...out.values()];
+}
+
+function recomputeAppliedGrants(authority, processedGrants, voidedGrantIds) {
+  return [...(authority.grants || []), ...processedGrants].filter((grant) => !voidedGrantIds.has(grant.id));
+}
+
+function processGrantForVoids(operation, context) {
+  const { authority, processedGrants, voidedGrantIds } = context;
+  if (!hasValidOperationHlc(operation)) return;
+  const grant = grantFromOperation(operation);
+  if (!grant || voidedGrantIds.has(grant.id)) return;
+  const applied = recomputeAppliedGrants(authority, processedGrants, voidedGrantIds);
+  const granterRole = roleInProjection(authority, applied, grant.granter);
+  const targetRole = roleInProjection(authority, applied, grant.target);
+  if (canSetRole(granterRole, grant.role, targetRole)) processedGrants.push(grant);
+}
+
+function processRevocationForVoids(operation, context) {
+  const { authority, grantsById, processedGrants, validRevocationIds, voidedGrantIds } = context;
+  if (!hasValidOperationHlc(operation)) return;
+  const revocation = revocationFromOperation(operation);
+  if (!revocation) return;
+  const applied = recomputeAppliedGrants(authority, processedGrants, voidedGrantIds);
+  const revokerRole = roleInProjection(authority, applied, revocation.revoker);
+  const matches = grantsMatchingRevocation(revocation, grantsById);
+  if (matches.length === 0) {
+    if (roleMeetsRequirement(revokerRole, "admin")) validRevocationIds.add(revocation.id);
+    return;
+  }
+  if (!matches.every((grant) => canVoidGrant(revokerRole, grant))) return;
+  validRevocationIds.add(revocation.id);
+  for (const grant of matches) voidedGrantIds.add(grant.id);
+}
+
+function computeVoidedGrantIds(authorityInput, operations = []) {
+  const authority = normalizeAuthorityState(authorityInput) || createAuthorityState({ ownerIds: [] });
+  const sorted = sortOperations(operations);
+  const context = {
+    authority,
+    grantsById: grantRecordMap(authority, sorted),
+    voidedGrantIds: new Set(),
+    validRevocationIds: new Set(),
+    processedGrants: []
+  };
+  for (const operation of sorted) {
+    if (isAuthorityGrantOperation(operation)) processGrantForVoids(operation, context);
+    else if (isAuthorityRevokeOperation(operation)) processRevocationForVoids(operation, context);
+  }
+  return { voidedGrantIds: context.voidedGrantIds, validRevocationIds: context.validRevocationIds };
+}
+
+module.exports = { computeVoidedGrantIds, grantIsAtOrAfterHlc, grantRecordMap, grantsMatchingRevocation, recomputeAppliedGrants };

package/src/roles.cjs

@@ -0,0 +1,53 @@
+const ROLE_RANKS = Object.freeze({
+  guest: 0,
+  member: 1,
+  user: 1,
+  facilitator: 1,
+  moderator: 2,
+  admin: 3,
+  owner: 4
+});
+
+function normalizeRoomRole(role, fallback) {
+  const missingFallback = arguments.length < 2;
+  const fallbackRole = missingFallback ? "guest" : fallback;
+  if (role === "user") return "member";
+  if (role === "owner" || role === "admin" || role === "moderator" || role === "facilitator" || role === "member" || role === "guest") return role;
+  return fallbackRole;
+}
+
+function roleRank(role, options = {}) {
+  const normalized = normalizeRoomRole(role, options.strict ? undefined : "guest");
+  if (!normalized) return undefined;
+  return ROLE_RANKS[normalized] ?? ROLE_RANKS.guest;
+}
+
+function minRoleByRank(roles = []) {
+  const normalized = (Array.isArray(roles) ? roles : [roles]).map((role) => normalizeRoomRole(role)).filter(Boolean);
+  if (normalized.length === 0) return undefined;
+  return normalized.reduce((lowest, role) => roleRank(role) < roleRank(lowest) ? role : lowest, normalized[0]);
+}
+
+function roleMeetsRequirement(actorRole, requiredRole) {
+  if (normalizeRoomRole(requiredRole, undefined) === "facilitator") {
+    const actor = normalizeRoomRole(actorRole, undefined);
+    return actor === "facilitator" || actor === "moderator" || actor === "admin" || actor === "owner";
+  }
+  return roleRank(actorRole) >= roleRank(requiredRole);
+}
+
+function effectiveRoleFor({ keyRole, stateRole, actorRole } = {}) {
+  const ceiling = normalizeRoomRole(keyRole, undefined);
+  const current = normalizeRoomRole(stateRole || actorRole || ceiling || "guest");
+  if (!ceiling) return current;
+  return roleRank(current) <= roleRank(ceiling) ? current : ceiling;
+}
+
+module.exports = {
+  ROLE_RANKS,
+  effectiveRoleFor,
+  minRoleByRank,
+  normalizeRoomRole,
+  roleMeetsRequirement,
+  roleRank
+};

package/src/shared.cjs

@@ -0,0 +1,5 @@
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+module.exports = { clone };

package/src/state.cjs

@@ -0,0 +1,146 @@
+const { normalizeRoomRole, roleRank } = require("./roles.cjs");
+const { clone } = require("./shared.cjs");
+const { AUTHORITY_STATE_KIND, AUTHORITY_STATE_VERSION } = require("./constants.cjs");
+
+function uniqStrings(values = []) {
+  return [...new Set((Array.isArray(values) ? values : []).filter((value) => typeof value === "string" && value.length > 0))];
+}
+
+function normalizeGrant(input = {}) {
+  const id = String(input.id || "");
+  const granter = String(input.granter || input.actor?.memberId || input.revoker || "");
+  const target = String(input.target || input.memberId || "");
+  const role = normalizeRoomRole(input.role, undefined);
+  if (!id || !granter || !target || !role) return undefined;
+  return {
+    id,
+    granter,
+    target,
+    role,
+    createdAt: Number.isFinite(Number(input.createdAt)) ? Number(input.createdAt) : 0,
+    ...(input.hlc ? { hlc: input.hlc } : {}),
+    ...(input.reason ? { reason: String(input.reason) } : {}),
+    ...(input.source ? { source: String(input.source) } : {}),
+    ...(typeof input.credentialId === "string" && input.credentialId.length > 0 ? { credentialId: input.credentialId } : {}),
+    ...(typeof input.signature === "string" && input.signature.length > 0 ? { signature: input.signature } : {}),
+    ...(Number.isFinite(Number(input.signedAt)) ? { signedAt: Number(input.signedAt) } : {})
+  };
+}
+
+function normalizeRevocation(input = {}) {
+  const id = String(input.id || "");
+  const revoker = String(input.revoker || input.actor?.memberId || "");
+  if (!id || !revoker) return undefined;
+  const voidGrantIds = uniqStrings(input.voidGrantIds);
+  return {
+    id,
+    revoker,
+    target: typeof input.target === "string" && input.target.length > 0 ? input.target : undefined,
+    voidGrantIds,
+    voidFrom: input.voidFrom ?? undefined,
+    scope: input.scope || (voidGrantIds.length ? "all-by-target" : "future"),
+    cascade: input.cascade !== false,
+    createdAt: Number.isFinite(Number(input.createdAt)) ? Number(input.createdAt) : 0,
+    ...(input.hlc ? { hlc: input.hlc } : {}),
+    ...(input.reason ? { reason: String(input.reason) } : {}),
+    ...(typeof input.credentialId === "string" && input.credentialId.length > 0 ? { credentialId: input.credentialId } : {}),
+    ...(typeof input.signature === "string" && input.signature.length > 0 ? { signature: input.signature } : {}),
+    ...(Number.isFinite(Number(input.signedAt)) ? { signedAt: Number(input.signedAt) } : {})
+  };
+}
+
+function createAuthorityState({ ownerIds = [], grants = [], revocations = [], tombstones = {}, createdAt = Date.now() } = {}) {
+  const normalizedOwners = uniqStrings(ownerIds);
+  const state = {
+    kind: AUTHORITY_STATE_KIND,
+    version: AUTHORITY_STATE_VERSION,
+    genesis: {
+      ownerIds: normalizedOwners,
+      createdAt
+    },
+    grants: grants.map(normalizeGrant).filter(Boolean),
+    revocations: revocations.map(normalizeRevocation).filter(Boolean),
+    tombstones: { ...(tombstones || {}) },
+    derivedRoles: {}
+  };
+  return applyAuthorityProjection(state).authority;
+}
+
+function normalizeAuthorityState(authority) {
+  if (!authority || typeof authority !== "object") return undefined;
+  const ownerIds = uniqStrings(authority.genesis?.ownerIds || authority.ownerIds || []);
+  if (ownerIds.length === 0) return undefined;
+  return applyAuthorityProjection({
+    kind: authority.kind || AUTHORITY_STATE_KIND,
+    version: authority.version || AUTHORITY_STATE_VERSION,
+    genesis: {
+      ...(authority.genesis || {}),
+      ownerIds,
+      createdAt: authority.genesis?.createdAt || authority.createdAt || 0
+    },
+    grants: (Array.isArray(authority.grants) ? authority.grants : []).map(normalizeGrant).filter(Boolean),
+    revocations: (Array.isArray(authority.revocations) ? authority.revocations : []).map(normalizeRevocation).filter(Boolean),
+    tombstones: { ...(authority.tombstones || {}) },
+    derivedRoles: { ...(authority.derivedRoles || {}) }
+  }).authority;
+}
+
+function authorityEnabled(roomState) {
+  return Boolean(normalizeAuthorityState(roomState?.authority));
+}
+
+function roleFromAuthority(authority, memberId) {
+  const normalized = normalizeAuthorityState(authority);
+  if (!normalized || typeof memberId !== "string" || memberId.length === 0) return undefined;
+  if (normalized.derivedRoles?.[memberId]) return normalized.derivedRoles[memberId];
+  if ((normalized.genesis?.ownerIds || []).includes(memberId)) return "owner";
+  return undefined;
+}
+
+function adminIdsFromDerivedRoles(roles = {}) {
+  return Object.entries(roles)
+    .filter(([, role]) => roleRank(role) >= roleRank("admin"))
+    .map(([memberId]) => memberId)
+    .sort();
+}
+
+function applyAuthorityProjection(authorityInput = {}, membersInput = {}) {
+  const authority = clone(authorityInput);
+  const roles = {};
+  const owners = uniqStrings(authority.genesis?.ownerIds || []);
+  for (const ownerId of owners) roles[ownerId] = "owner";
+  for (const grant of authority.grants || []) {
+    if (!grant?.target || !grant?.role) continue;
+    if (grant.role === "guest") delete roles[grant.target];
+    else roles[grant.target] = normalizeRoomRole(grant.role);
+  }
+  authority.derivedRoles = roles;
+  const members = { ...(membersInput || {}) };
+  for (const [memberId, role] of Object.entries(roles)) {
+    const member = {
+      ...(members[memberId] || {}),
+      id: members[memberId]?.id || memberId,
+      role
+    };
+    delete member.profileOnly;
+    members[memberId] = member;
+  }
+  // Downgrade members whose previous role projection disappeared, while retaining identity metadata.
+  for (const [memberId, member] of Object.entries(members)) {
+    if (roles[memberId]) continue;
+    if (member?.role && roleRank(member.role) > roleRank("member")) members[memberId] = { ...member, role: "member" };
+  }
+  return { authority, members, adminIds: adminIdsFromDerivedRoles(roles) };
+}
+
+module.exports = {
+  adminIdsFromDerivedRoles,
+  applyAuthorityProjection,
+  authorityEnabled,
+  createAuthorityState,
+  normalizeAuthorityState,
+  normalizeGrant,
+  normalizeRevocation,
+  roleFromAuthority,
+  uniqStrings
+};