diff --git a/docs/api/overview.md b/docs/api/overview.md index 416baae3370..ea66c673954 100644 --- a/docs/api/overview.md +++ b/docs/api/overview.md @@ -45,7 +45,7 @@ All responses return JSON. Successful responses return the entity directly. Erro | Code | Meaning | What to Do | |------|---------|------------| -| `400` | Validation error | Check request body against expected fields | +| `400` | Malformed JSON or validation error | Check JSON syntax and request fields | | `401` | Unauthenticated | API key missing or invalid | | `403` | Unauthorized | You don't have permission for this action | | `404` | Not found | Entity doesn't exist or isn't in your company | @@ -53,6 +53,8 @@ All responses return JSON. Successful responses return the entity directly. Erro | `422` | Semantic violation | Invalid state transition (e.g. backlog -> done) | | `500` | Server error | Transient failure. Comment on the task and move on. | +Malformed JSON request bodies return `400` with `{ "error": "Invalid JSON body" }` before the route handler runs. The response does not include request contents or parser details. Correct the JSON before retrying. + ## Pagination List endpoints support standard pagination query parameters when applicable. Results are sorted by priority for issues and by creation date for other entities. diff --git a/server/src/__tests__/json-parse-error-handler.test.ts b/server/src/__tests__/json-parse-error-handler.test.ts new file mode 100644 index 00000000000..83a59dd675a --- /dev/null +++ b/server/src/__tests__/json-parse-error-handler.test.ts @@ -0,0 +1,107 @@ +import express from "express"; +import request from "supertest"; +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { HttpError } from "../errors.js"; +import { errorHandler } from "../middleware/error-handler.js"; + +const sinks = vi.hoisted(() => ({ + captureException: vi.fn(), + trackErrorHandlerCrash: vi.fn(), + telemetryClient: {}, +})); +vi.mock("../sentry.js", () => ({ captureException: sinks.captureException })); +vi.mock("../telemetry.js", () => ({ getTelemetryClient: () => sinks.telemetryClient })); +vi.mock("@paperclipai/shared/telemetry", () => ({ trackErrorHandlerCrash: sinks.trackErrorHandlerCrash })); + +function createApp(routeError?: Error) { + const app = express(); + app.use(express.json()); + const handler = vi.fn((req: express.Request, res: express.Response, next: express.NextFunction) => { + if (routeError) return next(routeError); + res.status(200).json({ received: req.body }); + }); + app.post("/api/echo", handler); + app.patch("/api/echo", handler); + const errorResponses: Array = []; + app.use((err: unknown, req: express.Request, res: express.Response, next: express.NextFunction) => { + errorResponses.push(res); + errorHandler(err, req, res, next); + }); + return { app, handler, errorResponses }; +} + +describe("JSON parse error handler", () => { + beforeEach(() => vi.clearAllMocks()); + + it.each([ + ["truncated object", '{"body": "oops"'], + ["invalid syntax", "private-request-canary is not json"], + ["trailing garbage", '{"body": "ok"} trailing'], + ["strict scalar", '"private-request-canary"'], + ["credential-shaped body", '{"token":"private-request-canary","broken":'], + ])("returns a safe 400 for %s without reporting a crash", async (_label, body) => { + const { app, handler, errorResponses } = createApp(); + for (const method of ["post", "patch"] as const) { + const response = await request(app)[method]("/api/echo") + .set("Content-Type", "application/json") + .send(body); + expect(response.status).toBe(400); + expect(response.body).toEqual({ error: "Invalid JSON body" }); + } + expect(handler).not.toHaveBeenCalled(); + expect(sinks.captureException).not.toHaveBeenCalled(); + expect(sinks.trackErrorHandlerCrash).not.toHaveBeenCalled(); + expect(errorResponses).toHaveLength(2); + for (const response of errorResponses) { + expect(response.err).toBeUndefined(); + expect(response.__errorContext).toBeUndefined(); + } + }); + + it.each([ + { label: "object", body: { body: "valid comment" } }, + { label: "array", body: [{ body: "valid item" }] }, + ])( + "passes a valid JSON $label through to the route handler", async ({ body }) => { + const { app, handler } = createApp(); + const response = await request(app).post("/api/echo").send(body); + expect(response.status).toBe(200); + expect(response.body.received).toEqual(body); + expect(handler).toHaveBeenCalledOnce(); + expect(sinks.captureException).not.toHaveBeenCalled(); + }, + ); + + it.each([ + ["application JSON parse error", new SyntaxError("Stored JSON is invalid")], + ["other 400 syntax error", Object.assign(new SyntaxError("Stored JSON is invalid"), { + status: 400, type: "application.parse.failed", body: "private-request-canary", + })], + ["wrong parser status", Object.assign(new SyntaxError("Parser failed"), { + status: 500, type: "entity.parse.failed", body: "private-request-canary", + })], + ["non-syntax error", Object.assign(new Error("Parser failed"), { + status: 400, type: "entity.parse.failed", body: "private-request-canary", + })], + ])("still reports %s as a server error", async (_label, error) => { + const { app, handler, errorResponses } = createApp(error as Error); + const response = await request(app).post("/api/echo").send({ body: "valid" }); + expect(response.status).toBe(500); + expect(response.body).toEqual({ error: "Internal server error" }); + expect(handler).toHaveBeenCalledOnce(); + expect(sinks.captureException).toHaveBeenCalledExactlyOnceWith(error); + expect(sinks.trackErrorHandlerCrash).toHaveBeenCalledExactlyOnceWith(sinks.telemetryClient, { + errorCode: (error as Error).name, + }); + expect(errorResponses[0].err).toBe(error); + }); + + it("keeps route authorization errors intact for valid JSON", async () => { + const { app } = createApp(new HttpError(403, "Access denied")); + const response = await request(app).post("/api/echo").send({ body: "valid" }); + expect(response.status).toBe(403); + expect(response.body).toEqual({ error: "Access denied" }); + expect(sinks.captureException).not.toHaveBeenCalled(); + expect(sinks.trackErrorHandlerCrash).not.toHaveBeenCalled(); + }); +}); diff --git a/server/src/middleware/error-handler.ts b/server/src/middleware/error-handler.ts index c82a9211b44..31dd8535e62 100644 --- a/server/src/middleware/error-handler.ts +++ b/server/src/middleware/error-handler.ts @@ -236,6 +236,18 @@ export function errorHandler( return; } + // Only body-parser's malformed-JSON errors are client input failures. + // Parser messages can quote request bytes; return a constant response and + // keep the raw error out of crash reporting and HTTP error context. + if ( + err instanceof SyntaxError && + "status" in err && err.status === 400 && + "type" in err && err.type === "entity.parse.failed" + ) { + res.status(400).json({ error: "Invalid JSON body" }); + return; + } + const rootError = err instanceof Error ? err : new Error(String(err)); // The client tore down the connection mid-request (closed tab, dropped