@multiplier-labs/stepflow 0.3.3 → 0.3.4

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

@@ -0,0 +1,166 @@
+/**
+ * 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

@@ -0,0 +1,107 @@
+/**
+ * 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

@@ -0,0 +1,111 @@
+/**
+ * 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

@@ -0,0 +1,74 @@
+/**
+ * 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);
+}