Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

10.8 KB
Raw Blame
import 'reflect-metadata';
import { RequestMethod } from '@nestjs/common';
import { METHOD_METADATA } from '@nestjs/common/constants';
import { REQUIRED_ROLE_KEY } from './decorators/auth.decorators';
import { ApiKeyRole } from './entities/api-key.entity';
import { IntegrationInstanceController } from '../integration/integration-instance.controller';
import { RedriveController } from '../integration/redrive.controller';
import { GroupController } from '../group/group.controller';
import { ContactController } from '../contact/contact.controller';
import { ChannelController } from '../channel/channel.controller';
import { LabelController } from '../label/label.controller';
import { ProfileController } from '../profile/profile.controller';
import { CatalogController } from '../catalog/catalog.controller';
import { MessageController } from '../message/message.controller';
import { SessionController } from '../session/session.controller';
import { allAgentTools } from '../../core/agent-tools/tools';

// The dashboard's client-side role (seeded from localStorage) is cosmetic UX only — the ACTUAL
// authorization boundary is the backend @RequireRole guard. These assertions lock that the sensitive
// ADMIN-only integration provisioning / redrive surfaces are role-gated server-side at the class level,
// so a tampered client role can never reach them regardless of what the browser claims.
describe('admin controller role coverage (server-side authorization is the real gate)', () => {
  it.each([
    ['IntegrationInstanceController', IntegrationInstanceController],
    ['RedriveController', RedriveController],
  ])('%s requires the ADMIN role at the class level', (_name, controller) => {
    expect(Reflect.getMetadata(REQUIRED_ROLE_KEY, controller)).toBe(ApiKeyRole.ADMIN);
  });
});

// A group invite code is a bearer capability, not read data: whoever holds the link joins the group
// on WhatsApp with no OpenWA credential at all, and that membership survives revoking the key that
// fetched the code. Both invite-code routes therefore sit at OPERATOR, like the QR endpoint: the
// reads whose payload is a credential for a system outside OpenWA's authority.
describe('group invite-code role coverage (the code is a capability, not read data)', () => {
  it.each(['getInviteCode', 'revokeInviteCode'] as const)('GroupController.%s requires the OPERATOR role', method => {
    // eslint-disable-next-line @typescript-eslint/unbound-method -- reading route metadata, not invoking
    expect(Reflect.getMetadata(REQUIRED_ROLE_KEY, GroupController.prototype[method])).toBe(ApiKeyRole.OPERATOR);
  });
});

// A number-existence check is an outbound WhatsApp query about a third party, and bulk checks put the
// linked account's standing at risk, so it sits at OPERATOR (the MCP ContactCheckNumber tool too).
// The profile-picture and phone-resolution reads stay open to any key: the dashboard loads avatars
// with a VIEWER key.
describe('contact lookup role coverage', () => {
  it('ContactController.checkNumber requires the OPERATOR role', () => {
    // eslint-disable-next-line @typescript-eslint/unbound-method -- reading route metadata, not invoking
    expect(Reflect.getMetadata(REQUIRED_ROLE_KEY, ContactController.prototype.checkNumber)).toBe(ApiKeyRole.OPERATOR);
  });

  it.each(['getProfilePictures', 'getProfilePicture', 'resolvePhone'] as const)(
    'ContactController.%s stays open to any valid key',
    method => {
      // eslint-disable-next-line @typescript-eslint/unbound-method -- reading route metadata, not invoking
      expect(Reflect.getMetadata(REQUIRED_ROLE_KEY, ContactController.prototype[method])).toBeUndefined();
    },
  );
});

const atLeastOperator = (role?: ApiKeyRole): boolean => role === ApiKeyRole.OPERATOR || role === ApiKeyRole.ADMIN;

// A write route that loses its role gate is open to a read-only VIEWER key and nothing else notices: the
// handler still works and every other gate stays green. So this walks the routes instead of naming them.
// Every handler of these controllers that is not a plain read must require OPERATOR or higher, on the
// handler or on the class. A deliberate exception goes in OPEN_WRITES, keyed `Controller.handler`, with why.
describe('write routes of the channel, group, contact, label, profile and catalog controllers', () => {
  const CONTROLLERS = [
    ChannelController,
    GroupController,
    ContactController,
    LabelController,
    ProfileController,
    CatalogController,
  ];
  const OPEN_WRITES = new Map<string, string>();
  const READS = [RequestMethod.GET, RequestMethod.HEAD, RequestMethod.OPTIONS];

  const writeRoutes = CONTROLLERS.flatMap(controller =>
    Object.getOwnPropertyNames(controller.prototype).flatMap(name => {
      const handler = (controller.prototype as unknown as Record<string, unknown>)[name];
      if (typeof handler !== 'function') return [];
      // RequestMethod.GET is 0, so "is a route" is an undefined check, not a truthiness check.
      const method = Reflect.getMetadata(METHOD_METADATA, handler) as RequestMethod | undefined;
      if (method === undefined || READS.includes(method)) return [];
      const role = (Reflect.getMetadata(REQUIRED_ROLE_KEY, handler) ??
        Reflect.getMetadata(REQUIRED_ROLE_KEY, controller)) as ApiKeyRole | undefined;
      return [{ id: `${controller.name}.${name}`, role }];
    }),
  );

  it('walks the write routes of every controller (a walk that found none would pass for the wrong reason)', () => {
    // 35 when written: channel 7, group 15, contact 4, label 4, profile 4, catalog 1.
    expect(writeRoutes.length).toBeGreaterThanOrEqual(35);
    for (const controller of CONTROLLERS) {
      expect(writeRoutes.some(route => route.id.startsWith(`${controller.name}.`))).toBe(true);
    }
  });

  it('requires OPERATOR or higher on every write route', () => {
    const open = writeRoutes.filter(route => !atLeastOperator(route.role) && !OPEN_WRITES.has(route.id));
    expect(open.map(route => route.id)).toEqual([]);
  });

  it('keeps no allowance for a route that is gated or gone', () => {
    const stale = [...OPEN_WRITES.keys()].filter(
      id => !writeRoutes.some(route => route.id === id && !atLeastOperator(route.role)),
    );
    expect(stale).toEqual([]);
  });
});

// The message and session controllers drive the linked WhatsApp account: they send, delete, start, stop,
// log out, hand out the QR code and pair a number. The walk above only asks that a write route is gated at
// all, so it would not see the QR read slipping below OPERATOR, the proxy write sliding from ADMIN to
// OPERATOR, or the presence read losing its explicit VIEWER. These tables state every route's role, so
// removing or changing one mark fails here, and a new route fails until its role is decided.
describe('role of every message and session route', () => {
  const OPEN = 'open'; // no @RequireRole: any valid key may call it
  type Role = ApiKeyRole | typeof OPEN;

  const MESSAGE_ROLES: Record<string, Role> = {
    getMessages: OPEN,
    sendText: ApiKeyRole.OPERATOR,
    sendTemplate: ApiKeyRole.OPERATOR,
    sendImage: ApiKeyRole.OPERATOR,
    sendVideo: ApiKeyRole.OPERATOR,
    sendAudio: ApiKeyRole.OPERATOR,
    sendDocument: ApiKeyRole.OPERATOR,
    sendLocation: ApiKeyRole.OPERATOR,
    sendContact: ApiKeyRole.OPERATOR,
    sendSticker: ApiKeyRole.OPERATOR,
    sendPoll: ApiKeyRole.OPERATOR,
    reply: ApiKeyRole.OPERATOR,
    clickButton: ApiKeyRole.OPERATOR,
    forward: ApiKeyRole.OPERATOR,
    react: ApiKeyRole.OPERATOR,
    getBatchStatus: OPEN,
    cancelBatch: ApiKeyRole.OPERATOR,
    getChatHistory: OPEN,
    getReactions: OPEN,
    getChatMedia: OPEN,
    deleteMessage: ApiKeyRole.OPERATOR,
    votePoll: ApiKeyRole.OPERATOR,
    pinMessage: ApiKeyRole.OPERATOR,
    unpinMessage: ApiKeyRole.OPERATOR,
    starMessage: ApiKeyRole.OPERATOR,
    edit: ApiKeyRole.OPERATOR,
    sendBulk: ApiKeyRole.OPERATOR,
  };

  const SESSION_ROLES: Record<string, Role> = {
    create: ApiKeyRole.OPERATOR,
    findAll: OPEN,
    findOne: OPEN,
    getConfig: OPEN,
    updateConfig: ApiKeyRole.OPERATOR,
    getProxy: OPEN,
    updateProxy: ApiKeyRole.ADMIN,
    delete: ApiKeyRole.OPERATOR,
    start: ApiKeyRole.OPERATOR,
    stop: ApiKeyRole.OPERATOR,
    logout: ApiKeyRole.OPERATOR,
    forceKill: ApiKeyRole.OPERATOR,
    // A GET, but the QR code links a device to the account, like the invite codes above.
    getQRCode: ApiKeyRole.OPERATOR,
    requestPairingCode: ApiKeyRole.OPERATOR,
    getGroups: OPEN,
    getChats: OPEN,
    markChatRead: ApiKeyRole.OPERATOR,
    subscribeToPresence: ApiKeyRole.OPERATOR,
    setOnlinePresence: ApiKeyRole.OPERATOR,
    getPresence: ApiKeyRole.VIEWER,
    markChatUnread: ApiKeyRole.OPERATOR,
    clearChatMessages: ApiKeyRole.OPERATOR,
    archiveChat: ApiKeyRole.OPERATOR,
    muteChat: ApiKeyRole.OPERATOR,
    pinChat: ApiKeyRole.OPERATOR,
    deleteChat: ApiKeyRole.OPERATOR,
    sendChatState: ApiKeyRole.OPERATOR,
    getStats: OPEN,
  };

  // The role the guard resolves: the handler's own mark, else the class's.
  const rolesOf = (controller: { prototype: object }): Record<string, Role> => {
    const prototype = controller.prototype as Record<string, unknown>;
    return Object.fromEntries(
      Object.getOwnPropertyNames(prototype).flatMap(name => {
        const handler = prototype[name];
        if (typeof handler !== 'function') return [];
        // RequestMethod.GET is 0, so "is a route" is an undefined check, not a truthiness check.
        if (Reflect.getMetadata(METHOD_METADATA, handler) === undefined) return [];
        const role = (Reflect.getMetadata(REQUIRED_ROLE_KEY, handler) ??
          Reflect.getMetadata(REQUIRED_ROLE_KEY, controller)) as ApiKeyRole | undefined;
        return [[name, role ?? OPEN]];
      }),
    );
  };

  it.each([
    ['MessageController', MessageController, MESSAGE_ROLES],
    ['SessionController', SessionController, SESSION_ROLES],
  ])('%s carries exactly the roles in its table', (_name, controller, table) => {
    expect(rolesOf(controller)).toEqual(table);
  });
});

// The MCP invoker enforces a tool's requiredRole through hasPermission and nothing else: declaring the tool
// tier 'write' implies no role. A write tool that loses requiredRole is therefore callable over MCP by a
// read-only VIEWER key, so every write tool must declare OPERATOR or higher.
describe('MCP write tools', () => {
  // Handlers are never invoked, so stub services are fine: only the declarations are read.
  const writeTools = allAgentTools({} as never).filter(tool => tool.tier === 'write');

  it('walks the write tools (a filter that matched none would pass for the wrong reason)', () => {
    // 26 when written: session 4, message 12, contact 2, group 4, label 4.
    expect(writeTools.length).toBeGreaterThanOrEqual(26);
  });

  it('declares requiredRole OPERATOR or higher on every write tool', () => {
    expect(writeTools.filter(tool => !atLeastOperator(tool.requiredRole)).map(tool => tool.name)).toEqual([]);
  });
});