@multiplier-labs/stepflow 0.3.4 → 0.3.8

package/src/utils/retry.ts

@@ -1,121 +0,0 @@
-/**
- * Retry utilities for the workflow engine.
- */
-
-import { WorkflowCanceledError } from './errors';
-
-/**
- * Options for retry behavior.
- */
-export interface RetryOptions {
-  /** Maximum number of retry attempts (default: 3) */
-  maxRetries: number;
-  /** Initial delay between retries in ms (default: 1000) */
-  delay: number;
-  /** Backoff multiplier (default: 2) */
-  backoff: number;
-  /** Optional abort signal to cancel retries */
-  signal?: AbortSignal;
-  /** Optional callback before each retry */
-  onRetry?: (attempt: number, error: Error, nextDelay: number) => void;
-}
-
-/**
- * Default retry options.
- */
-export const DEFAULT_RETRY_OPTIONS: RetryOptions = {
-  maxRetries: 3,
-  delay: 1000,
-  backoff: 2,
-};
-
-/**
- * Sleep for a given number of milliseconds.
- * Can be canceled via AbortSignal.
- */
-export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(new WorkflowCanceledError('run'));
-      return;
-    }
-
-    const cleanup = () => {
-      clearTimeout(timeoutId);
-      if (onAbort) signal?.removeEventListener('abort', onAbort);
-    };
-
-    let onAbort: (() => void) | undefined;
-
-    const timeoutId = setTimeout(() => {
-      cleanup();
-      resolve();
-    }, ms);
-
-    if (signal) {
-      onAbort = () => {
-        cleanup();
-        reject(new WorkflowCanceledError('run'));
-      };
-      signal.addEventListener('abort', onAbort, { once: true });
-    }
-  });
-}
-
-/**
- * Execute a function with retry logic.
- *
- * @param fn - The async function to execute
- * @param options - Retry configuration
- * @returns The result of the function
- * @throws The last error if all retries are exhausted
- */
-export async function withRetry<T>(
-  fn: () => Promise<T>,
-  options: Partial<RetryOptions> = {}
-): Promise<T> {
-  const opts: RetryOptions = { ...DEFAULT_RETRY_OPTIONS, ...options };
-  let lastError: Error | undefined;
-  let currentDelay = opts.delay;
-
-  for (let attempt = 1; attempt <= opts.maxRetries + 1; attempt++) {
-    // Check if aborted before attempting
-    if (opts.signal?.aborted) {
-      throw new WorkflowCanceledError('run');
-    }
-
-    try {
-      return await fn();
-    } catch (error) {
-      lastError = error instanceof Error ? error : new Error(String(error));
-
-      // If this was the last attempt, throw
-      if (attempt > opts.maxRetries) {
-        throw lastError;
-      }
-
-      // Call onRetry callback if provided
-      opts.onRetry?.(attempt, lastError, currentDelay);
-
-      // Wait before next attempt
-      await sleep(currentDelay, opts.signal);
-
-      // Apply backoff multiplier
-      currentDelay = Math.round(currentDelay * opts.backoff);
-    }
-  }
-
-  // This should never be reached, but TypeScript needs it
-  throw lastError ?? new Error('Retry failed');
-}
-
-/**
- * Calculate the delay for a specific retry attempt.
- */
-export function calculateRetryDelay(
-  attempt: number,
-  baseDelay: number,
-  backoff: number
-): number {
-  return Math.round(baseDelay * Math.pow(backoff, attempt - 1));
-}

package/src/utils/safe-json.test.ts

@@ -1,166 +0,0 @@
-/**
- * Tests for safeJsonParse — audit findings L3 + M2.
- */
-
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import {
-  safeJsonParse,
-  safeParseField,
-  safeParseOptionalField,
-  getJsonParseCorruptionCount,
-  resetJsonParseCorruptionCount,
-} from './safe-json';
-
-function makeLogger() {
-  return {
-    debug: vi.fn(),
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-  };
-}
-
-describe('safeJsonParse', () => {
-  beforeEach(() => {
-    resetJsonParseCorruptionCount();
-  });
-
-  it('returns parsed value for valid JSON without logging', () => {
-    const logger = makeLogger();
-    const result = safeJsonParse('{"a":1}', null, { component: 'X', logger });
-    expect(result).toEqual({ a: 1 });
-    expect(logger.warn).not.toHaveBeenCalled();
-    expect(getJsonParseCorruptionCount()).toBe(0);
-  });
-
-  it('returns fallback on SyntaxError and increments the corruption counter', () => {
-    const logger = makeLogger();
-    const result = safeJsonParse('not-json', { fallback: true }, {
-      component: 'TestAdapter',
-      rowId: 'run-123',
-      column: 'input_json',
-      logger,
-    });
-    expect(result).toEqual({ fallback: true });
-    expect(getJsonParseCorruptionCount()).toBe(1);
-    expect(logger.warn).toHaveBeenCalledTimes(1);
-  });
-
-  it('emits row id, column, length, type — but never the raw value', () => {
-    const logger = makeLogger();
-    const sensitive = '{"sensitive":"PII-DATA-IN-DATABASE"]';
-    safeJsonParse(sensitive, undefined, {
-      component: 'TestAdapter',
-      rowId: 'run-456',
-      column: 'metadata_json',
-      logger,
-    });
-
-    expect(logger.warn).toHaveBeenCalledTimes(1);
-    const [message, meta] = logger.warn.mock.calls[0];
-    expect(message).toContain('TestAdapter');
-    expect(message).toContain('Corrupted JSON');
-    // Critical: do not leak raw payload via message OR metadata.
-    const serialized = JSON.stringify([message, meta]);
-    expect(serialized).not.toContain('PII-DATA-IN-DATABASE');
-
-    expect(meta).toMatchObject({
-      rowId: 'run-456',
-      column: 'metadata_json',
-      length: sensitive.length,
-      type: 'string',
-    });
-    expect(meta.error).toEqual(expect.any(String));
-    expect(meta.corruptionCount).toBe(1);
-  });
-
-  it('does not call console.warn or console.error directly', () => {
-    const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
-    try {
-      safeJsonParse('garbage{', null, { component: 'TestAdapter' });
-      expect(consoleWarn).not.toHaveBeenCalled();
-      expect(consoleError).not.toHaveBeenCalled();
-    } finally {
-      consoleWarn.mockRestore();
-      consoleError.mockRestore();
-    }
-  });
-
-  it('rethrows non-syntax errors', () => {
-    // SyntaxError-only catch — make JSON.parse throw something else and
-    // confirm it propagates instead of being swallowed.
-    const original = JSON.parse;
-    (JSON as any).parse = () => {
-      throw new TypeError('boom');
-    };
-    try {
-      expect(() =>
-        safeJsonParse('{}', null, { component: 'X' })
-      ).toThrowError(TypeError);
-    } finally {
-      (JSON as any).parse = original;
-    }
-    expect(getJsonParseCorruptionCount()).toBe(0);
-  });
-
-  it('counts corruption events across multiple calls', () => {
-    safeJsonParse('bad-1{', null, { component: 'A' });
-    safeJsonParse('bad-2{', null, { component: 'B' });
-    safeJsonParse('{"ok":1}', null, { component: 'C' });
-    expect(getJsonParseCorruptionCount()).toBe(2);
-  });
-});
-
-describe('safeParseField', () => {
-  beforeEach(() => {
-    resetJsonParseCorruptionCount();
-  });
-
-  it('parses string values', () => {
-    const result = safeParseField('{"x":1}', {}, { component: 'X' });
-    expect(result).toEqual({ x: 1 });
-  });
-
-  it('passes non-string values through unchanged', () => {
-    const obj = { x: 1 };
-    expect(safeParseField(obj, {}, { component: 'X' })).toBe(obj);
-    expect(safeParseField(42, {}, { component: 'X' })).toBe(42);
-  });
-
-  it('returns fallback on syntax error', () => {
-    const result = safeParseField('garbage{', { fallback: 1 }, { component: 'X' });
-    expect(result).toEqual({ fallback: 1 });
-    expect(getJsonParseCorruptionCount()).toBe(1);
-  });
-});
-
-describe('safeParseOptionalField', () => {
-  beforeEach(() => {
-    resetJsonParseCorruptionCount();
-  });
-
-  it('returns undefined for falsy values', () => {
-    expect(safeParseOptionalField(null, { component: 'X' })).toBeUndefined();
-    expect(safeParseOptionalField(undefined, { component: 'X' })).toBeUndefined();
-    expect(safeParseOptionalField('', { component: 'X' })).toBeUndefined();
-    expect(safeParseOptionalField(0, { component: 'X' })).toBeUndefined();
-  });
-
-  it('parses string values', () => {
-    expect(
-      safeParseOptionalField('{"a":1}', { component: 'X' })
-    ).toEqual({ a: 1 });
-  });
-
-  it('passes non-string truthy values through unchanged', () => {
-    const obj = { a: 1 };
-    expect(safeParseOptionalField(obj, { component: 'X' })).toBe(obj);
-  });
-
-  it('returns undefined on syntax error and increments counter', () => {
-    const result = safeParseOptionalField('garbage{', { component: 'X' });
-    expect(result).toBeUndefined();
-    expect(getJsonParseCorruptionCount()).toBe(1);
-  });
-});

package/src/utils/safe-json.ts

@@ -1,107 +0,0 @@
-/**
- * Safe JSON-parse helpers shared by storage and scheduler adapters.
- *
- * When a stored JSON column is corrupted, we want to surface the problem
- * operationally — structured log + counter — instead of silently degrading.
- * The logger payload is restricted to safe metadata (component, row id,
- * column, payload length, payload type, parser error message). The raw
- * value is intentionally never logged because it may contain user-provided
- * run / step input.
- *
- * Audit: 2026-04-27 findings L3 (corruption visibility) and M2 (do not
- * bypass the configured `Logger` or leak the raw value via `console`).
- */
-
-import type { Logger } from '../core/types';
-
-let corruptionCount = 0;
-
-/** Cumulative number of `safeJsonParse` failures since process start. */
-export function getJsonParseCorruptionCount(): number {
-  return corruptionCount;
-}
-
-/** Reset the corruption counter. Tests only. */
-export function resetJsonParseCorruptionCount(): void {
-  corruptionCount = 0;
-}
-
-export interface SafeJsonParseContext {
-  /** Component label, e.g. `SQLiteStorageAdapter`. */
-  component: string;
-  /** Optional database row id, surfaced in the warning so operators can locate the bad row. */
-  rowId?: string;
-  /** Optional column name for additional context. */
-  column?: string;
-  /** Optional structured logger; without one, only the counter is bumped. */
-  logger?: Logger;
-}
-
-/**
- * Storage-adapter-level slice of `SafeJsonParseContext` — the part each
- * adapter binds once (its component label + optional logger). Row mappers
- * extend this with `rowId` and `column` per field, so corruption logs always
- * identify the bad row.
- *
- * Shared between `src/storage/postgres-core.ts` and
- * `src/storage/sqlite-core.ts` so all storage adapters use one mapper-context
- * shape regardless of backend.
- */
-export type MapperContext = Pick<SafeJsonParseContext, 'component' | 'logger'>;
-
-/**
- * Parse a JSON string; on `SyntaxError` return `fallback`, increment the
- * corruption counter, and emit a structured warn log via `ctx.logger` (if
- * supplied). Non-syntax errors propagate so unexpected runtime issues are
- * still loud.
- */
-export function safeJsonParse<T = unknown>(
-  json: string,
-  fallback: T,
-  ctx: SafeJsonParseContext
-): T | unknown {
-  try {
-    return JSON.parse(json);
-  } catch (error) {
-    if (error instanceof SyntaxError) {
-      corruptionCount++;
-      ctx.logger?.warn(
-        `[${ctx.component}] Corrupted JSON in database row, using fallback`,
-        {
-          rowId: ctx.rowId,
-          column: ctx.column,
-          length: typeof json === 'string' ? json.length : undefined,
-          type: typeof json,
-          error: error.message,
-          corruptionCount,
-        }
-      );
-      return fallback;
-    }
-    throw error;
-  }
-}
-
-/** Parse a column value if it's still a JSON string; pass through otherwise. */
-export function safeParseField(
-  value: unknown,
-  fallback: unknown,
-  ctx: SafeJsonParseContext
-): unknown {
-  if (typeof value === 'string') {
-    return safeJsonParse(value, fallback, ctx);
-  }
-  return value;
-}
-
-/** Same as `safeParseField` but returns `undefined` for falsy/missing values. */
-export function safeParseOptionalField(
-  value: unknown,
-  ctx: SafeJsonParseContext
-): unknown {
-  if (!value) return undefined;
-  if (typeof value === 'string') {
-    return safeJsonParse(value, undefined, ctx);
-  }
-  return value;
-}

package/src/utils/webhook-signature.test.ts

@@ -1,111 +0,0 @@
-/**
- * Tests for verifyWebhookSignature / signWebhookPayload — audit finding L2.
- *
- * Round-trips against the WebCrypto-based signer used by `WebhookEventTransport`
- * to confirm both implementations agree on the wire format.
- */
-
-import { describe, it, expect } from 'vitest';
-import { signWebhookPayload, verifyWebhookSignature } from './webhook-signature';
-
-async function signWithWebCrypto(payload: string, secret: string): Promise<string> {
-  const encoder = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    'raw',
-    encoder.encode(secret),
-    { name: 'HMAC', hash: 'SHA-256' },
-    false,
-    ['sign'],
-  );
-  const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(payload));
-  const hex = Array.from(new Uint8Array(signature))
-    .map((b) => b.toString(16).padStart(2, '0'))
-    .join('');
-  return `sha256=${hex}`;
-}
-
-describe('signWebhookPayload', () => {
-  it('produces a sha256= prefixed lowercase hex digest', () => {
-    const sig = signWebhookPayload('hello', 'shhh');
-    expect(sig).toMatch(/^sha256=[0-9a-f]{64}$/);
-  });
-
-  it('matches the WebCrypto signer used by WebhookEventTransport', async () => {
-    const payload = JSON.stringify({ id: 'evt_1', type: 'run.completed' });
-    const secret = 'whsec_test';
-    const fromHelper = signWebhookPayload(payload, secret);
-    const fromWebCrypto = await signWithWebCrypto(payload, secret);
-    expect(fromHelper).toBe(fromWebCrypto);
-  });
-});
-
-describe('verifyWebhookSignature', () => {
-  const secret = 'whsec_test';
-  const payload = '{"event":"ping"}';
-
-  it('verifies a signature produced by the helper', () => {
-    const sig = signWebhookPayload(payload, secret);
-    expect(verifyWebhookSignature(payload, sig, secret)).toBe(true);
-  });
-
-  it('verifies a signature produced by the WebCrypto signer (cross-impl)', async () => {
-    const sig = await signWithWebCrypto(payload, secret);
-    expect(verifyWebhookSignature(payload, sig, secret)).toBe(true);
-  });
-
-  it('accepts the digest with or without the sha256= prefix', () => {
-    const sig = signWebhookPayload(payload, secret);
-    const bare = sig.slice('sha256='.length);
-    expect(verifyWebhookSignature(payload, bare, secret)).toBe(true);
-  });
-
-  it('rejects a tampered body', () => {
-    const sig = signWebhookPayload(payload, secret);
-    expect(verifyWebhookSignature(payload + 'X', sig, secret)).toBe(false);
-  });
-
-  it('rejects a tampered signature', () => {
-    const sig = signWebhookPayload(payload, secret);
-    const flipped = `sha256=${'0'.repeat(64)}`;
-    expect(verifyWebhookSignature(payload, flipped, secret)).toBe(false);
-    const tweaked = sig.slice(0, -1) + (sig.endsWith('a') ? 'b' : 'a');
-    expect(verifyWebhookSignature(payload, tweaked, secret)).toBe(false);
-  });
-
-  it('rejects when the secret is wrong', () => {
-    const sig = signWebhookPayload(payload, secret);
-    expect(verifyWebhookSignature(payload, sig, 'other-secret')).toBe(false);
-  });
-
-  it('rejects empty / missing inputs', () => {
-    const sig = signWebhookPayload(payload, secret);
-    expect(verifyWebhookSignature(payload, undefined, secret)).toBe(false);
-    expect(verifyWebhookSignature(payload, null, secret)).toBe(false);
-    expect(verifyWebhookSignature(payload, '', secret)).toBe(false);
-    expect(verifyWebhookSignature(payload, sig, '')).toBe(false);
-  });
-
-  it('rejects non-hex signature strings without throwing', () => {
-    expect(verifyWebhookSignature(payload, 'sha256=not-hex-content', secret)).toBe(false);
-    expect(verifyWebhookSignature(payload, 'sha256=zzzz', secret)).toBe(false);
-  });
-
-  it('rejects digests of the wrong length without throwing', () => {
-    expect(verifyWebhookSignature(payload, 'sha256=abcd', secret)).toBe(false);
-    expect(verifyWebhookSignature(payload, `sha256=${'a'.repeat(63)}`, secret)).toBe(false);
-    expect(verifyWebhookSignature(payload, `sha256=${'a'.repeat(65)}`, secret)).toBe(false);
-  });
-
-  it('treats the digest case-insensitively', () => {
-    const sig = signWebhookPayload(payload, secret);
-    const upper = `sha256=${sig.slice('sha256='.length).toUpperCase()}`;
-    expect(verifyWebhookSignature(payload, upper, secret)).toBe(true);
-  });
-
-  it('handles Uint8Array bodies', () => {
-    const body = new TextEncoder().encode(payload);
-    const sig = signWebhookPayload(body, secret);
-    expect(verifyWebhookSignature(body, sig, secret)).toBe(true);
-    expect(signWebhookPayload(body, secret)).toBe(signWebhookPayload(payload, secret));
-  });
-});

package/src/utils/webhook-signature.ts

@@ -1,74 +0,0 @@
-/**
- * Helpers for signing and verifying inbound / outbound webhook payloads.
- *
- * Both sides use HMAC-SHA256 with a `sha256=<lowercase-hex>` envelope —
- * the same shape produced by `WebhookEventTransport.signPayload`, matching
- * common third-party providers (Stripe, GitHub, etc.).
- *
- * Audit: 2026-04-27 finding L2 — without a shipped verifier, consumers
- * receiving inbound webhooks tend to roll their own comparisons that are
- * vulnerable to timing attacks.
- */
-
-import { createHmac, timingSafeEqual } from 'node:crypto';
-
-/**
- * Compute the canonical `X-Webhook-Signature` value for a request body.
- *
- * Returns a string of the form `sha256=<lowercase-hex>`.
- */
-export function signWebhookPayload(body: string | Uint8Array, secret: string): string {
-  const hmac = createHmac('sha256', secret);
-  hmac.update(body);
-  return `sha256=${hmac.digest('hex')}`;
-}
-
-/**
- * Constant-time verification of an inbound webhook signature.
- *
- * @param body      The raw request body that was signed.
- * @param signature The header value sent by the producer (e.g. `sha256=…`).
- * @param secret    The shared HMAC secret.
- * @returns `true` only if the computed digest matches the supplied signature.
- *
- * Properties:
- *  - Accepts an optional `sha256=` prefix on the signature, but does not
- *    require it (mirrors common third-party header conventions).
- *  - Uses `timingSafeEqual` so an attacker cannot probe digit-by-digit.
- *  - Returns `false` for missing/empty values, non-hex input, and length
- *    mismatches without throwing.
- *  - Returns `false` if the secret is empty — an empty secret is almost
- *    always a misconfiguration we do not want to silently accept.
- */
-export function verifyWebhookSignature(
-  body: string | Uint8Array,
-  signature: string | undefined | null,
-  secret: string,
-): boolean {
-  if (!secret || typeof signature !== 'string' || signature.length === 0) {
-    return false;
-  }
-
-  const provided = signature.startsWith('sha256=')
-    ? signature.slice('sha256='.length)
-    : signature;
-
-  // Hex-encoded SHA-256 is always exactly 64 characters; reject anything
-  // else so we don't mistake other algorithms or junk strings for ours.
-  if (!/^[0-9a-f]+$/i.test(provided)) {
-    return false;
-  }
-
-  const expectedHex = signWebhookPayload(body, secret).slice('sha256='.length);
-
-  // Length mismatch — `timingSafeEqual` would throw; exposing the digest
-  // length is fine since it's a public property of SHA-256.
-  if (provided.length !== expectedHex.length) {
-    return false;
-  }
-
-  const a = Buffer.from(provided.toLowerCase(), 'hex');
-  const b = Buffer.from(expectedHex, 'hex');
-  if (a.length !== b.length || a.length === 0) return false;
-  return timingSafeEqual(a, b);
-}

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "lib": ["ES2022", "DOM"],
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "declaration": true,
-    "declarationMap": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "noEmit": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts"]
-}

package/tsup.config.ts

@@ -1,14 +0,0 @@
-import { defineConfig } from 'tsup';
-
-export default defineConfig({
-  entry: {
-    index: 'src/index.ts',
-    'storage/index': 'src/storage/index.ts',
-    'events/index': 'src/events/index.ts',
-    'scheduler/index': 'src/scheduler/index.ts',
-  },
-  format: ['esm'],
-  dts: true,
-  clean: true,
-  sourcemap: true,
-});

package/vitest.config.ts

@@ -1,9 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-    include: ['src/**/*.test.ts'],
-  },
-});