Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

13.3 KB
Raw Blame
import type { ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ThrottlerException, ThrottlerStorageService } from '@nestjs/throttler';
import { ProxyAwareThrottlerGuard } from './proxy-aware-throttler.guard';

/**
 * Regression lock: the throttler must bucket on the resolved client IP, not the
 * proxy IP — so one abusive client cannot rate-limit everyone behind a reverse proxy.
 */
const reqFrom = (socketIp: string, xff?: string): unknown => ({
  ip: socketIp,
  socket: { remoteAddress: socketIp },
  headers: xff !== undefined ? { 'x-forwarded-for': xff } : {},
});

describe('ProxyAwareThrottlerGuard.getTracker', () => {
  const orig = process.env.TRUSTED_PROXIES;
  // The shared instance below trips the shared-bucket warning once (first test sends an XFF);
  // silence it so the suite output stays clean; the warning itself has its own describe below.
  let warn: jest.SpyInstance;
  beforeEach(() => {
    warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
  });
  afterEach(() => warn.mockRestore());

  // getTracker uses process.env, resolveClientIp, and this.ipv6SubnetPrefix (which defaults to
  // 64 when undefined), so we can invoke it on a prototype instance without the throttler's
  // storage/reflector deps.
  const guard = Object.create(ProxyAwareThrottlerGuard.prototype) as ProxyAwareThrottlerGuard;
  const track = (req: unknown): Promise<string> =>
    (guard as unknown as { getTracker(r: unknown): Promise<string> }).getTracker(req);

  afterEach(() => {
    if (orig === undefined) delete process.env.TRUSTED_PROXIES;
    else process.env.TRUSTED_PROXIES = orig;
  });

  it('with no trusted proxies, keys on the socket IP and ignores a spoofed XFF', async () => {
    delete process.env.TRUSTED_PROXIES;
    expect(await track(reqFrom('203.0.113.9', '1.1.1.1'))).toBe('203.0.113.9');
  });

  it('with a trusted proxy peer, keys on the real forwarded client IP', async () => {
    process.env.TRUSTED_PROXIES = '172.18.0.0/16';
    expect(await track(reqFrom('172.18.0.5', '203.0.113.9'))).toBe('203.0.113.9');
  });

  it('gives two distinct forwarded clients independent buckets', async () => {
    process.env.TRUSTED_PROXIES = '172.18.0.0/16';
    const a = await track(reqFrom('172.18.0.5', '203.0.113.9'));
    const b = await track(reqFrom('172.18.0.5', '198.51.100.7'));
    expect(a).not.toBe(b);
  });

  it('ignores XFF from an untrusted peer (anti-spoof)', async () => {
    process.env.TRUSTED_PROXIES = '172.18.0.0/16';
    // peer 203.0.113.9 is NOT a trusted proxy → its XFF is ignored, key on the socket IP
    expect(await track(reqFrom('203.0.113.9', '10.0.0.1'))).toBe('203.0.113.9');
  });

  it('masks directly connected IPv6 clients to a /64 so addresses in the same subnet share a tracker', async () => {
    delete process.env.TRUSTED_PROXIES;
    const a = await track(reqFrom('2001:db8:0:1::1'));
    const b = await track(reqFrom('2001:db8:0:1:dead:beef:1:2'));
    expect(a).toBe('2001:db8:0:1::/64');
    expect(b).toBe('2001:db8:0:1::/64');
    expect(a).toBe(b);
  });

  it('gives directly connected IPv6 clients in different /64 subnets independent buckets', async () => {
    delete process.env.TRUSTED_PROXIES;
    const a = await track(reqFrom('2001:db8:0:1::1'));
    const b = await track(reqFrom('2001:db8:0:2::1'));
    expect(a).toBe('2001:db8:0:1::/64');
    expect(b).toBe('2001:db8:0:2::/64');
    expect(a).not.toBe(b);
  });

  it('masks forwarded IPv6 clients behind a trusted proxy to a /64', async () => {
    process.env.TRUSTED_PROXIES = '172.18.0.0/16';
    const a = await track(reqFrom('172.18.0.5', '2001:db8:0:1::1'));
    const b = await track(reqFrom('172.18.0.5', '2001:db8:0:1::2'));
    const c = await track(reqFrom('172.18.0.5', '2001:db8:0:2::1'));
    expect(a).toBe('2001:db8:0:1::/64');
    expect(b).toBe('2001:db8:0:1::/64');
    expect(a).toBe(b);
    expect(c).toBe('2001:db8:0:2::/64');
    expect(a).not.toBe(c);
  });

  it('leaves IPv4, IPv4-mapped, and loopback addresses unchanged', async () => {
    delete process.env.TRUSTED_PROXIES;
    expect(await track(reqFrom('203.0.113.9'))).toBe('203.0.113.9');
    expect(await track(reqFrom('::ffff:203.0.113.9'))).toBe('203.0.113.9');
    expect(await track(reqFrom('::1'))).toBe('::1');
  });

  it('honors a custom ipv6SubnetPrefix configured on the guard', async () => {
    delete process.env.TRUSTED_PROXIES;
    const customGuard = Object.create(ProxyAwareThrottlerGuard.prototype) as ProxyAwareThrottlerGuard;
    Object.assign(customGuard, { ipv6SubnetPrefix: 48 });
    const trackCustom = (req: unknown): Promise<string> =>
      (customGuard as unknown as { getTracker(r: unknown): Promise<string> }).getTracker(req);
    expect(await trackCustom(reqFrom('2001:db8:0:1::1'))).toBe('2001:db8::/48');
  });
});

/**
 * An X-Forwarded-For header with an empty TRUSTED_PROXIES is the deployment-wide shared-bucket
 * condition (every client keys on the proxy address); it must surface as a one-time warning rather
 * than stay silent. The header stays untrusted either way; the fix is operator-side.
 */
describe('ProxyAwareThrottlerGuard shared-bucket warning', () => {
  const orig = process.env.TRUSTED_PROXIES;
  let warn: jest.SpyInstance;

  const trackOn = (guard: unknown, req: unknown): Promise<string> =>
    (guard as { getTracker(r: unknown): Promise<string> }).getTracker(req);

  beforeEach(() => {
    warn = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
  });
  afterEach(() => {
    warn.mockRestore();
    if (orig === undefined) delete process.env.TRUSTED_PROXIES;
    else process.env.TRUSTED_PROXIES = orig;
  });

  it('warns exactly once when a proxied request arrives with no trusted proxies', async () => {
    delete process.env.TRUSTED_PROXIES;
    const guard = Object.create(ProxyAwareThrottlerGuard.prototype) as ProxyAwareThrottlerGuard;

    expect(await trackOn(guard, reqFrom('172.18.0.5', '203.0.113.9'))).toBe('172.18.0.5');
    expect(await trackOn(guard, reqFrom('172.18.0.5', '198.51.100.7'))).toBe('172.18.0.5');

    expect(warn).toHaveBeenCalledTimes(1);
    expect(String(warn.mock.calls[0])).toContain('TRUSTED_PROXIES is empty');
  });

  it('stays silent when the proxy is trusted', async () => {
    process.env.TRUSTED_PROXIES = '172.18.0.0/16';
    const guard = Object.create(ProxyAwareThrottlerGuard.prototype) as ProxyAwareThrottlerGuard;

    expect(await trackOn(guard, reqFrom('172.18.0.5', '203.0.113.9'))).toBe('203.0.113.9');
    expect(warn).not.toHaveBeenCalled();
  });

  it('warns for an empty-string XFF header too (a stripped header still means a proxy hop)', async () => {
    delete process.env.TRUSTED_PROXIES;
    const guard = Object.create(ProxyAwareThrottlerGuard.prototype) as ProxyAwareThrottlerGuard;

    expect(await trackOn(guard, reqFrom('172.18.0.5', ''))).toBe('172.18.0.5');

    expect(warn).toHaveBeenCalledTimes(1);
  });

  it('stays silent for direct traffic with no XFF header', async () => {
    delete process.env.TRUSTED_PROXIES;
    const guard = Object.create(ProxyAwareThrottlerGuard.prototype) as ProxyAwareThrottlerGuard;

    expect(await trackOn(guard, reqFrom('203.0.113.9'))).toBe('203.0.113.9');
    expect(warn).not.toHaveBeenCalled();
  });
});

/**
 * Regression lock: a bare `@SkipThrottle()` must actually exempt the route.
 *
 * The decorator writes ONE metadata key, `THROTTLER:SKIP` + the key of its argument object, which
 * defaults to `{ default: true }`. The base guard reads `THROTTLER:SKIP` + the name of each
 * CONFIGURED tier, and this application names its tiers `short`, `medium` and `long`. The two
 * spellings never intersect, so a bare decorator writes a key nothing reads and the route stays
 * throttled. Unlike the tier loop, `shouldSkip` runs before any tier is evaluated, so honouring the
 * library's default key here exempts the route from every tier and from the storage round-trip each
 * one would perform.
 *
 * These cases instantiate the guard properly rather than via `Object.create`: unlike `getTracker`,
 * `shouldSkip` reads `this.reflector`.
 */
describe('ProxyAwareThrottlerGuard.shouldSkip', () => {
  const LIBRARY_DEFAULT_SKIP_KEY = 'THROTTLER:SKIPdefault';

  const handler = (): void => undefined;
  class Controller {}
  const context = {
    getHandler: () => handler,
    getClass: () => Controller,
  } as unknown as ExecutionContext;

  function guardReading(metadata: boolean | undefined): {
    skip: () => Promise<boolean>;
    reflector: { getAllAndOverride: jest.Mock };
  } {
    const reflector = { getAllAndOverride: jest.fn().mockReturnValue(metadata) };
    type GuardArgs = ConstructorParameters<typeof ProxyAwareThrottlerGuard>;
    const guard = new ProxyAwareThrottlerGuard(
      { throttlers: [] },
      {} as GuardArgs[1],
      reflector as unknown as Reflector,
    );
    const skip = (): Promise<boolean> =>
      (guard as unknown as { shouldSkip(c: ExecutionContext): Promise<boolean> }).shouldSkip(context);
    return { skip, reflector };
  }

  it('exempts a route whose bare @SkipThrottle() wrote the library default key', async () => {
    const { skip } = guardReading(true);
    expect(await skip()).toBe(true);
  });

  it('reads the key the library actually writes, on handler then class', async () => {
    const { skip, reflector } = guardReading(true);
    await skip();
    expect(reflector.getAllAndOverride).toHaveBeenCalledWith(LIBRARY_DEFAULT_SKIP_KEY, [handler, Controller]);
  });

  it('does not exempt a route carrying no skip metadata', async () => {
    const { skip } = guardReading(undefined);
    expect(await skip()).toBe(false);
  });

  it('does not exempt an explicit opt-out — @SkipThrottle({ default: false })', async () => {
    const { skip } = guardReading(false);
    expect(await skip()).toBe(false);
  });
});

/**
 * The library writes only `Retry-After-<tier>`, a spelling no HTTP client reads, so a shed request
 * advertised a retry hint nothing could act on. The plain header must go out with the same value.
 */
describe('ProxyAwareThrottlerGuard.throwThrottlingException', () => {
  const invoke = async (
    setHeaders: boolean | undefined,
  ): Promise<{ headers: Record<string, string>; error: unknown }> => {
    const headers: Record<string, string> = {};
    const guard = Object.create(ProxyAwareThrottlerGuard.prototype) as ProxyAwareThrottlerGuard;
    // `options` is what the base constructor would set; getErrorMessage reads it.
    Object.assign(guard, {
      options: {},
      commonOptions: { setHeaders },
      errorMessage: 'ThrottlerException: Too Many Requests',
    });
    (guard as unknown as { getRequestResponse(c: unknown): unknown }).getRequestResponse = () => ({
      req: {},
      res: { header: (name: string, value: string) => void (headers[name] = value) },
    });
    let error: unknown;
    try {
      await (
        guard as unknown as {
          throwThrottlingException(c: unknown, d: unknown): Promise<void>;
        }
      ).throwThrottlingException(
        {},
        {
          limit: 10,
          ttl: 60,
          key: 'k',
          tracker: '1.2.3.4',
          totalHits: 11,
          timeToExpire: 42,
          isBlocked: true,
          timeToBlockExpire: 37,
        },
      );
    } catch (caught) {
      error = caught;
    }
    return { headers, error };
  };

  it('emits a plain Retry-After carrying the blocked window, and still throws', async () => {
    const { headers, error } = await invoke(undefined);
    expect(headers['Retry-After']).toBe('37');
    expect(error).toBeInstanceOf(ThrottlerException);
  });

  it('respects setHeaders: false, matching the flag the base guard gates its own header on', async () => {
    const { headers, error } = await invoke(false);
    expect(headers['Retry-After']).toBeUndefined();
    expect(error).toBeInstanceOf(ThrottlerException);
  });
});

/**
 * Pins the bucket scope the docs describe: every window is counted per route handler per client IP
 * (the library's generateKey includes the controller and handler names). docs/04 section 4.6,
 * docs/10 and docs/12 say so; a generateKey override that changes the scope must update them too.
 */
describe('ProxyAwareThrottlerGuard bucket scope', () => {
  class SessionsController {}
  const list = function list(): void {};
  const get = function get(): void {};
  let storage: ThrottlerStorageService;

  afterEach(() => storage.onApplicationShutdown());

  it('counts each route handler separately for one client IP', async () => {
    storage = new ThrottlerStorageService();
    const guard = new ProxyAwareThrottlerGuard(
      { throttlers: [{ name: 'short', ttl: 1000, limit: 10 }] },
      storage,
      new Reflector(),
    );
    await guard.onModuleInit();
    delete process.env.TRUSTED_PROXIES;
    const req = { ip: '203.0.113.9', socket: { remoteAddress: '203.0.113.9' }, headers: {} };
    const contextFor = (handler: () => void): ExecutionContext =>
      ({
        getHandler: () => handler,
        getClass: () => SessionsController,
        switchToHttp: () => ({ getRequest: () => req, getResponse: () => ({ header: () => undefined }) }),
      }) as unknown as ExecutionContext;
    for (let i = 0; i < 10; i++) {
      await expect(guard.canActivate(contextFor(list))).resolves.toBe(true);
      await expect(guard.canActivate(contextFor(get))).resolves.toBe(true);
    }
    await expect(guard.canActivate(contextFor(list))).rejects.toThrow(ThrottlerException);
    await expect(guard.canActivate(contextFor(get))).rejects.toThrow(ThrottlerException);
  });
});