@stigmer/temporal-codecs 3.29.0 → 3.31.0

package/connection/config.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 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 declare const TEMPORAL_API_KEY_ENV = "STIGMER_TEMPORAL_API_KEY";
+export declare const TEMPORAL_TLS_ENV = "STIGMER_TEMPORAL_TLS";
+export declare const TEMPORAL_TLS_SERVER_NAME_ENV = "STIGMER_TEMPORAL_TLS_SERVER_NAME";
+/**
+ * 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 declare const TEMPORAL_TLS_CLIENT_KEY_DATA_ENV: string;
+/**
+ * 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 declare const TEMPORAL_CONNECTION_ENV_NAMES: readonly string[];
+/**
+ * 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 declare function loadTemporalConnectionConfig(read: SecretReader): TemporalConnectionConfig;
+/**
+ * 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 declare function temporalConnectionEnv(config: TemporalConnectionConfig): Record<string, string>;
+//# sourceMappingURL=config.d.ts.map

package/connection/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/connection/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,UAAU,CAAC;IAC9C,QAAQ,CAAC,cAAc,CAAC,EAAE;QACxB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;QACzB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;KAC1B,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAC/D,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AACvD,eAAO,MAAM,4BAA4B,qCAAqC,CAAC;AAS/E;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,QAAgC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAK1D,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,YAAY,GACjB,wBAAwB,CA2C1B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,wBAAwB,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB"}

package/connection/config.js

@@ -0,0 +1,171 @@
+/**
+ * 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";
+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",
+};
+/**
+ * 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 = [
+    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) {
+    const value = (name) => {
+        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 = {
+        ...(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) {
+    const env = {};
+    if (config.tls === undefined)
+        return env;
+    env[TEMPORAL_TLS_ENV] = "true";
+    const text = (bytes) => 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) {
+    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, value) {
+    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})`);
+    }
+}
+//# sourceMappingURL=config.js.map

package/connection/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/connection/config.ts"],"names":[],"mappings":"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"}

package/index.d.ts

@@ -1,11 +1,13 @@
 /**
- * @stigmer/temporal-codecs — Temporal payload codecs shared by Stigmer's
- * TypeScript Temporal processes (the runner today; the TS server at its
- * cutover). 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/), which is why the codecs live in one library
- * instead of per-consumer copies that could fork.
+ * @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
@@ -21,6 +23,8 @@
 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";

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;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,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"}
+{"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

@@ -1,11 +1,13 @@
 /**
- * @stigmer/temporal-codecs — Temporal payload codecs shared by Stigmer's
- * TypeScript Temporal processes (the runner today; the TS server at its
- * cutover). 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/), which is why the codecs live in one library
- * instead of per-consumer copies that could fork.
+ * @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
@@ -20,6 +22,7 @@
  */
 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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AASrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}
+{"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

@@ -1,7 +1,7 @@
 {
   "name": "@stigmer/temporal-codecs",
-  "version": "3.29.0",
-  "description": "Temporal payload codecs shared by Stigmer's TypeScript Temporal processes — AES-256-GCM payload encryption and claim-check offloading, the one home for the cross-language envelope contract",
+  "version": "3.31.0",
+  "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,
@@ -18,7 +18,8 @@
     "temporal",
     "payload-codec",
     "encryption",
-    "claim-check"
+    "claim-check",
+    "tls"
   ],
   "main": "./index.js",
   "types": "./index.d.ts",

package/src/__tests__/connection-config.test.ts

@@ -0,0 +1,155 @@
+/**
+ * The Temporal connection settings (`connection/config.ts`): what each
+ * setting turns on, the misconfigurations that stop the boot, the rule that
+ * an empty value is unset, the refusal to read Temporal's own names (they
+ * are the user's), and the round trip through the environment a child
+ * runner receives.
+ */
+
+import { describe, it, expect, afterAll } from "vitest";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  loadTemporalConnectionConfig,
+  temporalConnectionEnv,
+  TEMPORAL_CONNECTION_ENV_NAMES,
+} from "../connection/config.js";
+
+const CA = "-----BEGIN CERTIFICATE-----\nca\n-----END CERTIFICATE-----\n";
+const CRT = "-----BEGIN CERTIFICATE-----\nclient\n-----END CERTIFICATE-----\n";
+const KEY = "-----BEGIN PRIVATE KEY-----\nkey\n-----END PRIVATE KEY-----\n";
+
+const dir = mkdtempSync(join(tmpdir(), "temporal-connection-config-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+function load(env: Record<string, string>) {
+  return loadTemporalConnectionConfig((name) => env[name]);
+}
+
+function text(bytes: Uint8Array | undefined): string | undefined {
+  return bytes === undefined ? undefined : Buffer.from(bytes).toString("utf8");
+}
+
+describe("loadTemporalConnectionConfig", () => {
+  it("is a plaintext connection when nothing is set", () => {
+    expect(load({})).toEqual({});
+  });
+
+  it("treats every empty or blank value as unset", () => {
+    expect(
+      load({
+        STIGMER_TEMPORAL_API_KEY: "",
+        STIGMER_TEMPORAL_TLS: "  ",
+        STIGMER_TEMPORAL_TLS_SERVER_NAME: "",
+        STIGMER_TEMPORAL_TLS_SERVER_CA_CERT_DATA: "",
+        STIGMER_TEMPORAL_TLS_CLIENT_CERT_PATH: "",
+      }),
+    ).toEqual({});
+  });
+
+  it("never reads Temporal's own TEMPORAL_* names, which are the user's", () => {
+    expect(
+      load({
+        TEMPORAL_API_KEY: "the-users-own-key",
+        TEMPORAL_TLS: "true",
+        TEMPORAL_TLS_SERVER_CA_CERT_DATA: CA,
+      }),
+    ).toEqual({});
+  });
+
+  it("turns TLS on with the system's roots for STIGMER_TEMPORAL_TLS=true or 1", () => {
+    expect(load({ STIGMER_TEMPORAL_TLS: "true" })).toEqual({ tls: {} });
+    expect(load({ STIGMER_TEMPORAL_TLS: "1" })).toEqual({ tls: {} });
+    expect(load({ STIGMER_TEMPORAL_TLS: "false" })).toEqual({});
+  });
+
+  it("an API key implies TLS", () => {
+    expect(load({ STIGMER_TEMPORAL_API_KEY: " k-1 " })).toEqual({ tls: {}, apiKey: "k-1" });
+  });
+
+  it("a CA or a server name implies TLS and is carried in the SDK's shape", () => {
+    const config = load({
+      STIGMER_TEMPORAL_TLS_SERVER_CA_CERT_DATA: CA,
+      STIGMER_TEMPORAL_TLS_SERVER_NAME: "temporal.internal",
+    });
+    expect(config.tls?.serverNameOverride).toBe("temporal.internal");
+    expect(text(config.tls?.serverRootCACertificate)).toBe(CA);
+    expect(config.apiKey).toBeUndefined();
+  });
+
+  it("reads a client pair for mutual TLS, from data or from files", () => {
+    const fromData = load({
+      STIGMER_TEMPORAL_TLS_CLIENT_CERT_DATA: CRT,
+      STIGMER_TEMPORAL_TLS_CLIENT_KEY_DATA: KEY,
+    });
+    expect(text(fromData.tls?.clientCertPair?.crt)).toBe(CRT);
+    expect(text(fromData.tls?.clientCertPair?.key)).toBe(KEY);
+
+    writeFileSync(join(dir, "client.crt"), CRT);
+    writeFileSync(join(dir, "client.key"), KEY);
+    const fromFiles = load({
+      STIGMER_TEMPORAL_TLS_CLIENT_CERT_PATH: join(dir, "client.crt"),
+      STIGMER_TEMPORAL_TLS_CLIENT_KEY_PATH: join(dir, "client.key"),
+    });
+    expect(text(fromFiles.tls?.clientCertPair?.crt)).toBe(CRT);
+    expect(text(fromFiles.tls?.clientCertPair?.key)).toBe(KEY);
+  });
+
+  it.each([
+    [{ STIGMER_TEMPORAL_TLS_CLIENT_CERT_DATA: CRT }, /mutual TLS needs both/],
+    [{ STIGMER_TEMPORAL_TLS_CLIENT_KEY_DATA: KEY }, /mutual TLS needs both/],
+    [
+      {
+        STIGMER_TEMPORAL_TLS_SERVER_CA_CERT_DATA: CA,
+        STIGMER_TEMPORAL_TLS_SERVER_CA_CERT_PATH: "/etc/ca.pem",
+      },
+      /set STIGMER_TEMPORAL_TLS_SERVER_CA_CERT_PATH or STIGMER_TEMPORAL_TLS_SERVER_CA_CERT_DATA, not both/,
+    ],
+    [
+      { STIGMER_TEMPORAL_TLS_SERVER_CA_CERT_PATH: "/nonexistent/ca.pem" },
+      /STIGMER_TEMPORAL_TLS_SERVER_CA_CERT_PATH "\/nonexistent\/ca.pem" cannot be read/,
+    ],
+    [{ STIGMER_TEMPORAL_TLS: "yes" }, /must be true, 1, false or 0/],
+    [
+      { STIGMER_TEMPORAL_TLS: "false", STIGMER_TEMPORAL_API_KEY: "k" },
+      /STIGMER_TEMPORAL_TLS is false while/,
+    ],
+  ])("stops the boot on a contradictory or unreadable setting (%o)", (env, message) => {
+    expect(() => load(env)).toThrow(message);
+  });
+
+  it("reads every value through the injected reader, and only it", () => {
+    const asked: string[] = [];
+    loadTemporalConnectionConfig((name) => {
+      asked.push(name);
+      return undefined;
+    });
+    // The exported list is exactly what the reader reads, so a process
+    // that strips inherited settings strips all of them and nothing else.
+    expect([...new Set(asked)].sort()).toEqual([...TEMPORAL_CONNECTION_ENV_NAMES].sort());
+  });
+});
+
+describe("temporalConnectionEnv", () => {
+  it("renders nothing for a plaintext connection", () => {
+    expect(temporalConnectionEnv({})).toEqual({});
+  });
+
+  it("round-trips every setting through the _DATA forms a child runner reads", () => {
+    writeFileSync(join(dir, "ca.pem"), CA);
+    const loaded = load({
+      STIGMER_TEMPORAL_API_KEY: "k-2",
+      STIGMER_TEMPORAL_TLS_SERVER_NAME: "temporal.internal",
+      STIGMER_TEMPORAL_TLS_SERVER_CA_CERT_PATH: join(dir, "ca.pem"),
+      STIGMER_TEMPORAL_TLS_CLIENT_CERT_DATA: CRT,
+      STIGMER_TEMPORAL_TLS_CLIENT_KEY_DATA: KEY,
+    });
+    const env = temporalConnectionEnv(loaded);
+
+    expect(Object.keys(env).some((name) => name.endsWith("_PATH"))).toBe(false);
+    expect(env["STIGMER_TEMPORAL_TLS_SERVER_CA_CERT_DATA"]).toBe(CA);
+    expect(load(env)).toEqual(loaded);
+  });
+});

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})`,
+    );
+  }
+}

package/src/index.ts

@@ -1,11 +1,13 @@
 /**
- * @stigmer/temporal-codecs — Temporal payload codecs shared by Stigmer's
- * TypeScript Temporal processes (the runner today; the TS server at its
- * cutover). 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/), which is why the codecs live in one library
- * instead of per-consumer copies that could fork.
+ * @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
@@ -29,6 +31,18 @@ export type {
   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";