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

package/src/runtime/snowflake.cjs

@@ -0,0 +1,43 @@
+const {
+  createSnowflakeGenerator,
+  isSnowflakeId,
+  prefixedSnowflakeId,
+  snowflakeIdForOperation,
+  stableSnowflakeNodeId
+} = require("@mh-gg/protocol");
+
+function runtimeSnowflakeNodeId(options = {}) {
+  if (options.snowflakeNodeId !== undefined) return stableSnowflakeNodeId(options.snowflakeNodeId);
+  if (options.nodeId !== undefined) return stableSnowflakeNodeId(options.nodeId);
+  if (process.env.MATTERHORN_SNOWFLAKE_NODE_ID) return stableSnowflakeNodeId(process.env.MATTERHORN_SNOWFLAKE_NODE_ID);
+  const roomId = options.room?.id || "matterhorn-sdk";
+  const appId = options.room?.appPack?.id || "app";
+  return stableSnowflakeNodeId(`${appId}:${roomId}:${process.pid || 0}`);
+}
+
+function createRuntimeSnowflakeGenerator(runtime, options = {}) {
+  return createSnowflakeGenerator({
+    nodeId: runtimeSnowflakeNodeId(options),
+    now: () => runtime.now()
+  });
+}
+
+function assignOperationLedgerId(runtime, operation) {
+  if (operation?.ledgerId && isSnowflakeId(operation.ledgerId)) return operation;
+  const ledgerId = runtime.snowflakes.next(operation?.createdAt || runtime.now());
+  return { ...operation, ledgerId, snowflakeId: operation?.snowflakeId && isSnowflakeId(operation.snowflakeId) ? operation.snowflakeId : ledgerId };
+}
+
+function entityIdForOperation(prefix, operation, index = 0) {
+  const base = operation?.ledgerId && isSnowflakeId(operation.ledgerId)
+    ? operation.ledgerId
+    : snowflakeIdForOperation(operation || {});
+  return `${prefixedSnowflakeId(prefix, base)}${index > 0 ? `_${index}` : ""}`;
+}
+
+module.exports = {
+  assignOperationLedgerId,
+  createRuntimeSnowflakeGenerator,
+  entityIdForOperation,
+  runtimeSnowflakeNodeId
+};

package/src/security/authority/constants.cjs

@@ -0,0 +1,10 @@
+const a = require("@mh-gg/authority");
+module.exports = {
+  AUTHORITY_SCOPES: a.AUTHORITY_SCOPES,
+  AUTHORITY_STATE_KIND: a.AUTHORITY_STATE_KIND,
+  AUTHORITY_STATE_VERSION: a.AUTHORITY_STATE_VERSION,
+  CORE_AUTHORITY_GRANT_TYPE: a.CORE_AUTHORITY_GRANT_TYPE,
+  CORE_AUTHORITY_REVOKE_TYPE: a.CORE_AUTHORITY_REVOKE_TYPE,
+  CORE_PLUGIN_ID: a.CORE_PLUGIN_ID,
+  CORE_REVOKE_CREDENTIAL_TYPE: a.CORE_REVOKE_CREDENTIAL_TYPE
+};

package/src/security/authority/resolve/operations.cjs

@@ -0,0 +1,7 @@
+const a = require("@mh-gg/authority");
+module.exports = {
+  grantFromOperation: a.grantFromOperation,
+  isAuthorityGrantOperation: a.isAuthorityGrantOperation,
+  isAuthorityRevokeOperation: a.isAuthorityRevokeOperation,
+  revocationFromOperation: a.revocationFromOperation
+};

package/src/security/authority/resolve/policy.cjs

@@ -0,0 +1,7 @@
+const a = require("@mh-gg/authority");
+module.exports = {
+  canSetRole: a.canSetRole,
+  canVoidGrant: a.canVoidGrant,
+  projectionFor: a.projectionFor,
+  roleInProjection: a.roleInProjection
+};

package/src/security/authority/resolve/voids.cjs

@@ -0,0 +1,8 @@
+const a = require("@mh-gg/authority");
+module.exports = {
+  computeVoidedGrantIds: a.computeVoidedGrantIds,
+  grantIsAtOrAfterHlc: a.grantIsAtOrAfterHlc,
+  grantRecordMap: a.grantRecordMap,
+  grantsMatchingRevocation: a.grantsMatchingRevocation,
+  recomputeAppliedGrants: a.recomputeAppliedGrants
+};

package/src/security/authorization/coreGate.cjs

@@ -0,0 +1,63 @@
+const { runtimeError } = require("../../errors.cjs");
+const { actorWithStanding } = require("../standingAuthority.cjs");
+const { minRoleByRank, roleMeetsRequirement } = require("../roles.cjs");
+const { declaredRolesForOperation, operationDescriptor, requireDeclaredRolePolicy } = require("../../plugins/operationDescriptors.cjs");
+const { assertOperationScopeAccess } = require("../scopedRoles.cjs");
+const { schemaActionPolicyForOperation } = require("./schemaActions.cjs");
+
+
+async function evaluateStanding(standingAuthority, input) {
+  if (!standingAuthority || typeof standingAuthority.evaluate !== "function") {
+    throw runtimeError("STANDING_AUTHORITY_MISSING", "Standing authority is unavailable");
+  }
+  try {
+    const standing = await standingAuthority.evaluate(input);
+    if (!standing || typeof standing !== "object") throw new Error("standing result is invalid");
+    return standing;
+  } catch (error) {
+    if (error?.code) throw error;
+    throw runtimeError("STANDING_AUTHORITY_UNAVAILABLE", `Standing authority unavailable: ${error?.message || error}`);
+  }
+}
+
+async function authorizeCoreOperation(runtime, { operation, actor, state, plugin, roles, operationLabel } = {}) {
+  const standing = await evaluateStanding(runtime.standingAuthority, {
+    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()
+  });
+  const effectiveActor = actorWithStanding({ ...(operation?.actor || {}), ...actor, credentialId: actor?.credentialId || operation?.auth?.credentialId }, standing);
+  if (effectiveActor.standing !== "active") {
+    throw runtimeError("ACTOR_NOT_ACTIVE", `Actor ${effectiveActor.memberId || "unknown"} standing is ${effectiveActor.standing}`);
+  }
+
+  const schemaPolicy = schemaActionPolicyForOperation(runtime, operation);
+  const descriptor = roles ? { authorize: { roles } } : operationDescriptor(plugin, operation.type);
+  const schemaRoles = schemaPolicy?.roles;
+  const requiredRoles = schemaRoles || roles || requireDeclaredRolePolicy(plugin, operation.type);
+  const authorize = schemaRoles ? { ...(descriptor?.authorize || {}), roles: schemaRoles } : (descriptor?.authorize || {});
+  const requiredRole = minRoleByRank(requiredRoles);
+  if (!requiredRole || !roleMeetsRequirement(effectiveActor.role, requiredRole)) {
+    throw runtimeError("FORBIDDEN", `${operationLabel || `${plugin.id}.${operation.type}`} requires ${requiredRole || "a declared role"}; actor role is ${effectiveActor.role}`);
+  }
+  assertOperationScopeAccess({
+    roomState: state,
+    actor: effectiveActor,
+    operation,
+    plugin,
+    authorize,
+    operationLabel
+  });
+  return effectiveActor;
+}
+
+module.exports = {
+  authorizeCoreOperation,
+  declaredRolesForOperation,
+  operationDescriptor,
+  requireDeclaredRolePolicy
+};

package/src/security/authorization/schemaActions.cjs

@@ -0,0 +1,75 @@
+const { runtimeError } = require("../../errors.cjs");
+
+const CORE_PLUGIN_ID = "matterhorn.core";
+const INTERNAL_CORE_OPERATIONS = new Set([
+  "authority.grant",
+  "authority.revoke",
+  "credential.revoke",
+  "member.key.publish"
+]);
+
+function compositionForRuntime(runtime) {
+  return runtime.hostPack?.composition || runtime.room?.appPack?.composition;
+}
+
+function hasSchemaActions(composition) {
+  return Array.isArray(composition?.actions) && composition.actions.length > 0;
+}
+
+function schemaActionName(operation) {
+  if (typeof operation?.schemaAction === "string" && operation.schemaAction.length > 0) return operation.schemaAction;
+  if (typeof operation?.action === "string" && operation.action.length > 0) return operation.action;
+  return undefined;
+}
+
+function isInternalCoreOperation(operation) {
+  return operation?.pluginId === CORE_PLUGIN_ID && INTERNAL_CORE_OPERATIONS.has(operation.type);
+}
+
+function primaryPluginId(runtime, composition) {
+  return composition?.primaryPlugin?.id
+    || runtime.hostPack?.plugins?.[0]?.id
+    || (runtime.room?.appPack?.id ? `${runtime.room.appPack.id}.plugin` : undefined);
+}
+
+function pluginIdForAction(runtime, composition, action) {
+  if (action.plugin === "primary" || action.plugin === "$primary") return primaryPluginId(runtime, composition);
+  if (action.plugin === "core" || action.plugin === CORE_PLUGIN_ID) return CORE_PLUGIN_ID;
+  const ref = (composition.plugins || []).find((plugin) => plugin?.key === action.plugin || plugin?.id === action.plugin);
+  return ref?.id || action.plugin;
+}
+
+function rolesForAction(action) {
+  if (typeof action.requiredRole === "string" && action.requiredRole.length > 0) return [action.requiredRole];
+  const roles = action.payloadSchema?.authorize?.roles;
+  return Array.isArray(roles) && roles.length ? roles.slice() : undefined;
+}
+
+function schemaActionPolicyForOperation(runtime, operation) {
+  if (isInternalCoreOperation(operation)) return undefined;
+  const composition = compositionForRuntime(runtime);
+  if (!hasSchemaActions(composition)) return undefined;
+
+  const actionName = schemaActionName(operation);
+  if (!actionName) {
+    throw runtimeError("SCHEMA_ACTION_REQUIRED", `${operation.pluginId}.${operation.type} must include a schemaAction from the application schema`);
+  }
+
+  const action = composition.actions.find((item) => item?.name === actionName);
+  if (!action) throw runtimeError("SCHEMA_ACTION_UNKNOWN", `Application schema action ${actionName} is not declared`);
+
+  const pluginId = pluginIdForAction(runtime, composition, action);
+  if (operation.pluginId !== pluginId || operation.type !== action.type) {
+    throw runtimeError("SCHEMA_ACTION_MISMATCH", `Application schema action ${actionName} maps to ${pluginId}.${action.type}, not ${operation.pluginId}.${operation.type}`);
+  }
+
+  return {
+    action,
+    pluginId,
+    roles: rolesForAction(action)
+  };
+}
+
+module.exports = {
+  schemaActionPolicyForOperation
+};

package/src/security/roleKeys/authenticator.cjs

@@ -0,0 +1,36 @@
+const { runtimeError } = require("../../errors.cjs");
+const { verifyOperationRoleKey } = require("./signatures.cjs");
+
+function createRoleKeyAuthenticator(options = {}) {
+  const grants = options.grants || options.operationRoleKeyGrants || options.operationKeyGrants;
+  const expected = {
+    roomId: options.roomId,
+    appPackId: options.appPackId,
+    appPackHash: options.appPackHash
+  };
+  const now = options.now;
+  const grantAuthorities = options.grantAuthorities || options.operationGrantAuthorities || options.authorities;
+  const allowUnsigned = options.allowUnsignedOperationRoleKeyGrants === true || options.devUnsafeUnsignedOperationRoleKeyGrants === true;
+  const productionGrantMode = (options.productionRuntime === true || options.relayExecuted === true) && !allowUnsigned;
+  const requireSignedGrants = options.requireSignedGrants
+    || options.requireSignedOperationRoleKeyGrants
+    || productionGrantMode
+    || Boolean(grantAuthorities && (Array.isArray(grantAuthorities) ? grantAuthorities.length : true));
+  const acceptOperationAppPackHash = options.acceptOperationAppPackHash === true;
+  const roleKeyAuthenticator = async function roleKeyAuthenticator(auth, actor, operation = {}) {
+    const expectedForOperation = {
+      ...expected,
+      appPackHash: acceptOperationAppPackHash && operation.roomId === expected.roomId && operation.appPackId === expected.appPackId && typeof operation.appPackHash === "string"
+        ? operation.appPackHash
+        : expected.appPackHash
+    };
+    const verification = verifyOperationRoleKey({ ...operation, actor, auth }, grants, { ...expectedForOperation, now, grantAuthorities, requireSignedGrants });
+    if (!verification.ok) throw runtimeError("INVALID_OPERATION_ROLE_KEY", verification.error);
+    return verification.actor;
+  };
+  roleKeyAuthenticator.matterhornRoleKeyAuthenticator = true;
+  roleKeyAuthenticator.requireSignedGrants = requireSignedGrants === true;
+  return roleKeyAuthenticator;
+}
+
+module.exports = { createRoleKeyAuthenticator };

package/src/security/roleKeys/authorities/index.cjs

@@ -0,0 +1,4 @@
+module.exports = {
+  ...require("./shapes.cjs"),
+  ...require("./signing.cjs")
+};

package/src/security/roleKeys/authorities/shapes.cjs

@@ -0,0 +1,98 @@
+const crypto = require("node:crypto");
+const { clone } = require("../../../shared.cjs");
+const { OPERATION_GRANT_AUTHORITY_KIND, OPERATION_ROLE_KEY_VERSION, ROLE_ALG } = require("../constants.cjs");
+const { ensureText } = require("../grants.cjs");
+const { normalizeOperationKeyRole } = require("../roles.cjs");
+
+function authorityFingerprint(publicKeyPem) {
+  if (typeof publicKeyPem !== "string" || publicKeyPem.length === 0) throw new Error("Operation grant authority public key is required.");
+  return `sha256-${crypto.createHash("sha256").update(publicKeyPem).digest("hex")}`;
+}
+
+function generateOperationGrantAuthorityKeyPair(options = {}) {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" });
+  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" });
+  return {
+    issuer: options.issuer || "matterhorn-grant-authority",
+    publicKeyPem,
+    privateKeyPem,
+    publicKeyFingerprint: authorityFingerprint(publicKeyPem)
+  };
+}
+
+function optionalStringArray(value, label) {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.length === 0)) throw new Error(`${label} must be an array of non-empty strings`);
+  return [...new Set(value)];
+}
+
+function createOperationGrantAuthority(input = {}) {
+  const publicKeyPem = ensureText(input.publicKeyPem, "publicKeyPem");
+  const authority = {
+    kind: OPERATION_GRANT_AUTHORITY_KIND,
+    version: OPERATION_ROLE_KEY_VERSION,
+    alg: ROLE_ALG,
+    issuer: ensureText(input.issuer, "issuer"),
+    publicKeyPem,
+    publicKeyFingerprint: authorityFingerprint(publicKeyPem),
+    issuedAt: Number.isFinite(input.issuedAt) ? input.issuedAt : Date.now(),
+    ...(typeof input.roomId === "string" && input.roomId.length > 0 ? { roomId: input.roomId } : {}),
+    ...(typeof input.appPackId === "string" && input.appPackId.length > 0 ? { appPackId: input.appPackId } : {}),
+    ...(typeof input.appPackHash === "string" && input.appPackHash.length > 0 ? { appPackHash: input.appPackHash } : {}),
+    ...(Number.isFinite(input.expiresAt) ? { expiresAt: input.expiresAt } : {})
+  };
+  const allowedGrantRoles = optionalStringArray(input.allowedGrantRoles, "allowedGrantRoles")?.map(normalizeOperationKeyRole);
+  if (allowedGrantRoles) authority.allowedGrantRoles = allowedGrantRoles;
+  return authority;
+}
+
+function isOperationGrantAuthority(value, expected = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  if (value.kind !== OPERATION_GRANT_AUTHORITY_KIND || value.version !== OPERATION_ROLE_KEY_VERSION) return false;
+  if (value.alg !== ROLE_ALG) return false;
+  if (typeof value.issuer !== "string" || value.issuer.length === 0) return false;
+  if (typeof value.publicKeyPem !== "string" || value.publicKeyPem.length === 0) return false;
+  if (value.publicKeyFingerprint !== authorityFingerprint(value.publicKeyPem)) return false;
+  if (!Number.isFinite(value.issuedAt)) return false;
+  if (value.expiresAt !== undefined && !Number.isFinite(value.expiresAt)) return false;
+  if (value.roomId !== undefined && (typeof value.roomId !== "string" || value.roomId.length === 0)) return false;
+  if (expected.roomId && value.roomId && value.roomId !== expected.roomId) return false;
+  if (value.appPackId !== undefined && (typeof value.appPackId !== "string" || value.appPackId.length === 0)) return false;
+  if (expected.appPackId && value.appPackId && value.appPackId !== expected.appPackId) return false;
+  if (value.appPackHash !== undefined && (typeof value.appPackHash !== "string" || value.appPackHash.length === 0)) return false;
+  if (expected.appPackHash && value.appPackHash && value.appPackHash !== expected.appPackHash) return false;
+  if (value.allowedGrantRoles !== undefined && (!Array.isArray(value.allowedGrantRoles) || value.allowedGrantRoles.some((role) => role !== "admin" && role !== "user"))) return false;
+  return true;
+}
+
+function authorityArray(authorities) {
+  if (!authorities) return [];
+  if (Array.isArray(authorities)) return authorities;
+  if (authorities instanceof Map) return [...authorities.values()];
+  if (authorities.kind === OPERATION_GRANT_AUTHORITY_KIND) return [authorities];
+  return Object.values(authorities);
+}
+
+function publicOperationGrantAuthority(authority) {
+  const copy = clone(authority);
+  delete copy.privateKeyPem;
+  delete copy.privateKey;
+  delete copy.secret;
+  return copy;
+}
+
+function publicOperationGrantAuthorities(authorities) {
+  return authorityArray(authorities).map(publicOperationGrantAuthority);
+}
+
+module.exports = {
+  authorityArray,
+  authorityFingerprint,
+  createOperationGrantAuthority,
+  generateOperationGrantAuthorityKeyPair,
+  isOperationGrantAuthority,
+  optionalStringArray,
+  publicOperationGrantAuthorities,
+  publicOperationGrantAuthority
+};

package/src/security/roleKeys/authorities/signing.cjs

@@ -0,0 +1,121 @@
+const crypto = require("node:crypto");
+const { clone } = require("../../../shared.cjs");
+const { OPERATION_ROLE_KEY_GRANT_SIGNATURE_KIND, OPERATION_ROLE_KEY_VERSION, ROLE_ALG } = require("../constants.cjs");
+const { canonicalJson } = require("@mh-gg/event/canonicalJson");
+const { ensureText, isOperationRoleKeyGrant } = require("../grants.cjs");
+const { normalizeOperationKeyRole } = require("../roles.cjs");
+const {
+  authorityArray,
+  isOperationGrantAuthority,
+  publicOperationGrantAuthority
+} = require("./shapes.cjs");
+
+function unsignedOperationRoleKeyGrant(grant) {
+  const next = clone(grant);
+  delete next.grantSignature;
+  delete next.privateKeyPem;
+  delete next.privateKey;
+  delete next.secret;
+  return next;
+}
+
+function unsignedGrantSignaturePayload(grant, signatureMeta) {
+  const meta = clone(signatureMeta);
+  delete meta.signature;
+  return {
+    grant: unsignedOperationRoleKeyGrant(grant),
+    grantSignature: meta
+  };
+}
+
+function findAuthorityForSignature(signature, authorities, expected = {}) {
+  return authorityArray(authorities).find((authority) => {
+    if (!isOperationGrantAuthority(authority, expected)) return false;
+    if (signature.issuer !== authority.issuer) return false;
+    if (signature.authorityFingerprint !== authority.publicKeyFingerprint) return false;
+    return true;
+  });
+}
+
+function validateGrantSignatureShape(signature) {
+  if (!signature || typeof signature !== "object" || Array.isArray(signature)) return "Operation role-key grant signature is required.";
+  if (signature.kind !== OPERATION_ROLE_KEY_GRANT_SIGNATURE_KIND) return "Operation role-key grant signature kind is invalid.";
+  if (signature.version !== OPERATION_ROLE_KEY_VERSION) return "Operation role-key grant signature version is invalid.";
+  if (signature.alg !== ROLE_ALG) return "Operation role-key grant signature algorithm is invalid.";
+  if (typeof signature.issuer !== "string" || signature.issuer.length === 0) return "Operation role-key grant signature issuer is invalid.";
+  if (typeof signature.authorityFingerprint !== "string" || signature.authorityFingerprint.length === 0) return "Operation role-key grant signature authority fingerprint is invalid.";
+  if (!Number.isFinite(signature.signedAt)) return "Operation role-key grant signature time is invalid.";
+  if (signature.expiresAt !== undefined && !Number.isFinite(signature.expiresAt)) return "Operation role-key grant signature expiry is invalid.";
+  if (typeof signature.signature !== "string" || signature.signature.length === 0) return "Operation role-key grant signature is invalid.";
+  return undefined;
+}
+
+function signOperationRoleKeyGrant(grant, options = {}) {
+  if (!isOperationRoleKeyGrant(grant)) throw new Error("A valid operation role-key grant is required");
+  const authority = options.authority;
+  if (!isOperationGrantAuthority(authority)) throw new Error("A valid operation grant authority is required");
+  const privateKeyPem = ensureText(options.privateKeyPem || options.privateKey, "privateKeyPem");
+  const role = normalizeOperationKeyRole(grant.role);
+  if (authority.allowedGrantRoles && !authority.allowedGrantRoles.includes(role)) throw new Error("Operation grant authority is not allowed to sign this role");
+  if (authority.roomId && authority.roomId !== grant.roomId) throw new Error("Operation grant authority is for a different room");
+  if (authority.appPackId && authority.appPackId !== grant.appPackId) throw new Error("Operation grant authority is for a different app pack");
+  if (authority.appPackHash && grant.appPackHash && authority.appPackHash !== grant.appPackHash) throw new Error("Operation grant authority is for a different app pack hash");
+  const signedAt = Number.isFinite(options.signedAt) ? options.signedAt : Date.now();
+  const signatureMeta = {
+    kind: OPERATION_ROLE_KEY_GRANT_SIGNATURE_KIND,
+    version: OPERATION_ROLE_KEY_VERSION,
+    alg: ROLE_ALG,
+    issuer: authority.issuer,
+    authorityFingerprint: authority.publicKeyFingerprint,
+    signedAt,
+    ...(Number.isFinite(options.expiresAt) ? { expiresAt: options.expiresAt } : {})
+  };
+  const payload = Buffer.from(canonicalJson(unsignedGrantSignaturePayload(grant, signatureMeta)));
+  return {
+    ...unsignedOperationRoleKeyGrant(grant),
+    grantSignature: {
+      ...signatureMeta,
+      signature: crypto.sign(null, payload, privateKeyPem).toString("base64url")
+    }
+  };
+}
+
+function createSignedOperationRoleKeyGrant(input = {}, options = {}) {
+  const { createOperationRoleKeyGrant } = require("../grants.cjs");
+  return signOperationRoleKeyGrant(createOperationRoleKeyGrant(input), options);
+}
+
+function verifyOperationRoleKeyGrant(grant, authorities, options = {}) {
+  if (!isOperationRoleKeyGrant(grant, options)) return { ok: false, error: "Operation role-key grant is invalid." };
+  const requireSigned = options.requireSignedGrants === true || options.requireSignedGrant === true;
+  const signature = grant.grantSignature;
+  if (!signature) return requireSigned ? { ok: false, error: "Operation role-key grant is not signed by a trusted authority." } : { ok: true, grant: clone(grant) };
+  const shapeError = validateGrantSignatureShape(signature);
+  if (shapeError) return { ok: false, error: shapeError };
+  const authority = findAuthorityForSignature(signature, authorities, options);
+  if (!authority) return { ok: false, error: "Operation role-key grant authority is not trusted." };
+  const now = Number.isFinite(options.now) ? options.now : (typeof options.now === "function" ? options.now() : Date.now());
+  if (authority.expiresAt !== undefined && now > authority.expiresAt) return { ok: false, error: "Operation grant authority has expired." };
+  if (signature.expiresAt !== undefined && now > signature.expiresAt) return { ok: false, error: "Operation role-key grant signature has expired." };
+  if (signature.signedAt < authority.issuedAt) return { ok: false, error: "Operation role-key grant signature predates authority." };
+  if (signature.signedAt < grant.issuedAt) return { ok: false, error: "Operation role-key grant signature predates grant." };
+  const role = normalizeOperationKeyRole(grant.role);
+  if (authority.allowedGrantRoles && !authority.allowedGrantRoles.includes(role)) return { ok: false, error: "Operation grant authority is not allowed to sign this role." };
+  try {
+    const payload = Buffer.from(canonicalJson(unsignedGrantSignaturePayload(grant, signature)));
+    const ok = crypto.verify(null, payload, authority.publicKeyPem, Buffer.from(signature.signature, "base64url"));
+    if (!ok) return { ok: false, error: "Operation role-key grant signature is invalid." };
+  } catch (error) {
+    return { ok: false, error: error?.message || "Operation role-key grant signature verification failed." };
+  }
+  return { ok: true, authority: publicOperationGrantAuthority(authority), grant: clone(grant) };
+}
+
+module.exports = {
+  createSignedOperationRoleKeyGrant,
+  findAuthorityForSignature,
+  signOperationRoleKeyGrant,
+  unsignedOperationRoleKeyGrant,
+  validateGrantSignatureShape,
+  verifyOperationRoleKeyGrant
+};

package/src/security/roleKeys/constants.cjs

@@ -0,0 +1,15 @@
+const OPERATION_GRANT_AUTHORITY_KIND = "matterhorn.operation-grant-authority";
+const OPERATION_ROLE_KEY_GRANT_KIND = "matterhorn.operation-role-key-grant";
+const OPERATION_ROLE_KEY_GRANT_SIGNATURE_KIND = "matterhorn.operation-role-key-grant-signature";
+const OPERATION_ROLE_KEY_PROOF_KIND = "matterhorn.operation-role-key-proof";
+const OPERATION_ROLE_KEY_VERSION = 1;
+const ROLE_ALG = "ed25519";
+
+module.exports = {
+  OPERATION_GRANT_AUTHORITY_KIND,
+  OPERATION_ROLE_KEY_GRANT_KIND,
+  OPERATION_ROLE_KEY_GRANT_SIGNATURE_KIND,
+  OPERATION_ROLE_KEY_PROOF_KIND,
+  OPERATION_ROLE_KEY_VERSION,
+  ROLE_ALG
+};

package/src/security/roleKeys/fingerprints.cjs

@@ -0,0 +1,24 @@
+const crypto = require("node:crypto");
+
+function roleKeyFingerprint(publicKeyPem) {
+  if (typeof publicKeyPem !== "string" || publicKeyPem.length === 0) throw new Error("Operation role public key is required.");
+  return `sha256-${crypto.createHash("sha256").update(publicKeyPem).digest("hex")}`;
+}
+
+function generateOperationRoleKeyPair(options = {}) {
+  const { normalizeOperationKeyRole } = require("./roles.cjs");
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" });
+  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" });
+  return {
+    role: normalizeOperationKeyRole(options.role || "user"),
+    publicKeyPem,
+    privateKeyPem,
+    publicKeyFingerprint: roleKeyFingerprint(publicKeyPem)
+  };
+}
+
+module.exports = {
+  generateOperationRoleKeyPair,
+  roleKeyFingerprint
+};

package/src/security/roleKeys/grants.cjs

@@ -0,0 +1,93 @@
+const { clone } = require("../../shared.cjs");
+const { OPERATION_ROLE_KEY_GRANT_KIND, OPERATION_ROLE_KEY_VERSION, ROLE_ALG } = require("./constants.cjs");
+const { roleKeyFingerprint } = require("./fingerprints.cjs");
+const { normalizeOperationKeyRole } = require("./roles.cjs");
+
+function ensureText(value, label) {
+  if (typeof value !== "string" || value.length === 0) throw new Error(`${label} is required`);
+  return value;
+}
+
+function optionalStringArray(value, label) {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.length === 0)) throw new Error(`${label} must be an array of non-empty strings`);
+  return [...new Set(value)];
+}
+
+function createOperationRoleKeyGrant(input = {}) {
+  const publicKeyPem = ensureText(input.publicKeyPem, "publicKeyPem");
+  const role = normalizeOperationKeyRole(ensureText(input.role, "role"));
+  if (role !== "owner" && role !== "admin" && role !== "moderator" && role !== "user") throw new Error("role must be owner, admin, moderator, or user");
+  const grant = {
+    kind: OPERATION_ROLE_KEY_GRANT_KIND,
+    version: OPERATION_ROLE_KEY_VERSION,
+    alg: ROLE_ALG,
+    credentialId: ensureText(input.credentialId, "credentialId"),
+    roomId: ensureText(input.roomId, "roomId"),
+    appPackId: ensureText(input.appPackId, "appPackId"),
+    role,
+    publicKeyPem,
+    publicKeyFingerprint: roleKeyFingerprint(publicKeyPem),
+    issuedAt: Number.isFinite(input.issuedAt) ? input.issuedAt : Date.now(),
+    ...(typeof input.appPackHash === "string" && input.appPackHash.length > 0 ? { appPackHash: input.appPackHash } : {}),
+    ...(typeof input.memberId === "string" && input.memberId.length > 0 ? { memberId: input.memberId } : {}),
+    ...(typeof input.deviceId === "string" && input.deviceId.length > 0 ? { deviceId: input.deviceId } : {}),
+    ...(Number.isFinite(input.expiresAt) ? { expiresAt: input.expiresAt } : {})
+  };
+  const allowedPluginIds = optionalStringArray(input.allowedPluginIds, "allowedPluginIds");
+  const allowedOperations = optionalStringArray(input.allowedOperations, "allowedOperations");
+  if (allowedPluginIds) grant.allowedPluginIds = allowedPluginIds;
+  if (allowedOperations) grant.allowedOperations = allowedOperations;
+  return grant;
+}
+
+function isOperationRoleKeyGrant(value, expected = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  if (value.kind !== OPERATION_ROLE_KEY_GRANT_KIND || value.version !== OPERATION_ROLE_KEY_VERSION) return false;
+  if (value.alg !== ROLE_ALG) return false;
+  if (value.role !== "owner" && value.role !== "admin" && value.role !== "moderator" && value.role !== "user") return false;
+  if (typeof value.credentialId !== "string" || value.credentialId.length === 0) return false;
+  if (typeof value.roomId !== "string" || value.roomId.length === 0) return false;
+  if (expected.roomId && value.roomId !== expected.roomId) return false;
+  if (typeof value.appPackId !== "string" || value.appPackId.length === 0) return false;
+  if (expected.appPackId && value.appPackId !== expected.appPackId) return false;
+  if (expected.appPackHash && value.appPackHash && value.appPackHash !== expected.appPackHash) return false;
+  if (typeof value.publicKeyPem !== "string" || value.publicKeyPem.length === 0) return false;
+  if (value.publicKeyFingerprint !== roleKeyFingerprint(value.publicKeyPem)) return false;
+  if (!Number.isFinite(value.issuedAt)) return false;
+  if (value.expiresAt !== undefined && !Number.isFinite(value.expiresAt)) return false;
+  if (value.memberId !== undefined && (typeof value.memberId !== "string" || value.memberId.length === 0)) return false;
+  if (value.deviceId !== undefined && (typeof value.deviceId !== "string" || value.deviceId.length === 0)) return false;
+  if (value.allowedPluginIds !== undefined && !Array.isArray(value.allowedPluginIds)) return false;
+  if (value.allowedOperations !== undefined && !Array.isArray(value.allowedOperations)) return false;
+  return true;
+}
+
+function publicOperationRoleKeyGrant(grant) {
+  const copy = clone(grant);
+  delete copy.privateKeyPem;
+  delete copy.privateKey;
+  delete copy.secret;
+  return copy;
+}
+
+function grantArray(grants) {
+  if (!grants) return [];
+  if (Array.isArray(grants)) return grants;
+  if (grants instanceof Map) return [...grants.values()];
+  if (grants.kind === OPERATION_ROLE_KEY_GRANT_KIND) return [grants];
+  return Object.values(grants);
+}
+
+function publicOperationRoleKeyGrants(grants) {
+  return grantArray(grants).map(publicOperationRoleKeyGrant);
+}
+
+module.exports = {
+  createOperationRoleKeyGrant,
+  ensureText,
+  grantArray,
+  isOperationRoleKeyGrant,
+  publicOperationRoleKeyGrant,
+  publicOperationRoleKeyGrants
+};

package/src/security/roleKeys/index.cjs

@@ -0,0 +1,10 @@
+module.exports = {
+  ...require("./authenticator.cjs"),
+  ...require("@mh-gg/event/canonicalJson"),
+  ...require("./constants.cjs"),
+  ...require("./authorities/index.cjs"),
+  ...require("./fingerprints.cjs"),
+  ...require("./grants.cjs"),
+  ...require("./roles.cjs"),
+  ...require("./signatures.cjs")
+};

package/src/security/roleKeys/roles.cjs

@@ -0,0 +1,21 @@
+function normalizeOperationKeyRole(role) {
+  if (role === "owner") return "owner";
+  if (role === "admin") return "admin";
+  if (role === "moderator") return "moderator";
+  if (role === "member" || role === "user") return "user";
+  return role;
+}
+
+function operationKeyRoleToActorRole(role) {
+  const normalized = normalizeOperationKeyRole(role);
+  if (normalized === "owner") return "owner";
+  if (normalized === "admin") return "admin";
+  if (normalized === "moderator") return "moderator";
+  if (normalized === "user") return "member";
+  return normalized;
+}
+
+module.exports = {
+  normalizeOperationKeyRole,
+  operationKeyRoleToActorRole
+};