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

package/test/authorization-gate.test.cjs

@@ -0,0 +1,610 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const { manifestHash } = require("@mh-gg/base");
+const {
+  HostPluginRuntime,
+  CORE_ACCESS_ROLE_ASSIGN_TYPE,
+  CORE_ACCESS_ROLE_DEFINE_TYPE,
+  CORE_ACCESS_ROLE_UNASSIGN_TYPE,
+  CORE_SCOPE_ROLE_SET_TYPE,
+  allow,
+  createMemoryOperationLog,
+  createMemoryRoomStore,
+  createAuthorityState,
+  createRoomStateStandingAuthority,
+  createOperationGrantAuthority,
+  createOperationSchemaDescriptor,
+  createOperationRoleKeyGrant,
+  createRoleKeyAuthenticator,
+  createSignedOperationRoleKeyGrant,
+  defineHostPlugin,
+  deny,
+  generateOperationGrantAuthorityKeyPair,
+  generateOperationRoleKeyPair,
+  normalizeGrantRecord,
+  normalizeRevocationRecord,
+  normalizeScopedRolesState,
+  scopedRoleFromGlobalRole,
+  signOperationWithRoleKey
+} = require("../src/index.cjs");
+const { rebuildStateFromAuthorityLog } = require("../src/runtime/authorityReplay/index.cjs");
+
+const ROOM_ID = "room_authz_gate";
+const APP_PACK = { id: "com.matterhorn.authz", version: "1.0.0", hash: "sha256-authz", protocolHash: "sha256-protocol" };
+const APP_HASH = APP_PACK.hash || manifestHash(APP_PACK);
+const PLUGIN_ID = "com.matterhorn.authz.plugin";
+const AUDIT_PLUGIN_ID = "com.matterhorn.authz.audit";
+
+function schema(parse) { return { parse }; }
+
+function authzPlugin(events = []) {
+  return defineHostPlugin({
+    id: PLUGIN_ID,
+    version: "1.0.0",
+    operationSchemaDescriptor: createOperationSchemaDescriptor({ plugin: PLUGIN_ID, version: "1.0.0", operations: {
+      "admin.write": { authorize: { roles: ["admin"] } },
+      "member.write": { authorize: { roles: ["member"] } },
+      "narrow.write": { authorize: { roles: ["member"] } }
+    } }),
+    schemas: {
+      state: schema((value) => value && typeof value === "object" ? value : { writes: [] }),
+      operations: {
+        "admin.write": schema((payload) => payload || {}),
+        "member.write": schema((payload) => payload || {}),
+        "narrow.write": schema((payload) => payload || {})
+      }
+    },
+    createInitialState() { return { writes: [] }; },
+    authorize(ctx, op) {
+      events.push({ stage: "authorize", type: op.type, role: ctx.actor.role, keyRole: ctx.actor.keyRole, standing: ctx.actor.standing, memberId: ctx.actor.memberId });
+      if (op.type === "narrow.write") return deny("plugin narrowed");
+      return allow();
+    },
+    reduce(ctx, state, op) {
+      events.push({ stage: "reduce", type: op.type, role: ctx.actor.role, keyRole: ctx.actor.keyRole, standing: ctx.actor.standing, memberId: ctx.actor.memberId });
+      return { writes: [...state.writes, { type: op.type, role: ctx.actor.role, keyRole: ctx.actor.keyRole, standing: ctx.actor.standing, memberId: ctx.actor.memberId }] };
+    }
+  });
+}
+
+function auditPlugin(events = []) {
+  return defineHostPlugin({
+    id: AUDIT_PLUGIN_ID,
+    version: "1.0.0",
+    operationSchemaDescriptor: createOperationSchemaDescriptor({ plugin: AUDIT_PLUGIN_ID, version: "1.0.0", operations: { "audit.capture": { authorize: { roles: ["member"] } } } }),
+    schemas: {
+      state: schema((value) => value && typeof value === "object" ? value : { captures: [] }),
+      operations: { "audit.capture": schema((payload) => payload || {}) }
+    },
+    createInitialState() { return { captures: [] }; },
+    authorize(ctx, op) { events.push({ plugin: AUDIT_PLUGIN_ID, stage: "authorize", role: ctx.actor.role, standing: ctx.actor.standing }); return allow(); },
+    reduce(ctx, state, op) { events.push({ plugin: AUDIT_PLUGIN_ID, stage: "reduce", role: ctx.actor.role, standing: ctx.actor.standing }); return { captures: [...state.captures, ctx.actor] }; }
+  });
+}
+
+function scopedPlugin(events = []) {
+  return defineHostPlugin({
+    id: "com.matterhorn.authz.scoped",
+    version: "1.0.0",
+    operationSchemaDescriptor: createOperationSchemaDescriptor({ plugin: "com.matterhorn.authz.scoped", version: "1.0.0", operations: {
+      "board.view": { authorize: { roles: ["member"], scope: { action: "view", scopeType: "board", scopeId: "$payload.boardId" } } },
+      "board.edit": { authorize: { roles: ["member"], scope: { action: "edit", scopeType: "board", scopeId: "$payload.boardId" } } }
+    } }),
+    schemas: {
+      state: schema((value) => value && typeof value === "object" ? value : { edits: [] }),
+      operations: {
+        "board.view": schema((payload) => payload || {}),
+        "board.edit": schema((payload) => payload || {})
+      },
+      publicView: schema((view) => view)
+    },
+    createInitialState() { return { edits: [] }; },
+    authorize(ctx, op) {
+      events.push({ stage: "authorize", type: op.type, scopedRole: ctx.access.roleForScope("board", op.payload.boardId), canView: ctx.access.canView("board", op.payload.boardId), canEdit: ctx.access.canEdit("board", op.payload.boardId) });
+      return allow();
+    },
+    reduce(_ctx, state, op) {
+      return { edits: [...state.edits, op.type] };
+    },
+    getPublicView(ctx, state) {
+      return ctx.access.canView("board", "secret") ? state : { edits: [] };
+    }
+  });
+}
+
+function initialState(overrides = {}) {
+  return {
+    schemaVersion: 1,
+    roomId: ROOM_ID,
+    appPack: { id: APP_PACK.id, hash: APP_HASH, protocolHash: APP_PACK.protocolHash },
+    version: 0,
+    createdAt: 1,
+    updatedAt: 1,
+    members: {
+      alice: { id: "alice", role: "admin" },
+      bob: { id: "bob", role: "member" },
+      mod: { id: "mod", role: "moderator" },
+      demoted: { id: "demoted", role: "member" },
+      banned: { id: "banned", role: "member", bannedAt: 900 }
+    },
+    revokedCredentialIds: [],
+    guests: {},
+    pluginVersions: {},
+    plugins: {},
+    seenOperations: [],
+    ...overrides
+  };
+}
+
+function makeKeys() {
+  const authorityKey = generateOperationGrantAuthorityKeyPair({ issuer: "room-owner" });
+  const authority = createOperationGrantAuthority({
+    issuer: authorityKey.issuer,
+    roomId: ROOM_ID,
+    appPackId: APP_PACK.id,
+    appPackHash: APP_HASH,
+    publicKeyPem: authorityKey.publicKeyPem,
+    issuedAt: 1
+  });
+  function grantFor(memberId, role, credentialId = `${memberId}_cred`) {
+    const key = generateOperationRoleKeyPair({ role });
+    const unsigned = createOperationRoleKeyGrant({
+      roomId: ROOM_ID,
+      appPackId: APP_PACK.id,
+      appPackHash: APP_HASH,
+      credentialId,
+      memberId,
+      deviceId: `dev_${memberId}`,
+      role,
+      publicKeyPem: key.publicKeyPem,
+      issuedAt: 2,
+      expiresAt: 10_000
+    });
+    return { key, grant: createSignedOperationRoleKeyGrant(unsigned, { authority, privateKeyPem: authorityKey.privateKeyPem, signedAt: 3 }) };
+  }
+  const alice = grantFor("alice", "admin");
+  const bob = grantFor("bob", "user");
+  const mod = grantFor("mod", "moderator");
+  const demoted = grantFor("demoted", "admin");
+  const banned = grantFor("banned", "user");
+  const revoked = grantFor("bob", "user", "revoked_cred");
+  return { authority, grants: [alice.grant, bob.grant, mod.grant, demoted.grant, banned.grant, revoked.grant], alice, bob, mod, demoted, banned, revoked };
+}
+
+function createRuntime({ keys = makeKeys(), state = initialState(), plugins, standingAuthority } = {}) {
+  const events = [];
+  const runtime = new HostPluginRuntime({
+    room: { id: ROOM_ID, appPack: APP_PACK },
+    plugins: plugins || [authzPlugin(events), auditPlugin(events)],
+    store: createMemoryRoomStore(state),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: createRoleKeyAuthenticator({
+      roomId: ROOM_ID,
+      appPackId: APP_PACK.id,
+      appPackHash: APP_HASH,
+      grants: keys.grants,
+      grantAuthorities: [keys.authority],
+      requireSignedGrants: true,
+      now: () => 100
+    }),
+    ...(standingAuthority ? { standingAuthority } : {})
+  });
+  return { runtime, events, keys };
+}
+
+function unsignedOperation(memberId, type, pluginId = PLUGIN_ID, overrides = {}) {
+  return {
+    id: overrides.id || `op_${memberId}_${type.replace(/[^a-zA-Z0-9]/g, "_")}`,
+    roomId: ROOM_ID,
+    appPackId: APP_PACK.id,
+    appPackHash: APP_HASH,
+    pluginId,
+    type,
+    actor: { memberId, deviceId: `dev_${memberId}`, role: overrides.claimedRole || "member" },
+    seq: overrides.seq || 1,
+    createdAt: overrides.createdAt || 1000,
+    payload: overrides.payload || {},
+    auth: { credentialId: overrides.credentialId || `${memberId}_cred`, signature: "placeholder" }
+  };
+}
+
+function sign(op, keyPair, grant) {
+  return signOperationWithRoleKey(op, { privateKeyPem: keyPair.privateKeyPem, grant, now: () => op.createdAt });
+}
+
+async function run(runtime, op) {
+  await runtime.start();
+  return runtime.handleOperation(op);
+}
+
+test("core gate denies a banned member even with a valid unexpired operation grant", async () => {
+  const { runtime, keys } = createRuntime();
+  const op = sign(unsignedOperation("banned", "member.write"), keys.banned.key, keys.banned.grant);
+  const result = await run(runtime, op);
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /banned|active|standing/i);
+});
+
+test("core gate denies a revoked credential without banning the member", async () => {
+  const keys = makeKeys();
+  const { runtime } = createRuntime({ keys, state: initialState({ revokedCredentialIds: ["revoked_cred"] }) });
+  const op = sign(unsignedOperation("bob", "member.write", PLUGIN_ID, { credentialId: "revoked_cred" }), keys.revoked.key, keys.revoked.grant);
+  const result = await run(runtime, op);
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /revoked|active|standing/i);
+});
+
+test("effective role is current standing role, not the grant ceiling", async () => {
+  const { runtime, keys, events } = createRuntime();
+  const deniedAdmin = await run(runtime, sign(unsignedOperation("demoted", "admin.write", PLUGIN_ID, { claimedRole: "admin" }), keys.demoted.key, keys.demoted.grant));
+  assert.equal(deniedAdmin.ok, false);
+  assert.match(deniedAdmin.reason, /role|admin|Forbidden/i);
+
+  const allowedMember = await run(runtime, sign(unsignedOperation("demoted", "member.write", PLUGIN_ID, { id: "op_demoted_member", seq: 2, claimedRole: "admin" }), keys.demoted.key, keys.demoted.grant));
+  assert.equal(allowedMember.ok, true);
+  assert.deepEqual(events.filter((entry) => entry.stage === "reduce").at(-1), {
+    stage: "reduce",
+    type: "member.write",
+    role: "member",
+    keyRole: "admin",
+    standing: "active",
+    memberId: "demoted"
+  });
+});
+
+test("hand-written plugin authorize cannot widen access beyond declared roles", async () => {
+  const { runtime, keys } = createRuntime();
+  const op = sign(unsignedOperation("bob", "admin.write", PLUGIN_ID, { claimedRole: "admin" }), keys.bob.key, keys.bob.grant);
+  const result = await run(runtime, op);
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /role|admin|Forbidden/i);
+});
+
+test("operation descriptors without authorize.roles fail during plugin registration", () => {
+  assert.throws(() => defineHostPlugin({
+    id: "com.matterhorn.authz.bad-policy",
+    version: "1.0.0",
+    operationSchemaDescriptor: createOperationSchemaDescriptor({
+      plugin: "com.matterhorn.authz.bad-policy",
+      version: "1.0.0",
+      operations: { "missing-policy.write": { required: ["value"] } }
+    }),
+    schemas: {
+      state: schema((value) => value && typeof value === "object" ? value : { writes: [] }),
+      operations: { "missing-policy.write": schema((payload) => payload || {}) }
+    },
+    createInitialState() { return { writes: [] }; },
+    authorize() { return allow(); },
+    reduce(_ctx, state) { return state; }
+  }), /authorize\.roles|OPERATION_ROLE_POLICY_MISSING/);
+});
+
+test("plugin authorize is narrowing-only", async () => {
+  const { runtime, keys } = createRuntime();
+  const op = sign(unsignedOperation("bob", "narrow.write", PLUGIN_ID), keys.bob.key, keys.bob.grant);
+  const result = await run(runtime, op);
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /plugin narrowed/);
+});
+
+test("standing authority failure denies before plugin code runs", async () => {
+  const events = [];
+  const keys = makeKeys();
+  const runtime = new HostPluginRuntime({
+    room: { id: ROOM_ID, appPack: APP_PACK },
+    plugins: [authzPlugin(events)],
+    store: createMemoryRoomStore(initialState()),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: createRoleKeyAuthenticator({ roomId: ROOM_ID, appPackId: APP_PACK.id, appPackHash: APP_HASH, grants: keys.grants, grantAuthorities: [keys.authority], requireSignedGrants: true, now: () => 100 }),
+    standingAuthority: { evaluate() { throw new Error("standing db offline"); } }
+  });
+  const op = sign(unsignedOperation("alice", "admin.write", PLUGIN_ID, { claimedRole: "admin" }), keys.alice.key, keys.alice.grant);
+  const result = await run(runtime, op);
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /standing|offline|unavailable/i);
+  assert.deepEqual(events, []);
+});
+
+test("ctx.actor carries active standing and effective role across plugins", async () => {
+  const { runtime, keys, events } = createRuntime();
+  const op = sign(unsignedOperation("bob", "audit.capture", AUDIT_PLUGIN_ID), keys.bob.key, keys.bob.grant);
+  const result = await run(runtime, op);
+  assert.equal(result.ok, true, result.reason);
+  assert.deepEqual(events.filter((entry) => entry.plugin === AUDIT_PLUGIN_ID), [
+    { plugin: AUDIT_PLUGIN_ID, stage: "authorize", role: "member", standing: "active" },
+    { plugin: AUDIT_PLUGIN_ID, stage: "reduce", role: "member", standing: "active" }
+  ]);
+});
+
+test("profile-only member records do not make open rooms explicit-membership rooms", async () => {
+  const { runtime, keys } = createRuntime({
+    state: initialState({
+      members: {
+        alice: { id: "alice", memberId: "alice", role: "member", displayName: "Alice", profileOnly: true }
+      }
+    }),
+    standingAuthority: createRoomStateStandingAuthority()
+  });
+  const op = sign(unsignedOperation("bob", "member.write", PLUGIN_ID, {
+    id: "op_bob_profile_only_room",
+    createdAt: 1001
+  }), keys.bob.key, keys.bob.grant);
+
+  const result = await run(runtime, op);
+
+  assert.equal(result.ok, true, result.reason);
+  const state = await runtime.getState();
+  assert.equal(state.members.alice.profileOnly, true);
+  assert.equal(state.members.bob, undefined);
+});
+
+test("core credential revocation operation kills a specific grant before expiry", async () => {
+  const { runtime, keys } = createRuntime();
+  const revoke = sign(unsignedOperation("alice", "credential.revoke", "matterhorn.core", {
+    id: "op_revoke_bob",
+    claimedRole: "admin",
+    payload: { credentialId: "bob_cred" }
+  }), keys.alice.key, keys.alice.grant);
+  assert.equal((await run(runtime, revoke)).ok, true);
+
+  const bobWrite = sign(unsignedOperation("bob", "member.write", PLUGIN_ID, { id: "op_bob_after_revoke", seq: 2 }), keys.bob.key, keys.bob.grant);
+  const result = await runtime.handleOperation(bobWrite);
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /revoked|active|standing/i);
+});
+
+test("core scoped roles gate view and edit before plugin code can widen access", async () => {
+  const keys = makeKeys();
+  const events = [];
+  const runtime = new HostPluginRuntime({
+    room: { id: ROOM_ID, appPack: APP_PACK },
+    plugins: [scopedPlugin(events)],
+    store: createMemoryRoomStore(initialState()),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: createRoleKeyAuthenticator({ roomId: ROOM_ID, appPackId: APP_PACK.id, appPackHash: APP_HASH, grants: keys.grants, grantAuthorities: [keys.authority], requireSignedGrants: true, now: () => 100 })
+  });
+  await runtime.start();
+
+  const bobEditOpen = sign(unsignedOperation("bob", "board.edit", "com.matterhorn.authz.scoped", { payload: { boardId: "secret" } }), keys.bob.key, keys.bob.grant);
+  assert.equal((await runtime.handleOperation(bobEditOpen)).ok, true);
+
+  const restrict = sign(unsignedOperation("alice", CORE_SCOPE_ROLE_SET_TYPE, "matterhorn.core", {
+    id: "op_scope_restrict",
+    seq: 2,
+    claimedRole: "admin",
+    payload: { scopeType: "board", scopeId: "secret", defaultRole: "none" }
+  }), keys.alice.key, keys.alice.grant);
+  assert.equal((await runtime.handleOperation(restrict)).ok, true);
+
+  const deniedView = await runtime.handleOperation(sign(unsignedOperation("bob", "board.view", "com.matterhorn.authz.scoped", { id: "op_bob_view_denied", seq: 3, payload: { boardId: "secret" } }), keys.bob.key, keys.bob.grant));
+  assert.equal(deniedView.ok, false);
+  assert.match(deniedView.reason, /view access/);
+
+  const defineViewer = sign(unsignedOperation("alice", CORE_ACCESS_ROLE_DEFINE_TYPE, "matterhorn.core", {
+    id: "op_access_role_define",
+    seq: 4,
+    claimedRole: "admin",
+    payload: { roleId: "board-viewer", name: "Board viewer", grants: [{ scopeType: "board", scopeId: "secret", role: "viewer" }] }
+  }), keys.alice.key, keys.alice.grant);
+  assert.equal((await runtime.handleOperation(defineViewer)).ok, true);
+  const assignViewer = sign(unsignedOperation("alice", CORE_ACCESS_ROLE_ASSIGN_TYPE, "matterhorn.core", {
+    id: "op_access_role_assign",
+    seq: 5,
+    claimedRole: "admin",
+    payload: { target: "bob", roleId: "board-viewer" }
+  }), keys.alice.key, keys.alice.grant);
+  assert.equal((await runtime.handleOperation(assignViewer)).ok, true);
+  const scopedAfterAssignment = (await runtime.getState()).scopedRoles;
+  assert.equal(scopedAfterAssignment.roles["board-viewer"].authority.id, defineViewer.id);
+  assert.equal(scopedAfterAssignment.roles["board-viewer"].authority.grantedBy, "alice");
+  assert.equal(scopedAfterAssignment.assignmentGrants.bob["board-viewer"], assignViewer.id);
+  assert.equal(scopedAfterAssignment.grants[assignViewer.id].credentialId, "alice_cred");
+  assert.equal(typeof scopedAfterAssignment.grants[assignViewer.id].signature, "string");
+
+  const allowedView = await runtime.handleOperation(sign(unsignedOperation("bob", "board.view", "com.matterhorn.authz.scoped", { id: "op_bob_view_ok", seq: 6, payload: { boardId: "secret" } }), keys.bob.key, keys.bob.grant));
+  assert.equal(allowedView.ok, true);
+  const deniedEdit = await runtime.handleOperation(sign(unsignedOperation("bob", "board.edit", "com.matterhorn.authz.scoped", { id: "op_bob_edit_denied", seq: 7, payload: { boardId: "secret" } }), keys.bob.key, keys.bob.grant));
+  assert.equal(deniedEdit.ok, false);
+  assert.match(deniedEdit.reason, /edit access/);
+
+  const grantEditor = sign(unsignedOperation("alice", CORE_SCOPE_ROLE_SET_TYPE, "matterhorn.core", {
+    id: "op_scope_editor",
+    seq: 8,
+    claimedRole: "admin",
+    payload: { scopeType: "board", scopeId: "secret", target: "bob", role: "editor" }
+  }), keys.alice.key, keys.alice.grant);
+  assert.equal((await runtime.handleOperation(grantEditor)).ok, true);
+  const allowedEdit = await runtime.handleOperation(sign(unsignedOperation("bob", "board.edit", "com.matterhorn.authz.scoped", { id: "op_bob_edit_ok", seq: 9, payload: { boardId: "secret" } }), keys.bob.key, keys.bob.grant));
+  assert.equal(allowedEdit.ok, true);
+
+  const defineChannelRole = sign(unsignedOperation("alice", CORE_ACCESS_ROLE_DEFINE_TYPE, "matterhorn.core", {
+    id: "op_channel_role_define",
+    seq: 10,
+    claimedRole: "admin",
+    payload: {
+      roleId: "channel-limited",
+      name: "Channel limited",
+      grants: [
+        { scopeType: "voice.channel", scopeId: "d", role: "none" },
+        { scopeType: "voice.channel", scopeId: "e", role: "editor" },
+        { scopeType: "text.channel", scopeId: "f", role: "viewer" }
+      ]
+    }
+  }), keys.alice.key, keys.alice.grant);
+  assert.equal((await runtime.handleOperation(defineChannelRole)).ok, true);
+  const assignChannelRole = sign(unsignedOperation("alice", CORE_ACCESS_ROLE_ASSIGN_TYPE, "matterhorn.core", {
+    id: "op_channel_role_assign",
+    seq: 11,
+    claimedRole: "admin",
+    payload: { target: "bob", roleId: "channel-limited" }
+  }), keys.alice.key, keys.alice.grant);
+  assert.equal((await runtime.handleOperation(assignChannelRole)).ok, true);
+  const denyTextC = sign(unsignedOperation("alice", CORE_SCOPE_ROLE_SET_TYPE, "matterhorn.core", {
+    id: "op_text_c_deny",
+    seq: 12,
+    claimedRole: "admin",
+    payload: { scopeType: "text.channel", scopeId: "c", target: "bob", role: "none" }
+  }), keys.alice.key, keys.alice.grant);
+  assert.equal((await runtime.handleOperation(denyTextC)).ok, true);
+
+  const bobView = await runtime.publicView({ memberId: "bob", deviceId: "dev_bob", role: "member" });
+  assert.equal(bobView.access.scopes["text.channel:c"].canView, false);
+  assert.equal(bobView.access.scopes["voice.channel:d"].canView, false);
+  assert.equal(bobView.access.scopes["voice.channel:e"].canEdit, true);
+  assert.equal(bobView.access.scopes["text.channel:f"].canView, true);
+  assert.equal(bobView.access.scopes["text.channel:f"].canEdit, false);
+
+  const guestView = await runtime.publicView({ memberId: "guest", deviceId: "dev_guest", role: "guest" });
+  assert.deepEqual(guestView.plugins["com.matterhorn.authz.scoped"], { edits: [] });
+  assert.equal(guestView.access.scopes["board:secret"].canView, false);
+  assert.equal(events.some((entry) => entry.type === "board.edit" && entry.scopedRole === "editor"), true);
+});
+
+test("moderators cannot assign compound roles above moderator scope", async () => {
+  const keys = makeKeys();
+  const { runtime } = createRuntime({ keys, plugins: [scopedPlugin()] });
+  await runtime.start();
+
+  const defineAdminRole = sign(unsignedOperation("alice", CORE_ACCESS_ROLE_DEFINE_TYPE, "matterhorn.core", {
+    id: "op_admin_scoped_role_define",
+    seq: 2,
+    claimedRole: "admin",
+    payload: {
+      roleId: "board-admin",
+      name: "Board admin",
+      grants: [{ scopeType: "board", scopeId: "secret", role: "admin" }]
+    }
+  }), keys.alice.key, keys.alice.grant);
+  assert.equal((await runtime.handleOperation(defineAdminRole)).ok, true);
+
+  const assignAdminRole = sign(unsignedOperation("mod", CORE_ACCESS_ROLE_ASSIGN_TYPE, "matterhorn.core", {
+    id: "op_mod_assign_admin_scoped_role",
+    seq: 3,
+    claimedRole: "moderator",
+    payload: { target: "bob", roleId: "board-admin" }
+  }), keys.mod.key, keys.mod.grant);
+  const result = await runtime.handleOperation(assignAdminRole);
+  assert.equal(result.ok, false);
+  assert.match(result.reason, /above moderator|Forbidden/i);
+});
+
+test("authority replay preserves scoped role operations", async () => {
+  const keys = makeKeys();
+  const { runtime } = createRuntime({ keys, plugins: [scopedPlugin()] });
+  await runtime.start();
+
+  const ops = [
+    sign(unsignedOperation("alice", CORE_SCOPE_ROLE_SET_TYPE, "matterhorn.core", {
+      id: "op_replay_scope_restrict",
+      seq: 2,
+      claimedRole: "admin",
+      createdAt: 1002,
+      payload: { scopeType: "board", scopeId: "secret", defaultRole: "none" }
+    }), keys.alice.key, keys.alice.grant),
+    sign(unsignedOperation("alice", CORE_ACCESS_ROLE_DEFINE_TYPE, "matterhorn.core", {
+      id: "op_replay_role_define",
+      seq: 3,
+      claimedRole: "admin",
+      createdAt: 1003,
+      payload: { roleId: "board-viewer", grants: [{ scopeType: "board", scopeId: "secret", role: "viewer" }] }
+    }), keys.alice.key, keys.alice.grant),
+    sign(unsignedOperation("alice", CORE_ACCESS_ROLE_ASSIGN_TYPE, "matterhorn.core", {
+      id: "op_replay_role_assign",
+      seq: 4,
+      claimedRole: "admin",
+      createdAt: 1004,
+      payload: { target: "bob", roleId: "board-viewer" }
+    }), keys.alice.key, keys.alice.grant),
+    sign(unsignedOperation("alice", CORE_ACCESS_ROLE_UNASSIGN_TYPE, "matterhorn.core", {
+      id: "op_replay_role_unassign",
+      seq: 5,
+      claimedRole: "admin",
+      createdAt: 1005,
+      payload: { target: "bob", roleId: "board-viewer" }
+    }), keys.alice.key, keys.alice.grant)
+  ];
+
+  const rebuilt = await rebuildStateFromAuthorityLog(runtime, initialState({ authority: createAuthorityState({ ownerIds: ["alice"] }) }), ops);
+  assert.equal(rebuilt.scopedRoles.scopes["board:secret"].defaultRole, "none");
+  assert.equal(rebuilt.scopedRoles.roles["board-viewer"].grants[0].role, "viewer");
+  assert.equal(rebuilt.scopedRoles.roles["board-viewer"].authority.id, ops[1].id);
+  assert.equal(rebuilt.scopedRoles.assignmentGrants.bob, undefined);
+  assert.equal(rebuilt.scopedRoles.revocations[ops[3].id].voidGrantIds[0], ops[2].id);
+  assert.equal(rebuilt.scopedRoles.assignments.bob, undefined);
+});
+
+test("scoped role metadata normalization preserves signed grant records", () => {
+  assert.equal(scopedRoleFromGlobalRole("guest"), "none");
+  assert.equal(normalizeGrantRecord(null), undefined);
+  assert.equal(normalizeRevocationRecord([]), undefined);
+
+  assert.deepEqual(normalizeGrantRecord({
+    operationId: "op_define",
+    actorId: "admin",
+    action: "access.role.define",
+    scopeType: "board",
+    scopeId: "secret",
+    defaultRole: "viewer",
+    grantedAt: "bad",
+    credentialId: "cred_admin",
+    signature: "sig_admin"
+  }), {
+    id: "op_define",
+    action: "access.role.define",
+    scopeType: "board",
+    scopeId: "secret",
+    defaultRole: "viewer",
+    grantedBy: "admin",
+    grantedAt: 0,
+    credentialId: "cred_admin",
+    signature: "sig_admin"
+  });
+
+  assert.deepEqual(normalizeRevocationRecord({
+    operationId: "op_revoke",
+    actorId: "admin",
+    target: "bob",
+    roleId: "board-viewer",
+    voidGrantIds: ["op_assign", "", 2],
+    revokedAt: "bad",
+    credentialId: "cred_admin",
+    signature: "sig_admin"
+  }), {
+    id: "op_revoke",
+    action: "revoke",
+    target: "bob",
+    roleId: "board-viewer",
+    voidGrantIds: ["op_assign"],
+    revokedBy: "admin",
+    revokedAt: 0,
+    credentialId: "cred_admin",
+    signature: "sig_admin"
+  });
+
+  const normalized = normalizeScopedRolesState({
+    roles: {
+      "board-viewer": {
+        id: "board-viewer",
+        grants: [{ scopeType: "board", scopeId: "secret", role: "viewer" }],
+        authority: { operationId: "op_define", actorId: "admin" }
+      }
+    },
+    assignments: { bob: ["board-viewer", "missing-role"] },
+    grants: {
+      op_assign: { operationId: "op_assign", actorId: "admin", target: "bob", roleId: "board-viewer" }
+    },
+    revocations: {
+      op_revoke: { operationId: "op_revoke", actorId: "admin", target: "bob", roleId: "board-viewer", voidGrantIds: ["op_assign"] }
+    },
+    assignmentGrants: {
+      bob: { "board-viewer": "op_assign", missing: "op_missing" },
+      broken: null,
+      array: []
+    }
+  });
+
+  assert.deepEqual(normalized.assignments.bob, ["board-viewer"]);
+  assert.equal(normalized.roles["board-viewer"].authority.id, "op_define");
+  assert.equal(normalized.assignmentGrants.bob["board-viewer"], "op_assign");
+  assert.deepEqual(normalized.revocations.op_revoke.voidGrantIds, ["op_assign"]);
+});