@xyne/workflow-sdk 3.2.37 → 3.2.39

package/dist/runtime/workflow-runtime.js

@@ -18,10 +18,18 @@ import { validateTriggerPayload } from '../common/validate-payload.js';
 import { AccessDeniedError, ResourceNotFoundError } from '../authz/default.js';
 import { EventTrigger } from '../triggers/event-trigger.js';
 import { WebhookTrigger } from '../triggers/webhook-trigger.js';
+import { ApiTrigger } from '../triggers/api-trigger.js';
+import { CredentialResolver } from '../engine/credential-resolver.js';
+import { headerValue } from '../ingest/headers.js';
+import { parseInboundBody } from '../ingest/body.js';
+import { matchesTriggerFilter } from '../ingest/filter.js';
 import { CronTrigger } from '../triggers/cron-trigger.js';
 import { PauseStep } from '../engine/pause-step.js';
 import { leafStepId } from '../engine/node-path.js';
 // ─── Helpers ───
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 const noopLogger = {
     info: () => { },
     warn: () => { },
@@ -32,6 +40,13 @@ function generateSecret() {
     crypto.getRandomValues(bytes);
     return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
 }
+/** The trigger's author-supplied input schema, when it has one. */
+function inputSchemaOf(config) {
+    const inputSchema = (config.trigger.config ?? {})['inputSchema'];
+    return inputSchema && typeof inputSchema === 'object' && !Array.isArray(inputSchema)
+        ? inputSchema
+        : undefined;
+}
 function parseWorkflowConfig(raw) {
     return JSON.parse(raw ?? '{}');
 }
@@ -69,9 +84,9 @@ export class WorkflowRuntime {
     queue;
     scheduler;
     services;
-    steps;
-    triggers;
+    connectors;
     executor;
+    credentialResolver;
     log;
     baseUrl;
     /** Pub/sub transport for live execution events. Exposed for the router's SSE stream. */
@@ -95,9 +110,9 @@ export class WorkflowRuntime {
         this.queue = opts.queue;
         this.scheduler = opts.scheduler;
         this.services = opts.services;
-        this.steps = opts.steps;
-        this.triggers = opts.triggers;
+        this.connectors = opts.connectors;
         this.executor = opts.executor;
+        this.credentialResolver = new CredentialResolver(opts.persistence);
         this.log = opts.logger ?? noopLogger;
         this.eventBus = opts.eventBus;
         this.storage = opts.storage;
@@ -247,23 +262,26 @@ export class WorkflowRuntime {
      * can render inline in the workflow builder.
      */
     validateConfig(config) {
-        const validator = new ConfigValidator(this.triggers, this.steps);
+        const validator = new ConfigValidator(this.connectors);
         return validator.validate(config);
     }
     // ─── Workflow Lifecycle ───
     /**
      * Activate a workflow's trigger.
      *
-     * - WebhookTrigger: generates a unique path, stores it, calls onActivate()
+     * - Every trigger: its credential slots must resolve to accepted credentials
      * - CronTrigger: registers with the scheduler
-     * - EventTrigger / ManualTrigger: no activation needed (status change only)
+     *
+     * Only then is the workflow marked ACTIVE. Webhook ingest and event dispatch
+     * both key off that status, so it is what actually turns a workflow on.
      */
     async activateWorkflow(ctx, workflowId, opts) {
         // Guard up front, before any external side-effects (webhook/scheduler).
         const { record } = await this.authorizedWorkflow(ctx, workflowId, 'workflow:activate');
         await this.activateInternal(record);
-        // After the side-effects, never before: a webhook path that failed to store
-        // is not a change worth telling anyone about.
+        await this.persistence.updateWorkflow(workflowId, { status: 'ACTIVE' });
+        // After the side-effects, never before: an activation that failed is not a
+        // change worth telling anyone about.
         this.publishWorkflowChange(workflowId, 'activated', opts?.origin);
     }
     /**
@@ -274,20 +292,16 @@ export class WorkflowRuntime {
     async activateInternal(workflow) {
         const workflowId = workflow.id;
         const config = parseWorkflowConfig(workflow.config);
-        if (!this.triggers.has(config.trigger.type)) {
+        if (!this.connectors.hasTrigger(config.trigger.type)) {
             throw new Error(`Trigger type "${config.trigger.type}" is not registered`);
         }
-        const trigger = this.triggers.get(config.trigger.type);
+        const trigger = this.connectors.getTrigger(config.trigger.type);
+        // A missing, revoked or wrong-type credential fails here, naming the slot,
+        // rather than on the first event.
+        if (trigger.credentialSlots?.length) {
+            await this.credentialResolver.resolve(workflow.attributes, trigger, config.trigger.config);
+        }
         if (trigger instanceof WebhookTrigger) {
-            const secret = generateSecret();
-            const path = `/webhooks/${workflowId}/${secret}`;
-            await this.persistence.storeWebhookPath(workflowId, path, secret);
-            if (trigger.onActivate) {
-                await trigger.onActivate(config.trigger.config, {
-                    webhookUrl: this.baseUrl + path,
-                    credentials: {},
-                });
-            }
             this.log.info(`activated webhook trigger for workflow ${workflowId}`);
         }
         else if (trigger instanceof CronTrigger) {
@@ -310,24 +324,16 @@ export class WorkflowRuntime {
         // Falls through rather than returning early on an unregistered trigger type:
         // the call still succeeded, and every successful call must leave by the same
         // door so that none of them can quietly skip the notification below.
-        const trigger = this.triggers.has(config.trigger.type)
-            ? this.triggers.get(config.trigger.type)
+        const trigger = this.connectors.hasTrigger(config.trigger.type)
+            ? this.connectors.getTrigger(config.trigger.type)
             : null;
-        if (trigger instanceof WebhookTrigger) {
-            if (trigger.onDeactivate) {
-                await trigger.onDeactivate(config.trigger.config, {
-                    webhookUrl: '',
-                    credentials: {},
-                });
-            }
-            await this.persistence.removeWebhookPath(workflowId);
-            this.log.info(`deactivated webhook trigger for workflow ${workflowId}`);
-        }
-        else if (trigger instanceof CronTrigger) {
+        if (trigger instanceof CronTrigger) {
             await this.scheduler.unschedule(workflowId);
             this.log.info(`deactivated cron trigger for workflow ${workflowId}`);
         }
-        // EventTrigger, ManualTrigger and unregistered types need no teardown.
+        // Webhook, event and manual triggers need no teardown: webhook ingest and
+        // event dispatch only reach ACTIVE workflows, so the status below stops them.
+        await this.persistence.updateWorkflow(workflowId, { status: 'DISABLED' });
         this.publishWorkflowChange(workflowId, 'deactivated', opts?.origin);
     }
     // ─── Workflow callback secret ───
@@ -379,9 +385,9 @@ export class WorkflowRuntime {
         const executionIds = [];
         for (const workflow of workflows) {
             const config = parseWorkflowConfig(workflow.config);
-            if (!this.triggers.has(config.trigger.type))
+            if (!this.connectors.hasTrigger(config.trigger.type))
                 continue;
-            const trigger = this.triggers.get(config.trigger.type);
+            const trigger = this.connectors.getTrigger(config.trigger.type);
             if (!(trigger instanceof EventTrigger))
                 continue;
             // Hydrate lightweight payload → full context
@@ -399,6 +405,10 @@ export class WorkflowRuntime {
             if (!trigger.matchFilters(config.trigger.config, payload)) {
                 continue;
             }
+            // And the author's filter, before a run exists.
+            if (!matchesTriggerFilter(config.trigger.filter, payload, config.variables)) {
+                continue;
+            }
             const execId = await this.createAndEnqueue(workflow, {
                 type: event.type,
                 ...payload,
@@ -408,43 +418,95 @@ export class WorkflowRuntime {
         return executionIds;
     }
     /**
-     * Handle an incoming webhook request.
+     * Ingest a request to a workflow's webhook URL, `<baseUrl>/webhooks/<workflowId>`.
+     *
+     * The order is fixed, and the trigger's own code runs only after the sender is
+     * authenticated:
      *
-     * Looks up the workflow by webhook path, delegates to the trigger's
-     * `handleRequest()`, and enqueues an execution.
+     * 1. The workflow exists, is ACTIVE and uses a webhook trigger — else 404, the
+     *    same answer for each so workflow ids cannot be probed.
+     * 2. The trigger's credentials resolve — else 401, before any connector code runs.
+     * 3. The trigger's `handshake` may answer the request outright. It is the one
+     *    connector hook that sees an unauthenticated request, so it can only reply,
+     *    never start a run. A GET it does not answer gets 404: GET reaches nothing else.
+     * 4. The trigger's own `verify` accepts the request — else 401.
+     * 5. The body is parsed from the raw bytes — else 400.
+     * 6. The trigger turns the request into events and a reply.
+     * 7. Each event must pass the workflow's trigger filter, or it is dropped.
+     * 8. Survivors are enqueued before the reply is returned.
+     *
+     * Reasons for a rejection go to the log; responses stay generic.
      */
-    async handleWebhook(path, request) {
-        const webhookRecord = await this.persistence.getWebhookByPath(path);
-        if (!webhookRecord) {
-            return {
-                executionId: '',
-                httpResponse: { status: 404, body: { error: 'Webhook not found' } },
-            };
+    async handleWebhook(workflowId, request) {
+        const notFound = {
+            reply: { status: 404, body: { error: 'Webhook not found' } },
+            executionIds: [],
+        };
+        const unauthorized = {
+            reply: { status: 401, body: { error: 'Unauthorized' } },
+            executionIds: [],
+        };
+        const workflow = await this.persistence.getWorkflow(workflowId);
+        if (!workflow || workflow.status !== 'ACTIVE')
+            return notFound;
+        const config = parseWorkflowConfig(workflow.config);
+        const trigger = this.connectors.findTrigger(config.trigger.type)?.trigger;
+        if (!(trigger instanceof WebhookTrigger))
+            return notFound;
+        const attributes = workflow.attributes;
+        const triggerConfig = config.trigger.config;
+        let ctx;
+        try {
+            const credentials = await this.credentialResolver.resolve(attributes, trigger, triggerConfig);
+            ctx = { credentials, attributes, baseUrl: this.baseUrl };
         }
-        const workflow = await this.persistence.getWorkflow(webhookRecord.workflowId);
-        if (!workflow || workflow.status !== 'ACTIVE') {
-            return {
-                executionId: '',
-                httpResponse: { status: 404, body: { error: 'Workflow not active' } },
-            };
+        catch (err) {
+            // Fail closed: verification never runs without the credentials it needs.
+            this.log.warn(`webhook ${workflowId}: rejected, ${messageOf(err)}`);
+            return unauthorized;
         }
-        const config = parseWorkflowConfig(workflow.config);
-        const trigger = this.triggers.get(config.trigger.type);
-        if (!(trigger instanceof WebhookTrigger)) {
-            return {
-                executionId: '',
-                httpResponse: {
-                    status: 400,
-                    body: { error: 'Workflow does not use a webhook trigger' },
-                },
-            };
+        let handshakeReply;
+        try {
+            handshakeReply = await trigger.handshake(request, triggerConfig, ctx);
         }
-        const { triggerData, httpResponse } = await trigger.handleRequest(request, config.trigger.config);
-        const execId = await this.createAndEnqueue(workflow, {
-            type: config.trigger.type,
-            ...triggerData,
-        }, { publicTrigger: true });
-        return { executionId: execId, httpResponse };
+        catch (err) {
+            // A broken handshake must not block signed deliveries: carry on to verification.
+            this.log.warn(`webhook ${workflowId}: handshake threw: ${messageOf(err)}`);
+        }
+        if (handshakeReply)
+            return { reply: handshakeReply, executionIds: [] };
+        if (request.method !== 'POST')
+            return notFound;
+        let verified = false;
+        try {
+            verified = await trigger.verify(request, triggerConfig, ctx);
+        }
+        catch (err) {
+            this.log.warn(`webhook ${workflowId}: verification threw: ${messageOf(err)}`);
+        }
+        if (!verified) {
+            this.log.warn(`webhook ${workflowId}: rejected by ${trigger.type} verification`);
+            return unauthorized;
+        }
+        let body;
+        try {
+            body = parseInboundBody(request.rawBody, headerValue(request.headers, 'content-type'));
+        }
+        catch (err) {
+            this.log.warn(`webhook ${workflowId}: rejected, ${messageOf(err)}`);
+            return { reply: { status: 400, body: { error: 'Malformed request body' } }, executionIds: [] };
+        }
+        const translation = await trigger.handleRequest({ ...request, body }, triggerConfig, ctx);
+        const executionIds = [];
+        for (const event of translation.events) {
+            if (!matchesTriggerFilter(config.trigger.filter, event.payload, config.variables))
+                continue;
+            executionIds.push(await this.createAndEnqueue(workflow, { type: event.type, ...event.payload }, { publicTrigger: true }));
+        }
+        return {
+            reply: translation.reply ?? { status: 200, body: { ok: true } },
+            executionIds,
+        };
     }
     /**
      * Handle an incoming wait-callback at `POST /wait/callback/<secret>/<executionId>`.
@@ -524,91 +586,67 @@ export class WorkflowRuntime {
         return this.createAndEnqueue(workflow, triggerPayload);
     }
     /**
-     * Fire a workflow through the unauthenticated Webhook V2 API.
+     * Start a workflow from the API trigger route.
+     *
+     * No caller reaches the SDK here: the route has no session, and the SDK does
+     * not authorize whoever calls it. A host that exposes the route guards it
+     * itself, for example with an API key. The workflow must use an API trigger,
+     * and the payload must satisfy its input schema.
      *
-     * This intentionally bypasses caller authorization because the host exposes
-     * the route publicly. The workflow itself must opt in by using WEBHOOK_V2,
-     * and the execution is marked as public so privileged steps can enforce their
-     * own public-trigger restrictions.
+     * Runs are marked as public triggers, so privileged steps refuse them.
      */
-    async triggerWebhookV2Public(workflowId, payload) {
-        const workflow = await this.persistence.getWorkflow(workflowId);
-        if (!workflow) {
-            throw new Error(`Workflow ${workflowId} not found`);
-        }
-        const config = parseWorkflowConfig(workflow.config);
-        if (config.trigger.type !== 'WEBHOOK_V2') {
-            throw new Error(`Workflow ${workflowId} does not use a WEBHOOK_V2 trigger`);
-        }
-        const triggerCfg = (config.trigger.config ?? {});
-        const inputSchema = triggerCfg['inputSchema'];
-        const webhookV2InputSchema = inputSchema && Array.isArray(inputSchema['required'])
+    async triggerViaApi(workflowId, payload) {
+        const { workflow, config } = await this.apiTriggerWorkflow(workflowId);
+        const inputSchema = inputSchemaOf(config);
+        // Uploaded documents are optional on this route even when the schema lists
+        // them as required.
+        const apiInputSchema = inputSchema && Array.isArray(inputSchema['required'])
             ? {
                 ...inputSchema,
                 required: inputSchema['required'].filter((field) => field !== 'documents'),
             }
             : inputSchema;
-        const errors = validateTriggerPayload(webhookV2InputSchema, payload);
+        const errors = validateTriggerPayload(apiInputSchema, payload);
         if (errors.length > 0) {
             throw new Error(`Invalid trigger payload: ${errors.map((e) => e.message).join('; ')}`);
         }
-        return this.createAndEnqueue(workflow, {
-            type: config.trigger.type,
-            ...payload,
-        }, { publicTrigger: true });
+        return this.createAndEnqueue(workflow, { type: config.trigger.type, ...payload }, { publicTrigger: true });
     }
     /**
-     * Return the configured trigger input schema for routes that need to translate
-     * transport-level payloads before calling `triggerManual()`.
+     * What the API trigger route needs before it builds a payload: the trigger's
+     * input schema, and the workflow's scope for storing uploaded files. Checked
+     * the same way as {@link triggerViaApi}.
      */
-    async getWorkflowTriggerInputSchema(ctx, workflowId) {
-        const workflow = await this.persistence.getWorkflow(workflowId);
-        if (!workflow) {
-            throw new Error(`Workflow ${workflowId} not found`);
-        }
-        await this.require(ctx, 'workflow:run', this.workflowRef(workflow));
-        const config = parseWorkflowConfig(workflow.config);
-        const triggerCfg = (config.trigger.config ?? {});
-        const inputSchema = triggerCfg['inputSchema'];
-        return inputSchema && typeof inputSchema === 'object' && !Array.isArray(inputSchema)
-            ? inputSchema
-            : undefined;
+    async getApiTriggerTarget(workflowId) {
+        const { workflow, config } = await this.apiTriggerWorkflow(workflowId);
+        return {
+            inputSchema: inputSchemaOf(config),
+            storageScope: workflow.attributes,
+        };
     }
-    /**
-     * Return trigger input schema for public transport routes.
-     *
-     * Unlike getWorkflowTriggerInputSchema(), this does not authorize a caller;
-     * it only verifies the workflow exists and opted into the expected public
-     * trigger type.
-     */
-    async getWorkflowTriggerInputSchemaPublic(workflowId, expectedTriggerType) {
+    /** The workflow exists and uses an API trigger. */
+    async apiTriggerWorkflow(workflowId) {
         const workflow = await this.persistence.getWorkflow(workflowId);
-        if (!workflow) {
-            throw new Error(`Workflow ${workflowId} not found`);
-        }
+        if (!workflow)
+            throw new ResourceNotFoundError('Workflow', workflowId);
         const config = parseWorkflowConfig(workflow.config);
-        if (config.trigger.type !== expectedTriggerType) {
-            throw new Error(`Workflow ${workflowId} does not use a ${expectedTriggerType} trigger`);
+        const trigger = this.connectors.findTrigger(config.trigger.type)?.trigger;
+        if (!(trigger instanceof ApiTrigger)) {
+            throw new Error(`Workflow ${workflowId} does not use an API trigger`);
         }
-        const triggerCfg = (config.trigger.config ?? {});
-        const inputSchema = triggerCfg['inputSchema'];
-        return inputSchema && typeof inputSchema === 'object' && !Array.isArray(inputSchema)
-            ? inputSchema
-            : undefined;
+        return { workflow, config };
     }
     /**
-     * Return the workflow-owned storage scope for public transport routes.
+     * Return the configured trigger input schema for routes that need to translate
+     * transport-level payloads before calling `triggerManual()`.
      */
-    async getWorkflowStorageScopePublic(workflowId, expectedTriggerType) {
+    async getWorkflowTriggerInputSchema(ctx, workflowId) {
         const workflow = await this.persistence.getWorkflow(workflowId);
         if (!workflow) {
             throw new Error(`Workflow ${workflowId} not found`);
         }
-        const config = parseWorkflowConfig(workflow.config);
-        if (config.trigger.type !== expectedTriggerType) {
-            throw new Error(`Workflow ${workflowId} does not use a ${expectedTriggerType} trigger`);
-        }
-        return workflow.attributes;
+        await this.require(ctx, 'workflow:run', this.workflowRef(workflow));
+        return inputSchemaOf(parseWorkflowConfig(workflow.config));
     }
     /**
      * Resume a paused execution. Guards `execution:approve`, then does the work.
@@ -766,8 +804,10 @@ export class WorkflowRuntime {
                 // Internal post-create activation — already authorized by the create above.
                 await this.activateInternal(record);
             }
-            catch {
-                // Non-fatal — workflow is created but trigger may need manual activation
+            catch (err) {
+                // Non-fatal — the workflow is created, and its trigger can be activated
+                // once whatever failed is fixed.
+                this.log.warn(`created workflow ${id} but could not activate its trigger: ${messageOf(err)}`);
             }
         }
         this.log.info(`created workflow ${id} (${input.name})`);
@@ -1208,9 +1248,9 @@ export class WorkflowRuntime {
         if (!workflow || workflow.status !== 'ACTIVE')
             return null;
         const config = parseWorkflowConfig(workflow.config);
-        if (!this.triggers.has(config.trigger.type))
+        if (!this.connectors.hasTrigger(config.trigger.type))
             return null;
-        const trigger = this.triggers.get(config.trigger.type);
+        const trigger = this.connectors.getTrigger(config.trigger.type);
         if (!(trigger instanceof CronTrigger))
             return null;
         const metadata = JSON.parse(workflow.metadata ?? '{}');