@cosmicdrift/kumiko-bundled-features 0.208.0 → 0.208.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.208.0",
+  "version": "0.208.2",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -126,12 +126,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.208.0",
-    "@cosmicdrift/kumiko-framework": "0.208.0",
-    "@cosmicdrift/kumiko-headless": "0.208.0",
-    "@cosmicdrift/kumiko-renderer": "0.208.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.208.0",
-    "@cosmicdrift/kumiko-types": "0.208.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.208.2",
+    "@cosmicdrift/kumiko-framework": "0.208.2",
+    "@cosmicdrift/kumiko-headless": "0.208.2",
+    "@cosmicdrift/kumiko-renderer": "0.208.2",
+    "@cosmicdrift/kumiko-renderer-web": "0.208.2",
+    "@cosmicdrift/kumiko-types": "0.208.2",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -160,6 +160,6 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.208.0"
+    "@cosmicdrift/kumiko-locale-de": "0.208.2"
   }
 }

package/src/sessions/__tests__/sessions.integration.test.ts

@@ -25,6 +25,7 @@ import {
   resetBlindIndexKeyForTests,
   resetPiiSubjectKmsForTests,
   resetTestTables,
+  seedRows,
   updateRows,
 } from "@cosmicdrift/kumiko-framework/testing";
 import { Temporal } from "temporal-polyfill";
@@ -579,18 +580,25 @@ describe("sessions feature — login → check → revoke → rejected", () => {
     });
     expect(asAdmin.status).toBe(200);
     const body = (await asAdmin.json()) as {
-      data: Array<{
-        id: string;
-        userId: string;
-        createdAt: string;
-        revokedAt: string | null;
-      }>;
+      data: {
+        rows: Array<{
+          id: string;
+          userId: string;
+          createdAt: string;
+          revokedAt: string | null;
+        }>;
+        nextCursor: string | null;
+      };
     };
+    // PagedRows envelope (fw#2216) — the renderer reads data.rows, not a
+    // bare array; asserting the shape here is the proof session-list
+    // actually renders rows instead of silently falling back to [].
+    expect(body.data.nextCursor).toBeNull();
     // Three rows total for the two test users: Alice's pre-promotion session,
     // Alice's post-promotion session, Bob's session. seedUser's bootstrap
     // actor (systemAdmin) also holds live sessions in this tenant — exclude
     // them, they aren't part of what this test pins.
-    const nonSystemRows = body.data.filter((r) => r.userId !== TestUsers.systemAdmin.id);
+    const nonSystemRows = body.data.rows.filter((r) => r.userId !== TestUsers.systemAdmin.id);
     expect(nonSystemRows).toHaveLength(3);
     const userIds = new Set(nonSystemRows.map((r) => r.userId));
     expect(userIds.size).toBe(2);
@@ -598,7 +606,161 @@ describe("sessions feature — login → check → revoke → rejected", () => {
     // Order: most-recently-created first. aliceAsAdmin's session was the
     // last login; aliceAsAdmin.sid leads the list. Pinning guards against
     // silent orderBy removal.
-    expect(body.data[0]?.id).toBe(aliceAsAdmin.sid);
+    expect(body.data.rows[0]?.id).toBe(aliceAsAdmin.sid);
+  });
+
+  // fw#2230 — sort/sortDirection let the admin UI re-order the table client-
+  // side without a full refetch-and-sort round trip.
+  test("session:list sorts by an allowlisted column and direction", async () => {
+    const { userId: aliceId } = await h.seedUser("alice-sort@example.com", "pw-long-enough");
+    const { userId: bobId } = await h.seedUser("bob-sort@example.com", "pw-long-enough");
+    const { userId: carolId } = await h.seedUser("carol-sort@example.com", "pw-long-enough");
+    await updateRows(
+      stack.db,
+      tenantMembershipsTable,
+      { roles: JSON.stringify(["Admin"]) },
+      { userId: aliceId, tenantId: TENANT },
+    );
+    const aliceAsAdmin = await h.login("alice-sort@example.com", "pw-long-enough");
+    await h.login("bob-sort@example.com", "pw-long-enough");
+    await h.login("carol-sort@example.com", "pw-long-enough");
+
+    const fetchUserIds = async (sortDirection: "asc" | "desc") => {
+      const res = await h.authedPost("/api/query", aliceAsAdmin.token, {
+        type: SessionQueries.list,
+        payload: { sort: "userId", sortDirection },
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { data: { rows: Array<{ id: string; userId: string }> } };
+      return body.data.rows
+        .filter((r) => r.userId !== TestUsers.systemAdmin.id)
+        .map((r) => r.userId);
+    };
+
+    // Comparing asc against desc on the same query (rather than asserting
+    // against a re-sort of the response itself) is what actually fails if
+    // `sort`/`sortDirection` were silently ignored and rows just stayed in
+    // createdAt-desc order.
+    const ascending = await fetchUserIds("asc");
+    const descending = await fetchUserIds("desc");
+    expect(ascending).toEqual([...descending].reverse());
+    expect(new Set(ascending)).toEqual(new Set([aliceId, bobId, carolId]));
+  });
+
+  // A `sort` value outside the column allowlist (or an outright injection
+  // attempt) must not throw or 500 — it silently falls back to the default
+  // createdAt/desc ordering instead of letting a client sort by a
+  // non-exposed column like ip/userAgent.
+  test.each(["ip", "createdAt; DROP TABLE"])(
+    "session:list falls back to createdAt desc for a disallowed sort=%s",
+    async (badSort) => {
+      const { userId: aliceId } = await h.seedUser(
+        `alice-badsort-${badSort.length}@example.com`,
+        "pw-long-enough",
+      );
+      await updateRows(
+        stack.db,
+        tenantMembershipsTable,
+        { roles: JSON.stringify(["Admin"]) },
+        { userId: aliceId, tenantId: TENANT },
+      );
+      const aliceAsAdmin = await h.login(
+        `alice-badsort-${badSort.length}@example.com`,
+        "pw-long-enough",
+      );
+
+      const res = await h.authedPost("/api/query", aliceAsAdmin.token, {
+        type: SessionQueries.list,
+        payload: { sort: badSort },
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as {
+        data: { rows: Array<{ id: string; createdAt: string }> };
+      };
+      expect(body.data.rows.length).toBeGreaterThan(0);
+      const createdAtValues = body.data.rows.map((r) => Date.parse(r.createdAt));
+      const sortedDescending = [...createdAtValues].sort((a, b) => b - a);
+      expect(createdAtValues).toEqual(sortedDescending);
+    },
+  );
+
+  test("session:list defaults to createdAt desc without a sort param", async () => {
+    await h.seedUser("alice-nosort@example.com", "pw-long-enough");
+    await h.login("alice-nosort@example.com", "pw-long-enough");
+    const { userId: bobId } = await h.seedUser("bob-nosort@example.com", "pw-long-enough");
+    await updateRows(
+      stack.db,
+      tenantMembershipsTable,
+      { roles: JSON.stringify(["Admin"]) },
+      { userId: bobId, tenantId: TENANT },
+    );
+    const bobAsAdmin = await h.login("bob-nosort@example.com", "pw-long-enough");
+
+    const res = await h.authedPost("/api/query", bobAsAdmin.token, {
+      type: SessionQueries.list,
+      payload: {},
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { rows: Array<{ id: string; createdAt: string }> } };
+    const createdAtValues = body.data.rows.map((r) => Date.parse(r.createdAt));
+    const sortedDescending = [...createdAtValues].sort((a, b) => b - a);
+    expect(createdAtValues).toEqual(sortedDescending);
+    // bobAsAdmin's own (re-)login is the most recent row, must lead.
+    expect(body.data.rows[0]?.id).toBe(bobAsAdmin.sid);
+  });
+
+  // fw#2198/PR#2208 (the sibling stable-ORDER-BY fix) found the repro shape
+  // for Postgres's Top-N-heapsort tie instability empirically: few rows on
+  // large pages stay green even with no tie-breaker at all, by luck — it
+  // took 25 rows sharing one sort value at page size 3 to make it flip
+  // reliably. Same recipe here: seed 25 sessions with an identical
+  // createdAt, then compare a small LIMIT (a Top-N heap) against a LIMIT
+  // covering everything (a full sort) — without an `id` tie-breaker the two
+  // heap sizes can disagree on tie order even though the underlying rows
+  // never change between the two calls.
+  test("session:list keeps a stable order for tied createdAt values across page sizes", async () => {
+    const { userId: adminId } = await h.seedUser("tiebreak-admin@example.com", "pw-long-enough");
+    await updateRows(
+      stack.db,
+      tenantMembershipsTable,
+      { roles: JSON.stringify(["Admin"]) },
+      { userId: adminId, tenantId: TENANT },
+    );
+    const admin = await h.login("tiebreak-admin@example.com", "pw-long-enough");
+
+    const tiedCreatedAt = Temporal.Instant.from("2026-01-01T00:00:00Z");
+    const futureExpiry = Temporal.Instant.from("2099-01-01T00:00:00Z");
+    await seedRows(
+      stack.db,
+      userSessionTable,
+      Array.from({ length: 25 }, (_, i) => ({
+        id: `22222222-2222-2222-2222-${String(i).padStart(12, "0")}`,
+        tenantId: TENANT,
+        userId: adminId,
+        createdAt: tiedCreatedAt,
+        expiresAt: futureExpiry,
+        revokedAt: null,
+        ip: null,
+        userAgent: null,
+      })),
+    );
+
+    const fetchIds = async (limit: number) => {
+      const res = await h.authedPost("/api/query", admin.token, {
+        type: SessionQueries.list,
+        payload: { limit },
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { data: { rows: Array<{ id: string }> } };
+      return body.data.rows.map((r) => r.id);
+    };
+
+    // admin's own login row is strictly newer than the 25 tied rows, so it
+    // always leads both lists — the tie-breaking under test is among the 25.
+    const top3 = await fetchIds(3);
+    const full = await fetchIds(26);
+    expect(full).toHaveLength(26);
+    expect(top3).toEqual(full.slice(0, 3));
   });
 
   // Single-row inspector backing the session-detail screen (kumiko-framework#255).
@@ -685,8 +847,8 @@ describe("sessions feature — login → check → revoke → rejected", () => {
       payload: {},
     });
     expect(listRes.status).toBe(200);
-    const listBody = (await listRes.json()) as { data: Array<{ id: string }> };
-    expect(listBody.data.map((r) => r.id)).not.toContain(carolAsAdmin.sid);
+    const listBody = (await listRes.json()) as { data: { rows: Array<{ id: string }> } };
+    expect(listBody.data.rows.map((r) => r.id)).not.toContain(carolAsAdmin.sid);
   });
 });
 

package/src/sessions/feature.ts

@@ -217,6 +217,10 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
       id: SESSION_LIST_SCREEN_ID,
       type: "projectionList",
       query: SessionQueries.list,
+      // Mirrors list.query's own fallback (unrecognised/absent sort → createdAt
+      // desc) — kept in sync by hand, boot-validator only requires the field
+      // be present once the query accepts `sort` (fw#2230).
+      defaultSort: { field: "createdAt", dir: "desc" },
       columns: [
         { field: "id", label: "sessions.list.col.id" },
         { field: "userId", label: "sessions.list.col.userId" },

package/src/sessions/handlers/list.query.ts

@@ -1,17 +1,42 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  access,
+  definePagedQueryHandler,
+  MAX_LIST_LIMIT,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { decryptStoredPii } from "../../shared";
 import { userSessionTable } from "../schema/user-session";
 
+// `sort` arrives raw from the client's query string. selectMany's orderBy
+// has no column-existence check — an unrecognised field just gets
+// snake_cased and quoted as-is (bun-db/query.ts columnOf) — so this
+// allowlist is what stops a client sorting by ip/userAgent or any other
+// non-exposed column.
+const SORTABLE_COLUMNS = ["id", "userId", "createdAt", "expiresAt", "revokedAt"] as const;
+type SortableColumn = (typeof SORTABLE_COLUMNS)[number];
+
+function isSortableColumn(value: string): value is SortableColumn {
+  return (SORTABLE_COLUMNS as readonly string[]).includes(value);
+}
+
 // Admin view of every session in the active tenant. ctx.db (TenantDb)
 // applies tenant-scoping automatically on selects from tables with a
 // tenantId column. Includes revoked rows; UI shows revokedAt distinct.
-export const listQuery = defineQueryHandler({
+// No cursor — nextCursor is always null; `limit` only caps the page size,
+// it doesn't offset into a further one.
+export const listQuery = definePagedQueryHandler({
   name: "user-session:list",
-  schema: z.object({}),
+  schema: z.object({
+    limit: z.number().int().nonnegative().max(MAX_LIST_LIMIT).optional(),
+    sort: z.string().optional(),
+    sortDirection: z.enum(["asc", "desc"]).optional(),
+  }),
   access: { roles: access.admin },
-  handler: async (_query, ctx) => {
+  handler: async (query, ctx) => {
+    const requestedSort = query.payload.sort;
+    const sortColumn: SortableColumn =
+      requestedSort !== undefined && isSortableColumn(requestedSort) ? requestedSort : "createdAt";
     const rows = await selectMany<{
       id: string;
       userId: string;
@@ -21,9 +46,19 @@ export const listQuery = defineQueryHandler({
       ip: string | null;
       userAgent: string | null;
     }>(ctx.db, userSessionTable, undefined, {
-      orderBy: { col: "createdAt", direction: "desc" },
+      // `id` as a tie-breaker keeps row order (and, with `limit` set, row
+      // selection) deterministic across identical requests — sortColumn
+      // alone isn't unique (e.g. many NULL revokedAt, or equal timestamps).
+      orderBy:
+        sortColumn === "id"
+          ? { col: "id", direction: query.payload.sortDirection ?? "desc" }
+          : [
+              { col: sortColumn, direction: query.payload.sortDirection ?? "desc" },
+              { col: "id", direction: "asc" },
+            ],
+      ...(query.payload.limit !== undefined && { limit: query.payload.limit }),
     });
-    return Promise.all(
+    const decryptedRows = await Promise.all(
       rows.map(async (r) => ({
         id: r.id,
         userId: r.userId,
@@ -36,5 +71,6 @@ export const listQuery = defineQueryHandler({
           : r.userAgent,
       })),
     );
+    return { rows: decryptedRows, nextCursor: null };
   },
 });