diff --git a/src/lib/__tests__/api-response-zod.test.ts b/src/lib/__tests__/api-response-zod.test.ts new file mode 100644 index 000000000..2758da691 --- /dev/null +++ b/src/lib/__tests__/api-response-zod.test.ts @@ -0,0 +1,126 @@ +import { describe, it, expect } from "vitest"; +import { z } from "zod/v4"; +import { + returnAllZodIssues, + sanitiseZodIssues, +} from "../api-response"; + +// v1.4.42 W2 — every Zod-validated route historically returned +// `parsed.error.issues[0].message`, dropping every issue past the first. +// `returnAllZodIssues` is the additive replacement: clients that only +// read `error` keep working, new callers branch on `details.issues`. + +const schema = z.object({ + version: z.literal(1), + widgets: z.array(z.object({ id: z.string() })).min(1), + comparisonBaseline: z.enum(["none", "lastMonth", "lastYear"]).optional(), +}); + +describe("returnAllZodIssues", () => { + it("returns 422 by default with a sanitised issue list", async () => { + const parsed = schema.safeParse({}); + expect(parsed.success).toBe(false); + if (parsed.success) return; + + const response = returnAllZodIssues(parsed.error); + expect(response.status).toBe(422); + + const body = (await response.json()) as { + data: null; + error: string; + details: { issues: Array<{ path: string; code: string; message: string }> }; + }; + expect(body.data).toBeNull(); + expect(body.error).toBe("Validation failed"); + expect(body.details.issues.length).toBeGreaterThanOrEqual(2); + expect(body.details.issues[0]).toMatchObject({ + code: expect.any(String), + message: expect.any(String), + path: expect.any(String), + }); + }); + + it("surfaces TWO simultaneous validation errors", async () => { + const parsed = schema.safeParse({ version: 2, widgets: [] }); + expect(parsed.success).toBe(false); + if (parsed.success) return; + + const response = returnAllZodIssues(parsed.error); + const body = (await response.json()) as { + details: { issues: Array<{ path: string; code: string }> }; + }; + expect(body.details.issues.length).toBe(2); + const paths = body.details.issues.map((i) => i.path).sort(); + expect(paths).toEqual(["version", "widgets"]); + }); + + it("surfaces THREE simultaneous validation errors", async () => { + const parsed = schema.safeParse({ + version: 2, + widgets: [], + comparisonBaseline: "yesterday", + }); + expect(parsed.success).toBe(false); + if (parsed.success) return; + + const response = returnAllZodIssues(parsed.error); + const body = (await response.json()) as { + details: { issues: Array<{ path: string; code: string }> }; + }; + expect(body.details.issues.length).toBe(3); + const paths = body.details.issues.map((i) => i.path).sort(); + expect(paths).toEqual(["comparisonBaseline", "version", "widgets"]); + }); + + it("flattens nested paths with dots", async () => { + const nested = z.object({ outer: z.object({ inner: z.string() }) }); + const parsed = nested.safeParse({ outer: { inner: 5 } }); + if (parsed.success) throw new Error("expected failure"); + + const sanitised = sanitiseZodIssues(parsed.error.issues); + expect(sanitised[0].path).toBe("outer.inner"); + }); + + it("does NOT echo issue.params (privacy: may contain user input)", async () => { + const parsed = schema.safeParse({ + version: 99, + widgets: [{ id: "x" }], + }); + if (parsed.success) throw new Error("expected failure"); + + const response = returnAllZodIssues(parsed.error); + const body = (await response.json()) as { + details: { issues: Array> }; + }; + for (const issue of body.details.issues) { + expect(issue).not.toHaveProperty("params"); + // Only path / code / message survive the sanitiser. + expect(Object.keys(issue).sort()).toEqual(["code", "message", "path"]); + } + }); + + it("respects a custom status code", async () => { + const parsed = schema.safeParse({}); + if (parsed.success) throw new Error("expected failure"); + const response = returnAllZodIssues(parsed.error, 400); + expect(response.status).toBe(400); + }); + + it("forwards meta.errorCode and headers like apiError", async () => { + const parsed = schema.safeParse({}); + if (parsed.success) throw new Error("expected failure"); + + const response = returnAllZodIssues(parsed.error, 422, { + errorCode: "dashboard.widgets.invalid", + headers: { "X-Test": "yes" }, + }); + expect(response.headers.get("X-Test")).toBe("yes"); + const body = (await response.json()) as { + meta?: { errorCode?: string; headers?: unknown }; + }; + expect(body.meta?.errorCode).toBe("dashboard.widgets.invalid"); + // Headers are consumed by the NextResponse constructor and stripped + // from the JSON envelope, matching apiError's contract. + expect(body.meta?.headers).toBeUndefined(); + }); +}); diff --git a/src/lib/api-response.ts b/src/lib/api-response.ts index 4245696b8..797d420b4 100644 --- a/src/lib/api-response.ts +++ b/src/lib/api-response.ts @@ -1,10 +1,75 @@ import { isIP } from "node:net"; import { NextResponse } from "next/server"; +import type { ZodError, ZodIssue } from "zod/v4"; export function apiSuccess(data: T, status = 200) { return NextResponse.json({ data, error: null }, { status }); } +/** + * Sanitised view of a single Zod issue. We surface `path`, `code` and + * `message` only — `issue.params` may echo the offending user input + * (e.g. a too-long string, a regex source) and we do not want that + * round-tripped to mobile callers or persisted into the audit ledger. + */ +export interface SanitisedZodIssue { + path: string; + code: string; + message: string; +} + +/** + * v1.4.42 W2 — multi-issue Zod error envelope. + * + * Historic pattern was `apiError(parsed.error.issues[0].message, 422)` + * which dropped every issue past the first. The iOS contract debug + * loop hit this hard: a single PUT with three wrong fields produced + * one error, the client fixed it, re-sent, hit the next error, and + * so on — three round-trips for one stack of mistakes. + * + * Shape kept additive with `apiError` so existing clients that only + * read `error` keep working; new callers branch on `details.issues`. + * + * Privacy: only `path`, `code` and `message` are echoed. `issue.params` + * (which can carry the raw rejected value for some Zod issue codes) + * stays server-side. + */ +export function sanitiseZodIssues( + issues: readonly ZodIssue[], +): SanitisedZodIssue[] { + return issues.map((issue) => ({ + path: issue.path.join("."), + code: issue.code, + message: issue.message, + })); +} + +export function returnAllZodIssues( + error: ZodError, + status: number = 422, + meta?: { + errorCode?: string; + headers?: Record; + } & Record, +): NextResponse { + const { headers, ...rest } = meta ?? {}; + const metaKeys = Object.keys(rest); + return NextResponse.json( + { + data: null, + error: "Validation failed", + details: { + issues: sanitiseZodIssues(error.issues), + }, + ...(metaKeys.length > 0 ? { meta: rest } : {}), + }, + { + status, + ...(headers ? { headers } : {}), + }, + ); +} + /** * `meta` is additive — clients that ignore it see the unchanged * `{ data: null, error: }` envelope. New callers can pass