@objectstack/trigger-api 9.3.0

package/src/api-trigger.test.ts

@@ -0,0 +1,132 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { createHmac } from 'node:crypto';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ApiTrigger, verifySignature } from './api-trigger.js';
+import type { QueueServiceSurface } from './api-trigger.js';
+
+/** In-memory queue: publish stores, deliver() drains to subscribers. */
+function makeFakeQueue() {
+    const subs = new Map<string, (m: { data: any }) => Promise<void> | void>();
+    const pending = new Map<string, any[]>();
+    let n = 0;
+    const q: QueueServiceSurface & { deliver(): Promise<number>; published: Array<{ queue: string; data: any; idempotencyKey?: string }> } = {
+        published: [],
+        async publish(queue, data, options) {
+            this.published.push({ queue, data, idempotencyKey: options?.idempotencyKey });
+            (pending.get(queue) ?? pending.set(queue, []).get(queue)!).push(data);
+            return `msg_${++n}`;
+        },
+        async subscribe(queue, handler) { subs.set(queue, handler as any); },
+        async unsubscribe(queue) { subs.delete(queue); },
+        async deliver() {
+            let delivered = 0;
+            for (const [queue, items] of pending) {
+                const handler = subs.get(queue);
+                if (!handler) continue;
+                for (const data of items.splice(0)) { await handler({ data }); delivered++; }
+            }
+            return delivered;
+        },
+    };
+    return q;
+}
+
+const logger = { info: vi.fn(), warn: vi.fn() };
+
+function sig(secret: string, body: string): string {
+    return 'sha256=' + createHmac('sha256', secret).update(body, 'utf8').digest('hex');
+}
+
+describe('ApiTrigger', () => {
+    let queue: ReturnType<typeof makeFakeQueue>;
+    let trigger: ApiTrigger;
+    let runs: any[];
+
+    beforeEach(() => {
+        queue = makeFakeQueue();
+        trigger = new ApiTrigger(() => queue, logger as any);
+        runs = [];
+        vi.clearAllMocks();
+    });
+
+    function arm(config: Record<string, unknown> = {}) {
+        trigger.start({ flowName: 'lead_intake', config }, async (ctx) => { runs.push(ctx); });
+    }
+
+    it('verifySignature accepts a correct GitHub-style signature and rejects others', () => {
+        const body = '{"a":1}';
+        expect(verifySignature('s3cret', body, sig('s3cret', body))).toBe(true);
+        expect(verifySignature('s3cret', body, sig('wrong', body))).toBe(false);
+        expect(verifySignature('s3cret', body, undefined)).toBe(false);
+        expect(verifySignature('s3cret', body, 'sha256=zz')).toBe(false);
+    });
+
+    it('202-enqueues a valid post and the consumer runs the flow with the payload as record', async () => {
+        arm({ hookId: 'hk1', secret: 's3cret' });
+        const body = JSON.stringify({ title: 'New lead', amount: 5000 });
+        const res = await trigger.handleRequest({
+            flowName: 'lead_intake', hookId: 'hk1', rawBody: body, signatureHeader: sig('s3cret', body),
+        });
+        expect(res.status).toBe(202);
+        expect(res.body.accepted).toBe(true);
+        expect(runs).toHaveLength(0); // never executed in-band
+        expect(await queue.deliver()).toBe(1);
+        expect(runs).toHaveLength(1);
+        expect(runs[0].record).toEqual({ title: 'New lead', amount: 5000 });
+        expect(runs[0].params).toEqual({ title: 'New lead', amount: 5000 });
+    });
+
+    it('answers 404 identically for unknown flows and wrong hookIds (no probing oracle)', async () => {
+        arm({ hookId: 'hk1' });
+        const a = await trigger.handleRequest({ flowName: 'nope', hookId: 'hk1', rawBody: '{}' });
+        const b = await trigger.handleRequest({ flowName: 'lead_intake', hookId: 'wrong', rawBody: '{}' });
+        expect(a).toEqual(b);
+        expect(a.status).toBe(404);
+    });
+
+    it('401s a missing or bad signature when the flow declares a secret', async () => {
+        arm({ hookId: 'hk1', secret: 's3cret' });
+        const body = '{"x":1}';
+        expect((await trigger.handleRequest({ flowName: 'lead_intake', hookId: 'hk1', rawBody: body })).status).toBe(401);
+        expect((await trigger.handleRequest({
+            flowName: 'lead_intake', hookId: 'hk1', rawBody: body, signatureHeader: sig('other', body),
+        })).status).toBe(401);
+    });
+
+    it('accepts unsigned posts when no secret is configured (and warned at arm time)', async () => {
+        arm({});
+        const res = await trigger.handleRequest({ flowName: 'lead_intake', hookId: 'default', rawBody: '{"x":1}' });
+        expect(res.status).toBe(202);
+        expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('WITHOUT a secret'));
+    });
+
+    it('400s non-object or invalid JSON bodies', async () => {
+        arm({});
+        expect((await trigger.handleRequest({ flowName: 'lead_intake', hookId: 'default', rawBody: 'not json' })).status).toBe(400);
+        expect((await trigger.handleRequest({ flowName: 'lead_intake', hookId: 'default', rawBody: '[1,2]' })).status).toBe(400);
+    });
+
+    it('passes x-idempotency-key through to the queue dedup window', async () => {
+        arm({});
+        await trigger.handleRequest({
+            flowName: 'lead_intake', hookId: 'default', rawBody: '{}', idempotencyKey: 'evt_42',
+        });
+        expect(queue.published[0].idempotencyKey).toBe('evt_42');
+    });
+
+    it('503s when no queue service is registered', async () => {
+        const t = new ApiTrigger(() => null, logger as any);
+        t.start({ flowName: 'f', config: {} }, async () => {});
+        const res = await t.handleRequest({ flowName: 'f', hookId: 'default', rawBody: '{}' });
+        expect(res.status).toBe(503);
+    });
+
+    it('stop() disarms the hook and unsubscribes the queue', async () => {
+        arm({ hookId: 'hk1' });
+        trigger.stop('lead_intake');
+        const res = await trigger.handleRequest({ flowName: 'lead_intake', hookId: 'hk1', rawBody: '{}' });
+        expect(res.status).toBe(404);
+        expect(trigger.listHooks()).toHaveLength(0);
+    });
+});

package/src/api-trigger.ts

@@ -0,0 +1,216 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import type { AutomationContext } from '@objectstack/spec/contracts';
+
+/**
+ * Structural mirror of the automation engine's `FlowTriggerBinding` — same
+ * decoupling pattern as `trigger-schedule` / `trigger-record-change`: this
+ * package never imports `service-automation`.
+ */
+export interface FlowTriggerBinding {
+    readonly flowName: string;
+    readonly object?: string;
+    readonly event?: string;
+    readonly condition?: string | { dialect?: string; source?: string; ast?: unknown };
+    readonly schedule?: unknown;
+    readonly config?: Record<string, unknown>;
+}
+
+/** Structural mirror of the engine's `FlowTrigger` extension point. */
+export interface FlowTrigger {
+    readonly type: string;
+    start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void;
+    stop(flowName: string): void;
+}
+
+/**
+ * The slice of `IQueueService` this trigger needs. Boundary triggers MUST
+ * ingest through the queue (ADR-0041 §5): inbound HTTP is the first event
+ * source whose rate we don't control, and a slow flow execution may neither
+ * drop nor block inbound events. At-least-once delivery; flows should be
+ * authored idempotently (an `x-idempotency-key` header passes through to the
+ * queue's dedup window).
+ */
+export interface QueueServiceSurface {
+    publish<T = unknown>(queue: string, data: T, options?: { idempotencyKey?: string }): Promise<string>;
+    subscribe<T = unknown>(queue: string, handler: (message: { data: T }) => Promise<void> | void): Promise<void>;
+    unsubscribe(queue: string): Promise<void>;
+}
+
+/** Minimal logger surface (matches core's `ctx.logger`). */
+export interface TriggerLogger {
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    debug?(msg: string, ...args: unknown[]): void;
+}
+
+const QUEUE_PREFIX = 'flow-api';
+
+/** One armed inbound hook. */
+interface ArmedHook {
+    flowName: string;
+    hookId: string;
+    secret?: string;
+    queue: string;
+    callback: (ctx: AutomationContext) => Promise<void>;
+}
+
+/** Constant-time string compare (length leak only). */
+function safeEqual(a: string, b: string): boolean {
+    const ab = Buffer.from(a, 'utf8');
+    const bb = Buffer.from(b, 'utf8');
+    if (ab.length !== bb.length) return false;
+    return timingSafeEqual(ab, bb);
+}
+
+/**
+ * GitHub/Stripe-style HMAC verification: the sender computes
+ * `sha256=<hex hmac of the raw body>` with the shared per-flow secret and
+ * sends it as `x-objectstack-signature`.
+ */
+export function verifySignature(secret: string, rawBody: string, header: string | undefined): boolean {
+    if (!header) return false;
+    const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
+    return safeEqual(expected, header.trim());
+}
+
+/**
+ * `api` flow trigger (ADR-0041 Tier 1) — inbound webhook/HTTP.
+ *
+ * The engine binds every `type: 'api'` flow to this trigger; `start()` arms a
+ * hook (URL path + optional HMAC secret from the start node's `config`) and
+ * subscribes a queue consumer that runs the flow. The HTTP side
+ * ({@link handleRequest}) validates and **enqueues** — it never executes the
+ * flow in-band:
+ *
+ *   POST /api/v1/automation/hooks/:flowName/:hookId
+ *     → 404 unknown flow / wrong hookId
+ *     → 401 missing/bad HMAC signature (when the flow declares a `secret`)
+ *     → 400 non-JSON body
+ *     → 202 { accepted, messageId } — queued; a consumer executes the flow
+ *
+ * The JSON payload is exposed to the flow as the trigger record (`$record` /
+ * `record.*`, fields flattened to bare references) plus `params` — the same
+ * authoring surface record-change flows use.
+ *
+ * Start-node config keys:
+ *   - `hookId`  — URL path token (default `'default'`); rotate it to revoke
+ *                 old URLs without renaming the flow.
+ *   - `secret`  — HMAC-SHA256 shared secret. Strongly recommended; without it
+ *                 the endpoint accepts unsigned posts (the trigger logs a
+ *                 warning at arm time).
+ */
+export class ApiTrigger implements FlowTrigger {
+    readonly type = 'api';
+
+    private hooks = new Map<string, ArmedHook>();
+
+    constructor(
+        private readonly getQueue: () => QueueServiceSurface | null,
+        private readonly logger: TriggerLogger,
+    ) {}
+
+    /** Currently armed hooks (for diagnostics/tests). */
+    listHooks(): Array<{ flowName: string; hookId: string; signed: boolean }> {
+        return [...this.hooks.values()].map(h => ({
+            flowName: h.flowName, hookId: h.hookId, signed: !!h.secret,
+        }));
+    }
+
+    start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void {
+        const cfg = (binding.config ?? {}) as Record<string, unknown>;
+        const hookId = typeof cfg.hookId === 'string' && cfg.hookId.trim() ? cfg.hookId.trim() : 'default';
+        const secret = typeof cfg.secret === 'string' && cfg.secret.trim() ? cfg.secret.trim() : undefined;
+        const queue = `${QUEUE_PREFIX}:${binding.flowName}`;
+
+        const hook: ArmedHook = { flowName: binding.flowName, hookId, secret, queue, callback };
+        this.hooks.set(binding.flowName, hook);
+
+        const q = this.getQueue();
+        if (!q) {
+            this.logger.warn(
+                `[trigger-api] no queue service — inbound posts for flow '${binding.flowName}' will be rejected until one is registered`,
+            );
+        } else {
+            void q.subscribe<{ payload: Record<string, unknown> }>(queue, async (message) => {
+                const payload = (message?.data as any)?.payload ?? {};
+                await hook.callback({
+                    // The webhook body IS the trigger record: `$record`, `record.*`,
+                    // and bare field references all resolve, matching how
+                    // record-change flows are authored.
+                    record: payload,
+                    params: { ...payload },
+                    event: 'api',
+                } as AutomationContext);
+            }).catch((err: any) => {
+                this.logger.warn(`[trigger-api] subscribe failed for '${queue}': ${err?.message ?? err}`);
+            });
+        }
+
+        if (!secret) {
+            this.logger.warn(
+                `[trigger-api] flow '${binding.flowName}' armed WITHOUT a secret — endpoint accepts unsigned posts`,
+            );
+        }
+        this.logger.info(
+            `[trigger-api] armed: POST .../automation/hooks/${binding.flowName}/${hookId}${secret ? ' (HMAC required)' : ''}`,
+        );
+    }
+
+    stop(flowName: string): void {
+        const hook = this.hooks.get(flowName);
+        if (!hook) return;
+        this.hooks.delete(flowName);
+        const q = this.getQueue();
+        if (q) void q.unsubscribe(hook.queue).catch(() => { /* already gone */ });
+        this.logger.info(`[trigger-api] disarmed: flow '${flowName}'`);
+    }
+
+    /**
+     * Handle one inbound request. Transport-agnostic: the plugin adapts this
+     * to the host HTTP server. Returns the response to send.
+     */
+    async handleRequest(input: {
+        flowName: string;
+        hookId: string;
+        rawBody: string;
+        signatureHeader?: string;
+        idempotencyKey?: string;
+    }): Promise<{ status: number; body: Record<string, unknown> }> {
+        const hook = this.hooks.get(input.flowName);
+        // Unknown flow and wrong hookId answer identically — no oracle for
+        // probing which flows exist.
+        if (!hook || !safeEqual(hook.hookId, input.hookId)) {
+            return { status: 404, body: { error: 'not_found' } };
+        }
+        if (hook.secret && !verifySignature(hook.secret, input.rawBody, input.signatureHeader)) {
+            return { status: 401, body: { error: 'invalid_signature' } };
+        }
+
+        let payload: Record<string, unknown>;
+        try {
+            const parsed: unknown = input.rawBody.trim() ? JSON.parse(input.rawBody) : {};
+            if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                return { status: 400, body: { error: 'invalid_body', message: 'Body must be a JSON object.' } };
+            }
+            payload = parsed as Record<string, unknown>;
+        } catch {
+            return { status: 400, body: { error: 'invalid_body', message: 'Body must be valid JSON.' } };
+        }
+
+        const q = this.getQueue();
+        if (!q) {
+            return { status: 503, body: { error: 'queue_unavailable', message: 'No queue service is registered.' } };
+        }
+        try {
+            const messageId = await q.publish(hook.queue, { payload }, {
+                idempotencyKey: input.idempotencyKey,
+            });
+            return { status: 202, body: { accepted: true, messageId } };
+        } catch (err: any) {
+            this.logger.warn(`[trigger-api] enqueue failed for '${hook.queue}': ${err?.message ?? err}`);
+            return { status: 503, body: { error: 'enqueue_failed' } };
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export { ApiTriggerPlugin, HOOKS_PATH } from './plugin.js';
+export { ApiTrigger, verifySignature } from './api-trigger.js';
+export type {
+    FlowTrigger,
+    FlowTriggerBinding,
+    QueueServiceSurface,
+    TriggerLogger,
+} from './api-trigger.js';

package/src/plugin.ts

@@ -0,0 +1,105 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import { ApiTrigger } from './api-trigger.js';
+import type { FlowTrigger, QueueServiceSurface } from './api-trigger.js';
+
+/**
+ * The slice of the automation engine this plugin needs. Declared structurally
+ * so the plugin does not take a build dependency on
+ * `@objectstack/service-automation`.
+ */
+interface AutomationTriggerRegistry {
+    registerTrigger(trigger: FlowTrigger): void;
+    unregisterTrigger?(type: string): void;
+}
+
+/** The slice of the Hono host server this plugin needs. */
+interface HttpServerSurface {
+    getRawApp(): {
+        post(path: string, handler: (c: any) => Promise<unknown> | unknown): void;
+    } | null;
+}
+
+/** Mount point for inbound hooks on the host HTTP server. */
+export const HOOKS_PATH = '/api/v1/automation/hooks/:flowName/:hookId';
+
+/**
+ * ApiTriggerPlugin (ADR-0041 Tier 1)
+ *
+ * Makes `type: 'api'` flows actually fire. The automation engine derives an
+ * `api` binding from the flow; this plugin provides the concrete trigger:
+ *
+ *  - mounts `POST /api/v1/automation/hooks/:flowName/:hookId` on the host
+ *    Hono app (resolved via the `http-server` service);
+ *  - validates hookId + HMAC signature (`x-objectstack-signature`,
+ *    GitHub/Stripe style, constant-time) against the flow's start-node
+ *    config;
+ *  - **enqueues** the payload (`queue` service) and ACKs 202 — flow
+ *    execution happens on the queue consumer, never in-band with the
+ *    inbound request (ADR-0041 §5: boundary triggers must not let a slow
+ *    flow drop or block events). `x-idempotency-key` passes through to the
+ *    queue's dedup window.
+ *
+ * Webhook payloads surface to the flow as the trigger record (`$record` /
+ * `record.*` / bare field references) — the same authoring surface
+ * record-change flows use.
+ */
+export class ApiTriggerPlugin implements Plugin {
+    name = 'com.objectstack.trigger.api';
+    type = 'standard';
+    version = '1.0.0';
+    dependencies = ['com.objectstack.service.queue'];
+
+    async init(ctx: PluginContext): Promise<void> {
+        ctx.logger.info('API trigger plugin initialized');
+    }
+
+    async start(ctx: PluginContext): Promise<void> {
+        // Resolve at kernel:ready — the automation engine, queue service, and
+        // HTTP server may all start after this plugin.
+        ctx.hook('kernel:ready', async () => {
+            const automation = this.resolveService<AutomationTriggerRegistry>(ctx, 'automation');
+            if (!automation || typeof automation.registerTrigger !== 'function') {
+                ctx.logger.warn('ApiTriggerPlugin: automation service not available — api trigger NOT installed');
+                return;
+            }
+            if (!this.resolveService<QueueServiceSurface>(ctx, 'queue')) {
+                ctx.logger.warn('ApiTriggerPlugin: queue service not available — inbound posts will 503 until one is registered');
+            }
+
+            const trigger = new ApiTrigger(
+                () => this.resolveService<QueueServiceSurface>(ctx, 'queue'),
+                ctx.logger,
+            );
+            automation.registerTrigger(trigger);
+
+            const http = this.resolveService<HttpServerSurface>(ctx, 'http-server');
+            const rawApp = http && typeof http.getRawApp === 'function' ? http.getRawApp() : null;
+            if (!rawApp) {
+                ctx.logger.warn('ApiTriggerPlugin: HTTP server not available — hooks endpoint not mounted');
+                return;
+            }
+            rawApp.post(HOOKS_PATH, async (c: any) => {
+                const rawBody = await c.req.text();
+                const out = await trigger.handleRequest({
+                    flowName: c.req.param('flowName'),
+                    hookId: c.req.param('hookId'),
+                    rawBody,
+                    signatureHeader: c.req.header('x-objectstack-signature'),
+                    idempotencyKey: c.req.header('x-idempotency-key') || undefined,
+                });
+                return c.json(out.body, out.status);
+            });
+            ctx.logger.info(`ApiTriggerPlugin: api trigger registered, hooks mounted at POST ${HOOKS_PATH}`);
+        });
+    }
+
+    private resolveService<T>(ctx: PluginContext, name: string): T | null {
+        try {
+            return ctx.getService<T>(name) ?? null;
+        } catch {
+            return null;
+        }
+    }
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules",
+    "**/*.test.ts"
+  ]
+}