@hed-hog/core 0.0.386 → 0.0.387

package/src/integration-profile/integration-profile.utils.ts

@@ -98,6 +98,45 @@ export function getReplyToAddress(config: unknown): string | undefined {
   return replyToName ? `${replyToName} <${replyToEmail}>` : replyToEmail;
 }
 
+// ─── Messaging utilities ──────────────────────────────────────────────────────
+
+export const DEFAULT_GRAPH_API_VERSION = 'v21.0';
+
+export type WhatsappOfficialConfig = {
+  appId: string;
+  appSecret: string;
+  businessId?: string;
+  wabaId: string;
+  accessToken: string;
+  graphApiVersion: string;
+  verifyToken: string;
+  environment: 'test' | 'production';
+};
+
+/**
+ * Maps an integration_profile config JSON to the Meta WhatsApp Cloud API credentials.
+ *
+ * Os números não vêm daqui: um WABA pode ter vários e cada um tem estado próprio,
+ * então eles vivem na tabela whatsapp_phone_number (library whatsapp).
+ */
+export function buildWhatsappOfficialConfigFromIntegration(
+  config: unknown,
+): WhatsappOfficialConfig {
+  const cfg = (config as Cfg) ?? {};
+  const environment = String(cfg.environment ?? 'production').trim();
+  return {
+    appId: String(cfg.app_id ?? '').trim(),
+    appSecret: String(cfg.app_secret ?? '').trim(),
+    ...(cfg.business_id ? { businessId: String(cfg.business_id).trim() } : {}),
+    wabaId: String(cfg.waba_id ?? '').trim(),
+    accessToken: String(cfg.access_token ?? '').trim(),
+    graphApiVersion:
+      String(cfg.graph_api_version ?? '').trim() || DEFAULT_GRAPH_API_VERSION,
+    verifyToken: String(cfg.verify_token ?? '').trim(),
+    environment: environment === 'test' ? 'test' : 'production',
+  };
+}
+
 // ─── Storage utilities ────────────────────────────────────────────────────────
 
 /**

package/src/profile/profile.controller.ts

@@ -2,6 +2,10 @@ import { NoRole, User } from '@hed-hog/api';
 import { Locale } from '@hed-hog/api-locale';
 import { Body, Controller, Delete, Get, Headers, Ip, Param, ParseIntPipe, Post, Put, UploadedFile, UseInterceptors } from '@nestjs/common';
 import { FileInterceptor } from '@nestjs/platform-express';
+import type {
+    PublicKeyCredentialCreationOptionsJSON,
+    PublicKeyCredentialRequestOptionsJSON,
+} from '@simplewebauthn/server';
 import { ChangeEmailDto } from './dto/change-email.dto';
 import { ChangePasswordDto } from './dto/change-password.dto';
 import { EmailVerificationDto } from './dto/email-verification-confirm.dto';
@@ -161,7 +165,7 @@ export class ProfileController {
     @Body() { name }: GenerateWebAuthnRegistrationOptionsDto,
     @Locale() locale: string,
     @Headers('origin') origin: string
-  ) {
+  ): Promise<PublicKeyCredentialCreationOptionsJSON> {
     return this.profileService.generateWebAuthnRegistrationOptions(locale, id, name, origin);
   }
 
@@ -180,7 +184,7 @@ export class ProfileController {
     @User() { id },
     @Locale() locale: string,
     @Headers('origin') origin: string
-  ) {
+  ): Promise<PublicKeyCredentialRequestOptionsJSON> {
     return this.profileService.generateWebAuthnAuthenticationOptions(locale, id, origin);
   }
 

package/src/profile/profile.service.ts

@@ -5,6 +5,8 @@ import { BadRequestException, forwardRef, Inject, Injectable, NotFoundException
 import { EventEmitter2 } from '@nestjs/event-emitter';
 import { JwtService } from '@nestjs/jwt';
 import type {
+    PublicKeyCredentialCreationOptionsJSON,
+    PublicKeyCredentialRequestOptionsJSON,
     VerifiedAuthenticationResponse,
     VerifiedRegistrationResponse,
 } from '@simplewebauthn/server';
@@ -1221,7 +1223,7 @@ export class ProfileService {
     }
   }
 
-  async generateWebAuthnRegistrationOptions(locale: string, userId: number, name: string, requestOrigin?: string) {
+  async generateWebAuthnRegistrationOptions(locale: string, userId: number, name: string, requestOrigin?: string): Promise<PublicKeyCredentialCreationOptionsJSON> {
     try {
       const user = await this.prisma.user.findFirst({
         where: { id: userId },
@@ -1367,7 +1369,7 @@ export class ProfileService {
     }
   }
 
-  async generateWebAuthnAuthenticationOptions(locale: string, userId: number, requestOrigin?: string) {
+  async generateWebAuthnAuthenticationOptions(locale: string, userId: number, requestOrigin?: string): Promise<PublicKeyCredentialRequestOptionsJSON> {
     try {
       const user = await this.prisma.user.findFirst({
         where: { id: userId },
@@ -1500,7 +1502,7 @@ export class ProfileService {
     }
   }
 
-  async generateWebAuthnAuthenticationOptionsForLogin(locale: string, mfaToken: string) {
+  async generateWebAuthnAuthenticationOptionsForLogin(locale: string, mfaToken: string): Promise<PublicKeyCredentialRequestOptionsJSON> {
     try {
       const decoded = this.jwt.decode(mfaToken) as any;
       if (!decoded || !decoded.userId) {

package/src/webhook-integration/webhook-integration.controller.ts

@@ -15,6 +15,7 @@ import {
   Res,
 } from '@nestjs/common';
 import { Request, Response } from 'express';
+import { WebhookProtocolResponse } from './webhook-protocol.registry';
 import { WebhookIntegrationService } from './webhook-integration.service';
 import {
   CreateWebhookActionDTO,
@@ -145,12 +146,24 @@ export class PublicWebhookController {
   constructor(private readonly service: WebhookIntegrationService) {}
 
   @Post(':uuid')
-  execute(
+  async execute(
     @Param('uuid') uuid: string,
     @Body() body: any,
+    @Query() query: any,
     @Headers() headers: any,
     @Req() req: Request,
+    @Res({ passthrough: true }) res: Response,
   ) {
+    const handled = await this.service.executeProtocol(
+      uuid,
+      'POST',
+      body,
+      query,
+      headers,
+      req,
+    );
+    if (handled) return sendProtocolResponse(res, handled);
+
     return this.service.executePublic(uuid, body, headers, req);
   }
 
@@ -158,15 +171,40 @@ export class PublicWebhookController {
    * GET variant so a webhook can be triggered by a plain clickable link (e.g.
    * approve/reject links sent by email/WhatsApp). Query params are used as the
    * payload for action templates (`{{body.decision}}` ← `?decision=approve`).
+   *
+   * Webhooks with a protocol take a different path: for them a GET is the
+   * provider's verification handshake, not a trigger — it must not run actions.
    */
   @Get(':uuid')
-  executeGet(
+  async executeGet(
     @Param('uuid') uuid: string,
     @Query() query: any,
     @Headers() headers: any,
     @Req() req: Request,
+    @Res({ passthrough: true }) res: Response,
   ) {
+    const handled = await this.service.executeProtocol(
+      uuid,
+      'GET',
+      query ?? {},
+      query,
+      headers,
+      req,
+    );
+    if (handled) return sendProtocolResponse(res, handled);
+
     return this.service.executePublic(uuid, query ?? {}, headers, req);
   }
 }
 
+/**
+ * Aplica status/content-type que o adaptador pediu. Devolver a string crua importa:
+ * provedores como a Meta comparam o corpo da resposta literalmente, então um
+ * envelope JSON reprovaria a verificação.
+ */
+function sendProtocolResponse(res: Response, result: WebhookProtocolResponse) {
+  res.status(result.status);
+  if (result.contentType) res.type(result.contentType);
+  return result.body;
+}
+

package/src/webhook-integration/webhook-integration.module.ts

@@ -16,6 +16,7 @@ import {
   WebhookIntegrationController,
 } from './webhook-integration.controller';
 import { WebhookIntegrationService } from './webhook-integration.service';
+import { WebhookProtocolRegistry } from './webhook-protocol.registry';
 
 @Module({
   imports: [
@@ -38,12 +39,16 @@ import { WebhookIntegrationService } from './webhook-integration.service';
     IntegrationEventCatalogService,
     WebhookIntegrationService,
     EventWebhookService,
+    WebhookProtocolRegistry,
   ],
   exports: [
     IntegrationEventCatalogService,
     AppCommandModule,
     WebhookIntegrationService,
     EventWebhookService,
+    // Exportado para que outros módulos registrem protocolos de entrada
+    // (ex.: a library whatsapp registra o protocolo da Meta).
+    WebhookProtocolRegistry,
   ],
 })
 export class WebhookIntegrationModule {}

package/src/webhook-integration/webhook-integration.service.ts

@@ -7,6 +7,7 @@ import {
     BadRequestException,
     HttpException,
     Injectable,
+    Logger,
     NotFoundException,
 } from '@nestjs/common';
 import { EventEmitter } from 'events';
@@ -25,6 +26,11 @@ import {
     UpdateWebhookActionDTO,
 } from './dto/webhook-action.dto';
 import { AppCommandRegistry } from '../app-command/app-command.registry';
+import {
+    WebhookProtocolRegistry,
+    WebhookProtocolRequest,
+    WebhookProtocolResponse,
+} from './webhook-protocol.registry';
 import {
     createPlainToken,
     createPublicUuid,
@@ -58,6 +64,7 @@ type WebhookActionPayload =
 
 @Injectable()
 export class WebhookIntegrationService {
+  private readonly logger = new Logger(WebhookIntegrationService.name);
   private readonly logEmitter = new EventEmitter();
   private readonly webhookActionSelect = {
     id: true,
@@ -105,6 +112,7 @@ export class WebhookIntegrationService {
     private readonly settingService: SettingService,
     private readonly commandRegistry: AppCommandRegistry,
     private readonly mcpApiKeyService: McpApiKeyService,
+    private readonly protocolRegistry: WebhookProtocolRegistry,
   ) {}
 
   private get integrations() {
@@ -551,6 +559,131 @@ export class WebhookIntegrationService {
     });
   }
 
+  /**
+   * Cria (ou devolve) o webhook de um perfil de integração que fala um protocolo
+   * próprio. Idempotente: a chave é (protocol, integration_profile_id), então
+   * chamar de novo devolve o mesmo UUID — e a URL já registrada no painel do
+   * provedor continua válida.
+   *
+   * Existe para que módulos não precisem montar a URL pública por conta própria:
+   * `/webhook/:uuid` e a base vinda dos settings ficam sob responsabilidade do core.
+   */
+  async provisionProtocolWebhook(input: {
+    slug: string;
+    name: string;
+    protocol: string;
+    integrationProfileId: number;
+    description?: string;
+  }) {
+    const existing = await this.integrations.findFirst({
+      where: {
+        protocol: input.protocol,
+        integration_profile_id: input.integrationProfileId,
+      },
+    });
+
+    if (existing) return this.withPublicUrl(existing);
+
+    const created = await this.integrations.create({
+      data: {
+        slug: await this.ensureProvisionSlug(input.slug),
+        name: input.name,
+        description: input.description ?? null,
+        protocol: input.protocol,
+        integration_profile_id: input.integrationProfileId,
+        public_uuid: createPublicUuid(),
+        status: 'active',
+        // Webhooks de protocolo não usam o token estático do core: o adaptador
+        // faz a própria autenticação (HMAC, no caso da Meta).
+        require_token: false,
+      },
+    });
+
+    this.logger.log(
+      `Provisioned "${input.protocol}" webhook ${created.id} for integration profile ${input.integrationProfileId}`,
+    );
+
+    return this.withPublicUrl(created);
+  }
+
+  /** Sufixa o slug até achar um livre (o slug é unique na tabela). */
+  private async ensureProvisionSlug(base: string): Promise<string> {
+    const slug = base.trim();
+    if (!(await this.integrations.findUnique({ where: { slug } }))) return slug;
+
+    for (let i = 2; ; i++) {
+      const candidate = `${slug}-${i}`;
+      if (!(await this.integrations.findUnique({ where: { slug: candidate } }))) {
+        return candidate;
+      }
+    }
+  }
+
+  /**
+   * Entrega a chamada ao adaptador de protocolo do webhook, se houver um.
+   *
+   * Devolve `null` quando o webhook é clássico (protocol nulo) ou quando nenhum
+   * módulo registrou o protocolo — nesse caso o chamador segue pelo fluxo normal
+   * de token + actions.
+   *
+   * Webhooks com protocolo NÃO passam por validateToken/validateIp/validateBodySchema:
+   * o adaptador faz a própria autenticação (a Meta, por exemplo, assina com HMAC).
+   */
+  async executeProtocol(
+    uuid: string,
+    method: 'GET' | 'POST',
+    body: any,
+    query: any,
+    headers: any,
+    req: Request,
+  ): Promise<WebhookProtocolResponse | null> {
+    const integration = await this.integrations.findUnique({
+      where: { public_uuid: uuid },
+      select: {
+        id: true,
+        slug: true,
+        status: true,
+        protocol: true,
+        integration_profile_id: true,
+      },
+    });
+
+    if (!integration?.protocol) return null;
+
+    const adapter = this.protocolRegistry.get(integration.protocol);
+    if (!adapter) {
+      // Protocolo gravado mas nenhum módulo o registrou (library desabilitada,
+      // por exemplo). Não cai no fluxo de actions: seria autenticar com o token
+      // clássico um webhook que deveria exigir a auth do provedor.
+      this.logger.error(
+        `Webhook ${integration.id} declares protocol "${integration.protocol}", but no adapter is registered.`,
+      );
+      throw new NotFoundException('Webhook not found.');
+    }
+
+    if (integration.status !== 'active') {
+      throw new NotFoundException('Webhook not found.');
+    }
+
+    const request: WebhookProtocolRequest = {
+      integration: {
+        id: integration.id,
+        slug: integration.slug,
+        integration_profile_id: integration.integration_profile_id ?? null,
+      },
+      body,
+      query: (query ?? {}) as Record<string, string>,
+      headers: (headers ?? {}) as Record<string, string | string[] | undefined>,
+      rawBody: (req as Request & { rawBody?: Buffer }).rawBody,
+      remoteIp: this.getRemoteIp(req),
+      req,
+    };
+
+    return method === 'GET'
+      ? adapter.verify(request)
+      : adapter.handle(request);
+  }
+
   async executePublic(uuid: string, body: any, headers: any, req: Request) {
     const startedAt = Date.now();
     const remoteIp = this.getRemoteIp(req);

package/src/webhook-integration/webhook-protocol.registry.spec.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it, jest } from '@jest/globals';
+import { WebhookProtocolRegistry } from './webhook-protocol.registry';
+
+const makeAdapter = () =>
+  ({
+    verify: jest.fn(),
+    handle: jest.fn(),
+  }) as any;
+
+describe('WebhookProtocolRegistry', () => {
+  it('devolve o adaptador registrado', () => {
+    const registry = new WebhookProtocolRegistry();
+    const adapter = makeAdapter();
+
+    registry.register('meta-whatsapp', adapter);
+
+    expect(registry.get('meta-whatsapp')).toBe(adapter);
+    expect(registry.has('meta-whatsapp')).toBe(true);
+  });
+
+  it('normaliza a chave (case e espaços)', () => {
+    const registry = new WebhookProtocolRegistry();
+    const adapter = makeAdapter();
+
+    registry.register('  Meta-WhatsApp ', adapter);
+
+    expect(registry.get('meta-whatsapp')).toBe(adapter);
+    expect(registry.get('META-WHATSAPP')).toBe(adapter);
+  });
+
+  it('devolve null para protocolo desconhecido, nulo ou vazio', () => {
+    const registry = new WebhookProtocolRegistry();
+
+    expect(registry.get('nao-existe')).toBeNull();
+    expect(registry.get(null)).toBeNull();
+    expect(registry.get(undefined)).toBeNull();
+    expect(registry.get('')).toBeNull();
+    expect(registry.has(null)).toBe(false);
+  });
+
+  it('recusa registrar com chave vazia', () => {
+    const registry = new WebhookProtocolRegistry();
+
+    expect(() => registry.register('   ', makeAdapter())).toThrow();
+  });
+
+  it('avisa ao sobrescrever um protocolo já registrado', () => {
+    const registry = new WebhookProtocolRegistry();
+    const warn = jest
+      .spyOn((registry as any).logger, 'warn')
+      .mockImplementation(() => undefined);
+    const first = makeAdapter();
+    const second = makeAdapter();
+
+    registry.register('dup', first);
+    registry.register('dup', second);
+
+    // Sobrescrever silenciosamente esconderia dois módulos brigando pelo protocolo.
+    expect(warn).toHaveBeenCalled();
+    expect(registry.get('dup')).toBe(second);
+  });
+
+  it('lista os protocolos registrados em ordem', () => {
+    const registry = new WebhookProtocolRegistry();
+    registry.register('zeta', makeAdapter());
+    registry.register('alpha', makeAdapter());
+
+    expect(registry.list()).toEqual(['alpha', 'zeta']);
+  });
+});

package/src/webhook-integration/webhook-protocol.registry.ts

@@ -0,0 +1,93 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+
+/**
+ * Resposta que um adaptador devolve ao controller público.
+ *
+ * `contentType` existe porque nem todo provedor aceita JSON: o handshake da Meta,
+ * por exemplo, compara o corpo com o challenge literalmente — um envelope JSON
+ * reprova a verificação.
+ */
+export type WebhookProtocolResponse = {
+  status: number;
+  contentType?: string;
+  body: string | object;
+};
+
+export type WebhookProtocolRequest = {
+  /** O registro de webhook_integration que casou com o uuid da URL. */
+  integration: {
+    id: number;
+    slug: string;
+    integration_profile_id: number | null;
+  };
+  /** Body já parseado (POST) ou query params (GET). */
+  body: unknown;
+  query: Record<string, string>;
+  headers: Record<string, string | string[] | undefined>;
+  /**
+   * Bytes originais da requisição. Obrigatório para validar assinaturas HMAC:
+   * reserializar o JSON reordena chaves e invalida a assinatura.
+   */
+  rawBody?: Buffer;
+  remoteIp: string;
+  req: Request;
+};
+
+/**
+ * Adaptador de um protocolo de webhook de entrada.
+ *
+ * O framework de webhooks do core é um disparador de ações genérico, autenticado
+ * por token estático. Provedores como a Meta falam um protocolo próprio (handshake
+ * de verificação + assinatura HMAC) que não cabe nesse modelo.
+ *
+ * Em vez de espalhar `if (provider === 'meta')` pelo core, um módulo registra aqui
+ * um adaptador e passa a responder pela mesma URL pública (`/webhook/:uuid`). O core
+ * continua sem conhecer nenhum provedor específico.
+ */
+export interface IWebhookProtocolAdapter {
+  /** GET na URL pública (tipicamente o handshake de verificação). */
+  verify(request: WebhookProtocolRequest): Promise<WebhookProtocolResponse>;
+  /** POST na URL pública (o evento em si). */
+  handle(request: WebhookProtocolRequest): Promise<WebhookProtocolResponse>;
+}
+
+/**
+ * Registro dos adaptadores de protocolo, no mesmo padrão do QueueHandlerRegistry
+ * e do FiscalProviderRegistry: o módulo dono do protocolo se registra no boot.
+ */
+@Injectable()
+export class WebhookProtocolRegistry {
+  private readonly logger = new Logger(WebhookProtocolRegistry.name);
+  private readonly adapters = new Map<string, IWebhookProtocolAdapter>();
+
+  register(protocol: string, adapter: IWebhookProtocolAdapter): void {
+    const key = normalizeProtocol(protocol);
+    if (!key) throw new Error('Webhook protocol key is required.');
+
+    if (this.adapters.has(key)) {
+      this.logger.warn(`Webhook protocol "${key}" was overwritten.`);
+    }
+
+    this.adapters.set(key, adapter);
+    this.logger.log(`Registered webhook protocol "${key}"`);
+  }
+
+  get(protocol: string | null | undefined): IWebhookProtocolAdapter | null {
+    const key = normalizeProtocol(protocol);
+    return key ? (this.adapters.get(key) ?? null) : null;
+  }
+
+  has(protocol: string | null | undefined): boolean {
+    return this.get(protocol) !== null;
+  }
+
+  /** Protocolos registrados (para a UI listar o que existe). */
+  list(): string[] {
+    return [...this.adapters.keys()].sort();
+  }
+}
+
+function normalizeProtocol(protocol: string | null | undefined): string {
+  return String(protocol ?? '').trim().toLowerCase();
+}