Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.ts
index 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.sen
expect(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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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;
}
}