@stigmer/runner 3.9.0 → 3.11.0

package/src/activities/workflow-event-activities.ts

@@ -3,8 +3,12 @@
  *
  * Converts plain event descriptors (safe for the Temporal deterministic
  * sandbox) into WorkflowExecutionEvent proto objects and sends them
- * alongside a status update via gRPC. Best-effort — failures are logged
- * but do not fail the activity.
+ * alongside a status update via gRPC. Failures propagate so the local
+ * activity's retry policy fires — safe because sequence numbers are
+ * workflow-assigned (stable across attempts) and the store skips
+ * already-persisted sequences, making retries idempotent. The workflow's
+ * emit wrappers catch after retries are exhausted; event emission never
+ * fails a run.
  *
  * Registered as proxyLocalActivities in engine-core.ts so the workflow
  * sandbox can emit events at task boundaries and approval gates.
@@ -140,6 +144,17 @@ function buildClient(): StigmerClient {
   });
 }
 
+/**
+ * LEGACY sequence assignment — only for descriptors that arrive without a
+ * workflow-assigned `sequenceNumber`, i.e. replays of histories recorded
+ * before the "workflow-assigned-event-sequences" patch (see
+ * engine-core.ts). This counter is process-global: it is shared across
+ * every execution on the worker and resets on worker restart, which is
+ * the root cause of oss#308's silent event loss. Deliberately NOT fixed —
+ * pre-patch executions keep their old (flawed) behavior for the
+ * migration window. Delete together with the patch gate once pre-patch
+ * executions have drained.
+ */
 let sequenceCounter = 0;
 
 function nextSequence(): bigint {
@@ -148,33 +163,44 @@ function nextSequence(): bigint {
 }
 
 /**
- * Initialize the event sequence counter from the persisted high-water mark.
+ * Return the persisted event-log high-water mark for the execution, and
+ * seed the legacy process-global counter from it.
  *
- * On first run (no prior events), the counter stays at 0 and the first
- * event gets sequence_number = 1 — identical to the original behavior.
+ * The workflow seeds its own sequence counter from the returned value
+ * (patched path); the legacy global seed remains for pre-patch replays,
+ * whose emit path still assigns sequences here in the activity.
  *
- * On recovery (events already persisted from a failed run), the counter
- * is set to the highest persisted sequence_number so that new events
- * continue from N+1, avoiding duplicate-key collisions in storage.
+ * On first run (no prior events) returns 0, so the first event gets
+ * sequence_number = 1. On recovery (events already persisted from a
+ * failed run) returns the highest persisted sequence_number, so new
+ * events continue from N+1.
  *
  * When executionId is empty (direct executeServerlessWorkflow without a
- * persisted execution), the counter resets to 0 as a safe fallback.
+ * persisted execution), returns 0 as a safe fallback.
+ *
+ * Returns a plain number — the value crosses back into the workflow
+ * through Temporal's JSON payload converter, which cannot carry BigInt.
  */
-export async function initSequenceFromEventLog(executionId: string): Promise<void> {
+export async function initSequenceFromEventLog(executionId: string): Promise<number> {
   if (!executionId) {
     sequenceCounter = 0;
-    return;
+    return 0;
   }
   const client = buildClient();
   const highWaterMark = await client.getEventLogHighWaterMark(executionId);
   sequenceCounter = Number(highWaterMark);
+  return sequenceCounter;
 }
 
 /** @internal Exported for unit testing only. */
 export function toProtoEvent(desc: WorkflowEventDescriptor): WorkflowExecutionEvent {
   const base = create(WorkflowExecutionEventSchema, {
     eventId: crypto.randomUUID(),
-    sequenceNumber: nextSequence(),
+    // Workflow-assigned sequence when present (stable across activity
+    // retries); legacy activity-side assignment only for pre-patch replays.
+    sequenceNumber: desc.sequenceNumber !== undefined
+      ? BigInt(desc.sequenceNumber)
+      : nextSequence(),
     occurredAt: desc.occurredAt,
     taskName: desc.taskName ?? "",
   });
@@ -382,6 +408,14 @@ export function toProtoEvent(desc: WorkflowEventDescriptor): WorkflowExecutionEv
   return base;
 }
 
+/**
+ * Emit workflow events (with the accompanying status snapshot) to the
+ * server. Errors propagate so the local activity retry policy fires;
+ * retries are idempotent because workflow-assigned sequence numbers are
+ * stable across attempts and the store skips already-persisted ones. The
+ * workflow-side emit wrappers absorb the failure after retries are
+ * exhausted, so a broken timeline write never fails the run.
+ */
 export async function emitWorkflowEvents(
   executionId: string,
   events: WorkflowEventDescriptor[],
@@ -389,64 +423,57 @@ export async function emitWorkflowEvents(
 ): Promise<void> {
   if (!executionId || events.length === 0) return;
 
-  try {
-    const client = buildClient();
-    const protoEvents = events.map(toProtoEvent);
-
-    const protoTasks = (taskStatuses ?? []).map(ts =>
-      create(WorkflowTaskSchema, {
-        taskId: ts.taskId ?? "",
-        taskName: ts.taskName,
-        taskType: TASK_KIND_TO_TYPE_MAP[ts.taskKind] ?? WorkflowTaskType.WORKFLOW_TASK_TYPE_UNSPECIFIED,
-        status: TASK_STATUS_MAP[ts.status],
-        startedAt: ts.startedAt ?? "",
-        completedAt: ts.completedAt ?? "",
-        error: ts.error ?? "",
-        input: toJsonObject(ts.input),
-        output: toJsonObject(ts.output),
-        metadata: toJsonObject(ts.metadata),
-        costMicros: BigInt(ts.costMicros ?? 0),
-        inputTokens: BigInt(ts.inputTokens ?? 0),
-        outputTokens: BigInt(ts.outputTokens ?? 0),
-        uiHint: ts.uiHint ?? "",
-      }),
-    );
-
-    const startedEvent = events.find(e => e.type === "execution_started");
-    const completedEvent = events.find(e => e.type === "execution_completed");
-    const failedEvent = events.find(e => e.type === "execution_failed");
-
-    const statusFields: Record<string, unknown> = { tasks: protoTasks };
-
-    if (startedEvent) {
-      statusFields.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
-      statusFields.startedAt = startedEvent.occurredAt;
-    }
-    if (completedEvent && completedEvent.type === "execution_completed") {
-      statusFields.phase = ExecutionPhase.EXECUTION_COMPLETED;
-      statusFields.completedAt = completedEvent.occurredAt;
-      statusFields.totalCostMicros = BigInt(completedEvent.totalCostMicros);
-      statusFields.totalInputTokens = BigInt(completedEvent.totalInputTokens ?? 0);
-      statusFields.totalOutputTokens = BigInt(completedEvent.totalOutputTokens ?? 0);
-    }
-    if (failedEvent && failedEvent.type === "execution_failed") {
-      statusFields.phase = ExecutionPhase.EXECUTION_FAILED;
-      statusFields.completedAt = failedEvent.occurredAt;
-      statusFields.error = failedEvent.error;
-    }
-
-    const input = create(WorkflowExecutionUpdateStatusInputSchema, {
-      executionId,
-      status: create(WorkflowExecutionStatusSchema, statusFields as Parameters<typeof create>[1]),
-      events: protoEvents,
-    });
-    await client.workflowExecutionCommand.updateStatus(input);
-  } catch (err) {
-    console.error(
-      `Failed to emit ${events.length} workflow event(s) for ${executionId}:`,
-      err,
-    );
+  const client = buildClient();
+  const protoEvents = events.map(toProtoEvent);
+
+  const protoTasks = (taskStatuses ?? []).map(ts =>
+    create(WorkflowTaskSchema, {
+      taskId: ts.taskId ?? "",
+      taskName: ts.taskName,
+      taskType: TASK_KIND_TO_TYPE_MAP[ts.taskKind] ?? WorkflowTaskType.WORKFLOW_TASK_TYPE_UNSPECIFIED,
+      status: TASK_STATUS_MAP[ts.status],
+      startedAt: ts.startedAt ?? "",
+      completedAt: ts.completedAt ?? "",
+      error: ts.error ?? "",
+      input: toJsonObject(ts.input),
+      output: toJsonObject(ts.output),
+      metadata: toJsonObject(ts.metadata),
+      costMicros: BigInt(ts.costMicros ?? 0),
+      inputTokens: BigInt(ts.inputTokens ?? 0),
+      outputTokens: BigInt(ts.outputTokens ?? 0),
+      uiHint: ts.uiHint ?? "",
+    }),
+  );
+
+  const startedEvent = events.find(e => e.type === "execution_started");
+  const completedEvent = events.find(e => e.type === "execution_completed");
+  const failedEvent = events.find(e => e.type === "execution_failed");
+
+  const statusFields: Record<string, unknown> = { tasks: protoTasks };
+
+  if (startedEvent) {
+    statusFields.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
+    statusFields.startedAt = startedEvent.occurredAt;
+  }
+  if (completedEvent && completedEvent.type === "execution_completed") {
+    statusFields.phase = ExecutionPhase.EXECUTION_COMPLETED;
+    statusFields.completedAt = completedEvent.occurredAt;
+    statusFields.totalCostMicros = BigInt(completedEvent.totalCostMicros);
+    statusFields.totalInputTokens = BigInt(completedEvent.totalInputTokens ?? 0);
+    statusFields.totalOutputTokens = BigInt(completedEvent.totalOutputTokens ?? 0);
+  }
+  if (failedEvent && failedEvent.type === "execution_failed") {
+    statusFields.phase = ExecutionPhase.EXECUTION_FAILED;
+    statusFields.completedAt = failedEvent.occurredAt;
+    statusFields.error = failedEvent.error;
   }
+
+  const input = create(WorkflowExecutionUpdateStatusInputSchema, {
+    executionId,
+    status: create(WorkflowExecutionStatusSchema, statusFields as Parameters<typeof create>[1]),
+    events: protoEvents,
+  });
+  await client.workflowExecutionCommand.updateStatus(input);
 }
 
 const PROTO_STATUS_TO_STRING: Record<number, string> = {

package/src/claimcheck/payload-codec.ts

@@ -22,6 +22,14 @@ interface ClaimcheckMarker {
   key: string;
   size: number;
   compressed: boolean;
+  /**
+   * The relocated payload's original metadata, base64-encoded per value.
+   * Without it the restored payload would carry the marker's own
+   * "binary/claimcheck" encoding and no payload converter could interpret
+   * it. Absent on markers written before this field existed; those decode
+   * with the legacy (metadata-less) behavior.
+   */
+  metadata?: Record<string, string>;
 }
 
 export class ClaimcheckPayloadCodec implements PayloadCodec {
@@ -63,6 +71,7 @@ export class ClaimcheckPayloadCodec implements PayloadCodec {
       key,
       size: data.length,
       compressed,
+      metadata: serializeMetadata(payload.metadata),
     };
 
     return {
@@ -94,7 +103,9 @@ export class ClaimcheckPayloadCodec implements PayloadCodec {
     const dataBuf = marker.compressed ? decompress(rawBuf) : rawBuf;
 
     return {
-      metadata: payload.metadata,
+      metadata: marker.metadata
+        ? deserializeMetadata(marker.metadata)
+        : payload.metadata,
       data: dataBuf,
     };
   }
@@ -105,3 +116,24 @@ export class ClaimcheckPayloadCodec implements PayloadCodec {
     return Buffer.from(encoding).toString("utf-8") === MARKER_ENCODING_VALUE;
   }
 }
+
+function serializeMetadata(
+  metadata: Payload["metadata"],
+): Record<string, string> | undefined {
+  if (!metadata) return undefined;
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value) out[key] = Buffer.from(value).toString("base64");
+  }
+  return out;
+}
+
+function deserializeMetadata(
+  metadata: Record<string, string>,
+): Record<string, Uint8Array> {
+  const out: Record<string, Uint8Array> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    out[key] = Buffer.from(value, "base64");
+  }
+  return out;
+}

package/src/client/__tests__/stigmer-client.test.ts

@@ -320,22 +320,22 @@ describe("StigmerClient", () => {
       expect(spy).not.toHaveBeenCalled();
     });
 
-    it("falls back (undefined) when the server mints no token", async () => {
+    it("throws when the server mints no token — the bootstrap credential no longer decrypts (stigmer-cloud#218)", async () => {
       const client = clientWithRunnerCredential(fakeTokenOfType("embedded_runner"));
       vi.spyOn(client, "getRunnerScopedToken").mockResolvedValue(undefined);
 
-      const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
-
-      expect(token).toBeUndefined();
+      await expect(
+        client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" }),
+      ).rejects.toThrow(/minted no scoped runner token for agent execution aex_1/);
     });
 
-    it("falls back (undefined) when the exchange fails, instead of failing the execution", async () => {
+    it("throws when the exchange fails, naming the scope and preserving the cause", async () => {
       const client = clientWithRunnerCredential(fakeTokenOfType("embedded_runner"));
       vi.spyOn(client, "getRunnerScopedToken").mockRejectedValue(new Error("boom"));
 
-      const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
-
-      expect(token).toBeUndefined();
+      await expect(
+        client.acquireScopedRunnerToken({ workflowExecutionId: "wfx_1" }),
+      ).rejects.toThrow(/exchange failed for workflow execution wfx_1: boom/);
     });
   });
 

package/src/client/stigmer-client.ts

@@ -360,10 +360,15 @@ export class StigmerClient {
    * OSS/local runner holds no runner-class credential at all (skip — the
    * server neither mints nor redacts).
    *
-   * Failure falls back rather than failing the execution: returning undefined
-   * makes the read authenticate with the bootstrap credential, which remains
-   * decrypt-eligible until issue #156 item 3 removes it — at that point this
-   * fallback stops yielding secrets and executions surface the warning below.
+   * A failed exchange is a hard error, not a fallback: since the #156 item-3
+   * flip (stigmer-cloud#218) the bootstrap credential no longer decrypts, so
+   * a read that "fell back" would silently receive redacted placeholders and
+   * the execution would run against junk secret values — strictly worse than
+   * failing here with the real reason. The secret-delivery call sites let
+   * this error fail the activity; opportunistic consumers that can genuinely
+   * proceed without a scoped token (attachment credential, channel
+   * discovery) catch it at the call site, where their degrade-to-empty
+   * contract lives.
    */
   async acquireScopedRunnerToken(
     scope: RunnerScopedTokenScope,
@@ -371,24 +376,33 @@ export class StigmerClient {
     if (!isEmbeddedRunnerToken(this.runnerTokenRef?.current)) {
       return undefined;
     }
+    const scopeDescription =
+      "agentExecutionId" in scope
+        ? `agent execution ${scope.agentExecutionId}`
+        : "workflowExecutionId" in scope
+          ? `workflow execution ${scope.workflowExecutionId}`
+          : JSON.stringify(scope);
+    let scoped: RunnerScopedToken | undefined;
     try {
-      const scoped = await this.getRunnerScopedToken(scope);
-      if (!scoped) {
-        console.warn(
-          "[stigmer-client] Server minted no scoped runner token; " +
-          "falling back to the bootstrap credential for the ExecutionContext read",
-        );
-        return undefined;
-      }
-      return scoped.token;
+      scoped = await this.getRunnerScopedToken(scope);
     } catch (err) {
-      console.warn(
-        "[stigmer-client] Scoped runner token exchange failed; " +
-        "falling back to the bootstrap credential for the ExecutionContext read: " +
-        `${err instanceof Error ? err.message : err}`,
+      throw new Error(
+        `Scoped runner token exchange failed for ${scopeDescription}: ` +
+        `${err instanceof Error ? err.message : String(err)}. ` +
+        "The bootstrap credential cannot read ExecutionContext secrets " +
+        "(stigmer-cloud#218), so this runner cannot serve the execution " +
+        "until the exchange succeeds.",
+      );
+    }
+    if (!scoped) {
+      throw new Error(
+        `Server minted no scoped runner token for ${scopeDescription}. ` +
+        "The bootstrap credential cannot read ExecutionContext secrets " +
+        "(stigmer-cloud#218), so this runner cannot serve the execution " +
+        "until the control plane mints scoped tokens.",
       );
-      return undefined;
     }
+    return scoped.token;
   }
 
   /**

package/src/encryption/config.ts

@@ -0,0 +1,91 @@
+/**
+ * Payload-encryption configuration (stigmer-cloud#227).
+ *
+ * Encryption is enabled iff STIGMER_PAYLOAD_ENCRYPTION_KEY is present —
+ * the same enabled-iff-configured pattern as the claim-check codec. A
+ * malformed key fails the boot rather than silently running plaintext:
+ * an operator who set the key intended history to be encrypted.
+ *
+ * Key rotation: payloads carry the id of the key that encrypted them.
+ * During a rotation window the previous key stays readable via
+ * STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY(_ID) while new payloads are
+ * written under the primary key.
+ */
+
+export interface EncryptionKey {
+  readonly keyId: string;
+  /** 32-byte AES-256 key. */
+  readonly key: Buffer;
+}
+
+export interface PayloadEncryptionConfig {
+  /** Key used to encrypt outgoing payloads (and decrypt its own). */
+  readonly primary: EncryptionKey;
+  /** Decrypt-only key accepted during rotation windows. */
+  readonly secondary?: EncryptionKey;
+}
+
+const KEY_ENV = "STIGMER_PAYLOAD_ENCRYPTION_KEY";
+const KEY_ID_ENV = "STIGMER_PAYLOAD_ENCRYPTION_KEY_ID";
+const SECONDARY_KEY_ENV = "STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY";
+const SECONDARY_KEY_ID_ENV = "STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY_ID";
+
+const AES_256_KEY_BYTES = 32;
+
+/**
+ * Returns the encryption config, or undefined when encryption is not
+ * configured (the codec is then simply not installed).
+ *
+ * @throws when a key is present but malformed, or a key id is missing —
+ *   key misconfiguration must stop the boot, not degrade to plaintext.
+ */
+export function loadPayloadEncryptionConfig(): PayloadEncryptionConfig | undefined {
+  const rawKey = process.env[KEY_ENV];
+  if (!rawKey) {
+    return undefined;
+  }
+
+  const primary: EncryptionKey = {
+    keyId: requireKeyId(KEY_ID_ENV),
+    key: parseKey(rawKey, KEY_ENV),
+  };
+
+  const rawSecondary = process.env[SECONDARY_KEY_ENV];
+  const secondary: EncryptionKey | undefined = rawSecondary
+    ? {
+        keyId: requireKeyId(SECONDARY_KEY_ID_ENV),
+        key: parseKey(rawSecondary, SECONDARY_KEY_ENV),
+      }
+    : undefined;
+
+  return { primary, secondary };
+}
+
+function requireKeyId(envName: string): string {
+  const keyId = process.env[envName];
+  // An explicit id is required (no default): during rotation two keys
+  // coexist, and payloads must name which one encrypted them.
+  if (!keyId) {
+    throw new Error(
+      `Payload encryption misconfigured: ${envName} is required when the ` +
+        `corresponding key is set`,
+    );
+  }
+  return keyId;
+}
+
+function parseKey(rawBase64: string, envName: string): Buffer {
+  let key: Buffer;
+  try {
+    key = Buffer.from(rawBase64, "base64");
+  } catch {
+    throw new Error(`Payload encryption misconfigured: ${envName} is not valid base64`);
+  }
+  if (key.length !== AES_256_KEY_BYTES) {
+    throw new Error(
+      `Payload encryption misconfigured: ${envName} must decode to ` +
+        `${AES_256_KEY_BYTES} bytes (AES-256), got ${key.length}`,
+    );
+  }
+  return key;
+}

package/src/encryption/index.ts

@@ -0,0 +1,3 @@
+export { EncryptionPayloadCodec } from "./payload-codec.js";
+export { loadPayloadEncryptionConfig } from "./config.js";
+export type { PayloadEncryptionConfig, EncryptionKey } from "./config.js";

package/src/encryption/payload-codec.ts

@@ -0,0 +1,152 @@
+/**
+ * Temporal PayloadCodec that encrypts payloads at rest in workflow
+ * history (stigmer-cloud#227).
+ *
+ * Why: the workflow engine runs inside the Temporal deterministic
+ * sandbox, so decrypted execution-context values cross the history
+ * boundary in many places — the hydrate activity result, the runtime
+ * env passed as an input to every per-task activity, and expression
+ * results recorded as local-activity markers. Encrypting at the payload
+ * codec layer closes the entire class with one mechanism instead of
+ * chasing each crossing.
+ *
+ * Envelope (cross-SDK contract — the Java decode-only codec in
+ * stigmer-cloud's temporal-starter must match it byte-for-byte, pinned
+ * by the conformance fixture in __tests__/fixtures/):
+ *
+ *   metadata: encoding            = "binary/encrypted"
+ *             encryption-key-id   = <key id that encrypted this payload>
+ *   data:     iv (12 bytes) ‖ AES-256-GCM(ciphertext ‖ tag (16 bytes))
+ *
+ * The plaintext is the serialized ORIGINAL Payload proto (metadata AND
+ * data), so decode restores the payload exactly — including its
+ * original encoding — with no side channel.
+ *
+ * Decode passes through payloads it did not encode. This is what keeps
+ * plaintext signals from the Java/Go orchestrators and pre-rollout
+ * in-flight histories working with zero migration. Everything else
+ * fails closed: unknown key id, missing key id, and ciphertext tampering
+ * all throw rather than surfacing bogus payloads.
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import type { Payload, PayloadCodec } from "@temporalio/common";
+// Default-import + destructure, NOT `import { temporal } from …`:
+// @temporalio/proto is CommonJS and its `temporal` export defeats Node's
+// cjs-module-lexer named-export detection, so the named form loads under
+// tsx/vitest (their interop is looser) but crashes plain `node dist/main.js`
+// at startup with "Named export 'temporal' not found" (stigmer/stigmer#399
+// boot regression). Pinned by scripts/verify-dist-boot.mjs in CI.
+import proto from "@temporalio/proto";
+import type { EncryptionKey, PayloadEncryptionConfig } from "./config.js";
+
+const { temporal } = proto;
+
+const ENCODING_METADATA_KEY = "encoding";
+const ENCRYPTED_ENCODING_VALUE = "binary/encrypted";
+const KEY_ID_METADATA_KEY = "encryption-key-id";
+
+/** AES-GCM parameters shared with the Java implementation. */
+const IV_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+
+export class EncryptionPayloadCodec implements PayloadCodec {
+  private readonly decryptKeysById: Map<string, Buffer>;
+
+  constructor(private readonly config: PayloadEncryptionConfig) {
+    this.decryptKeysById = new Map([[config.primary.keyId, config.primary.key]]);
+    if (config.secondary) {
+      this.decryptKeysById.set(config.secondary.keyId, config.secondary.key);
+    }
+  }
+
+  async encode(payloads: Payload[]): Promise<Payload[]> {
+    return payloads.map((p) => this.encodePayload(p));
+  }
+
+  async decode(payloads: Payload[]): Promise<Payload[]> {
+    return payloads.map((p) => this.decodePayload(p));
+  }
+
+  private encodePayload(payload: Payload): Payload {
+    // Data-less payloads (binary/null from void results) stay as-is:
+    // there is nothing to protect, and the cross-language parents that
+    // await our workflows as void must be able to read them without a key.
+    if (!payload.data || payload.data.length === 0) {
+      return payload;
+    }
+
+    const plaintext = temporal.api.common.v1.Payload.encode(payload).finish();
+    return {
+      metadata: {
+        [ENCODING_METADATA_KEY]: Buffer.from(ENCRYPTED_ENCODING_VALUE),
+        [KEY_ID_METADATA_KEY]: Buffer.from(this.config.primary.keyId),
+      },
+      data: encrypt(plaintext, this.config.primary),
+    };
+  }
+
+  private decodePayload(payload: Payload): Payload {
+    if (!isEncryptedPayload(payload)) {
+      return payload;
+    }
+
+    const keyIdBytes = payload.metadata?.[KEY_ID_METADATA_KEY];
+    if (!keyIdBytes) {
+      throw new Error(
+        "Encrypted payload is missing its encryption-key-id metadata — refusing to decode",
+      );
+    }
+    const keyId = Buffer.from(keyIdBytes).toString("utf-8");
+    const key = this.decryptKeysById.get(keyId);
+    if (!key) {
+      throw new Error(
+        `Encrypted payload uses unknown key id '${keyId}' — configure it as the ` +
+          `primary or secondary payload encryption key (rotation window?)`,
+      );
+    }
+
+    const plaintext = decrypt(payload.data!, key, keyId);
+    return temporal.api.common.v1.Payload.decode(plaintext);
+  }
+}
+
+function isEncryptedPayload(payload: Payload): boolean {
+  const encoding = payload.metadata?.[ENCODING_METADATA_KEY];
+  if (!encoding) return false;
+  return Buffer.from(encoding).toString("utf-8") === ENCRYPTED_ENCODING_VALUE;
+}
+
+function encrypt(plaintext: Uint8Array, key: EncryptionKey): Buffer {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv("aes-256-gcm", key.key, iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  // Layout iv ‖ ciphertext ‖ tag matches Java's AES/GCM/NoPadding, whose
+  // doFinal() output is ciphertext ‖ tag.
+  return Buffer.concat([iv, ciphertext, cipher.getAuthTag()]);
+}
+
+function decrypt(data: Uint8Array, key: Buffer, keyId: string): Buffer {
+  if (data.length < IV_BYTES + AUTH_TAG_BYTES) {
+    throw new Error(
+      `Encrypted payload under key id '${keyId}' is truncated (${data.length} bytes)`,
+    );
+  }
+  const buf = Buffer.from(data);
+  const iv = buf.subarray(0, IV_BYTES);
+  const ciphertext = buf.subarray(IV_BYTES, buf.length - AUTH_TAG_BYTES);
+  const tag = buf.subarray(buf.length - AUTH_TAG_BYTES);
+
+  const decipher = createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(tag);
+  try {
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  } catch {
+    // GCM auth failure: tampered ciphertext or a key that does not match
+    // its advertised id. Never surface partially decrypted bytes.
+    throw new Error(
+      `Failed to decrypt payload under key id '${keyId}' — ciphertext is ` +
+        `corrupt or the configured key does not match`,
+    );
+  }
+}