@stigmer/runner 3.10.0 → 3.11.1-dev.20260812192248

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

@@ -45,10 +45,11 @@ function makeScopedTokenExchangeRequest() {
 }
 
 /** An unsigned JWT-shaped token carrying the given token_type claim. */
-function fakeTokenOfType(tokenType: string): string {
+function fakeTokenOfType(tokenType?: string): string {
   const b64 = (obj: Record<string, unknown>) =>
     Buffer.from(JSON.stringify(obj)).toString("base64url");
-  return `${b64({ alg: "RS256" })}.${b64({ token_type: tokenType })}.sig`;
+  const claims = tokenType === undefined ? {} : { token_type: tokenType };
+  return `${b64({ alg: "RS256" })}.${b64(claims)}.sig`;
 }
 
 /**
@@ -310,32 +311,82 @@ describe("StigmerClient", () => {
       expect(spy).not.toHaveBeenCalled();
     });
 
-    it("skips the exchange when no runner credential exists (OSS/local)", async () => {
+    // NOTE (oss#535): the no-credential arm previously pinned "skip the
+    // exchange" — correct while OSS neither minted nor redacted. Since
+    // oss#535 the OSS server redacts EC reads by default and mints
+    // execution-scoped tokens on this exchange, so a credential-less runner
+    // must now ASK, and fall back to the tokenless read only when the server
+    // answers not-minted (pre-oss#535 OSS) or refuses (cloud refusing a
+    // non-runner credential — the legacy desktop degrade).
+    it("exchanges best-effort when no runner credential exists and uses a minted token (oss#535)", async () => {
       const client = clientWithRunnerCredential(null);
-      const spy = vi.spyOn(client, "getRunnerScopedToken");
+      vi.spyOn(client, "getRunnerScopedToken").mockResolvedValue({
+        token: "oss-scoped-tok",
+        expiresInSeconds: 3600,
+      });
 
       const token = await client.acquireScopedRunnerToken({ workflowExecutionId: "wfx_1" });
 
-      expect(token).toBeUndefined();
-      expect(spy).not.toHaveBeenCalled();
+      expect(token).toBe("oss-scoped-tok");
+      expect(client.getRunnerScopedToken).toHaveBeenCalledWith({ workflowExecutionId: "wfx_1" });
     });
 
-    it("falls back (undefined) when the server mints no token", async () => {
-      const client = clientWithRunnerCredential(fakeTokenOfType("embedded_runner"));
+    it("proceeds tokenless when a credential-less exchange is answered not-minted (pre-oss#535 server)", async () => {
+      const client = clientWithRunnerCredential(null);
       vi.spyOn(client, "getRunnerScopedToken").mockResolvedValue(undefined);
 
+      const token = await client.acquireScopedRunnerToken({ workflowExecutionId: "wfx_1" });
+
+      expect(token).toBeUndefined();
+    });
+
+    it("proceeds tokenless when a credential-less exchange is refused (cloud refusing a non-runner credential)", async () => {
+      const client = clientWithRunnerCredential(null);
+      vi.spyOn(client, "getRunnerScopedToken").mockRejectedValue(new Error("permission denied"));
+
       const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
 
       expect(token).toBeUndefined();
     });
 
-    it("falls back (undefined) when the exchange fails, instead of failing the execution", async () => {
-      const client = clientWithRunnerCredential(fakeTokenOfType("embedded_runner"));
-      vi.spyOn(client, "getRunnerScopedToken").mockRejectedValue(new Error("boom"));
+    it("treats a non-JWT process token as no runner credential (the harness/proxy token shape)", async () => {
+      // e.g. the conformance harness boots the runner with a mock proxy
+      // token that is not a Stigmer-minted JWT; the best-effort arm must
+      // still ask the server for a scoped token.
+      const client = clientWithRunnerCredential("not-a-jwt-proxy-token");
+      vi.spyOn(client, "getRunnerScopedToken").mockResolvedValue({ token: "scoped-tok" });
+
+      const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
+
+      expect(token).toBe("scoped-tok");
+    });
+
+    it("treats a claim-less user JWT as no runner credential (legacy desktop shape)", async () => {
+      const client = clientWithRunnerCredential(fakeTokenOfType(undefined));
+      vi.spyOn(client, "getRunnerScopedToken").mockResolvedValue(undefined);
 
       const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
 
       expect(token).toBeUndefined();
+      expect(client.getRunnerScopedToken).toHaveBeenCalled();
+    });
+
+    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);
+
+      await expect(
+        client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" }),
+      ).rejects.toThrow(/minted no scoped runner token for agent execution aex_1/);
+    });
+
+    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"));
+
+      await expect(
+        client.acquireScopedRunnerToken({ workflowExecutionId: "wfx_1" }),
+      ).rejects.toThrow(/exchange failed for workflow execution wfx_1: boom/);
     });
   });
 
@@ -432,6 +483,54 @@ describe("StigmerClient", () => {
     });
   });
 
+  describe("sendWorkflowSignal", () => {
+    function clientWithWorkflowCommand() {
+      const client = new StigmerClient({ endpoint: "http://localhost", token: null });
+      const sendSignal = vi.fn().mockResolvedValue({});
+      // Reach into the private generated client: the mocked createClient()
+      // returned {}, so install the method it would have provided.
+      (client as any).workflowExecutionCommand = { sendSignal };
+      return { client, rpc: sendSignal };
+    }
+
+    it("builds SendSignalInput with execution addressing and the payload verbatim", async () => {
+      const { client, rpc } = clientWithWorkflowCommand();
+      const payload = { type: "approval.granted", data: { ok: true } };
+
+      await client.sendWorkflowSignal("wfx_1", "approval_resolved", payload);
+
+      const input = rpc.mock.calls[0]![0];
+      expect(input.executionId).toBe("wfx_1");
+      expect(input.signalName).toBe("approval_resolved");
+      expect(input.payload).toEqual(payload);
+    });
+
+    it("sends no idempotency key (oss#442: failed-delivery claims are never released)", async () => {
+      const { client, rpc } = clientWithWorkflowCommand();
+
+      await client.sendWorkflowSignal("wfx_1", "ping", undefined);
+
+      const input = rpc.mock.calls[0]![0];
+      expect(input.idempotencyKey).toBe("");
+    });
+
+    it("passes the per-call timeout through to the RPC", async () => {
+      const { client, rpc } = clientWithWorkflowCommand();
+
+      await client.sendWorkflowSignal("wfx_1", "ping", undefined, { timeoutMs: 30_000 });
+
+      expect(rpc).toHaveBeenCalledWith(expect.anything(), { timeoutMs: 30_000 });
+    });
+
+    it("passes an undefined timeout when no options are supplied", async () => {
+      const { client, rpc } = clientWithWorkflowCommand();
+
+      await client.sendWorkflowSignal("wfx_1", "ping", undefined);
+
+      expect(rpc).toHaveBeenCalledWith(expect.anything(), { timeoutMs: undefined });
+    });
+  });
+
   describe("updateToken", () => {
     it("does not affect tokenRef-based resolution", async () => {
       const ref: TokenRef = { current: "from-ref" };

package/src/client/stigmer-client.ts

@@ -44,7 +44,8 @@ import type { UpdateStatusResponse } from "@stigmer/protos/ai/stigmer/agentic/ag
 import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
 import { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
 import type { WorkflowExecution, WorkflowExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
-import { WorkflowExecutionUpdateStatusInputSchema, GetEventLogRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { WorkflowExecutionUpdateStatusInputSchema, GetEventLogRequestSchema, SendSignalInputSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import type { JsonObject } from "@bufbuild/protobuf";
 import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
 import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
 import { WorkflowInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/query_pb";
@@ -52,9 +53,29 @@ import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workfl
 import { PlatformQueryController, GetRunnerScopedTokenInputSchema, TokenRenewalSchema } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 import { ChannelMessageQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_query_pb";
 import type { ChannelTemplate, MessagingChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
-import { isEmbeddedRunnerToken } from "./token-claims.js";
+import { TOKEN_TYPE_EMBEDDED_RUNNER, tokenTypeOf } from "./token-claims.js";
 import { assertCreateRequirements, assertReferenceRequirements } from "./server-contracts.js";
 
+/**
+ * Server-managed Temporal payload-encryption keys for this runner.
+ *
+ * Minted once per caller identity and persisted by the control plane, so
+ * every boot of the same identity's runners receives the SAME key — the
+ * persistence Temporal replay requires across runner restarts. The secondary
+ * pair is present only during a rotation window (decrypt-only; new payloads
+ * are written under the primary).
+ */
+export interface BootstrapPayloadEncryptionKeys {
+  /** Base64-encoded 32-byte AES-256 key. */
+  key: string;
+  /** Key id stamped on payloads encrypted under {@link key}. */
+  keyId: string;
+  /** Previous key of this identity, present during rotation windows. */
+  secondaryKey?: string;
+  /** Key id of {@link secondaryKey}; present exactly when it is. */
+  secondaryKeyId?: string;
+}
+
 /**
  * Everything an embedded runner needs to bootstrap: Temporal coordinates plus
  * its own minted access token.
@@ -62,7 +83,10 @@ import { assertCreateRequirements, assertReferenceRequirements } from "./server-
  * The Temporal coordinates are always present. The access token is optional: the
  * server only mints one when it has a Cursor proxy to authenticate against
  * (cloud) and a signing key configured — OSS and misconfigured servers omit it,
- * and the runner keeps using its existing token in that case.
+ * and the runner keeps using its existing token in that case. Payload-encryption
+ * keys follow the same presence contract: absent when the server does not manage
+ * runner keys (OSS uses env-configured keys; older cloud servers predate key
+ * management).
  */
 export interface RunnerBootstrapConfig {
   temporalAddress: string;
@@ -71,15 +95,18 @@ export interface RunnerBootstrapConfig {
   runnerAccessToken?: string;
   /** Lifetime of {@link runnerAccessToken} in seconds; absent/0 when no token. */
   runnerAccessTokenExpiresInSeconds?: number;
+  /** Server-managed payload-encryption keys; absent when not managed by the server. */
+  payloadEncryption?: BootstrapPayloadEncryptionKeys;
 }
 
 /**
  * A runner token scoped to one unit of dispatched work (issue #156).
  *
- * Minted on demand by the control plane when the runner exchanges its
- * bootstrap credential at task start; presented for the ExecutionContext
- * fetch of exactly that execution. Absent when the server does not mint
- * (OSS, or no signing key) — the runner keeps its existing credential.
+ * Minted on demand by the control plane at task start — a desktop runner
+ * exchanges its bootstrap credential, an OSS runner asks with no credential
+ * at all (oss#535) — and presented for the ExecutionContext fetch of exactly
+ * that execution. Absent when the server does not mint (pre-oss#535 OSS, or
+ * a refused credential class) — the runner keeps its existing credential.
  */
 export interface RunnerScopedToken {
   token: string;
@@ -272,6 +299,18 @@ export class StigmerClient {
       runnerAccessToken: res.runnerAccessToken || undefined,
       runnerAccessTokenExpiresInSeconds:
         res.runnerAccessTokenExpiresInSeconds || undefined,
+      // Same presence contract, grouped so callers make ONE presence check.
+      // Key without id (or vice versa) is a server contract violation the
+      // encryption config loader rejects — not silently dropped here, so the
+      // breakage is diagnosable at the fail-closed boundary.
+      payloadEncryption: res.payloadEncryptionKey
+        ? {
+            key: res.payloadEncryptionKey,
+            keyId: res.payloadEncryptionKeyId,
+            secondaryKey: res.payloadEncryptionSecondaryKey || undefined,
+            secondaryKeyId: res.payloadEncryptionSecondaryKeyId || undefined,
+          }
+        : undefined,
     };
   }
 
@@ -313,14 +352,16 @@ export class StigmerClient {
   }
 
   /**
-   * Exchange this runner's bootstrap credential for a token scoped to one
-   * unit of dispatched work (issue #156).
+   * Exchange this runner's credential for a token scoped to one unit of
+   * dispatched work (issue #156).
    *
-   * The call authenticates with the runner credential (see the interceptor);
-   * the server verifies it is an embedded_runner token and that its identity
-   * can view the named execution, then mints the same session/execution-scoped
-   * sandbox token a cloud sandbox runner receives at provisioning. Returns
-   * undefined when the server does not mint (OSS, or no signing key) —
+   * The call authenticates with the runner credential (see the interceptor).
+   * Cloud verifies it is an embedded_runner token and that its identity can
+   * view the named execution, then mints the same session/execution-scoped
+   * sandbox token a cloud sandbox runner receives at provisioning. OSS mints
+   * an execution-scoped token for any caller (oss#535 — a lane discriminator
+   * on a single-user server, not a trust boundary). Returns undefined when
+   * the server does not mint (pre-oss#535 OSS, or an unserved scope arm) —
    * presence-based, like the bootstrap token fields.
    *
    * `callerToken` authenticates the exchange per-call instead of the
@@ -354,41 +395,83 @@ export class StigmerClient {
    * Acquire a scoped runner token for an ExecutionContext read, if this
    * runner's credential situation calls for one.
    *
-   * The gate is the credential itself: only an unscoped embedded_runner
-   * bootstrap token needs exchanging. A cloud sandbox runner's credential is
-   * already scoped (skip — the exchange would rightly refuse it), and an
-   * OSS/local runner holds no runner-class credential at all (skip — the
-   * server neither mints nor redacts).
+   * The gate is the credential itself, three ways:
    *
-   * 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.
+   * 1. An unscoped embedded_runner bootstrap token MUST be exchanged, and 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.
+   *
+   * 2. Any other runner-class credential is already scoped (a cloud
+   *    sandbox/pool/connect token) — skip; the exchange would rightly
+   *    refuse it and the ambient credential decrypts on its own.
+   *
+   * 3. No runner-class credential at all (OSS/local, where the process
+   *    token is absent or carries no token_type claim) — attempt the
+   *    exchange best-effort (oss#535): a current OSS server mints an
+   *    execution-scoped token here, which is the ONLY way this runner can
+   *    read decrypted secrets from its redact-by-default EC RPCs. A server
+   *    that answers "not minted" (pre-oss#535 OSS, which also does not
+   *    redact) or refuses the exchange (cloud refusing a non-runner
+   *    credential — the legacy desktop degrade, which reads redacted today
+   *    regardless) falls through to the tokenless read, preserving each
+   *    old pairing's exact behavior.
    */
   async acquireScopedRunnerToken(
     scope: RunnerScopedTokenScope,
   ): Promise<string | undefined> {
-    if (!isEmbeddedRunnerToken(this.runnerTokenRef?.current)) {
+    // Inspect the same credential chain the EC read's interceptor would use.
+    const ambientTokenType = tokenTypeOf(
+      this.runnerTokenRef?.current ?? this.tokenRef?.current ?? this.currentToken,
+    );
+    const isEmbeddedRunner = ambientTokenType === TOKEN_TYPE_EMBEDDED_RUNNER;
+    if (ambientTokenType !== undefined && !isEmbeddedRunner) {
+      // Case 2: an already-scoped runner-class credential.
       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",
-        );
+      scoped = await this.getRunnerScopedToken(scope);
+    } catch (err) {
+      if (!isEmbeddedRunner) {
+        // Case 3: best-effort — a refusal means the server does not serve
+        // this credential class; the tokenless read is today's behavior.
         return undefined;
       }
-      return scoped.token;
-    } 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.",
       );
-      return undefined;
     }
+    if (!scoped) {
+      if (!isEmbeddedRunner) {
+        // Case 3: a server that mints nothing for this scope also does not
+        // redact for this runner (pre-oss#535 OSS) — proceed tokenless.
+        return undefined;
+      }
+      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 scoped.token;
   }
 
   /**
@@ -538,6 +621,36 @@ export class StigmerClient {
     return this.workflowExecutionCommand.updateStatus(input);
   }
 
+  /**
+   * Deliver a named signal to another workflow execution through the
+   * server's SendSignal lane (validate → phase gate → relay via the
+   * outer orchestrator). This is the ONLY sanctioned path for
+   * runner-originated signals: a direct Temporal client would bypass
+   * both the authorization boundary and the payload-encryption design
+   * (per-identity runner keys make sender-side encryption fail closed
+   * at receivers holding a different key — see oss#517).
+   *
+   * Deliberately sends no idempotency_key: the server's dedupe claim is
+   * not released when delivery fails (oss#442), so a key here would
+   * poison the exact retry it exists to protect — and emit envelope ids
+   * regenerate per activity attempt anyway. Revisit once oss#442 lands.
+   */
+  async sendWorkflowSignal(
+    executionId: string,
+    signalName: string,
+    payload: JsonObject | undefined,
+    options?: { timeoutMs?: number },
+  ): Promise<WorkflowExecution> {
+    const input = create(SendSignalInputSchema, {
+      executionId,
+      signalName,
+      payload,
+    });
+    return this.workflowExecutionCommand.sendSignal(input, {
+      timeoutMs: options?.timeoutMs,
+    });
+  }
+
   async getWorkflowExecution(executionId: string): Promise<WorkflowExecution> {
     return this.workflowExecutionQuery.get({ value: executionId });
   }

package/src/encryption/config.ts

@@ -0,0 +1,155 @@
+/**
+ * Payload-encryption configuration (stigmer-cloud#227, stigmer#398).
+ *
+ * Two key sources, strict precedence:
+ *
+ *   1. Environment (STIGMER_PAYLOAD_ENCRYPTION_KEY(_ID)) — the operator's
+ *      explicit choice: self-hosted deployments sharing one key with their
+ *      server, and cloud sandboxes injected with the platform key. When the
+ *      env key is set, bootstrap-delivered material is ignored entirely.
+ *   2. Bootstrap-delivered — server-managed per-identity keys handed to
+ *      desktop-class runners by getRunnerBootstrapConfig. Held in memory
+ *      only; persistence lives server-side, which is what makes Temporal
+ *      replay work across runner restarts (every boot re-fetches the SAME
+ *      key).
+ *
+ * Encryption is enabled iff a key is present from either source — 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 (or a server that minted one) 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 the
+ * secondary pair while new payloads are written under the primary key.
+ * Workers capture keys at construction, so a rotated bootstrap key lands
+ * on the next runner boot — there is no live re-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;
+}
+
+/**
+ * Server-managed key material delivered by getRunnerBootstrapConfig.
+ * Structurally mirrors {@link BootstrapPayloadEncryptionKeys} in
+ * stigmer-client.ts — declared here so this leaf module stays free of
+ * client imports.
+ */
+export interface BootstrapKeyMaterial {
+  readonly key: string;
+  readonly keyId?: string;
+  readonly secondaryKey?: string;
+  readonly secondaryKeyId?: string;
+}
+
+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).
+ *
+ * Source precedence: the env key wins outright; bootstrap-delivered
+ * material applies only when no env key is set (see the module doc).
+ *
+ * @throws when a key is present but malformed, or a key id is missing —
+ *   key misconfiguration must stop the boot, not degrade to plaintext.
+ *   This applies equally to bootstrap material: a server that hands out
+ *   a bad key or omits its id has broken the protocol contract, and
+ *   running plaintext against a server that manages keys would silently
+ *   defeat the feature.
+ */
+export function loadPayloadEncryptionConfig(
+  bootstrap?: BootstrapKeyMaterial,
+): PayloadEncryptionConfig | undefined {
+  const rawKey = process.env[KEY_ENV];
+  if (rawKey) {
+    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 };
+  }
+
+  if (bootstrap?.key) {
+    const primary: EncryptionKey = {
+      keyId: requireBootstrapKeyId(bootstrap.keyId, "payload_encryption_key_id"),
+      key: parseKey(bootstrap.key, "bootstrap payload_encryption_key"),
+    };
+
+    const secondary: EncryptionKey | undefined = bootstrap.secondaryKey
+      ? {
+          keyId: requireBootstrapKeyId(
+            bootstrap.secondaryKeyId,
+            "payload_encryption_secondary_key_id",
+          ),
+          key: parseKey(bootstrap.secondaryKey, "bootstrap payload_encryption_secondary_key"),
+        }
+      : undefined;
+
+    return { primary, secondary };
+  }
+
+  return undefined;
+}
+
+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 requireBootstrapKeyId(keyId: string | undefined, fieldName: string): string {
+  if (!keyId) {
+    throw new Error(
+      `Runner bootstrap returned a payload encryption key without its ${fieldName} — ` +
+        `refusing to encrypt under an unidentified key (server contract violation)`,
+    );
+  }
+  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";