fix(usage): reject invalid explicit dates in usage RPC date parsing

harjothkhara · harjothkhara · commit 803649738783 · 2026-06-16T11:18:57.000-07:00
usage.cost and sessions.usage accepted shape-valid but impossible dates such as 2026-02-30: parseDateParts validated only the YYYY-MM-DD regex, so Date.* silently rolled them over (2026-02-30 -&gt; 2026-03-02) and the RPC returned cost/usage for the wrong day. Out-of-range parts now fail a UTC round-trip check, and an explicitly provided unparseable date (bad format or impossible calendar date) returns INVALID_REQUEST instead of silently falling back to the default range. Absent/valid dates are unchanged.

[AI-assisted]
diff --git a/src/gateway/server-methods/usage.test.ts b/src/gateway/server-methods/usage.test.ts
@@ -94,6 +94,49 @@ describe("gateway usage helpers", () => {
     expect(testApi.parseDateToMs(undefined)).toBeUndefined();
   });
 
+  it("parseDateToMs rejects out-of-range calendar dates instead of rolling them over", () => {
+    // Impossible dates that still match the YYYY-MM-DD shape must not silently shift to a real day.
+    expect(testApi.parseDateToMs("2026-02-30")).toBeUndefined(); // would roll to Mar 2
+    expect(testApi.parseDateToMs("2026-04-31")).toBeUndefined(); // would roll to May 1
+    expect(testApi.parseDateToMs("2025-02-29")).toBeUndefined(); // non-leap Feb 29
+    expect(testApi.parseDateToMs("2026-13-01")).toBeUndefined(); // month too large
+    expect(testApi.parseDateToMs("2026-00-10")).toBeUndefined(); // month zero
+    expect(testApi.parseDateToMs("2026-01-00")).toBeUndefined(); // day zero
+    // Real leap day must stay valid (guard against over-rejection).
+    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: "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: undefined })).toBeUndefined();
+    expect(
+      testApi.findInvalidExplicitDate({ startDate: "2026-02-01", endDate: "2026-02-02" }),
+    ).toBeUndefined();
+  });
+
+  it("usage.cost rejects an explicitly provided invalid date with INVALID_REQUEST", async () => {
+    const respond = vi.fn();
+    await usageHandlers["usage.cost"]({
+      respond,
+      params: { startDate: "2026-02-30" },
+      context: { getRuntimeConfig: () => ({}) },
+    } as unknown as Parameters<(typeof usageHandlers)["usage.cost"]>[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");
+    // A rejected request must not query the cost loader for an unrelated range.
+    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);
@@ -327,7 +370,8 @@ describe("gateway usage helpers", () => {
 
     expect(vi.mocked(loadCostUsageSummaryFromCache)).toHaveBeenCalledTimes(3);
     expect(
-      vi.mocked(loadCostUsageSummaryFromCache)
+      vi
+        .mocked(loadCostUsageSummaryFromCache)
         .mock.calls.slice(1)
         .map((call) => call[0]?.agentId),
     ).toEqual(["main", "opus"]);
diff --git a/src/gateway/server-methods/usage.ts b/src/gateway/server-methods/usage.ts
@@ -180,9 +180,38 @@ const parseDateParts = (
   if (!Number.isFinite(year) || !Number.isFinite(monthIndex) || !Number.isFinite(day)) {
     return undefined;
   }
+  // The regex only checks shape; Date.* silently rolls impossible calendar dates over
+  // (e.g. 2026-02-30 -> 2026-03-02), so a typo'd day would return usage for the wrong day.
+  // Reject parts that don't round-trip through a UTC probe (also catches the JS 2-digit-year remap).
+  const probe = new Date(Date.UTC(year, monthIndex, day));
+  if (
+    probe.getUTCFullYear() !== year ||
+    probe.getUTCMonth() !== monthIndex ||
+    probe.getUTCDate() !== day
+  ) {
+    return undefined;
+  }
   return { year, monthIndex, day };
 };
 
+// usage.cost / sessions.usage accept optional startDate/endDate. parseDateParts returns
+// 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.
+const findInvalidExplicitDate = (params: {
+  startDate?: unknown;
+  endDate?: unknown;
+}): "startDate" | "endDate" | undefined => {
+  for (const field of ["startDate", "endDate"] as const) {
+    const raw = params[field];
+    if (typeof raw === "string" && raw.trim() !== "" && parseDateParts(raw) === undefined) {
+      return field;
+    }
+  }
+  return undefined;
+};
+
 /**
  * Parse a UTC offset string in the format UTC+H, UTC-H, UTC+HH, UTC-HH, UTC+H:MM, UTC-HH:MM.
  * Returns the UTC offset in minutes (east-positive), or undefined if invalid.
@@ -902,6 +931,7 @@ 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,
@@ -922,6 +952,21 @@ 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({
       startDate: params?.startDate,
@@ -956,6 +1001,18 @@ 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({
       startDate: p.startDate,
@@ -1335,7 +1392,8 @@ export const usageHandlers: GatewayRequestHandlers = {
         }
         const hiddenSession = hiddenSessions[hiddenIndex];
         const merged = mergedEntries[hiddenSession.entryIndex];
-        const usage = usageByEntryIndex[hiddenSession.entryIndex] ?? createEmptySessionCostSummary();
+        const usage =
+          usageByEntryIndex[hiddenSession.entryIndex] ?? createEmptySessionCostSummary();
         usage.sessionId = merged.sessionId;
         usage.sessionFile = merged.sessionFile;
         mergeSessionUsageInto(usage, summary);
