Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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; the
plugin 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. A
declared 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.ts
index 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.ts
index 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 202
body?: 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)`,
);
}
}