Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(plugins): scope the sandbox re-entrancy guard to the hook chain
Yudhi Armyndharisac58ad509389
diff --git a/src/core/hooks/hook-manager.service.spec.ts b/src/core/hooks/hook-manager.service.spec.tsindex 3d6fc2781..d750c7515 100644--- a/src/core/hooks/hook-manager.service.spec.ts+++ b/src/core/hooks/hook-manager.service.spec.ts@@ -202,6 +202,18 @@ describe('HookManager.isInFlight + selective re-entrancy guard (conversation.senexpect(unrelated).toBe(false);});+ it('currentInFlight reports the whole chain a handler runs under (what a sandbox dispatch forwards)', async () => {+ const hm = new HookManager();+ let seen: HookEvent[] = [];+ hm.register('p', 'message:sent', async () => {+ seen = hm.currentInFlight();+ return { continue: true };+ });+ expect(hm.currentInFlight()).toEqual([]);+ await hm.runInFlight(SENDING, () => hm.execute('message:sent', {}, { source: 't' }));+ expect(seen).toEqual(['message:sending', 'message:sent']);+ });+it('a top-level guarded send still fires message:sending for unrelated observers; genuine re-entrancy suppresses it', async () => {const hm = new HookManager();let observerCalls = 0;diff --git a/src/core/hooks/hook-manager.service.ts b/src/core/hooks/hook-manager.service.tsindex cbba9360e..501d2018d 100644--- a/src/core/hooks/hook-manager.service.ts+++ b/src/core/hooks/hook-manager.service.ts@@ -126,6 +126,13 @@ export class HookManager {return this.inFlightEvents.getStore()?.has(event) ?? false;}+ /** Every event in flight on the active async context, for a caller that must carry the chain across a+ * boundary AsyncLocalStorage does not span (the sandbox worker IPC) and re-establish it with+ * {@link runInFlight} on the way back. */+ currentInFlight(): HookEvent[] {+ return [...(this.inFlightEvents.getStore() ?? [])];+ }+private async runHandlers<T>(event: HookEvent,data: T,diff --git a/src/core/plugins/plugin-loader-sandbox-routing.spec.ts b/src/core/plugins/plugin-loader-sandbox-routing.spec.tsindex 34ea14474..b8bc267c8 100644--- a/src/core/plugins/plugin-loader-sandbox-routing.spec.ts+++ b/src/core/plugins/plugin-loader-sandbox-routing.spec.ts@@ -163,6 +163,22 @@ describe('PluginLoaderService — sandbox tier routing', () => {expect(registerSpy.mock.calls.filter(c => c[1] === 'message:received')).toHaveLength(1);});+ it('forwards the host in-flight chain to the worker with each dispatch', async () => {+ const loader = makeLoader();+ seed(loader, { builtIn: false, instance: null });+ const hookManager = (loader as unknown as { hookManager: HookManager }).hookManager;+ await loader.enablePlugin('p1');+ loader.capturedOnHookSubscribe!('message:sent');++ await hookManager.runInFlight(['message:sending'], () =>+ hookManager.execute('message:sent', {}, { sessionId: 's1', source: 't' }),+ );++ expect(loader.hosts[0].dispatchHook).toHaveBeenCalledWith(+ expect.objectContaining({ event: 'message:sent', inFlight: ['message:sending', 'message:sent'] }),+ );+ });+it('enables a built-in plugin in-process (no sandbox worker spawned)', async () => {const loader = makeLoader();const onEnable = jest.fn().mockResolvedValue(undefined);diff --git a/src/core/plugins/plugin-sandbox-bridge.ts b/src/core/plugins/plugin-sandbox-bridge.tsindex b7f065604..04f66b973 100644--- a/src/core/plugins/plugin-sandbox-bridge.ts+++ b/src/core/plugins/plugin-sandbox-bridge.ts@@ -475,6 +475,9 @@ export class PluginSandboxBridge {hookCtx.sessionId,plugin.manifest.sessionScoped !== false,),+ // The chain this dispatch belongs to, so a capability the handler calls is guarded+ // against re-firing any event of it (not only this one) once it returns to the host.+ inFlight: this.hookManager.currentInFlight(),timeoutMs: SANDBOX_HOOK_TIMEOUT_MS,onTimeout: () =>this.logger.warn(`Sandboxed plugin ${pluginId} hook '${event}' timed out`, {diff --git a/src/core/plugins/sandbox/plugin-worker-host.spec.ts b/src/core/plugins/sandbox/plugin-worker-host.spec.tsindex 34ec90069..3f5c1b6d5 100644--- a/src/core/plugins/sandbox/plugin-worker-host.spec.ts+++ b/src/core/plugins/sandbox/plugin-worker-host.spec.ts@@ -723,9 +723,17 @@ describe('PluginWorkerHost', () => {const firstHooks = ch.sent.filter(m => m.kind === 'hook');expect(firstHooks).toHaveLength(1);const hookId = firstHooks[0].id;+ expect(firstHooks[0].inFlight).toEqual(['message:sending']);- // The worker, mid-handler, issues a capability that re-fires message:sending on the host.- ch.reply({ kind: 'cap', id: 99, verb: 'messages.sendText', args: ['s1', 'c1', 'hi'] });+ // The worker, mid-handler, issues a capability that re-fires message:sending on the host. A call+ // made inside a hook handler echoes that dispatch's chain (WorkerCapabilityClient does this).+ ch.reply({+ kind: 'cap',+ id: 99,+ verb: 'messages.sendText',+ args: ['s1', 'c1', 'hi'],+ inFlight: firstHooks[0].inFlight,+ });await flush();await flush();@@ -738,6 +746,78 @@ describe('PluginWorkerHost', () => {});});+ describe('hook re-entrancy guard is scoped to the causal chain, not the worker', () => {+ const flush = (): Promise<void> => new Promise(resolve => setImmediate(resolve));+ const SENDING = 'message:sending' as HookEvent;++ // A worker with a message:sending dispatch still pending, plus an in-process moderation hook that+ // vetoes every send. The cap dispatcher reports what the veto chain decided for its send.+ const setup = (pendingEvent = 'message:sending') => {+ const hm = new HookManager();+ const ch = new FakeChannel();+ hm.register('moderation', SENDING, () => Promise.resolve({ continue: false }));+ const capDispatcher = async (): Promise<unknown> => (await hm.execute(SENDING, {}, { source: 'cap' })).continue;+ const host = new PluginWorkerHost(ch, capDispatcher, undefined, undefined, undefined, (events, run) =>+ hm.runInFlight(events as HookEvent[], run),+ );+ void host.dispatchHook({ event: pendingEvent, data: {}, source: 'test', timeoutMs: 60_000 });+ const result = async (id: number): Promise<unknown> => {+ await flush();+ await flush();+ const reply = ch.sent.find(m => m.kind === 'cap-result' && m.id === id);+ return reply && reply.kind === 'cap-result' && reply.ok ? reply.result : reply;+ };+ return { ch, result };+ };++ it('a capability call outside any hook handler still runs every message:sending veto', async () => {+ const { ch, result } = setup();+ // e.g. an ingress handler sending while the worker's own message:sending hook is pending.+ ch.reply({ kind: 'cap', id: 1, verb: 'messages.sendText', args: [] });+ await expect(result(1)).resolves.toBe(false); // vetoed, not short-circuited to continue:true+ ch.crash(); // drains the pending dispatch and its timer+ });++ it('a capability call carrying the pending dispatch chain is still short-circuited', async () => {+ const { ch, result } = setup();+ ch.reply({ kind: 'cap', id: 2, verb: 'messages.sendText', args: [], inFlight: ['message:sending'] });+ await expect(result(2)).resolves.toBe(true);+ ch.crash(); // drains the pending dispatch and its timer+ });++ it('ignores a claimed event the host never dispatched to this worker', async () => {+ // Only message:sent is pending; the worker claims message:sending, the chain the send would skip.+ const { ch, result } = setup('message:sent');+ ch.reply({ kind: 'cap', id: 3, verb: 'messages.sendText', args: [], inFlight: ['message:sending'] });+ await expect(result(3)).resolves.toBe(false);+ ch.crash(); // drains the pending dispatch and its timer+ });++ it('forwards the host ancestor chain on the hook message and honours it on the way back', async () => {+ const hm = new HookManager();+ const ch = new FakeChannel();+ hm.register('moderation', SENDING, () => Promise.resolve({ continue: false }));+ const capDispatcher = async (): Promise<unknown> => (await hm.execute(SENDING, {}, { source: 'cap' })).continue;+ const host = new PluginWorkerHost(ch, capDispatcher, undefined, undefined, undefined, (events, run) =>+ hm.runInFlight(events as HookEvent[], run),+ );+ void host.dispatchHook({+ event: 'message:sent',+ data: {},+ source: 'test',+ inFlight: ['message:sending', 'message:sent'],+ timeoutMs: 60_000,+ });+ const hook = ch.sent.find(m => m.kind === 'hook');+ expect(hook && hook.kind === 'hook' && hook.inFlight).toEqual(['message:sending', 'message:sent']);+ ch.reply({ kind: 'cap', id: 4, verb: 'messages.sendText', args: [], inFlight: ['message:sending'] });+ await flush();+ await flush();+ expect(ch.sent).toContainEqual({ kind: 'cap-result', id: 4, ok: true, result: true });+ ch.crash(); // drains the pending dispatch and its timer+ });+ });+describe('post-crash dead-check (fail-fast, no stall)', () => {it('dispatchHook resolves {continue:true} immediately when the worker is already dead', async () => {jest.useFakeTimers();diff --git a/src/core/plugins/sandbox/plugin-worker-host.ts b/src/core/plugins/sandbox/plugin-worker-host.tsindex eab13299f..0e1708ff8 100644--- a/src/core/plugins/sandbox/plugin-worker-host.ts+++ b/src/core/plugins/sandbox/plugin-worker-host.ts@@ -73,10 +73,10 @@ export class PluginWorkerHost {timer: ReturnType<typeof setTimeout>;}>();- // Hook events currently dispatched to the worker and not yet settled, as a multiset. While the- // worker handles a hook it may issue capability calls that round-trip to the host; those run inside- // this in-flight set so a capability that re-fires the same event is short-circuited (HookManager's- // AsyncLocalStorage re-entrancy guard does not span the worker IPC boundary).+ // Hook events (each dispatch's event plus its host-side ancestors) currently dispatched to the worker+ // and not yet settled, as a multiset. A capability call names the chain of the dispatch it came from;+ // this set bounds that claim, so a worker can never mark an event in flight that the host did not+ // actually dispatch to it (HookManager's AsyncLocalStorage guard does not span the IPC boundary).private readonly inFlightHookEvents = new Map<string, number>();// Worker-initiated capability calls currently running host-side, bounded by maxInFlightCaps.@@ -148,6 +148,9 @@ export class PluginWorkerHost {source: string;sessionId?: string;config?: Record<string, unknown>;+ // Events already in flight on the host's hook chain when this dispatch fires (the caller's+ // ancestors); forwarded so a capability call the handler makes is guarded against all of them.+ inFlight?: string[];timeoutMs: number;onTimeout?: () => void;}): Promise<{ continue: boolean; data?: unknown; error?: string }> {@@ -157,12 +160,13 @@ export class PluginWorkerHost {// crash-drain already produce.if (this.dead) return Promise.resolve({ continue: true });const id = this.nextId++;- this.incInFlightHook(options.event);+ const inFlight = [...new Set([...(options.inFlight ?? []), options.event])];+ for (const event of inFlight) this.incInFlightHook(event);return new Promise(resolve => {- // settle decrements the in-flight counter on every exit path (worker result, timeout, or crash+ // settle decrements the in-flight counters on every exit path (worker result, timeout, or crash// drain) since it is what the hookPending entry's resolve runs.const settle = (result: { continue: boolean; data?: unknown; error?: string }): void => {- this.decInFlightHook(options.event);+ for (const event of inFlight) this.decInFlightHook(event);resolve(result);};const timer = setTimeout(() => {@@ -179,6 +183,7 @@ export class PluginWorkerHost {sessionId: options.sessionId,source: options.source,config: options.config,+ inFlight,});});}@@ -436,10 +441,16 @@ export class PluginWorkerHost {try {const dispatcher = this.capDispatcher;const run = (): Promise<unknown> => dispatcher(message.verb, message.args);- // Run inside the in-flight hook context so a capability that re-fires an event this worker is- // currently handling is short-circuited by HookManager's re-entrancy guard (which otherwise- // can't see across the IPC boundary). No hooks in flight => run directly, no wrapping cost.- const inFlight = [...this.inFlightHookEvents.keys()];+ // Run inside the in-flight hook context of the dispatch whose handler issued this call, so a+ // capability that re-fires that event is short-circuited by HookManager's re-entrancy guard+ // (which otherwise can't see across the IPC boundary). Only that causal chain is guarded: a call+ // from an ingress handler or a timer carries none, and must still run every plugin's hooks+ // (a moderation veto on message:sending included) even while another dispatch is pending. The+ // worker's claim is untrusted, so only events this host has dispatched to it and not yet settled+ // are honoured. A worker can still echo a pending event from outside that handler, but that grants+ // nothing a genuinely re-entrant call from inside the pending handler would not.+ const claimed: unknown[] = Array.isArray(message.inFlight) ? message.inFlight : [];+ const inFlight = claimed.filter((e): e is string => typeof e === 'string' && this.inFlightHookEvents.has(e));const work = this.runWithHookGuard && inFlight.length > 0 ? this.runWithHookGuard(inFlight, run) : run();const result = await this.withCapTimeout(message.verb, work);this.channel.postMessage({ kind: 'cap-result', id: message.id, ok: true, result });diff --git a/src/core/plugins/sandbox/protocol.ts b/src/core/plugins/sandbox/protocol.tsindex 673639735..78f82a185 100644--- a/src/core/plugins/sandbox/protocol.ts+++ b/src/core/plugins/sandbox/protocol.ts@@ -38,6 +38,10 @@ export type HostToWorkerMessage =sessionId?: string;source: string;config?: Record<string, unknown>;+ // The host's in-flight hook chain for this dispatch (this event plus any ancestor event whose+ // handler led to it). The worker echoes it on every capability call the handler makes, so the+ // host re-establishes the re-entrancy guard for that causal chain only.+ inFlight?: string[];}// The plugin's config was updated: refresh ctx.config and invoke onConfigChange (fire-and-forget).| { kind: 'config-change'; config: Record<string, unknown> }@@ -77,7 +81,9 @@ export type WorkerToHostMessage =| { kind: 'lifecycle-result'; id: number; ok: false; error: string }// Worker-initiated capability call (ctx.messages.* / ctx.engine.* / ctx.storage.*). The host// validates it (permission + session scope) before running the real verb and replying.- | { kind: 'cap'; id: number; verb: string; args: unknown[] }+ // `inFlight` is the chain of the hook dispatch whose handler issued the call (absent outside a hook,+ // e.g. an ingress handler or a timer); the host trusts only events it actually dispatched.+ | { kind: 'cap'; id: number; verb: string; args: unknown[]; inFlight?: string[] }// The worker asks the host to dispatch `event` to it (registered a handler for it).| { kind: 'hook-subscribe'; event: string; priority?: number }// The worker's handler result for a dispatched hook (continue/modify/error).diff --git a/src/core/plugins/sandbox/worker-capability.spec.ts b/src/core/plugins/sandbox/worker-capability.spec.tsindex d6e2762c0..ec8867ce1 100644--- a/src/core/plugins/sandbox/worker-capability.spec.ts+++ b/src/core/plugins/sandbox/worker-capability.spec.ts@@ -1,5 +1,6 @@import { WorkerCapabilityClient, buildSandboxContext } from './worker-capability';import { WorkerToHostMessage } from './protocol';+import { WorkerHookRegistry } from './worker-hooks';describe('WorkerCapabilityClient', () => {it('posts a cap request and resolves on the matching cap-result', async () => {@@ -39,6 +40,52 @@ describe('WorkerCapabilityClient', () => {await expect(a).resolves.toBe('A');await expect(b).resolves.toBe('B');});++ it('tags a call made inside a hook handler with that dispatch chain, and only that call', async () => {+ const sent: WorkerToHostMessage[] = [];+ const client = new WorkerCapabilityClient(m => sent.push(m));+ const hooks = new WorkerHookRegistry(m => sent.push(m));+ hooks.register('message:sending', () => {+ void client.call('messages.sendText', ['in-hook']);+ return { continue: true };+ });++ void client.call('messages.sendText', ['outside']); // an ingress handler or a timer+ await hooks.handleHook({+ kind: 'hook',+ id: 1,+ event: 'message:sending',+ data: {},+ source: 't',+ inFlight: ['message:received', 'message:sending'],+ });++ const caps = sent.filter((m): m is Extract<WorkerToHostMessage, { kind: 'cap' }> => m.kind === 'cap');+ expect(caps.map(c => [c.args[0], c.inFlight])).toEqual([+ ['outside', undefined],+ ['in-hook', ['message:received', 'message:sending']],+ ]);+ });++ it('does not tag a call a hook handler defers past the end of its dispatch', async () => {+ const sent: WorkerToHostMessage[] = [];+ const client = new WorkerCapabilityClient(m => sent.push(m));+ const hooks = new WorkerHookRegistry(m => sent.push(m));+ let fireLater!: () => void;+ const later = new Promise<void>(resolve => (fireLater = resolve));+ hooks.register('message:sent', () => {+ void later.then(() => client.call('messages.sendText', ['later']));+ return { continue: true };+ });++ await hooks.handleHook({ kind: 'hook', id: 1, event: 'message:sent', data: {}, source: 't' });+ fireLater();+ await later;+ await Promise.resolve();++ const caps = sent.filter((m): m is Extract<WorkerToHostMessage, { kind: 'cap' }> => m.kind === 'cap');+ expect(caps.map(c => [c.args[0], c.inFlight])).toEqual([['later', undefined]]);+ });});describe('buildSandboxContext', () => {diff --git a/src/core/plugins/sandbox/worker-capability.ts b/src/core/plugins/sandbox/worker-capability.tsindex 9a576d4f2..493b634f8 100644--- a/src/core/plugins/sandbox/worker-capability.ts+++ b/src/core/plugins/sandbox/worker-capability.ts@@ -1,4 +1,5 @@import { WorkerToHostMessage, HostToWorkerMessage } from './protocol';+import { hookConfigStore } from './worker-hooks';import { ConversationSendEnvelope } from '../plugin.interfaces';import { HandoverState } from '../../../modules/integration/entities/conversation-mapping.entity';@@ -16,7 +17,8 @@ export class WorkerCapabilityClient {const id = this.nextId++;return new Promise((resolve, reject) => {this.pending.set(id, { resolve, reject });- this.post({ kind: 'cap', id, verb, args });+ const inFlight = hookConfigStore.getStore()?.inFlight;+ this.post(inFlight ? { kind: 'cap', id, verb, args, inFlight } : { kind: 'cap', id, verb, args });});}diff --git a/src/core/plugins/sandbox/worker-hooks.ts b/src/core/plugins/sandbox/worker-hooks.tsindex 12a867e3c..a51a973e1 100644--- a/src/core/plugins/sandbox/worker-hooks.ts+++ b/src/core/plugins/sandbox/worker-hooks.ts@@ -5,8 +5,11 @@ import { WorkerToHostMessage, HostToWorkerMessage } from './protocol';* Carries the per-session-resolved config for the duration of a hook dispatch so ctx.config (a getter* in worker-bootstrap) returns the right slice — even when events for different sessions interleave.* AsyncLocalStorage scopes it per async call tree, so concurrent dispatches never see each other's.+ * It also carries the dispatch's in-flight hook chain, which a capability call made from that tree+ * sends back to the host: only a call caused by a hook handler is re-entrancy-guarded, never an+ * unrelated one (an ingress handler, a timer set outside a hook) that merely overlaps a dispatch.*/-export const hookConfigStore = new AsyncLocalStorage<{ config: Record<string, unknown> }>();+export const hookConfigStore = new AsyncLocalStorage<{ config?: Record<string, unknown>; inFlight?: string[] }>();export interface WorkerHookContext {event: string;@@ -51,11 +54,16 @@ export class WorkerHookRegistry {// Run the whole dispatch inside the per-session config scope so every handler (and any async work// it awaits) sees ctx.config resolved for THIS event's session. Absent config => the bootstrap// getter falls back to the base config.- const run = () => this.dispatch(message);- if (message.config !== undefined) {- await hookConfigStore.run({ config: message.config }, run);- } else {- await run();+ // The store outlives the dispatch in any timer or detached promise a handler starts; drop the+ // chain once it settles so such a later call is not treated as re-entrant.+ const store: { config?: Record<string, unknown>; inFlight?: string[] } = {+ config: message.config,+ inFlight: message.inFlight ?? [message.event],+ };+ try {+ await hookConfigStore.run(store, () => this.dispatch(message));+ } finally {+ store.inFlight = undefined;}}