Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(validation): bound varchar-backed fields in code points
Yudhi Armyndharisbedd37afb09c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b31a1644a..27a491b8f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -158,7 +158,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Webhook create and update answer `400` for a URL longer than 2048 characters instead of `500` on PostgreSQL.- With `WEBHOOK_SSRF_PROTECT=false`, webhook create and update answer `400` for a URL that is not an absolute `http://` or `https://` URL instead of storing one that fails every delivery.- `POST /api/sessions/:sessionId/status/send-text` answers `400` for an empty or whitespace-only text instead of posting a blank status.-- A template name over 100 code points, such as one of emoji with variation selectors, is refused with `400` instead of failing with `500` on PostgreSQL.+- A template, automation rule or API key name, a webhook URL or signing secret, or a session proxy URL longer than its column in code points, such as one of emoji with variation selectors, is refused with `400` instead of failing with `500` on PostgreSQL.- `POST /api/sessions/:sessionId/messages/send-bulk` answers `429` instead of `400` when the node already runs `BULK_MAX_CONCURRENT_BATCHES` batches, so clients retry it.- A bulk batch whose run failed before processing started, or whose process died first, ends `FAILED` instead of staying `PENDING`, and batches failed by the startup or takeover reap report `completedAt`.- Starting or stopping a session whose node's lease lapsed, with `POST /api/sessions/:sessionId/start` or `POST /api/sessions/:sessionId/stop`, fails that node's unfinished bulk batches, as the takeover sweep does; before, they stayed `PENDING` or `PROCESSING` until a node restarted.diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex d4bdd7431..f3874c59d 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -4661,9 +4661,9 @@ Create a webhook for the session.| Field | Type | Required | Constraints | Description || ---------- | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| url | string | yes | `@IsUrl({ require_tld: false, require_protocol: true, protocols: ['http', 'https'] })` (allows hostnames without a dot, e.g. `http://localhost:3000`), `@MaxLength(2048)`; also run through the SSRF guard, which can reject with `400`. | Webhook URL to receive events. |+| url | string | yes | `@IsUrl({ require_tld: false, require_protocol: true, protocols: ['http', 'https'] })` (allows hostnames without a dot, e.g. `http://localhost:3000`), `@MaxCodePoints(2048)`; also run through the SSRF guard, which can reject with `400`. | 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`. |+| secret | string | no | `@IsString`, `@MinLength(16)`, `@MaxCodePoints(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-]+$/` and are unique ignoring case, 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`, `user-agent` 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`. |@@ -4725,15 +4725,15 @@ Update a webhook. Partial — only fields present in the body are changed.**Request body** — `UpdateWebhookDto` (all fields optional; only fields where the value is not `undefined` are applied)-| Field | Type | Required | Constraints | Description |-| ---------- | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |-| url | string | no | omit to skip (explicit `null` → `400`), `@IsUrl({ require_tld: false, require_protocol: true, protocols: ['http', 'https'] })`, `@MaxLength(2048)`; re-runs the SSRF guard when provided → `400` if blocked. | New URL. |-| events | string[] | no | omit to skip (explicit `null` → `400`), `@IsArray`, `@ArrayMinSize(1)`, `@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })` | Same allowed set as create (incl. `*`). |-| secret | string | no | `@IsOptional`, `@IsString`, `@MinLength(16)` (skipped for `""`, which clears it), `@MaxLength(255)` | **Write-only.** An empty string is normalized to `null`, which disables HMAC. |-| headers | Record<string,string> | no | omit to skip (explicit `null` → `400`), `@IsHeaderMap()` (same constraints as create) | **Write-only.** Replaces existing headers wholesale when provided. |-| filters | WebhookFilters \| null | no | `@IsOptional`, `@IsValidWebhookFilters()` | Set to `null` or `{ conditions: [] }` to clear filters. |-| active | boolean | no | omit to skip (explicit `null` → `400`), `@IsBoolean` | Enable/disable the webhook. (Present only on update, not create.) |-| retryCount | number (int) | no | omit to skip (explicit `null` → `400`), `@IsInt`, `@Min(0)`, `@Max(5)` | Total delivery attempts per event, including the first. |+| Field | Type | Required | Constraints | Description |+| ---------- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |+| url | string | no | omit to skip (explicit `null` → `400`), `@IsUrl({ require_tld: false, require_protocol: true, protocols: ['http', 'https'] })`, `@MaxCodePoints(2048)`; re-runs the SSRF guard when provided → `400` if blocked. | New URL. |+| events | string[] | no | omit to skip (explicit `null` → `400`), `@IsArray`, `@ArrayMinSize(1)`, `@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })` | Same allowed set as create (incl. `*`). |+| secret | string | no | `@IsOptional`, `@IsString`, `@MinLength(16)` (skipped for `""`, which clears it), `@MaxCodePoints(255)` | **Write-only.** An empty string is normalized to `null`, which disables HMAC. |+| headers | Record<string,string> | no | omit to skip (explicit `null` → `400`), `@IsHeaderMap()` (same constraints as create) | **Write-only.** Replaces existing headers wholesale when provided. |+| filters | WebhookFilters \| null | no | `@IsOptional`, `@IsValidWebhookFilters()` | Set to `null` or `{ conditions: [] }` to clear filters. |+| active | boolean | no | omit to skip (explicit `null` → `400`), `@IsBoolean` | Enable/disable the webhook. (Present only on update, not create.) |+| retryCount | number (int) | no | omit to skip (explicit `null` → `400`), `@IsInt`, `@Min(0)`, `@Max(5)` | Total delivery attempts per event, including the first. |```json{diff --git a/src/common/validation/max-code-points.spec.ts b/src/common/validation/max-code-points.spec.tsnew file mode 100644index 000000000..258ea7981--- /dev/null+++ b/src/common/validation/max-code-points.spec.ts@@ -0,0 +1,38 @@+import { BadRequestException, ValidationPipe } from '@nestjs/common';+import { GLOBAL_VALIDATION_OPTIONS } from '../../config/app-validation';+import { CreateApiKeyDto, UpdateApiKeyDto } from '../../modules/auth/dto/api-key.dto';+import { CreateAutomationRuleDto, UpdateAutomationRuleDto } from '../../modules/automation/dto/automation-rule.dto';+import { CreateSessionDto } from '../../modules/session/dto/create-session.dto';+import { UpdateSessionProxyDto } from '../../modules/session/dto/session-proxy.dto';+import { CreateWebhookDto, UpdateWebhookDto } from '../../modules/webhook/dto/webhook.dto';++// Each field lands in a varchar(n) column, which PostgreSQL counts in code points. @MaxLength folds a+// presentation selector (U+FE0F) into the character before it, so a value of up to 2n code points+// passed validation and the INSERT failed as a 500.+describe('varchar-backed fields are bounded in code points', () => {+ const pipe = new ValidationPipe(GLOBAL_VALIDATION_OPTIONS);+ const emoji = '✔️';+ const url = 'https://example.com/';+ const proxy = (pad: string): string => `http://user:${pad}@proxy.example.com:8080`;++ it.each([+ ['automation rule create name', CreateAutomationRuleDto, { replyText: 'hi' }, 'name', 100, (p: string) => p],+ ['automation rule update name', UpdateAutomationRuleDto, {}, 'name', 100, (p: string) => p],+ ['API key create name', CreateApiKeyDto, {}, 'name', 100, (p: string) => p],+ ['API key update name', UpdateApiKeyDto, {}, 'name', 100, (p: string) => p],+ ['webhook create secret', CreateWebhookDto, { url }, 'secret', 255, (p: string) => p],+ ['webhook update secret', UpdateWebhookDto, {}, 'secret', 255, (p: string) => p],+ ['webhook create url', CreateWebhookDto, {}, 'url', 2048 - url.length, (p: string) => url + p],+ ['webhook update url', UpdateWebhookDto, {}, 'url', 2048 - url.length, (p: string) => url + p],+ ['session create proxyUrl', CreateSessionDto, { name: 'bot' }, 'proxyUrl', 255 - proxy('').length, proxy],+ ['session proxy update proxyUrl', UpdateSessionProxyDto, {}, 'proxyUrl', 255 - proxy('').length, proxy],+ ])('%s', async (_label, metatype, rest, field, room, wrap) => {+ const through = (pad: string): Promise<unknown> =>+ pipe.transform({ ...rest, [field]: wrap(pad) }, { type: 'body', metatype });+ const half = Math.floor(room / 2);+ await expect(through(emoji.repeat(half + 1))).rejects.toBeInstanceOf(BadRequestException);+ await expect(through(emoji.repeat(half))).resolves.toMatchObject({ [field]: wrap(emoji.repeat(half)) });+ await expect(through('a'.repeat(room))).resolves.toMatchObject({ [field]: wrap('a'.repeat(room)) });+ await expect(through('a'.repeat(room + 1))).rejects.toBeInstanceOf(BadRequestException);+ });+});diff --git a/src/common/validation/max-code-points.ts b/src/common/validation/max-code-points.tsnew file mode 100644index 000000000..66f64159a--- /dev/null+++ b/src/common/validation/max-code-points.ts@@ -0,0 +1,14 @@+import { Matches, ValidationOptions } from 'class-validator';++/**+ * Bound a string by code points, the unit PostgreSQL counts a `varchar(n)` in. `@MaxLength` does not:+ * it folds a presentation selector (U+FE0F) into the character before it, so a value it passes can+ * still overflow the column and fail the INSERT with a 500. The `u` flag makes each matched unit one+ * code point.+ */+export function MaxCodePoints(max: number, options?: ValidationOptions): PropertyDecorator {+ return Matches(new RegExp(`^[\\s\\S]{0,${max}}$`, 'u'), {+ message: `$property must be shorter than or equal to ${max} characters`,+ ...options,+ });+}diff --git a/src/modules/auth/dto/api-key.dto.ts b/src/modules/auth/dto/api-key.dto.tsindex 193fb8e6e..2ea1e146b 100644--- a/src/modules/auth/dto/api-key.dto.ts+++ b/src/modules/auth/dto/api-key.dto.ts@@ -1,15 +1,6 @@-import {- IsString,- IsOptional,- IsEnum,- IsArray,- ArrayUnique,- IsDateString,- MinLength,- MaxLength,- Validate,-} from 'class-validator';+import { IsString, IsOptional, IsEnum, IsArray, ArrayUnique, IsDateString, MinLength, Validate } from 'class-validator';import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';+import { MaxCodePoints } from '../../../common/validation/max-code-points';import { ApiKeyRole } from '../entities/api-key.entity';import { IsIpOrCidrConstraint } from './is-ip-or-cidr.validator';import { IsSessionIdConstraint } from './is-session-id.validator';@@ -22,7 +13,7 @@ export class CreateApiKeyDto {})@IsString()@MinLength(3)- @MaxLength(100)+ @MaxCodePoints(100)name!: string;@ApiPropertyOptional({@@ -150,7 +141,7 @@ export class UpdateApiKeyDto {@IsOptional()@IsString()@MinLength(3)- @MaxLength(100)+ @MaxCodePoints(100)name?: string;@ApiPropertyOptional({ enum: ApiKeyRole })diff --git a/src/modules/automation/dto/automation-rule.dto.ts b/src/modules/automation/dto/automation-rule.dto.tsindex 32020de0e..73c0cb57a 100644--- a/src/modules/automation/dto/automation-rule.dto.ts+++ b/src/modules/automation/dto/automation-rule.dto.ts@@ -2,6 +2,7 @@ import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';import { Expose, plainToInstance } from 'class-transformer';import { IsBoolean, IsInt, IsNotEmpty, IsOptional, IsString, Max, MaxLength, Min, ValidateIf } from 'class-validator';import { ToStrictBoolean, ToStrictNumber } from '../../../common/utils/strict-boolean';+import { MaxCodePoints } from '../../../common/validation/max-code-points';import { MESSAGE_TEXT_MAX_LENGTH } from '../../message/dto/send-message.dto';import { WebhookFilters } from '../../webhook/filters/filter-types';import { IsValidWebhookFilters } from '../../webhook/filters/filter-validation';@@ -27,7 +28,7 @@ export class CreateAutomationRuleDto {@ApiProperty({ description: 'Display name for the rule', example: 'Greet new enquiries', maxLength: 100 })@IsString()@IsNotEmpty()- @MaxLength(100)+ @MaxCodePoints(100)name!: string;@ApiProperty({@@ -71,7 +72,7 @@ export class UpdateAutomationRuleDto {@ValidateIf((o: UpdateAutomationRuleDto) => o.name !== undefined)@IsString()@IsNotEmpty()- @MaxLength(100)+ @MaxCodePoints(100)name?: string;@ApiPropertyOptional({diff --git a/src/modules/session/dto/create-session.dto.ts b/src/modules/session/dto/create-session.dto.tsindex 10f13c567..f4fecbe5b 100644--- a/src/modules/session/dto/create-session.dto.ts+++ b/src/modules/session/dto/create-session.dto.ts@@ -1,5 +1,6 @@import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';import { IsIn, IsObject, IsOptional, IsString, IsUrl, Matches, MaxLength, MinLength, Validate } from 'class-validator';+import { MaxCodePoints } from '../../../common/validation/max-code-points';import { HasDecodableProxyCredentialsConstraint } from './has-decodable-proxy-credentials.validator';export class CreateSessionDto {@@ -46,7 +47,7 @@ export class CreateSessionDto {})@IsOptional()@IsString()- @MaxLength(255)+ @MaxCodePoints(255)// Reject a malformed/non-proxy URL at the boundary (credentialed http://user:pass@host and// socks4/5 still validate). The host is intentionally NOT SSRF-blocked here — a per-session proxy// is trusted egress that only an ADMIN key may set, and a loopback proxy sidecar is a legitimate setup.diff --git a/src/modules/session/dto/session-proxy.dto.ts b/src/modules/session/dto/session-proxy.dto.tsindex ac73296cd..1db96af37 100644--- a/src/modules/session/dto/session-proxy.dto.ts+++ b/src/modules/session/dto/session-proxy.dto.ts@@ -1,5 +1,6 @@import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';-import { IsOptional, IsString, IsUrl, MaxLength, Validate } from 'class-validator';+import { IsOptional, IsString, IsUrl, Validate } from 'class-validator';+import { MaxCodePoints } from '../../../common/validation/max-code-points';import { HasDecodableProxyCredentialsConstraint } from './has-decodable-proxy-credentials.validator';import type { Session } from '../entities/session.entity';@@ -61,7 +62,7 @@ export class UpdateSessionProxyDto {})@IsOptional()@IsString()- @MaxLength(255)+ @MaxCodePoints(255)@IsUrl({protocols: ['http', 'https', 'socks4', 'socks5'],diff --git a/src/modules/template/dto/template.dto.ts b/src/modules/template/dto/template.dto.tsindex d4a93d89e..c8e9d139f 100644--- a/src/modules/template/dto/template.dto.ts+++ b/src/modules/template/dto/template.dto.ts@@ -1,16 +1,11 @@import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';-import { IsString, IsNotEmpty, IsOptional, Matches, MaxLength, ValidateIf } from 'class-validator';+import { IsString, IsNotEmpty, IsOptional, MaxLength, ValidateIf } from 'class-validator';+import { MaxCodePoints } from '../../../common/validation/max-code-points';const NAME_MAX_LENGTH = 100;const BODY_MAX_LENGTH = 4096;const HEADER_FOOTER_MAX_LENGTH = 1024;-// name is a varchar(100) column, and PostgreSQL counts code points. @MaxLength does not: it folds a-// presentation selector (U+FE0F) into the character before it, so 100 emoji of two code points each-// passed and the INSERT failed as a 500. The u flag makes each matched unit one code point.-const NAME_PATTERN = new RegExp(`^[\\s\\S]{0,${NAME_MAX_LENGTH}}$`, 'u');-const NAME_LENGTH_MESSAGE = `name must be shorter than or equal to ${NAME_MAX_LENGTH} characters`;-export class CreateTemplateDto {@ApiProperty({description: 'Unique template name within the session',@@ -19,7 +14,7 @@ export class CreateTemplateDto {})@IsString()@IsNotEmpty()- @Matches(NAME_PATTERN, { message: NAME_LENGTH_MESSAGE })+ @MaxCodePoints(NAME_MAX_LENGTH)name!: string;@ApiProperty({@@ -59,7 +54,7 @@ export class UpdateTemplateDto {@ValidateIf((o: UpdateTemplateDto) => o.name !== undefined)@IsString()@IsNotEmpty()- @Matches(NAME_PATTERN, { message: NAME_LENGTH_MESSAGE })+ @MaxCodePoints(NAME_MAX_LENGTH)name?: string;@ApiPropertyOptional({ description: 'Template body with {{variable}} placeholders', maxLength: BODY_MAX_LENGTH })diff --git a/src/modules/webhook/dto/webhook.dto.ts b/src/modules/webhook/dto/webhook.dto.tsindex 648585b84..53ceee993 100644--- a/src/modules/webhook/dto/webhook.dto.ts+++ b/src/modules/webhook/dto/webhook.dto.ts@@ -9,7 +9,6 @@ import {IsString,IsUrl,Max,- MaxLength,Min,MinLength,ValidateIf,@@ -21,6 +20,7 @@ import type { FilterOperator, WebhookFilters } from '../filters/filter-types';import { IsValidWebhookFilters } from '../filters/filter-validation';import { IsHeaderMap } from './is-header-map.validator';import { ToStrictBoolean, ToStrictNumber } from '../../../common/utils/strict-boolean';+import { MaxCodePoints } from '../../../common/validation/max-code-points';/*** Swagger metadata for the smart-filter shape — `WebhookFilters` in filters/filter-types.ts is a@@ -115,7 +115,7 @@ export class CreateWebhookDto {// were stored and then failed every delivery. 2048 is the column width; PostgreSQL refuses a// longer value on insert with a 500.@IsUrl(WEBHOOK_URL_OPTIONS)- @MaxLength(2048)+ @MaxCodePoints(2048)url!: string;@ApiPropertyOptional({@@ -150,7 +150,7 @@ export class CreateWebhookDto {// A short secret signs webhooks badly: HMAC-SHA256 over a 4-char key is brute-forcible from one// observed signature. 16 is the floor, not a recommendation.@MinLength(16)- @MaxLength(255)+ @MaxCodePoints(255)secret?: string;@ApiPropertyOptional({@@ -203,7 +203,7 @@ export class UpdateWebhookDto {// (save() then failed with a 500). Only an omitted field means "leave unchanged".@ValidateIf((_: UpdateWebhookDto, v: unknown) => v !== undefined)@IsUrl(WEBHOOK_URL_OPTIONS)- @MaxLength(2048)+ @MaxCodePoints(2048)url?: string;@ApiPropertyOptional({@@ -240,7 +240,7 @@ export class UpdateWebhookDto {// (the service stores null for it); a non-string value is still rejected by @IsString.@ValidateIf((o: UpdateWebhookDto) => o.secret !== '')@MinLength(16)- @MaxLength(255)+ @MaxCodePoints(255)secret?: string;@ApiPropertyOptional({