@stigmer/temporal-codecs 3.12.9

package/src/__tests__/claimcheck-codec.test.ts

@@ -0,0 +1,256 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { ClaimcheckPayloadCodec } from "../claimcheck/payload-codec.js";
+import { compress } from "../claimcheck/compressor.js";
+import type { ClaimcheckConfig } from "../claimcheck/config.js";
+import { makeInMemoryClaimcheckStorage } from "../__test-utils__/fake-claimcheck-storage.js";
+import type { Payload } from "@temporalio/common";
+
+function makeConfig(overrides: Partial<ClaimcheckConfig> = {}): ClaimcheckConfig {
+  return {
+    enabled: true,
+    thresholdBytes: 1024,
+    compressionEnabled: true,
+    keyPrefix: "claimcheck/",
+    ...overrides,
+  };
+}
+
+function makeStorage() {
+  // The canonical in-memory double; `uploads` aliases its backing Map so the
+  // existing `storage.uploads.*` assertions keep working, and `download` reads
+  // straight from what `encode` uploaded (no fetch to stub).
+  const { storage, blobs } = makeInMemoryClaimcheckStorage();
+  return Object.assign(storage, { uploads: blobs });
+}
+
+function makePayload(data: string | Buffer): Payload {
+  const buf = typeof data === "string" ? Buffer.from(data) : data;
+  return {
+    metadata: { encoding: Buffer.from("binary/plain") },
+    data: buf,
+  };
+}
+
+function makeLargePayload(sizeBytes: number): Payload {
+  const buf = Buffer.alloc(sizeBytes, "x");
+  return {
+    metadata: { encoding: Buffer.from("binary/plain") },
+    data: buf,
+  };
+}
+
+describe("ClaimcheckPayloadCodec", () => {
+  let storage: ReturnType<typeof makeStorage>;
+  let codec: ClaimcheckPayloadCodec;
+
+  beforeEach(() => {
+    storage = makeStorage();
+    codec = new ClaimcheckPayloadCodec(storage, makeConfig());
+  });
+
+  describe("encode", () => {
+    it("passes through payloads below threshold unchanged", async () => {
+      const payload = makePayload("small data");
+      const [result] = await codec.encode([payload]);
+      expect(result).toBe(payload);
+      expect(storage.uploads.size).toBe(0);
+    });
+
+    it("passes through empty payloads", async () => {
+      const payload: Payload = { metadata: {}, data: undefined };
+      const [result] = await codec.encode([payload]);
+      expect(result).toBe(payload);
+    });
+
+    it("offloads payloads at or above threshold", async () => {
+      const payload = makeLargePayload(1024);
+      const [result] = await codec.encode([payload]);
+
+      expect(result).not.toBe(payload);
+      expect(storage.uploads.size).toBe(1);
+
+      const markerMeta = result.metadata?.["encoding"];
+      expect(Buffer.from(markerMeta!).toString()).toBe("binary/claimcheck");
+
+      const marker = JSON.parse(Buffer.from(result.data!).toString());
+      expect(marker.key).toMatch(/^claimcheck\//);
+      expect(marker.size).toBe(1024);
+      expect(marker.compressed).toBe(true);
+    });
+
+    it("skips compression when it does not reduce size", async () => {
+      const randomBuf = Buffer.from(
+        Array.from({ length: 1024 }, () => Math.floor(Math.random() * 256)),
+      );
+      const payload: Payload = {
+        metadata: { encoding: Buffer.from("binary/plain") },
+        data: randomBuf,
+      };
+
+      const compressedSize = compress(randomBuf).length;
+      if (compressedSize >= randomBuf.length) {
+        const [result] = await codec.encode([payload]);
+        const marker = JSON.parse(Buffer.from(result.data!).toString());
+        expect(marker.compressed).toBe(false);
+
+        const uploaded = storage.uploads.values().next().value!;
+        expect(uploaded.length).toBe(randomBuf.length);
+      }
+    });
+
+    it("does not compress when compression is disabled", async () => {
+      codec = new ClaimcheckPayloadCodec(
+        storage,
+        makeConfig({ compressionEnabled: false }),
+      );
+      const payload = makeLargePayload(1024);
+      const [result] = await codec.encode([payload]);
+
+      const marker = JSON.parse(Buffer.from(result.data!).toString());
+      expect(marker.compressed).toBe(false);
+
+      const uploaded = storage.uploads.values().next().value!;
+      expect(uploaded.length).toBe(1024);
+    });
+
+    it("handles multiple payloads in a batch", async () => {
+      const small = makePayload("tiny");
+      const large = makeLargePayload(2048);
+
+      const results = await codec.encode([small, large]);
+      expect(results[0]).toBe(small);
+      expect(results[1]).not.toBe(large);
+      expect(storage.uploads.size).toBe(1);
+    });
+
+    it("uses configured key prefix", async () => {
+      codec = new ClaimcheckPayloadCodec(
+        storage,
+        makeConfig({ keyPrefix: "custom-prefix/" }),
+      );
+      const payload = makeLargePayload(1024);
+      const [result] = await codec.encode([payload]);
+
+      const marker = JSON.parse(Buffer.from(result.data!).toString());
+      expect(marker.key).toMatch(/^custom-prefix\//);
+    });
+  });
+
+  describe("decode", () => {
+    it("passes through non-claimcheck payloads unchanged", async () => {
+      const payload = makePayload("normal data");
+      const [result] = await codec.decode([payload]);
+      expect(result).toBe(payload);
+    });
+
+    it("retrieves and decompresses offloaded payloads (round-trip)", async () => {
+      const original = makeLargePayload(2048);
+      const [encoded] = await codec.encode([original]);
+
+      // decode reads back through storage.download from what encode uploaded.
+      const [decoded] = await codec.decode([encoded]);
+      expect(Buffer.from(decoded.data!)).toEqual(original.data);
+    });
+
+    it("restores the original payload metadata (round-trip)", async () => {
+      // The restored payload must carry its ORIGINAL encoding, not the
+      // marker's binary/claimcheck — otherwise no payload converter can
+      // interpret it and composition with the encryption codec breaks.
+      const original: Payload = {
+        metadata: {
+          encoding: Buffer.from("json/plain"),
+          "custom-key": Buffer.from("custom-value"),
+        },
+        data: Buffer.alloc(2048, "y"),
+      };
+
+      const [encoded] = await codec.encode([original]);
+      const [decoded] = await codec.decode([encoded]);
+
+      expect(Buffer.from(decoded.metadata!["encoding"]!).toString()).toBe("json/plain");
+      expect(Buffer.from(decoded.metadata!["custom-key"]!).toString()).toBe("custom-value");
+      expect(Buffer.from(decoded.data!)).toEqual(original.data);
+    });
+
+    it("decodes legacy markers written before metadata preservation", async () => {
+      const original = makeLargePayload(2048);
+      const [encoded] = await codec.encode([original]);
+
+      // Simulate a pre-fix marker: strip the metadata field.
+      const marker = JSON.parse(Buffer.from(encoded.data!).toString());
+      delete marker.metadata;
+      const legacy: Payload = {
+        metadata: encoded.metadata,
+        data: Buffer.from(JSON.stringify(marker)),
+      };
+
+      const [decoded] = await codec.decode([legacy]);
+      expect(Buffer.from(decoded.data!)).toEqual(original.data);
+    });
+
+    it("retrieves uncompressed payloads correctly", async () => {
+      codec = new ClaimcheckPayloadCodec(
+        storage,
+        makeConfig({ compressionEnabled: false }),
+      );
+
+      const original = makeLargePayload(1500);
+      const [encoded] = await codec.encode([original]);
+
+      const [decoded] = await codec.decode([encoded]);
+      expect(Buffer.from(decoded.data!)).toEqual(original.data);
+    });
+
+    it("wraps a download failure with the claimcheck error contract", async () => {
+      const encoded: Payload = {
+        metadata: { encoding: Buffer.from("binary/claimcheck") },
+        data: Buffer.from(JSON.stringify({
+          key: "claimcheck/missing",
+          size: 100,
+          compressed: false,
+        })),
+      };
+
+      // Drive the failure through the port; the proxy download surfaces the HTTP
+      // status, which the codec must preserve in its wrapped, key-scoped message.
+      storage.download.mockRejectedValueOnce(
+        new Error("Artifact download failed (HTTP 404) for key 'claimcheck/missing'"),
+      );
+
+      await expect(codec.decode([encoded])).rejects.toThrow(
+        /Claimcheck retrieve failed for key claimcheck\/missing.*HTTP 404/,
+      );
+    });
+  });
+
+  describe("threshold boundary", () => {
+    it("does NOT offload at threshold - 1", async () => {
+      const payload = makeLargePayload(1023);
+      const [result] = await codec.encode([payload]);
+      expect(result).toBe(payload);
+    });
+
+    it("offloads at exactly threshold", async () => {
+      const payload = makeLargePayload(1024);
+      const [result] = await codec.encode([payload]);
+      expect(result).not.toBe(payload);
+    });
+
+    it("offloads above threshold", async () => {
+      const payload = makeLargePayload(1025);
+      const [result] = await codec.encode([payload]);
+      expect(result).not.toBe(payload);
+    });
+  });
+
+  describe("compressor", () => {
+    it("compresses and decompresses correctly", async () => {
+      const { compress: c, decompress: d } = await import("../claimcheck/compressor.js");
+      const input = Buffer.from("hello world ".repeat(100));
+      const compressed = c(input);
+      expect(compressed.length).toBeLessThan(input.length);
+      const decompressed = d(compressed);
+      expect(decompressed).toEqual(input);
+    });
+  });
+});

package/src/__tests__/encryption-codec.test.ts

@@ -0,0 +1,292 @@
+/**
+ * Unit tests for the payload-encryption codec (stigmer-cloud#227).
+ *
+ * Covers the codec in isolation, its composition with the claim-check
+ * codec (order is load-bearing: encrypt before relocate, so object
+ * storage only ever sees ciphertext), the config loader's fail-fast
+ * contract, and the committed cross-language conformance fixture that
+ * pins the envelope format the Java decode-only codec (stigmer-cloud
+ * temporal-starter) must match.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Payload } from "@temporalio/common";
+import { EncryptionPayloadCodec } from "../encryption/payload-codec.js";
+import { loadPayloadEncryptionConfig } from "../encryption/config.js";
+import type { PayloadEncryptionConfig } from "../encryption/config.js";
+import { ClaimcheckPayloadCodec } from "../claimcheck/payload-codec.js";
+import { makeInMemoryClaimcheckStorage } from "../__test-utils__/fake-claimcheck-storage.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function makeKeyConfig(overrides: Partial<PayloadEncryptionConfig> = {}): PayloadEncryptionConfig {
+  return {
+    primary: { keyId: "test-key-1", key: randomBytes(32) },
+    ...overrides,
+  };
+}
+
+function makeJsonPayload(value: unknown): Payload {
+  return {
+    metadata: { encoding: Buffer.from("json/plain") },
+    data: Buffer.from(JSON.stringify(value)),
+  };
+}
+
+function metadataString(payload: Payload, key: string): string | undefined {
+  const bytes = payload.metadata?.[key];
+  return bytes ? Buffer.from(bytes).toString("utf-8") : undefined;
+}
+
+describe("EncryptionPayloadCodec", () => {
+  it("round-trips a payload, restoring metadata and data exactly", async () => {
+    const codec = new EncryptionPayloadCodec(makeKeyConfig());
+    const original = makeJsonPayload({ secret: "s3cret-value" });
+
+    const [encoded] = await codec.encode([original]);
+    expect(metadataString(encoded, "encoding")).toBe("binary/encrypted");
+    expect(metadataString(encoded, "encryption-key-id")).toBe("test-key-1");
+    expect(Buffer.from(encoded.data!).includes("s3cret-value")).toBe(false);
+
+    const [decoded] = await codec.decode([encoded]);
+    expect(metadataString(decoded, "encoding")).toBe("json/plain");
+    expect(Buffer.from(decoded.data!)).toEqual(original.data);
+  });
+
+  it("passes through payloads it did not encode", async () => {
+    const codec = new EncryptionPayloadCodec(makeKeyConfig());
+    const plaintext = makeJsonPayload({ from: "java-orchestrator" });
+    const [decoded] = await codec.decode([plaintext]);
+    expect(decoded).toBe(plaintext);
+  });
+
+  it("skips data-less payloads on encode (binary/null void results)", async () => {
+    const codec = new EncryptionPayloadCodec(makeKeyConfig());
+    const nullPayload: Payload = {
+      metadata: { encoding: Buffer.from("binary/null") },
+      data: undefined,
+    };
+    const [encoded] = await codec.encode([nullPayload]);
+    expect(encoded).toBe(nullPayload);
+  });
+
+  it("fails closed on tampered ciphertext", async () => {
+    const codec = new EncryptionPayloadCodec(makeKeyConfig());
+    const [encoded] = await codec.encode([makeJsonPayload({ a: 1 })]);
+
+    const tampered = Buffer.from(encoded.data!);
+    tampered[tampered.length - 1] ^= 0xff;
+
+    await expect(
+      codec.decode([{ metadata: encoded.metadata, data: tampered }]),
+    ).rejects.toThrow(/corrupt or the configured key does not match/);
+  });
+
+  it("fails closed on an unknown key id", async () => {
+    const writer = new EncryptionPayloadCodec(makeKeyConfig());
+    const [encoded] = await writer.encode([makeJsonPayload({ a: 1 })]);
+
+    const reader = new EncryptionPayloadCodec(
+      makeKeyConfig({ primary: { keyId: "other-key", key: randomBytes(32) } }),
+    );
+    await expect(reader.decode([encoded])).rejects.toThrow(
+      /unknown key id 'test-key-1'/,
+    );
+  });
+
+  it("fails closed when the key id metadata is missing", async () => {
+    const codec = new EncryptionPayloadCodec(makeKeyConfig());
+    const [encoded] = await codec.encode([makeJsonPayload({ a: 1 })]);
+
+    const stripped: Payload = {
+      metadata: { encoding: Buffer.from("binary/encrypted") },
+      data: encoded.data,
+    };
+    await expect(codec.decode([stripped])).rejects.toThrow(
+      /missing its encryption-key-id/,
+    );
+  });
+
+  it("decodes payloads written under the secondary key (rotation window)", async () => {
+    const oldKey = { keyId: "2026-01", key: randomBytes(32) };
+    const writer = new EncryptionPayloadCodec({ primary: oldKey });
+    const [encoded] = await writer.encode([makeJsonPayload({ rotated: true })]);
+
+    const rotatedReader = new EncryptionPayloadCodec({
+      primary: { keyId: "2026-08", key: randomBytes(32) },
+      secondary: oldKey,
+    });
+    const [decoded] = await rotatedReader.decode([encoded]);
+    expect(JSON.parse(Buffer.from(decoded.data!).toString())).toEqual({ rotated: true });
+  });
+});
+
+describe("composition with claim-check (encrypt, then relocate)", () => {
+  it("stores only ciphertext in object storage and round-trips exactly", async () => {
+    const { storage, blobs } = makeInMemoryClaimcheckStorage();
+    const encryption = new EncryptionPayloadCodec(makeKeyConfig());
+    const claimcheck = new ClaimcheckPayloadCodec(storage, {
+      enabled: true,
+      thresholdBytes: 128,
+      compressionEnabled: false,
+      keyPrefix: "claimcheck/",
+    });
+
+    const secret = "very-large-and-very-secret-".repeat(32);
+    const original = makeJsonPayload({ secret });
+
+    // Temporal applies codec arrays in order on encode, reverse on decode.
+    const [encrypted] = await encryption.encode([original]);
+    const [relocated] = await claimcheck.encode([encrypted]);
+    expect(metadataString(relocated, "encoding")).toBe("binary/claimcheck");
+
+    expect(blobs.size).toBe(1);
+    const blob: Buffer = blobs.values().next().value!;
+    expect(blob.includes("very-large-and-very-secret-")).toBe(false);
+
+    const [restored] = await claimcheck.decode([relocated]);
+    const [decrypted] = await encryption.decode([restored]);
+    expect(metadataString(decrypted, "encoding")).toBe("json/plain");
+    expect(Buffer.from(decrypted.data!)).toEqual(original.data);
+  });
+});
+
+describe("loadPayloadEncryptionConfig", () => {
+  const ENV_VARS = [
+    "STIGMER_PAYLOAD_ENCRYPTION_KEY",
+    "STIGMER_PAYLOAD_ENCRYPTION_KEY_ID",
+    "STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY",
+    "STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY_ID",
+  ];
+
+  // Consumers inject their secret custody (see SecretReader); a plain env
+  // read is exactly what these tests exercised before the extraction, when
+  // the runner's getRunnerSecret fell back to process.env with no capture.
+  const readEnv = (name: string) => process.env[name];
+
+  afterEach(() => {
+    for (const name of ENV_VARS) delete process.env[name];
+  });
+
+  it("returns undefined when no key is configured", () => {
+    expect(loadPayloadEncryptionConfig(readEnv)).toBeUndefined();
+  });
+
+  it("loads primary and secondary keys", () => {
+    process.env.STIGMER_PAYLOAD_ENCRYPTION_KEY = randomBytes(32).toString("base64");
+    process.env.STIGMER_PAYLOAD_ENCRYPTION_KEY_ID = "k2";
+    process.env.STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY = randomBytes(32).toString("base64");
+    process.env.STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY_ID = "k1";
+
+    const config = loadPayloadEncryptionConfig(readEnv);
+    expect(config?.primary.keyId).toBe("k2");
+    expect(config?.primary.key.length).toBe(32);
+    expect(config?.secondary?.keyId).toBe("k1");
+  });
+
+  it("fails the boot when a key is set without an id", () => {
+    process.env.STIGMER_PAYLOAD_ENCRYPTION_KEY = randomBytes(32).toString("base64");
+    expect(() => loadPayloadEncryptionConfig(readEnv)).toThrow(
+      /STIGMER_PAYLOAD_ENCRYPTION_KEY_ID is required/,
+    );
+  });
+
+  it("fails the boot on a key of the wrong length", () => {
+    process.env.STIGMER_PAYLOAD_ENCRYPTION_KEY = randomBytes(16).toString("base64");
+    process.env.STIGMER_PAYLOAD_ENCRYPTION_KEY_ID = "k1";
+    expect(() => loadPayloadEncryptionConfig(readEnv)).toThrow(/must decode to 32 bytes/);
+  });
+
+  // Server-managed key material from getRunnerBootstrapConfig (stigmer#398):
+  // desktop-class runners receive a per-identity key at bootstrap instead of
+  // env config. The env key is the operator's explicit choice and must win.
+  describe("bootstrap-delivered keys", () => {
+    const bootstrapKeys = () => ({
+      key: randomBytes(32).toString("base64"),
+      keyId: "identity-key-v1",
+      secondaryKey: randomBytes(32).toString("base64"),
+      secondaryKeyId: "identity-key-v0",
+    });
+
+    it("enables encryption from bootstrap material when no env key is set", () => {
+      const config = loadPayloadEncryptionConfig(readEnv, bootstrapKeys());
+      expect(config?.primary.keyId).toBe("identity-key-v1");
+      expect(config?.primary.key.length).toBe(32);
+      expect(config?.secondary?.keyId).toBe("identity-key-v0");
+    });
+
+    it("env-configured key wins over bootstrap material", () => {
+      process.env.STIGMER_PAYLOAD_ENCRYPTION_KEY = randomBytes(32).toString("base64");
+      process.env.STIGMER_PAYLOAD_ENCRYPTION_KEY_ID = "env-key";
+
+      const config = loadPayloadEncryptionConfig(readEnv, bootstrapKeys());
+      expect(config?.primary.keyId).toBe("env-key");
+      expect(config?.secondary).toBeUndefined();
+    });
+
+    it("fails the boot on a bootstrap key without its id (server contract violation)", () => {
+      expect(() =>
+        loadPayloadEncryptionConfig(readEnv, { key: randomBytes(32).toString("base64") }),
+      ).toThrow(/payload_encryption_key_id/);
+    });
+
+    it("fails the boot on a malformed bootstrap key rather than running plaintext", () => {
+      expect(() =>
+        loadPayloadEncryptionConfig(readEnv, {
+          key: randomBytes(16).toString("base64"),
+          keyId: "identity-key-v1",
+        }),
+      ).toThrow(/must decode to 32 bytes/);
+    });
+
+    it("fails the boot on a bootstrap secondary key without its id", () => {
+      expect(() =>
+        loadPayloadEncryptionConfig(readEnv, {
+          key: randomBytes(32).toString("base64"),
+          keyId: "identity-key-v1",
+          secondaryKey: randomBytes(32).toString("base64"),
+        }),
+      ).toThrow(/payload_encryption_secondary_key_id/);
+    });
+  });
+});
+
+describe("cross-language conformance fixture", () => {
+  // The committed fixture pins the envelope as a wire contract. A copy
+  // lives in stigmer-cloud (temporal-starter test resources) where the
+  // Java decode-only codec must decrypt it to the same payload. Never
+  // regenerate it casually: changing the fixture means changing the
+  // cross-SDK envelope, which requires both implementations to move in
+  // lockstep.
+  it("decrypts the committed fixture to the expected payload", async () => {
+    const fixture = JSON.parse(
+      readFileSync(join(__dirname, "fixtures", "encrypted-payload-fixture.json"), "utf-8"),
+    );
+
+    const codec = new EncryptionPayloadCodec({
+      primary: {
+        keyId: fixture.keyId,
+        key: Buffer.from(fixture.keyBase64, "base64"),
+      },
+    });
+
+    const encrypted: Payload = {
+      metadata: Object.fromEntries(
+        Object.entries(fixture.encrypted.metadataBase64 as Record<string, string>).map(
+          ([k, v]) => [k, Buffer.from(v, "base64")],
+        ),
+      ),
+      data: Buffer.from(fixture.encrypted.dataBase64, "base64"),
+    };
+
+    const [decoded] = await codec.decode([encrypted]);
+    expect(metadataString(decoded, "encoding")).toBe("json/plain");
+    expect(Buffer.from(decoded.data!).toString("utf-8")).toBe(
+      fixture.original.dataJson,
+    );
+  });
+});

package/src/__tests__/fixtures/encrypted-payload-fixture.json

@@ -0,0 +1,15 @@
+{
+  "description": "Cross-language conformance fixture for the Temporal payload-encryption envelope (stigmer-cloud#227). data = iv(12) || AES-256-GCM ciphertext || tag(16); plaintext is the serialized original Payload proto. The TS codec (stigmer OSS runner) and the Java decode-only codec (stigmer-cloud temporal-starter) must both decrypt this to original.dataJson with encoding json/plain. The key is TEST-ONLY. Do not regenerate without moving both implementations in lockstep.",
+  "keyId": "conformance-2026-08-11",
+  "keyBase64": "LwN0jDzOwm0aPH8lyRRqsTMali/7RAgKKB9CY6psNFw=",
+  "encrypted": {
+    "metadataBase64": {
+      "encoding": "YmluYXJ5L2VuY3J5cHRlZA==",
+      "encryption-key-id": "Y29uZm9ybWFuY2UtMjAyNi0wOC0xMQ=="
+    },
+    "dataBase64": "CzL44tAoZwoawET5ApaDKGLYcJO2P8eTPS4hZnoEOUvZ7jkD5mkCnD9krgY9etYWO+06y779i8xRCs7QrnOKo5xo74HtlY0bwxYjr2dOra9TGRbtv3PlrW+DcfmEFAQ3Efem"
+  },
+  "original": {
+    "dataJson": "{\"secret\":\"cross-language-conformance-value\"}"
+  }
+}

package/src/claimcheck/compressor.ts

@@ -0,0 +1,19 @@
+/**
+ * Gzip helpers for claim-checked blobs. Synchronous by design: the codec
+ * runs on the Temporal worker's payload path where the blobs are bounded
+ * by the claim-check threshold, and gzip's format is part of the marker
+ * contract (`compressed: true` blobs must gunzip on any consumer).
+ *
+ * Moved from backend/services/runner/src/claimcheck/compressor.ts when the
+ * codecs became @stigmer/temporal-codecs.
+ */
+
+import { gzipSync, gunzipSync } from "node:zlib";
+
+export function compress(data: Buffer): Buffer<ArrayBuffer> {
+  return gzipSync(data) as Buffer<ArrayBuffer>;
+}
+
+export function decompress(data: Buffer): Buffer<ArrayBuffer> {
+  return gunzipSync(data) as Buffer<ArrayBuffer>;
+}

package/src/claimcheck/config.ts

@@ -0,0 +1,30 @@
+/**
+ * Claim-check configuration, env-driven with an enabled-iff-configured
+ * gate (CLAIMCHECK_ENABLED) — unlike encryption, the offload threshold and
+ * key prefix are operational tuning, not secrets, so plain env reads are
+ * the whole policy.
+ *
+ * Moved from backend/services/runner/src/claimcheck/config.ts when the
+ * codecs became @stigmer/temporal-codecs.
+ */
+
+export interface ClaimcheckConfig {
+  readonly enabled: boolean;
+  readonly thresholdBytes: number;
+  readonly compressionEnabled: boolean;
+  readonly keyPrefix: string;
+}
+
+const DEFAULT_THRESHOLD_BYTES = 128 * 1024; // 128KB
+
+export function loadClaimcheckConfig(): ClaimcheckConfig {
+  return {
+    enabled: process.env.CLAIMCHECK_ENABLED === "true",
+    thresholdBytes: parseInt(
+      process.env.CLAIMCHECK_THRESHOLD_BYTES ?? String(DEFAULT_THRESHOLD_BYTES),
+      10,
+    ),
+    compressionEnabled: process.env.CLAIMCHECK_COMPRESSION_ENABLED !== "false",
+    keyPrefix: process.env.CLAIMCHECK_KEY_PREFIX ?? "claimcheck/",
+  };
+}