Encryption: derive unique key per operation for key binding

This PR tweaks the way workflow data is encrypted by ensuring that each operation uses a unique encryption key, achieving key binding.

Currently, the encryption serialization format `encr` uses a different key for each workflow run ID. However, the same key is used for all encryption operations performed within the same workflow run, including workflow arguments & return values, step arguments & return values, and each frame in the serialized stream.

The downsides of reusing the same key are:

1. While there's key binding for each specific workflow run (so, attackers cannot swap data from "workflow run 1" with "workflow run 2"), there's no binding within the same run, so for example the input of step 1 and 2 could be swapped undetected.
2. Encryption uses AES-GCM with a random nonce of "just" 96 bits. Due to the nature of GCM, re-using the same (key, nonce) pair has catastrophic effects (causes the plaintext key to be leaked). While the risk is very small (it's considered safe to re-use the same key up to ~4 billion times with random nonces), a different key removes the likelihood of nonce reuse entirely.

Signed-off-by: ItalyPaleAle <43508+ItalyPaleAle@users.noreply.github.com>

Author: ItalyPaleAle

.changeset/early-dolls-fix.md

@@ -0,0 +1,7 @@
+---
+"@workflow/core": patch
+"@workflow/cli": patch
+"@workflow/web-shared": patch
+---
+
+Add `enc2` encryption for serialized workflow data, which includes key binding for each operation, also reducing the likelihood of nonce reuse for long-running workflows.

packages/cli/src/lib/inspect/hydration.ts

@@ -237,8 +237,8 @@ async function maybeDecryptFields<
 
   try {
     const rawKey = await resolver(runId);
-    const { importKey } = await import('@workflow/core/encryption');
-    const k = rawKey ? await importKey(rawKey) : undefined;
+    const { importEncryptionKeys } = await import('@workflow/core/encryption');
+    const k = rawKey ? await importEncryptionKeys(rawKey) : undefined;
 
     // Decrypt input/output/error fields (WorkflowRun, Step)
     result.input = await maybeDecrypt(result.input, k);

packages/cli/src/lib/inspect/output.ts

@@ -1,4 +1,4 @@
-import { importKey } from '@workflow/core/encryption';
+import { importEncryptionKeys } from '@workflow/core/encryption';
 import {
   type EncryptionKeyParam,
   getDeserializeStream,
@@ -859,7 +859,7 @@ export const showStream = async (
     encryptionKey = (async () => {
       const run = await world.runs.get(opts.runId!);
       const rawKey = await world.getEncryptionKeyForRun?.(run);
-      return rawKey ? await importKey(rawKey) : undefined;
+      return rawKey ? await importEncryptionKeys(rawKey) : undefined;
     })();
   } else if (opts.decrypt && !opts.runId) {
     logger.warn(

packages/core/src/encryption.ts

@@ -1,19 +1,18 @@
 /**
- * Browser-compatible AES-256-GCM encryption module.
+ * Browser-compatible encryption helpers.
  *
  * Uses the Web Crypto API (`globalThis.crypto.subtle`) which works in
  * both modern browsers and Node.js 20+. This module is intentionally
  * free of Node.js-specific imports so it can be bundled for the browser.
  *
  * The World interface (`getEncryptionKeyForRun`) returns a raw 32-byte
- * AES-256 key. Callers should use `importKey()` once to convert it to a
- * `CryptoKey`, then pass that to `encrypt()`/`decrypt()` for all
- * operations within the same run. This avoids repeated `importKey()`
- * calls on every encrypt/decrypt invocation.
+ * per-run key. Core imports that key twice:
+ * - as `AES-GCM` for legacy `encr` payloads
+ * - as `HKDF` for derived-key `enc2` payloads
  *
- * Wire format: `[nonce (12 bytes)][ciphertext + auth tag]`
- * The `encr` format prefix is NOT part of this module — it's added/stripped
- * by the serialization layer in `maybeEncrypt`/`maybeDecrypt`.
+ * Wire format for AES-GCM blobs: `[nonce (12 bytes)][ciphertext + auth tag]`
+ * The `encr` / `enc2` serialization prefixes are NOT part of this module —
+ * they're added/stripped by the serialization layer.
  */
 
 // CryptoKey is a global type in browsers and Node.js 20+, but TypeScript's
@@ -24,42 +23,258 @@ export type CryptoKey = import('node:crypto').webcrypto.CryptoKey;
 const NONCE_LENGTH = 12;
 const TAG_LENGTH = 128; // bits
 const KEY_LENGTH = 32; // bytes (AES-256)
+const HKDF_SALT = new Uint8Array(KEY_LENGTH);
+const V2_HEADER_LENGTH_SIZE = 4;
+const MAX_V2_HEADER_LENGTH = 16 * 1024;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export interface EncryptionKeyBundle {
+  legacyKey: CryptoKey;
+  derivationKey: CryptoKey;
+}
+
+export type EncryptionKeyLike = CryptoKey | EncryptionKeyBundle;
+
+export interface EncryptedV2Header {
+  purpose: string;
+  runId: string;
+  activityId?: string;
+  counter?: number;
+}
+
+function validateRawKey(raw: Uint8Array): void {
+  if (raw.byteLength !== KEY_LENGTH) {
+    throw new Error(
+      `Encryption key must be exactly ${KEY_LENGTH} bytes, got ${raw.byteLength}`
+    );
+  }
+}
+
+export function isEncryptionKeyBundle(
+  key: EncryptionKeyLike | undefined
+): key is EncryptionKeyBundle {
+  return (
+    typeof key === 'object' &&
+    key !== null &&
+    'legacyKey' in key &&
+    'derivationKey' in key
+  );
+}
+
+export function getLegacyKey(
+  key: EncryptionKeyLike | undefined
+): CryptoKey | undefined {
+  if (!key) return undefined;
+  return isEncryptionKeyBundle(key) ? key.legacyKey : key;
+}
+
+export function getDerivationKey(
+  key: EncryptionKeyLike | undefined
+): CryptoKey | undefined {
+  if (!isEncryptionKeyBundle(key)) return undefined;
+  return key.derivationKey;
+}
 
 /**
- * Import a raw AES-256 key as a `CryptoKey` for use with `encrypt()`/`decrypt()`.
+ * Import a raw AES-256 key as a legacy `AES-GCM` `CryptoKey`.
  *
- * Callers should call this once per run (after `getEncryptionKeyForRun()`)
- * and pass the resulting `CryptoKey` to all subsequent encrypt/decrypt calls.
+ * This is kept for backwards compatibility with callers that still
+ * explicitly work with the legacy `encr` path.
  *
  * @param raw - Raw 32-byte AES-256 key (from World.getEncryptionKeyForRun)
  * @returns CryptoKey ready for AES-GCM operations
  */
-export async function importKey(raw: Uint8Array) {
-  if (raw.byteLength !== KEY_LENGTH) {
-    throw new Error(
-      `Encryption key must be exactly ${KEY_LENGTH} bytes, got ${raw.byteLength}`
-    );
-  }
+export async function importLegacyKey(raw: Uint8Array) {
+  validateRawKey(raw);
   return globalThis.crypto.subtle.importKey('raw', raw, 'AES-GCM', false, [
     'encrypt',
     'decrypt',
   ]);
 }
 
+/**
+ * Import a raw per-run key as an `HKDF` base key for derived `enc2` keys.
+ *
+ * @param raw - Raw 32-byte per-run key
+ * @returns CryptoKey ready for HKDF deriveKey operations
+ */
+export async function importDerivationKey(raw: Uint8Array) {
+  validateRawKey(raw);
+  return globalThis.crypto.subtle.importKey('raw', raw, 'HKDF', false, [
+    'deriveKey',
+  ]);
+}
+
+/**
+ * Import a raw per-run key into the pair of keys needed by core.
+ */
+export async function importEncryptionKeys(
+  raw: Uint8Array
+): Promise<EncryptionKeyBundle> {
+  const [legacyKey, derivationKey] = await Promise.all([
+    importLegacyKey(raw),
+    importDerivationKey(raw),
+  ]);
+  return { legacyKey, derivationKey };
+}
+
+/**
+ * Derive an activity-specific AES-256-GCM key from the per-run HKDF key.
+ *
+ * The `info` bytes should encode the full activity context. For `enc2`
+ * payloads we reuse the exact serialized header bytes as both the HKDF
+ * `info` parameter and the AES-GCM AAD.
+ */
+export async function deriveActivityKey(
+  derivationKey: CryptoKey,
+  info: Uint8Array
+): Promise<CryptoKey> {
+  const derived = await globalThis.crypto.subtle.deriveKey(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: HKDF_SALT,
+      info,
+    },
+    derivationKey,
+    { name: 'AES-GCM', length: KEY_LENGTH * 8 },
+    false,
+    ['encrypt', 'decrypt']
+  );
+  return derived as CryptoKey;
+}
+
+function isValidEncryptedV2Header(value: unknown): value is EncryptedV2Header {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+
+  const header = value as Record<string, unknown>;
+  return (
+    typeof header.purpose === 'string' &&
+    header.purpose.length > 0 &&
+    typeof header.runId === 'string' &&
+    header.runId.length > 0 &&
+    (header.activityId === undefined ||
+      typeof header.activityId === 'string') &&
+    (header.counter === undefined ||
+      (typeof header.counter === 'number' &&
+        Number.isInteger(header.counter) &&
+        header.counter >= 0))
+  );
+}
+
+export function encodeEncryptedV2Header(header: EncryptedV2Header): Uint8Array {
+  if (!isValidEncryptedV2Header(header)) {
+    throw new Error('Invalid enc2 header');
+  }
+
+  const normalized: EncryptedV2Header = {
+    purpose: header.purpose,
+    runId: header.runId,
+  };
+  if (header.activityId !== undefined) {
+    normalized.activityId = header.activityId;
+  }
+  if (header.counter !== undefined) {
+    normalized.counter = header.counter;
+  }
+
+  return encoder.encode(JSON.stringify(normalized));
+}
+
+export function decodeEncryptedV2Header(
+  headerBytes: Uint8Array
+): EncryptedV2Header {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoder.decode(headerBytes));
+  } catch (error) {
+    throw new Error('Invalid enc2 header JSON', { cause: error });
+  }
+
+  if (!isValidEncryptedV2Header(parsed)) {
+    throw new Error('Invalid enc2 header fields');
+  }
+
+  return parsed;
+}
+
+/**
+ * Encode the inner `enc2` payload body:
+ * `[4-byte header length][header bytes][nonce + ciphertext + auth tag]`
+ */
+export function encodeEncryptedV2Body(
+  headerBytes: Uint8Array,
+  ciphertext: Uint8Array
+): Uint8Array {
+  const result = new Uint8Array(
+    V2_HEADER_LENGTH_SIZE + headerBytes.byteLength + ciphertext.byteLength
+  );
+  new DataView(result.buffer).setUint32(0, headerBytes.byteLength, false);
+  result.set(headerBytes, V2_HEADER_LENGTH_SIZE);
+  result.set(ciphertext, V2_HEADER_LENGTH_SIZE + headerBytes.byteLength);
+  return result;
+}
+
+export function decodeEncryptedV2Body(data: Uint8Array): {
+  headerBytes: Uint8Array;
+  ciphertext: Uint8Array;
+} {
+  if (data.byteLength < V2_HEADER_LENGTH_SIZE) {
+    throw new Error('enc2 payload too short to contain header length');
+  }
+
+  const headerLength = new DataView(
+    data.buffer,
+    data.byteOffset,
+    data.byteLength
+  ).getUint32(0, false);
+
+  if (headerLength === 0 || headerLength > MAX_V2_HEADER_LENGTH) {
+    throw new Error(`Invalid enc2 header length: ${headerLength}`);
+  }
+
+  const headerStart = V2_HEADER_LENGTH_SIZE;
+  const headerEnd = headerStart + headerLength;
+  if (data.byteLength < headerEnd) {
+    throw new Error('enc2 payload truncated before header completed');
+  }
+
+  const ciphertext = data.subarray(headerEnd);
+  if (ciphertext.byteLength === 0) {
+    throw new Error('enc2 payload missing ciphertext');
+  }
+
+  return {
+    headerBytes: data.subarray(headerStart, headerEnd),
+    ciphertext,
+  };
+}
+
 /**
  * Encrypt data using AES-256-GCM.
  *
- * @param key - CryptoKey from `importKey()`
+ * @param key - CryptoKey from `importLegacyKey()`
  * @param data - Plaintext to encrypt
+ * @param aad - Optional AES-GCM additional authenticated data
  * @returns `[nonce (12 bytes)][ciphertext + GCM auth tag]`
  */
 export async function encrypt(
   key: CryptoKey,
-  data: Uint8Array
+  data: Uint8Array,
+  aad?: Uint8Array
 ): Promise<Uint8Array> {
   const nonce = globalThis.crypto.getRandomValues(new Uint8Array(NONCE_LENGTH));
   const ciphertext = await globalThis.crypto.subtle.encrypt(
-    { name: 'AES-GCM', iv: nonce, tagLength: TAG_LENGTH },
+    {
+      name: 'AES-GCM',
+      iv: nonce,
+      tagLength: TAG_LENGTH,
+      ...(aad ? { additionalData: aad } : {}),
+    },
     key,
     data
   );
@@ -72,13 +287,15 @@ export async function encrypt(
 /**
  * Decrypt data using AES-256-GCM.
  *
- * @param key - CryptoKey from `importKey()`
+ * @param key - CryptoKey from `importLegacyKey()`
  * @param data - `[nonce (12 bytes)][ciphertext + GCM auth tag]`
+ * @param aad - Optional AES-GCM additional authenticated data
  * @returns Decrypted plaintext
  */
 export async function decrypt(
   key: CryptoKey,
-  data: Uint8Array
+  data: Uint8Array,
+  aad?: Uint8Array
 ): Promise<Uint8Array> {
   const minLength = NONCE_LENGTH + TAG_LENGTH / 8; // nonce + auth tag
   if (data.byteLength < minLength) {
@@ -89,7 +306,12 @@ export async function decrypt(
   const nonce = data.subarray(0, NONCE_LENGTH);
   const ciphertext = data.subarray(NONCE_LENGTH);
   const plaintext = await globalThis.crypto.subtle.decrypt(
-    { name: 'AES-GCM', iv: nonce, tagLength: TAG_LENGTH },
+    {
+      name: 'AES-GCM',
+      iv: nonce,
+      tagLength: TAG_LENGTH,
+      ...(aad ? { additionalData: aad } : {}),
+    },
     key,
     ciphertext
   );

packages/core/src/private.ts

@@ -2,7 +2,7 @@
  * Utils used by the bundler when transforming code
  */
 
-import type { CryptoKey } from './encryption.js';
+import type { EncryptionKeyLike } from './encryption.js';
 import type { EventsConsumer } from './events-consumer.js';
 import type { QueueItem } from './global.js';
 import type { Serializable } from './schemas.js';
@@ -114,7 +114,7 @@ export { __private_getClosureVars } from './step/get-closure-vars.js';
 
 export interface WorkflowOrchestratorContext {
   runId: string;
-  encryptionKey: CryptoKey | undefined;
+  encryptionKey: EncryptionKeyLike | undefined;
   globalThis: typeof globalThis;
   eventsConsumer: EventsConsumer;
   /**

packages/core/src/runtime.ts

@@ -13,7 +13,7 @@ import {
   WorkflowInvokePayloadSchema,
   type WorkflowRun,
 } from '@workflow/world';
-import { importKey } from './encryption.js';
+import { importEncryptionKeys } from './encryption.js';
 import { WorkflowSuspension } from './global.js';
 import { runtimeLogger } from './logger.js';
 import {
@@ -346,7 +346,7 @@ export function workflowEntrypoint(
                 const rawKey =
                   await world.getEncryptionKeyForRun?.(workflowRun);
                 const encryptionKey = rawKey
-                  ? await importKey(rawKey)
+                  ? await importEncryptionKeys(rawKey)
                   : undefined;
 
                 // --- User code execution ---