@stigmer/temporal-codecs 0.1.0-dev.20261017020314.g644422724c27

package/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @stigmer/temporal-codecs — the Temporal plumbing Stigmer's TypeScript
+ * Temporal processes (the server and the runner) share: payload codecs,
+ * and the connection-security settings every Temporal connection reads
+ * (`connection/config.ts`). The encryption envelope is a cross-language
+ * wire contract (the Java decode-only codec in stigmer-cloud's
+ * temporal-starter must match it byte-for-byte, pinned by the fixture in
+ * src/__tests__/fixtures/), and the connection settings must mean the same
+ * on every connection, which is why both live in one library instead of
+ * per-consumer copies that could fork.
+ *
+ * This is the package's ONLY public boundary. Codec order at the consumer
+ * is a correctness property: install [encryption, claimcheck] so encode
+ * encrypts before relocating (object storage only ever sees ciphertext)
+ * and decode restores the blob before decrypting.
+ *
+ * Dependency policy: @temporalio/common and @temporalio/proto are pinned
+ * exact and identical to the runner's pins, bumped in lockstep with it —
+ * the runner's consumer-install gate (stigmer#786) fails any version mix
+ * because a split @temporalio/proto tree registers the core-sdk protobuf
+ * namespace twice and crashes worker init.
+ */
+export { EncryptionPayloadCodec } from "./encryption/payload-codec.js";
+export { loadPayloadEncryptionConfig } from "./encryption/config.js";
+export type { BootstrapKeyMaterial, EncryptionKey, PayloadEncryptionConfig, PayloadKeyResolver, SecretReader, } from "./encryption/config.js";
+export { loadTemporalConnectionConfig, temporalConnectionEnv, TEMPORAL_API_KEY_ENV, TEMPORAL_CONNECTION_ENV_NAMES, TEMPORAL_TLS_CLIENT_KEY_DATA_ENV, } from "./connection/config.js";
+export type { TemporalConnectionConfig, TemporalTls, } from "./connection/config.js";
+export { ClaimcheckPayloadCodec } from "./claimcheck/payload-codec.js";
+export { loadClaimcheckConfig } from "./claimcheck/config.js";
+export type { ClaimcheckConfig } from "./claimcheck/config.js";
+export type { ClaimcheckStorage } from "./claimcheck/storage.js";
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AACrE,YAAY,EACV,oBAAoB,EACpB,aAAa,EACb,uBAAuB,EACvB,kBAAkB,EAClB,YAAY,GACb,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,4BAA4B,EAC5B,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,wBAAwB,EACxB,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC"}

package/index.js

@@ -0,0 +1,28 @@
+/**
+ * @stigmer/temporal-codecs — the Temporal plumbing Stigmer's TypeScript
+ * Temporal processes (the server and the runner) share: payload codecs,
+ * and the connection-security settings every Temporal connection reads
+ * (`connection/config.ts`). The encryption envelope is a cross-language
+ * wire contract (the Java decode-only codec in stigmer-cloud's
+ * temporal-starter must match it byte-for-byte, pinned by the fixture in
+ * src/__tests__/fixtures/), and the connection settings must mean the same
+ * on every connection, which is why both live in one library instead of
+ * per-consumer copies that could fork.
+ *
+ * This is the package's ONLY public boundary. Codec order at the consumer
+ * is a correctness property: install [encryption, claimcheck] so encode
+ * encrypts before relocating (object storage only ever sees ciphertext)
+ * and decode restores the blob before decrypting.
+ *
+ * Dependency policy: @temporalio/common and @temporalio/proto are pinned
+ * exact and identical to the runner's pins, bumped in lockstep with it —
+ * the runner's consumer-install gate (stigmer#786) fails any version mix
+ * because a split @temporalio/proto tree registers the core-sdk protobuf
+ * namespace twice and crashes worker init.
+ */
+export { EncryptionPayloadCodec } from "./encryption/payload-codec.js";
+export { loadPayloadEncryptionConfig } from "./encryption/config.js";
+export { loadTemporalConnectionConfig, temporalConnectionEnv, TEMPORAL_API_KEY_ENV, TEMPORAL_CONNECTION_ENV_NAMES, TEMPORAL_TLS_CLIENT_KEY_DATA_ENV, } from "./connection/config.js";
+export { ClaimcheckPayloadCodec } from "./claimcheck/payload-codec.js";
+export { loadClaimcheckConfig } from "./claimcheck/config.js";
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AASrE,OAAO,EACL,4BAA4B,EAC5B,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,wBAAwB,CAAC;AAMhC,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@stigmer/temporal-codecs",
+  "version": "0.1.0-dev.20261017020314.g644422724c27",
+  "description": "The Temporal plumbing Stigmer's TypeScript Temporal processes share — AES-256-GCM payload encryption and claim-check offloading (the one home for the cross-language envelope contract), and the connection-security settings every Temporal connection reads",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stigmer/stigmer.git",
+    "directory": "backend/libs/ts/temporal-codecs"
+  },
+  "engines": {
+    "node": "^22.13.0 || >=23.4.0"
+  },
+  "keywords": [
+    "stigmer",
+    "temporal",
+    "payload-codec",
+    "encryption",
+    "claim-check",
+    "tls"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./connection": {
+      "types": "./connection/config.d.ts",
+      "import": "./connection/config.js",
+      "default": "./connection/config.js"
+    }
+  },
+  "dependencies": {
+    "@temporalio/common": "1.16.2",
+    "@temporalio/proto": "1.16.2"
+  }
+}

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/",
+  };
+}

package/src/claimcheck/payload-codec.ts

@@ -0,0 +1,144 @@
+/**
+ * Temporal PayloadCodec that transparently offloads large payloads to
+ * external storage ({@link ClaimcheckStorage}). Payloads below the
+ * threshold pass through unchanged. Payloads at or above the threshold
+ * are compressed (optional), uploaded, and replaced with a small
+ * reference marker.
+ *
+ * On decode, markers are detected, the original payload is downloaded
+ * and decompressed, and the original bytes are restored — transparent
+ * to workflow/activity code.
+ *
+ * Moved from backend/services/runner/src/claimcheck/payload-codec.ts when
+ * the codecs became @stigmer/temporal-codecs (one home for the
+ * cross-language envelope contract; the TS server is the second consumer).
+ */
+
+import { randomUUID } from "node:crypto";
+import type { Payload, PayloadCodec } from "@temporalio/common";
+import type { ClaimcheckStorage } from "./storage.js";
+import type { ClaimcheckConfig } from "./config.js";
+import { compress, decompress } from "./compressor.js";
+
+const MARKER_METADATA_KEY = "encoding";
+const MARKER_ENCODING_VALUE = "binary/claimcheck";
+
+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 {
+  constructor(
+    private readonly storage: ClaimcheckStorage,
+    private readonly config: ClaimcheckConfig,
+  ) {}
+
+  async encode(payloads: Payload[]): Promise<Payload[]> {
+    return Promise.all(payloads.map((p) => this.encodePayload(p)));
+  }
+
+  async decode(payloads: Payload[]): Promise<Payload[]> {
+    return Promise.all(payloads.map((p) => this.decodePayload(p)));
+  }
+
+  private async encodePayload(payload: Payload): Promise<Payload> {
+    const data = payload.data;
+    if (!data || data.length < this.config.thresholdBytes) {
+      return payload;
+    }
+
+    const originalBuf = Buffer.from(data);
+    let uploadBuf = originalBuf;
+    let compressed = false;
+
+    if (this.config.compressionEnabled) {
+      const compressedBuf = compress(originalBuf);
+      if (compressedBuf.length < originalBuf.length) {
+        uploadBuf = compressedBuf;
+        compressed = true;
+      }
+    }
+
+    const key = `${this.config.keyPrefix}${randomUUID()}`;
+    await this.storage.upload(key, uploadBuf, "application/octet-stream");
+
+    const marker: ClaimcheckMarker = {
+      key,
+      size: data.length,
+      compressed,
+      metadata: serializeMetadata(payload.metadata),
+    };
+
+    return {
+      metadata: {
+        [MARKER_METADATA_KEY]: Buffer.from(MARKER_ENCODING_VALUE),
+      },
+      data: Buffer.from(JSON.stringify(marker)),
+    };
+  }
+
+  private async decodePayload(payload: Payload): Promise<Payload> {
+    if (!this.isClaimcheckPayload(payload)) {
+      return payload;
+    }
+
+    const marker: ClaimcheckMarker = JSON.parse(
+      Buffer.from(payload.data!).toString("utf-8"),
+    );
+
+    let rawBuf: Buffer;
+    try {
+      rawBuf = await this.storage.download(marker.key);
+    } catch (err) {
+      // Preserve the claimcheck-scoped error contract; the shared download error
+      // already carries the HTTP status (proxy) or the miss (local) as the cause.
+      const cause = err instanceof Error ? err.message : String(err);
+      throw new Error(`Claimcheck retrieve failed for key ${marker.key}: ${cause}`);
+    }
+    const dataBuf = marker.compressed ? decompress(rawBuf) : rawBuf;
+
+    return {
+      metadata: marker.metadata
+        ? deserializeMetadata(marker.metadata)
+        : payload.metadata,
+      data: dataBuf,
+    };
+  }
+
+  private isClaimcheckPayload(payload: Payload): boolean {
+    const encoding = payload.metadata?.[MARKER_METADATA_KEY];
+    if (!encoding) return false;
+    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/claimcheck/storage.ts

@@ -0,0 +1,19 @@
+/**
+ * The blob-store contract the claim-check codec needs — nothing more.
+ *
+ * Deliberately minimal (upload + download by key) so any consumer's
+ * storage client satisfies it structurally: the runner's ArtifactStorage
+ * (a richer interface with presigned-URL minting) matches as-is, and the
+ * TS server brings its own. Widening this port widens the wire contract's
+ * dependency surface for every consumer — do not add methods the codec
+ * itself does not call.
+ */
+export interface ClaimcheckStorage {
+  /** Store `content` under `key`; resolves once the blob is durable. */
+  upload(key: string, content: Buffer, contentType?: string): Promise<string>;
+  /**
+   * Return the exact bytes stored under `key`, or throw a descriptive,
+   * key-scoped `Error` when the object is missing or the transport fails.
+   */
+  download(key: string): Promise<Buffer>;
+}

package/src/connection/config.ts

@@ -0,0 +1,217 @@
+/**
+ * Temporal connection security: how a Stigmer process authenticates to the
+ * Temporal frontend it dials. The server's client and worker connections
+ * and the runner's worker connection all read it, so it lives here, in the
+ * one library both processes share. Unset means today's plaintext
+ * connection, unchanged.
+ *
+ * The settings (each `_PATH` item has a `_DATA` twin holding the PEM text):
+ *
+ *   STIGMER_TEMPORAL_API_KEY                    bearer key; implies TLS
+ *   STIGMER_TEMPORAL_TLS                        "true" or "1": TLS with the
+ *                                               system's trusted roots
+ *   STIGMER_TEMPORAL_TLS_SERVER_NAME            SNI / host-name override
+ *   STIGMER_TEMPORAL_TLS_SERVER_CA_CERT_PATH    the frontend's CA (implies TLS)
+ *   STIGMER_TEMPORAL_TLS_CLIENT_CERT_PATH       mutual TLS: the client's
+ *   STIGMER_TEMPORAL_TLS_CLIENT_KEY_PATH          certificate and key, together
+ *
+ * WHY Stigmer's own names, not Temporal's `TEMPORAL_API_KEY` and
+ * `TEMPORAL_TLS_*`: those belong to the user's own Temporal work. A local
+ * Stigmer (`stigmer up`) inherits the user's shell, and agents that build
+ * Temporal applications export `TEMPORAL_API_KEY` for their own namespaces.
+ * Reading it would present the user's key to Stigmer's own Temporal and,
+ * through the runner's secret custody, take it away from the agents that
+ * need it. The shape follows Temporal's so an operator recognises it.
+ *
+ * WHY not Temporal's reader (`@temporalio/envconfig`): at the SDK version
+ * every Stigmer package pins (1.16.2), it reads `TEMPORAL_TLS=true` as TLS
+ * disabled. Releases before 1.22.0 carry that inversion. It also ignores
+ * host-verification settings, and it reads the user's own Temporal profile
+ * file by default.
+ *
+ * Misconfiguration fails the boot, the posture of the payload-encryption
+ * config beside this module: an operator who set half a client pair, or
+ * the same item twice, believes the connection is authenticated, and a
+ * silently weaker connection would be a security failure. An empty value
+ * means unset, so a blank line in a deployment's environment turns nothing
+ * on.
+ *
+ * Values are read through an injected {@link SecretReader}, as the
+ * encryption keys are: secret custody is the consumer's policy. The runner
+ * passes its credential store's reader, so the API key and the client key
+ * never live in an environment its agent tools can read.
+ */
+
+import { readFileSync } from "node:fs";
+
+import type { SecretReader } from "../encryption/config.js";
+
+/**
+ * TLS settings in the Temporal SDK's own shape (`TLSConfig` in
+ * `@temporalio/common`), declared structurally so this library imports
+ * nothing internal. An empty object means TLS with the system's roots.
+ */
+export interface TemporalTls {
+  readonly serverNameOverride?: string;
+  readonly serverRootCACertificate?: Uint8Array;
+  readonly clientCertPair?: {
+    readonly crt: Uint8Array;
+    readonly key: Uint8Array;
+  };
+}
+
+/**
+ * What a connection needs beyond its address. Both fields are absent for a
+ * plaintext connection; spread it into `Connection.connect` or
+ * `NativeConnection.connect` as is.
+ */
+export interface TemporalConnectionConfig {
+  readonly tls?: TemporalTls;
+  readonly apiKey?: string;
+}
+
+export const TEMPORAL_API_KEY_ENV = "STIGMER_TEMPORAL_API_KEY";
+export const TEMPORAL_TLS_ENV = "STIGMER_TEMPORAL_TLS";
+export const TEMPORAL_TLS_SERVER_NAME_ENV = "STIGMER_TEMPORAL_TLS_SERVER_NAME";
+
+/** The PEM items, each settable as a file path or as its text. */
+const PEM_ITEMS = {
+  serverCa: "STIGMER_TEMPORAL_TLS_SERVER_CA_CERT",
+  clientCert: "STIGMER_TEMPORAL_TLS_CLIENT_CERT",
+  clientKey: "STIGMER_TEMPORAL_TLS_CLIENT_KEY",
+} as const;
+
+/**
+ * The `_DATA` name of the client key: a credential, which the runner takes
+ * into custody beside the API key (its `_PATH` twin names a file, not a
+ * secret).
+ */
+export const TEMPORAL_TLS_CLIENT_KEY_DATA_ENV = `${PEM_ITEMS.clientKey}_DATA`;
+
+/**
+ * Every setting name this module reads, exactly. A process that hands its
+ * children their own rendered settings ({@link temporalConnectionEnv})
+ * removes these from what the child inherits; other `STIGMER_TEMPORAL_*`
+ * names (the CLI's own) are not connection settings.
+ */
+export const TEMPORAL_CONNECTION_ENV_NAMES: readonly string[] = [
+  TEMPORAL_API_KEY_ENV,
+  TEMPORAL_TLS_ENV,
+  TEMPORAL_TLS_SERVER_NAME_ENV,
+  ...Object.values(PEM_ITEMS).flatMap((item) => [`${item}_PATH`, `${item}_DATA`]),
+];
+
+/**
+ * Loads the connection settings.
+ *
+ * @throws when a setting is contradictory or unreadable: a client
+ *   certificate without its key (or the reverse), both the `_PATH` and the
+ *   `_DATA` form of one item, a path that cannot be read, or a
+ *   `STIGMER_TEMPORAL_TLS` that is neither true nor false.
+ */
+export function loadTemporalConnectionConfig(
+  read: SecretReader,
+): TemporalConnectionConfig {
+  const value = (name: string): string | undefined => {
+    const raw = read(name);
+    return raw === undefined || raw.trim() === "" ? undefined : raw;
+  };
+
+  const apiKey = value(TEMPORAL_API_KEY_ENV)?.trim();
+  const tlsFlag = parseFlag(value(TEMPORAL_TLS_ENV));
+  const serverName = value(TEMPORAL_TLS_SERVER_NAME_ENV)?.trim();
+  const serverCa = readPem(PEM_ITEMS.serverCa, value);
+  const clientCert = readPem(PEM_ITEMS.clientCert, value);
+  const clientKey = readPem(PEM_ITEMS.clientKey, value);
+
+  if ((clientCert === undefined) !== (clientKey === undefined)) {
+    throw new Error(
+      `Temporal connection misconfigured: mutual TLS needs both ` +
+        `${PEM_ITEMS.clientCert}_* and ${PEM_ITEMS.clientKey}_* — set both or neither`,
+    );
+  }
+
+  const tlsRequested =
+    tlsFlag === true ||
+    apiKey !== undefined ||
+    serverName !== undefined ||
+    serverCa !== undefined ||
+    clientCert !== undefined;
+  if (tlsFlag === false && tlsRequested) {
+    throw new Error(
+      `Temporal connection misconfigured: ${TEMPORAL_TLS_ENV} is false while ` +
+        `an API key, a server name, a CA or a client certificate is set — ` +
+        `each of those needs TLS`,
+    );
+  }
+  if (!tlsRequested) return {};
+
+  const tls: TemporalTls = {
+    ...(serverName !== undefined ? { serverNameOverride: serverName } : {}),
+    ...(serverCa !== undefined ? { serverRootCACertificate: serverCa } : {}),
+    ...(clientCert !== undefined && clientKey !== undefined
+      ? { clientCertPair: { crt: clientCert, key: clientKey } }
+      : {}),
+  };
+  return { tls, ...(apiKey !== undefined ? { apiKey } : {}) };
+}
+
+/**
+ * Renders loaded settings back as the environment a child runner reads,
+ * every PEM item in its `_DATA` form, so that no file has to exist where
+ * the child runs. The server's sandbox drivers pass this to the runners
+ * they start. Round-trips: loading the rendered environment yields the
+ * same settings.
+ */
+export function temporalConnectionEnv(
+  config: TemporalConnectionConfig,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+  if (config.tls === undefined) return env;
+  env[TEMPORAL_TLS_ENV] = "true";
+  const text = (bytes: Uint8Array): string => Buffer.from(bytes).toString("utf8");
+  const { serverNameOverride, serverRootCACertificate, clientCertPair } = config.tls;
+  if (serverNameOverride !== undefined) env[TEMPORAL_TLS_SERVER_NAME_ENV] = serverNameOverride;
+  if (serverRootCACertificate !== undefined) {
+    env[`${PEM_ITEMS.serverCa}_DATA`] = text(serverRootCACertificate);
+  }
+  if (clientCertPair !== undefined) {
+    env[`${PEM_ITEMS.clientCert}_DATA`] = text(clientCertPair.crt);
+    env[TEMPORAL_TLS_CLIENT_KEY_DATA_ENV] = text(clientCertPair.key);
+  }
+  if (config.apiKey !== undefined) env[TEMPORAL_API_KEY_ENV] = config.apiKey;
+  return env;
+}
+
+function parseFlag(raw: string | undefined): boolean | undefined {
+  if (raw === undefined) return undefined;
+  const flag = raw.trim().toLowerCase();
+  if (flag === "true" || flag === "1") return true;
+  if (flag === "false" || flag === "0") return false;
+  throw new Error(
+    `Temporal connection misconfigured: ${TEMPORAL_TLS_ENV} must be true, 1, false or 0, got "${raw}"`,
+  );
+}
+
+function readPem(
+  item: string,
+  value: (name: string) => string | undefined,
+): Uint8Array | undefined {
+  const path = value(`${item}_PATH`);
+  const data = value(`${item}_DATA`);
+  if (path !== undefined && data !== undefined) {
+    throw new Error(
+      `Temporal connection misconfigured: set ${item}_PATH or ${item}_DATA, not both`,
+    );
+  }
+  if (data !== undefined) return Buffer.from(data, "utf8");
+  if (path === undefined) return undefined;
+  try {
+    return readFileSync(path.trim());
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Temporal connection misconfigured: ${item}_PATH "${path.trim()}" cannot be read (${reason})`,
+    );
+  }
+}