@zuplo/errors 7.12.5 → 7.12.6

package/dist/errors.d.ts

@@ -2,6 +2,14 @@ import { ProblemDetails, ProblemDetailsFactory } from "./interfaces.js";
 import * as Problems from "./problems.js";
 export type { ProblemDetails, ProblemDetailsFactory };
 export { Problems };
+/**
+ * Every problem `type` an {@link ApiError} accepts must be a URI under this
+ * prefix. Exported so callers that validate an untrusted problem body before
+ * constructing an `ApiError` test the same rule the constructor enforces —
+ * checking a divergent prefix turns a rejected `type` into a thrown plain
+ * `Error` instead of the upstream problem.
+ */
+export declare const PROBLEM_TYPE_PREFIX = "https://zup.fail/";
 /**
  * The default format for Api errors
  */

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAE1C,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,CAAC;AACpB;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAE3B,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,YAAY;CAiB5D;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;gBAChC,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,UAAU,CAAM;CAOtE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAYpE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAE1C,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,CAAC;AAEpB;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AAEvD;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAE3B,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,YAAY;CAiB5D;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;gBAChC,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,UAAU,CAAM;CAOtE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAYpE"}

package/dist/errors.js

@@ -1,5 +1,13 @@
 import * as Problems from "./problems.js";
 export { Problems };
+/**
+ * Every problem `type` an {@link ApiError} accepts must be a URI under this
+ * prefix. Exported so callers that validate an untrusted problem body before
+ * constructing an `ApiError` test the same rule the constructor enforces —
+ * checking a divergent prefix turns a rejected `type` into a thrown plain
+ * `Error` instead of the upstream problem.
+ */
+export const PROBLEM_TYPE_PREFIX = "https://zup.fail/";
 /**
  * The default format for Api errors
  */
@@ -11,8 +19,8 @@ export class ApiError extends Error {
     extra;
     constructor(problem, options) {
         super(problem.title, options);
-        if (!problem.type.startsWith("https://zup.fail/")) {
-            throw new Error(`Invalid 'type' specified on ApiError, must be a URI starting with 'https://zup.fail/'. Type was set to ${problem.type}`);
+        if (!problem.type.startsWith(PROBLEM_TYPE_PREFIX)) {
+            throw new Error(`Invalid 'type' specified on ApiError, must be a URI starting with '${PROBLEM_TYPE_PREFIX}'. Type was set to ${problem.type}`);
         }
         const { type, status, detail, instance, ...extra } = problem;
         this.name = "ApiProblemError";

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAG1C,OAAO,EAAE,QAAQ,EAAE,CAAC;AACpB;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAC1B,IAAI,CAAS;IACb,MAAM,CAAS;IACf,MAAM,CAAU;IAChB,QAAQ,CAAU;IAClB,KAAK,CAA2B;IAEvC,YAAY,OAAuB,EAAE,OAAsB;QACzD,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAE9B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CACb,0GAA0G,OAAO,CAAC,IAAI,EAAE,CACzH,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IAC5C,YAAY,UAAuD,EAAE;QACnE,KAAK,CAAC;YACJ,GAAG,OAAO;YACV,GAAG,QAAQ,CAAC,SAAS;SACtB,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,OAAO,CACL,GAAG,KAAK,SAAS;QACjB,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,KAAK,QAAQ;QACvB,MAAM,IAAI,GAAG;QACb,OAAO,IAAI,GAAG;QACd,QAAQ,IAAI,GAAG;QACf,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;QAC5B,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;QAC7B,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAC/B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAG1C,OAAO,EAAE,QAAQ,EAAE,CAAC;AAEpB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;AAEvD;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAC1B,IAAI,CAAS;IACb,MAAM,CAAS;IACf,MAAM,CAAU;IAChB,QAAQ,CAAU;IAClB,KAAK,CAA2B;IAEvC,YAAY,OAAuB,EAAE,OAAsB;QACzD,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAE9B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CACb,sEAAsE,mBAAmB,sBAAsB,OAAO,CAAC,IAAI,EAAE,CAC9H,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IAC5C,YAAY,UAAuD,EAAE;QACnE,KAAK,CAAC;YACJ,GAAG,OAAO;YACV,GAAG,QAAQ,CAAC,SAAS;SACtB,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,OAAO,CACL,GAAG,KAAK,SAAS;QACjB,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,KAAK,QAAQ;QACvB,MAAM,IAAI,GAAG;QACb,OAAO,IAAI,GAAG;QACd,QAAQ,IAAI,GAAG;QACf,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;QAC5B,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;QAC7B,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAC/B,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./errors.js";
 export type { HttpStatusCodeRangeDefinition } from "./http-status.js";
 export { HttpStatusCode } from "./http-status.js";
+export * from "./problem-parsing.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from "./errors.js";
 export { HttpStatusCode } from "./http-status.js";
+export * from "./problem-parsing.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,cAAc,sBAAsB,CAAC"}

package/dist/problem-parsing.d.ts

@@ -0,0 +1,77 @@
+import { ProblemDetails } from "./interfaces.js";
+/**
+ * Whether an untrusted value can be rethrown as an {@link ApiError} that
+ * faithfully represents the upstream failure.
+ *
+ * Every internal service client in this repo gets a non-2xx response from
+ * another Zuplo service and wants to rethrow its problem+json rather than
+ * flatten it into a generic 500. The naive form of that check —
+ * `if (body.type && body.status && body.title)` — is wrong in four ways, and
+ * each one turned a diagnosable upstream failure into an opaque one:
+ *
+ * - **Not an object.** `null` is valid JSON, and reading `.type` off it throws
+ *   a `TypeError` out of the client. An array passes a `typeof === "object"`
+ *   guard and then fails later.
+ * - **Wrong member types.** A `status` of `"400"` is truthy, so it reached
+ *   `ApiError` as a string.
+ * - **A `type` outside {@link PROBLEM_TYPE_PREFIX}.** `ApiError`'s constructor
+ *   rejects those, so passing one through throws a plain `Error` about the
+ *   type instead of surfacing the problem. RFC 7807's default `about:blank`
+ *   lands here.
+ * - **A `status` that disagrees with the response, or that is not an error
+ *   status at all.** This is the dangerous one. `handleError` copies
+ *   `ApiError.status` straight into `reply.status(...)` (`@zuplo/server`'s
+ *   `fastify/error-handler.ts`), so the body dictates the response status.
+ *   Two guards are needed, not one:
+ *   - It must equal `httpStatus`. Otherwise a body claiming `200` serves an
+ *     upstream failure as a success. RFC 7807 says `status` SHOULD match the
+ *     response, so equality costs nothing on a conforming body.
+ *   - It must be a 4xx or 5xx. Equality alone is not enough, because callers
+ *     do not all gate on `>= 400`: `ApiKeyService` treats every
+ *     `status >= 300` as a failure and `Response.ok` is false for 3xx too. A
+ *     `301` response carrying a body that also says `301` would satisfy
+ *     equality and turn into `reply.status(301)` — an upstream-dictated
+ *     redirect emitted from an error path.
+ * - **Non-string `detail` or `instance`.** Both are declared `string`, and
+ *   `handleError` copies them into the response body while
+ *   `request.audit.setError` puts `detail` into the audit event. Left
+ *   unchecked, an object or array from an untrusted body reaches both while
+ *   the types claim it is a string.
+ *
+ * `httpStatus` is the status the upstream service actually responded with.
+ *
+ * Extra members are preserved: RFC 7807 allows them and callers pass them
+ * through to `ApiError.extra`.
+ */
+export declare function isRethrowableProblem(value: unknown, httpStatus: number): value is ProblemDetails;
+/**
+ * Parses an upstream error body and returns its problem detail, or `undefined`
+ * when the body is not one {@link isRethrowableProblem} accepts.
+ *
+ * Takes the body as text rather than a parsed value because a failing internal
+ * service is not guaranteed to answer with JSON at all: an HTML error page
+ * from a load balancer, or an empty body on a Cloud Run cold-start timeout,
+ * makes `Response.json()` throw a `SyntaxError` that escapes the caller as an
+ * opaque 500 — and skips the log that would have recorded what the upstream
+ * actually returned. Read `res.text()` and hand it here instead.
+ *
+ * Callers that already hold a parsed body (an SDK that deserializes for them)
+ * should use {@link isRethrowableProblem} directly rather than re-serializing.
+ */
+export declare function parseProblemDetails(rawBody: string, httpStatus: number): ProblemDetails | undefined;
+/**
+ * Caps how much of an unparsed upstream error body reaches the logs. A proxy
+ * error page is measured in kilobytes and the first few lines are enough to
+ * tell an HTML 502 from a truncated JSON payload.
+ */
+export declare const MAX_LOGGED_PROBLEM_BODY_LENGTH = 512;
+/**
+ * Trims an upstream error body to {@link MAX_LOGGED_PROBLEM_BODY_LENGTH} for
+ * logging, marking it when anything was dropped.
+ *
+ * Log the body whenever {@link parseProblemDetails} returns `undefined`:
+ * that is the branch where the upstream failure gets flattened into a generic
+ * 500, so the body is the only remaining evidence of what actually happened.
+ */
+export declare function truncateProblemBody(body: string): string;
+//# sourceMappingURL=problem-parsing.d.ts.map

package/dist/problem-parsing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"problem-parsing.d.ts","sourceRoot":"","sources":["../src/problem-parsing.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,MAAM,GACjB,KAAK,IAAI,cAAc,CAezB;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,cAAc,GAAG,SAAS,CAS5B;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIxD"}

package/dist/problem-parsing.js

@@ -0,0 +1,113 @@
+import { PROBLEM_TYPE_PREFIX } from "./errors.js";
+/**
+ * Whether an untrusted value can be rethrown as an {@link ApiError} that
+ * faithfully represents the upstream failure.
+ *
+ * Every internal service client in this repo gets a non-2xx response from
+ * another Zuplo service and wants to rethrow its problem+json rather than
+ * flatten it into a generic 500. The naive form of that check —
+ * `if (body.type && body.status && body.title)` — is wrong in four ways, and
+ * each one turned a diagnosable upstream failure into an opaque one:
+ *
+ * - **Not an object.** `null` is valid JSON, and reading `.type` off it throws
+ *   a `TypeError` out of the client. An array passes a `typeof === "object"`
+ *   guard and then fails later.
+ * - **Wrong member types.** A `status` of `"400"` is truthy, so it reached
+ *   `ApiError` as a string.
+ * - **A `type` outside {@link PROBLEM_TYPE_PREFIX}.** `ApiError`'s constructor
+ *   rejects those, so passing one through throws a plain `Error` about the
+ *   type instead of surfacing the problem. RFC 7807's default `about:blank`
+ *   lands here.
+ * - **A `status` that disagrees with the response, or that is not an error
+ *   status at all.** This is the dangerous one. `handleError` copies
+ *   `ApiError.status` straight into `reply.status(...)` (`@zuplo/server`'s
+ *   `fastify/error-handler.ts`), so the body dictates the response status.
+ *   Two guards are needed, not one:
+ *   - It must equal `httpStatus`. Otherwise a body claiming `200` serves an
+ *     upstream failure as a success. RFC 7807 says `status` SHOULD match the
+ *     response, so equality costs nothing on a conforming body.
+ *   - It must be a 4xx or 5xx. Equality alone is not enough, because callers
+ *     do not all gate on `>= 400`: `ApiKeyService` treats every
+ *     `status >= 300` as a failure and `Response.ok` is false for 3xx too. A
+ *     `301` response carrying a body that also says `301` would satisfy
+ *     equality and turn into `reply.status(301)` — an upstream-dictated
+ *     redirect emitted from an error path.
+ * - **Non-string `detail` or `instance`.** Both are declared `string`, and
+ *   `handleError` copies them into the response body while
+ *   `request.audit.setError` puts `detail` into the audit event. Left
+ *   unchecked, an object or array from an untrusted body reaches both while
+ *   the types claim it is a string.
+ *
+ * `httpStatus` is the status the upstream service actually responded with.
+ *
+ * Extra members are preserved: RFC 7807 allows them and callers pass them
+ * through to `ApiError.extra`.
+ */
+export function isRethrowableProblem(value, httpStatus) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const problem = value;
+    return (typeof problem.type === "string" &&
+        typeof problem.title === "string" &&
+        isErrorStatus(problem.status) &&
+        problem.status === httpStatus &&
+        problem.type.startsWith(PROBLEM_TYPE_PREFIX) &&
+        isAbsentOrString(problem.detail) &&
+        isAbsentOrString(problem.instance));
+}
+/** Whether a value is an integer HTTP status in the 4xx or 5xx range. */
+function isErrorStatus(value) {
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        value >= 400 &&
+        value <= 599);
+}
+/** Whether an optional problem member is either absent or a string. */
+function isAbsentOrString(value) {
+    return value === undefined || typeof value === "string";
+}
+/**
+ * Parses an upstream error body and returns its problem detail, or `undefined`
+ * when the body is not one {@link isRethrowableProblem} accepts.
+ *
+ * Takes the body as text rather than a parsed value because a failing internal
+ * service is not guaranteed to answer with JSON at all: an HTML error page
+ * from a load balancer, or an empty body on a Cloud Run cold-start timeout,
+ * makes `Response.json()` throw a `SyntaxError` that escapes the caller as an
+ * opaque 500 — and skips the log that would have recorded what the upstream
+ * actually returned. Read `res.text()` and hand it here instead.
+ *
+ * Callers that already hold a parsed body (an SDK that deserializes for them)
+ * should use {@link isRethrowableProblem} directly rather than re-serializing.
+ */
+export function parseProblemDetails(rawBody, httpStatus) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawBody);
+    }
+    catch {
+        return undefined;
+    }
+    return isRethrowableProblem(parsed, httpStatus) ? parsed : undefined;
+}
+/**
+ * Caps how much of an unparsed upstream error body reaches the logs. A proxy
+ * error page is measured in kilobytes and the first few lines are enough to
+ * tell an HTML 502 from a truncated JSON payload.
+ */
+export const MAX_LOGGED_PROBLEM_BODY_LENGTH = 512;
+/**
+ * Trims an upstream error body to {@link MAX_LOGGED_PROBLEM_BODY_LENGTH} for
+ * logging, marking it when anything was dropped.
+ *
+ * Log the body whenever {@link parseProblemDetails} returns `undefined`:
+ * that is the branch where the upstream failure gets flattened into a generic
+ * 500, so the body is the only remaining evidence of what actually happened.
+ */
+export function truncateProblemBody(body) {
+    return body.length > MAX_LOGGED_PROBLEM_BODY_LENGTH
+        ? `${body.slice(0, MAX_LOGGED_PROBLEM_BODY_LENGTH)}...[truncated]`
+        : body;
+}
+//# sourceMappingURL=problem-parsing.js.map

package/dist/problem-parsing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"problem-parsing.js","sourceRoot":"","sources":["../src/problem-parsing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAc,EACd,UAAkB;IAElB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,KAAgC,CAAC;IACjD,OAAO,CACL,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;QAChC,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ;QACjC,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC;QAC7B,OAAO,CAAC,MAAM,KAAK,UAAU;QAC7B,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC;QAC5C,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC;QAChC,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,CACnC,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;QACvB,KAAK,IAAI,GAAG;QACZ,KAAK,IAAI,GAAG,CACb,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,UAAkB;IAElB,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,oBAAoB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,GAAG,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,IAAI,CAAC,MAAM,GAAG,8BAA8B;QACjD,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,8BAA8B,CAAC,gBAAgB;QAClE,CAAC,CAAC,IAAI,CAAC;AACX,CAAC"}

package/dist/problem-parsing.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=problem-parsing.spec.d.ts.map

package/dist/problem-parsing.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"problem-parsing.spec.d.ts","sourceRoot":"","sources":["../src/problem-parsing.spec.ts"],"names":[],"mappings":""}

package/dist/problem-parsing.spec.js

@@ -0,0 +1,152 @@
+import { assert } from "chai";
+import { ApiError, PROBLEM_TYPE_PREFIX } from "./errors.js";
+import { isRethrowableProblem, parseProblemDetails, } from "./problem-parsing.js";
+const problem = {
+    type: `${PROBLEM_TYPE_PREFIX}auth/client-not-found`,
+    title: "Client not found",
+    status: 400,
+    detail: "No client matches that id",
+};
+describe("isRethrowableProblem", function () {
+    it("accepts a problem whose type and status line up", function () {
+        assert.isTrue(isRethrowableProblem(problem, 400));
+    });
+    it("rejects values that are not objects", function () {
+        // `null` parses out of valid JSON, and reading `.type` off it used to
+        // throw a TypeError out of the calling service client.
+        for (const value of [null, undefined, "a string", 42, true]) {
+            assert.isFalse(isRethrowableProblem(value, 400));
+        }
+    });
+    it("rejects an array", function () {
+        // Arrays are objects, so a null/typeof guard alone lets them through.
+        assert.isFalse(isRethrowableProblem([], 400));
+        assert.isFalse(isRethrowableProblem([problem], 400));
+    });
+    it("rejects a missing member", function () {
+        for (const member of ["type", "title", "status"]) {
+            const { [member]: _dropped, ...without } = problem;
+            assert.isFalse(isRethrowableProblem(without, 400), `expected a problem without '${member}' to be rejected`);
+        }
+    });
+    it("rejects members of the wrong type", function () {
+        assert.isFalse(isRethrowableProblem({ ...problem, status: "400" }, 400));
+        assert.isFalse(isRethrowableProblem({ ...problem, type: 1 }, 400));
+        assert.isFalse(isRethrowableProblem({ ...problem, title: null }, 400));
+    });
+    it("rejects a type outside the zup.fail prefix", function () {
+        // RFC 7807's default. `ApiError` rejects it, so rethrowing would throw a
+        // plain Error about the type rather than surfacing the upstream problem.
+        assert.isFalse(isRethrowableProblem({ ...problem, type: "about:blank" }, 400));
+        assert.isFalse(isRethrowableProblem({ ...problem, type: "https://example.com/errors/oops" }, 400));
+    });
+    describe("the status must match the response", function () {
+        // `ApiError.status` is echoed into `reply.status(...)`, so an unchecked
+        // body status is a response-status injection.
+        it("rejects a body claiming success on a failed response", function () {
+            assert.isFalse(isRethrowableProblem({ ...problem, status: 200 }, 500));
+            assert.isFalse(isRethrowableProblem({ ...problem, status: 204 }, 500));
+        });
+        it("rejects a body claiming zero", function () {
+            assert.isFalse(isRethrowableProblem({ ...problem, status: 0 }, 500));
+        });
+        it("rejects a body claiming a redirect", function () {
+            assert.isFalse(isRethrowableProblem({ ...problem, status: 301 }, 500));
+        });
+        it("rejects a body that merely disagrees", function () {
+            assert.isFalse(isRethrowableProblem({ ...problem, status: 403 }, 400));
+        });
+        it("accepts a matching 5xx", function () {
+            const upstream = { ...problem, status: 503 };
+            assert.isTrue(isRethrowableProblem(upstream, 503));
+        });
+        it("rejects a redirect even when the response agrees", function () {
+            // Equality alone is not enough. `ApiKeyService` treats every
+            // `status >= 300` as a failure and `Response.ok` is false for 3xx, so a
+            // 301 body on a 301 response would otherwise become `reply.status(301)`
+            // — an upstream-dictated redirect emitted from an error path.
+            for (const status of [301, 302, 304, 307, 308]) {
+                assert.isFalse(isRethrowableProblem({ ...problem, status }, status), `expected a matching ${status} to be rejected`);
+            }
+        });
+        it("rejects a matching 2xx", function () {
+            assert.isFalse(isRethrowableProblem({ ...problem, status: 200 }, 200));
+        });
+        it("rejects a status outside the HTTP range", function () {
+            for (const status of [399, 600, -400, 4000]) {
+                assert.isFalse(isRethrowableProblem({ ...problem, status }, status));
+            }
+        });
+        it("rejects a non-integer status", function () {
+            for (const status of [404.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+                assert.isFalse(isRethrowableProblem({ ...problem, status }, status));
+            }
+        });
+        it("accepts the 4xx and 5xx boundaries", function () {
+            for (const status of [400, 499, 500, 599]) {
+                assert.isTrue(isRethrowableProblem({ ...problem, status }, status), `expected a matching ${status} to be accepted`);
+            }
+        });
+    });
+    describe("optional standard members", function () {
+        // `handleError` copies `detail` and `instance` into the response body,
+        // and `request.audit.setError` puts `detail` into the audit event. Both
+        // are declared `string`, so a non-string reaches those while the types
+        // claim otherwise.
+        it("rejects a non-string detail", function () {
+            for (const detail of [{ nested: true }, ["a"], 42, null]) {
+                assert.isFalse(isRethrowableProblem({ ...problem, detail }, 400));
+            }
+        });
+        it("rejects a non-string instance", function () {
+            for (const instance of [{ nested: true }, ["a"], 42, null]) {
+                assert.isFalse(isRethrowableProblem({ ...problem, instance }, 400));
+            }
+        });
+        it("accepts them when absent", function () {
+            const { detail: _detail, ...withoutDetail } = problem;
+            assert.isTrue(isRethrowableProblem(withoutDetail, 400));
+        });
+        it("accepts a string instance", function () {
+            assert.isTrue(isRethrowableProblem({ ...problem, instance: "/clients/abc" }, 400));
+        });
+        it("still allows non-string extra members", function () {
+            // Only the standard members are typed. RFC 7807 extensions are free-form
+            // and callers pass them through to `ApiError.extra`.
+            assert.isTrue(isRethrowableProblem({ ...problem, errors: [{ field: "id" }] }, 400));
+        });
+    });
+    it("accepts everything the ApiError constructor accepts", function () {
+        // Guards against this check drifting from the constructor's own rule.
+        assert.isTrue(isRethrowableProblem(problem, 400));
+        assert.doesNotThrow(() => new ApiError(problem));
+    });
+});
+describe("parseProblemDetails", function () {
+    it("returns the problem from a conforming body", function () {
+        assert.deepEqual(parseProblemDetails(JSON.stringify(problem), 400), problem);
+    });
+    it("preserves extra members", function () {
+        // RFC 7807 allows them and callers pass them to ApiError.extra.
+        const withExtra = { ...problem, clientId: "abc123" };
+        assert.deepEqual(parseProblemDetails(JSON.stringify(withExtra), 400), withExtra);
+    });
+    it("returns undefined for an HTML error page", function () {
+        // What a load balancer or ingress returns on a 502.
+        assert.isUndefined(parseProblemDetails("<html><head><title>502 Bad Gateway</title></head></html>", 502));
+    });
+    it("returns undefined for an empty body", function () {
+        // What a Cloud Run cold-start timeout leaves behind.
+        assert.isUndefined(parseProblemDetails("", 504));
+    });
+    it("returns undefined for truncated JSON", function () {
+        assert.isUndefined(parseProblemDetails('{"type":"https://zup.fail/a"', 500));
+    });
+    it("returns undefined for a JSON null body", function () {
+        assert.isUndefined(parseProblemDetails("null", 500));
+    });
+    it("returns undefined for a body the guard rejects", function () {
+        assert.isUndefined(parseProblemDetails(JSON.stringify({ ...problem, status: 200 }), 500));
+    });
+});
+//# sourceMappingURL=problem-parsing.spec.js.map

package/dist/problem-parsing.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"problem-parsing.spec.js","sourceRoot":"","sources":["../src/problem-parsing.spec.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@zuplo/errors",
   "type": "module",
   "sideEffects": false,
-  "version": "7.12.5",
+  "version": "7.12.6",
   "description": "Error types",
   "repository": {
     "type": "git",
@@ -21,7 +21,8 @@
   "author": "Zuplo",
   "license": "SEE LICENSE IN LICENSE.txt",
   "scripts": {
-    "build": "tsc --build"
+    "build": "tsc --build",
+    "test": "mocha"
   },
   "devDependencies": {
     "@types/chai": "^5.0.0",

package/src/errors.ts

@@ -3,6 +3,16 @@ import * as Problems from "./problems.js";
 
 export type { ProblemDetails, ProblemDetailsFactory };
 export { Problems };
+
+/**
+ * Every problem `type` an {@link ApiError} accepts must be a URI under this
+ * prefix. Exported so callers that validate an untrusted problem body before
+ * constructing an `ApiError` test the same rule the constructor enforces —
+ * checking a divergent prefix turns a rejected `type` into a thrown plain
+ * `Error` instead of the upstream problem.
+ */
+export const PROBLEM_TYPE_PREFIX = "https://zup.fail/";
+
 /**
  * The default format for Api errors
  */
@@ -16,9 +26,9 @@ export class ApiError extends Error {
   constructor(problem: ProblemDetails, options?: ErrorOptions) {
     super(problem.title, options);
 
-    if (!problem.type.startsWith("https://zup.fail/")) {
+    if (!problem.type.startsWith(PROBLEM_TYPE_PREFIX)) {
       throw new Error(
-        `Invalid 'type' specified on ApiError, must be a URI starting with 'https://zup.fail/'. Type was set to ${problem.type}`
+        `Invalid 'type' specified on ApiError, must be a URI starting with '${PROBLEM_TYPE_PREFIX}'. Type was set to ${problem.type}`
       );
     }
 

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from "./errors.js";
 export type { HttpStatusCodeRangeDefinition } from "./http-status.js";
 export { HttpStatusCode } from "./http-status.js";
+export * from "./problem-parsing.js";

package/src/problem-parsing.spec.ts

@@ -0,0 +1,220 @@
+import { assert } from "chai";
+import { ApiError, PROBLEM_TYPE_PREFIX } from "./errors.js";
+import {
+  isRethrowableProblem,
+  parseProblemDetails,
+} from "./problem-parsing.js";
+
+const problem = {
+  type: `${PROBLEM_TYPE_PREFIX}auth/client-not-found`,
+  title: "Client not found",
+  status: 400,
+  detail: "No client matches that id",
+};
+
+describe("isRethrowableProblem", function () {
+  it("accepts a problem whose type and status line up", function () {
+    assert.isTrue(isRethrowableProblem(problem, 400));
+  });
+
+  it("rejects values that are not objects", function () {
+    // `null` parses out of valid JSON, and reading `.type` off it used to
+    // throw a TypeError out of the calling service client.
+    for (const value of [null, undefined, "a string", 42, true]) {
+      assert.isFalse(isRethrowableProblem(value, 400));
+    }
+  });
+
+  it("rejects an array", function () {
+    // Arrays are objects, so a null/typeof guard alone lets them through.
+    assert.isFalse(isRethrowableProblem([], 400));
+    assert.isFalse(isRethrowableProblem([problem], 400));
+  });
+
+  it("rejects a missing member", function () {
+    for (const member of ["type", "title", "status"] as const) {
+      const { [member]: _dropped, ...without } = problem;
+      assert.isFalse(
+        isRethrowableProblem(without, 400),
+        `expected a problem without '${member}' to be rejected`
+      );
+    }
+  });
+
+  it("rejects members of the wrong type", function () {
+    assert.isFalse(isRethrowableProblem({ ...problem, status: "400" }, 400));
+    assert.isFalse(isRethrowableProblem({ ...problem, type: 1 }, 400));
+    assert.isFalse(isRethrowableProblem({ ...problem, title: null }, 400));
+  });
+
+  it("rejects a type outside the zup.fail prefix", function () {
+    // RFC 7807's default. `ApiError` rejects it, so rethrowing would throw a
+    // plain Error about the type rather than surfacing the upstream problem.
+    assert.isFalse(
+      isRethrowableProblem({ ...problem, type: "about:blank" }, 400)
+    );
+    assert.isFalse(
+      isRethrowableProblem(
+        { ...problem, type: "https://example.com/errors/oops" },
+        400
+      )
+    );
+  });
+
+  describe("the status must match the response", function () {
+    // `ApiError.status` is echoed into `reply.status(...)`, so an unchecked
+    // body status is a response-status injection.
+    it("rejects a body claiming success on a failed response", function () {
+      assert.isFalse(isRethrowableProblem({ ...problem, status: 200 }, 500));
+      assert.isFalse(isRethrowableProblem({ ...problem, status: 204 }, 500));
+    });
+
+    it("rejects a body claiming zero", function () {
+      assert.isFalse(isRethrowableProblem({ ...problem, status: 0 }, 500));
+    });
+
+    it("rejects a body claiming a redirect", function () {
+      assert.isFalse(isRethrowableProblem({ ...problem, status: 301 }, 500));
+    });
+
+    it("rejects a body that merely disagrees", function () {
+      assert.isFalse(isRethrowableProblem({ ...problem, status: 403 }, 400));
+    });
+
+    it("accepts a matching 5xx", function () {
+      const upstream = { ...problem, status: 503 };
+      assert.isTrue(isRethrowableProblem(upstream, 503));
+    });
+
+    it("rejects a redirect even when the response agrees", function () {
+      // Equality alone is not enough. `ApiKeyService` treats every
+      // `status >= 300` as a failure and `Response.ok` is false for 3xx, so a
+      // 301 body on a 301 response would otherwise become `reply.status(301)`
+      // — an upstream-dictated redirect emitted from an error path.
+      for (const status of [301, 302, 304, 307, 308]) {
+        assert.isFalse(
+          isRethrowableProblem({ ...problem, status }, status),
+          `expected a matching ${status} to be rejected`
+        );
+      }
+    });
+
+    it("rejects a matching 2xx", function () {
+      assert.isFalse(isRethrowableProblem({ ...problem, status: 200 }, 200));
+    });
+
+    it("rejects a status outside the HTTP range", function () {
+      for (const status of [399, 600, -400, 4000]) {
+        assert.isFalse(isRethrowableProblem({ ...problem, status }, status));
+      }
+    });
+
+    it("rejects a non-integer status", function () {
+      for (const status of [404.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+        assert.isFalse(isRethrowableProblem({ ...problem, status }, status));
+      }
+    });
+
+    it("accepts the 4xx and 5xx boundaries", function () {
+      for (const status of [400, 499, 500, 599]) {
+        assert.isTrue(
+          isRethrowableProblem({ ...problem, status }, status),
+          `expected a matching ${status} to be accepted`
+        );
+      }
+    });
+  });
+
+  describe("optional standard members", function () {
+    // `handleError` copies `detail` and `instance` into the response body,
+    // and `request.audit.setError` puts `detail` into the audit event. Both
+    // are declared `string`, so a non-string reaches those while the types
+    // claim otherwise.
+    it("rejects a non-string detail", function () {
+      for (const detail of [{ nested: true }, ["a"], 42, null]) {
+        assert.isFalse(isRethrowableProblem({ ...problem, detail }, 400));
+      }
+    });
+
+    it("rejects a non-string instance", function () {
+      for (const instance of [{ nested: true }, ["a"], 42, null]) {
+        assert.isFalse(isRethrowableProblem({ ...problem, instance }, 400));
+      }
+    });
+
+    it("accepts them when absent", function () {
+      const { detail: _detail, ...withoutDetail } = problem;
+      assert.isTrue(isRethrowableProblem(withoutDetail, 400));
+    });
+
+    it("accepts a string instance", function () {
+      assert.isTrue(
+        isRethrowableProblem({ ...problem, instance: "/clients/abc" }, 400)
+      );
+    });
+
+    it("still allows non-string extra members", function () {
+      // Only the standard members are typed. RFC 7807 extensions are free-form
+      // and callers pass them through to `ApiError.extra`.
+      assert.isTrue(
+        isRethrowableProblem({ ...problem, errors: [{ field: "id" }] }, 400)
+      );
+    });
+  });
+
+  it("accepts everything the ApiError constructor accepts", function () {
+    // Guards against this check drifting from the constructor's own rule.
+    assert.isTrue(isRethrowableProblem(problem, 400));
+    assert.doesNotThrow(() => new ApiError(problem));
+  });
+});
+
+describe("parseProblemDetails", function () {
+  it("returns the problem from a conforming body", function () {
+    assert.deepEqual(
+      parseProblemDetails(JSON.stringify(problem), 400),
+      problem
+    );
+  });
+
+  it("preserves extra members", function () {
+    // RFC 7807 allows them and callers pass them to ApiError.extra.
+    const withExtra = { ...problem, clientId: "abc123" };
+
+    assert.deepEqual(
+      parseProblemDetails(JSON.stringify(withExtra), 400),
+      withExtra
+    );
+  });
+
+  it("returns undefined for an HTML error page", function () {
+    // What a load balancer or ingress returns on a 502.
+    assert.isUndefined(
+      parseProblemDetails(
+        "<html><head><title>502 Bad Gateway</title></head></html>",
+        502
+      )
+    );
+  });
+
+  it("returns undefined for an empty body", function () {
+    // What a Cloud Run cold-start timeout leaves behind.
+    assert.isUndefined(parseProblemDetails("", 504));
+  });
+
+  it("returns undefined for truncated JSON", function () {
+    assert.isUndefined(
+      parseProblemDetails('{"type":"https://zup.fail/a"', 500)
+    );
+  });
+
+  it("returns undefined for a JSON null body", function () {
+    assert.isUndefined(parseProblemDetails("null", 500));
+  });
+
+  it("returns undefined for a body the guard rejects", function () {
+    assert.isUndefined(
+      parseProblemDetails(JSON.stringify({ ...problem, status: 200 }), 500)
+    );
+  });
+});

package/src/problem-parsing.ts

@@ -0,0 +1,130 @@
+import { PROBLEM_TYPE_PREFIX } from "./errors.js";
+import { ProblemDetails } from "./interfaces.js";
+
+/**
+ * Whether an untrusted value can be rethrown as an {@link ApiError} that
+ * faithfully represents the upstream failure.
+ *
+ * Every internal service client in this repo gets a non-2xx response from
+ * another Zuplo service and wants to rethrow its problem+json rather than
+ * flatten it into a generic 500. The naive form of that check —
+ * `if (body.type && body.status && body.title)` — is wrong in four ways, and
+ * each one turned a diagnosable upstream failure into an opaque one:
+ *
+ * - **Not an object.** `null` is valid JSON, and reading `.type` off it throws
+ *   a `TypeError` out of the client. An array passes a `typeof === "object"`
+ *   guard and then fails later.
+ * - **Wrong member types.** A `status` of `"400"` is truthy, so it reached
+ *   `ApiError` as a string.
+ * - **A `type` outside {@link PROBLEM_TYPE_PREFIX}.** `ApiError`'s constructor
+ *   rejects those, so passing one through throws a plain `Error` about the
+ *   type instead of surfacing the problem. RFC 7807's default `about:blank`
+ *   lands here.
+ * - **A `status` that disagrees with the response, or that is not an error
+ *   status at all.** This is the dangerous one. `handleError` copies
+ *   `ApiError.status` straight into `reply.status(...)` (`@zuplo/server`'s
+ *   `fastify/error-handler.ts`), so the body dictates the response status.
+ *   Two guards are needed, not one:
+ *   - It must equal `httpStatus`. Otherwise a body claiming `200` serves an
+ *     upstream failure as a success. RFC 7807 says `status` SHOULD match the
+ *     response, so equality costs nothing on a conforming body.
+ *   - It must be a 4xx or 5xx. Equality alone is not enough, because callers
+ *     do not all gate on `>= 400`: `ApiKeyService` treats every
+ *     `status >= 300` as a failure and `Response.ok` is false for 3xx too. A
+ *     `301` response carrying a body that also says `301` would satisfy
+ *     equality and turn into `reply.status(301)` — an upstream-dictated
+ *     redirect emitted from an error path.
+ * - **Non-string `detail` or `instance`.** Both are declared `string`, and
+ *   `handleError` copies them into the response body while
+ *   `request.audit.setError` puts `detail` into the audit event. Left
+ *   unchecked, an object or array from an untrusted body reaches both while
+ *   the types claim it is a string.
+ *
+ * `httpStatus` is the status the upstream service actually responded with.
+ *
+ * Extra members are preserved: RFC 7807 allows them and callers pass them
+ * through to `ApiError.extra`.
+ */
+export function isRethrowableProblem(
+  value: unknown,
+  httpStatus: number
+): value is ProblemDetails {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+
+  const problem = value as Partial<ProblemDetails>;
+  return (
+    typeof problem.type === "string" &&
+    typeof problem.title === "string" &&
+    isErrorStatus(problem.status) &&
+    problem.status === httpStatus &&
+    problem.type.startsWith(PROBLEM_TYPE_PREFIX) &&
+    isAbsentOrString(problem.detail) &&
+    isAbsentOrString(problem.instance)
+  );
+}
+
+/** Whether a value is an integer HTTP status in the 4xx or 5xx range. */
+function isErrorStatus(value: unknown): value is number {
+  return (
+    typeof value === "number" &&
+    Number.isInteger(value) &&
+    value >= 400 &&
+    value <= 599
+  );
+}
+
+/** Whether an optional problem member is either absent or a string. */
+function isAbsentOrString(value: unknown): boolean {
+  return value === undefined || typeof value === "string";
+}
+
+/**
+ * Parses an upstream error body and returns its problem detail, or `undefined`
+ * when the body is not one {@link isRethrowableProblem} accepts.
+ *
+ * Takes the body as text rather than a parsed value because a failing internal
+ * service is not guaranteed to answer with JSON at all: an HTML error page
+ * from a load balancer, or an empty body on a Cloud Run cold-start timeout,
+ * makes `Response.json()` throw a `SyntaxError` that escapes the caller as an
+ * opaque 500 — and skips the log that would have recorded what the upstream
+ * actually returned. Read `res.text()` and hand it here instead.
+ *
+ * Callers that already hold a parsed body (an SDK that deserializes for them)
+ * should use {@link isRethrowableProblem} directly rather than re-serializing.
+ */
+export function parseProblemDetails(
+  rawBody: string,
+  httpStatus: number
+): ProblemDetails | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return undefined;
+  }
+
+  return isRethrowableProblem(parsed, httpStatus) ? parsed : undefined;
+}
+
+/**
+ * Caps how much of an unparsed upstream error body reaches the logs. A proxy
+ * error page is measured in kilobytes and the first few lines are enough to
+ * tell an HTML 502 from a truncated JSON payload.
+ */
+export const MAX_LOGGED_PROBLEM_BODY_LENGTH = 512;
+
+/**
+ * Trims an upstream error body to {@link MAX_LOGGED_PROBLEM_BODY_LENGTH} for
+ * logging, marking it when anything was dropped.
+ *
+ * Log the body whenever {@link parseProblemDetails} returns `undefined`:
+ * that is the branch where the upstream failure gets flattened into a generic
+ * 500, so the body is the only remaining evidence of what actually happened.
+ */
+export function truncateProblemBody(body: string): string {
+  return body.length > MAX_LOGGED_PROBLEM_BODY_LENGTH
+    ? `${body.slice(0, MAX_LOGGED_PROBLEM_BODY_LENGTH)}...[truncated]`
+    : body;
+}