Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(hooks): keep a message or payload a hook cannot replace
Yudhi Armyndharis485677e32d91
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.mdindex 8f3b052cb..e528a7a18 100644--- a/docs/19-plugin-architecture.md+++ b/docs/19-plugin-architecture.md@@ -404,7 +404,11 @@ still has its `data` applied.or left, WhatsApp, so the gateway still persists it and still dispatches `message.received` /`message.sent` to webhooks and the websocket. This is the flag an auto-reply plugin uses to claim amessage ("I answered this, don't let another bot answer it too"); it is not a way to hide a message from-the operator's own history.+the operator's own history. For the same reason the gateway only keeps a returned `data` on these two+events while it is still a message (an object with a string `id` and `chatId`): `data: null`, a+primitive or `{}` is logged and skipped, and the chain carries on with the last message it held, so an+earlier handler's rewrite (a redaction) still applies. `webhook:before` treats a result without a+plain-object `payload` the same way.On a **pre-action** event it is a veto, because the action has not been taken yet: `false` on`message:sending` blocks the send (the caller gets a `400`), and on `webhook:before` it cancels that onediff --git a/src/core/hooks/hook-manager.service.spec.ts b/src/core/hooks/hook-manager.service.spec.tsindex d6eb8c952..068dadb41 100644--- a/src/core/hooks/hook-manager.service.spec.ts+++ b/src/core/hooks/hook-manager.service.spec.ts@@ -125,6 +125,34 @@ describe('HookManager', () => {expect(res.data).toBe('original'); // but the errored mutation is not carried out on stop});+ it('skips a result the caller cannot use, keeping an earlier handler rewrite', async () => {+ const isMessage = (d: unknown) => typeof d === 'object' && d !== null && 'id' in d;+ hm.register(+ 'redact',+ 'message:received',+ async ctx => ({+ continue: true,+ data: { ...(ctx.data as object), body: '[redacted]' },+ }),+ 10,+ );+ hm.register('bot', 'message:received', async () => ({ continue: true, data: null }), 100);++ const guarded = await hm.execute<unknown>(+ 'message:received',+ { id: 'm1', body: 'secret' },+ {+ source: 'test',+ accept: isMessage,+ },+ );+ expect(guarded.data).toEqual({ id: 'm1', body: '[redacted]' });++ // Without `accept` any defined data is adopted, as before.+ const unguarded = await hm.execute<unknown>('message:received', { id: 'm1', body: 'secret' }, { source: 'test' });+ expect(unguarded.data).toBeNull();+ });+it('register/unregister/hasHooks/getHookCount track registrations', () => {expect(hm.hasHooks('session:created')).toBe(false);const id = hm.register('p', 'session:created', async ctx => ({ continue: true, data: ctx.data }));diff --git a/src/core/hooks/hook-manager.service.ts b/src/core/hooks/hook-manager.service.tsindex 31d2870a6..04b9cd0c8 100644--- a/src/core/hooks/hook-manager.service.ts+++ b/src/core/hooks/hook-manager.service.ts@@ -12,6 +12,13 @@ export function normalizeHookPriority(priority: unknown): number {return typeof priority === 'number' && Number.isFinite(priority) ? priority : 100;}+export interface HookExecuteOptions<T> {+ sessionId?: string;+ source: string;+ /** Adopt a handler's `data` only when this returns true; a rejected result is skipped, not applied. */+ accept?: (data: T) => boolean;+}+@Injectable()export class HookManager {private readonly logger = new Logger(HookManager.name);@@ -108,11 +115,7 @@ export class HookManager {* Execute hooks for an event* Returns: { continue: boolean, data: T }*/- async execute<T>(- event: HookEvent,- data: T,- options: { sessionId?: string; source: string },- ): Promise<{ continue: boolean; data: T }> {+ async execute<T>(event: HookEvent, data: T, options: HookExecuteOptions<T>): Promise<{ continue: boolean; data: T }> {const inFlight = this.inFlightEvents.getStore();if (inFlight?.has(event)) {this.logger.warn(@@ -157,7 +160,7 @@ export class HookManager {private async runHandlers<T>(event: HookEvent,data: T,- options: { sessionId?: string; source: string },+ options: HookExecuteOptions<T>,): Promise<{ continue: boolean; data: T }> {// A snapshot: a registration added or moved while this chain awaits a handler (a sandboxed plugin// re-subscribing at a lower priority) must not make the loop skip or repeat one.@@ -183,8 +186,16 @@ export class HookManager {// A handler that reports an error discards its output: do NOT apply its (possibly partial or// corrupted) data mutation, even though HookResult allows returning data and error together.+ // A result the caller cannot use is dropped the same way, so the chain keeps the last usable+ // value (an earlier handler's redaction included) instead of the caller falling back to the input.if (result.error === undefined && result.data !== undefined) {- currentData = result.data as T;+ if (options.accept && !options.accept(result.data as T)) {+ this.logger.warn(+ `Hook result from ${registration.pluginId} for ${event} is not usable; keeping the previous data`,+ );+ } else {+ currentData = result.data as T;+ }}if (!result.continue) {diff --git a/src/core/hooks/hook-results.ts b/src/core/hooks/hook-results.tsnew file mode 100644index 000000000..77998536c--- /dev/null+++ b/src/core/hooks/hook-results.ts@@ -0,0 +1,25 @@+import type { HookEvent } from './hook.interfaces';++const isPlainObject = (value: unknown): boolean => typeof value === 'object' && value !== null && !Array.isArray(value);++/** A message:received / message:sent result the projector can store and dispatch: it keeps `id` and `chatId`. */+export function isMessagePayload(data: unknown): boolean {+ const candidate = data as { id?: unknown; chatId?: unknown } | null;+ return isPlainObject(candidate) && typeof candidate!.id === 'string' && typeof candidate!.chatId === 'string';+}++/** A webhook:before result whose `payload` can replace the one being sent. */+export function isWebhookBeforeResult(data: unknown): boolean {+ return isPlainObject(data) && isPlainObject((data as { payload?: unknown }).payload);+}++/**+ * The handler results each event can use. A chain skips a result that fails its check and keeps the+ * last usable value, so an earlier handler's rewrite (a redaction) survives a later handler returning+ * `null`: HookManager applies it between plugins, the sandbox worker between one plugin's handlers.+ */+export const HOOK_RESULT_ACCEPT: Partial<Record<HookEvent, (data: unknown) => boolean>> = {+ 'message:received': isMessagePayload,+ 'message:sent': isMessagePayload,+ 'webhook:before': isWebhookBeforeResult,+};diff --git a/src/core/plugins/sandbox/worker-hooks.spec.ts b/src/core/plugins/sandbox/worker-hooks.spec.tsindex b7c735139..5d66d6de5 100644--- a/src/core/plugins/sandbox/worker-hooks.spec.ts+++ b/src/core/plugins/sandbox/worker-hooks.spec.ts@@ -78,6 +78,22 @@ describe('WorkerHookRegistry', () => {expect(sent.find(m => m.kind === 'hook-result')).toMatchObject({ continue: false, data: { n: 2 } });});+ it('skips a later handler result the event cannot use, keeping an earlier rewrite', async () => {+ const { sent, post } = collect();+ const reg = new WorkerHookRegistry(post);+ reg.register(+ 'message:received',+ ctx => Promise.resolve({ continue: true, data: { ...(ctx.data as object), body: '[redacted]' } }),+ 10,+ );+ reg.register('message:received', () => Promise.resolve({ continue: true, data: null }), 100);++ const message = { id: 'm1', chatId: '[email protected]', body: 'secret' };+ await reg.handleHook({ kind: 'hook', id: 5, event: 'message:received', data: message, source: 'Engine' });++ expect(sent.find(m => m.kind === 'hook-result')).toMatchObject({ data: { ...message, body: '[redacted]' } });+ });+it('a throwing handler does not break the chain', async () => {const { sent, post } = collect();const reg = new WorkerHookRegistry(post);diff --git a/src/core/plugins/sandbox/worker-hooks.ts b/src/core/plugins/sandbox/worker-hooks.tsindex a2f451cac..29494cdc4 100644--- a/src/core/plugins/sandbox/worker-hooks.ts+++ b/src/core/plugins/sandbox/worker-hooks.ts@@ -1,5 +1,7 @@import { AsyncLocalStorage } from 'async_hooks';import { WorkerToHostMessage, HostToWorkerMessage } from './protocol';+import { HOOK_RESULT_ACCEPT } from '../../hooks/hook-results';+import type { HookEvent } from '../../hooks/hook.interfaces';/*** Carries the per-session-resolved config for the duration of a hook dispatch so ctx.config (a getter@@ -76,6 +78,9 @@ export class WorkerHookRegistry {private async dispatch(message: Extract<HostToWorkerMessage, { kind: 'hook' }>): Promise<void> {const list = this.handlers.get(message.event) ?? [];+ // Guard only a chain that starts from a usable value: there is nothing to keep otherwise.+ const check = HOOK_RESULT_ACCEPT[message.event as HookEvent];+ const accept = check?.(message.data) ? check : undefined;let data = message.data;let shouldContinue = true;let firstError: string | undefined;@@ -88,7 +93,9 @@ export class WorkerHookRegistry {source: message.source,timestamp: new Date(),});- if (result.data !== undefined) data = result.data;+ // Same rule as the host chain: a result the event cannot use is skipped, so an earlier handler's+ // rewrite (a redaction) survives a later handler of this plugin returning null.+ if (result.data !== undefined && (accept?.(result.data) ?? true)) data = result.data;if (!result.continue) {shouldContinue = false;break;diff --git a/src/modules/session/message-projector.service.spec.ts b/src/modules/session/message-projector.service.spec.tsindex c6df7dbc4..03d037445 100644--- a/src/modules/session/message-projector.service.spec.ts+++ b/src/modules/session/message-projector.service.spec.ts@@ -290,7 +290,12 @@ describe('MessageProjector (inbound projection)', () => {let engines: EngineRegistry;let messageRepository: { create: jest.Mock; insert: jest.Mock; findOne: jest.Mock; update: jest.Mock };let sessionRepository: { update: jest.Mock; findOne: jest.Mock };- let eventsGateway: { emitMessage: jest.Mock; emitMessageAck: jest.Mock; emitMessageRevoked: jest.Mock };+ let eventsGateway: {+ emitMessage: jest.Mock;+ emitMessageSent: jest.Mock;+ emitMessageAck: jest.Mock;+ emitMessageRevoked: jest.Mock;+ };let webhookService: { dispatch: jest.Mock };let hookManager: { execute: jest.Mock };let statusStore: { ingest: jest.Mock };@@ -325,7 +330,12 @@ describe('MessageProjector (inbound projection)', () => {update: jest.fn().mockResolvedValue(undefined),};sessionRepository = { update: jest.fn().mockResolvedValue(undefined), findOne: jest.fn().mockResolvedValue(null) };- eventsGateway = { emitMessage: jest.fn(), emitMessageAck: jest.fn(), emitMessageRevoked: jest.fn() };+ eventsGateway = {+ emitMessage: jest.fn(),+ emitMessageSent: jest.fn(),+ emitMessageAck: jest.fn(),+ emitMessageRevoked: jest.fn(),+ };webhookService = { dispatch: jest.fn() };// Mirrors the real HookManager contract (hook-manager.service.ts `execute`/`runHandlers`): resolves// `{ continue, data }`, passing `data` through unchanged when no hooks are registered — exactly@@ -429,6 +439,55 @@ describe('MessageProjector (inbound projection)', () => {);});+ // HookManager threads any defined `data`, so a handler returning `data: null` ("I consumed it")+ // or an object that is not a message reaches the projector. It must still record and dispatch+ // the engine's message, not throw and erase it.+ it.each([+ ['null', null],+ ['a primitive', 'consumed'],+ ['an object without the message identity', {}],+ ])('still persists and dispatches the message when a hook returns %s', async (_label, data) => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);+ hookManager.execute.mockResolvedValueOnce({ continue: true, data });+ const incoming = makeIncoming();++ projector.handleInboundMessage(SESSION_ID, engine, incoming);+ await new Promise(resolve => setImmediate(resolve));++ expect(messageRepository.create).toHaveBeenCalledWith(+ expect.objectContaining({ waMessageId: incoming.id, chatId: incoming.chatId }),+ );+ expect(webhookService.dispatch).toHaveBeenCalledWith(SESSION_ID, 'message.received', incoming);+ expect(eventsGateway.emitMessage).toHaveBeenCalledWith(SESSION_ID, incoming);+ });++ it('lets HookManager skip a handler result that is not a message', async () => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);++ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming());+ await new Promise(resolve => setImmediate(resolve));++ const [, , options] = hookManager.execute.mock.calls[0] as [string, unknown, { accept: (d: unknown) => boolean }];+ expect(options.accept(null)).toBe(false);+ expect(options.accept('consumed')).toBe(false);+ expect(options.accept({})).toBe(false);+ expect(options.accept({ id: 'm', chatId: '[email protected]' })).toBe(true);+ });++ it('keeps a rewritten message a hook returns', async () => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);+ const rewritten = { ...makeIncoming(), body: '[redacted]' };+ hookManager.execute.mockResolvedValueOnce({ continue: true, data: rewritten });++ projector.handleInboundMessage(SESSION_ID, engine, makeIncoming());+ await new Promise(resolve => setImmediate(resolve));++ expect(webhookService.dispatch).toHaveBeenCalledWith(SESSION_ID, 'message.received', rewritten);+ });+it('routes a status broadcast to the status store instead of the message table', async () => {const engine = makeEngine();engines.set(SESSION_ID, engine);@@ -511,4 +570,22 @@ describe('MessageProjector (inbound projection)', () => {});});});++ describe('handleOwnSendEcho', () => {+ it('still persists and dispatches the send when a message:sent hook returns null', async () => {+ const engine = makeEngine();+ engines.set(SESSION_ID, engine);+ hookManager.execute.mockResolvedValueOnce({ continue: true, data: null });+ const sent = makeIncoming({ fromMe: true, to: '[email protected]' });++ projector.handleOwnSendEcho(SESSION_ID, engine, sent);+ await new Promise(resolve => setImmediate(resolve));++ expect(messageRepository.create).toHaveBeenCalledWith(+ expect.objectContaining({ waMessageId: sent.id, chatId: sent.chatId }),+ );+ expect(webhookService.dispatch).toHaveBeenCalledWith(SESSION_ID, 'message.sent', sent);+ expect(eventsGateway.emitMessageSent).toHaveBeenCalledWith(SESSION_ID, sent);+ });+ });});diff --git a/src/modules/session/message-projector.service.ts b/src/modules/session/message-projector.service.tsindex 1c85d473a..27eafbbc9 100644--- a/src/modules/session/message-projector.service.ts+++ b/src/modules/session/message-projector.service.ts@@ -35,6 +35,7 @@ import {deliveryStatusToAck,ackStatusTransitionFrom,} from '../message/message-status.util';+import { isMessagePayload } from '../../core/hooks/hook-results';/*** Projects engine message events into the `messages` table and out to webhooks/WebSocket.@@ -143,11 +144,42 @@ export class MessageProjector {.execute('message:received', messageData, {sessionId: id,source: 'Engine',+ accept: isMessagePayload,})- .then(({ data: finalMessage }) => this.projectInboundMessage(id, engine, finalMessage))+ .then(({ data }) =>+ this.projectInboundMessage(id, engine, this.messageOrEngineCopy(id, 'message:received', data, message)),+ ).catch(err => this.logger.error(`onMessage handler failed for ${id}`, String(err)));}+ /**+ * The message a `message:received` / `message:sent` hook chain handed back, or a fresh copy of the+ * engine's message when it is not one: null, a primitive, or an object without the `id` and `chatId`+ * every row and dispatch keys on. HookManager already skips such a result per handler+ * ({@link isMessagePayload}), keeping an earlier handler's rewrite; this is the last guard. A plugin+ * returning `data: null` to mean "I consumed it" used to throw below and erase the message from+ * history, webhooks and the websocket. A plugin may rewrite a message; it cannot make the gateway+ * forget it (see projectInboundMessage).+ */+ private messageOrEngineCopy(+ id: string,+ event: 'message:received' | 'message:sent',+ data: unknown,+ message: IncomingMessage,+ ): InboundMessageData {+ const candidate = data as Partial<IncomingMessage> | null;+ if (isMessagePayload(candidate)) {+ return candidate as InboundMessageData;+ }+ this.logger.warn(`A ${event} hook returned a payload that is not a message; using the engine's copy`, {+ sessionId: id,+ messageId: message.id,+ received: candidate === null ? 'null' : typeof candidate,+ action: 'hook_message_discarded',+ });+ return { ...message };+ }+/** `isStatusBroadcast` arm of {@link handleInboundMessage}: ingest into the status store, not the message pipeline. */private ingestInboundStatus(id: string, engine: IWhatsAppEngine, message: IncomingMessage): void {// Status/Story posts arrive via the inbound path for some engines; ingest them into the@@ -371,8 +403,10 @@ export class MessageProjector {.execute('message:sent', messageData, {sessionId: id,source: 'Engine',+ accept: isMessagePayload,})- .then(async ({ data: finalMessage }) => {+ .then(async ({ data }) => {+ const finalMessage = this.messageOrEngineCopy(id, 'message:sent', data, message);// `continue: false` is not read here, for the same reason as the message:received path// above: the send has already happened, so a plugin can stop the handler chain but cannot// un-send it. Skipping the persist below dropped the operator's own outgoing message fromdiff --git a/src/modules/webhook/webhook-delivery.service.spec.ts b/src/modules/webhook/webhook-delivery.service.spec.tsindex de7a53655..7476fca06 100644--- a/src/modules/webhook/webhook-delivery.service.spec.ts+++ b/src/modules/webhook/webhook-delivery.service.spec.ts@@ -515,6 +515,56 @@ describe('WebhookDeliveryService', () => {expect(headers['X-OpenWA-Signature']).toBe(expected);});+ it.each([+ ['a string', 'rewritten'],+ ['a number', 42],+ ['an array', [1, 2]],+ ])(+ 'sends the original payload when a webhook:before hook returns %s as the payload',+ async (_label, hookPayload) => {+ const webhook = createMockWebhook({ events: ['message.received'] });+ (repository.find as jest.Mock).mockResolvedValue([webhook]);+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });+ (hookManager.execute as jest.Mock).mockImplementation((event: string) =>+ Promise.resolve({ continue: true, data: event === 'webhook:before' ? { payload: hookPayload } : {} }),+ );++ await service.dispatch('sess-1', 'message.received', { from: '[email protected]' });++ expect(mockFetch).toHaveBeenCalledTimes(1);+ const call = mockFetch.mock.calls[0] as [unknown, { headers: Record<string, string>; body: string }];+ const body = JSON.parse(call[1].body) as WebhookPayload;+ expect(body.event).toBe('message.received');+ expect(body.sessionId).toBe('sess-1');+ expect(body.data).toEqual({ from: '[email protected]' });+ expect(body.idempotencyKey).toBe(call[1].headers['X-OpenWA-Idempotency-Key']);+ expect(failureRepository.insert).not.toHaveBeenCalled();+ },+ );++ it('lets HookManager skip a webhook:before result without a plain-object payload', async () => {+ const webhook = createMockWebhook({ events: ['message.received'] });+ (repository.find as jest.Mock).mockResolvedValue([webhook]);+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });+ (hookManager.execute as jest.Mock).mockImplementation((_event: string, data: unknown) =>+ Promise.resolve({ continue: true, data }),+ );++ await service.dispatch('sess-1', 'message.received', { from: '[email protected]' });++ const call = (hookManager.execute as jest.Mock).mock.calls.find(([event]) => event === 'webhook:before') as [+ string,+ unknown,+ { accept: (d: unknown) => boolean },+ ];+ const { accept } = call[2];+ expect(accept(null)).toBe(false);+ expect(accept({})).toBe(false);+ expect(accept({ payload: 'rewritten' })).toBe(false);+ expect(accept({ payload: [1] })).toBe(false);+ expect(accept({ payload: { event: 'message.received' } })).toBe(true);+ });+it('records (never sends) a hook-mutated payload that exceeds the payload size cap', async () => {(configService.get as jest.Mock).mockImplementation(<T>(key: string, def?: T): T | boolean | number => {if (key === 'queue.enabled') return false;diff --git a/src/modules/webhook/webhook-delivery.service.ts b/src/modules/webhook/webhook-delivery.service.tsindex 80e15d388..f93ea4620 100644--- a/src/modules/webhook/webhook-delivery.service.ts+++ b/src/modules/webhook/webhook-delivery.service.ts@@ -26,6 +26,7 @@ import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.import { redactSsrfError } from '../../common/security/ssrf-guard';import { HookManager } from '../../core/hooks';import { ConcurrencyLimiter } from '../../common/utils/concurrency-limiter';+import { isWebhookBeforeResult } from '../../core/hooks/hook-results';export interface WebhookPayload {event: string;@@ -86,6 +87,8 @@ interface DispatchEventContext {* Records terminally failed deliveries in webhook_delivery_failures. Webhook registration/CRUD* lives on WebhookService, which delegates dispatch here.*/+const isPlainObject = (value: unknown): boolean => typeof value === 'object' && value !== null && !Array.isArray(value);+@Injectable()export class WebhookDeliveryService implements OnModuleInit, OnModuleDestroy {private readonly logger = createLogger('WebhookDelivery');@@ -330,10 +333,16 @@ export class WebhookDeliveryService implements OnModuleInit, OnModuleDestroy {// place, so reading the canonical timestamp off the hook result afterwards is not safe.const payloadTimestamp = payload.timestamp;+ // A handler result without a plain-object payload is skipped, so the chain keeps the last usable+ // payload (an earlier hook's redaction included) rather than the one it started from.const { continue: shouldContinue, data: hookResult } = await this.hookManager.execute('webhook:before',{ sessionId, event, payload },- { sessionId, source: 'WebhookService' },+ {+ sessionId,+ source: 'WebhookService',+ accept: isWebhookBeforeResult,+ },);if (!shouldContinue) {@@ -344,8 +353,20 @@ export class WebhookDeliveryService implements OnModuleInit, OnModuleDestroy {return 'cancelled';}- // Null/undefined hook results mean "no override", matching an object without payload.- const finalPayload = (hookResult as { payload?: WebhookPayload } | null | undefined)?.payload ?? payload;+ // Null/undefined hook results mean "no override", matching an object without payload. A+ // payload that is not a plain object (a primitive, which throws on the writes below, or an+ // array, which drops them from the JSON) is not one either: send the original and say so.+ const hookPayload = (hookResult as { payload?: unknown } | null | undefined)?.payload ?? payload;+ const usable = isPlainObject(hookPayload);+ if (!usable) {+ this.logger.warn('A webhook:before hook returned a payload that is not an object; sending the original', {+ webhookId: webhook.id,+ event,+ received: Array.isArray(hookPayload) ? 'array' : typeof hookPayload,+ action: 'hook_payload_discarded',+ });+ }+ const finalPayload = usable ? (hookPayload as WebhookPayload) : payload;// Re-assert EVERY identity field after the (untrusted) hook chain. A hook may rewrite data,// but event/sessionId/timestamp and the dedupe ids must remain the server's values: the// receiver verifies the signature over this body and compares it against the X-OpenWA-*