@cosmicdrift/kumiko-framework 0.87.2 → 0.88.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.87.2",
+  "version": "0.88.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.87.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.88.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/auth-routes.ts

@@ -2,6 +2,7 @@ import type { Context } from "hono";
 import { Hono } from "hono";
 import { deleteCookie, setCookie } from "hono/cookie";
 import { z } from "zod";
+import { stripForbiddenMembershipRoles } from "../engine/membership-roles";
 import { createSystemUser } from "../engine/system-user";
 import { type SessionUser, SYSTEM_TENANT_ID, type TenantId } from "../engine/types";
 import { NotFoundError } from "../errors";
@@ -902,7 +903,13 @@ export function createAuthRoutes(
     // tenant A accidentally surviving into tenant B's session). The
     // resolver runs each feature's r.authClaims() hook under the new
     // TenantDb scope.
-    const mergedRoles = Array.from(new Set([...globalRoles, ...membership.roles]));
+    // Strip reserved roles from the membership portion only — globalRoles
+    // (where SystemAdmin legitimately lives) is never filtered. Backstop for a
+    // membership role that a projection rebuild resurrected past command-time
+    // validation (see engine/membership-roles).
+    const mergedRoles = Array.from(
+      new Set([...globalRoles, ...stripForbiddenMembershipRoles(membership.roles)]),
+    );
     const targetSession: SessionUser = {
       id: user.id,
       tenantId: targetTenantId,

package/src/engine/__tests__/membership-roles.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import {
+  FORBIDDEN_MEMBERSHIP_ROLES,
+  findForbiddenMembershipRole,
+  isForbiddenMembershipRole,
+  stripForbiddenMembershipRoles,
+} from "../membership-roles";
+
+describe("forbidden membership roles", () => {
+  test("set covers the platform-global/reserved roles", () => {
+    expect([...FORBIDDEN_MEMBERSHIP_ROLES].sort()).toEqual(
+      ["SystemAdmin", "all", "anonymous", "system"].sort(),
+    );
+  });
+
+  test("isForbiddenMembershipRole flags reserved, allows tenant roles", () => {
+    expect(isForbiddenMembershipRole("SystemAdmin")).toBe(true);
+    expect(isForbiddenMembershipRole("system")).toBe(true);
+    expect(isForbiddenMembershipRole("all")).toBe(true);
+    expect(isForbiddenMembershipRole("anonymous")).toBe(true);
+    expect(isForbiddenMembershipRole("Admin")).toBe(false);
+    expect(isForbiddenMembershipRole("User")).toBe(false);
+  });
+
+  test("findForbiddenMembershipRole returns the first reserved role or undefined", () => {
+    expect(findForbiddenMembershipRole(["Admin", "SystemAdmin", "User"])).toBe("SystemAdmin");
+    expect(findForbiddenMembershipRole(["Admin", "User"])).toBeUndefined();
+  });
+
+  test("strip removes reserved roles, preserves order of the rest", () => {
+    expect(stripForbiddenMembershipRoles(["Admin", "SystemAdmin", "User", "all"])).toEqual([
+      "Admin",
+      "User",
+    ]);
+    expect(stripForbiddenMembershipRoles(["Editor", "User"])).toEqual(["Editor", "User"]);
+    expect(stripForbiddenMembershipRoles(["SystemAdmin"])).toEqual([]);
+  });
+});
+
+// The two cases that discriminate the fix at every JWT mint: the strip wraps
+// ONLY the membership portion, never the merged result — so a legitimate
+// SystemAdmin in globalRoles survives, a resurrected one in membership does not.
+describe("merge semantics (globalRoles never filtered)", () => {
+  function merge(
+    globalRoles: readonly string[],
+    membershipRoles: readonly string[],
+  ): readonly string[] {
+    return Array.from(new Set([...globalRoles, ...stripForbiddenMembershipRoles(membershipRoles)]));
+  }
+
+  test("global SystemAdmin survives (no regression for real admins)", () => {
+    expect(merge(["SystemAdmin"], [])).toContain("SystemAdmin");
+  });
+
+  test("membership SystemAdmin is stripped (resurrected role neutralised)", () => {
+    expect(merge([], ["SystemAdmin"])).not.toContain("SystemAdmin");
+  });
+
+  test("global admin + tenant membership keeps both, deduped", () => {
+    expect([...merge(["SystemAdmin"], ["Admin", "SystemAdmin"])].sort()).toEqual(
+      ["Admin", "SystemAdmin"].sort(),
+    );
+  });
+});

package/src/engine/index.ts

@@ -167,6 +167,12 @@ export {
   checkWriteFieldRoles,
   filterReadFields,
 } from "./field-access";
+export {
+  FORBIDDEN_MEMBERSHIP_ROLES,
+  findForbiddenMembershipRole,
+  isForbiddenMembershipRole,
+  stripForbiddenMembershipRoles,
+} from "./membership-roles";
 export type { OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule } from "./ownership";
 export { from } from "./ownership";
 export { buildPipelineSteps, pipeline } from "./pipeline";

package/src/engine/membership-roles.ts

@@ -0,0 +1,32 @@
+// Reserved/platform-global roles must never reach a session via a tenant
+// membership. hasAccess checks session.roles flat, with no notion of origin,
+// so a membership role like "SystemAdmin" would unlock the SystemAdmin-gated
+// cross-tenant surface. The write paths enforce this at command time
+// (assertAssignableMembershipRoles), but command-time validation does not
+// survive a projection rebuild: replaying a stored membership event goes
+// through the apply path, not the handler. stripForbiddenMembershipRoles is
+// the read-time backstop — applied at every JWT mint that derives roles from
+// membership, it neutralises a resurrected role without touching globalRoles
+// (where SystemAdmin legitimately lives).
+
+import { access } from "./config-helpers";
+
+export const FORBIDDEN_MEMBERSHIP_ROLES: ReadonlySet<string> = new Set<string>([
+  ...access.privileged, // system, SystemAdmin
+  ...access.all, // all
+  ...access.anonymous, // anonymous
+]);
+
+export function isForbiddenMembershipRole(role: string): boolean {
+  return FORBIDDEN_MEMBERSHIP_ROLES.has(role);
+}
+
+export function findForbiddenMembershipRole(roles: readonly string[]): string | undefined {
+  return roles.find(isForbiddenMembershipRole);
+}
+
+// Filters reserved roles out of the membership portion only. Callers merge the
+// result with globalRoles, which is never filtered.
+export function stripForbiddenMembershipRoles(roles: readonly string[]): readonly string[] {
+  return roles.filter((role) => !isForbiddenMembershipRole(role));
+}