@cosmicdrift/kumiko-framework 0.87.1 → 0.87.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.87.1",
+  "version": "0.87.3",
   "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.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.87.3",
     "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/cross-tenant.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import { AccessDeniedError } from "../errors";
+import { crossTenantOverrideDenied } from "./cross-tenant";
+import type { SessionUser } from "./types";
+
+const KEY = "feature.errors.tenantOverrideRequiresSystemAdmin";
+
+function user(roles: string[]): SessionUser {
+  return { id: "u", tenantId: "t1" as SessionUser["tenantId"], roles };
+}
+
+describe("crossTenantOverrideDenied", () => {
+  test("allows when no override is requested", () => {
+    expect(crossTenantOverrideDenied(user(["TenantAdmin"]), undefined, KEY)).toBeUndefined();
+  });
+
+  test("allows a SystemAdmin to target another tenant", () => {
+    expect(crossTenantOverrideDenied(user(["SystemAdmin"]), "other-tenant", KEY)).toBeUndefined();
+  });
+
+  test("denies a TenantAdmin targeting another tenant", () => {
+    const denied = crossTenantOverrideDenied(user(["TenantAdmin"]), "other-tenant", KEY);
+    expect(denied).toBeInstanceOf(AccessDeniedError);
+    expect(denied?.code).toBe("access_denied");
+  });
+
+  test("denies an Admin too — only SystemAdmin clears the override", () => {
+    expect(crossTenantOverrideDenied(user(["Admin", "TenantAdmin"]), "other", KEY)).toBeInstanceOf(
+      AccessDeniedError,
+    );
+  });
+});

package/src/engine/cross-tenant.ts

@@ -0,0 +1,22 @@
+import { AccessDeniedError } from "../errors";
+import type { SessionUser } from "./types";
+
+// A payload-supplied target tenant (tenantIdOverride) on a TenantAdmin-reachable
+// handler is the cross-tenant escape hatch: hasAccess passes the handler for any
+// TenantAdmin, so without a SystemAdmin gate a TenantAdmin could act on another
+// tenant. Centralizes the check the override handlers used to inline. Returns
+// the denial to `throw` (queries) or wrap in `writeFailure` (writes), or
+// undefined when allowed. The i18nKey stays per-feature so existing
+// translations keep resolving.
+export function crossTenantOverrideDenied(
+  user: SessionUser,
+  tenantIdOverride: string | undefined,
+  i18nKey: string,
+): AccessDeniedError | undefined {
+  if (tenantIdOverride === undefined) return undefined;
+  if (user.roles.includes("SystemAdmin")) return undefined;
+  return new AccessDeniedError({
+    i18nKey,
+    details: { reason: "tenant_override_requires_system_admin" },
+  });
+}

package/src/engine/index.ts

@@ -38,6 +38,7 @@ export {
 } from "./constants";
 export type { App, AppConfig } from "./create-app";
 export { createApp } from "./create-app";
+export { crossTenantOverrideDenied } from "./cross-tenant";
 export { defineFeature } from "./define-feature";
 export type {
   QueryHandlerDefinition,
@@ -166,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));
+}