Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(webhook): refuse custom header values outside Latin-1
Yudhi Armyndharisffa8079dd2d2
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 90c4e788e..bd05093b5 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -4619,7 +4619,7 @@ Create a webhook for the session.| url | string | yes | `@IsUrl({ require_tld: false })` (allows hostnames without a dot, e.g. `http://localhost:3000`); also run through the SSRF guard, which can reject with `400`. Entity column max 2048 chars. | Webhook URL to receive events. || events | string[] | no | `@IsArray`, `@ArrayMinSize(1)`, `@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })` | Event names to subscribe to (see allowed set above). Defaults to `["message.received"]` when omitted. || secret | string | no | `@IsString`, `@MinLength(16)`, `@MaxLength(255)` | HMAC-SHA256 signing key. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). Used for `X-OpenWA-Signature`. Defaults to `null`. |-| headers | Record<string,string> | no | `@IsHeaderMap()` — flat object (not array), ≤50 entries, names match `/^[A-Za-z0-9-]+$/`, values are strings ≤1024 chars with no C0 control/DEL (CR/LF injection guard). | Custom headers added to deliveries. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). At delivery, `content-type` and `x-openwa-*` names are stripped, and so are the connection-level names the HTTP client owns: `connection`, `content-length`, `expect`, `keep-alive`, `te`, `trailer`, `transfer-encoding` and `upgrade`. Defaults to `{}`. |+| headers | Record<string,string> | no | `@IsHeaderMap()`: flat object (not array), ≤50 entries, names match `/^[A-Za-z0-9-]+$/`, values are strings ≤1024 chars with no C0 control/DEL (CR/LF injection guard) and nothing above U+00FF (Latin-1 only). | Custom headers added to deliveries. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). At delivery, `content-type` and `x-openwa-*` names are stripped, and so are the connection-level names the HTTP client owns: `connection`, `content-length`, `expect`, `keep-alive`, `te`, `trailer`, `transfer-encoding` and `upgrade`. Defaults to `{}`. || filters | WebhookFilters \| null | no | `@IsValidWebhookFilters()`, i.e. `{ conditions: [...] }`; each condition `{ field, operator('is'\|'isNot'\|'contains'\|'equals'), value(string\|string[]\|boolean), caseSensitive?:boolean }`; bounds: max 20 conditions, 100 values/condition, 1000-char text values. Message fields: `sender`, `recipient`, `chatId`, `body`, `type`, `isGroup`, `kind`, `fromMe`, `hasMedia`, `mentions`. An id-valued condition accepts a bare phone number, but a group must be written as its full `<id>@g.us` JID: bare digits canonicalise to `@c.us` and match no group. | Optional AND pre-filter; **all** conditions must match for the webhook to fire. Omit/null = fire on every subscribed event. Defaults to `null`. ⚠️ A condition whose field is DEFINED for the event family but absent from that event's payload does not scope the event, it decides it outright: an `is`, `contains` or `equals` condition cannot match and suppresses the event, while an `isNot` condition passes it, and so does a boolean field compared with `false`, because an absent boolean reads as `false` (a field with no definition for the family is skipped instead). `message.ack`/`message.failed` carry `{ id, messageId, status, ack }` and `message.reaction` carries `{ messageId, chatId, reaction, senderId }`, none of which has a sender or body, so a `sender` `is` filter silently drops all three and a `sender` `isNot` filter delivers all three. `message.ack`/`message.failed` carry no `chatId` either, so a `chatId` `isNot` exclusion does not keep that chat's acks and failures out. Scope the subscription with `events[]` rather than relying on a filter to be inert. Set `LOG_LEVEL=debug` to see each suppression and the payload fields that were available. || retryCount | number (int) | no | `@IsInt`, `@Min(0)`, `@Max(5)` | Total delivery attempts per event, including the first: `0` and `1` both mean a single attempt with no retry. An event that exhausts them is recorded in `GET /api/webhooks/delivery-failures`; the webhook stays active. Defaults to `3`. |diff --git a/src/modules/webhook/dto/is-header-map.validator.ts b/src/modules/webhook/dto/is-header-map.validator.tsindex 484152df6..b5946e61f 100644--- a/src/modules/webhook/dto/is-header-map.validator.ts+++ b/src/modules/webhook/dto/is-header-map.validator.ts@@ -4,11 +4,15 @@ const HEADER_NAME = /^[A-Za-z0-9-]+$/;const MAX_HEADERS = 50;const MAX_VALUE_LENGTH = 1024;-/** Reject C0 control chars + DEL — notably CR/LF, the header-injection vector. */-function hasControlChar(s: string): boolean {+/**+ * Reject C0 control chars and DEL (notably CR/LF, the header-injection vector) and anything above+ * U+00FF: the HTTP client sends header values as Latin-1 bytes and throws on any wider code unit,+ * which would fail every delivery of the webhook.+ */+function hasInvalidValueChar(s: string): boolean {for (let i = 0; i < s.length; i++) {const c = s.charCodeAt(i);- if (c < 0x20 || c === 0x7f) return true;+ if (c < 0x20 || c === 0x7f || c > 0xff) return true;}return false;}@@ -16,8 +20,9 @@ function hasControlChar(s: string): boolean {/*** Validate operator-supplied webhook custom headers as a flat map of valid header names to string* values: rejects non-object shapes, invalid header names, non-string or control-character values- * (CR/LF header injection), and over-large maps (≤50 entries, value ≤1024 chars). Reserved-name- * stripping still happens at delivery time (sanitizeCustomHeaders); this is the input-side guard.+ * (CR/LF header injection), values outside Latin-1, and over-large maps (≤50 entries, value ≤1024+ * chars). Reserved-name stripping still happens at delivery time (sanitizeCustomHeaders); this is the+ * input-side guard.*/export function IsHeaderMap(options?: ValidationOptions) {return function (target: object, propertyName: string): void {@@ -34,11 +39,11 @@ export function IsHeaderMap(options?: ValidationOptions) {if (entries.length > MAX_HEADERS) return false;return entries.every(([k, v]) =>- HEADER_NAME.test(k) && typeof v === 'string' && v.length <= MAX_VALUE_LENGTH && !hasControlChar(v),+ HEADER_NAME.test(k) && typeof v === 'string' && v.length <= MAX_VALUE_LENGTH && !hasInvalidValueChar(v),);},defaultMessage(): string {- return 'headers must be a flat map of valid header names to string values (no control characters, max 50 entries, value max 1024 chars)';+ return 'headers must be a flat map of valid header names to string values (no control characters or characters outside Latin-1, max 50 entries, value max 1024 chars)';},},});diff --git a/src/modules/webhook/dto/webhook.dto.spec.ts b/src/modules/webhook/dto/webhook.dto.spec.tsindex 7c2679b60..d1ae9b1c6 100644--- a/src/modules/webhook/dto/webhook.dto.spec.ts+++ b/src/modules/webhook/dto/webhook.dto.spec.ts@@ -91,6 +91,29 @@ describe('webhook DTO custom-header validation', () => {const errs = await errorsFor(UpdateWebhookDto, { headers: { 'X-Evil': 'a\nb' } });expect(errs.some(e => e.property === 'headers')).toBe(true);});++ // Header values go out as Latin-1 bytes; a wider code unit throws inside the HTTP client on every+ // delivery, so it must be refused when the webhook is saved.+ it.each(['Caf\u00e9 \u2192 Norte', '\u6771\u4eac', 'hi \u{1F600}'])(+ 'rejects a header value outside Latin-1 (%s) on create and update',+ async value => {+ const create = await errorsFor(CreateWebhookDto, {+ url: 'https://example.com/hook',+ headers: { 'X-Tenant': value },+ });+ expect(create.some(e => e.property === 'headers')).toBe(true);+ const update = await errorsFor(UpdateWebhookDto, { headers: { 'X-Tenant': value } });+ expect(update.some(e => e.property === 'headers')).toBe(true);+ },+ );++ it('accepts a Latin-1 header value on create and update', async () => {+ const headers = { 'X-Tenant': 'Caf\u00e9 Norte \u00ff' };+ const create = await errorsFor(CreateWebhookDto, { url: 'https://example.com/hook', headers });+ expect(create.some(e => e.property === 'headers')).toBe(false);+ const update = await errorsFor(UpdateWebhookDto, { headers });+ expect(update.some(e => e.property === 'headers')).toBe(false);+ });});describe('webhook DTO filter validation', () => {