Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(integration): refuse ingress for a disabled or deleted instance

Yudhi Armyndharis932e8b273365
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 2330b4d8f..747dbf6bf 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -6220,10 +6220,9 @@ still outstanding after this batch.
**Auth:** API key (ADMIN) · **Scope:** session-scoped (a key restricted to `allowedSessions` may only
redrive an instance whose current `sessionScope` is inside that allowlist; out of scope and missing
-instances both answer `404`, so redrive can't be used to probe other sessions). An unrestricted key is
-not fenced this way: it may drain retained rows for an instance that no longer exists, which is
-deliberate — those rows still carry the deleted binding's `sessionId` and only an unscoped caller may
-replay them.
+instances both answer `404`, so redrive can't be used to probe other sessions). A deleted or disabled
+instance answers `409` for every caller: ingress dispatch refuses such an instance, so its rows could
+only fail again. Re-enable the instance to replay its backlog.
**Path parameters**
@@ -6238,7 +6237,7 @@ replay them.
{ "redriven": 3, "remaining": 0, "batchSize": 100 }
```
-**Errors:** `401` · `403` key role < ADMIN · `404` a **scoped** key's instance that is missing or outside its `allowedSessions` (an unrestricted key gets `201` with `redriven: 0` instead)
+**Errors:** `401` · `403` key role < ADMIN · `404` a **scoped** key's instance that is missing or outside its `allowedSessions` · `409` the instance is deleted or disabled
---
diff --git a/openapi.json b/openapi.json
index f458bdcfc..edda37249 100644
--- a/openapi.json
+++ b/openapi.json
@@ -9440,6 +9440,9 @@
}
}
}
+ },
+ "409": {
+ "description": "The instance is disabled or deleted; its dead-lettered deliveries cannot be re-dispatched."
}
},
"tags": [
diff --git a/src/core/plugins/ingress-instance-config.spec.ts b/src/core/plugins/ingress-instance-config.spec.ts
index 7f4e418e4..02c413ef6 100644
--- a/src/core/plugins/ingress-instance-config.spec.ts
+++ b/src/core/plugins/ingress-instance-config.spec.ts
@@ -260,3 +260,27 @@ describe('ingress dispatch resolves config per INSTANCE, not per session scope',
expect(calls[0].config).toEqual({ apiToken: 'token-A' });
});
});
+
+describe('ingress dispatch refuses an instance that is disabled or deleted', () => {
+ it('rejects a disabled instance without reaching the worker', async () => {
+ const a = { ...instanceRow('acct-a', { apiToken: 'token-A' }, SHARED_SCOPE), enabled: false };
+ const { bridge, calls } = makeBridge({ rows: [a] });
+
+ await expect(bridge.dispatchWebhookForInstance(job('acct-a'))).rejects.toThrow(
+ 'instance acct-a of plugin chat-adapter is disabled or deleted',
+ );
+ expect(calls).toHaveLength(0);
+ });
+
+ it('rejects a deleted instance instead of dispatching it with the base config a wildcard sibling wrote', async () => {
+ // A wildcard instance projects its config into the base config; a job for a row that no longer
+ // exists must not run with it.
+ const wildcard = instanceRow('acct-b', { apiToken: 'token-B' }, null);
+ const { bridge, calls } = makeBridge({ rows: [wildcard], baseConfig: { apiToken: 'token-B' } });
+
+ await expect(bridge.dispatchWebhookForInstance(job('acct-a'))).rejects.toThrow(
+ 'instance acct-a of plugin chat-adapter is disabled or deleted',
+ );
+ expect(calls).toHaveLength(0);
+ });
+});
diff --git a/src/core/plugins/plugin-sandbox-bridge.ts b/src/core/plugins/plugin-sandbox-bridge.ts
index 1f9dc7b3f..395569909 100644
--- a/src/core/plugins/plugin-sandbox-bridge.ts
+++ b/src/core/plugins/plugin-sandbox-bridge.ts
@@ -175,7 +175,8 @@ export class PluginSandboxBridge {
/**
* 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) or when the worker's handler itself reports
+ * 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> {
@@ -193,6 +194,14 @@ export class PluginSandboxBridge {
// Missing/hot-swapped route metadata fails closed.
const verified = route ? route.signature.scheme !== 'none' : false;
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');
+ }
// 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
diff --git a/src/modules/integration/redrive.controller.spec.ts b/src/modules/integration/redrive.controller.spec.ts
index 3dc194d36..f1863fad0 100644
--- a/src/modules/integration/redrive.controller.spec.ts
+++ b/src/modules/integration/redrive.controller.spec.ts
@@ -1,5 +1,5 @@
import { Reflector } from '@nestjs/core';
-import { NotFoundException } from '@nestjs/common';
+import { ConflictException, NotFoundException } from '@nestjs/common';
import { RedriveController } from './redrive.controller';
import { ApiKey, ApiKeyRole } from '../auth/entities/api-key.entity';
import { REQUIRED_ROLE_KEY } from '../auth/decorators/auth.decorators';
@@ -22,13 +22,13 @@ describe('RedriveController authz', () => {
describe('RedriveController session-scope fence', () => {
const scopedKey = { allowedSessions: ['sess-1'] } as ApiKey;
- function build(sessionScope: string | null | undefined) {
+ function build(sessionScope: string | null | undefined, enabled?: boolean) {
const redrive = { redriveInstance: jest.fn().mockResolvedValue({ redriven: 0, remaining: 0, batchSize: 100 }) };
const instances = {
resolve: jest
.fn()
.mockResolvedValue(
- sessionScope === undefined ? null : { pluginId: 'chatwoot', instanceId: 'acct1', sessionScope },
+ sessionScope === undefined ? null : { pluginId: 'chatwoot', instanceId: 'acct1', sessionScope, enabled },
),
};
const audit = { logInfo: jest.fn() };
@@ -68,15 +68,32 @@ describe('RedriveController session-scope fence', () => {
expect(redrive.redriveInstance).not.toHaveBeenCalled();
});
- it('lets an unrestricted key redrive a missing instance (drains retained DLQ rows for cleanup), passing null as an unrestricted provenance filter', async () => {
- // An unrestricted key has no session fence, so it drains every retained row regardless of
- // sessionId. null signals "caller-decided unrestricted" to the service — never undefined, which
- // would silently fail open if a caller forgot the argument.
- const { controller, redrive } = build(undefined);
+ it('answers 409 when an unrestricted key redrives a missing instance (dispatch would refuse every row)', async () => {
+ // Dispatch refuses a deleted instance, so a replay could only fail again, and a queued replay
+ // would still retire its DLQ row as redriven. Refused before the service is reached.
+ const { controller, redrive, audit } = build(undefined);
- await controller.redriveInstance('chatwoot', 'acct1', { allowedSessions: null } as unknown as ApiKey);
+ await expect(
+ controller.redriveInstance('chatwoot', 'acct1', { allowedSessions: null } as unknown as ApiKey),
+ ).rejects.toThrow(ConflictException);
+ expect(redrive.redriveInstance).not.toHaveBeenCalled();
+ expect(audit.logInfo).not.toHaveBeenCalled();
+ });
- expect(redrive.redriveInstance).toHaveBeenCalledWith('chatwoot', 'acct1', null);
+ it('answers 409 when redriving a disabled instance, for scoped and unrestricted keys alike', async () => {
+ for (const apiKey of [scopedKey, { allowedSessions: null } as unknown as ApiKey]) {
+ const { controller, redrive } = build('sess-1', false);
+
+ await expect(controller.redriveInstance('chatwoot', 'acct1', apiKey)).rejects.toThrow(ConflictException);
+ expect(redrive.redriveInstance).not.toHaveBeenCalled();
+ }
+ });
+
+ it('keeps answering 404, not 409, when a scoped key redrives an out-of-scope disabled instance', async () => {
+ // The scope fence runs first so a disabled instance in another session is not revealed.
+ const { controller } = build('sess-2', false);
+
+ await expect(controller.redriveInstance('chatwoot', 'acct1', scopedKey)).rejects.toThrow(NotFoundException);
});
it('answers 404 when a scoped key redrives an all-sessions (null scope) instance', async () => {
diff --git a/src/modules/integration/redrive.controller.ts b/src/modules/integration/redrive.controller.ts
index e8b41c28e..e507c1f99 100644
--- a/src/modules/integration/redrive.controller.ts
+++ b/src/modules/integration/redrive.controller.ts
@@ -1,4 +1,4 @@
-import { Controller, NotFoundException, Param, Post } from '@nestjs/common';
+import { ConflictException, Controller, NotFoundException, Param, Post } from '@nestjs/common';
import { ApiTags, ApiResponse } from '@nestjs/swagger';
import { CurrentApiKey, RequireRole } from '../auth/decorators/auth.decorators';
import { type ApiKey, ApiKeyRole } from '../auth/entities/api-key.entity';
@@ -28,6 +28,10 @@ export class RedriveController {
description: 'One bounded batch of dead-lettered ingress deliveries re-dispatched, with remaining depth.',
type: RedriveResultDto,
})
+ @ApiResponse({
+ status: 409,
+ description: 'The instance is disabled or deleted; its dead-lettered deliveries cannot be re-dispatched.',
+ })
async redriveInstance(
@Param('pluginId') pluginId: string,
@Param('instanceId') instanceId: string,
@@ -36,19 +40,28 @@ export class RedriveController {
// Session-scoped keys may only redrive instances bound inside their own fence; an out-of-scope
// instance answers 404 (same as a missing one) so redrive can't be used to probe other sessions.
// A MISSING instance row is refused too: its retained DLQ rows still carry the deleted instance's
- // sessionId and would be re-dispatched unscoped. Only an unrestricted key may drain those.
+ // sessionId and would be re-dispatched unscoped.
const inst = await this.instances.resolve(pluginId, instanceId);
const scoped = (apiKey?.allowedSessions?.length ?? 0) > 0;
if (scoped && (!inst || !sessionScopeVisible(apiKey?.allowedSessions, inst.sessionScope))) {
throw new NotFoundException('instance not found');
}
+ // Dispatch refuses a deleted or disabled instance, so every replayed row would only fail again. A
+ // queued replay still counts as redriven and retires its DLQ row before the job fails, which would
+ // report success for deliveries that are then dead-lettered anew. Refuse up front instead; re-enable
+ // the instance first to replay its backlog.
+ if (!inst || inst.enabled === false) {
+ throw new ConflictException(
+ `instance ${instanceId} of plugin ${pluginId} is ${inst ? 'disabled' : 'deleted'}; its dead-lettered deliveries cannot be redriven`,
+ );
+ }
// Thread the authorized binding down as an explicit DLQ provenance filter. A scoped key is
// authorized against the instance's CURRENT sessionScope, but retained DLQ rows still carry the
// sessionId of whatever binding wrote them; without this filter a rebind sess-old -> sess-current
// lets a sess-current key replay historical sess-old rows. The filter is derived from the
// PERSISTED current instance (not the request body), and null means an unrestricted caller may
// drain every retained row — never undefined, which would silently fail open.
- const sessionIdFilter = scoped ? inst!.sessionScope : null;
+ const sessionIdFilter = scoped ? inst.sessionScope : null;
const result = await this.redrive.redriveInstance(pluginId, instanceId, sessionIdFilter);
// A redrive can trigger real downstream sends, so every successful batch is audited with its
// outcome counts (no payload content — the DLQ rows themselves hold those).
diff --git a/test/integration-instance.e2e-spec.ts b/test/integration-instance.e2e-spec.ts
index a7fbd38ee..75b615cb1 100644
--- a/test/integration-instance.e2e-spec.ts
+++ b/test/integration-instance.e2e-spec.ts
@@ -341,6 +341,16 @@ describe('IntegrationInstanceController (e2e)', () => {
.post('/api/integration/instances/chatwoot/other1/redrive')
.set('X-API-Key', scopedKey)
.expect(404);
+ // own1 was disabled above; dispatch refuses a disabled instance, so the redrive is refused too.
+ await request(app.getHttpServer())
+ .post('/api/integration/instances/chatwoot/own1/redrive')
+ .set('X-API-Key', scopedKey)
+ .expect(409);
+ await request(app.getHttpServer())
+ .patch(`${base}/chatwoot/instances/own1`)
+ .set('X-API-Key', scopedKey)
+ .send({ enabled: true })
+ .expect(200);
await request(app.getHttpServer())
.post('/api/integration/instances/chatwoot/own1/redrive')
.set('X-API-Key', scopedKey)