@cosmicdrift/kumiko-framework 0.215.6 → 0.216.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.215.6",
+  "version": "0.216.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>",
@@ -194,7 +194,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.215.6",
+    "@cosmicdrift/kumiko-types": "0.216.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -210,7 +210,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.215.6",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.216.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/role-assignment.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import { findForbiddenRoleAssignment } from "../role-assignment";
+
+describe("role assignment guard", () => {
+  test("rejects roles above the actor's highest role", () => {
+    expect(findForbiddenRoleAssignment(["Admin"], ["User", "TenantAdmin"])).toBe("TenantAdmin");
+    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["SystemAdmin"])).toBe("SystemAdmin");
+  });
+
+  test("allows equal or lower roles, including self-updates", () => {
+    expect(findForbiddenRoleAssignment(["Admin"], ["User", "Admin"])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["Admin"], ["Editor"])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["Editor"], ["User", "Editor"])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["User", "Admin"])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["Admin"], ["Admin"])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["SystemAdmin"], ["SystemAdmin"])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["system"], ["SystemAdmin"])).toBeUndefined();
+  });
+
+  test("rejects Editor above User, Admin above Editor", () => {
+    expect(findForbiddenRoleAssignment(["User"], ["Editor"])).toBe("Editor");
+    expect(findForbiddenRoleAssignment(["Editor"], ["Admin"])).toBe("Admin");
+  });
+
+  test("rejects unknown roles (fail-closed)", () => {
+    expect(findForbiddenRoleAssignment(["User"], ["Custom"])).toBe("Custom");
+    expect(findForbiddenRoleAssignment(["SystemAdmin"], ["Custom"])).toBe("Custom");
+  });
+
+  test("rejects assignment if actor has no roles or only unknown roles", () => {
+    expect(findForbiddenRoleAssignment([], ["User"])).toBe("User");
+    expect(findForbiddenRoleAssignment(["UnknownRole"], ["User"])).toBe("User");
+  });
+
+  test("rejects modifying target user with higher existing role", () => {
+    expect(findForbiddenRoleAssignment(["Admin"], ["User"], ["SystemAdmin"])).toBe("SystemAdmin");
+    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["User"], ["TenantAdmin"])).toBeUndefined();
+  });
+
+  test("allows modifying target that currently holds an unranked app role", () => {
+    // Editor is ranked (invite options); use a true app-defined role here.
+    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["User"], ["Billing"])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["Admin"], ["User"], ["Billing", "User"])).toBeUndefined();
+    // Still cannot assign the unranked role on the write path (fail-closed).
+    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["Billing"], ["Billing"])).toBe("Billing");
+  });
+});

package/src/engine/index.ts

@@ -229,6 +229,7 @@ export { readClaim } from "./read-claim";
 export { createRegistry } from "./registry";
 export type { ClampInfo, ResolveOptions } from "./resolve-config-or-param";
 export { resolveConfigOrParam } from "./resolve-config-or-param";
+export { findForbiddenRoleAssignment } from "./role-assignment";
 export { runsInLane } from "./run-in";
 export type { StepListOutcome } from "./run-pipeline";
 export { runPipeline, runStepList } from "./run-pipeline";

package/src/engine/role-assignment.ts

@@ -0,0 +1,45 @@
+const ROLE_RANKS: Readonly<Record<string, number>> = {
+  User: 0,
+  // Matches DEFAULT_INVITE_ROLE_OPTIONS — must stay ranked or invite UI fails closed.
+  Editor: 1,
+  Admin: 2,
+  TenantAdmin: 3,
+  SystemAdmin: 4,
+  system: 5,
+};
+
+function getRoleRank(role: string): number {
+  return ROLE_RANKS[role] ?? Number.POSITIVE_INFINITY;
+}
+
+function maxRoleRank(roles: readonly string[]): number {
+  if (roles.length === 0) return -1;
+  return Math.max(...roles.map((role) => ROLE_RANKS[role] ?? -1));
+}
+
+/** Known built-in rank only — unranked app roles (Billing, …) are not privilege tiers. */
+function knownRoleRank(role: string): number | undefined {
+  return ROLE_RANKS[role];
+}
+
+export function findForbiddenRoleAssignment(
+  actorRoles: readonly string[],
+  assignedRoles: readonly string[],
+  targetCurrentRoles: readonly string[] = [],
+): string | undefined {
+  const actorRank = maxRoleRank(actorRoles);
+  // Assign path: fail-closed on unknown / above-actor roles.
+  const forbiddenAssigned = assignedRoles.find((role) => getRoleRank(role) > actorRank);
+  if (forbiddenAssigned) return forbiddenAssigned;
+
+  // Target path: only ranked roles above the actor block (can't touch a
+  // SystemAdmin). Unranked app roles must not block demotion/updates — invite
+  // can assign them; treating them as rank ∞ on the target freezes those members.
+  const forbiddenTarget = targetCurrentRoles.find((role) => {
+    const rank = knownRoleRank(role);
+    return rank !== undefined && rank > actorRank;
+  });
+  if (forbiddenTarget) return forbiddenTarget;
+
+  return undefined;
+}

package/src/stack/__tests__/request-helper.integration.test.ts

@@ -0,0 +1,126 @@
+// Pins createRequestHelper against a real setupTestStack (buildServer + JWT),
+// not the mock-Hono unit suite. Covers success, structured errors, batch, and
+// extra-header forwarding — the paths every integration test relies on via
+// stack.http.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../engine";
+import { NotFoundError, UnprocessableError, writeFailure } from "../../errors";
+import { setupTestStack, type TestStack } from "../test-stack";
+import { TestUsers } from "../test-users";
+
+let stack: TestStack;
+
+const pingFeature = defineFeature("reqhelp", (r) => {
+  r.writeHandler(
+    "echo",
+    z.object({ note: z.string().min(1) }),
+    async (event) => ({
+      isSuccess: true as const,
+      data: { note: event.payload.note, userId: event.user.id },
+    }),
+    { access: { openToAll: true } },
+  );
+
+  r.writeHandler(
+    "boom",
+    z.object({}),
+    async () =>
+      writeFailure(new UnprocessableError("reqhelp-boom", { i18nKey: "errors.unprocessable" })),
+    { access: { openToAll: true } },
+  );
+
+  r.queryHandler(
+    "lookup",
+    z.object({ id: z.string().min(1) }),
+    async (query) => {
+      if (query.payload.id === "missing") {
+        throw new NotFoundError("thing", query.payload.id, { i18nKey: "errors.notFound" });
+      }
+      return { id: query.payload.id, ok: true };
+    },
+    { access: { openToAll: true } },
+  );
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [pingFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("createRequestHelper via setupTestStack.http", () => {
+  test("writeOk posts to /api/write and returns handler data", async () => {
+    const data = await stack.http.writeOk<{ note: string; userId: string }>(
+      "reqhelp:write:echo",
+      { note: "hello" },
+      TestUsers.admin,
+    );
+    expect(data).toEqual({ note: "hello", userId: TestUsers.admin.id });
+  });
+
+  test("queryOk posts to /api/query and returns handler data", async () => {
+    const data = await stack.http.queryOk<{ id: string; ok: boolean }>(
+      "reqhelp:query:lookup",
+      { id: "abc" },
+      TestUsers.admin,
+    );
+    expect(data).toEqual({ id: "abc", ok: true });
+  });
+
+  test("writeErr returns structured WriteErrorInfo with httpStatus", async () => {
+    const err = await stack.http.writeErr("reqhelp:write:boom", {}, TestUsers.admin);
+    expect(err.code).toBe("unprocessable");
+    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+    expect(err.i18nKey).toBe("errors.unprocessable");
+  });
+
+  test("queryErr returns structured WriteErrorInfo for not-found", async () => {
+    const err = await stack.http.queryErr(
+      "reqhelp:query:lookup",
+      { id: "missing" },
+      TestUsers.admin,
+    );
+    expect(err.code).toBe("not_found");
+    expect(err.httpStatus).toBe(404);
+  });
+
+  test("writeOk throws when the write fails (so suites cannot ignore failures)", async () => {
+    await expect(stack.http.writeOk("reqhelp:write:boom", {}, TestUsers.admin)).rejects.toThrow(
+      /reqhelp:write:boom/,
+    );
+  });
+
+  test("batch posts commands and returns per-command results", async () => {
+    const res = await stack.http.batch(
+      [
+        { type: "reqhelp:write:echo", payload: { note: "a" } },
+        { type: "reqhelp:write:echo", payload: { note: "b" } },
+      ],
+      TestUsers.admin,
+    );
+    expect(res.ok).toBe(true);
+    const body = (await res.json()) as {
+      isSuccess?: boolean;
+      results?: readonly { isSuccess?: boolean; data?: { note?: string } }[];
+    };
+    expect(body.isSuccess).toBe(true);
+    expect(body.results?.map((r) => r.data?.note)).toEqual(["a", "b"]);
+  });
+
+  test("writeWithHeaders forwards extra headers alongside auth", async () => {
+    const res = await stack.http.writeWithHeaders(
+      "reqhelp:write:echo",
+      { note: "hdr" },
+      TestUsers.admin,
+      { "X-Correlation-ID": "corr-42" },
+    );
+    expect(res.ok).toBe(true);
+    const body = (await res.json()) as { isSuccess?: boolean; data?: { note?: string } };
+    expect(body.isSuccess).toBe(true);
+    expect(body.data?.note).toBe("hdr");
+  });
+});

package/src/stack/__tests__/request-helper.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import type { JwtHelper } from "../../api/jwt";
+import type { SessionUser } from "../../engine/types";
+import { createRequestHelper } from "../request-helper";
+
+const user: SessionUser = {
+  id: "u1",
+  tenantId: "t1",
+  roles: ["member"],
+};
+
+function jwtStub() {
+  const signed: unknown[] = [];
+  const jwt = {
+    sign: async (payload: unknown) => {
+      signed.push(payload);
+      return `j.${Buffer.from(JSON.stringify(payload)).toString("base64url")}`;
+    },
+  } as unknown as JwtHelper;
+  return { jwt, signed };
+}
+
+function appRecording(
+  handler: (c: {
+    req: { json: () => Promise<unknown>; header: (n: string) => string | undefined };
+  }) => Response | Promise<Response>,
+) {
+  const calls: { path: string; auth?: string; extraHeaders: Record<string, string | undefined> }[] =
+    [];
+  const app = new Hono();
+  for (const path of ["/api/write", "/api/query", "/api/command", "/api/batch"]) {
+    app.post(path, async (c) => {
+      calls.push({
+        path,
+        auth: c.req.header("authorization"),
+        extraHeaders: { "x-trace": c.req.header("x-trace") },
+      });
+      return handler({ req: { json: () => c.req.json(), header: (n) => c.req.header(n) } });
+    });
+  }
+  return { app, calls };
+}
+
+describe("createRequestHelper", () => {
+  test("writeOk posts JSON to /api/write and resolves the success data", async () => {
+    const { app, calls } = appRecording(() =>
+      Response.json({ isSuccess: true, data: { written: true } }),
+    );
+    const { jwt } = jwtStub();
+    const http = createRequestHelper(app, jwt);
+
+    const data = await http.writeOk("todo.create", { title: "x" }, user);
+    expect(data).toEqual({ written: true });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.path).toBe("/api/write");
+    expect(calls[0]!.auth).toMatch(/^Bearer j\./);
+  });
+
+  test("sessionCreator is consulted once per user and its sid reaches the jwt", async () => {
+    let creations = 0;
+    const { app } = appRecording(() => Response.json({ isSuccess: true, data: {} }));
+    const { jwt, signed } = jwtStub();
+    const http = createRequestHelper(app, jwt, {
+      sessionCreator: async () => {
+        creations += 1;
+        return "sid-42";
+      },
+    });
+
+    await http.writeOk("a.b", {}, user);
+    await http.queryOk("c.d", {}, user);
+    expect(creations).toBe(1);
+    expect(signed).toHaveLength(2);
+    expect(signed[0]).toMatchObject({ id: "u1", tenantId: "t1", sid: "sid-42" });
+  });
+
+  test("user-provided sid skips the sessionCreator entirely", async () => {
+    const { app } = appRecording(() => Response.json({ isSuccess: true, data: {} }));
+    const { jwt, signed } = jwtStub();
+    let creations = 0;
+    const http = createRequestHelper(app, jwt, {
+      sessionCreator: async () => {
+        creations += 1;
+        throw new Error("must not be called");
+      },
+    });
+    await http.writeOk("a.b", {}, { ...user, sid: "pre-set" });
+    expect(creations).toBe(0);
+    expect(signed[0]).toMatchObject({ sid: "pre-set" });
+  });
+
+  test("writeOk surfaces the formatted failure including cause details", async () => {
+    const { app } = appRecording(() =>
+      Response.json(
+        {
+          error: {
+            code: "internal_error",
+            details: { causeName: "DbError", causeMessage: "connection lost" },
+          },
+        },
+        { status: 500 },
+      ),
+    );
+    const http = createRequestHelper(app, jwtStub().jwt);
+    expect(http.writeOk("todo.create", {}, user)).rejects.toThrow(
+      'Expected write "todo.create" to succeed but got error: internal_error (DbError: connection lost)',
+    );
+  });
+
+  test("queryErr returns the wire error plus http status, but throws on success", async () => {
+    const failing = appRecording(() =>
+      Response.json({ error: { code: "validation_failed", message: "nope" } }, { status: 400 }),
+    );
+    const http = createRequestHelper(failing.app, jwtStub().jwt);
+    const err = await http.queryErr("q.type", {}, user);
+    expect(err.code).toBe("validation_failed");
+    expect(err.httpStatus).toBe(400);
+
+    const succeeding = appRecording(() => Response.json({ isSuccess: true, data: {} }));
+    const http2 = createRequestHelper(succeeding.app, jwtStub().jwt);
+    expect(http2.queryErr("q.type", {}, user)).rejects.toThrow(
+      'Expected query "q.type" to fail but it succeeded',
+    );
+  });
+
+  test("batch posts the commands array unchanged to /api/batch", async () => {
+    const bodies: unknown[] = [];
+    const app = new Hono();
+    app.post("/api/batch", async (c) => {
+      bodies.push(await c.req.json());
+      return Response.json({ isSuccess: true, data: [] });
+    });
+    const http = createRequestHelper(app, jwtStub().jwt);
+    await http.batch(
+      [
+        { type: "a", payload: { x: 1 } },
+        { type: "b", payload: {} },
+      ],
+      user,
+      "req-9",
+    );
+    expect(bodies[0]).toEqual({
+      commands: [
+        { type: "a", payload: { x: 1 } },
+        { type: "b", payload: {} },
+      ],
+      requestId: "req-9",
+    });
+  });
+
+  test("extra headers are forwarded alongside the auth header", async () => {
+    const { app, calls } = appRecording(() => Response.json({ isSuccess: true, data: {} }));
+    const http = createRequestHelper(app, jwtStub().jwt);
+    await http.writeWithHeaders("a.b", {}, user, { "x-trace": "tr-1" });
+    expect(calls[0]!.extraHeaders["x-trace"]).toBe("tr-1");
+    expect(calls[0]!.auth).toMatch(/^Bearer /);
+  });
+});

package/src/testing/__tests__/multipart-helper.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { buildMultipartBody } from "../multipart-helper";
+
+describe("buildMultipartBody", () => {
+  test("serializes text fields so a Response can parse them back", async () => {
+    const fd = new FormData();
+    fd.set("title", "hello world");
+    fd.set("count", "42");
+
+    const { body, contentType } = await buildMultipartBody(fd);
+    expect(contentType).toMatch(/^multipart\/form-data; boundary=kumikoBnd/i);
+
+    const parsed = await new Response(body, {
+      headers: { "content-type": contentType },
+    }).formData();
+    expect(parsed.get("title")).toBe("hello world");
+    expect(parsed.get("count")).toBe("42");
+  });
+
+  test("carries file name and bytes through", async () => {
+    const fd = new FormData();
+    fd.set("doc", new File(["PDF-bytes"], "report.pdf", { type: "application/pdf" }));
+
+    const { body, contentType } = await buildMultipartBody(fd);
+    const text = typeof body === "string" ? body : await new Response(body).text();
+
+    expect(contentType).toMatch(/^multipart\/form-data; boundary=kumikoBnd/i);
+    expect(text).toContain('filename="report.pdf"');
+    expect(text).toContain("PDF-bytes");
+    expect(text.endsWith(`--${contentType.split("boundary=")[1]}--\r\n`)).toBe(true);
+  });
+
+  test("mixed fields and files round-trip together", async () => {
+    const fd = new FormData();
+    fd.set("note", "attached");
+    fd.set("file", new File(["abc"], "a.txt"));
+
+    const { body, contentType } = await buildMultipartBody(fd);
+    const parsed = await new Response(body, {
+      headers: { "content-type": contentType },
+    }).formData();
+    expect(parsed.get("note")).toBe("attached");
+    // Structural check: happy-dom and bun can expose different File realms,
+    // so instanceof would fail depending on file order in the same process.
+    const file = parsed.get("file") as { name?: string; size?: number } | null;
+    expect(file?.name).toBe("a.txt");
+    expect(file?.size).toBe(3);
+  });
+});