Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import * as path from 'path';
import { ConfigService } from '@nestjs/config';
import { createLogger } from '../../common/services/logger.service';
import { HookManager, HookEvent, KNOWN_HOOK_EVENTS, isKnownHookEvent, normalizeHookPriority } from '../hooks';
import { PluginCapabilityPermission, PluginContext, PluginInstance, PluginStatus } from './plugin.interfaces';
import { PluginStorageService } from './plugin-storage.service';
import { PluginHostServices } from './plugin-host-services';
import { PluginCapabilityContext } from './plugin-capability-context';
import {
isPluginActiveForSession,
resolveInstanceConfig,
resolvePluginConfig,
sessionScopeKey,
} from './plugin-activation';
import { PluginWorkerHost } from './sandbox/plugin-worker-host';
import { dispatchCapabilityVerb } from './sandbox/capability-router';
import { PluginLogLevel } from './sandbox/protocol';
import { shouldDispatchToPlugin } from './handover-gate';
import { countMetaValues, metaText } from './sandbox-log-meta';
import { makeOnWebhookSubscribe } from './webhook-subscribe.util';
import { registerPluginSearchProvider, unregisterPluginSearchProvider } from './search-provider-registration.util';
import { INGRESS_DISPATCH_TIMEOUT_MS } from '../../modules/integration/integration.constants';
import type { IngressJobData } from '../../modules/queue/processors/ingress.processor';
/** Time budget for a sandboxed plugin's hook handler before the chain proceeds without it. */
const SANDBOX_HOOK_TIMEOUT_MS = 5000;
/** A sandboxed plugin's healthCheck must answer within this, else it's reported unhealthy (not hung). */
const SANDBOX_HEALTH_TIMEOUT_MS = 5000;
/** A sandboxed plugin's search handler must answer within this, else /search fails fast (not hung). */
const SANDBOX_SEARCH_TIMEOUT_MS = 10000;
/**
* A sandboxed plugin's load()/onLoad/onEnable/onDisable must complete within this, else the worker is
* torn down and the operation fails — a wedged lifecycle can't hang the enable/disable request (and
* the ADMIN HTTP call behind it) forever. Generous on purpose: a slow-but-valid onEnable that opens
* connections should still finish well under it.
*/
const SANDBOX_LIFECYCLE_TIMEOUT_MS = 30000;
/**
* Rate limit for the structured sandboxed-hook error log: at most one line per event per window so a
* hook that throws on every message can't flood the host log. Suppressed occurrences are counted and
* ride the next emitted line.
*/
const SANDBOX_HOOK_ERROR_LOG_INTERVAL_MS = 60000;
/**
* Worker log-relay bounds (per sandboxed plugin): at most this many lines per window are relayed;
* excess is dropped, counted, and surfaced as one warn per window. Longer lines are truncated. The
* worker is not a security boundary — these are robustness bounds against a chatty/buggy plugin
* flooding the host log, not isolation.
*/
const SANDBOX_LOG_MAX_PER_WINDOW = 200;
const SANDBOX_LOG_WINDOW_MS = 10000;
const SANDBOX_LOG_MAX_MESSAGE_LENGTH = 8192;
/** Per-enable log-relay rate-limit window, shared by the onLog relay and the onWorkerExit final flush. */
interface SandboxLogRelayState {
windowStart: number;
count: number;
dropped: number;
}
/**
* The loader's protected createSandboxHost signature, as a factory type. The bridge receives it as a
* closure and calls it exactly where enableSandboxed used to call the method.
*/
type CreateSandboxHostFn = (
capDispatcher?: (verb: string, args: unknown[]) => Promise<unknown>,
onHookSubscribe?: (event: string, priority?: number) => void,
onWebhookSubscribe?: (route: string) => void,
onLog?: (level: PluginLogLevel, message: string, meta?: Record<string, unknown>) => void,
runWithHookGuard?: (inFlightEvents: string[], run: () => Promise<unknown>) => Promise<unknown>,
onSearchProviderRegister?: () => void,
onWorkerExit?: (code: number, intentional: boolean, reason?: string) => void,
onUnresponsive?: () => void,
) => PluginWorkerHost;
/**
* The sandboxed-worker half of the plugin runtime: everything that speaks to an untrusted plugin's
* worker thread. Spawning the host on enable (and tearing it down on disable), relaying the worker's
* hook subscriptions, log lines and search-provider declaration back into the host, reacting to a
* worker exit, and the health + ingress-webhook dispatch that route to a live worker.
*
* Split out of PluginLoaderService so the loader reads as registry + lifecycle while this IPC bridge
* — the boundary an untrusted worker can actually poke — is reviewed on its own. A plain class, not
* a Nest provider: the loader constructs it in its constructor with everything it needs (the same
* pattern as PluginCapabilityContext), so the loader's public constructor signature — which specs
* build directly — is unchanged.
*
* Two deliberate seams keep the uneditable specs working:
* - `createHost` is a closure over the loader's protected createSandboxHost, so a spec subclass that
* overrides that method still injects its fake/real worker host through the bridge.
* - `plugins`, `sandboxHosts` and `lastSandboxHookError` are the loader's own Maps, passed by
* reference: specs poke them on the loader via casts, and one shared (mutable) Map instance keeps
* the loader's view and the bridge's view the same map.
*/
export class PluginSandboxBridge {
constructor(
// The LOADER's logger, deliberately — sandbox-bridge lines carry the PluginLoaderService tag,
// and that context is operator-visible. Creating a second logger here would silently retag every
// sandbox log line the moment this moved out.
private readonly logger: ReturnType<typeof createLogger>,
private readonly hookManager: HookManager,
private readonly capabilities: PluginCapabilityContext,
private readonly hostServices: PluginHostServices,
private readonly configService: ConfigService,
private readonly pluginStorage: PluginStorageService,
// The loader's own registry + sandbox state, passed BY REFERENCE (see the class doc): mutations
// here are visible to the loader and to the specs that poke these Maps on it.
private readonly plugins: Map<string, PluginInstance>,
private readonly sandboxHosts: Map<string, PluginWorkerHost>,
private readonly lastSandboxHookError: Map<string, { event: string; error: string; at: Date }>,
private readonly pluginsDir: string,
// Closure over the loader's protected createSandboxHost (see the class doc for the seam).
private readonly createHost: CreateSandboxHostFn,
// resolvePluginMainPath stays exported from the loader (specs import it there); passed in so this
// file never has to import back from the loader, which would close an import cycle.
private readonly resolvePluginMainPath: (pluginsDir: string, pluginId: string, main: string) => string,
) {}
/**
* Surface a sandboxed plugin's hook-handler failure host-side: record it for the plugin's health
* surface and emit one structured warn per event per SANDBOX_HOOK_ERROR_LOG_INTERVAL_MS — a hook
* that throws on every message must be visible, but must not become a log-flood vector. Suppressed
* occurrences are counted and ride the next emitted line.
*/
private recordSandboxHookError(
pluginId: string,
event: string,
error: string,
rateLimit: Map<string, { lastAt: number; suppressed: number }>,
action: 'sandbox_hook_error' | 'sandbox_hook_timeout' = 'sandbox_hook_error',
): void {
this.lastSandboxHookError.set(pluginId, { event, error, at: new Date() });
const now = Date.now();
// Errors and timeouts are windowed apart, so a burst of one never hides the other.
const key = `${action}:${event}`;
const state = rateLimit.get(key);
if (state && now - state.lastAt < SANDBOX_HOOK_ERROR_LOG_INTERVAL_MS) {
state.suppressed++;
return;
}
const suppressed = state?.suppressed ?? 0;
rateLimit.set(key, { lastAt: now, suppressed: 0 });
this.logger.warn(`Sandboxed plugin ${pluginId} hook '${event}' handler failed: ${error}`, {
pluginId,
event,
action,
...(suppressed > 0 ? { suppressed } : {}),
});
}
/**
* Run a plugin's healthCheck across both tiers. A sandboxed plugin's healthCheck lives in the worker
* (plugin.instance is null), so route to the live worker host (time-bounded); built-ins use the
* in-process instance. A sandboxed plugin with no live worker (crashed, failed to enable, disabled) is
* unhealthy. Returns the default "healthy" when a built-in implements no health check.
*/
async checkPluginHealth(pluginId: string): Promise<{ healthy: boolean; message?: string }> {
const sandboxHost = this.sandboxHosts.get(pluginId);
if (sandboxHost) {
const result = await sandboxHost.healthCheck(SANDBOX_HEALTH_TIMEOUT_MS);
// Attach the last hook-handler error the worker reported: a plugin whose hook throws on every
// event can still answer healthCheck "healthy" while doing nothing useful. This is operator
// context, not a verdict override — the worker's own healthCheck stays authoritative.
const lastError = this.lastSandboxHookError.get(pluginId);
if (!lastError) return result;
const note = `last hook error in '${lastError.event}' at ${lastError.at.toISOString()}: ${lastError.error}`;
return { healthy: result.healthy, message: result.message ? `${result.message}; ${note}` : note };
}
const plugin = this.plugins.get(pluginId);
if (plugin && !plugin.builtIn) {
const message =
plugin.status === PluginStatus.ERROR && plugin.error
? plugin.error
: `plugin is not running (status ${plugin.status})`;
return { healthy: false, message };
}
if (plugin?.instance?.healthCheck) {
return plugin.instance.healthCheck();
}
return { healthy: true, message: 'Plugin does not implement health check' };
}
/**
* Dispatch a queued ingress job into its plugin's live sandbox worker. Called from IngressProcessor,
* mirroring checkPluginHealth's sandboxHosts lookup. Throws when the plugin has no live
* worker (disabled/crashed since the job was enqueued), when the instance was disabled or deleted
* since, or when the worker's handler itself reports
* failure (`!result.ok`, e.g. a 502/504/500) — either way BullMQ's retry/DLQ machinery takes over.
*/
async dispatchWebhookForInstance(d: IngressJobData): Promise<void> {
const host = this.sandboxHosts.get(d.pluginId);
if (!host) {
throw new Error('no live sandbox host for plugin ' + d.pluginId);
}
// Resolve this instance's per-session config (the base merged with the sessionScope override that
// provisioning wrote) so the ingress handler reads it as ctx.config — this is what makes a minted
// instance multi-tenant. Best-effort: an unresolved plugin just yields undefined (base config only).
const plugin = this.plugins.get(d.pluginId);
const route = plugin?.manifest.ingress?.find(candidate => candidate.route === d.route);
// Reaching dispatch means every authenticating scheme already passed host verification. A route
// explicitly configured with scheme:none is unauthenticated and must never be labelled verified.
// The verdict is the one recorded at admission: a plugin update can change the route's scheme while
// a delivery waits, and it must not relabel a payload nobody authenticated. A delivery admitted before
// the verdict was recorded reads the route as it stands. Missing/hot-swapped route metadata fails closed.
const verified = !!route && (d.payload.admission?.verified ?? route.signature.scheme !== 'none');
const instance = await this.hostServices.getPluginInstancePort().resolve(d.pluginId, d.instanceId);
// The live door and the reconciler refuse an unknown or disabled instance; a queued job, a retry,
// the inline fallback and a redrive all land here instead, so the same rule is enforced once more.
// A missing row must never fall through to the base config below: a wildcard instance projects its
// own config there, so the delivery would run with another instance's endpoint and credentials.
// Throwing hands the job to the normal retry/dead-letter path.
if (!instance || instance.enabled === false) {
throw new Error('instance ' + d.instanceId + ' of plugin ' + d.pluginId + ' is disabled or deleted');
}
// The job carries the session the instance acted on at admission. Rebound since, the delivery would
// reach the handler under that session with the new session's config, so it is refused instead.
if (sessionScopeKey(instance.sessionScope) !== sessionScopeKey(d.sessionId)) {
throw new Error('instance ' + d.instanceId + ' of plugin ' + d.pluginId + ' was rebound since this delivery');
}
// Three layers, most specific last: the base ('*') config, then the operator's per-session
// override from PUT /plugins/:id/sessions/:sessionId/config, then THIS instance's own config.
// The instance layer is what keeps two instances sharing one session scope apart — provisioning
// projects both onto the same scope key, so the scope-keyed store alone would hand a delivery
// whichever instance was provisioned last. It applies even for a non-session-scoped plugin,
// whose instances are otherwise indistinguishable here.
//
// PRECEDENCE NOTE: this puts the instance row above the operator's per-session override from
// PUT /plugins/:id/sessions/:sessionId/config, for the keys the instance itself defines. That is
// deliberate and cannot be otherwise: provisioning PROJECTS each instance's config into the
// scope-keyed store, so for two instances sharing a scope that slice holds whichever was written
// last — applying it on top would hand a delivery the other tenant's credentials again. The
// override still decides every key the instance does not define, and still decides everything on
// the hook path. To change an instance's own config, use the instance route.
// The scope slice is consulted only while it can be ATTRIBUTED to this instance. Layering the row
// on top corrects the keys the row defines; every key it leaves unset — the normal shape when an
// instance relies on a plugin default — falls through to that slice, which for two instances
// sharing a scope holds the other tenant's projected value. So a sparse row was still handed a
// sibling's live endpoint or token.
//
// KNOWN RESIDUE: a WILDCARD instance is projected into the BASE config instead
// (scope-binding.service.ts, `updatePluginConfig`), and that merge is not separable per instance
// by design — its own comment says so. Attribution there needs the projection re-keyed by
// instance, which is a storage change, not a resolution one.
const scopeIsAttributable = await this.scopeHasAtMostOneInstance(d.pluginId, instance?.sessionScope ?? undefined);
const config = plugin
? resolveInstanceConfig(
scopeIsAttributable
? resolvePluginConfig(
plugin.config,
plugin.sessionConfig,
instance?.sessionScope ?? undefined,
plugin.manifest.sessionScoped !== false,
plugin.manifest,
)
: plugin.config,
instance?.config,
plugin.manifest,
plugin.config,
)
: undefined;
const result = await host.dispatchWebhook({
instanceId: d.instanceId,
route: d.route,
method: d.method ?? 'POST',
headers: d.payload.headers,
query: d.payload.query,
body: d.payload.body,
rawBody: d.payload.rawBody,
verified,
deliveryId: d.deliveryId,
sessionId: d.sessionId,
config,
timeoutMs: INGRESS_DISPATCH_TIMEOUT_MS,
});
if (!result.ok) {
throw new Error(result.error ?? 'ingress dispatch failed with status ' + result.status);
}
}
/**
* Whether the scope-keyed config slice can be attributed to the instance being dispatched.
*
* Provisioning projects each instance's config into that slice keyed by SCOPE, so with siblings it
* holds whichever was written last and says nothing about whose delivery this is. With one enabled
* instance it is either that instance's own projection or an operator's deliberate per-session
* override — both of which must keep applying, so a single-instance deployment is unchanged.
*
* A lookup failure is treated as NOT attributable: the instance's own config still applies, and the
* cost of being wrong that way is a missing default rather than another tenant's credential.
*/
private async scopeHasAtMostOneInstance(pluginId: string, scope: string | undefined): Promise<boolean> {
if (!scope) return false;
try {
const rows = await this.hostServices.getPluginInstancePort().list(pluginId);
return rows.filter(row => row.enabled && row.sessionScope === scope).length <= 1;
} catch (error) {
// Logged rather than swallowed: this drops the operator's per-session override for the
// deliveries it affects, and a silent config change is exactly what made the original
// collapse hard to see.
this.logger.warn('Could not count instances on the scope; withholding the per-session config slice', {
pluginId,
scope,
error: error instanceof Error ? error.message : String(error),
});
return false;
}
}
/**
* Untrusted enable: load the plugin in an isolated worker and drive its lifecycle there. Capability
* calls and hooks round-trip to the host, which enforces permission + session scope. A failure
* tears the worker back down.
*/
async enableSandboxed(pluginId: string, plugin: PluginInstance): Promise<void> {
// A new worker generation starts from a clean slate. disablePlugin clears this too, but a crash
// and a failed enable both end a generation WITHOUT going through disable — so clearing only
// there let the replacement worker inherit a dead one's hook error and report it through
// checkPluginHealth as current. Enforced here, at the one point every generation begins, rather
// than repeated on each way a generation can end.
this.lastSandboxHookError.delete(pluginId);
// Containment guard: reject a manifest.main that escapes the plugin dir.
// Anchored to the directory the package was loaded from, which is not necessarily
// <plugins.dir>/<id>: the loader also scans the legacy plugins directory, and the worker's
// require() of a path in the wrong tree fails with MODULE_NOT_FOUND.
const packageDir = plugin.packageDir ?? path.join(this.pluginsDir, pluginId);
const mainPath = this.resolvePluginMainPath(
path.dirname(packageDir),
path.basename(packageDir),
plugin.manifest.main,
);
// The capability dispatcher runs a worker request through the SAME context an in-process plugin
// gets, so permission + session-scope checks (assertPermission / assertSessionActive) apply
// identically. The worker can only ask; the host is the gatekeeper.
const context = this.capabilities.createPluginContext(plugin);
const onHookSubscribe = this.buildHookSubscribeHandler(pluginId, plugin);
// When the worker claims an ingress route, check the claim against the manifest-declared routes
// and log an undeclared one (warn once). Same hardening as onHookSubscribe (the wire `route` is an
// arbitrary untrusted string). Nothing is recorded: dispatch never consults the claim, and the
// worker answers 404 for a route it never registered.
const onWebhookSubscribe = makeOnWebhookSubscribe({
pluginId,
declaredRoutes: new Set((plugin.manifest.ingress ?? []).map(r => r.route)),
hasPermission: (plugin.manifest.permissions ?? []).includes(PluginCapabilityPermission.WEBHOOK_INGRESS),
warn: (message, meta) => this.logger.warn(message, meta),
});
const logRelayState: SandboxLogRelayState = { windowStart: Date.now(), count: 0, dropped: 0 };
const onLog = this.buildLogRelay(pluginId, context, logRelayState);
const onSearchProviderRegister = this.buildSearchProviderRegistrar(pluginId, plugin);
const onWorkerExit = this.buildWorkerExitHandler(pluginId, logRelayState, () => host);
// A worker whose event loop stays blocked after a dispatch timeout (a synchronous loop in plugin
// code) would otherwise keep running and queue every later dispatch for the full budget each.
// Same policy as a crash: terminate it and leave the plugin in ERROR for the operator to re-enable.
// The generation check keeps a late report from marking a replacement worker.
const onUnresponsive = (): void => {
if (this.sandboxHosts.get(pluginId) !== host) return;
this.markWorkerFailed(pluginId, 'worker unresponsive: event loop blocked past the liveness probe');
this.logger.warn(`Sandboxed plugin ${pluginId} worker is unresponsive; terminating it`, {
pluginId,
action: 'sandbox_worker_unresponsive',
});
void host.terminate().catch(() => undefined);
};
const host: PluginWorkerHost = this.createHost(
(verb, args) => dispatchCapabilityVerb(context, verb, args),
onHookSubscribe,
onWebhookSubscribe,
onLog,
// Re-establish the in-flight hook context for worker-initiated capability calls, so a sandboxed
// plugin that sends from within a send hook can't loop the event back into itself unboundedly.
(events, run) => this.hookManager.runInFlight(events as HookEvent[], run),
onSearchProviderRegister,
onWorkerExit,
onUnresponsive,
);
this.sandboxHosts.set(pluginId, host);
try {
await host.load(mainPath, { pluginId, config: plugin.config }, SANDBOX_LIFECYCLE_TIMEOUT_MS);
await host.runLifecycle('onLoad', SANDBOX_LIFECYCLE_TIMEOUT_MS);
await host.runLifecycle('onEnable', SANDBOX_LIFECYCLE_TIMEOUT_MS);
} catch (error) {
this.sandboxHosts.delete(pluginId);
// Drop a search provider registered mid-onEnable before the failure: without this, a plugin that
// registers then throws leaves a dead provider as the ACTIVE registry entry in auto mode, so every
// /search routes to a terminated worker → outage. Mirrors disablePlugin's cleanup.
unregisterPluginSearchProvider(this.hostServices.getSearchRegistryPort(), pluginId);
await host.terminate().catch(() => undefined);
throw error;
}
}
/**
* The sandboxed half of disablePlugin: the loader found a live worker host, so the plugin's
* onDisable (and, only on the unload path, onUnload) runs in the worker, bounded, before the worker
* is terminated and dropped from sandboxHosts. The shared tail of disablePlugin — hook
* unregistration, the search-provider drop, status persistence — stays in the loader because it
* runs for in-process plugins too.
*/
async teardownSandboxed(pluginId: string, host: PluginWorkerHost, opts?: { unload?: boolean }): Promise<void> {
// Disable is a force-teardown: even if the plugin's onDisable hangs (now bounded) or throws,
// we still kill the worker and drop the reference, so a misbehaving plugin can never block a
// disable or leak its worker thread.
try {
await host.runLifecycle('onDisable', SANDBOX_LIFECYCLE_TIMEOUT_MS);
} catch (error) {
this.logger.warn(`Sandboxed plugin ${pluginId} onDisable failed during disable; terminating anyway`, {
pluginId,
action: 'sandbox_disable_lifecycle_failed',
error: error instanceof Error ? error.message : String(error),
});
}
if (opts?.unload) {
// The worker is about to be terminated, so this is the ONLY chance onUnload ever gets for
// a sandboxed plugin — after terminate the hook is unreachable, and unloadPlugin's
// in-process call can't help (plugin.instance is null). Same bounded, best-effort policy
// as onDisable above: a wedged/throwing onUnload must never block the teardown.
try {
await host.runLifecycle('onUnload', SANDBOX_LIFECYCLE_TIMEOUT_MS);
} catch (error) {
this.logger.warn(`Sandboxed plugin ${pluginId} onUnload failed during unload; terminating anyway`, {
pluginId,
action: 'sandbox_unload_lifecycle_failed',
error: error instanceof Error ? error.message : String(error),
});
}
}
await host.terminate().catch(() => undefined);
this.sandboxHosts.delete(pluginId);
}
// When the worker subscribes to a hook, register a shim with the hook manager that dispatches the
// event into the worker (time-bounded, so a wedged plugin can't stall the chain). The shim looks
// the host up at fire time, so disabling the plugin (which removes it + unregisters hooks) stops it.
// Harden the IPC boundary against an untrusted worker flooding the host hook registry. HookEvent is
// a type-only union and the wire payload is an arbitrary string, so a hostile/buggy worker can post
// 'hook-subscribe' with (a) the same event repeatedly and (b) unbounded fabricated event names
// ('x:0','x:1',…). Without guards each call adds a live host-side registration (unbounded host-heap
// growth + an O(n log n) re-sort). Three guards, all local to this enableSandboxed call (dropped on
// disable): reject unknown events (bounds growth to the finite known set + drops events that can
// never fire), dedup per event, and a belt-and-suspenders size cap.
//
// One shim per event runs the worker's whole chain for it, so it sits at the LOWEST priority any of
// the worker's handlers asked for: the worker re-subscribes when a later handler lowers it, and the
// shim moves up. Pinning it to the first handler's priority let another plugin's handler run before
// a sandboxed handler that asked to go first (a redaction ahead of a mirror, say).
private buildHookSubscribeHandler(
pluginId: string,
plugin: PluginInstance,
): (event: string, priority?: number) => void {
const subscribedEvents = new Map<HookEvent, { hookId: string; priority: number }>();
let unknownEventWarned = false;
return (event: string, rawPriority?: number): void => {
if (!isKnownHookEvent(event)) {
if (!unknownEventWarned) {
unknownEventWarned = true; // warn at most once per plugin so a flood isn't a log-flood vector
this.logger.warn(`Sandboxed plugin ${pluginId} subscribed to an unknown hook event; ignoring`, {
pluginId,
event,
action: 'sandbox_unknown_hook_event',
});
}
return;
}
const priority = normalizeHookPriority(rawPriority);
const existing = subscribedEvents.get(event);
if (existing) {
if (priority < existing.priority) {
this.hookManager.setPriority(existing.hookId, priority);
existing.priority = priority;
}
return;
}
if (subscribedEvents.size >= KNOWN_HOOK_EVENTS.size) return; // can't exceed the known set
// Per-event rate-limit state for the hook-error log; local to this enable call so it is dropped
// on disable exactly like subscribedEvents.
const hookErrorLogState = new Map<string, { lastAt: number; suppressed: number }>();
const hookId = this.hookManager.register(
pluginId,
event,
async hookCtx => {
const liveHost = this.sandboxHosts.get(pluginId);
if (!liveHost) return { continue: true };
// Per-session activation gate: a session-scoped plugin only sees events for the sessions
// it is activated for. Pass-through (don't dispatch into the worker) otherwise.
if (
!isPluginActiveForSession(
plugin.manifest.sessionScoped ?? true,
plugin.activeSessions ?? ['*'],
hookCtx.sessionId,
)
)
return { continue: true };
// Handover gate: once a human has taken over (or closed) a conversation, the bot stops
// seeing its inbound messages. Scoped to message:received only — every other hook event is
// unaffected. Best-effort + fail-open: a lookup failure (or an event/mapping shape the gate
// can't resolve) must never block a normal message from reaching the adapter.
if (event === 'message:received') {
try {
const chatId = (hookCtx.data as { chatId?: string } | undefined)?.chatId;
if (chatId && hookCtx.sessionId) {
const handover = await this.hostServices
.getConversationMappingPort()
.findHandoverForChat(hookCtx.sessionId, chatId);
if (!shouldDispatchToPlugin(handover, pluginId)) return { continue: true };
}
} catch (error) {
this.logger.debug(`Handover gate lookup failed for plugin ${pluginId}; dispatching normally`, {
pluginId,
event,
error: error instanceof Error ? error.message : String(error),
action: 'handover_gate_fail_open',
});
}
}
return liveHost
.dispatchHook({
event,
data: hookCtx.data,
sessionId: hookCtx.sessionId,
source: hookCtx.source,
// The host resolves the per-session slice (real secrets — the worker is the plugin's
// trusted execution context) and ships it; the worker exposes it as ctx.config.
config: resolvePluginConfig(
plugin.config,
plugin.sessionConfig,
hookCtx.sessionId,
plugin.manifest.sessionScoped !== false,
plugin.manifest,
),
// 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,
// Rate-limited like a handler error: a plugin that times out on every message must be
// visible (log + health) without writing one line per event.
onTimeout: () =>
this.recordSandboxHookError(
pluginId,
event,
`timed out after ${SANDBOX_HOOK_TIMEOUT_MS}ms`,
hookErrorLogState,
'sandbox_hook_timeout',
),
})
.then(result => {
// The worker reports (not throws) a hook-handler failure: surface it host-side instead
// of failing open in silence. The chain itself still proceeds fail-open.
if (result.error) this.recordSandboxHookError(pluginId, event, result.error, hookErrorLogState);
return { continue: result.continue, data: result.data };
});
},
priority,
);
subscribedEvents.set(event, { hookId, priority });
};
}
// Route the worker plugin's ctx.logger.* calls to the same per-plugin logger an in-process plugin
// uses, so sandboxed plugins log identically (prefixed + structured) instead of bare stdout. The
// relay is bounded: oversized lines are truncated and throughput is capped per window — a chatty
// or buggy plugin must not flood the host log. Dropped lines are counted and surfaced as one warn
// per window (never one line per drop, or the bound itself would be a flood vector), plus a final
// flush on worker exit so a plugin that goes quiet first doesn't silently lose the count. State is
// local to this enable call, so it resets on disable.
private buildLogRelay(
pluginId: string,
context: PluginContext,
state: SandboxLogRelayState,
): (level: PluginLogLevel, message: string, meta?: Record<string, unknown>) => void {
return (level: PluginLogLevel, message: string, meta?: Record<string, unknown>): void => {
const now = Date.now();
if (now - state.windowStart >= SANDBOX_LOG_WINDOW_MS) {
if (state.dropped > 0) {
this.logger.warn(
`Dropped ${state.dropped} log messages from sandboxed plugin ${pluginId} (log relay rate limit)`,
{ pluginId, action: 'sandbox_log_relay_dropped', dropped: state.dropped },
);
}
state.windowStart = now;
state.count = 0;
state.dropped = 0;
}
state.count++;
if (state.count > SANDBOX_LOG_MAX_PER_WINDOW) {
state.dropped++;
return;
}
// Like the level below, the message and meta come off the wire unchecked: a non-string message is replaced by
// a fixed marker (turning an array into text would write a shared reference out at every use), and a meta
// whose text, as the logger writes it (metaText), exceeds the same cap is replaced by a size marker (not a
// truncated string, which would hide its keys from the logger's secret redaction).
// logger.error's reason travels as a string meta.error, so that one key survives the replacement.
const truncate = (value: string): string =>
value.length > SANDBOX_LOG_MAX_MESSAGE_LENGTH
? `${value.slice(0, SANDBOX_LOG_MAX_MESSAGE_LENGTH)}…[truncated]`
: value;
const bounded = truncate(typeof message === 'string' ? message : '[non-string log message]');
let boundedMeta = meta;
if (meta !== undefined) {
const reason = typeof meta?.error === 'string' ? { error: truncate(meta.error) } : undefined;
// A count past the size limit (values, string characters and property name characters) marks a meta that is
// replaced without being written out. The text is only built, to learn its length, for a meta under the
// limit: building it for any other could take seconds, as a shared reference is written out at every use.
if (countMetaValues(meta, SANDBOX_LOG_MAX_MESSAGE_LENGTH) > SANDBOX_LOG_MAX_MESSAGE_LENGTH) {
boundedMeta = { ...reason, metaTruncated: true };
} else {
try {
const metaLength = (metaText(meta) ?? '').length;
if (metaLength > SANDBOX_LOG_MAX_MESSAGE_LENGTH)
boundedMeta = { ...reason, metaTruncated: true, metaLength };
} catch {
boundedMeta = reason; // circular, or holding a BigInt, whose text is not built on the host
}
}
}
// The level comes off the wire unchecked (plugin code can post to parentPort directly), and the
// plugin logger has no method for anything outside PluginLogLevel.
if (level === 'error') context.logger.error(bounded, undefined, boundedMeta);
else if (level === 'debug' || level === 'warn') context.logger[level](bounded, boundedMeta);
else context.logger.log(bounded, boundedMeta);
};
}
// When the worker declares itself a search provider (ctx.registerSearchProvider →
// search-provider-register), register a PluginSearchProvider in the SearchProviderRegistry. The host
// is in sandboxHosts by the time registration fires (during onLoad/onEnable), so look it up lazily
// like onHookSubscribe. Search disabled (no registry, or SEARCH_PROVIDER=none) → the util skips, and
// a manifest without 'search:provide' is denied there — the wire declaration is untrusted input, and
// this bridge bypasses the capability router that gates the ctx.* capabilities.
private buildSearchProviderRegistrar(pluginId: string, plugin: PluginInstance): () => void {
return (): void => {
const liveHost = this.sandboxHosts.get(pluginId);
if (!liveHost) return;
registerPluginSearchProvider({
pluginId,
label: `${plugin.manifest.name} (plugin)`,
transport: liveHost,
timeoutMs: SANDBOX_SEARCH_TIMEOUT_MS,
registry: this.hostServices.getSearchRegistryPort(),
mode: this.configService.get<string>('search.provider', 'auto'),
hasPermission: (plugin.manifest.permissions ?? []).includes(PluginCapabilityPermission.SEARCH_PROVIDE),
warn: (message, meta) => this.logger.warn(message, meta),
});
};
}
// Shared ERROR transition for a crashed or unresponsive worker: mark the plugin ERROR, drop its hook
// shims and the dead host. The exit handler releases the search provider.
private markWorkerFailed(pluginId: string, reason: string): void {
const plugin = this.plugins.get(pluginId);
if (plugin) {
plugin.status = PluginStatus.ERROR;
plugin.error = reason;
this.pluginStorage.setPluginStatus(pluginId, PluginStatus.ERROR);
}
this.hookManager.unregisterPlugin(pluginId);
this.sandboxHosts.delete(pluginId);
}
// A worker that crashes AFTER a successful enable is otherwise invisible to the loader (handleExit only
// drains in-flight calls). Drop the plugin's search-provider entry so the registry falls back to
// builtin-fts instead of routing every /search to a dead worker (auto mode would otherwise pin the dead
// provider ACTIVE). Mirrors the enable-failure cleanup.
private buildWorkerExitHandler(
pluginId: string,
logRelayState: SandboxLogRelayState,
getSourceHost: () => PluginWorkerHost,
): (code: number, intentional: boolean, reason?: string) => void {
return (code: number, intentional: boolean, reason?: string): void => {
// Final log-relay flush: the per-window drop warn above only fires when a new line arrives in a
// later window, so without this a plugin that goes quiet (or is disabled) before the rollover
// silently discards its pending count. The worker is gone, so no further lines can arrive.
if (logRelayState.dropped > 0) {
this.logger.warn(
`Dropped ${logRelayState.dropped} log messages from sandboxed plugin ${pluginId} (log relay rate limit)`,
{ pluginId, action: 'sandbox_log_relay_dropped', dropped: logRelayState.dropped },
);
logRelayState.dropped = 0;
}
// A replacement owns its provider, hooks and status. An absent host still needs cleanup after
// markWorkerFailed removed the retiring worker before its termination completed.
const currentHost = this.sandboxHosts.get(pluginId);
if (currentHost && currentHost !== getSourceHost()) return;
unregisterPluginSearchProvider(this.hostServices.getSearchRegistryPort(), pluginId);
if (intentional) return; // routine disable/enable-failure already logged and expected
// Unexpected crash after a successful enable: the worker is gone. Drop the dead host +
// unregister the hook shims (so they don't keep dispatching into the dead worker) + mark the
// plugin ERROR so the dashboard reflects reality. The dispatchHook/dispatchWebhook dead-checks
// fail-fast; this cleanup is the root-cause fix (it also makes the shim's !liveHost guard fire).
const why = reason ? `: ${reason}` : '';
this.markWorkerFailed(pluginId, `worker exited unexpectedly (code ${code})${why}`);
this.logger.warn(`Sandboxed plugin ${pluginId} worker exited unexpectedly (code ${code})${why}`, {
pluginId,
code,
action: 'sandbox_worker_exit',
});
};
}
}