Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
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.mdindex 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 onlyredrive 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.jsonindex 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.tsindex 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.tsindex 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 — provisioningdiff --git a/src/modules/integration/redrive.controller.spec.ts b/src/modules/integration/redrive.controller.spec.tsindex 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.tsindex 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.tsindex 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)