@flowget/codec

Payload encryption codec for the Flowget BYO-worker model. Ships the PayloadCodec interface, an authenticated AES-256-GCM reference implementation, key-loading utilities, and a Temporal data-converter adapter. With the codec wired into your SDK and worker, plaintext never crosses Flowget infrastructure — the cluster persists and routes only ciphertext, and you hold the key.

Install

npm i @flowget/codec

@temporalio/common is an optional peer dependency, pulled in only when you import the /temporal-adapter subpath.

Generate a key

# 32 random bytes, base64-encoded. Treat as a secret; never commit it.
openssl rand -base64 32 > .flowget-key
chmod 600 .flowget-key

Use standard base64 (not base64url) — the loaders reject the URL-safe alphabet. Keep the key in a secret manager and inject it at process start.

Usage

import { AESPayloadCodec, loadKeyFromEnv } from "@flowget/codec";

const codec = new AESPayloadCodec(loadKeyFromEnv("FLOWGET_PAYLOAD_KEY"));

const ciphertext = await codec.encode(
  new TextEncoder().encode(JSON.stringify({ email: "[email protected]" })),
);
const plaintext = await codec.decode(ciphertext);

Temporal adapter

PayloadCodec is a byte-level primitive (Uint8Array → Uint8Array). Temporal's data converter expects a different shape, so bridge it with wrapForTemporal from the @flowget/codec/temporal-adapter subpath — do not pass an AESPayloadCodec to the worker directly.

import { Worker } from "@temporalio/worker";
import { AESPayloadCodec, loadKeysFromEnv } from "@flowget/codec";
import { wrapForTemporal } from "@flowget/codec/temporal-adapter";

const codec = new AESPayloadCodec(loadKeysFromEnv("FLOWGET_PAYLOAD_KEYS"));

const worker = await Worker.create({
  // ...workflowsPath, taskQueue, etc.
  dataConverter: { payloadCodecs: [wrapForTemporal(codec)] },
});

Use the same wrap on the client so both ends of the cluster speak one wire format.

Key rotation

AESPayloadCodec accepts an ordered key set (primary first). encode uses the primary; decode trial-decodes each configured key until one validates — so a worker can advertise [NEW, OLD], encrypt new payloads under NEW, and still decode in-flight payloads under OLD with no drain window.

const codec = new AESPayloadCodec([newKey, oldKey]);

Custom codecs

AESPayloadCodec is the reference implementation. HSM-backed or envelope-encrypted deployments can ship their own authenticated, symmetric PayloadCodec by implementing the two-method interface.

⚠️ 0.x is unstable

The surface is unstable until v1 — breaking changes ship as minor bumps. Pin exact versions in consumers ("@flowget/codec": "0.1.0", not "^0.1.0").

Links

• Full documentation: https://docs.flowget.io
• Security policy: SECURITY.md
• License: FSL-1.1-ALv2 (see LICENSE)