fix(api): validate v2 cursor key values and compare timestamps at ms precision

Two review findings, fixed at the root by making a keyset key own its cursor
codec instead of hand-writing a decoder per sort.

Cursor key values are caller-controlled, and matching the sort stamp and key
count was not enough: an unparseable timestamp or a non-numeric size reached
the query as an Invalid Date or NaN and surfaced as a 500. Each key now type-
checks its own value and rejects a cursor it cannot hold, which both routes
render as the documented 400.

Timestamp keys now order and compare on date_trunc('milliseconds', col).
Postgres keeps microseconds and defaultNow() populates them, but a cursor value
round-trips through a millisecond-only JS Date — comparing the raw column
against the truncated value re-admitted the page's own last row, duplicating it
and stalling pagination outright at a page size of one. Reachable today via
workspace_files.updated_at, which insertFileMetadata leaves to defaultNow().

Author: TheodoreSpeaks

apps/sim/app/api/v2/files/route.test.ts

@@ -36,7 +36,6 @@ vi.mock('@/app/api/v2/lib/gate', () => ({
 
 vi.mock('@/lib/uploads/contexts/workspace', () => ({
   queryWorkspaceFiles: mockQueryWorkspaceFiles,
-  workspaceFileCursorKeyCount: () => 2,
   uploadWorkspaceFile: mockUploadWorkspaceFile,
   getWorkspaceFile: mockGetWorkspaceFile,
   FileConflictError: class FileConflictError extends Error {},
@@ -288,6 +287,20 @@ describe('GET /api/v2/files', () => {
     expect(mockQueryWorkspaceFiles).not.toHaveBeenCalled()
   })
 
+  it('400s when the cursor carries values the sort cannot hold', async () => {
+    mockQueryWorkspaceFiles.mockRejectedValue(
+      new OrchestrationError('validation', 'cursor does not match the requested sortBy/sortOrder.')
+    )
+    const cursor = Buffer.from(
+      JSON.stringify({ sort: 'uploadedAt:asc', keys: ['not-a-date', 'wf_1'] })
+    ).toString('base64')
+
+    const res = await callList(`workspaceId=${WS}&cursor=${encodeURIComponent(cursor)}`)
+
+    expect(res.status).toBe(400)
+    expect((await res.json()).error.code).toBe('BAD_REQUEST')
+  })
+
   it('terminates pagination when the query reports no further keys', async () => {
     mockQueryWorkspaceFiles.mockResolvedValue({ files: [buildRecord()], nextKeys: null })
 

apps/sim/app/api/v2/files/route.ts

@@ -18,7 +18,6 @@ import {
   getWorkspaceFile,
   queryWorkspaceFiles,
   uploadWorkspaceFile,
-  workspaceFileCursorKeyCount,
 } from '@/lib/uploads/contexts/workspace'
 import { checkRateLimit, resolveWorkspaceAccess } from '@/app/api/v1/middleware'
 import { toV2File } from '@/app/api/v2/files/utils'
@@ -83,7 +82,7 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
     if (access) return v2WorkspaceAccessError(access)
 
     const sort = cursorSortKey(sortBy, sortOrder)
-    const decoded = decodeSortedCursor(cursor, sort, workspaceFileCursorKeyCount(sortBy))
+    const decoded = decodeSortedCursor(cursor, sort)
     if (decoded.status === 'invalid') return v2CursorSortError()
 
     const { files, nextKeys } = await queryWorkspaceFiles(workspaceId, {
@@ -101,6 +100,10 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
 
     return v2CursorList(items, nextCursor, { rateLimit })
   } catch (error) {
+    // A cursor that doesn't fit the requested sort arrives classified as `validation` → 400.
+    const classified = v2CaughtOrchestrationError(error)
+    if (classified) return classified
+
     logger.error('Error listing files', { error: getErrorMessage(error, 'Unknown error') })
     return v2Error('INTERNAL_ERROR', 'Internal server error')
   }

apps/sim/app/api/v2/lib/response.ts

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server'
 import type { ZodError } from 'zod'
-import type { CursorKey } from '@/lib/api/list-query'
+import { type CursorKey, INVALID_CURSOR_MESSAGE } from '@/lib/api/list-query'
 import { getValidationErrorMessage, serializeZodIssues } from '@/lib/api/server'
 import { asOrchestrationError, type OrchestrationErrorCode } from '@/lib/core/orchestration/types'
 import type { RateLimitResult, WorkspaceAccessError } from '@/app/api/v1/middleware'
@@ -190,36 +190,26 @@ export type DecodedSortedCursor =
  * Reads a keyset cursor back, refusing one that does not belong to the
  * requested sort. Resuming a `name`-ordered cursor under `createdAt` would
  * compare the wrong column and silently duplicate or skip rows, so a mismatch
- * is a client error rather than a best-effort page. A malformed cursor — bad
- * base64, or the wrong number of keys for `keyCount` — is rejected for the same
- * reason: ignoring it would restart from page one while the caller believes it
- * is paging forward, and a short key list would compare a column against
- * `undefined`.
+ * is a client error rather than a best-effort page. A cursor that isn't valid
+ * base64-JSON is rejected for the same reason: ignoring it would restart from
+ * page one while the caller believes it is paging forward.
+ *
+ * This checks the envelope only. The key VALUES are caller-controlled too, and
+ * are type-checked against the sort's keys by `keysetAfter`, which is where a
+ * bad arity or an unparseable timestamp is caught.
  */
-export function decodeSortedCursor(
-  cursor: string | undefined,
-  sort: string,
-  keyCount: number
-): DecodedSortedCursor {
+export function decodeSortedCursor(cursor: string | undefined, sort: string): DecodedSortedCursor {
   if (!cursor) return { status: 'absent' }
   const decoded = decodeCursor<Partial<SortedCursorPayload>>(cursor)
-  if (
-    !decoded ||
-    decoded.sort !== sort ||
-    !Array.isArray(decoded.keys) ||
-    decoded.keys.length !== keyCount
-  ) {
+  if (!decoded || decoded.sort !== sort || !Array.isArray(decoded.keys)) {
     return { status: 'invalid' }
   }
   return { status: 'ok', keys: decoded.keys }
 }
 
-/** The 400 for a cursor that does not match the request's sort. */
+/** The 400 for a cursor that cannot be resumed under the request's sort. */
 export function v2CursorSortError(): NextResponse {
-  return v2Error(
-    'BAD_REQUEST',
-    'cursor does not match the requested sortBy/sortOrder. Restart pagination without a cursor after changing the sort.'
-  )
+  return v2Error('BAD_REQUEST', INVALID_CURSOR_MESSAGE)
 }
 
 const V2_CODE_BY_ORCHESTRATION_ERROR: Record<OrchestrationErrorCode, V2ErrorCode> = {

apps/sim/app/api/v2/workflows/route.test.ts

@@ -70,6 +70,13 @@ const lastConditions = () =>
 
 const lastOrderBy = () => dbChainMockFns.orderBy.mock.calls.at(-1) ?? []
 
+/**
+ * Timestamp keys order on `date_trunc('milliseconds', col)` rather than the raw
+ * column, so the mocked `sql` fragment carries the column in its interpolated
+ * values rather than being the column itself.
+ */
+const truncatedColumnOf = (entry: { column: { values?: unknown[] } }) => entry.column?.values?.[0]
+
 describe('GET /api/v2/workflows', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -133,11 +140,11 @@ describe('GET /api/v2/workflows', () => {
 
     await callList(`workspaceId=${WS}`)
 
-    expect(lastOrderBy()).toEqual([
-      { type: 'asc', column: schemaMock.workflow.sortOrder },
-      { type: 'asc', column: schemaMock.workflow.createdAt },
-      { type: 'asc', column: schemaMock.workflow.id },
-    ])
+    const orderBy = lastOrderBy()
+    expect(orderBy.map((e: { type: string }) => e.type)).toEqual(['asc', 'asc', 'asc'])
+    expect(orderBy[0].column).toBe(schemaMock.workflow.sortOrder)
+    expect(truncatedColumnOf(orderBy[1])).toBe(schemaMock.workflow.createdAt)
+    expect(orderBy[2].column).toBe(schemaMock.workflow.id)
   })
 
   it('orders by the requested field and direction', async () => {

apps/sim/app/api/v2/workflows/route.ts

@@ -11,11 +11,15 @@ import {
   v2ListWorkflowsContract,
 } from '@/lib/api/contracts/v2/workflows'
 import {
-  cursorDate,
-  type KeysetSort,
+  encodeKeyset,
+  type KeysetKey,
   keysetAfter,
+  keysetColumns,
   listOrderBy,
+  numberKey,
   searchFilter,
+  textKey,
+  timestampKey,
 } from '@/lib/api/list-query'
 import { parseRequest } from '@/lib/api/server'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
@@ -57,37 +61,20 @@ type WorkflowRow = {
  * `sortOrder` freely, and dropping `createdAt` from the tiebreak would reshuffle
  * every workspace's default list.
  */
+const workflowId = textKey<WorkflowRow>(workflow.id, (row) => row.id)
+const workflowCreatedAt = timestampKey<WorkflowRow>(workflow.createdAt, (row) => row.createdAt)
+
 const WORKFLOW_SORTS = {
-  position: {
-    keys: [workflow.sortOrder, workflow.createdAt, workflow.id],
-    encode: (row) => [row.sortOrder, cursorDate.encode(row.createdAt), row.id],
-    decode: ([sortOrder, createdAt, id]) => [
-      Number(sortOrder),
-      cursorDate.decode(createdAt),
-      String(id),
-    ],
-  },
-  name: {
-    keys: [workflow.name, workflow.id],
-    encode: (row) => [row.name, row.id],
-    decode: ([name, id]) => [String(name), String(id)],
-  },
-  createdAt: {
-    keys: [workflow.createdAt, workflow.id],
-    encode: (row) => [cursorDate.encode(row.createdAt), row.id],
-    decode: ([createdAt, id]) => [cursorDate.decode(createdAt), String(id)],
-  },
-  updatedAt: {
-    keys: [workflow.updatedAt, workflow.id],
-    encode: (row) => [cursorDate.encode(row.updatedAt), row.id],
-    decode: ([updatedAt, id]) => [cursorDate.decode(updatedAt), String(id)],
-  },
-  runCount: {
-    keys: [workflow.runCount, workflow.id],
-    encode: (row) => [row.runCount, row.id],
-    decode: ([runCount, id]) => [Number(runCount), String(id)],
-  },
-} satisfies Record<V2WorkflowSortBy, KeysetSort<WorkflowRow>>
+  position: [
+    numberKey<WorkflowRow>(workflow.sortOrder, (row) => row.sortOrder),
+    workflowCreatedAt,
+    workflowId,
+  ],
+  name: [textKey<WorkflowRow>(workflow.name, (row) => row.name), workflowId],
+  createdAt: [workflowCreatedAt, workflowId],
+  updatedAt: [timestampKey<WorkflowRow>(workflow.updatedAt, (row) => row.updatedAt), workflowId],
+  runCount: [numberKey<WorkflowRow>(workflow.runCount, (row) => row.runCount), workflowId],
+} satisfies Record<V2WorkflowSortBy, readonly KeysetKey<WorkflowRow>[]>
 
 export const GET = withRouteHandler(async (request: NextRequest) => {
   const requestId = generateId().slice(0, 8)
@@ -117,19 +104,22 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
     if (access) return v2WorkspaceAccessError(access)
 
     const sortKey = cursorSortKey(params.sortBy, params.sortOrder)
-    const sort: KeysetSort<WorkflowRow> = WORKFLOW_SORTS[params.sortBy]
-    const decoded = decodeSortedCursor(params.cursor, sortKey, sort.keys.length)
+    const keys: readonly KeysetKey<WorkflowRow>[] = WORKFLOW_SORTS[params.sortBy]
+    const decoded = decodeSortedCursor(params.cursor, sortKey)
     if (decoded.status === 'invalid') return v2CursorSortError()
 
+    // `null` here is a cursor whose values don't fit this sort — a client error, not an empty page.
+    const resumeAfter =
+      decoded.status === 'ok' ? keysetAfter(keys, decoded.keys, params.sortOrder) : undefined
+    if (resumeAfter === null) return v2CursorSortError()
+
     const conditions = [
       eq(workflow.workspaceId, params.workspaceId),
       isNull(workflow.archivedAt),
       params.folderId ? eq(workflow.folderId, params.folderId) : undefined,
       params.deployedOnly ? eq(workflow.isDeployed, true) : undefined,
       searchFilter(workflow.name, params.search),
-      decoded.status === 'ok'
-        ? keysetAfter(sort.keys, sort.decode(decoded.keys), params.sortOrder)
-        : undefined,
+      resumeAfter,
     ]
 
     const rows = await db
@@ -149,14 +139,15 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
       })
       .from(workflow)
       .where(and(...conditions))
-      .orderBy(...listOrderBy(sort.keys, params.sortOrder))
+      .orderBy(...listOrderBy(keysetColumns(keys), params.sortOrder))
       .limit(params.limit + 1)
 
     const hasMore = rows.length > params.limit
     const data = rows.slice(0, params.limit)
 
     const last = data.at(-1)
-    const nextCursor = hasMore && last ? encodeSortedCursor(sortKey, sort.encode(last)) : null
+    const nextCursor =
+      hasMore && last ? encodeSortedCursor(sortKey, encodeKeyset(keys, last)) : null
 
     const formatted: V2WorkflowListItem[] = data.map((w) => ({
       id: w.id,