fix: check target run capabilities before encrypting hook payloads

.changeset/fix-hook-resume-encryption-compat.md

@@ -0,0 +1,5 @@
+---
+"@workflow/core": patch
+---
+
+Fix `resumeHook()`/`resumeWebhook()` failing on workflow runs from pre-encryption deployments by checking the target run's `workflowCoreVersion` capabilities before encoding the payload

packages/core/package.json

@@ -93,12 +93,14 @@
     "ms": "2.1.3",
     "nanoid": "5.1.6",
     "seedrandom": "3.0.5",
+    "semver": "catalog:",
     "ulid": "catalog:",
     "zod": "catalog:"
   },
   "devDependencies": {
     "@opentelemetry/api": "1.9.0",
     "@types/debug": "4.1.12",
+    "@types/semver": "7.7.1",
     "@types/node": "catalog:",
     "@types/seedrandom": "3.0.8",
     "@workflow/tsconfig": "workspace:*",

packages/core/src/capabilities.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { getRunCapabilities } from './capabilities.js';
+import { SerializationFormat } from './serialization.js';
+
+describe('getRunCapabilities', () => {
+  describe('undefined version (very old runs)', () => {
+    it('only supports baseline formats', () => {
+      const { supportedFormats } = getRunCapabilities(undefined);
+      expect(supportedFormats.has(SerializationFormat.DEVALUE_V1)).toBe(true);
+      expect(supportedFormats.has(SerializationFormat.ENCRYPTED)).toBe(false);
+    });
+  });
+
+  describe('pre-encryption versions', () => {
+    it.each([
+      '4.1.0-beta.63',
+      '4.0.1-beta.27',
+      '3.0.0',
+    ])('%s does not support encryption', (version) => {
+      const { supportedFormats } = getRunCapabilities(version);
+      expect(supportedFormats.has(SerializationFormat.DEVALUE_V1)).toBe(true);
+      expect(supportedFormats.has(SerializationFormat.ENCRYPTED)).toBe(false);
+    });
+  });
+
+  describe('encryption-capable versions', () => {
+    it('supports encryption at the exact cutoff version', () => {
+      const { supportedFormats } = getRunCapabilities('4.2.0-beta.64');
+      expect(supportedFormats.has(SerializationFormat.DEVALUE_V1)).toBe(true);
+      expect(supportedFormats.has(SerializationFormat.ENCRYPTED)).toBe(true);
+    });
+
+    it.each([
+      '4.2.0-beta.74',
+      '4.2.0',
+      '5.0.0',
+    ])('%s supports encryption', (version) => {
+      const { supportedFormats } = getRunCapabilities(version);
+      expect(supportedFormats.has(SerializationFormat.ENCRYPTED)).toBe(true);
+    });
+  });
+});

packages/core/src/capabilities.ts

@@ -0,0 +1,84 @@
+/**
+ * Capabilities table for workflow runs based on their `@workflow/core` version.
+ *
+ * When resuming a hook or webhook, the payload must be encoded in a format
+ * that the *target* workflow run's deployment can decode. This module provides
+ * a way to look up what serialization formats a given `@workflow/core` version
+ * supports, so that newer deployments can avoid encoding payloads in formats
+ * that older deployments don't understand (e.g., the `encr` encryption format).
+ *
+ * ## Adding a new format
+ *
+ * When a new serialization format is introduced:
+ * 1. Add the format constant to `SerializationFormat` in `serialization.ts`
+ * 2. Add an entry to `FORMAT_VERSION_TABLE` below with the minimum
+ *    `@workflow/core` version that supports it
+ * 3. The `getRunCapabilities()` function will automatically include it
+ */
+
+import semver from 'semver';
+import {
+  SerializationFormat,
+  type SerializationFormatType,
+} from './serialization.js';
+
+/**
+ * Capabilities of a workflow run based on its `@workflow/core` version.
+ */
+export interface RunCapabilities {
+  /**
+   * The set of serialization format prefixes that the target run can decode.
+   * Use `supportedFormats.has(SerializationFormat.ENCRYPTED)` to check
+   * if encryption is supported, etc.
+   */
+  supportedFormats: ReadonlySet<SerializationFormatType>;
+}
+
+/**
+ * Maps serialization format identifiers to the minimum `@workflow/core`
+ * version that introduced support for them. Formats not listed here are
+ * assumed to be supported by all specVersion 2 runs (e.g., `devl`).
+ */
+const FORMAT_VERSION_TABLE: ReadonlyArray<{
+  format: SerializationFormatType;
+  minVersion: string;
+}> = [
+  { format: SerializationFormat.ENCRYPTED, minVersion: '4.2.0-beta.64' },
+  // Future entries:
+  // { format: SerializationFormat.CBOR, minVersion: '5.x.y' },
+  // { format: SerializationFormat.ENCRYPTED_V2, minVersion: '5.x.y' },
+];
+
+/**
+ * The set of formats supported by all specVersion 2 runs, regardless of
+ * `@workflow/core` version. These are the baseline formats that were present
+ * from the start of the specVersion 2 protocol.
+ */
+const BASELINE_FORMATS: ReadonlySet<SerializationFormatType> = new Set([
+  SerializationFormat.DEVALUE_V1,
+]);
+
+/**
+ * Look up what serialization capabilities a workflow run supports based on
+ * its `@workflow/core` version string (from `executionContext.workflowCoreVersion`).
+ *
+ * When the version is `undefined` (e.g. very old runs that predate the field),
+ * we assume the most conservative capabilities (baseline formats only).
+ */
+export function getRunCapabilities(
+  workflowCoreVersion: string | undefined
+): RunCapabilities {
+  if (!workflowCoreVersion) {
+    return { supportedFormats: BASELINE_FORMATS };
+  }
+
+  const formats = new Set<SerializationFormatType>(BASELINE_FORMATS);
+
+  for (const { format, minVersion } of FORMAT_VERSION_TABLE) {
+    if (semver.gte(workflowCoreVersion, minVersion)) {
+      formats.add(format);
+    }
+  }
+
+  return { supportedFormats: formats };
+}

packages/core/src/runtime/resume-hook.ts

@@ -11,10 +11,12 @@ import {
   type WorkflowInvokePayload,
   type WorkflowRun,
 } from '@workflow/world';
+import { getRunCapabilities } from '../capabilities.js';
 import { type CryptoKey, importKey } from '../encryption.js';
 import {
   dehydrateStepReturnValue,
   hydrateStepArguments,
+  SerializationFormat,
 } from '../serialization.js';
 import { WEBHOOK_RESPONSE_WRITABLE } from '../symbols.js';
 import * as Attribute from '../telemetry/semantic-conventions.js';
@@ -123,6 +125,17 @@ export async function resumeHook<T = any>(
           ...Attribute.WorkflowRunId(hook.runId),
         });
 
+        // Check the target run's capabilities to ensure we encode the
+        // payload in a format the run's deployment can decode. For example,
+        // runs created before encryption support was added cannot decode
+        // the 'encr' serialization format.
+        const { supportedFormats } = getRunCapabilities(
+          workflowRun.executionContext?.workflowCoreVersion
+        );
+        if (!supportedFormats.has(SerializationFormat.ENCRYPTED)) {
+          encryptionKey = undefined;
+        }
+
         // Dehydrate the payload for storage
         const ops: Promise<any>[] = [];
         const v1Compat = isLegacySpecVersion(hook.specVersion);

packages/next/package.json

@@ -37,7 +37,7 @@
     "@workflow/builders": "workspace:*",
     "@workflow/core": "workspace:*",
     "@workflow/swc-plugin": "workspace:*",
-    "semver": "7.7.4",
+    "semver": "catalog:",
     "watchpack": "2.5.1"
   },
   "devDependencies": {

pnpm-workspace.yaml

@@ -16,6 +16,7 @@ catalog:
   ai: 6.0.116
   esbuild: ^0.27.3
   nitro: 3.0.1-alpha.1
+  semver: 7.7.4
   typescript: ^5.9.3
   ulid: ~3.0.1
   undici: 7.22.0