Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

18.9 KB
Raw Blame
import { ConfigService } from '@nestjs/config';
import { HookManager } from '../hooks';
import { PluginSandboxBridge } from './plugin-sandbox-bridge';
import { PluginCapabilityContext } from './plugin-capability-context';
import { PluginHostServices } from './plugin-host-services';
import { PluginStorageService } from './plugin-storage.service';
import { PluginInstance as LoadedPlugin, PluginManifest, PluginStatus, PluginType } from './plugin.interfaces';
import { PluginWorkerHost } from './sandbox/plugin-worker-host';
import { PluginInstance as InstanceRow } from '../../modules/integration/entities/plugin-instance.entity';
import { IngressJobData } from '../../modules/queue/processors/ingress.processor';
import { createLogger } from '../../common/services/logger.service';

// Two enabled instances of ONE plugin may legitimately share a session scope. Provisioning projects
// each instance's config into a scope-keyed store, so the second write overwrites the first — which
// makes the scope an unusable key for resolving WHOSE credentials a delivery must run with. Dispatch
// is per-instance by definition and already holds the instance row, so these pin that the row, not
// the scope, decides the config a delivery is handled with.

const PLUGIN_ID = 'chat-adapter';
const SHARED_SCOPE = 'session-shared';

function manifest(overrides: Partial<PluginManifest> = {}): PluginManifest {
  return {
    id: PLUGIN_ID,
    name: 'Chat Adapter',
    version: '1.0.0',
    type: PluginType.EXTENSION,
    main: 'index.js',
    ...overrides,
  };
}

function instanceRow(instanceId: string, config: Record<string, unknown> | null, scope: string | null): InstanceRow {
  return {
    id: `${PLUGIN_ID}:${instanceId}`,
    pluginId: PLUGIN_ID,
    instanceId,
    sessionScope: scope,
    secret: 'secret-' + instanceId,
    verifyToken: null,
    config,
    enabled: true,
    createdAt: new Date(),
    updatedAt: new Date(),
  };
}

/** A job as admission leaves it: the session is the one the instance was bound to. */
function job(
  instanceId: string,
  sessionId: string | null = SHARED_SCOPE,
  admission?: { verified: boolean },
): IngressJobData {
  return {
    pluginId: PLUGIN_ID,
    instanceId,
    route: '/hook',
    deliveryId: 'delivery-' + instanceId,
    sessionId: sessionId ?? undefined,
    payload: { headers: {}, query: {}, body: '{}', rawBody: '{}', ...(admission ? { admission } : {}) },
  };
}

/** The fields of the worker payload these specs assert on. */
type WebhookCall = { config?: Record<string, unknown>; verified?: boolean; sessionId?: string };

/** Builds a bridge whose dispatch path is real; only the worker host and the instance store are fakes. */
function makeBridge(opts: {
  rows: InstanceRow[];
  baseConfig?: Record<string, unknown>;
  sessionConfig?: Record<string, Record<string, unknown>>;
  manifestOverrides?: Partial<PluginManifest>;
}): { bridge: PluginSandboxBridge; calls: WebhookCall[] } {
  const calls: WebhookCall[] = [];
  const dispatchWebhook = (payload: WebhookCall): Promise<{ ok: boolean; status: number }> => {
    calls.push(payload);
    return Promise.resolve({ ok: true, status: 200 });
  };
  const sandboxHosts = new Map<string, PluginWorkerHost>([
    [PLUGIN_ID, { dispatchWebhook } as unknown as PluginWorkerHost],
  ]);

  const plugins = new Map<string, LoadedPlugin>([
    [
      PLUGIN_ID,
      {
        manifest: manifest(opts.manifestOverrides),
        status: PluginStatus.ENABLED,
        config: opts.baseConfig ?? {},
        sessionConfig: opts.sessionConfig,
      } as unknown as LoadedPlugin,
    ],
  ]);

  const hostServices = {
    getPluginInstancePort: () => ({
      resolve: (pluginId: string, instanceId: string) =>
        Promise.resolve(opts.rows.find(r => r.pluginId === pluginId && r.instanceId === instanceId) ?? null),
      list: (pluginId: string) => Promise.resolve(opts.rows.filter(r => r.pluginId === pluginId)),
    }),
  } as unknown as PluginHostServices;

  const bridge = new PluginSandboxBridge(
    createLogger('test'),
    new HookManager(),
    undefined as unknown as PluginCapabilityContext,
    hostServices,
    undefined as unknown as ConfigService,
    undefined as unknown as PluginStorageService,
    plugins,
    sandboxHosts,
    new Map(),
    '/plugins',
    (() => undefined) as never,
    () => '/plugins/index.js',
  );
  return { bridge, calls };
}

describe('ingress dispatch resolves config per INSTANCE, not per session scope', () => {
  it('hands each instance its own credentials when two instances share one session scope', async () => {
    const a = instanceRow('acct-a', { apiToken: 'token-A' }, SHARED_SCOPE);
    const b = instanceRow('acct-b', { apiToken: 'token-B' }, SHARED_SCOPE);
    // Provisioning wrote both to the same scope key; the second write won.
    const { bridge, calls } = makeBridge({
      rows: [a, b],
      sessionConfig: { [SHARED_SCOPE]: { apiToken: 'token-B' } },
    });

    await bridge.dispatchWebhookForInstance(job('acct-a'));

    expect(calls).toHaveLength(1);
    expect(calls[0].config).toEqual({ apiToken: 'token-A' });
  });

  it('hands the other instance ITS credentials from the same shared scope', async () => {
    const a = instanceRow('acct-a', { apiToken: 'token-A' }, SHARED_SCOPE);
    const b = instanceRow('acct-b', { apiToken: 'token-B' }, SHARED_SCOPE);
    const { bridge, calls } = makeBridge({
      rows: [a, b],
      sessionConfig: { [SHARED_SCOPE]: { apiToken: 'token-B' } },
    });

    await bridge.dispatchWebhookForInstance(job('acct-b'));

    expect(calls[0].config).toEqual({ apiToken: 'token-B' });
  });

  /**
   * Layering the row on top corrects only the keys the row DEFINES. Every key it leaves unset falls
   * through to the layer underneath — and for two instances sharing a scope that layer is not a
   * schema default, it is the other tenant's projected config. So a sparse row, which is the normal
   * shape when an instance relies on a plugin default, still received the sibling's live value.
   *
   * The scope slice cannot be attributed to an instance once siblings exist, so it is not consulted
   * there at all. With a single instance on the scope it still applies: that slice is either that
   * instance's own projection or the operator's deliberate per-session override.
   */
  it('does not hand a sparse instance the sibling tenant value for a key it left unset', async () => {
    const a = instanceRow('acct-a', { apiToken: 'token-A', endpoint: 'https://a.example' }, SHARED_SCOPE);
    const b = instanceRow('acct-b', { apiToken: 'token-B' }, SHARED_SCOPE); // relies on the default
    const { bridge, calls } = makeBridge({
      rows: [a, b],
      baseConfig: { endpoint: 'https://default.example' },
      // acct-a was provisioned last, so the scope slice carries ITS endpoint.
      sessionConfig: { [SHARED_SCOPE]: { apiToken: 'token-A', endpoint: 'https://a.example' } },
    });

    await bridge.dispatchWebhookForInstance(job('acct-b'));

    expect(calls[0].config).toEqual({ apiToken: 'token-B', endpoint: 'https://default.example' });
  });

  // Negative twin: with no sibling the slice IS attributable, so an operator's per-session override
  // must keep applying — dropping it everywhere would break the surface it exists for.
  it('still applies the per-session override when one instance binds the scope', async () => {
    const a = instanceRow('acct-a', { apiToken: 'token-A' }, SHARED_SCOPE);
    const { bridge, calls } = makeBridge({
      rows: [a],
      baseConfig: { endpoint: 'https://default.example' },
      sessionConfig: { [SHARED_SCOPE]: { endpoint: 'https://operator.example' } },
    });

    await bridge.dispatchWebhookForInstance(job('acct-a'));

    expect(calls[0].config).toEqual({ apiToken: 'token-A', endpoint: 'https://operator.example' });
  });

  /**
   * A DISABLED sibling is not a tenant receiving deliveries, so it cannot be the one the slice was
   * projected for in any way that matters — counting it would drop the operator's override for a
   * deployment that has only one live instance.
   */
  it('a disabled sibling does not make the scope unattributable', async () => {
    const a = instanceRow('acct-a', { apiToken: 'token-A' }, SHARED_SCOPE);
    const retired = { ...instanceRow('acct-b', { apiToken: 'token-B' }, SHARED_SCOPE), enabled: false };
    const { bridge, calls } = makeBridge({
      rows: [a, retired],
      baseConfig: { endpoint: 'https://default.example' },
      sessionConfig: { [SHARED_SCOPE]: { endpoint: 'https://operator.example' } },
    });

    await bridge.dispatchWebhookForInstance(job('acct-a'));

    expect(calls[0].config).toEqual({ apiToken: 'token-A', endpoint: 'https://operator.example' });
  });

  it('keeps plugin-level defaults underneath the instance override', async () => {
    const a = instanceRow('acct-a', { apiToken: 'token-A' }, SHARED_SCOPE);
    const { bridge, calls } = makeBridge({
      rows: [a],
      // Base carries schema-seeded defaults the instance row does not repeat.
      baseConfig: { apiToken: 'unset', endpoint: 'https://default.example', retries: 3 },
      sessionConfig: { [SHARED_SCOPE]: { apiToken: 'token-A' } },
    });

    await bridge.dispatchWebhookForInstance(job('acct-a'));

    expect(calls[0].config).toEqual({
      apiToken: 'token-A',
      endpoint: 'https://default.example',
      retries: 3,
    });
  });

  it('merges the instance config deeply, so a sparse override cannot drop a nested base key', async () => {
    const a = instanceRow('acct-a', { auth: { token: 'token-A' } }, SHARED_SCOPE);
    const { bridge, calls } = makeBridge({
      rows: [a],
      // `auth.region` exists only in the base; a shallow merge would delete it.
      baseConfig: { auth: { token: 'unset', region: 'eu-west-1' } },
    });

    await bridge.dispatchWebhookForInstance(job('acct-a'));

    expect(calls[0].config).toEqual({
      auth: { token: 'token-A', region: 'eu-west-1' },
    });
  });

  it('falls back to the base config when the instance row carries none', async () => {
    const a = instanceRow('acct-a', null, SHARED_SCOPE);
    const { bridge, calls } = makeBridge({
      rows: [a],
      baseConfig: { endpoint: 'https://default.example' },
    });

    await bridge.dispatchWebhookForInstance(job('acct-a'));

    expect(calls[0].config).toEqual({ endpoint: 'https://default.example' });
  });

  it('isolates instances of a plugin that is NOT session-scoped', async () => {
    // sessionScoped:false previously skipped the override entirely, so every instance of such a
    // plugin was dispatched with one shared config.
    const a = instanceRow('acct-a', { apiToken: 'token-A' }, null);
    const b = instanceRow('acct-b', { apiToken: 'token-B' }, null);
    const { bridge, calls } = makeBridge({
      rows: [a, b],
      baseConfig: { apiToken: 'token-B' },
      manifestOverrides: { sessionScoped: false },
    });

    await bridge.dispatchWebhookForInstance(job('acct-a', null));

    expect(calls[0].config).toEqual({ apiToken: 'token-A' });
  });
});

describe('ingress dispatch does not carry a base secret to another host', () => {
  // An adapter that calls the host named in `baseUrl` with a stored token. A key that may create an
  // instance on one session, or write that session's override, picks the host; the token is the
  // operator's and belongs to the host it was saved for.
  const adapter: Partial<PluginManifest> = {
    net: { allowConfigHosts: ['baseUrl'] },
    configSchema: {
      type: 'object',
      properties: { baseUrl: { type: 'string' }, apiToken: { type: 'string', secret: true } },
    },
  };
  const baseConfig = { baseUrl: 'https://chat.example.com', apiToken: 'OPERATOR-TOKEN' };

  it('withholds the operator token from an instance that names its own host', async () => {
    const tenant = instanceRow('tenant', { baseUrl: 'https://attacker.example' }, 'S1');
    const { bridge, calls } = makeBridge({ rows: [tenant], baseConfig, manifestOverrides: adapter });

    await bridge.dispatchWebhookForInstance(job('tenant', 'S1'));

    expect(calls[0].config).toEqual({ baseUrl: 'https://attacker.example' });
  });

  it('withholds it from an instance on a session whose override names another host', async () => {
    const tenant = instanceRow('tenant', null, 'S1');
    const { bridge, calls } = makeBridge({
      rows: [tenant],
      baseConfig,
      sessionConfig: { S1: { baseUrl: 'https://attacker.example' } },
      manifestOverrides: adapter,
    });

    await bridge.dispatchWebhookForInstance(job('tenant', 'S1'));

    expect(calls[0].config).toEqual({ baseUrl: 'https://attacker.example' });
  });

  // The row's token was provisioned against the operator host. An override written for the same session by a
  // key that cannot read it must not be able to move the host and take the row's token along.
  it('withholds the token an instance holds itself when a session override moved the host', async () => {
    const tenant = instanceRow('tenant', { apiToken: 'TENANT-TOKEN', inboxId: '9' }, 'S1');
    const { bridge, calls } = makeBridge({
      rows: [tenant],
      baseConfig,
      sessionConfig: { S1: { baseUrl: 'https://attacker.example' } },
      manifestOverrides: adapter,
    });

    await bridge.dispatchWebhookForInstance(job('tenant', 'S1'));

    expect(calls[0].config).toEqual({ baseUrl: 'https://attacker.example', inboxId: '9' });
  });

  it('keeps the token an instance holds itself when the override left the host alone', async () => {
    const tenant = instanceRow('tenant', { apiToken: 'TENANT-TOKEN' }, 'S1');
    const { bridge, calls } = makeBridge({
      rows: [tenant],
      baseConfig,
      sessionConfig: { S1: { baseUrl: 'https://chat.example.com/' } },
      manifestOverrides: adapter,
    });

    await bridge.dispatchWebhookForInstance(job('tenant', 'S1'));

    expect(calls[0].config).toMatchObject({ apiToken: 'TENANT-TOKEN' });
  });

  it('keeps the token for an instance that names the operator host or none', async () => {
    const same = instanceRow('same', { baseUrl: 'https://chat.example.com/other' }, 'S1');
    const none = instanceRow('none', {}, 'S2');
    const { bridge, calls } = makeBridge({ rows: [same, none], baseConfig, manifestOverrides: adapter });

    await bridge.dispatchWebhookForInstance(job('same', 'S1'));
    await bridge.dispatchWebhookForInstance(job('none', 'S2'));

    expect(calls[0].config).toMatchObject({ apiToken: 'OPERATOR-TOKEN' });
    expect(calls[1].config).toEqual(baseConfig);
  });

  it('hands an instance the token it brings for its own host', async () => {
    const tenant = instanceRow('tenant', { baseUrl: 'https://other.example', apiToken: 'TENANT-TOKEN' }, 'S1');
    const { bridge, calls } = makeBridge({ rows: [tenant], baseConfig, manifestOverrides: adapter });

    await bridge.dispatchWebhookForInstance(job('tenant', 'S1'));

    expect(calls[0].config).toEqual({ baseUrl: 'https://other.example', apiToken: 'TENANT-TOKEN' });
  });
});

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', null))).rejects.toThrow(
      'instance acct-a of plugin chat-adapter is disabled or deleted',
    );
    expect(calls).toHaveLength(0);
  });
});

const route = (scheme: 'none' | 'hmac-sha256') => ({
  route: '/hook',
  mode: 'async' as const,
  verify: 'core' as const,
  maxBodyBytes: 1024,
  signature: scheme === 'none' ? { scheme: 'none' as const } : { scheme: 'hmac-sha256' as const, header: 'x-sig' },
});

describe('ingress dispatch keeps what was decided when the delivery was admitted', () => {
  const row = () => instanceRow('acct-a', { apiToken: 'token-A' }, 'S1');

  it('does not label an unauthenticated delivery verified after its route starts signing', async () => {
    const { bridge, calls } = makeBridge({
      rows: [row()],
      manifestOverrides: { ingress: [route('hmac-sha256')] },
    });

    await bridge.dispatchWebhookForInstance(job('acct-a', 'S1', { verified: false }));

    expect(calls[0].verified).toBe(false);
  });

  it('keeps an authenticated delivery verified after its route stops signing', async () => {
    const { bridge, calls } = makeBridge({
      rows: [row()],
      manifestOverrides: { ingress: [route('none')] },
    });

    await bridge.dispatchWebhookForInstance(job('acct-a', 'S1', { verified: true }));

    expect(calls[0].verified).toBe(true);
  });

  it('still never labels a delivery verified when its route is gone', async () => {
    const { bridge, calls } = makeBridge({ rows: [row()] });

    await bridge.dispatchWebhookForInstance(job('acct-a', 'S1', { verified: true }));

    expect(calls[0].verified).toBe(false);
  });

  it.each([
    ['signing', 'hmac-sha256', true],
    ['unsigned', 'none', false],
  ] as const)(
    'reads the route for a delivery admitted before the verdict was recorded (%s)',
    async (_l, scheme, want) => {
      const { bridge, calls } = makeBridge({
        rows: [row()],
        manifestOverrides: { ingress: [route(scheme)] },
      });

      await bridge.dispatchWebhookForInstance(job('acct-a', 'S1'));

      expect(calls[0].verified).toBe(want);
    },
  );

  it('refuses a delivery admitted for a session the instance has since left', async () => {
    const rebound = instanceRow('acct-a', { apiToken: 'token-A' }, 'S-new');
    const { bridge, calls } = makeBridge({ rows: [rebound], sessionConfig: { 'S-new': { endpoint: 'https://new' } } });

    await expect(bridge.dispatchWebhookForInstance(job('acct-a', 'S-old'))).rejects.toThrow(/rebound/);
    expect(calls).toHaveLength(0);
  });

  it('treats null, undefined and * as the one all-sessions scope', async () => {
    const wildcard = instanceRow('acct-a', { apiToken: 'token-A' }, '*');
    const { bridge, calls } = makeBridge({ rows: [wildcard] });

    await bridge.dispatchWebhookForInstance(job('acct-a', null));
    await bridge.dispatchWebhookForInstance(job('acct-a', '*'));

    expect(calls).toHaveLength(2);
  });

  it('refuses a delivery admitted for all sessions once the instance is bound to one', async () => {
    const { bridge, calls } = makeBridge({ rows: [row()] });

    await expect(bridge.dispatchWebhookForInstance(job('acct-a', null))).rejects.toThrow(/rebound/);
    expect(calls).toHaveLength(0);
  });
});