@hexabot-ai/api 3.2.7 → 3.3.0-beta.0

package/src/workflow/guards/webhook-trigger.guard.ts

@@ -0,0 +1,193 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { timingSafeEqual } from 'node:crypto';
+
+import { WebhookAuthType, WebhookTriggerConfig } from '@hexabot-ai/types';
+import {
+  CanActivate,
+  ExecutionContext,
+  HttpStatus,
+  Injectable,
+  NotFoundException,
+  ParseUUIDPipe,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import { Request } from 'express';
+
+import { LoggerService } from '@/logger/logger.service';
+import { CredentialService } from '@/user/services/credential.service';
+
+import { WorkflowService } from '../services/workflow.service';
+import { WorkflowType } from '../types';
+
+/**
+ * Guards the public webhook trigger endpoint. It resolves the target workflow,
+ * enforces that it is a manual workflow with an enabled webhook, and verifies
+ * the configured credentials. The handler re-resolves the workflow rather than
+ * receiving it through mutated request state.
+ */
+@Injectable()
+export class WebhookTriggerGuard implements CanActivate {
+  private readonly uuidPipe = new ParseUUIDPipe({
+    version: '4',
+    errorHttpStatusCode: HttpStatus.NOT_FOUND,
+  });
+
+  constructor(
+    private readonly workflowService: WorkflowService,
+    private readonly credentialService: CredentialService,
+    private readonly jwtService: JwtService,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<Request>();
+    const id = await this.uuidPipe.transform(request.params.id, {
+      type: 'param',
+      data: 'id',
+    });
+    const workflow = await this.workflowService.findOne(id);
+    if (!workflow) {
+      throw new NotFoundException(`Workflow with ID ${id} not found`);
+    }
+
+    // Do not disclose whether the workflow exists when it is not exposed as a
+    // webhook (wrong type or webhook disabled).
+    if (workflow.type !== WorkflowType.manual) {
+      throw new NotFoundException(`Workflow with ID ${id} not found`);
+    }
+
+    const webhook = workflow.webhookTrigger;
+    if (!webhook?.enabled) {
+      throw new NotFoundException(`Workflow with ID ${id} not found`);
+    }
+
+    await this.verifyWebhookAuth(webhook, request);
+
+    return true;
+  }
+
+  /**
+   * Resolves the secret referenced by the trigger config from the credentials
+   * store. A missing reference or a dangling credential must never
+   * authenticate: both fail closed with a generic 401, with a server-side
+   * warning so operators can diagnose broken references.
+   */
+  private async resolveSecret(
+    credentialId: string | null | undefined,
+  ): Promise<string> {
+    if (!credentialId) {
+      throw new UnauthorizedException('Invalid webhook credentials');
+    }
+
+    const value = await this.credentialService.findOneValue(credentialId);
+    if (!value) {
+      this.logger.warn(
+        `Webhook trigger references a missing credential (${credentialId})`,
+      );
+      throw new UnauthorizedException('Invalid webhook credentials');
+    }
+
+    return value;
+  }
+
+  /**
+   * Validates incoming webhook credentials against the workflow configuration.
+   * Throws {@link UnauthorizedException} when the credentials are missing or invalid.
+   */
+  private async verifyWebhookAuth(
+    webhook: WebhookTriggerConfig,
+    req: Request,
+  ): Promise<void> {
+    switch (webhook.authType) {
+      case WebhookAuthType.none:
+        return;
+
+      case WebhookAuthType.basic: {
+        // A missing expected secret must never authenticate empty credentials.
+        if (!webhook.username) {
+          throw new UnauthorizedException('Invalid webhook credentials');
+        }
+        const expectedPassword = await this.resolveSecret(
+          webhook.passwordCredentialId,
+        );
+        const header = req.headers.authorization ?? '';
+        const match = header.match(/^Basic\s+(\S+)$/i);
+        if (!match) {
+          throw new UnauthorizedException('Invalid webhook credentials');
+        }
+        const decoded = Buffer.from(match[1], 'base64').toString('utf8');
+        const separator = decoded.indexOf(':');
+        const username =
+          separator === -1 ? decoded : decoded.slice(0, separator);
+        const password = separator === -1 ? '' : decoded.slice(separator + 1);
+        if (
+          !this.safeEqual(username, webhook.username) ||
+          !this.safeEqual(password, expectedPassword)
+        ) {
+          throw new UnauthorizedException('Invalid webhook credentials');
+        }
+
+        return;
+      }
+
+      case WebhookAuthType.header: {
+        const headerName = (webhook.headerName ?? '').toLowerCase();
+        // A missing expected secret must never authenticate empty credentials.
+        if (!headerName) {
+          throw new UnauthorizedException('Invalid webhook credentials');
+        }
+        const expectedValue = await this.resolveSecret(
+          webhook.headerValueCredentialId,
+        );
+        const provided = req.headers[headerName];
+        const value = Array.isArray(provided) ? provided[0] : (provided ?? '');
+        if (!this.safeEqual(value, expectedValue)) {
+          throw new UnauthorizedException('Invalid webhook credentials');
+        }
+
+        return;
+      }
+
+      case WebhookAuthType.jwt: {
+        const secret = await this.resolveSecret(webhook.jwtSecretCredentialId);
+        const header = req.headers.authorization ?? '';
+        const match = header.match(/^Bearer\s+(\S+)$/i);
+        if (!match) {
+          throw new UnauthorizedException('Invalid webhook credentials');
+        }
+        try {
+          this.jwtService.verify(match[1], {
+            secret,
+            algorithms: [webhook.jwtAlgorithm ?? 'HS256'],
+          });
+        } catch {
+          throw new UnauthorizedException('Invalid webhook credentials');
+        }
+
+        return;
+      }
+
+      default:
+        throw new UnauthorizedException('Invalid webhook credentials');
+    }
+  }
+
+  /**
+   * Constant-time string comparison to avoid leaking secrets through timing.
+   */
+  private safeEqual(a: string, b: string): boolean {
+    const bufferA = Buffer.from(a, 'utf8');
+    const bufferB = Buffer.from(b, 'utf8');
+    if (bufferA.length !== bufferB.length) {
+      return false;
+    }
+
+    return timingSafeEqual(bufferA, bufferB);
+  }
+}

package/src/workflow/services/agentic.service.ts

@@ -13,6 +13,7 @@ import {
 } from '@hexabot-ai/agentic';
 import { WorkflowFull, WorkflowRunFull } from '@hexabot-ai/types';
 import { Injectable } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
 
 import { ActionService } from '@/actions/actions.service';
 import { RuntimeBindingsService } from '@/bindings/runtime-bindings.service';
@@ -57,9 +58,14 @@ export class AgenticService implements WorkflowCallService {
   /**
    * Process an event by resuming a suspended workflow run if it exists,
    * otherwise start a new run using the latest configured workflow.
+   *
+   * Callers that already resolved the target workflow (e.g. the webhook
+   * trigger path) can pass it through `options.workflow` to avoid a redundant
+   * lookup.
    */
   async handleEvent(
     event: TriggerEventWrapper,
+    options: { workflow?: WorkflowFull } = {},
   ): Promise<WorkflowRunFull | null> {
     const initiator = event.getInitiator();
     const requestedWorkflowId = event.getWorkflowId();
@@ -98,9 +104,11 @@ export class AgenticService implements WorkflowCallService {
         return execution.run;
       }
 
-      const workflowToRun = requestedWorkflowId
-        ? await this.workflowService.findOneAndPopulate(requestedWorkflowId)
-        : await this.workflowService.pickWorkflow();
+      const workflowToRun =
+        options.workflow ??
+        (requestedWorkflowId
+          ? await this.workflowService.findOneAndPopulate(requestedWorkflowId)
+          : await this.workflowService.pickWorkflow());
       if (!workflowToRun) {
         this.logger.warn('No workflow available to handle incoming event', {
           requestedWorkflowId: requestedWorkflowId ?? null,
@@ -761,4 +769,20 @@ export class AgenticService implements WorkflowCallService {
 
     return typeof error === 'string' ? error : JSON.stringify(error);
   }
+
+  /**
+   * Abort all active workflow runs linked to a thread when that thread is closed.
+   */
+  @OnEvent('hook:thread:postUpdate')
+  async handleThreadClosed({
+    entity,
+    databaseEntity,
+  }: {
+    entity: { id: string; status: string };
+    databaseEntity: { id: string; status: string };
+  }): Promise<void> {
+    if (entity.status === 'closed' && databaseEntity.status !== 'closed') {
+      await this.workflowRunService.abortActiveRunsForThread(entity.id);
+    }
+  }
 }

package/src/workflow/services/webhook-trigger.service.ts

@@ -0,0 +1,169 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  WebhookAuthType,
+  WorkflowFull,
+  WorkflowRun,
+  WorkflowRunFull,
+} from '@hexabot-ai/types';
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+  UnprocessableEntityException,
+} from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+
+import { CredentialService } from '@/user/services/credential.service';
+import { UserService } from '@/user/services/user.service';
+
+import {
+  ManualEventWrapper,
+  TriggerEventWrapper,
+} from '../lib/trigger-event-wrapper';
+import { WorkflowType } from '../types';
+
+import { AgenticService } from './agentic.service';
+import { WorkflowService } from './workflow.service';
+
+/**
+ * Outcome of a triggered workflow run, exposed to webhook callers. Execution
+ * is synchronous, so the final status and workflow output are available.
+ */
+export type WorkflowTriggerResult = {
+  runId: string;
+  status: WorkflowRun['status'];
+  output: Record<string, unknown> | null;
+  error: string | null;
+};
+
+/**
+ * A server-issued webhook trigger token. Tokens carry no expiry: they stay
+ * valid until the workflow's signing secret credential is rotated.
+ */
+export type WebhookTokenResult = {
+  token: string;
+};
+
+@Injectable()
+export class WebhookTriggerService {
+  constructor(
+    private readonly workflowService: WorkflowService,
+    private readonly userService: UserService,
+    private readonly agenticService: AgenticService,
+    private readonly credentialService: CredentialService,
+    private readonly jwtService: JwtService,
+  ) {}
+
+  /**
+   * Signs a webhook trigger token with the workflow's own JWT secret so
+   * callers never have to craft tokens themselves. Tokens carry no expiry;
+   * rotating the secret credential invalidates every previously issued
+   * token. The workflow must be a manual workflow with an enabled,
+   * JWT-authenticated webhook trigger.
+   *
+   * @param id - The workflow ID the token is scoped to.
+   */
+  async generateToken(id: string): Promise<WebhookTokenResult> {
+    const workflow = await this.workflowService.findOne(id);
+    if (!workflow) {
+      throw new NotFoundException(`Workflow with ID ${id} not found`);
+    }
+
+    const webhook = workflow.webhookTrigger;
+    if (
+      workflow.type !== WorkflowType.manual ||
+      !webhook?.enabled ||
+      webhook.authType !== WebhookAuthType.jwt
+    ) {
+      throw new BadRequestException(
+        'Workflow must have an enabled JWT-authenticated webhook trigger',
+      );
+    }
+
+    const secret = await this.credentialService.findOneValue(
+      webhook.jwtSecretCredentialId ?? undefined,
+    );
+    if (!secret) {
+      throw new BadRequestException(
+        'The webhook trigger references a missing JWT secret credential',
+      );
+    }
+
+    const token = this.jwtService.sign(
+      { sub: id },
+      {
+        secret,
+        algorithm: webhook.jwtAlgorithm ?? 'HS256',
+      },
+    );
+
+    return { token };
+  }
+
+  /**
+   * Executes a manual workflow run from a webhook.
+   *
+   * Access control (existence, manual type, enabled webhook, credentials) is
+   * enforced upstream by {@link WebhookTriggerGuard}; this method resolves the
+   * workflow, validates the payload, and dispatches the event. The workflow
+   * runs to completion before responding, so the result carries the final run
+   * status and output.
+   *
+   * @param id - The workflow ID to execute.
+   * @param input - Optional workflow input payload.
+   */
+  async trigger(id: string, input: unknown): Promise<WorkflowTriggerResult> {
+    const workflow = await this.workflowService.findOneAndPopulate(id);
+    if (!workflow) {
+      throw new NotFoundException(`Workflow with ID ${id} not found`);
+    }
+
+    const manualInput = this.workflowService.validateManualInput(
+      input ?? {},
+      workflow.inputSchema,
+    );
+    const initiatorId = workflow.createdBy?.id ?? null;
+    const event = new ManualEventWrapper(manualInput, initiatorId);
+    const run = await this.dispatchTriggerEvent(workflow, event, initiatorId);
+    if (!run) {
+      // The run could not be created (missing initiator/definition) or the
+      // runner crashed before persisting a result.
+      throw new UnprocessableEntityException(
+        'Workflow run could not be started',
+      );
+    }
+
+    return {
+      runId: run.id,
+      status: run.status,
+      output: run.output ?? null,
+      error: run.error ?? null,
+    };
+  }
+
+  /**
+   * Resolves the initiator, targets the event at the given workflow, and hands
+   * it to the agentic runner. Shared by webhook triggers and authenticated
+   * manual runs so both paths dispatch identically.
+   */
+  async dispatchTriggerEvent(
+    workflow: WorkflowFull,
+    event: TriggerEventWrapper,
+    initiatorId: string | null,
+  ): Promise<WorkflowRunFull | null> {
+    const initiator = initiatorId
+      ? await this.userService.findOne(initiatorId)
+      : null;
+    if (initiator) {
+      event.setInitiator(initiator);
+    }
+    event.setWorkflowId(workflow.id);
+
+    return await this.agenticService.handleEvent(event, { workflow });
+  }
+}

package/src/workflow/services/workflow-run.service.ts

@@ -264,4 +264,25 @@ export class WorkflowRunService extends BaseOrmService<WorkflowRunOrmEntity> {
       );
     })[0];
   }
+
+  /**
+   * Mark all active runs linked to a thread as failed.
+   * Called when a thread is closed to abort any in-flight workflow execution.
+   *
+   * @param threadId - The ID of the closed thread.
+   */
+  async abortActiveRunsForThread(threadId: string): Promise<void> {
+    const activeRuns = await this.find({
+      where: {
+        thread: { id: threadId },
+        status: In(ACTIVE_WORKFLOW_RUN_STATUSES),
+      },
+    });
+
+    await Promise.all(
+      activeRuns.map((run) =>
+        this.markFailed(run.id, { error: 'Thread was closed' }),
+      ),
+    );
+  }
 }

package/src/workflow/workflow.module.ts

@@ -5,6 +5,7 @@
  */
 
 import { forwardRef, Module } from '@nestjs/common';
+import { JwtModule } from '@nestjs/jwt';
 import { SchedulerRegistry } from '@nestjs/schedule';
 import { TypeOrmModule } from '@nestjs/typeorm';
 
@@ -28,6 +29,7 @@ import { MemoryRecordOrmEntity } from './entities/memory-record.entity';
 import { WorkflowRunOrmEntity } from './entities/workflow-run.entity';
 import { WorkflowVersionOrmEntity } from './entities/workflow-version.entity';
 import { WorkflowOrmEntity } from './entities/workflow.entity';
+import { WebhookTriggerGuard } from './guards/webhook-trigger.guard';
 import { McpServerRepository } from './repositories/mcp-server.repository';
 import { MemoryDefinitionRepository } from './repositories/memory-definition.repository';
 import { MemoryRecordRepository } from './repositories/memory-record.repository';
@@ -42,6 +44,7 @@ import { McpServerService } from './services/mcp-server.service';
 import { MemoryDefinitionService } from './services/memory-definition.service';
 import { MemoryRecordService } from './services/memory-record.service';
 import { MemoryService } from './services/memory.service';
+import { WebhookTriggerService } from './services/webhook-trigger.service';
 import { WorkflowRunService } from './services/workflow-run.service';
 import { WorkflowSchedulerService } from './services/workflow-scheduler.service';
 import { WorkflowVersionService } from './services/workflow-version.service';
@@ -62,6 +65,7 @@ import { WORKFLOW_CALL_SERVICE } from './types';
     forwardRef(() => CmsModule),
     forwardRef(() => ChatModule),
     UserModule,
+    JwtModule.register({}),
   ],
   controllers: [
     WorkflowController,
@@ -94,6 +98,8 @@ import { WORKFLOW_CALL_SERVICE } from './types';
     ScheduledWorkflowContext,
     WorkflowContextFactory,
     AgenticService,
+    WebhookTriggerService,
+    WebhookTriggerGuard,
     { provide: WORKFLOW_CALL_SERVICE, useExisting: AgenticService },
   ],
   exports: [
@@ -113,6 +119,8 @@ import { WORKFLOW_CALL_SERVICE } from './types';
     McpClientPoolService,
     ConversationalWorkflowContext,
     AgenticService,
+    WebhookTriggerService,
+    WebhookTriggerGuard,
     WORKFLOW_CALL_SERVICE,
   ],
 })