Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(ingress): fence the framing headers and refuse an untyped ack
Yudhi Armyndharis0645746351ba
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex fefd1487e..17bb8ad3f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -37,9 +37,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- `POST /api/sessions/:sessionId/automation-rules` answers `404` for a session that does not exist, instead of letting the foreign key surface as `500`.- A session proxy whose credentials contain a bare `%` is refused by `POST /api/sessions` and `PATCH /api/sessions/:sessionId/proxy` when it is set, instead of being stored and then failing every later start and every proxied URL fetch with an opaque `URI malformed`.- A WebSocket handshake whose transport closes while the key is being validated no longer burns a slot of the per-key connection cap for the life of the process.-- A repeated query parameter on an ingress verification challenge fails the challenge instead of answering `500`: the value arrives from Express as an array and reached a constant-time compare that accepts only strings.-- A plugin's declared ingress ack can no longer write the response headers that decide how a browser treats its own reflected body, nor set a cookie on the gateway's origin. The declared content type still applies, through the allowlist that already governed it.-- An ingress route whose manifest carries a non-string ack body, status or header is answered rather than failing with `500`; a manifest is third-party JSON and the loader does not type-check every leaf.+- A repeated query parameter on an ingress verification challenge is read as its first value instead of answering `500`: the value arrives from Express as an array and reached a constant-time compare that accepts only strings.+- A plugin's declared ingress ack can no longer write the response headers that decide how a browser treats its own reflected body, set a cookie on the gateway's origin, or claim a transfer or content encoding the ack does not actually use, which made the response undecodable and sent the provider back to retry a delivery already queued. The declared content type still applies, through the allowlist that already governed it.+- An ingress route whose manifest declares a non-string ack body or header value is refused at install and at boot, naming the field, instead of loading and then answering every delivery with that part of the ack silently missing.- Uploading a zip whose trailer parses but whose directory does not answers `400`, not `500`.- A `socks5://` or `socks4://` proxy at an IPv6 literal connects: the brackets `URL` keeps were going on the wire as part of a hostname.- A Baileys session whose credentials carry no LID of their own no longer reports a `group.join` for a group it created itself: every LID comparison answered false, so the creator was never recognised. The session's own LID mapping settles it instead.diff --git a/docs/25-integration-fabric.md b/docs/25-integration-fabric.mdindex f4c841455..c360fd95d 100644--- a/docs/25-integration-fabric.md+++ b/docs/25-integration-fabric.md@@ -269,7 +269,13 @@ 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. The `mode: 'sync-reply'` value is **deprecated** in favor of `response`: it was inert dead code+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. A declared header is dropped rather than written when it+names the content type (decided by the allowlist in §25.8), a framing or encoding header (`content-length`,+`transfer-encoding`, `content-encoding`, since the response is framed by the host and never compressed), a+cookie, a CORS header, or one of the browser-facing protections the host sets for every response.++The `mode: 'sync-reply'` value is **deprecated** in favor of `response`: it was inert dead codethat was never wired to the HTTP response (the pipeline is always async + fast-ack), and it is kept in the`mode` union only to preserve SDK v1 additive-only compatibility — do not remove it within major 1, and donot rely on it at runtime.diff --git a/src/core/plugins/plugin-manifest-ingress.spec.ts b/src/core/plugins/plugin-manifest-ingress.spec.tsindex fd41f547e..09698d515 100644--- a/src/core/plugins/plugin-manifest-ingress.spec.ts+++ b/src/core/plugins/plugin-manifest-ingress.spec.ts@@ -287,6 +287,25 @@ describe('validateIngressManifest: response contract', () => {).toThrow(/invalid characters/);});+ 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+ // ack while the manifest read as if it declared one.+ expect(() =>+ validateIngressManifest(manifestWithRoute({ response: { ack: { body: 42 as unknown as string } } })),+ ).toThrow(/ack\.body/);+ });++ 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+ // argument, so a number passes the injection check and is then filtered out at render time.+ expect(() =>+ validateIngressManifest(+ manifestWithRoute({ response: { ack: { headers: { 'x-retry': 5 as unknown as string } } } }),+ ),+ ).toThrow(/'x-retry'/);+ });+it('rejects a non-token ack header name', () => {expect(() =>validateIngressManifest(manifestWithRoute({ response: { ack: { headers: { 'bad header': 'x' } } } })),diff --git a/src/core/plugins/plugin.interfaces.ts b/src/core/plugins/plugin.interfaces.tsindex 676f795c4..d9e0963ec 100644--- a/src/core/plugins/plugin.interfaces.ts+++ b/src/core/plugins/plugin.interfaces.ts@@ -370,6 +370,10 @@ export function validateIngressManifest(manifest: PluginManifest, allowUnsignedI`Plugin ${manifest.id}: route '${r.route}' response.ack.status must be a valid HTTP status (100-599)`,);}+ const ackBody = r.response.ack?.body;+ if (ackBody !== undefined && typeof ackBody !== 'string') {+ throw new Error(`Plugin ${manifest.id}: route '${r.route}' response.ack.body must be a string`);+ }if (r.response.ack?.headers) {for (const [name, value] of Object.entries(r.response.ack.headers)) {if (!HTTP_HEADER_NAME.test(name)) {@@ -377,6 +381,11 @@ 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+ // 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)) {throw new Error(`Plugin ${manifest.id}: route '${r.route}' response.ack header '${name}' has invalid characters (CR/LF forbidden)`,diff --git a/src/modules/integration/ingress-ack.spec.ts b/src/modules/integration/ingress-ack.spec.tsindex 7b7b7e242..537051262 100644--- a/src/modules/integration/ingress-ack.spec.ts+++ b/src/modules/integration/ingress-ack.spec.ts@@ -59,17 +59,32 @@ describe('ackContentType', () => {});describe('safeAckHeaders (a plugin-authored ack cannot undo the app response contract)', () => {- it('drops the headers that decide how a browser treats the reflected body', () => {- expect(- safeAckHeaders({- 'X-Content-Type-Options': 'nosniff-not',- 'Content-Security-Policy': 'default-src *',- 'Set-Cookie': 'a=b',- 'Access-Control-Allow-Origin': '*',- 'Content-Type': 'text/html',- 'X-Provider-Ack': 'ok',- }),- ).toEqual({ 'X-Provider-Ack': 'ok' });+ it('drops every reserved name, whatever the case, and keeps everything else', () => {+ const reserved = {+ 'Content-Type': 'text/html',+ 'Content-Length': '99',+ 'Transfer-Encoding': 'chunked',+ 'Content-Encoding': 'gzip',+ 'Content-Security-Policy': 'default-src *',+ 'X-Content-Type-Options': 'nosniff-not',+ 'X-Frame-Options': 'ALLOWALL',+ 'Strict-Transport-Security': 'max-age=0',+ 'Referrer-Policy': 'unsafe-url',+ 'Set-Cookie': 'a=b',+ 'Access-Control-Allow-Origin': '*',+ 'Access-Control-Allow-Credentials': 'true',+ };+ // Every name is asserted, so removing any one of them from the set fails this.+ expect(safeAckHeaders(reserved)).toEqual({});+ expect(safeAckHeaders({ ...reserved, 'X-Provider-Ack': 'ok' })).toEqual({ 'X-Provider-Ack': 'ok' });+ });++ it('drops the framing headers, which would put an undecodable response on the wire', () => {+ // Express frames the ack itself and the host runs no compression middleware, so a declared+ // `Transfer-Encoding: chunked` or `Content-Encoding: gzip` describes an encoding the body does+ // not have: the provider's HTTP client fails to decode it and retries a delivery already queued.+ expect(safeAckHeaders({ 'transfer-encoding': 'chunked' })).toEqual({});+ expect(safeAckHeaders({ 'content-encoding': 'gzip' })).toEqual({});});it('is total: no headers, and a non-string value, both answer an object', () => {@@ -82,7 +97,7 @@ describe('renderAck / ackContentType stay total on a manifest the loader did notconst ctx = { rawBody: '{}', timestamp: '1', id: 'd1' };it('ignores a non-string body and a non-number status instead of throwing', () => {- const spec = { status: '202' as unknown as number, body: 7 as unknown as string };+ const spec = { status: '204' as unknown as number, body: 7 as unknown as string };expect(renderAck(spec, ctx)).toEqual({ status: 202 });});diff --git a/src/modules/integration/ingress-ack.ts b/src/modules/integration/ingress-ack.tsindex b15ba3593..8fa93dc7a 100644--- a/src/modules/integration/ingress-ack.ts+++ b/src/modules/integration/ingress-ack.ts@@ -18,9 +18,10 @@ export type AckResult = { status: number; body?: string; headers?: Record<stringexport function renderAck(spec: IngressResponseContract['ack'] | undefined, ctx: AckRenderCtx): AckResult {if (!spec) return { status: 202, body: 'accepted' };const result: AckResult = { status: typeof spec.status === 'number' ? spec.status : 202 };- // Typed as a string, but a manifest is third-party JSON and the loader does not check the type of- // every leaf, so a number or an object here would throw out of a function documented as total and- // turn an accepted delivery into a 500.+ // validateIngressManifest rejects a non-string body, a non-string header value and a non-integer+ // status, so these guards are the second line rather than the first: this function is documented+ // as total, and it is also reachable from a built-in manifest and from a test fixture that never+ // went through the loader. On a shape the loader would have refused, fall back rather than throw.if (typeof spec.body === 'string') {result.body = substitute(spec.body, ctx);}@@ -31,16 +32,24 @@ export function renderAck(spec: IngressResponseContract['ack'] | undefined, ctx:}/**- * Header names a route's declared ack may never write.+ * Header names a route's declared ack may never write. Three groups, all plugin-authored and landing+ * on the gateway's own origin, so none of them may undo what the app sets for every response:*- * The ack block is plugin-authored and lands on the gateway's own origin, so it must not undo what- * the app sets for every response: `content-type` is decided by {@link ackContentType} immediately- * after, and the rest are the browser-facing protections that make a reflected ack body safe in the- * first place. Anything else a manifest declares still goes out verbatim.+ * - `content-type`, decided by {@link ackContentType} immediately after;+ * - the framing and encoding headers, which describe a body Express has already framed and the host+ * never compresses. A declared `Transfer-Encoding: chunked` or `Content-Encoding: gzip` describes+ * bytes the ack does not carry, so the provider's HTTP client fails to decode the response and+ * retries a delivery the host has already accepted and queued. `content-length` is inert (Express+ * overwrites it) and is fenced with them rather than reasoned about separately;+ * - the browser-facing protections that make a reflected ack body safe in the first place.+ *+ * Anything else a manifest declares still goes out verbatim.*/const RESERVED_ACK_HEADERS: ReadonlySet<string> = new Set(['content-type','content-length',+ 'transfer-encoding',+ 'content-encoding','content-security-policy','x-content-type-options','x-frame-options',diff --git a/src/modules/integration/ingress.controller.spec.ts b/src/modules/integration/ingress.controller.spec.tsindex 98cb7776c..94446fe88 100644--- a/src/modules/integration/ingress.controller.spec.ts+++ b/src/modules/integration/ingress.controller.spec.ts@@ -158,4 +158,56 @@ describe('IngressController', () => {expect(captured.body).toBe('{"ok":true}');expect(captured.headers).toEqual({ 'content-type': 'application/json' });});++ it('never writes a reserved header a route declared', async () => {+ // res.type rewrites content-type whatever happens, so asserting that header alone cannot tell+ // whether the filter runs at all. These are the ones nothing downstream would put back.+ const handle = jest.fn().mockResolvedValue({+ status: 200,+ body: 'ok',+ headers: { 'Set-Cookie': 'a=b', 'Transfer-Encoding': 'chunked', 'X-Provider-Ack': 'kept' },+ });+ const controller = new IngressController({ handle } as unknown as IngressService);+ const { res, captured } = fakeRes();+ const req = {+ method: 'POST',+ params: { path: ['send-sms'] },+ headers: {},+ rawBody: Buffer.from('{}'),+ } as unknown as Request & { rawBody?: Buffer };++ await controller.receive('p', 'i1', {}, req, res);++ expect(captured.headers['set-cookie']).toBeUndefined();+ expect(captured.headers['transfer-encoding']).toBeUndefined();+ expect(captured.headers['x-provider-ack']).toBe('kept');+ });+});++describe('query values reach the pipeline as strings', () => {+ const callWithQuery = async (query: Record<string, unknown>) => {+ const handle = jest.fn().mockResolvedValue({ status: 200, body: '' });+ const controller = new IngressController({ handle } as unknown as IngressService);+ const { res } = fakeRes();+ const req = {+ method: 'GET',+ params: { path: ['meta'] },+ headers: {},+ } as unknown as Request & { rawBody?: Buffer };+ await controller.receive('meta', 'i1', query as Record<string, string>, req, res);+ return (handle.mock.calls[0] as [{ query: Record<string, string> }])[0].query;+ };++ it('keeps the first value of a repeated parameter', async () => {+ // Express answers `?hub.challenge=a&hub.challenge=b` with an array, and the challenge path feeds+ // the value into a constant-time compare that accepts only strings, so this used to answer 500.+ const query = await callWithQuery({ 'hub.challenge': ['a', 'b'], 'hub.verify_token': 'tok' });+ expect(query).toEqual({ 'hub.challenge': 'a', 'hub.verify_token': 'tok' });+ for (const value of Object.values(query)) expect(typeof value).toBe('string');+ });++ it('answers an empty string for a repeated parameter with no values, and for a non-string one', async () => {+ const query = await callWithQuery({ empty: [], odd: { nested: 'x' } });+ expect(query).toEqual({ empty: '', odd: '' });+ });});diff --git a/src/modules/integration/ingress.controller.ts b/src/modules/integration/ingress.controller.tsindex 26b7a1dd2..90a9a7012 100644--- a/src/modules/integration/ingress.controller.ts+++ b/src/modules/integration/ingress.controller.ts@@ -87,11 +87,13 @@ export class IngressController {const headers: Record<string, string> = Object.fromEntries(Object.entries(req.headers).map(([k, v]) => [k.toLowerCase(), Array.isArray(v) ? v.join(',') : String(v ?? '')]),);- // Express answers a repeated query parameter with an array, and a nested one with an object, so- // the Record<string, string> the service is typed against is a promise the framework does not- // keep. The challenge path feeds these straight into a constant-time compare, which throws on- // anything that is not a string, so `?token=a&token=b` answered 500 rather than failing the- // challenge. Flattened here, the way the headers above already are.+ // Express answers a repeated query parameter with an array, so the Record<string, string> the+ // service is typed against is a promise the framework does not keep. The challenge path feeds+ // these straight into a constant-time compare, which throws on anything that is not a string, so+ // `?token=a&token=b` answered 500. Flattened here, the way the headers above already are: the+ // first value wins, as URLSearchParams.get and most providers' own clients read it. The app runs+ // Express's default 'simple' query parser, which never nests (`?a[b]=c` is the key `a[b]`), so+ // the last arm is only there to keep the mapping total if that setting ever changes.const flatQuery: Record<string, string> = Object.fromEntries(Object.entries(query as Record<string, unknown>).map(([k, v]) => [k,@@ -111,8 +113,9 @@ export class IngressController {if (result.headers) res.set(safeAckHeaders(result.headers));// Both reflections echo provider-controlled strings (hub.challenge, the ack template). Express// types a bare send() as text/html, which turns a reflection into XSS material on this origin, so- // only a non-executable declared type survives and everything else is forced to text/plain. This- // runs AFTER res.set on purpose: both write the same Content-Type slot and the last writer wins.+ // only a non-executable declared type survives and everything else is forced to text/plain. It+ // reads the UNFILTERED headers on purpose: safeAckHeaders fences content-type precisely because+ // this is the one place allowed to decide it.res.type(ackContentType(result.headers));res.status(result.status).send(result.body ?? '');}