fix(api): reject malformed cursors with 400 instead of listing page one

decodeCursor returned null for an undecodable cursor and the callers treated
null as "no cursor", so GET /v1/templates, GET /v1/templates/pull and
GET /v1/email/logs answered 200 with the first page. A client following a
stale or corrupted cursor looped over page one with no error.

- decodeCursor (packages/db) now accepts only a value encodeCursor could
  produce: the decoded date must re-encode to the input. This rejects
  lookalikes such as "5|abc", which new Date() parses as a valid date.
- apps/api/src/lib/cursor.ts parseCursorParam: absent cursor is the first
  page; a present but invalid cursor sets 400 and throws, which the standard
  error handler reports as { error, code: "BAD_REQUEST" }.
- The three cursor-paginated routes use it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GxJAQNUP4FKZHL1yzPDsGd

Author: stewartjarod

apps/api/src/__tests__/email-logs.test.ts

@@ -1,13 +1,17 @@
 import { Elysia } from "elysia";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { AuthContext } from "../middleware/auth";
+import { createErrorHarness } from "./error-handler-harness";
 
 const { mockListEmailLogs, mockGetEmailLogByMessageId } = vi.hoisted(() => ({
   mockListEmailLogs: vi.fn(),
   mockGetEmailLogByMessageId: vi.fn(),
 }));
 
-vi.mock("@wraps/db", () => ({
+vi.mock("@wraps/db", async (importOriginal) => ({
+  // Real decodeCursor: the route validates cursors with it before the mocked
+  // repository call.
+  ...(await importOriginal<typeof import("@wraps/db")>()),
   listEmailLogs: mockListEmailLogs,
   getEmailLogByMessageId: mockGetEmailLogByMessageId,
 }));
@@ -130,19 +134,38 @@ describe("Email Logs Route", () => {
         total: 0,
         nextCursor: null,
       });
+      const cursor = Buffer.from(
+        "2026-05-20T10:00:00.000Z|log-1",
+        "utf8"
+      ).toString("base64url");
 
       const app = createApp();
       const response = await app.handle(
-        authedGet("/v1/email/logs?cursor=2026-05-20T10%3A00%3A00.000Z")
+        authedGet(`/v1/email/logs?cursor=${encodeURIComponent(cursor)}`)
       );
       const body = await response.json();
 
       expect(response.status).toBe(200);
       expect(body).toHaveProperty("logs");
       expect(mockListEmailLogs).toHaveBeenCalledWith(
         mockAuthContext.organizationId,
-        expect.objectContaining({ cursor: "2026-05-20T10:00:00.000Z" })
+        expect.objectContaining({ cursor })
+      );
+    });
+
+    it("rejects a malformed cursor with 400 instead of listing page one", async () => {
+      // Mount the real onError handler so the body is the API error shape.
+      const { app: harnessApp } = createErrorHarness();
+      const app = harnessApp.use(emailLogsRoutes);
+      const response = await app.handle(
+        authedGet("/v1/email/logs?cursor=2026-05-20T10%3A00%3A00.000Z")
       );
+
+      expect(response.status).toBe(400);
+      const body = await response.json();
+      expect(body.code).toBe("BAD_REQUEST");
+      expect(body.error).toMatch(/cursor/i);
+      expect(mockListEmailLogs).not.toHaveBeenCalled();
     });
 
     it("passes limit to repository", async () => {

apps/api/src/__tests__/templates-api-db.test.ts

@@ -591,6 +591,106 @@ describe("GET /v1/templates/pull on the combined app", () => {
   });
 });
 
+describe("cursor validation on the template list routes", () => {
+  const b64 = (raw: string) => Buffer.from(raw).toString("base64url");
+  const malformedCursors = [
+    "not-a-real-cursor!!",
+    "%%%",
+    "",
+    b64('{"createdAt":"2026-05-20T10:00:00.000Z","id":"x"}'),
+    b64("5|abc"),
+    b64("2026-05-20T10:00:00Z|abc"),
+  ];
+
+  for (const path of ["/v1/templates", "/v1/templates/pull"]) {
+    it(`${path} rejects a malformed cursor with 400 BAD_REQUEST`, async () => {
+      await db.insert(template).values(
+        templateRow(`${PREFIX}-bad-cursor`, ids.org, {
+          slug: "bad-cursor",
+          source: "// bad",
+        })
+      );
+      const app = appFor(ids.org, ids.user);
+
+      for (const cursor of malformedCursors) {
+        const res = await app.handle(
+          new Request(
+            `http://localhost${path}?limit=1&cursor=${encodeURIComponent(cursor)}`
+          )
+        );
+        expect(res.status, `cursor=${JSON.stringify(cursor)}`).toBe(400);
+        const body = await res.json();
+        expect(body.code).toBe("BAD_REQUEST");
+        expect(body.error).toMatch(/cursor/i);
+      }
+    });
+  }
+
+  it("/v1/templates/pull rejects a malformed cursor with 400 even without limit", async () => {
+    const app = appFor(ids.org, ids.user);
+    for (const cursor of malformedCursors) {
+      const res = await app.handle(
+        new Request(
+          `http://localhost/v1/templates/pull?cursor=${encodeURIComponent(cursor)}`
+        )
+      );
+      expect(res.status, `cursor=${JSON.stringify(cursor)}`).toBe(400);
+      const body = await res.json();
+      expect(body.code).toBe("BAD_REQUEST");
+    }
+  });
+
+  it("/v1/templates/pull walks every page with limit=1 and no row repeats or drops", async () => {
+    const now = Date.now();
+    await db.insert(template).values([
+      templateRow(`${PREFIX}-walk-1`, ids.org, {
+        slug: "walk-1",
+        source: "// 1",
+        updatedAt: new Date(now - 3000),
+      }),
+      templateRow(`${PREFIX}-walk-2`, ids.org, {
+        slug: "walk-2",
+        source: "// 2",
+        updatedAt: new Date(now - 2000),
+      }),
+      templateRow(`${PREFIX}-walk-3`, ids.org, {
+        slug: "walk-3",
+        source: "// 3",
+        updatedAt: new Date(now - 1000),
+      }),
+    ]);
+
+    const app = appFor(ids.org, ids.user);
+    const seen: string[] = [];
+    let cursor: string | null = null;
+    for (let page = 0; page < 20; page++) {
+      const qs = cursor
+        ? `limit=1&cursor=${encodeURIComponent(cursor)}`
+        : "limit=1";
+      const res = await app.handle(
+        new Request(`http://localhost/v1/templates/pull?${qs}`)
+      );
+      expect(res.status).toBe(200);
+      const body = await res.json();
+      for (const row of body.templates) {
+        if (row.id.startsWith(`${PREFIX}-walk-`)) {
+          seen.push(row.id);
+        }
+      }
+      cursor = body.nextCursor;
+      if (!cursor) {
+        break;
+      }
+    }
+
+    expect(seen).toEqual([
+      `${PREFIX}-walk-3`,
+      `${PREFIX}-walk-2`,
+      `${PREFIX}-walk-1`,
+    ]);
+  });
+});
+
 describe("POST /v1/templates/:id/duplicate", () => {
   it("copies channel and previewText, and resets slug/sesTemplateName/publishedAt/status", async () => {
     const id = `${PREFIX}-sms-original`;

apps/api/src/lib/cursor.ts

@@ -0,0 +1,26 @@
+import { decodeCursor } from "@wraps/db";
+
+export const INVALID_CURSOR_MESSAGE =
+  "Invalid cursor. Pass the nextCursor from a previous page unchanged, or omit cursor to start from the first page.";
+
+/**
+ * Decode a client-supplied keyset cursor from a query string.
+ *
+ * An absent cursor is the first page and returns null. A present cursor that
+ * does not decode is a 400: treating it as the first page makes a client that
+ * follows a stale or corrupted cursor loop over page one with no error.
+ */
+export function parseCursorParam(
+  cursor: string | undefined,
+  set: { status?: unknown }
+): { createdAt: Date; id: string } | null {
+  if (cursor === undefined) {
+    return null;
+  }
+  const decoded = decodeCursor(cursor);
+  if (decoded === null) {
+    set.status = 400;
+    throw new Error(INVALID_CURSOR_MESSAGE);
+  }
+  return decoded;
+}

apps/api/src/routes/email-logs.ts

@@ -1,5 +1,6 @@
 import { getEmailLogByMessageId, listEmailLogs } from "@wraps/db";
 import { t } from "elysia";
+import { parseCursorParam } from "../lib/cursor";
 import { createAuthenticatedRoutes, getAuth } from "../middleware/auth";
 
 export const emailLogsRoutes = createAuthenticatedRoutes("/v1/email/logs")
@@ -9,6 +10,8 @@ export const emailLogsRoutes = createAuthenticatedRoutes("/v1/email/logs")
     async (ctx) => {
       const authContext = getAuth(ctx);
       const { status, limit, cursor } = ctx.query;
+      // Reject a malformed cursor here; listEmailLogs would silently list page one.
+      parseCursorParam(cursor, ctx.set);
 
       const result = await listEmailLogs(authContext.organizationId, {
         status,

apps/api/src/routes/templates-sync.ts

@@ -8,19 +8,11 @@
  * GET  /v1/templates/pull       - List all code-pushed templates with source
  */
 
-import {
-  and,
-  db,
-  decodeCursor,
-  desc,
-  encodeCursor,
-  eq,
-  or,
-  template,
-} from "@wraps/db";
+import { and, db, desc, encodeCursor, eq, or, template } from "@wraps/db";
 import { lt } from "drizzle-orm";
 import { t } from "elysia";
 import { trackFirstResourceCreated } from "../lib/activation-tracking";
+import { parseCursorParam } from "../lib/cursor";
 import type { AuthContext } from "../middleware/auth";
 import { createAuthenticatedRoutes, getAuth } from "../middleware/auth";
 
@@ -234,6 +226,8 @@ export const templatesSyncRoutes = createAuthenticatedRoutes("/v1/templates")
       const authContext = getAuth(ctx);
       const { limit, cursor, source } = ctx.query;
       const includeSource = source ?? true;
+      // Validate before branching: a bad cursor is a 400 with or without `limit`.
+      const decoded = parseCursorParam(cursor, ctx.set);
 
       type PullRow = {
         id: string;
@@ -296,7 +290,6 @@ export const templatesSyncRoutes = createAuthenticatedRoutes("/v1/templates")
         eq(template.organizationId, authContext.organizationId),
         eq(template.sourceFormat, "react-email"),
       ];
-      const decoded = cursor ? decodeCursor(cursor) : null;
       if (decoded) {
         const keyset = or(
           lt(template.updatedAt, decoded.createdAt),

apps/api/src/routes/templates.ts

@@ -26,7 +26,6 @@ import {
   and,
   awsAccount,
   db,
-  decodeCursor,
   desc,
   encodeCursor,
   eq,
@@ -45,6 +44,7 @@ import { normalizePlainTextForSes } from "@wraps/template-render";
 import { ilike, lt } from "drizzle-orm";
 import { t } from "elysia";
 import { trackFirstResourceCreated } from "../lib/activation-tracking";
+import { parseCursorParam } from "../lib/cursor";
 import { createAuthenticatedRoutes, getAuth } from "../middleware/auth";
 import { rateLimitMiddleware } from "../middleware/rate-limit";
 import { getCredentials } from "../services/credentials";
@@ -354,7 +354,7 @@ export const templatesRoutes = createAuthenticatedRoutes("/v1/templates")
       if (search) {
         conditions.push(ilike(template.name, `%${escapeIlike(search)}%`));
       }
-      const decoded = cursor ? decodeCursor(cursor) : null;
+      const decoded = parseCursorParam(cursor, ctx.set);
       if (decoded) {
         const keyset = or(
           lt(template.updatedAt, decoded.createdAt),

packages/db/src/__tests__/repository-message-sends.test.ts

@@ -230,6 +230,22 @@ describe("Repository: listEmailLogs", () => {
       id: "abc",
     });
   });
+
+  it("rejects base64 payloads that only look like a cursor", () => {
+    const b64 = (s: string) => Buffer.from(s).toString("base64url");
+    // JSON with no separator
+    expect(
+      decodeCursor(b64('{"createdAt":"2026-05-20T10:00:00.000Z","id":"abc"}'))
+    ).toBeNull();
+    // new Date("5") is a valid date, so a lenient parse would accept this
+    expect(decodeCursor(b64("5|abc"))).toBeNull();
+    // Parses, but is not the canonical form encodeCursor emits
+    expect(decodeCursor(b64("2026-05-20T10:00:00Z|abc"))).toBeNull();
+    // Empty id
+    expect(decodeCursor(b64("2026-05-20T10:00:00.000Z|"))).toBeNull();
+    // Not base64 at all
+    expect(decodeCursor("%%%")).toBeNull();
+  });
 });
 
 describe("Repository: getEmailLogByMessageId", () => {

packages/db/src/repositories/message-sends.ts

@@ -20,6 +20,11 @@ export function encodeCursor(createdAt: Date, id: string): string {
   return Buffer.from(`${createdAt.toISOString()}|${id}`).toString("base64url");
 }
 
+// Returns null for anything encodeCursor could not have produced. Accepting a
+// lookalike is worse than rejecting it: `new Date("5")` parses, so a lenient
+// decode turns "5|abc" into a 2001 keyset position, and a client following a
+// stale or corrupted cursor silently loops over the first page. Callers decide
+// what null means; the API routes answer 400.
 export function decodeCursor(
   cursor: string
 ): { createdAt: Date; id: string } | null {
@@ -33,6 +38,10 @@ export function decodeCursor(
   if (Number.isNaN(createdAt.getTime()) || !id) {
     return null;
   }
+  // Canonical-form check: re-encoding must reproduce the input exactly.
+  if (encodeCursor(createdAt, id) !== cursor) {
+    return null;
+  }
   return { createdAt, id };
 }