Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

17.8 KB
Raw Blame
import {
  validateIngressManifest,
  SUPPORTED_SDK_MAJOR,
  warnUnauthenticatedIngressRoutes,
  warnUnsignedTimestampRoutes,
} from './plugin.interfaces';

const baseManifest = () => ({
  id: 'chatwoot',
  name: 'Chatwoot',
  version: '1.0.0',
  main: 'index.js',
  sdkVersion: '1',
  permissions: ['webhook:ingress', 'conversation:send', 'net:fetch'],
  ingress: [
    {
      route: 'chatwoot',
      mode: 'async',
      verify: 'core',
      maxBodyBytes: 262144,
      signature: {
        scheme: 'hmac-sha256',
        header: 'X-Chatwoot-Signature',
        contentTemplate: '{rawBody}',
        encoding: 'hex',
        toleranceSec: 300,
        dedupHeader: 'X-Chatwoot-Delivery',
      },
    },
  ],
});

describe('validateIngressManifest', () => {
  it('accepts a well-formed sdkVersion 1 ingress manifest', () => {
    expect(() => validateIngressManifest(baseManifest() as never)).not.toThrow();
  });

  it('refuses a plugin whose declared SDK major differs from the host major', () => {
    const m = baseManifest();
    m.sdkVersion = '2';
    expect(() => validateIngressManifest(m as never)).toThrow(/sdk.*major/i);
    expect(SUPPORTED_SDK_MAJOR).toBe(1);
  });

  it('rejects an ingress route declared without the webhook:ingress permission', () => {
    const m = baseManifest();
    m.permissions = ['conversation:send'];
    expect(() => validateIngressManifest(m as never)).toThrow(/webhook:ingress/);
  });

  it('the ingress refusal names the array and the manifest file to fix', () => {
    // Load-time twin of the capability denial: an author who sees only "is missing the
    // 'webhook:ingress' permission" is told the fault, not where to declare it.
    const m = baseManifest();
    m.permissions = ['conversation:send'];
    const error = (() => {
      try {
        validateIngressManifest(m as never);
        return null;
      } catch (e) {
        return e as Error;
      }
    })();
    expect(error?.message).toContain('webhook:ingress');
    expect(error?.message).toContain('permissions');
    expect(error?.message).toContain('manifest.json');
  });

  it('rejects toleranceSec <= 0 (replay guard would be a no-op)', () => {
    const m = baseManifest();
    m.ingress[0].signature.toleranceSec = 0;
    expect(() => validateIngressManifest(m as never)).toThrow(/toleranceSec/);
  });

  it('rejects a toleranceSec that is not a finite number, which would disable the replay window', () => {
    for (const tol of ['5m', '300s', '', {}, true, [], null, JSON.parse('1e999') as number]) {
      for (const scheme of ['hmac-sha256', 'standard-webhooks']) {
        const m = baseManifest();
        m.ingress[0].signature.scheme = scheme;
        (m.ingress[0].signature as { toleranceSec?: unknown }).toleranceSec = tol;
        expect(() => validateIngressManifest(m as never)).toThrow(/toleranceSec/);
      }
    }
  });

  it('still loads a numeric toleranceSec, quoted or not', () => {
    for (const tol of [300, '300']) {
      const m = baseManifest();
      (m.ingress[0].signature as { toleranceSec?: unknown }).toleranceSec = tol;
      expect(() => validateIngressManifest(m as never)).not.toThrow();
    }
  });

  it('rejects a route that is not a single URL path segment', () => {
    for (const route of ['events/message', '/hook', 'a\\b', 'a?b', 'a#b', 'a%2Fb', 'a\nb', '.', '..']) {
      const m = baseManifest();
      m.ingress[0].route = route;
      expect(() => validateIngressManifest(m as never)).toThrow(/single URL path segment/);
    }
    // A space or a non-ASCII letter is percent-encoded by the client and decoded before the match.
    for (const route of ['send-sms', 'chatwoot', 'v1.events', 'a_b~c', 'a b', 'café', '...']) {
      const m = baseManifest();
      m.ingress[0].route = route;
      expect(() => validateIngressManifest(m as never)).not.toThrow();
    }
  });

  it('rejects a route holding a lone UTF-16 surrogate (no URL can encode or decode to it)', () => {
    for (const route of ['\ud800', 'a\udc00b', 'x\ud83d']) {
      const m = baseManifest();
      m.ingress[0].route = route;
      expect(() => validateIngressManifest(m as never)).toThrow(/single URL path segment/);
    }
    // A well-formed surrogate pair is an ordinary astral character.
    const m = baseManifest();
    m.ingress[0].route = 'hook-\ud83d\ude80';
    expect(() => validateIngressManifest(m as never)).not.toThrow();
  });

  it('rejects a dedupOn value other than header or body', () => {
    const m = baseManifest();
    (m.ingress[0] as { dedupOn?: string }).dedupOn = 'bdy';
    expect(() => validateIngressManifest(m as never)).toThrow(/dedupOn/);
  });

  it('accepts dedupOn: body', () => {
    const m = baseManifest();
    (m.ingress[0] as { dedupOn?: string }).dedupOn = 'body';
    expect(() => validateIngressManifest(m as never)).not.toThrow();
  });

  // An unknown scheme used to load and then fail every delivery as a signature mismatch, with nothing
  // pointing at the manifest; a missing signature object failed the load with a bare TypeError.
  it.each(['hmac_sha256', 'HMAC-SHA256', 'standard-webhook', undefined])(
    'rejects signature.scheme %p, naming the route',
    scheme => {
      const m = baseManifest();
      (m.ingress[0].signature as { scheme?: string }).scheme = scheme;
      expect(() => validateIngressManifest(m as never)).toThrow(/route 'chatwoot' signature\.scheme must be one of/);
    },
  );

  it('rejects a route with no signature object as a manifest error', () => {
    const m = baseManifest();
    delete (m.ingress[0] as { signature?: unknown }).signature;
    expect(() => validateIngressManifest(m as never)).toThrow(/route 'chatwoot' signature\.scheme must be one of/);
  });

  it('rejects an hmac-sha256 signature.encoding other than hex or base64', () => {
    const m = baseManifest();
    (m.ingress[0].signature as { encoding?: string }).encoding = 'b64';
    expect(() => validateIngressManifest(m as never)).toThrow(/route 'chatwoot' signature\.encoding must be/);
  });

  // Only hmac-sha256 reads `encoding`, so a stray value on another scheme must not fail the plugin's load.
  it.each(['shared-secret', 'standard-webhooks'])('ignores signature.encoding on a %s route', scheme => {
    const m = baseManifest();
    m.ingress[0].signature.scheme = scheme;
    (m.ingress[0].signature as { encoding?: string }).encoding = 'b64';
    expect(() => validateIngressManifest(m as never)).not.toThrow();
  });

  it('accepts every declared scheme', () => {
    for (const scheme of ['hmac-sha256', 'shared-secret', 'standard-webhooks', 'none']) {
      const m = baseManifest();
      m.ingress[0].signature.scheme = scheme;
      expect(() => validateIngressManifest(m as never, true)).not.toThrow();
    }
  });

  it('rejects a duplicate route within one manifest', () => {
    const m = baseManifest();
    m.ingress.push({ ...m.ingress[0] });
    expect(() => validateIngressManifest(m as never)).toThrow(/duplicate/i);
  });
});

describe('validateIngressManifest: signature.scheme "none" opt-in gate', () => {
  // A none-scheme route is an unauthenticated @Public endpoint that can trigger WhatsApp sends.
  // It must be rejected at load unless the operator explicitly opted in via ALLOW_UNSIGNED_INGRESS.
  const noneManifest = () =>
    ({
      id: 'p',
      name: 'p',
      version: '1.0.0',
      type: 'extension',
      main: 'index.js',
      sdkVersion: '1',
      permissions: ['webhook:ingress'],
      ingress: [{ route: 'r', mode: 'async', verify: 'core', maxBodyBytes: 1024, signature: { scheme: 'none' } }],
    }) as never;

  it('rejects a none-scheme route by default (no opt-in)', () => {
    expect(() => validateIngressManifest(noneManifest())).toThrow(/ALLOW_UNSIGNED_INGRESS/i);
    expect(() => validateIngressManifest(noneManifest())).toThrow(/unauthenticated/i);
  });

  it('rejects a none-scheme route when explicitly passed allowUnsignedIngress=false', () => {
    expect(() => validateIngressManifest(noneManifest(), false)).toThrow(/ALLOW_UNSIGNED_INGRESS/i);
  });

  it('accepts a none-scheme route when the operator opted in (allowUnsignedIngress=true)', () => {
    expect(() => validateIngressManifest(noneManifest(), true)).not.toThrow();
  });

  it('still accepts signed routes regardless of the opt-in flag', () => {
    expect(() => validateIngressManifest(baseManifest() as never, false)).not.toThrow();
    expect(() => validateIngressManifest(baseManifest() as never, true)).not.toThrow();
  });
});

describe('warnUnauthenticatedIngressRoutes', () => {
  it('warns once per scheme:none route, naming the plugin and route', () => {
    const logger = { warn: jest.fn() };
    const m = baseManifest();
    (m.ingress[0].signature as { scheme: string }).scheme = 'none';
    warnUnauthenticatedIngressRoutes(m as never, logger);
    expect(logger.warn).toHaveBeenCalledTimes(1);
    expect(logger.warn).toHaveBeenCalledWith(
      expect.stringMatching(/UNAUTHENTICATED/i),
      expect.objectContaining({ pluginId: 'chatwoot', route: 'chatwoot', action: 'ingress_unauthenticated_route' }),
    );
  });

  it('does not warn for an authenticated scheme', () => {
    const logger = { warn: jest.fn() };
    warnUnauthenticatedIngressRoutes(baseManifest() as never, logger);
    expect(logger.warn).not.toHaveBeenCalled();
  });

  it('is a no-op for a manifest with no ingress routes', () => {
    const logger = { warn: jest.fn() };
    warnUnauthenticatedIngressRoutes({ id: 'x', name: 'X', version: '1.0.0', main: 'i.js' } as never, logger);
    expect(logger.warn).not.toHaveBeenCalled();
  });
});

describe('warnUnsignedTimestampRoutes', () => {
  const hmacRoute = (signature: Record<string, unknown>) => ({
    id: 'p',
    name: 'p',
    version: '1.0.0',
    main: 'index.js',
    sdkVersion: '1',
    permissions: ['webhook:ingress'],
    ingress: [{ route: 'r', mode: 'async', verify: 'core', maxBodyBytes: 1024, signature }],
  });

  it('warns when a timestampHeader is declared but the contentTemplate does not sign it', () => {
    const logger = { warn: jest.fn() };
    warnUnsignedTimestampRoutes(
      hmacRoute({
        scheme: 'hmac-sha256',
        header: 'X-Sig',
        contentTemplate: '{rawBody}',
        timestampHeader: 'X-Ts',
      }) as never,
      logger,
    );
    expect(logger.warn).toHaveBeenCalledTimes(1);
    expect(logger.warn).toHaveBeenCalledWith(
      expect.stringMatching(/UNSIGNED/i),
      expect.objectContaining({ pluginId: 'p', route: 'r', action: 'ingress_unsigned_timestamp' }),
    );
  });

  it('warns when the contentTemplate signs {timestamp} but no timestampHeader is declared', () => {
    const logger = { warn: jest.fn() };
    warnUnsignedTimestampRoutes(
      hmacRoute({ scheme: 'hmac-sha256', header: 'X-Sig', contentTemplate: '{timestamp}.{rawBody}' }) as never,
      logger,
    );
    expect(logger.warn).toHaveBeenCalledTimes(1);
    expect(logger.warn).toHaveBeenCalledWith(
      expect.stringMatching(/no timestampHeader/i),
      expect.objectContaining({ pluginId: 'p', route: 'r', action: 'ingress_unsigned_timestamp' }),
    );
  });

  it('stays silent when the declared timestamp is signed (the bound form)', () => {
    const logger = { warn: jest.fn() };
    warnUnsignedTimestampRoutes(
      hmacRoute({
        scheme: 'hmac-sha256',
        header: 'X-Sig',
        contentTemplate: '{timestamp}.{rawBody}',
        timestampHeader: 'X-Ts',
        toleranceSec: 300,
      }) as never,
      logger,
    );
    expect(logger.warn).not.toHaveBeenCalled();
  });

  const withDedupOnBody = (manifest: ReturnType<typeof hmacRoute>) => ({
    ...manifest,
    ingress: manifest.ingress.map(route => ({ ...route, dedupOn: 'body' })),
  });

  it('warns once when an hmac route binds no timestamp and dedups on its header', () => {
    const logger = { warn: jest.fn() };
    warnUnsignedTimestampRoutes(
      hmacRoute({ scheme: 'hmac-sha256', header: 'X-Sig', contentTemplate: '{rawBody}' }) as never,
      logger,
    );
    expect(logger.warn).toHaveBeenCalledTimes(1);
    expect(logger.warn).toHaveBeenCalledWith(
      expect.stringMatching(/dedupOn: 'body'/),
      expect.objectContaining({ pluginId: 'p', route: 'r', action: 'ingress_replayable_route' }),
    );
  });

  it('stays silent for an hmac route without a timestamp that dedups on the body', () => {
    const logger = { warn: jest.fn() };
    warnUnsignedTimestampRoutes(
      withDedupOnBody(hmacRoute({ scheme: 'hmac-sha256', header: 'X-Sig', contentTemplate: '{rawBody}' })) as never,
      logger,
    );
    expect(logger.warn).not.toHaveBeenCalled();
  });

  it('warns for a shared-secret route unless it dedups on the body', () => {
    const logger = { warn: jest.fn() };
    const route = hmacRoute({ scheme: 'shared-secret', header: 'X-Token', timestampHeader: 'X-Ts' });
    warnUnsignedTimestampRoutes(route as never, logger);
    expect(logger.warn).toHaveBeenCalledTimes(1);
    expect(logger.warn).toHaveBeenCalledWith(
      expect.stringMatching(/shared-secret/),
      expect.objectContaining({ pluginId: 'p', route: 'r', action: 'ingress_replayable_route' }),
    );

    logger.warn.mockClear();
    warnUnsignedTimestampRoutes(withDedupOnBody(route) as never, logger);
    expect(logger.warn).not.toHaveBeenCalled();
  });

  it('ignores standard-webhooks (its dedup id and timestamp are signed)', () => {
    const logger = { warn: jest.fn() };
    warnUnsignedTimestampRoutes(hmacRoute({ scheme: 'standard-webhooks', dedupHeader: 'webhook-id' }) as never, logger);
    expect(logger.warn).not.toHaveBeenCalled();
  });
});

function manifestWithRoute(overrides: Record<string, unknown> = {}) {
  return {
    id: 'p',
    name: 'p',
    version: '1.0.0',
    type: 'extension',
    main: 'index.js',
    sdkVersion: '1',
    permissions: ['webhook:ingress'],
    ingress: [
      // Default to a signed scheme so the response-contract / standard-webhooks suites below
      // exercise fields other than the scheme. The scheme:'none' opt-in gate has its own block.
      {
        route: 'r',
        mode: 'async',
        verify: 'core',
        maxBodyBytes: 1024,
        signature: { scheme: 'hmac-sha256', header: 'X-Sig', contentTemplate: '{rawBody}', encoding: 'hex' },
        ...overrides,
      },
    ],
  } as never;
}

describe('validateIngressManifest: response contract', () => {
  it('accepts a route with no response (default fast-ack)', () => {
    expect(() => validateIngressManifest(manifestWithRoute())).not.toThrow();
  });

  it('accepts a valid response contract', () => {
    expect(() =>
      validateIngressManifest(
        manifestWithRoute({
          response: {
            preflight: [{ type: 'session-alive' }],
            ack: { status: 200, body: '{"ok":true}', headers: { 'content-type': 'application/json' } },
          },
        }),
      ),
    ).not.toThrow();
  });

  it('rejects an out-of-range ack.status', () => {
    expect(() => validateIngressManifest(manifestWithRoute({ response: { ack: { status: 99 } } }))).toThrow(
      /ack\.status/,
    );
    expect(() => validateIngressManifest(manifestWithRoute({ response: { ack: { status: 600 } } }))).toThrow(
      /ack\.status/,
    );
  });

  it('rejects a CR/LF in an ack header value (injection guard)', () => {
    expect(() =>
      validateIngressManifest(
        manifestWithRoute({ response: { ack: { headers: { 'content-type': 'text/plain\r\nX-Injected: yes' } } } }),
      ),
    ).toThrow(/invalid characters/);
  });

  it('rejects a 1xx ack.status, which Node sends with no final response after it', () => {
    for (const status of [100, 103, 199]) {
      expect(() => validateIngressManifest(manifestWithRoute({ response: { ack: { status } } }))).toThrow(
        /ack\.status/,
      );
    }
    expect(() => validateIngressManifest(manifestWithRoute({ response: { ack: { status: 200 } } }))).not.toThrow();
  });

  it('rejects an ack header value Node cannot write, and keeps Latin-1 and HTAB', () => {
    for (const value of ['ok \u2713', 'a\u0000b', 'a\u007fb', 'a\u001bb']) {
      expect(() =>
        validateIngressManifest(manifestWithRoute({ response: { ack: { headers: { 'x-note': value } } } })),
      ).toThrow(/invalid characters/);
    }
    for (const value of ['caf\u00e9', 'a\tb']) {
      expect(() =>
        validateIngressManifest(manifestWithRoute({ response: { ack: { headers: { 'x-note': value } } } })),
      ).not.toThrow();
    }
  });

  it('rejects a non-string ack body', () => {
    // A manifest is third-party JSON. Left unchecked, a number or object here reached the renderer,
    // which drops anything that is not a string, so the route answered every delivery with an EMPTY
    // ack while the manifest read as if it declared one.
    expect(() =>
      validateIngressManifest(manifestWithRoute({ response: { ack: { body: 42 as unknown as string } } })),
    ).toThrow(/ack\.body/);
  });

  it('rejects a non-string ack header value', () => {
    // Same silent drop, and the character guard does not catch it: RegExp.test coerces its
    // argument, so a number passes the injection check and is then filtered out at render time.
    expect(() =>
      validateIngressManifest(
        manifestWithRoute({ response: { ack: { headers: { 'x-retry': 5 as unknown as string } } } }),
      ),
    ).toThrow(/'x-retry'/);
  });

  it('rejects a non-token ack header name', () => {
    expect(() =>
      validateIngressManifest(manifestWithRoute({ response: { ack: { headers: { 'bad header': 'x' } } } })),
    ).toThrow(/'bad header'/);
  });
});

describe('validateIngressManifest: standard-webhooks scheme', () => {
  it('loads a standard-webhooks route without header/contentTemplate', () => {
    expect(() =>
      validateIngressManifest(
        manifestWithRoute({ signature: { scheme: 'standard-webhooks', dedupHeader: 'webhook-id' } }),
      ),
    ).not.toThrow();
  });

  it('rejects a standard-webhooks route with a non-positive toleranceSec', () => {
    expect(() =>
      validateIngressManifest(
        manifestWithRoute({ signature: { scheme: 'standard-webhooks', dedupHeader: 'webhook-id', toleranceSec: 0 } }),
      ),
    ).toThrow(/toleranceSec/);
  });
});