From eba19b2077a961fc026f4fdfa6cab71296a6f053 Mon Sep 17 00:00:00 2001 From: Yun Wang Date: Fri, 13 Nov 2026 13:57:20 +0100 Subject: [PATCH] fix: limit decompressed webhook payloads to 10 MiB, configurable with webhookConfig.maxPayloadBytes --- .../integration/webhook-compression.test.ts | 45 ++++++++++++++++++- index.ts | 1 + src/utils/webhook.ts | 26 ++++++++++- 3 files changed, 69 insertions(+), 3 deletions(-) diff --git a/__tests__/integration/webhook-compression.test.ts b/__tests__/integration/webhook-compression.test.ts index f2cce5e0..3981ad6f 100644 --- a/__tests__/integration/webhook-compression.test.ts +++ b/__tests__/integration/webhook-compression.test.ts @@ -1,7 +1,7 @@ import crypto from 'crypto'; import zlib from 'zlib'; -import { beforeEach, describe, expect, it } from 'vitest'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; import { StreamClient } from '../../src/StreamClient'; import { @@ -15,6 +15,7 @@ import { parseSqs, verifyAndParseWebhook, verifySignature, + webhookConfig, } from '../../src/utils/webhook'; const JSON_BODY = @@ -127,6 +128,48 @@ describe('Webhook verification + parsing', () => { InvalidWebhookErrorMessages.gzipFailed, ); }); + + describe('size limit', () => { + const defaultLimit = webhookConfig.maxPayloadBytes; + + afterEach(() => { + webhookConfig.maxPayloadBytes = defaultLimit; + }); + + it('defaults to 10 MiB', () => { + expect(defaultLimit).toBe(10 * 1024 * 1024); + }); + + it('inflates a body of exactly the limit', () => { + expect(gunzipPayload(gzip(Buffer.alloc(defaultLimit))).length).toBe( + defaultLimit, + ); + }); + + it('rejects a gzip bomb before the signature check', () => { + const bomb = gzip(Buffer.alloc(defaultLimit + 1)); + expect(() => + verifyAndParseWebhook(bomb, 'deadbeef', API_SECRET), + ).toThrow( + `${InvalidWebhookErrorMessages.gzipFailed}: payload exceeds ${defaultLimit} bytes`, + ); + expect(() => parseSqs(base64(bomb))).toThrow('payload exceeds'); + }); + + it('honours a custom limit', () => { + webhookConfig.maxPayloadBytes = JSON_BODY.length - 1; + expect(() => gunzipPayload(gzip(JSON_BODY))).toThrow( + InvalidWebhookError, + ); + webhookConfig.maxPayloadBytes = JSON_BODY.length; + expect(gunzipPayload(gzip(JSON_BODY)).toString('utf8')).toBe(JSON_BODY); + }); + + it('does not limit uncompressed bodies', () => { + webhookConfig.maxPayloadBytes = 1; + expect(gunzipPayload(JSON_BODY).toString('utf8')).toBe(JSON_BODY); + }); + }); }); describe('decodeSqsPayload', () => { diff --git a/index.ts b/index.ts index 62427801..d1d1bd1e 100644 --- a/index.ts +++ b/index.ts @@ -10,6 +10,7 @@ export { InvalidWebhookError, InvalidWebhookErrorMessages, verifyAndParseWebhook, + webhookConfig, } from './src/utils/webhook'; export { convertTimestampToDate, diff --git a/src/utils/webhook.ts b/src/utils/webhook.ts index add00b10..77579515 100644 --- a/src/utils/webhook.ts +++ b/src/utils/webhook.ts @@ -35,6 +35,18 @@ export class InvalidWebhookError extends Error { const GZIP_MAGIC = Buffer.from([0x1f, 0x8b]); +/** + * Webhook helper settings. + * + * `maxPayloadBytes` caps the decompressed size of a gzip webhook body + * (default 10 MiB). {@link gunzipPayload} runs before the signature + * check, so without a cap an unsigned gzip bomb could exhaust memory. + * Raise it if your events are larger. + */ +export const webhookConfig = { + maxPayloadBytes: 10 * 1024 * 1024, +}; + /** * Returns `body` as a `Buffer`, gzip-decompressed when its first two * bytes match the gzip magic (`1f 8b`, per RFC 1952). When the body is @@ -44,13 +56,23 @@ const GZIP_MAGIC = Buffer.from([0x1f, 0x8b]); * Magic-byte detection (rather than relying on a header) keeps the same * handler correct when middleware - Express, Next.js, AWS Lambda - * auto-decompresses the request before your code sees it. + * + * @throws {InvalidWebhookError} When the body has the gzip magic but is + * not valid gzip, or inflates to more than + * `webhookConfig.maxPayloadBytes`. */ export function gunzipPayload(rawBody: string | Buffer): Buffer { const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody); if (body.length >= 2 && body.subarray(0, 2).equals(GZIP_MAGIC)) { + const limit = webhookConfig.maxPayloadBytes; try { - return zlib.gunzipSync(body); - } catch { + return zlib.gunzipSync(body, { maxOutputLength: limit }); + } catch (err) { + if ((err as NodeJS.ErrnoException).code === 'ERR_BUFFER_TOO_LARGE') { + throw new InvalidWebhookError( + `${InvalidWebhookErrorMessages.gzipFailed}: payload exceeds ${limit} bytes`, + ); + } throw new InvalidWebhookError(InvalidWebhookErrorMessages.gzipFailed); } }