Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(ingress): refuse ack header values and statuses Node cannot send
Yudhi Armyndharisfe4dd4e3a57e
diff --git a/docs/25-integration-fabric.md b/docs/25-integration-fabric.mdindex d30b252f0..4f8224c55 100644--- a/docs/25-integration-fabric.md+++ b/docs/25-integration-fabric.md@@ -269,8 +269,10 @@ Within major 1 the surface grows additively. A route's optional `response` contr`headers`, rendered host-side with `{rawBody}`/`{timestamp}`/`{id}` templates from the verified request),and an advisory `deadlineMs` — lets an adapter shape the synchronous HTTP response the provider sees; theplugin still always runs async, and a route with no `response` is byte-identical to today's default-fast-ack. `ack.body` and every `ack.headers` value must be strings, and a manifest that declares otherwise-is refused at install and at boot, which leaves that plugin in error until the manifest is fixed. A+fast-ack. `ack.body` and every `ack.headers` value must be strings, `ack.status` must be a final status+(200-599), and a header value may hold no control character (other than HTAB) and nothing above U+00FF,+since Node cannot write one; a manifest that declares otherwise is refused at install and at boot, which+leaves that plugin in error until the manifest is fixed. Adeclared header is dropped rather than written when it is one of these thirteen names: `content-type`(decided by the allowlist in §25.8); `content-length`, `transfer-encoding`, `content-encoding` and`trailer`, since the host frames the response itself and never compresses it; `set-cookie`,diff --git a/src/core/plugins/plugin-manifest-ingress.spec.ts b/src/core/plugins/plugin-manifest-ingress.spec.tsindex 09698d515..c29e5f8e0 100644--- a/src/core/plugins/plugin-manifest-ingress.spec.ts+++ b/src/core/plugins/plugin-manifest-ingress.spec.ts@@ -287,6 +287,28 @@ describe('validateIngressManifest: response contract', () => {).toThrow(/invalid characters/);});+ it('rejects a 1xx ack.status, which Node sends with no final response after it', () => {+ for (const status of [100, 103, 199]) {+ expect(() => validateIngressManifest(manifestWithRoute({ response: { ack: { status } } }))).toThrow(+ /ack\.status/,+ );+ }+ expect(() => validateIngressManifest(manifestWithRoute({ response: { ack: { status: 200 } } }))).not.toThrow();+ });++ it('rejects an ack header value Node cannot write, and keeps Latin-1 and HTAB', () => {+ for (const value of ['ok \u2713', 'a\u0000b', 'a\u007fb', 'a\u001bb']) {+ expect(() =>+ validateIngressManifest(manifestWithRoute({ response: { ack: { headers: { 'x-note': value } } } })),+ ).toThrow(/invalid characters/);+ }+ for (const value of ['caf\u00e9', 'a\tb']) {+ expect(() =>+ validateIngressManifest(manifestWithRoute({ response: { ack: { headers: { 'x-note': value } } } })),+ ).not.toThrow();+ }+ });+it('rejects a non-string ack body', () => {// A manifest is third-party JSON. Left unchecked, a number or object here reached the renderer,// which drops anything that is not a string, so the route answered every delivery with an EMPTY@@ -297,7 +319,7 @@ describe('validateIngressManifest: response contract', () => {});it('rejects a non-string ack header value', () => {- // Same silent drop, and the CR/LF guard below does not catch it: RegExp.test coerces its+ // Same silent drop, and the character guard does not catch it: RegExp.test coerces its// argument, so a number passes the injection check and is then filtered out at render time.expect(() =>validateIngressManifest(diff --git a/src/core/plugins/plugin.interfaces.ts b/src/core/plugins/plugin.interfaces.tsindex d9e0963ec..1d383387b 100644--- a/src/core/plugins/plugin.interfaces.ts+++ b/src/core/plugins/plugin.interfaces.ts@@ -243,7 +243,7 @@ export interface IngressResponseContract {ack?: {status?: number; // default 202body?: string; // literal, or a '{rawBody}'/'{timestamp}'/'{id}' template rendered host-side- headers?: Record<string, string>; // static; validated at load (HTTP-token name, no CR/LF value)+ headers?: Record<string, string>; // static; validated at load (HTTP-token name, a value Node can write)};deadlineMs?: number; // documented provider ack budget (advisory; not enforced)}@@ -309,10 +309,13 @@ export interface ConversationSendEnvelope {/** Integration SDK major version this host supports. A plugin whose `sdkVersion` major differs is refused. */export const SUPPORTED_SDK_MAJOR = 1;-// ack header guards: name must be an RFC 7230 token (no spaces/separators), value must contain no-// CR/LF (header-injection guard). The header source is the static manifest, validated once at load.+// ack header guards: name must be an RFC 7230 token (no spaces/separators), value must be one Node's+// setHeader accepts (HTAB, visible ASCII, space, and 0x80-0xFF; so no CR/LF and no other control+// character or anything above U+00FF). A value Node refuses throws at write time, after the delivery+// was persisted, and answers every attempt with a 500. The header source is the static manifest,+// validated once at load.const HTTP_HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;-const HTTP_HEADER_VALUE_NO_CRLF = /^[^\r\n]*$/;+const HTTP_HEADER_VALUE = /^[\t\x20-\x7e\x80-\xff]*$/;/*** Validates a manifest's `ingress` declarations: SDK major compatibility, the `webhook:ingress`@@ -365,9 +368,11 @@ export function validateIngressManifest(manifest: PluginManifest, allowUnsignedI}if (r.response) {const ackStatus = r.response.ack?.status;- if (ackStatus !== undefined && (!Number.isInteger(ackStatus) || ackStatus < 100 || ackStatus > 599)) {+ // A 1xx is an informational response: Node writes it with no final response after it, so the+ // provider waits until it times out.+ if (ackStatus !== undefined && (!Number.isInteger(ackStatus) || ackStatus < 200 || ackStatus > 599)) {throw new Error(- `Plugin ${manifest.id}: route '${r.route}' response.ack.status must be a valid HTTP status (100-599)`,+ `Plugin ${manifest.id}: route '${r.route}' response.ack.status must be a final HTTP status (200-599)`,);}const ackBody = r.response.ack?.body;@@ -381,14 +386,15 @@ export function validateIngressManifest(manifest: PluginManifest, allowUnsignedI`Plugin ${manifest.id}: route '${r.route}' response.ack header name '${name}' is not a valid HTTP token`,);}- // Before the CR/LF guard: RegExp.test coerces its argument, so a number would pass it and+ // Before the character guard: RegExp.test coerces its argument, so a number would pass it and// then be dropped at render time, leaving the header silently absent from every ack.if (typeof value !== 'string') {throw new Error(`Plugin ${manifest.id}: route '${r.route}' response.ack header '${name}' must be a string`);}- if (!HTTP_HEADER_VALUE_NO_CRLF.test(value)) {+ if (!HTTP_HEADER_VALUE.test(value)) {throw new Error(- `Plugin ${manifest.id}: route '${r.route}' response.ack header '${name}' has invalid characters (CR/LF forbidden)`,+ `Plugin ${manifest.id}: route '${r.route}' response.ack header '${name}' has invalid characters ` ++ `(control characters and characters above U+00FF cannot be written in a header)`,);}}