|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * ADR-0041 — `trigger-api`'s acceptance criteria name "a per-flow secret; HMAC |
| 5 | + * signature verification". A flow whose binding resolves to the `api` trigger |
| 6 | + * and whose start node carries no non-blank `config.secret` is refused at |
| 7 | + * REGISTRATION — the publish seam — so its author learns before deploying. |
| 8 | + * (`@objectstack/trigger-api`'s own `start()` refuses the same binding for a |
| 9 | + * host that binds without this engine; its tests pin that half.) |
| 10 | + * |
| 11 | + * Every refusal case asserts the substance, not only the throw: the flow is |
| 12 | + * absent from the engine afterwards and the api trigger was never started. The |
| 13 | + * contrast cases pin what stays legal — a signed `api` flow registers and its |
| 14 | + * trigger receives that secret, and a flow that binds no `api` trigger needs |
| 15 | + * none. |
| 16 | + */ |
| 17 | + |
| 18 | +import { describe, it, expect, beforeEach } from 'vitest'; |
| 19 | +import { AutomationEngine } from './engine.js'; |
| 20 | +import type { FlowTrigger, FlowTriggerBinding } from './engine.js'; |
| 21 | + |
| 22 | +function createTestLogger() { |
| 23 | + return { debug() {}, info() {}, warn() {}, error() {} } as any; |
| 24 | +} |
| 25 | + |
| 26 | +/** A minimal registrable flow whose start node carries `config`. */ |
| 27 | +function flowWith( |
| 28 | + name: string, |
| 29 | + config: Record<string, unknown>, |
| 30 | + type: string = 'api', |
| 31 | + extra: Record<string, unknown> = {}, |
| 32 | +) { |
| 33 | + return { |
| 34 | + name, |
| 35 | + label: name, |
| 36 | + type, |
| 37 | + status: 'active', |
| 38 | + ...extra, |
| 39 | + nodes: [ |
| 40 | + { id: 'start', type: 'start', label: 'Start', config }, |
| 41 | + { id: 'end', type: 'end', label: 'End' }, |
| 42 | + ], |
| 43 | + edges: [{ id: 'e1', source: 'start', target: 'end' }], |
| 44 | + }; |
| 45 | +} |
| 46 | + |
| 47 | +describe('ADR-0041 — an api flow registers only with its per-flow secret', () => { |
| 48 | + let engine: AutomationEngine; |
| 49 | + let started: FlowTriggerBinding[]; |
| 50 | + let stopped: string[]; |
| 51 | + |
| 52 | + beforeEach(() => { |
| 53 | + engine = new AutomationEngine(createTestLogger()); |
| 54 | + started = []; |
| 55 | + stopped = []; |
| 56 | + // A recording `api` trigger, registered BEFORE the flows, so a flow that |
| 57 | + // got past registration would be started on it at once. |
| 58 | + const trigger: FlowTrigger = { |
| 59 | + type: 'api', |
| 60 | + start: (binding) => { |
| 61 | + started.push(binding); |
| 62 | + }, |
| 63 | + stop: (flowName) => { |
| 64 | + stopped.push(flowName); |
| 65 | + }, |
| 66 | + }; |
| 67 | + engine.registerTrigger(trigger); |
| 68 | + }); |
| 69 | + |
| 70 | + const refused: Array<{ label: string; flow: ReturnType<typeof flowWith> }> = [ |
| 71 | + { label: "a `type: 'api'` flow with no secret", flow: flowWith('no_secret', {}) }, |
| 72 | + { label: "a `type: 'api'` flow with a blank secret", flow: flowWith('blank_secret', { secret: ' ' }) }, |
| 73 | + { label: "a `type: 'api'` flow with a non-string secret", flow: flowWith('numeric_secret', { secret: 42 }) }, |
| 74 | + { |
| 75 | + label: "a start-node `triggerType: 'api'` flow with no secret", |
| 76 | + flow: flowWith('token_no_secret', { triggerType: 'api', hookId: 'intake' }, 'autolaunched'), |
| 77 | + }, |
| 78 | + { |
| 79 | + // Status-agnostic, like every other registration refusal: an |
| 80 | + // `obsolete` flow is re-enabled by a toggle, not by re-registering. |
| 81 | + label: "an obsolete `type: 'api'` flow with no secret", |
| 82 | + flow: flowWith('obsolete_no_secret', {}, 'api', { status: 'obsolete' }), |
| 83 | + }, |
| 84 | + ]; |
| 85 | + |
| 86 | + for (const row of refused) { |
| 87 | + it(`refuses ${row.label} at registration, naming the flow and config.secret, and arms nothing`, async () => { |
| 88 | + const name = row.flow.name; |
| 89 | + expect(() => engine.registerFlow(name, row.flow as never)).toThrow( |
| 90 | + new RegExp(`Flow '${name}' rejected: .*\`api\` trigger.*config\\.secret`, 's'), |
| 91 | + ); |
| 92 | + |
| 93 | + // Not registered: nothing to read back, nothing to run, nothing armed. |
| 94 | + expect(await engine.getFlow(name)).toBeNull(); |
| 95 | + expect(engine.getFlowRuntimeStates().map((s) => s.name)).not.toContain(name); |
| 96 | + expect(started).toEqual([]); |
| 97 | + }); |
| 98 | + } |
| 99 | + |
| 100 | + it('registers and binds an api flow that carries its secret, handing the trigger that secret', async () => { |
| 101 | + engine.registerFlow('signed_hook', flowWith('signed_hook', { hookId: 'intake', secret: 's3cret' }) as never); |
| 102 | + |
| 103 | + expect(await engine.getFlow('signed_hook')).not.toBeNull(); |
| 104 | + expect(started).toHaveLength(1); |
| 105 | + expect(started[0].flowName).toBe('signed_hook'); |
| 106 | + expect(started[0].config).toMatchObject({ hookId: 'intake', secret: 's3cret' }); |
| 107 | + const state = engine.getFlowRuntimeStates().find((s) => s.name === 'signed_hook'); |
| 108 | + expect(state?.triggerType).toBe('api'); |
| 109 | + }); |
| 110 | + |
| 111 | + it('requires nothing of a flow that binds no api trigger — an autolaunched flow registers without a secret', async () => { |
| 112 | + engine.registerFlow('manual', flowWith('manual', {}, 'autolaunched') as never); |
| 113 | + |
| 114 | + expect(await engine.getFlow('manual')).not.toBeNull(); |
| 115 | + expect(started).toEqual([]); |
| 116 | + expect((await engine.execute('manual')).success).toBe(true); |
| 117 | + }); |
| 118 | + |
| 119 | + it('refuses a re-registration that drops the secret, and the registered signed version stays armed', async () => { |
| 120 | + engine.registerFlow('signed_hook', flowWith('signed_hook', { secret: 's3cret' }) as never); |
| 121 | + expect(started).toHaveLength(1); |
| 122 | + |
| 123 | + expect(() => engine.registerFlow('signed_hook', flowWith('signed_hook', {}) as never)).toThrow( |
| 124 | + /Flow 'signed_hook' rejected: .*config\.secret/s, |
| 125 | + ); |
| 126 | + |
| 127 | + // The refused definition never replaced the stored one, and the trigger |
| 128 | + // was neither stopped nor re-started with the unsigned binding. |
| 129 | + const stored = await engine.getFlow('signed_hook'); |
| 130 | + const start = stored?.nodes.find((n) => n.type === 'start'); |
| 131 | + expect((start?.config as Record<string, unknown> | undefined)?.secret).toBe('s3cret'); |
| 132 | + expect(started).toHaveLength(1); |
| 133 | + expect(stopped).toEqual([]); |
| 134 | + }); |
| 135 | +}); |
0 commit comments