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

package/test/operation-descriptor-policy.test.cjs

@@ -0,0 +1,140 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const {
+  HostPluginRuntime,
+  allow,
+  createMemoryOperationLog,
+  createMemoryRoomStore,
+  createOperationSchemaDescriptor,
+  defineHostPlugin,
+  declaredRolesForOperation,
+  operationDescriptor
+} = require("..");
+const { ensureOperationIdentity } = require("@mh-gg/protocol");
+
+const ROOM = {
+  id: "room_policy",
+  appPack: { id: "app.policy", hash: "sha256-policy" }
+};
+
+function stateSchema() {
+  return { parse(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : { items: [] }; } };
+}
+
+function payloadSchema() {
+  return { parse(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : {}; } };
+}
+
+function validPlugin(overrides = {}) {
+  return defineHostPlugin({
+    id: overrides.id || "policy.plugin",
+    version: "1.0.0",
+    schemas: {
+      state: stateSchema(),
+      operations: overrides.operations || { "thing.create": payloadSchema() }
+    },
+    operationSchemaDescriptor: overrides.operationSchemaDescriptor || createOperationSchemaDescriptor({
+      plugin: overrides.id || "policy.plugin",
+      version: "1.0.0",
+      operations: {
+        "thing.create": { authorize: { roles: ["member"] } }
+      }
+    }),
+    createInitialState() { return { items: [] }; },
+    authorize() { return allow(); },
+    reduce(_ctx, state) { return { ...state, items: [...(state.items || []), "ok"] }; }
+  });
+}
+
+function runtimeFor(plugin) {
+  return new HostPluginRuntime({
+    room: ROOM,
+    plugins: [plugin],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor
+  });
+}
+
+function operation(type = "thing.create", overrides = {}) {
+  const op = {
+    id: `op_${type.replace(/[^a-z0-9]+/gi, "_")}_${overrides.seq || 1}`,
+    roomId: ROOM.id,
+    appPackId: ROOM.appPack.id,
+    appPackHash: ROOM.appPack.hash,
+    pluginId: "policy.plugin",
+    type,
+    actor: { memberId: "member", deviceId: "dev", role: "member" },
+    seq: overrides.seq || 1,
+    createdAt: 1000 + (overrides.seq || 1),
+    payload: {},
+    auth: { credentialId: "cred", signature: "sig" },
+    ...overrides
+  };
+  return ensureOperationIdentity(op, { nodeId: op.actor.deviceId, now: op.createdAt });
+}
+
+test("valid plugins expose one canonical operation descriptor shape", () => {
+  const plugin = validPlugin();
+  assert.deepEqual(operationDescriptor(plugin, "thing.create"), { authorize: { roles: ["member"] } });
+  assert.deepEqual(declaredRolesForOperation(plugin, "thing.create"), ["member"]);
+});
+
+test("plugin registration rejects operations without canonical authorize.roles", () => {
+  assert.throws(() => validPlugin({
+    operationSchemaDescriptor: createOperationSchemaDescriptor({
+      plugin: "policy.plugin",
+      version: "1.0.0",
+      operations: { "thing.create": { required: ["title"] } }
+    })
+  }), /authorize\.roles|OPERATION_ROLE_POLICY_MISSING/);
+});
+
+test("plugin registration rejects legacy flat operation descriptors", () => {
+  assert.throws(() => validPlugin({
+    operationSchemaDescriptor: { "thing.create": { authorize: { roles: ["member"] } } }
+  }), /operationSchemaDescriptor\.operations|canonical/i);
+});
+
+test("plugin registration rejects alternate descriptor shapes instead of falling back", () => {
+  assert.throws(() => defineHostPlugin({
+    id: "policy.plugin",
+    version: "1.0.0",
+    operationPolicyDescriptor: { "thing.create": { authorize: { roles: ["member"] } } },
+    schemas: { state: stateSchema(), operations: { "thing.create": payloadSchema() } },
+    createInitialState() { return { items: [] }; },
+    authorize() { return allow(); },
+    reduce(_ctx, state) { return state; }
+  }), /operationSchemaDescriptor|canonical/i);
+});
+
+test("canonical descriptor entries must match schemas.operations exactly", () => {
+  assert.throws(() => validPlugin({
+    operationSchemaDescriptor: createOperationSchemaDescriptor({
+      plugin: "policy.plugin",
+      version: "1.0.0",
+      operations: {
+        "thing.create": { authorize: { roles: ["member"] } },
+        "thing.extra": { authorize: { roles: ["member"] } }
+      }
+    })
+  }), /thing\.extra|schemas\.operations/);
+
+  assert.throws(() => validPlugin({
+    operations: { "thing.create": payloadSchema(), "thing.delete": payloadSchema() },
+    operationSchemaDescriptor: createOperationSchemaDescriptor({
+      plugin: "policy.plugin",
+      version: "1.0.0",
+      operations: { "thing.create": { authorize: { roles: ["member"] } } }
+    })
+  }), /thing\.delete|authorize\.roles/);
+});
+
+test("unknown operation attacks produce routine unknown-operation denial, not missing policy", async () => {
+  const runtime = runtimeFor(validPlugin());
+  const result = await runtime.handleOperation(operation("thing.unknown"));
+  assert.equal(result.ok, false);
+  assert.equal(result.code, "UNKNOWN_OPERATION_TYPE");
+  assert.doesNotMatch(result.reason, /authorize\.roles|role policy/i);
+});

package/test/role-key-auth.test.cjs

@@ -0,0 +1,289 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { manifestHash } = require("@mh-gg/base");
+const {
+  HostPluginRuntime,
+  createMemoryOperationLog,
+  createMemoryRoomStore,
+  createOperationRoleKeyGrant,
+  createRoleKeyAuthenticator,
+  generateOperationRoleKeyPair,
+  publicOperationRoleKeyGrant,
+  signOperationWithRoleKey,
+  verifyOperationRoleKey,
+  operationKeyRoleToActorRole
+} = require("../src/index.cjs");
+const { kanbanAppPack, kanbanHostPlugin, KANBAN_PLUGIN_ID } = require("../../../examples/kanban/src/sdk-app.mjs");
+
+const ROOM_ID = "room_role_keys";
+const APP_HASH = manifestHash(kanbanAppPack);
+
+function actor(role = "member", memberId = "member") {
+  return { memberId, deviceId: `dev_${memberId}`, role, displayName: memberId };
+}
+
+function operation(overrides = {}) {
+  return {
+    id: overrides.id || "op_1",
+    roomId: ROOM_ID,
+    appPackId: kanbanAppPack.id,
+    appPackHash: APP_HASH,
+    pluginId: overrides.pluginId || KANBAN_PLUGIN_ID,
+    type: overrides.type || "list.create",
+    actor: overrides.actor || actor("admin", "admin"),
+    seq: overrides.seq || 1,
+    createdAt: overrides.createdAt || 1000,
+    payload: overrides.payload || { title: "Backlog" },
+    auth: { credentialId: overrides.credentialId || "cred_placeholder", signature: "placeholder" },
+    ...overrides
+  };
+}
+
+function signedOperation(op, key, grant, overrides = {}) {
+  return signOperationWithRoleKey({ ...op, auth: { credentialId: grant.credentialId } }, {
+    privateKeyPem: key.privateKeyPem,
+    grant,
+    now: () => op.createdAt || 1000,
+    ...overrides
+  });
+}
+
+function initialMembersFromGrants(grants) {
+  return Object.fromEntries(grants.filter((grant) => grant.memberId).map((grant) => [grant.memberId, { id: grant.memberId, role: operationKeyRoleToActorRole(grant.role), credentialId: grant.credentialId, deviceId: grant.deviceId }]));
+}
+
+async function startRuntime(grants, now = () => 5000) {
+  const runtime = new HostPluginRuntime({
+    room: {
+      id: ROOM_ID,
+      appPack: {
+        id: kanbanAppPack.id,
+        version: kanbanAppPack.version,
+        hash: APP_HASH,
+        protocolHash: kanbanAppPack.compatibility.appProtocolHash
+      }
+    },
+    plugins: [kanbanHostPlugin],
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    initialMembers: initialMembersFromGrants(grants),
+    authenticateActor: createRoleKeyAuthenticator({
+      roomId: ROOM_ID,
+      appPackId: kanbanAppPack.id,
+      appPackHash: APP_HASH,
+      grants,
+      now
+    })
+  });
+  await runtime.start();
+  return runtime;
+}
+
+test("role-key authenticator prevents a user key from claiming admin operations", async () => {
+  const adminKey = generateOperationRoleKeyPair({ role: "admin" });
+  const userKey = generateOperationRoleKeyPair({ role: "user" });
+  const adminGrant = createOperationRoleKeyGrant({
+    roomId: ROOM_ID,
+    appPackId: kanbanAppPack.id,
+    appPackHash: APP_HASH,
+    credentialId: "admin_cred",
+    memberId: "alice",
+    deviceId: "dev_alice",
+    role: "admin",
+    publicKeyPem: adminKey.publicKeyPem,
+    issuedAt: 100
+  });
+  const userGrant = createOperationRoleKeyGrant({
+    roomId: ROOM_ID,
+    appPackId: kanbanAppPack.id,
+    appPackHash: APP_HASH,
+    credentialId: "user_cred",
+    memberId: "bob",
+    deviceId: "dev_bob",
+    role: "user",
+    publicKeyPem: userKey.publicKeyPem,
+    issuedAt: 100
+  });
+  const runtime = await startRuntime([adminGrant, userGrant]);
+
+  const forgedAdmin = signedOperation(operation({
+    id: "op_forged_admin",
+    actor: actor("admin", "bob")
+  }), userKey, userGrant);
+  const rejected = await runtime.handleOperation(forgedAdmin);
+  assert.equal(rejected.ok, false);
+  assert.match(rejected.reason, /Admins only|Forbidden|Operation is not allowed|requires admin/);
+
+  const adminList = signedOperation(operation({ id: "op_admin_list", actor: actor("admin", "alice") }), adminKey, adminGrant);
+  assert.equal((await runtime.handleOperation(adminList)).ok, true);
+
+  const state = await runtime.getState();
+  const listId = state.plugins[KANBAN_PLUGIN_ID].lists[0].id;
+  const userCard = signedOperation(operation({
+    id: "op_user_card",
+    seq: 2,
+    type: "card.create",
+    actor: actor("admin", "bob"),
+    payload: { listId, title: "User can write member operation" },
+    createdAt: 1001
+  }), userKey, userGrant);
+  assert.equal((await runtime.handleOperation(userCard)).ok, true);
+
+  const finalState = await runtime.getState();
+  const cardId = finalState.plugins[KANBAN_PLUGIN_ID].lists[0].cardIds[0];
+  assert.equal(finalState.plugins[KANBAN_PLUGIN_ID].cards[cardId].title, "User can write member operation");
+});
+
+test("role-key signatures reject tampering, wrong room, and expired grants", async () => {
+  const key = generateOperationRoleKeyPair({ role: "admin" });
+  const grant = createOperationRoleKeyGrant({
+    roomId: ROOM_ID,
+    appPackId: kanbanAppPack.id,
+    appPackHash: APP_HASH,
+    credentialId: "admin_cred",
+    memberId: "alice",
+    role: "admin",
+    publicKeyPem: key.publicKeyPem,
+    issuedAt: 100,
+    expiresAt: 10000
+  });
+  const signed = signedOperation(operation({ id: "op_valid", actor: actor("admin", "alice") }), key, grant);
+  assert.equal(verifyOperationRoleKey(signed, [grant], { now: 5000 }).ok, true);
+
+  const tampered = { ...signed, payload: { title: "Changed after signing" } };
+  assert.equal(verifyOperationRoleKey(tampered, [grant], { now: 5000 }).ok, false);
+
+  const wrongRoom = signedOperation(operation({ id: "op_wrong_room", roomId: "other", actor: actor("admin", "alice") }), key, grant);
+  assert.equal(verifyOperationRoleKey(wrongRoom, [grant], { now: 5000 }).ok, false);
+
+  assert.equal(verifyOperationRoleKey(signed, [grant], { now: 11000 }).ok, false);
+});
+
+test("public role-key grants never expose private key material", () => {
+  const key = generateOperationRoleKeyPair({ role: "admin" });
+  const grant = createOperationRoleKeyGrant({
+    roomId: ROOM_ID,
+    appPackId: kanbanAppPack.id,
+    appPackHash: APP_HASH,
+    credentialId: "admin_cred",
+    memberId: "alice",
+    role: "admin",
+    publicKeyPem: key.publicKeyPem
+  });
+  const publicGrant = publicOperationRoleKeyGrant({ ...grant, privateKeyPem: key.privateKeyPem });
+  assert.equal(publicGrant.privateKeyPem, undefined);
+  assert.equal(publicGrant.publicKeyPem.includes("PUBLIC KEY"), true);
+});
+
+test("role-key helpers reject malformed grants and scoped permissions", () => {
+  const key = generateOperationRoleKeyPair({ role: "member" });
+  assert.equal(key.role, "user");
+  assert.throws(() => createOperationRoleKeyGrant({}), /publicKeyPem/);
+  assert.throws(() => createOperationRoleKeyGrant({ publicKeyPem: key.publicKeyPem, role: "guest", credentialId: "c", roomId: ROOM_ID, appPackId: kanbanAppPack.id }), /role/);
+  assert.throws(() => createOperationRoleKeyGrant({ publicKeyPem: key.publicKeyPem, role: "user", credentialId: "c", roomId: ROOM_ID, appPackId: kanbanAppPack.id, allowedPluginIds: [""] }), /allowedPluginIds/);
+
+  const grant = createOperationRoleKeyGrant({
+    roomId: ROOM_ID,
+    appPackId: kanbanAppPack.id,
+    appPackHash: APP_HASH,
+    credentialId: "user_scoped",
+    memberId: "bob",
+    deviceId: "dev_bob",
+    role: "user",
+    publicKeyPem: key.publicKeyPem,
+    allowedPluginIds: [KANBAN_PLUGIN_ID],
+    allowedOperations: ["card.create"],
+    issuedAt: 100
+  });
+  const base = operation({
+    id: "op_scoped",
+    type: "card.create",
+    actor: actor("member", "bob"),
+    payload: { listId: "list_1", title: "Card" },
+    createdAt: 1000
+  });
+  const signed = signedOperation(base, key, grant);
+  assert.equal(verifyOperationRoleKey(signed, [grant], { now: 5000 }).ok, true);
+  assert.match(verifyOperationRoleKey({ ...signed, pluginId: "other.plugin" }, [grant], { now: 5000 }).error, /plugin/);
+  assert.match(verifyOperationRoleKey({ ...signed, type: "list.create" }, [grant], { now: 5000 }).error, /operation/);
+  assert.match(verifyOperationRoleKey({ ...signed, actor: { ...signed.actor, deviceId: "other" } }, [grant], { now: 5000 }).error, /device/);
+});
+
+test("role-key verifier covers auth metadata and grant collection forms", () => {
+  const key = generateOperationRoleKeyPair({ role: "admin" });
+  const grant = createOperationRoleKeyGrant({
+    roomId: ROOM_ID,
+    appPackId: kanbanAppPack.id,
+    appPackHash: APP_HASH,
+    credentialId: "admin_map",
+    memberId: "alice",
+    role: "admin",
+    publicKeyPem: key.publicKeyPem,
+    issuedAt: 100
+  });
+  const signed = signedOperation(operation({ id: "op_map", actor: actor("admin", "alice") }), key, grant);
+  assert.equal(verifyOperationRoleKey(signed, new Map([[grant.credentialId, grant]]), { now: 5000 }).ok, true);
+  assert.equal(verifyOperationRoleKey(signed, { [grant.credentialId]: grant }, { now: 5000 }).ok, true);
+  assert.match(verifyOperationRoleKey({ ...signed, auth: { ...signed.auth, kind: "wrong" } }, [grant], { now: 5000 }).error, /kind/);
+  assert.match(verifyOperationRoleKey({ ...signed, auth: { ...signed.auth, version: 2 } }, [grant], { now: 5000 }).error, /version/);
+  assert.match(verifyOperationRoleKey({ ...signed, auth: { ...signed.auth, alg: "rsa" } }, [grant], { now: 5000 }).error, /algorithm/);
+  assert.match(verifyOperationRoleKey({ ...signed, auth: { ...signed.auth, keyRole: "user" } }, [grant], { now: 5000 }).error, /role/);
+  assert.match(verifyOperationRoleKey({ ...signed, auth: { ...signed.auth, publicKeyFingerprint: "sha256-nope" } }, [grant], { now: 5000 }).error, /fingerprint/);
+  assert.match(verifyOperationRoleKey({ ...signed, auth: { ...signed.auth, issuedAt: 1 } }, [grant], { now: 5000 }).error, /predates/);
+  assert.match(verifyOperationRoleKey({ ...signed, auth: { credentialId: grant.credentialId } }, [grant], { now: 5000 }).error, /signature/);
+  assert.match(verifyOperationRoleKey(null, [grant]).error, /Operation is required/);
+  assert.match(verifyOperationRoleKey({ ...signed, auth: null }, [grant]).error, /auth/);
+});
+
+
+test("role-key helpers cover canonicalization and public grant collection edge cases", () => {
+  const {
+    canonicalJson,
+    isOperationRoleKeyGrant,
+    operationKeyRoleToActorRole,
+    publicOperationRoleKeyGrants,
+    roleKeyFingerprint
+  } = require("../src/index.cjs");
+  assert.throws(() => canonicalJson(Symbol("bad")), /Unsupported value/);
+  assert.equal(operationKeyRoleToActorRole("guest"), "guest");
+  assert.deepEqual(publicOperationRoleKeyGrants(undefined), []);
+
+  const key = generateOperationRoleKeyPair({ role: "admin" });
+  const grant = createOperationRoleKeyGrant({
+    roomId: ROOM_ID,
+    appPackId: kanbanAppPack.id,
+    credentialId: "admin_publics",
+    role: "admin",
+    publicKeyPem: key.publicKeyPem
+  });
+  assert.equal(publicOperationRoleKeyGrants(grant)[0].credentialId, "admin_publics");
+  assert.equal(publicOperationRoleKeyGrants(new Map([[grant.credentialId, grant]])).length, 1);
+
+  const invalidKeyGrant = {
+    ...grant,
+    credentialId: "invalid_key",
+    publicKeyPem: "not a public key",
+    publicKeyFingerprint: roleKeyFingerprint("not a public key")
+  };
+  assert.equal(isOperationRoleKeyGrant(invalidKeyGrant), true);
+  const signed = signedOperation(operation({ id: "op_invalid_key", actor: actor("admin", "admin") }), key, invalidKeyGrant);
+  assert.match(verifyOperationRoleKey(signed, [invalidKeyGrant], { now: 5000 }).error, /decoder|PEM|key|unsupported|asn1|Failed/i);
+});
+
+test("signing role-key operations accepts operations without existing auth", () => {
+  const key = generateOperationRoleKeyPair({ role: "admin" });
+  const grant = createOperationRoleKeyGrant({
+    roomId: ROOM_ID,
+    appPackId: kanbanAppPack.id,
+    appPackHash: APP_HASH,
+    credentialId: "admin_no_auth",
+    role: "admin",
+    publicKeyPem: key.publicKeyPem,
+    issuedAt: 1
+  });
+  const signed = signOperationWithRoleKey({ ...operation({ id: "op_no_auth" }), auth: undefined }, { privateKeyPem: key.privateKeyPem, grant, issuedAt: 10 });
+  assert.equal(signed.auth.credentialId, "admin_no_auth");
+  assert.equal(verifyOperationRoleKey(signed, [grant], { now: 20 }).ok, true);
+  assert.throws(() => signOperationWithRoleKey(operation(), { privateKeyPem: key.privateKeyPem, grant: { bad: true } }), /valid operation role-key grant/);
+});

package/test/security-isolation.test.cjs

@@ -0,0 +1,112 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const {
+  HostPluginRuntime,
+  allow,
+  createOperationSchemaDescriptor,
+  defineHostPlugin,
+  createMemoryOperationLog,
+  createMemoryRoomStore
+} = require("../src/index.cjs");
+const { ensureOperationIdentity } = require("@mh-gg/protocol");
+
+function stateSchema() {
+  return { parse(value) { return JSON.parse(JSON.stringify(value)); } };
+}
+
+function makeOp(type, pluginId, id = type) {
+  const op = {
+    id,
+    roomId: "room_security",
+    appPackId: "app.security",
+    appPackHash: "sha256-app-security",
+    pluginId,
+    type,
+    actor: { memberId: "alice", deviceId: "dev_alice", role: "admin" },
+    seq: 1,
+    createdAt: 1000,
+    payload: {},
+    auth: { credentialId: "cred", signature: "sig" }
+  };
+  return ensureOperationIdentity(op, { nodeId: op.actor.deviceId, now: op.createdAt });
+}
+
+function victimPlugin() {
+  return defineHostPlugin({
+    id: "com.matterhorn.security.victim",
+    version: "1.0.0",
+    operationSchemaDescriptor: createOperationSchemaDescriptor({ plugin: "com.matterhorn.security.victim", version: "1.0.0", operations: { noop: { authorize: { roles: ["member"] } } } }),
+    schemas: {
+      state: stateSchema(),
+      operations: { noop: { parse: (value) => value || {} } }
+    },
+    async createInitialState() { return { secret: "safe", methodTouched: false }; },
+    authorize() { return allow(); },
+    async reduce(_ctx, state) { return state; },
+    methods: {
+      mutateState(ctx) {
+        ctx.state.secret = "method-pwned";
+        ctx.state.methodTouched = true;
+        return { ok: true };
+      }
+    }
+  });
+}
+
+function attackerPlugin({ viaMethod = false } = {}) {
+  return defineHostPlugin({
+    id: "com.matterhorn.security.attacker",
+    version: "1.0.0",
+    operationSchemaDescriptor: createOperationSchemaDescriptor({ plugin: "com.matterhorn.security.attacker", version: "1.0.0", operations: { attack: { authorize: { roles: ["member"] } } } }),
+    schemas: {
+      state: stateSchema(),
+      operations: { attack: { parse: (value) => value || {} } }
+    },
+    async createInitialState() { return { attacks: 0 }; },
+    authorize() { return allow(); },
+    async reduce(ctx, state) {
+      if (viaMethod) {
+        await ctx.plugins.call("com.matterhorn.security.victim", "mutateState", {});
+      } else {
+        ctx.roomState.plugins["com.matterhorn.security.victim"].secret = "context-pwned";
+      }
+      return { ...state, attacks: state.attacks + 1 };
+    }
+  });
+}
+
+async function startRuntime(plugins) {
+  const runtime = new HostPluginRuntime({
+    room: { id: "room_security", appPack: { id: "app.security", hash: "sha256-app-security" } },
+    plugins,
+    store: createMemoryRoomStore(),
+    operationLog: createMemoryOperationLog(),
+    authenticateActor: async (_auth, actor) => actor,
+    now: () => 1000
+  });
+  await runtime.start();
+  return runtime;
+}
+
+test("plugin reducers cannot mutate sibling plugin state through their context", async () => {
+  const runtime = await startRuntime([victimPlugin(), attackerPlugin()]);
+
+  const result = await runtime.handleOperation(makeOp("attack", "com.matterhorn.security.attacker"));
+  const state = await runtime.getState();
+
+  assert.equal(result.ok, true);
+  assert.equal(state.plugins["com.matterhorn.security.attacker"].attacks, 1);
+  assert.equal(state.plugins["com.matterhorn.security.victim"].secret, "safe");
+});
+
+test("plugin method calls receive isolated target state and cannot mutate persisted plugin state", async () => {
+  const runtime = await startRuntime([victimPlugin(), attackerPlugin({ viaMethod: true })]);
+
+  const result = await runtime.handleOperation(makeOp("attack", "com.matterhorn.security.attacker", "op_method_attack"));
+  const state = await runtime.getState();
+
+  assert.equal(result.ok, true);
+  assert.equal(state.plugins["com.matterhorn.security.attacker"].attacks, 1);
+  assert.deepEqual(state.plugins["com.matterhorn.security.victim"], { secret: "safe", methodTouched: false });
+});