@multiplier-labs/stepflow 0.3.1 → 0.3.4

package/src/utils/logger.test.ts

@@ -1,77 +1,71 @@
-import { describe, it, expect, vi } from "vitest";
-import { ConsoleLogger, SilentLogger, createScopedLogger } from "./logger";
+import { describe, it, expect, vi } from 'vitest';
+import { ConsoleLogger, SilentLogger, createScopedLogger } from './logger';
 
-describe("ConsoleLogger", () => {
-  it("should log debug messages with prefix", () => {
-    const spy = vi.spyOn(console, "debug").mockImplementation(() => {});
-    const logger = new ConsoleLogger("[test]", "debug");
+describe('ConsoleLogger', () => {
+  it('should log debug messages with prefix', () => {
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const logger = new ConsoleLogger('[test]', 'debug');
 
-    logger.debug("hello", { extra: true });
+    logger.debug('hello', { extra: true });
 
-    expect(spy).toHaveBeenCalledWith("[test] [DEBUG]", "hello", {
-      extra: true,
-    });
+    expect(spy).toHaveBeenCalledWith('[test] [DEBUG]', 'hello', { extra: true });
     spy.mockRestore();
   });
 
-  it("should log info messages with prefix", () => {
-    const spy = vi.spyOn(console, "info").mockImplementation(() => {});
-    const logger = new ConsoleLogger("[test]");
+  it('should log info messages with prefix', () => {
+    const spy = vi.spyOn(console, 'info').mockImplementation(() => {});
+    const logger = new ConsoleLogger('[test]');
 
-    logger.info("info msg");
+    logger.info('info msg');
 
-    expect(spy).toHaveBeenCalledWith("[test] [INFO]", "info msg");
+    expect(spy).toHaveBeenCalledWith('[test] [INFO]', 'info msg');
     spy.mockRestore();
   });
 
-  it("should log warn messages with prefix", () => {
-    const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const logger = new ConsoleLogger("[test]");
+  it('should log warn messages with prefix', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const logger = new ConsoleLogger('[test]');
 
-    logger.warn("warning");
+    logger.warn('warning');
 
-    expect(spy).toHaveBeenCalledWith("[test] [WARN]", "warning");
+    expect(spy).toHaveBeenCalledWith('[test] [WARN]', 'warning');
     spy.mockRestore();
   });
 
-  it("should log error messages with prefix", () => {
-    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
-    const logger = new ConsoleLogger("[test]");
+  it('should log error messages with prefix', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const logger = new ConsoleLogger('[test]');
 
-    logger.error("error msg", new Error("boom"));
+    logger.error('error msg', new Error('boom'));
 
-    expect(spy).toHaveBeenCalledWith(
-      "[test] [ERROR]",
-      "error msg",
-      expect.any(Error),
-    );
+    expect(spy).toHaveBeenCalledWith('[test] [ERROR]', 'error msg', expect.any(Error));
     spy.mockRestore();
   });
 
-  it("should use default prefix when none provided", () => {
-    const spy = vi.spyOn(console, "info").mockImplementation(() => {});
+  it('should use default prefix when none provided', () => {
+    const spy = vi.spyOn(console, 'info').mockImplementation(() => {});
     const logger = new ConsoleLogger();
 
-    logger.info("test");
+    logger.info('test');
 
-    expect(spy).toHaveBeenCalledWith("[workflow] [INFO]", "test");
+    expect(spy).toHaveBeenCalledWith('[workflow] [INFO]', 'test');
     spy.mockRestore();
   });
 });
 
-describe("SilentLogger", () => {
-  it("should not throw on any log level", () => {
+describe('SilentLogger', () => {
+  it('should not throw on any log level', () => {
     const logger = new SilentLogger();
 
-    expect(() => logger.debug("test")).not.toThrow();
-    expect(() => logger.info("test")).not.toThrow();
-    expect(() => logger.warn("test")).not.toThrow();
-    expect(() => logger.error("test")).not.toThrow();
+    expect(() => logger.debug('test')).not.toThrow();
+    expect(() => logger.info('test')).not.toThrow();
+    expect(() => logger.warn('test')).not.toThrow();
+    expect(() => logger.error('test')).not.toThrow();
   });
 });
 
-describe("createScopedLogger", () => {
-  it("should prefix messages with run ID", () => {
+describe('createScopedLogger', () => {
+  it('should prefix messages with run ID', () => {
     const calls: string[] = [];
     const baseLogger = {
       debug: (msg: string) => calls.push(`debug:${msg}`),
@@ -80,22 +74,22 @@ describe("createScopedLogger", () => {
       error: (msg: string) => calls.push(`error:${msg}`),
     };
 
-    const scoped = createScopedLogger(baseLogger, "run-123");
+    const scoped = createScopedLogger(baseLogger, 'run-123');
 
-    scoped.debug("d");
-    scoped.info("i");
-    scoped.warn("w");
-    scoped.error("e");
+    scoped.debug('d');
+    scoped.info('i');
+    scoped.warn('w');
+    scoped.error('e');
 
     expect(calls).toEqual([
-      "debug:[run:run-123] d",
-      "info:[run:run-123] i",
-      "warn:[run:run-123] w",
-      "error:[run:run-123] e",
+      'debug:[run:run-123] d',
+      'info:[run:run-123] i',
+      'warn:[run:run-123] w',
+      'error:[run:run-123] e',
     ]);
   });
 
-  it("should include step key when provided", () => {
+  it('should include step key when provided', () => {
     const calls: string[] = [];
     const baseLogger = {
       debug: (msg: string) => calls.push(msg),
@@ -104,13 +98,13 @@ describe("createScopedLogger", () => {
       error: (msg: string) => calls.push(msg),
     };
 
-    const scoped = createScopedLogger(baseLogger, "run-1", "step-a");
-    scoped.info("hello");
+    const scoped = createScopedLogger(baseLogger, 'run-1', 'step-a');
+    scoped.info('hello');
 
-    expect(calls[0]).toBe("[run:run-1][step:step-a] hello");
+    expect(calls[0]).toBe('[run:run-1][step:step-a] hello');
   });
 
-  it("should forward extra arguments", () => {
+  it('should forward extra arguments', () => {
     const captured: unknown[][] = [];
     const baseLogger = {
       debug: (...args: unknown[]) => captured.push(args),
@@ -119,9 +113,9 @@ describe("createScopedLogger", () => {
       error: (...args: unknown[]) => captured.push(args),
     };
 
-    const scoped = createScopedLogger(baseLogger, "r1");
-    scoped.info("msg", { data: 1 }, 42);
+    const scoped = createScopedLogger(baseLogger, 'r1');
+    scoped.info('msg', { data: 1 }, 42);
 
-    expect(captured[0]).toEqual(["[run:r1] msg", { data: 1 }, 42]);
+    expect(captured[0]).toEqual(['[run:r1] msg', { data: 1 }, 42]);
   });
 });

package/src/utils/logger.ts

@@ -2,10 +2,10 @@
  * Logger utilities for the workflow engine.
  */
 
-import type { Logger, WorkflowError } from "../core/types";
+import type { Logger, WorkflowError } from '../core/types';
 
 /** Log level for ConsoleLogger. Levels are ordered: debug < info < warn < error. */
-export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 
 const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
   debug: 0,
@@ -23,7 +23,7 @@ export class ConsoleLogger implements Logger {
   private prefix: string;
   private minLevel: number;
 
-  constructor(prefix = "[workflow]", level: LogLevel = "info") {
+  constructor(prefix = '[workflow]', level: LogLevel = 'info') {
     this.prefix = prefix;
     this.minLevel = LOG_LEVEL_PRIORITY[level];
   }
@@ -79,7 +79,7 @@ export function sanitizeErrorForStorage(error: WorkflowError): WorkflowError {
 export function createScopedLogger(
   logger: Logger,
   runId: string,
-  stepKey?: string,
+  stepKey?: string
 ): Logger {
   const prefix = stepKey ? `[run:${runId}][step:${stepKey}]` : `[run:${runId}]`;
 

package/src/utils/pinned-fetch.test.ts

@@ -0,0 +1,84 @@
+/**
+ * pinnedFetch is the linchpin of the M1 (DNS rebinding TOCTOU) fix: by
+ * passing a `lookup` function that returns a caller-supplied IP, the TCP
+ * connection cannot be re-resolved to a different address. We test it
+ * against a real loopback HTTP server because ESM forbids spying on the
+ * `http` module's exports and we want to exercise the real request path
+ * end-to-end.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import * as http from 'node:http';
+import { pinnedFetch } from './pinned-fetch';
+
+describe('pinnedFetch', () => {
+  let server: http.Server;
+  let port: number;
+  let lastRequest: { hostHeader?: string; method?: string; path?: string; body: string } = {
+    body: '',
+  };
+
+  beforeAll(async () => {
+    server = http.createServer((req, res) => {
+      const chunks: Buffer[] = [];
+      req.on('data', (c: Buffer) => chunks.push(c));
+      req.on('end', () => {
+        lastRequest = {
+          hostHeader: req.headers.host,
+          method: req.method,
+          path: req.url,
+          body: Buffer.concat(chunks).toString('utf8'),
+        };
+        res.writeHead(204, 'No Content');
+        res.end();
+      });
+    });
+    await new Promise<void>((resolve) => {
+      server.listen(0, '127.0.0.1', () => resolve());
+    });
+    port = (server.address() as { port: number }).port;
+  });
+
+  afterAll(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  });
+
+  it('connects to the pinned IP even when the URL hostname is unrelated', async () => {
+    // The URL hostname is one that would never resolve to 127.0.0.1 via DNS.
+    // pinnedFetch must ignore the URL's would-be DNS answer and connect to
+    // the pinned address. If pinning is broken, the connection will fail
+    // or hit a different host.
+    const response = await pinnedFetch(
+      `http://rebind.invalid:${port}/hook`,
+      { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{"ok":1}' },
+      '127.0.0.1',
+      4,
+    );
+
+    expect(response.ok).toBe(true);
+    expect(response.status).toBe(204);
+    expect(lastRequest.method).toBe('POST');
+    expect(lastRequest.path).toBe('/hook');
+    expect(lastRequest.body).toBe('{"ok":1}');
+  });
+
+  it('preserves the original hostname in the Host header (vhost / TLS SNI)', async () => {
+    await pinnedFetch(
+      `http://example.test:${port}/`,
+      { method: 'GET' },
+      '127.0.0.1',
+      4,
+    );
+
+    // The Host header must reflect the URL hostname, not the pinned IP, so
+    // that virtual-host routing and TLS certificate validation work.
+    expect(lastRequest.hostHeader).toContain('example.test');
+  });
+
+  it('rejects when the connection cannot be established', async () => {
+    // Pin to a non-listening port on loopback.
+    await expect(
+      pinnedFetch(`http://example.test:1/`, { method: 'GET' }, '127.0.0.1', 4),
+    ).rejects.toThrow();
+  });
+});

package/src/utils/pinned-fetch.ts

@@ -0,0 +1,118 @@
+/**
+ * DNS-pinned fetch helper.
+ *
+ * Performs an HTTP(S) request that connects to a caller-supplied IP address
+ * instead of re-resolving the URL hostname. Used by the webhook transport to
+ * close the SSRF DNS-rebinding TOCTOU window: the hostname is resolved
+ * exactly once (by the caller), the resolved IP is validated, and the
+ * resolved IP is then pinned for the connection so the request cannot be
+ * rerouted by a hostile DNS server.
+ *
+ * The original hostname is preserved for TLS SNI / certificate verification
+ * and for the HTTP `Host` header.
+ *
+ * Audit: 2026-04-27 finding M1 — DNS TOCTOU between SSRF validation and
+ * connect.
+ */
+
+import * as http from 'node:http';
+import * as https from 'node:https';
+import type { LookupAddress, LookupOptions } from 'node:dns';
+
+/** Minimal fetch-compatible Response surface used by the webhook transport. */
+export interface PinnedFetchResponse {
+  ok: boolean;
+  status: number;
+  statusText: string;
+}
+
+/** Subset of `RequestInit` accepted by `pinnedFetch`. */
+export interface PinnedFetchInit {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+  signal?: AbortSignal;
+}
+
+/**
+ * Make an HTTP(S) request that connects to `address` instead of resolving
+ * `url`'s hostname. Returns a minimal `Response`-shaped object compatible
+ * with the webhook transport's status / ok checks.
+ *
+ * @throws Error on transport failure or abort
+ */
+export function pinnedFetch(
+  url: string,
+  init: PinnedFetchInit,
+  address: string,
+  family: 4 | 6 = 4,
+): Promise<PinnedFetchResponse> {
+  const parsed = new URL(url);
+  const isHttps = parsed.protocol === 'https:';
+  const lib = isHttps ? https : http;
+  const port = parsed.port ? Number(parsed.port) : isHttps ? 443 : 80;
+
+  // `lookup` is called by the agent's socket-create path. By returning the
+  // pre-validated address here we guarantee the TCP connection target is the
+  // IP whose safety the caller already verified. Node may invoke this with
+  // `{ all: true }` (expects an array result) or single-address mode
+  // (expects positional address/family) — handle both for cross-version safety.
+  const lookup = (
+    _hostname: string,
+    options: LookupOptions,
+    cb: (err: NodeJS.ErrnoException | null, addr: string | LookupAddress[], fam?: number) => void,
+  ): void => {
+    if (options && options.all === true) {
+      cb(null, [{ address, family }]);
+    } else {
+      cb(null, address, family);
+    }
+  };
+
+  return new Promise<PinnedFetchResponse>((resolve, reject) => {
+    const req = lib.request(
+      {
+        hostname: parsed.hostname,
+        port,
+        path: `${parsed.pathname || '/'}${parsed.search}`,
+        method: init.method ?? 'GET',
+        headers: init.headers,
+        lookup,
+        servername: parsed.hostname,
+      },
+      (res) => {
+        // Drain the body — we only inspect status, but leaving the socket
+        // half-read would leak it.
+        res.resume();
+        res.on('end', () => {
+          const status = res.statusCode ?? 0;
+          resolve({
+            ok: status >= 200 && status < 300,
+            status,
+            statusText: res.statusMessage ?? '',
+          });
+        });
+        res.on('error', reject);
+      },
+    );
+
+    req.on('error', reject);
+
+    if (init.signal) {
+      if (init.signal.aborted) {
+        req.destroy(new Error('Request aborted'));
+      } else {
+        init.signal.addEventListener(
+          'abort',
+          () => req.destroy(new Error('Request aborted')),
+          { once: true },
+        );
+      }
+    }
+
+    if (init.body !== undefined) {
+      req.write(init.body);
+    }
+    req.end();
+  });
+}

package/src/utils/postgres-deps.ts

@@ -37,21 +37,21 @@ export async function loadPostgresDeps(): Promise<PostgresDeps> {
     let pgModule: any;
 
     try {
-      const kyselyMod = await import("kysely");
+      const kyselyMod = await import('kysely');
       Kysely = kyselyMod.Kysely;
       PostgresDialect = kyselyMod.PostgresDialect;
       sql = kyselyMod.sql;
     } catch {
       throw new Error(
-        'PostgreSQL support requires the "kysely" package. Install it with: npm install kysely',
+        'PostgreSQL support requires the "kysely" package. Install it with: npm install kysely'
       );
     }
     try {
-      const pg = await import("pg");
+      const pg = await import('pg');
       pgModule = pg.default ?? pg;
     } catch {
       throw new Error(
-        'PostgreSQL support requires the "pg" package. Install it with: npm install pg',
+        'PostgreSQL support requires the "pg" package. Install it with: npm install pg'
       );
     }
 
@@ -61,3 +61,19 @@ export async function loadPostgresDeps(): Promise<PostgresDeps> {
 
   return loadingPromise;
 }
+
+/**
+ * Synchronously access the cached PostgreSQL deps. Throws if
+ * `loadPostgresDeps()` has not yet completed. Used by code paths that run
+ * after `PostgresStorageAdapter.initialize()` and need direct access to
+ * `sql` / `Kysely` without re-awaiting.
+ */
+export function requirePostgresDeps(): PostgresDeps {
+  if (!cached) {
+    throw new Error(
+      'PostgreSQL dependencies have not been loaded yet. ' +
+      'Call loadPostgresDeps() (or PostgresStorageAdapter.initialize()) first.'
+    );
+  }
+  return cached;
+}