review: narrow the o11y decrypt key type and dedupe an import

- `hydrateDataWithKey` accepted `PayloadKey`, which includes `SealTarget`.
  A seal target holds only a public key, so it can open neither scheme —
  passing one compiled fine and then always failed at runtime. Added a
  `DecryptionKey` alias (`CryptoKey | RunPayloadKeys`) and narrowed the
  signature, so that misuse is now a compile error. A `@ts-expect-error`
  test pins the guarantee.
- `hydrateResourceIOAsync` dynamically imported
  `@workflow/core/serialization-format` twice. Destructure both bindings
  from the single existing import instead.

Author: TooTallNate

packages/core/src/serialization-format.test.ts

@@ -711,6 +711,37 @@ describe('encrypted data handling', () => {
       expect(result).toEqual(original);
     });
 
+    it('rejects a write-only seal target at the type level', async () => {
+      // A seal target holds only a public key, so it can open neither scheme.
+      // Accepting it here would compile into a guaranteed runtime failure, so
+      // the signature takes a read capability instead.
+      const { sealTo, deriveRunPayloadKeys } = await import(
+        './serialization/encryption.js'
+      );
+      const target = sealTo(new Uint8Array(32).fill(1));
+
+      // @ts-expect-error - SealTarget is write-only and must not be accepted
+      void hydrateDataWithKey(
+        makeSealedPayload(),
+        observabilityRevivers,
+        target
+      );
+
+      // Both read capabilities remain accepted: the run's full key bundle...
+      const keys = await deriveRunPayloadKeys(testKeyRaw);
+      await expect(
+        hydrateDataWithKey(makeSealedPayload(), observabilityRevivers, keys)
+      ).rejects.toThrow(); // fake ciphertext, but it type-checks and is attempted
+      // ...and a bare symmetric key (which simply cannot open sealed data).
+      await expect(
+        hydrateDataWithKey(
+          makeSealedPayload(),
+          observabilityRevivers,
+          await getTestKey()
+        )
+      ).resolves.toBeInstanceOf(Uint8Array);
+    });
+
     it('should pass sealed payloads through untouched even when a key is present', async () => {
       // A sealed payload is encrypted to the run's X25519 public key, so the
       // symmetric key this function receives cannot open it. Attempting an

packages/core/src/serialization-format.ts

@@ -23,16 +23,17 @@ import { parse, unflatten } from 'devalue';
  * `encryption.ts` and `sealed-box.ts` are all free of Node dependencies.
  */
 export {
+  type DecryptionKey,
   decrypt as decryptEnvelope,
   deriveRunPayloadKeys,
   encrypt as encryptEnvelope,
   isRunPayloadKeys,
   isSealTarget,
   type PayloadKey,
-  runPayloadKeys,
   type RunPayloadKeys,
-  sealTo,
+  runPayloadKeys,
   type SealTarget,
+  sealTo,
 } from './serialization/encryption.js';
 
 // ---------------------------------------------------------------------------
@@ -419,11 +420,13 @@ export function hydrateData(value: unknown, revivers: Revivers): unknown {
  * @param key - The run's key material. Pass `RunPayloadKeys` (from
  *   `deriveRunPayloadKeys`) to open both symmetric (`encr`) and sealed
  *   (`encp`) payloads; a bare `CryptoKey` opens only the symmetric ones.
+ *   Typed as a read capability so a write-only seal target — which could open
+ *   neither scheme — is rejected at compile time rather than failing here.
  */
 export async function hydrateDataWithKey(
   value: unknown,
   revivers: Revivers,
-  key: import('./serialization/encryption.js').PayloadKey | undefined
+  key: import('./serialization/encryption.js').DecryptionKey | undefined
 ): Promise<unknown> {
   let data = value;
   if (data instanceof Uint8Array && isEncryptedData(data) && key) {

packages/core/src/serialization/encryption.ts

@@ -97,6 +97,17 @@ export interface RunPayloadKeys {
  */
 export type PayloadKey = CryptoKey | SealTarget | RunPayloadKeys;
 
+/**
+ * The subset of {@link PayloadKey} that can actually *read* a payload.
+ *
+ * Excludes {@link SealTarget}, which is write-only by construction: it holds a
+ * public key, so it can open neither `encp` (needs the private scalar) nor
+ * `encr` (needs the symmetric key). Decrypt-side signatures should take this
+ * rather than `PayloadKey`, so passing a seal target is a compile error instead
+ * of a guaranteed runtime failure.
+ */
+export type DecryptionKey = CryptoKey | RunPayloadKeys;
+
 /**
  * Build a write-only seal capability for a recipient run's public key.
  *

packages/web-shared/src/lib/hydration.ts

@@ -487,7 +487,7 @@ export async function hydrateResourceIOAsync<T>(
   resource: T,
   key?: Uint8Array
 ): Promise<T> {
-  const { hydrateDataWithKey } = await import(
+  const { hydrateDataWithKey, deriveRunPayloadKeys } = await import(
     '@workflow/core/serialization-format'
   );
   // Payloads may be zstd-compressed (the Web DecompressionStream has no zstd);
@@ -502,11 +502,12 @@ export async function hydrateResourceIOAsync<T>(
   // it (a cross-deployment hook resumption, say), and opening those needs the
   // run's X25519 scalar in addition to its AES key. Both are derived from the
   // same 32 bytes the key-retrieval endpoint returns.
-  const cryptoKey = key
-    ? await import('@workflow/core/serialization-format').then(
-        ({ deriveRunPayloadKeys }) => deriveRunPayloadKeys(key)
-      )
-    : undefined;
+  // Resolve the *full* key capability, not just the symmetric key: a run's
+  // event log can contain sealed ('encp') payloads that another run wrote to
+  // it (a cross-deployment hook resumption, say), and opening those needs the
+  // run's X25519 scalar in addition to its AES key. Both derive from the same
+  // 32 bytes the key-retrieval endpoint returns.
+  const cryptoKey = key ? await deriveRunPayloadKeys(key) : undefined;
   const revivers = getRevivers();
 
   async function hydrateField(value: unknown): Promise<unknown> {