fix(usage): reject inverted startDate-endDate range in usage.cost and sessions.usage (#94096)

Alix-007 · Peter Steinberger · web-flow · commit 640258d7b31d · 2026-06-30T12:55:43.000-07:00
* fix(usage): reject inverted startDate-endDate range

* chore: retrigger CI for real behavior proof check

* refactor(usage): resolve validated date ranges once

---------

Co-authored-by: Peter Steinberger &lt;steipete@golden-gate.local&gt;
diff --git a/src/gateway/server-methods/usage.test.ts b/src/gateway/server-methods/usage.test.ts
@@ -72,14 +72,23 @@ describe("gateway usage helpers", () => {
   });
 
   function expectUtcDateRange(
-    range: ReturnType<typeof testApi.parseDateRange>,
+    result: ReturnType<typeof testApi.resolveDateRange>,
     startDate: string,
     endDate: string,
   ) {
+    const range = expectDateRange(result);
     expect(range.startMs).toBe(testApi.parseDateToMs(startDate));
     expect(range.endMs).toBe(testApi.parseDateToMs(endDate)! + dayMs - 1);
   }
 
+  function expectDateRange(result: ReturnType<typeof testApi.resolveDateRange>) {
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      throw new Error(result.error);
+    }
+    return result.value;
+  }
+
   beforeEach(() => {
     testApi.costUsageCache.clear();
     vi.useRealTimers();
@@ -106,21 +115,18 @@ describe("gateway usage helpers", () => {
     expect(testApi.parseDateToMs("2024-02-29")).toBe(Date.UTC(2024, 1, 29));
   });
 
-  it("findInvalidExplicitDate flags provided-but-unparseable dates and ignores absent/valid ones", () => {
-    // Explicitly provided invalid dates (bad format or impossible calendar date) are reported.
-    expect(testApi.findInvalidExplicitDate({ startDate: "2026-02-30" })).toBe("startDate");
-    expect(testApi.findInvalidExplicitDate({ endDate: "2026-2-5" })).toBe("endDate");
-    expect(testApi.findInvalidExplicitDate({ startDate: 0 })).toBe("startDate");
-    expect(testApi.findInvalidExplicitDate({ endDate: [] })).toBe("endDate");
-    expect(
-      testApi.findInvalidExplicitDate({ startDate: "2026-02-01", endDate: "2026-13-01" }),
-    ).toBe("endDate");
-    // Absent or valid dates are not flagged, so they still fall through to the default range.
-    expect(testApi.findInvalidExplicitDate({})).toBeUndefined();
-    expect(testApi.findInvalidExplicitDate({ startDate: "", endDate: null })).toBeUndefined();
-    expect(
-      testApi.findInvalidExplicitDate({ startDate: "2026-02-01", endDate: "2026-02-02" }),
-    ).toBeUndefined();
+  it.each([
+    [{ startDate: "2026-02-30" }, "invalid startDate"],
+    [{ endDate: "2026-2-5" }, "invalid endDate"],
+    [{ startDate: 0 }, "invalid startDate"],
+    [{ endDate: [] }, "invalid endDate"],
+    [{ startDate: "2026-02-01", endDate: "2026-13-01" }, "invalid endDate"],
+    [{ startDate: "2026-02-03", endDate: "2026-02-02" }, "startDate must not be after endDate"],
+  ])("resolveDateRange rejects invalid explicit ranges", (params, error) => {
+    expect(testApi.resolveDateRange(params)).toEqual({
+      ok: false,
+      error: expect.stringContaining(error),
+    });
   });
 
   it("usage.cost rejects an explicitly provided invalid date with INVALID_REQUEST", async () => {
@@ -139,6 +145,25 @@ describe("gateway usage helpers", () => {
     expect(vi.mocked(loadCostUsageSummaryFromCache)).not.toHaveBeenCalled();
   });
 
+  it.each(["usage.cost", "sessions.usage"] as const)(
+    "%s rejects startDate after endDate with INVALID_REQUEST",
+    async (method) => {
+      const respond = vi.fn();
+      await usageHandlers[method]({
+        respond,
+        params: { startDate: "2026-02-03", endDate: "2026-02-02" },
+        context: { getRuntimeConfig: vi.fn(() => ({})) },
+      } as unknown as Parameters<(typeof usageHandlers)[typeof method]>[0]);
+
+      expect(respond).toHaveBeenCalledTimes(1);
+      const [ok, payload, error] = respond.mock.calls[0];
+      expect(ok).toBe(false);
+      expect(payload).toBeUndefined();
+      expect(JSON.stringify(error)).toContain("startDate must not be after endDate");
+      expect(vi.mocked(loadCostUsageSummaryFromCache)).not.toHaveBeenCalled();
+    },
+  );
+
   it("parseUtcOffsetToMinutes supports whole-hour and half-hour offsets", () => {
     expect(testApi.parseUtcOffsetToMinutes("UTC-4")).toBe(-240);
     expect(testApi.parseUtcOffsetToMinutes("UTC+5:30")).toBe(330);
@@ -160,80 +185,91 @@ describe("gateway usage helpers", () => {
     expect(testApi.parseDays("nope")).toBeUndefined();
   });
 
-  it("parseDateRange uses explicit start/end as UTC when mode is missing (backward compatible)", () => {
-    const range = testApi.parseDateRange({ startDate: "2026-02-01", endDate: "2026-02-02" });
-    expectUtcDateRange(range, "2026-02-01", "2026-02-02");
-  });
-
-  it("parseDateRange uses explicit UTC mode", () => {
-    const range = testApi.parseDateRange({
+  it("resolveDateRange uses explicit start/end as UTC when mode is missing (backward compatible)", () => {
+    const result = testApi.resolveDateRange({
       startDate: "2026-02-01",
       endDate: "2026-02-02",
-      mode: "utc",
     });
-    expectUtcDateRange(range, "2026-02-01", "2026-02-02");
+    expectUtcDateRange(result, "2026-02-01", "2026-02-02");
   });
 
-  it("parseDateRange uses specific UTC offset for explicit dates", () => {
-    const range = testApi.parseDateRange({
+  it("resolveDateRange uses explicit UTC mode", () => {
+    const result = testApi.resolveDateRange({
       startDate: "2026-02-01",
       endDate: "2026-02-02",
-      mode: "specific",
-      utcOffset: "UTC+5:30",
+      mode: "utc",
     });
+    expectUtcDateRange(result, "2026-02-01", "2026-02-02");
+  });
+
+  it("resolveDateRange uses specific UTC offset for explicit dates", () => {
+    const range = expectDateRange(
+      testApi.resolveDateRange({
+        startDate: "2026-02-01",
+        endDate: "2026-02-02",
+        mode: "specific",
+        utcOffset: "UTC+5:30",
+      }),
+    );
     const start = Date.UTC(2026, 1, 1) - 5.5 * 60 * 60 * 1000;
     const endStart = Date.UTC(2026, 1, 2) - 5.5 * 60 * 60 * 1000;
     expect(range.startMs).toBe(start);
     expect(range.endMs).toBe(endStart + dayMs - 1);
   });
 
-  it("parseDateRange falls back to UTC when specific mode offset is missing or invalid", () => {
-    const missingOffset = testApi.parseDateRange({
-      startDate: "2026-02-01",
-      endDate: "2026-02-02",
-      mode: "specific",
-    });
-    const invalidOffset = testApi.parseDateRange({
-      startDate: "2026-02-01",
-      endDate: "2026-02-02",
-      mode: "specific",
-      utcOffset: "bad-value",
-    });
+  it("resolveDateRange falls back to UTC when specific mode offset is missing or invalid", () => {
+    const missingOffset = expectDateRange(
+      testApi.resolveDateRange({
+        startDate: "2026-02-01",
+        endDate: "2026-02-02",
+        mode: "specific",
+      }),
+    );
+    const invalidOffset = expectDateRange(
+      testApi.resolveDateRange({
+        startDate: "2026-02-01",
+        endDate: "2026-02-02",
+        mode: "specific",
+        utcOffset: "bad-value",
+      }),
+    );
     expect(missingOffset.startMs).toBe(Date.UTC(2026, 1, 1));
     expect(missingOffset.endMs).toBe(Date.UTC(2026, 1, 2) + dayMs - 1);
     expect(invalidOffset.startMs).toBe(Date.UTC(2026, 1, 1));
     expect(invalidOffset.endMs).toBe(Date.UTC(2026, 1, 2) + dayMs - 1);
   });
 
-  it("parseDateRange uses specific offset for today/day math after UTC midnight", () => {
+  it("resolveDateRange uses specific offset for today/day math after UTC midnight", () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-02-17T03:57:00.000Z"));
-    const range = testApi.parseDateRange({
-      days: 1,
-      mode: "specific",
-      utcOffset: "UTC-5",
-    });
+    const range = expectDateRange(
+      testApi.resolveDateRange({
+        days: 1,
+        mode: "specific",
+        utcOffset: "UTC-5",
+      }),
+    );
     expect(range.startMs).toBe(Date.UTC(2026, 1, 16, 5, 0, 0, 0));
     expect(range.endMs).toBe(Date.UTC(2026, 1, 17, 4, 59, 59, 999));
   });
 
-  it("parseDateRange uses gateway local day boundaries in gateway mode", () => {
+  it("resolveDateRange uses gateway local day boundaries in gateway mode", () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-02-05T12:34:56.000Z"));
-    const range = testApi.parseDateRange({ days: 1, mode: "gateway" });
+    const range = expectDateRange(testApi.resolveDateRange({ days: 1, mode: "gateway" }));
     const expectedStart = new Date(2026, 1, 5).getTime();
     expect(range.startMs).toBe(expectedStart);
     expect(range.endMs).toBe(expectedStart + dayMs - 1);
   });
 
-  it("parseDateRange clamps days to at least 1 and defaults to 30 days", () => {
+  it("resolveDateRange clamps days to at least 1 and defaults to 30 days", () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-02-05T12:34:56.000Z"));
-    const oneDay = testApi.parseDateRange({ days: 0 });
+    const oneDay = expectDateRange(testApi.resolveDateRange({ days: 0 }));
     expect(oneDay.endMs).toBe(Date.UTC(2026, 1, 5) + dayMs - 1);
     expect(oneDay.startMs).toBe(Date.UTC(2026, 1, 5));
 
-    const def = testApi.parseDateRange({});
+    const def = expectDateRange(testApi.resolveDateRange({}));
     expect(def.endMs).toBe(Date.UTC(2026, 1, 5) + dayMs - 1);
     expect(def.startMs).toBe(Date.UTC(2026, 1, 5) - 29 * dayMs);
   });
diff --git a/src/gateway/server-methods/usage.ts b/src/gateway/server-methods/usage.ts
@@ -69,6 +69,9 @@ const SESSIONS_USAGE_CACHE_READ_CONCURRENCY = 12;
 const DAY_MS = 24 * 60 * 60 * 1000;
 
 type DateRange = { startMs: number; endMs: number };
+// Keep validation and parsed timestamps in one result so handlers cannot forward
+// an invalid or backwards window to the usage loaders.
+type DateRangeResolution = { ok: true; value: DateRange } | { ok: false; error: string };
 type DateInterpretation =
   | { mode: "utc" | "gateway" }
   | { mode: "specific"; utcOffsetMinutes: number };
@@ -172,7 +175,7 @@ const parseDateParts = (
 // undefined for both absent and invalid input, so an explicitly supplied but unparseable
 // date (bad format or impossible calendar date like 2026-02-30) would otherwise silently
 // fall through to the default range and return a successful response for an unrelated range.
-// Return the offending field so handlers can reject it instead of querying the wrong window.
+// Return the offending field so range resolution can reject it instead of querying the wrong window.
 const findInvalidExplicitDate = (params: {
   startDate?: unknown;
   endDate?: unknown;
@@ -309,14 +312,22 @@ const resolveRangeDays = (raw: unknown): number | "all" | undefined => {
  * Get date range from params (startDate/endDate or days).
  * Falls back to last 30 days if not provided.
  */
-const parseDateRange = (params: {
+const resolveDateRange = (params: {
   startDate?: unknown;
   endDate?: unknown;
   days?: unknown;
   range?: unknown;
   mode?: unknown;
   utcOffset?: unknown;
-}): DateRange => {
+}): DateRangeResolution => {
+  const invalidDate = findInvalidExplicitDate(params);
+  if (invalidDate) {
+    return {
+      ok: false,
+      error: `invalid ${invalidDate}: expected a valid YYYY-MM-DD calendar date`,
+    };
+  }
+
   const now = new Date();
   const interpretation = resolveDateInterpretation(params);
   const todayStartMs = getTodayStartMs(now, interpretation);
@@ -326,29 +337,32 @@ const parseDateRange = (params: {
   const endMs = parseDateToMs(params.endDate, interpretation);
 
   if (startMs !== undefined && endMs !== undefined) {
+    if (startMs > endMs) {
+      return { ok: false, error: "startDate must not be after endDate" };
+    }
     // endMs should be end of day
-    return { startMs, endMs: endMs + DAY_MS - 1 };
+    return { ok: true, value: { startMs, endMs: endMs + DAY_MS - 1 } };
   }
 
   const rangeDays = resolveRangeDays(params.range);
   if (rangeDays === "all") {
-    return { startMs: 0, endMs: todayEndMs };
+    return { ok: true, value: { startMs: 0, endMs: todayEndMs } };
   }
   if (rangeDays !== undefined) {
     const start = todayStartMs - (rangeDays - 1) * DAY_MS;
-    return { startMs: start, endMs: todayEndMs };
+    return { ok: true, value: { startMs: start, endMs: todayEndMs } };
   }
 
   const days = parseDays(params.days);
   if (days !== undefined) {
     const clampedDays = Math.max(1, days);
     const start = todayStartMs - (clampedDays - 1) * DAY_MS;
-    return { startMs: start, endMs: todayEndMs };
+    return { ok: true, value: { startMs: start, endMs: todayEndMs } };
   }
 
   // Default to last 30 days
   const defaultStartMs = todayStartMs - 29 * DAY_MS;
-  return { startMs: defaultStartMs, endMs: todayEndMs };
+  return { ok: true, value: { startMs: defaultStartMs, endMs: todayEndMs } };
 };
 
 type DiscoveredSessionWithAgent = DiscoveredSession & { agentId: string };
@@ -875,13 +889,12 @@ function mergeUsageCacheStatus(
 // Exposed for unit tests (kept as a single export to avoid widening the public API surface).
 export const testApi = {
   parseDateParts,
-  findInvalidExplicitDate,
   parseUtcOffsetToMinutes,
   resolveDateInterpretation,
   parseDateToMs,
   getTodayStartMs,
   parseDays,
-  parseDateRange,
+  resolveDateRange,
   discoverAllSessionsForUsage,
   loadCostUsageSummaryCached,
   costUsageCache,
@@ -896,30 +909,20 @@ export const usageHandlers: GatewayRequestHandlers = {
     respond(true, summary, undefined);
   },
   "usage.cost": async ({ respond, params, context }) => {
-    const invalidDate = findInvalidExplicitDate({
-      startDate: params?.startDate,
-      endDate: params?.endDate,
-    });
-    if (invalidDate) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid ${invalidDate}: expected a valid YYYY-MM-DD calendar date`,
-        ),
-      );
-      return;
-    }
-    const config = context.getRuntimeConfig();
-    const { startMs, endMs } = parseDateRange({
+    const dateRange = resolveDateRange({
       startDate: params?.startDate,
       endDate: params?.endDate,
       days: params?.days,
       range: params?.range,
       mode: params?.mode,
       utcOffset: params?.utcOffset,
     });
+    if (!dateRange.ok) {
+      respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, dateRange.error));
+      return;
+    }
+    const config = context.getRuntimeConfig();
+    const { startMs, endMs } = dateRange.value;
     const agentId = normalizeOptionalString(params?.agentId);
     const agentScope = params?.agentScope === "all" && !agentId ? "all" : undefined;
     const summary = await loadCostUsageSummaryCached({
@@ -945,26 +948,19 @@ export const usageHandlers: GatewayRequestHandlers = {
     }
 
     const p = params;
-    const invalidDate = findInvalidExplicitDate({ startDate: p.startDate, endDate: p.endDate });
-    if (invalidDate) {
-      respond(
-        false,
-        undefined,
-        errorShape(
-          ErrorCodes.INVALID_REQUEST,
-          `invalid ${invalidDate}: expected a valid YYYY-MM-DD calendar date`,
-        ),
-      );
-      return;
-    }
-    const config = context.getRuntimeConfig();
-    const { startMs, endMs } = parseDateRange({
+    const dateRange = resolveDateRange({
       startDate: p.startDate,
       endDate: p.endDate,
       range: p.range,
       mode: p.mode,
       utcOffset: p.utcOffset,
     });
+    if (!dateRange.ok) {
+      respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, dateRange.error));
+      return;
+    }
+    const config = context.getRuntimeConfig();
+    const { startMs, endMs } = dateRange.value;
     const limit = typeof p.limit === "number" && Number.isFinite(p.limit) ? p.limit : 50;
     const includeContextWeight = p.includeContextWeight ?? false;
     const specificKey = normalizeOptionalString(p.key) ?? null;
