Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { createHash } from 'node:crypto';
import { throttlerMessage } from '@nestjs/throttler';
import { verifyIngressSignature } from './ingress-signature';
import { constantTimeEqual } from '../../common/security/constantTimeEqual';
import { PluginIngressRoute } from '../../core/plugins/plugin.interfaces';
import { IngressJobData } from '../queue/processors/ingress.processor';
import type { EngineStatus } from '../../engine/interfaces/whatsapp-engine.interface';
import { evaluatePreflight, pluginRestoringRejection } from './ingress-preflight';
import { renderAck } from './ingress-ack';
import type { IngressAdmission } from './ingress-instance-limit';
import { parseBodyLimitBytes } from '../../config/inflight-body-budget';
import { resolveBodyLimit } from '../../config/bootstrap-security';
import { createLogger } from '../../common/services/logger.service';
export interface IngressRequest {
pluginId: string;
instanceId: string;
route: string;
method: string;
headers: Record<string, string>; // lower-cased keys
query: Record<string, string>;
rawBody: string;
/**
* A body arrived in a content type no parser captured (only JSON and form bodies are), so `rawBody`
* is empty rather than the bytes that were sent.
*/
unparsedBody?: boolean;
}
export interface ResolvedInstance {
id: string;
pluginId: string;
instanceId: string;
secret: string;
enabled: boolean;
sessionScope: string | null;
verifyToken: string | null;
}
// The manifest route, possibly with the dedup header surfaced at the top level. On the real manifest
// dedupHeader lives under `signature`; the resolver may lift it, so read both (top level wins).
export type IngressRouteDescriptor = PluginIngressRoute & { dedupHeader?: string };
export interface IngressDeps {
instances: { resolve(pluginId: string, instanceId: string): Promise<ResolvedInstance | null> };
manifestRoute: (pluginId: string, route: string) => IngressRouteDescriptor | undefined;
events: {
recordOrSkip(input: {
instanceId: string;
pluginId: string;
providerDeliveryId: string;
route: string;
payload: IngressJobData['payload'] & { method?: string };
payloadHash: string;
sessionId: string | null;
}): Promise<boolean>;
};
// Returns an enqueue outcome (queued/dispatched/failed); handle() ignores it — only durability
// follow-up paths like redrive act on it. Typed as unknown here to keep this pure module decoupled.
enqueue: (data: IngressJobData, jobId: string) => Promise<unknown>;
// Optional host-side session-liveness probe for the `session-alive` preflight: returns the in-memory
// EngineStatus for a concrete session scope, or undefined when no engine is live. O(1) (a Map read +
// field read); MUST NOT call engine.initialize() or any blocking call. Absent (pure unit tests) → the
// session-alive check skips (passes) rather than false-rejecting.
sessionStatus?: (scope: string) => EngineStatus | undefined;
// Optional host-side probe: whether the boot restore has yet to finish with this plugin. A delivery for
// such a plugin on a route that declares a response contract is refused with a retryable 503 in the
// preflight stage, since no worker can take it yet. O(1) (a Set lookup). Absent in pure unit tests: every
// plugin counts as restored.
restorePending?: (pluginId: string) => boolean;
// Optional host-side probe: whether a delivery that was just persisted must not be dispatched yet. True for a
// plugin the boot restore has not reached while dispatch runs inline (queue off), where there is no worker
// to run it in; the row then stays 'pending' for the reconciler. Absent in pure unit tests: every delivery
// is dispatched.
deferDispatch?: (pluginId: string) => boolean;
// Optional structured sink for preflight rejections, so operators can audit deliveries that were
// rejected host-side (and therefore leave no dedup/DLQ row). Absent in pure unit tests.
log?: (event: string, meta: Record<string, unknown>) => void;
// Optional per-instance rate bucket (admitIngressInstance), charged only for a verified delivery.
// Absent in pure unit tests: every delivery is admitted and no rate headers are added.
admitInstance?: (pluginId: string, instanceId: string) => Promise<IngressAdmission>;
now: () => number;
}
/**
* The fast-ack ingress pipeline. Pure orchestration over injected deps so it is unit-testable without
* Nest DI: resolve the instance → answer a GET challenge host-side → size cap → verify over the RAW
* body → per-instance rate bucket → dedup (persist-before-ack) → best-effort conversation id →
* enqueue (or inline) → 202.
*/
export class IngressService {
private readonly logger = createLogger('IngressService');
constructor(private readonly deps: IngressDeps) {}
/**
* The cap to apply when a manifest route declares none. Warned once per route so an incomplete
* manifest is visible to the operator rather than silently degrading to the global limit.
*/
private readonly warnedMissingCap = new Set<string>();
private fallbackMaxBodyBytes(pluginId: string, route: string): number {
const key = `${pluginId}:${route}`;
if (!this.warnedMissingCap.has(key)) {
this.warnedMissingCap.add(key);
this.logger.warn(
`Ingress route ${key} declares no usable maxBodyBytes; falling back to the process body limit. ` +
'Set a per-route maxBodyBytes in the plugin manifest.',
);
}
return parseBodyLimitBytes(resolveBodyLimit(process.env.BODY_SIZE_LIMIT));
}
async handle(req: IngressRequest): Promise<{ status: number; body?: string; headers?: Record<string, string> }> {
const instance = await this.deps.instances.resolve(req.pluginId, req.instanceId);
if (!instance || !instance.enabled) return { status: 404, body: 'unknown instance' };
const route = this.deps.manifestRoute(req.pluginId, req.route);
if (!route) return { status: 404, body: 'unknown route' };
// GET challenge handshake (e.g. Meta hub.challenge), answered host-side without the worker. The
// token is compared against the instance's minted verifyToken.
if (req.method === 'GET' && route.challenge) {
const token = req.query[route.challenge.tokenParam];
const echo = req.query[route.challenge.echoParam];
// Constant-time compare (mirrors the signature path) so the verify token can't be probed by timing.
if (token && instance.verifyToken && constantTimeEqual(token, instance.verifyToken)) {
return { status: 200, body: echo ?? '' };
}
return { status: 403, body: 'challenge failed' };
}
// Handled as the empty body, it would pass a scheme that signs only a header, and every such delivery
// would hash to one dedup key: the first stored without its body, the rest acked and dropped. It
// would also slip past the size cap below.
if (req.unparsedBody) return { status: 415, body: 'unsupported ingress content type' };
// `n > undefined` is always false, so a manifest that omits maxBodyBytes — or carries a
// non-numeric or non-positive value — left this check inert: the 413 the published contract
// promises never fired, and every accepted delivery is persisted with the body stored twice
// (payload.body and payload.rawBody) and carried into the queue. A third-party adapter forgetting
// one field turned its route into a write amplifier with no load-time error and no runtime signal.
//
// The fallback is the process-wide body limit, which is what such a route was already bounded by
// in practice, so no delivery that is accepted today starts failing. What changes is that the
// check can no longer be vacuous, and the gap is now stated in the log instead of being silent.
// A manifest is third-party JSON with no runtime validation, so the field is only a `number` by
// declaration. The `>` this replaced COERCED, which means a quoted number ("1024") enforced a real
// cap — rejecting it as "unusable" would swap that for the far larger process-wide fallback. And
// 0 is a cap, not a missing value: it admits the empty body a verification callback sends and
// nothing else. Only a value that cannot express a limit at all falls back.
const declaredCap: unknown = route.maxBodyBytes;
const parsedCap =
typeof declaredCap === 'number'
? declaredCap
: typeof declaredCap === 'string' && declaredCap.trim() !== ''
? Number(declaredCap)
: Number.NaN;
const effectiveCap =
Number.isFinite(parsedCap) && parsedCap >= 0 ? parsedCap : this.fallbackMaxBodyBytes(req.pluginId, route.route);
if (Buffer.byteLength(req.rawBody, 'utf8') > effectiveCap) return { status: 413, body: 'payload too large' };
const verdict = verifyIngressSignature(route.signature, {
rawBody: req.rawBody,
headers: req.headers,
secret: instance.secret,
now: this.deps.now(),
instanceId: req.instanceId,
});
if (!verdict.ok) return { status: 401, body: verdict.reason ?? 'signature verification failed' };
// The per-instance bucket is charged here, after verification; everything above is bounded by the
// guard's per-client-IP tier.
// Before the preflight, so a signed provider hammering a dead session is still bounded.
const admission = this.deps.admitInstance ? await this.deps.admitInstance(req.pluginId, req.instanceId) : undefined;
if (admission && !admission.ok) {
return {
status: 429,
// The body the global filter writes for a guard's ThrottlerException, so the wire shape is
// the same one this route answered with before the charge moved here.
body: JSON.stringify({ statusCode: 429, message: throttlerMessage }),
headers: { 'content-type': 'application/json', ...admission.headers },
};
}
// Host-side preflight (e.g. session-alive). AFTER signature verify (so an unauthenticated caller
// cannot probe liveness) and BEFORE the dedup persist (so a 5xx-rejected delivery never writes a
// dedup row that would swallow the provider's retry as a 200 'duplicate' — the dedup trap). A
// rejection leaves no dedup/DLQ row, so log it for operator audit.
// A route that declares a response contract wants its answer now, so a plugin the boot restore has not
// reached yet is refused in the same stage. Any other route is accepted and persisted below like every
// delivery: the queue holds its job until the plugin is up, or the reconciler dispatches the row.
const preflight =
route.response && this.deps.restorePending?.(req.pluginId)
? pluginRestoringRejection()
: evaluatePreflight(route, instance.sessionScope, this.deps.sessionStatus);
if (preflight) {
this.deps.log?.('ingress_preflight_rejected', {
pluginId: req.pluginId,
instanceId: req.instanceId,
route: req.route,
status: preflight.status,
reason: preflight.body,
sessionScope: instance.sessionScope,
});
// Returned whole, so a rejection's headers reach the wire. Re-packing the two fields dropped the
// Retry-After that decides whether the provider retries at all.
return preflight;
}
// Standard Webhooks signs and requires webhook-id, so it is the stable, authenticated retry id.
// Other schemes retain the existing x-delivery/body-hash behavior for compatibility.
const defaultDedupHeader = route.signature.scheme === 'standard-webhooks' ? 'webhook-id' : 'x-delivery';
const dedupHeader = (route.dedupHeader ?? route.signature.dedupHeader ?? defaultDedupHeader).toLowerCase();
// A route that declares dedupOn: 'body' keys retries on the raw body: its provider mints a fresh
// delivery id per attempt, so trusting the header would let every retry through as new.
//
// A header that is present but blank is no id at all, and it used to be taken as one: every
// delivery then shared the empty key, so the dedup row admitted the first and dropped the rest
// while answering each provider with the route's success ack. Nothing was enqueued, nothing was
// dead-lettered, and the deliveries were simply gone. Fall through to the body hash, which is
// exactly the "provider supplied no id" case it already exists for.
const headerId = req.headers[dedupHeader]?.trim();
// An id past 255 characters is no id a provider mints, and the unique index it is stored under refuses an
// entry past about 2.7 KB on PostgreSQL with a 500, so such a header gets the body hash too.
const deliveryId =
route.dedupOn === 'body' || !headerId || headerId.length > MAX_DELIVERY_ID_LENGTH
? deriveDeliveryId(req)
: headerId;
// Provider request headers persist with the event (redrive/debugging); credentials must not.
// Signature headers are re-derivable, auth material is not — redact before the first write.
// A shared-secret route carries the instance secret itself in its declared header, and an hmac
// route's declared header carries a signature that is only useful to re-send the same body.
const payload = {
// Every authenticating scheme has passed by here; a `none` route authenticates nothing. Recorded now
// because a plugin update can change the scheme before a queued or replayed delivery runs.
admission: { verified: route.signature.scheme !== 'none' },
headers: redactSensitiveHeaders(
req.headers,
route.signature.scheme === 'shared-secret' || route.signature.scheme === 'hmac-sha256'
? route.signature.header
: undefined,
),
query: req.query,
body: req.rawBody,
rawBody: req.rawBody,
};
// Rendered BEFORE the dedup check so a provider retry gets the route's ack (same status and headers)
// rather than a second contract on the same route. A body template renders from the retry, not the
// first delivery, and a retry still passes the preflight above first. The ctx is the request in
// hand (rawBody, deliveryId, now), never stored state, which is what makes rendering it on a dedup
// hit sound: an ack field that had to reflect the PERSISTED row would echo the retry's values as the
// original's. Keep it that way.
const rendered = renderAck(route.response?.ack, {
rawBody: req.rawBody,
timestamp: String(Math.floor(this.deps.now() / 1000)),
id: deliveryId,
});
const ack = admission ? { ...rendered, headers: { ...rendered.headers, ...admission.headers } } : rendered;
const isNew = await this.deps.events.recordOrSkip({
instanceId: req.instanceId,
pluginId: req.pluginId,
providerDeliveryId: deliveryId,
route: req.route,
// The method rides with the row so a reconciler replay reaches the handler as this attempt does.
payload: { ...payload, method: req.method },
// The slim content fingerprint kept after the payload is retired on dispatch (see the entity).
payloadHash: createHash('sha256').update(req.rawBody).digest('hex'),
sessionId: instance.sessionScope,
});
if (!isNew) return ack; // already persisted/acked; a retry gets the route's ack, not enqueued again
// Persisted and acked: dispatching it now would run the plugin inline where there is no worker to run it in.
// The row stays 'pending', which is where a crash here would leave it too, and the reconciler dispatches it.
if (this.deps.deferDispatch?.(req.pluginId)) return ack;
// Best-effort conversation id for P1 ordering. Never throws — a malformed body just yields undefined.
const providerConversationId = extractConversationId(route.conversationId, req.headers, req.rawBody);
const jobData: IngressJobData = {
pluginId: req.pluginId,
instanceId: req.instanceId,
route: req.route,
method: req.method,
deliveryId,
sessionId: instance.sessionScope ?? undefined,
providerConversationId,
payload,
};
if (route.response) {
// Sync-response route: the ack is host-side and final; enqueue (queued or inline) must NOT block
// it — a queue-disabled deployment otherwise holds the HTTP response for up to the inline dispatch
// timeout. enqueue() is not awaited; the dedup row already persisted is the durability handle. The
// .catch() is a defensive guard: enqueue() never rejects without a signal (it swallows inline failures
// and the factory wrapper writes a DLQ row on 'failed'), but a future regression must not become an unhandled
// rejection that crashes the process on the ingress hot path.
void this.deps.enqueue(jobData, deliveryId).catch(err => {
this.deps.log?.('ingress_enqueue_unhandled', {
pluginId: req.pluginId,
instanceId: req.instanceId,
deliveryId,
error: err instanceof Error ? err.message : String(err),
});
});
} else {
await this.deps.enqueue(jobData, deliveryId);
}
return ack;
}
}
/** The longest dedup header value taken as a delivery id, kept far below the index entry limit of PostgreSQL. */
const MAX_DELIVERY_ID_LENGTH = 255;
/**
* Derives a DETERMINISTIC delivery id when the provider sends no dedup header, so a provider retry of
* the same delivery dedups instead of being treated as new. A random UUID would silently disable both
* the persist-dedup and BullMQ's jobId idempotency, causing duplicate downstream WhatsApp sends. Keyed
* on pluginId + instanceId + route + rawBody ONLY — never a server timestamp, which would defeat dedup.
*/
function deriveDeliveryId(req: IngressRequest): string {
return createHash('sha256').update([req.pluginId, req.instanceId, req.route, req.rawBody].join('\0')).digest('hex');
}
/**
* Extracts the provider conversation id from a declared header or a JSON pointer into the body.
* Returns undefined when no pointer is declared or extraction fails — the P1 lock then keys per
* instance. Pure and total: never throws on a malformed body.
*/
export function extractConversationId(
spec: { header?: string; jsonPointer?: string } | undefined,
headers: Record<string, string>,
rawBody: string,
): string | undefined {
if (!spec) return undefined;
if (spec.header) {
const v = headers[spec.header.toLowerCase()];
if (v) return v;
}
if (spec.jsonPointer) {
try {
let node: unknown = JSON.parse(rawBody);
// RFC 6901: an empty token is a key, `~1` and `~0` stand for `/` and `~`, and an array takes only an
// index. A pointer written without its leading slash keeps resolving as it did.
const path = spec.jsonPointer.startsWith('/') ? spec.jsonPointer.slice(1) : spec.jsonPointer;
for (const token of path.split('/')) {
if (/~(?:[^01]|$)/.test(token)) return undefined;
const key = token.replace(/~1/g, '/').replace(/~0/g, '~');
if (node === null || typeof node !== 'object' || !Object.hasOwn(node, key)) return undefined;
if (Array.isArray(node) && !/^(0|[1-9][0-9]*)$/.test(key)) return undefined;
node = (node as Record<string, unknown>)[key];
}
// Only a scalar is a usable conversation key — an object/array would stringify to junk.
if (typeof node === 'string') return node;
if (typeof node === 'number' || typeof node === 'boolean') return String(node);
} catch {
return undefined; // malformed body → no key, per-instance ordering
}
}
return undefined;
}
/**
* Header names whose VALUES must never reach the persisted event payload: bearer/basic
* credentials, cookies, and the provider signature headers (recomputable from the raw body, and
* useless for redrive — the retry re-signs). The names survive so operators can still see WHICH
* scheme the provider used.
*/
const SENSITIVE_INGRESS_HEADERS = new Set([
'authorization',
'proxy-authorization',
'cookie',
'x-hub-signature',
'x-hub-signature-256',
'x-signature',
'x-signature-ed25519',
'x-webhook-signature',
'webhook-signature',
]);
export function redactSensitiveHeaders(
headers: Record<string, string>,
credentialHeader?: string,
): Record<string, string> {
const extra = credentialHeader?.toLowerCase();
const out: Record<string, string> = {};
for (const [name, value] of Object.entries(headers)) {
const lower = name.toLowerCase();
out[name] = SENSITIVE_INGRESS_HEADERS.has(lower) || lower === extra ? '[redacted]' : value;
}
return out;
}