blokctl 1.3.0 → 1.4.0

package/dist/scaffold-repo/triggers/webhook/src/verifiers.ts

@@ -0,0 +1,394 @@
+/**
+ * Webhook signature verifiers — one strategy per supported provider.
+ *
+ * Each verifier reads the raw request bytes (NOT the JSON-parsed body)
+ * and the provider-specific signature header, computes the expected
+ * HMAC against a shared secret, and constant-time compares. On match,
+ * returns `{ ok: true, eventId, eventType }`. On mismatch / missing
+ * header / drift, returns `{ ok: false, reason, message }`.
+ *
+ * Constant-time comparison via `crypto.timingSafeEqual` is mandatory —
+ * a naive `===` compare leaks the expected HMAC byte by byte through
+ * timing variance and a network-adjacent attacker can recover the
+ * secret in ~256 requests per byte.
+ *
+ * Built-in providers + their signature shapes:
+ *
+ *   - **github**:    `X-Hub-Signature-256: sha256=<hex>` over rawBody.
+ *                    Event id from `X-GitHub-Delivery`; event type
+ *                    from `X-GitHub-Event` header.
+ *   - **stripe**:    `Stripe-Signature: t=<ts>,v1=<hex>` over
+ *                    `<ts>.<rawBody>` with a 5-minute drift window.
+ *                    Event id + type from body.id / body.type.
+ *   - **slack**:     `X-Slack-Signature: v0=<hex>` over
+ *                    `v0:<X-Slack-Request-Timestamp>:<rawBody>` with a
+ *                    5-minute drift window. Event type from
+ *                    body.event.type; event id from body.event_id.
+ *   - **shopify**:   `X-Shopify-Hmac-Sha256: <base64>` over rawBody.
+ *                    Event type from `X-Shopify-Topic`; event id from
+ *                    `X-Shopify-Webhook-Id`.
+ *   - **svix**:      Standard Webhooks. `webhook-signature:
+ *                    v1,<base64>` over `<webhook-id>.<webhook-timestamp>.<rawBody>`
+ *                    with a 5-minute drift window. Event id from
+ *                    `webhook-id`; event type from body.type.
+ *
+ * Custom (unknown provider) verifier is built dynamically by
+ * `buildCustomVerifier()` from the workflow's `signature` config.
+ */
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/** Successful verification result — workflow may proceed. */
+export interface VerifyOk {
+	ok: true;
+	/** Provider-specific event id (used for replay-protection cache key). */
+	eventId: string;
+	/** Provider-specific event type (used for the allowlist check). */
+	eventType: string;
+}
+
+/** Verification failure — trigger returns 401 with structured reason. */
+export interface VerifyError {
+	ok: false;
+	/** Stable discriminator — log/alert dashboards branch on this. */
+	reason:
+		| "missing_signature"
+		| "missing_timestamp"
+		| "missing_secret"
+		| "bad_format"
+		| "timestamp_drift"
+		| "signature_mismatch";
+	/** Human-readable error message. Safe to surface to the sender. */
+	message: string;
+}
+
+export type VerifyResult = VerifyOk | VerifyError;
+
+/** Inputs every verifier receives. */
+export interface VerifyInput {
+	headers: Record<string, string>;
+	rawBody: string;
+	parsedBody: unknown;
+	secret: string;
+	toleranceSec: number;
+}
+
+export interface Verifier {
+	verify(input: VerifyInput): VerifyResult;
+}
+
+const DEFAULT_TOLERANCE_SEC = 300;
+
+function safeEqualString(a: string, b: string): boolean {
+	const aBuf = Buffer.from(a);
+	const bBuf = Buffer.from(b);
+	if (aBuf.length !== bBuf.length) return false;
+	return timingSafeEqual(aBuf, bBuf);
+}
+
+function hmacHex(algo: "sha256" | "sha1" | "sha512", secret: string, data: string): string {
+	return createHmac(algo, secret).update(data).digest("hex");
+}
+
+function hmacBase64(algo: "sha256" | "sha1" | "sha512", secret: string, data: string): string {
+	return createHmac(algo, secret).update(data).digest("base64");
+}
+
+function isWithinTolerance(timestampSec: number, toleranceSec: number): boolean {
+	const nowSec = Math.floor(Date.now() / 1000);
+	return Math.abs(nowSec - timestampSec) <= toleranceSec;
+}
+
+function getEventTypeFromBody(parsedBody: unknown, key = "type"): string | undefined {
+	if (!parsedBody || typeof parsedBody !== "object") return undefined;
+	const value = (parsedBody as Record<string, unknown>)[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * Read a value from a parsed body by dot-separated path (e.g. `"data.id"`,
+ * `"resource.id"`). Returns the value coerced to string when it's a string or
+ * number, otherwise `undefined`. Used to pull a custom provider's event id out
+ * of the payload so webhook replay-protection has a key to dedup on.
+ */
+function getByPath(parsedBody: unknown, path: string): string | undefined {
+	if (!path) return undefined;
+	let cur: unknown = parsedBody;
+	for (const segment of path.split(".")) {
+		if (!cur || typeof cur !== "object") return undefined;
+		cur = (cur as Record<string, unknown>)[segment];
+	}
+	if (typeof cur === "string") return cur;
+	if (typeof cur === "number") return String(cur);
+	return undefined;
+}
+
+// =============================================================================
+// Built-in providers
+// =============================================================================
+
+export const githubVerifier: Verifier = {
+	verify({ headers, rawBody, secret }) {
+		if (!secret) return { ok: false, reason: "missing_secret", message: "GitHub: secret not configured" };
+		const sig = headers["x-hub-signature-256"];
+		if (!sig) return { ok: false, reason: "missing_signature", message: "GitHub: X-Hub-Signature-256 header missing" };
+		const expected = `sha256=${hmacHex("sha256", secret, rawBody)}`;
+		if (!safeEqualString(sig, expected)) {
+			return { ok: false, reason: "signature_mismatch", message: "GitHub: signature mismatch" };
+		}
+		return {
+			ok: true,
+			eventId: headers["x-github-delivery"] ?? "",
+			eventType: headers["x-github-event"] ?? "unknown",
+		};
+	},
+};
+
+export const stripeVerifier: Verifier = {
+	verify({ headers, rawBody, parsedBody, secret, toleranceSec }) {
+		if (!secret) return { ok: false, reason: "missing_secret", message: "Stripe: secret not configured" };
+		const sig = headers["stripe-signature"];
+		if (!sig) return { ok: false, reason: "missing_signature", message: "Stripe: Stripe-Signature header missing" };
+
+		// Format: t=1234567890,v1=<hex>,v0=<hex>,...
+		const parts = Object.fromEntries(
+			sig
+				.split(",")
+				.map((p) => p.trim())
+				.map((p) => {
+					const idx = p.indexOf("=");
+					return idx === -1 ? [p, ""] : [p.slice(0, idx), p.slice(idx + 1)];
+				}),
+		);
+		const ts = parts.t;
+		const v1 = parts.v1;
+		if (!ts || !v1) {
+			return {
+				ok: false,
+				reason: "bad_format",
+				message: "Stripe: signature missing t= or v1= component",
+			};
+		}
+		const tsNum = Number.parseInt(ts, 10);
+		if (!Number.isFinite(tsNum)) {
+			return { ok: false, reason: "bad_format", message: "Stripe: t= is not numeric" };
+		}
+		if (!isWithinTolerance(tsNum, toleranceSec || DEFAULT_TOLERANCE_SEC)) {
+			return {
+				ok: false,
+				reason: "timestamp_drift",
+				message: `Stripe: timestamp drift exceeds ${toleranceSec || DEFAULT_TOLERANCE_SEC}s tolerance`,
+			};
+		}
+		const expected = hmacHex("sha256", secret, `${ts}.${rawBody}`);
+		if (!safeEqualString(v1, expected)) {
+			return { ok: false, reason: "signature_mismatch", message: "Stripe: signature mismatch" };
+		}
+		const eventId = (parsedBody as { id?: unknown } | null)?.id;
+		const eventType = getEventTypeFromBody(parsedBody);
+		return {
+			ok: true,
+			eventId: typeof eventId === "string" ? eventId : "",
+			eventType: eventType ?? "unknown",
+		};
+	},
+};
+
+export const slackVerifier: Verifier = {
+	verify({ headers, rawBody, parsedBody, secret, toleranceSec }) {
+		if (!secret) return { ok: false, reason: "missing_secret", message: "Slack: secret not configured" };
+		const sig = headers["x-slack-signature"];
+		if (!sig) return { ok: false, reason: "missing_signature", message: "Slack: X-Slack-Signature header missing" };
+		const ts = headers["x-slack-request-timestamp"];
+		if (!ts) {
+			return {
+				ok: false,
+				reason: "missing_timestamp",
+				message: "Slack: X-Slack-Request-Timestamp header missing",
+			};
+		}
+		const tsNum = Number.parseInt(ts, 10);
+		if (!Number.isFinite(tsNum)) {
+			return { ok: false, reason: "bad_format", message: "Slack: timestamp is not numeric" };
+		}
+		if (!isWithinTolerance(tsNum, toleranceSec || DEFAULT_TOLERANCE_SEC)) {
+			return {
+				ok: false,
+				reason: "timestamp_drift",
+				message: `Slack: timestamp drift exceeds ${toleranceSec || DEFAULT_TOLERANCE_SEC}s tolerance`,
+			};
+		}
+		const expected = `v0=${hmacHex("sha256", secret, `v0:${ts}:${rawBody}`)}`;
+		if (!safeEqualString(sig, expected)) {
+			return { ok: false, reason: "signature_mismatch", message: "Slack: signature mismatch" };
+		}
+		const event = (parsedBody as { event?: { type?: unknown }; event_id?: unknown } | null) ?? {};
+		const eventType = typeof event.event?.type === "string" ? event.event.type : "unknown";
+		const eventId = typeof event.event_id === "string" ? event.event_id : "";
+		return { ok: true, eventId, eventType };
+	},
+};
+
+export const shopifyVerifier: Verifier = {
+	verify({ headers, rawBody, secret }) {
+		if (!secret) return { ok: false, reason: "missing_secret", message: "Shopify: secret not configured" };
+		const sig = headers["x-shopify-hmac-sha256"];
+		if (!sig) {
+			return { ok: false, reason: "missing_signature", message: "Shopify: X-Shopify-Hmac-Sha256 header missing" };
+		}
+		const expected = hmacBase64("sha256", secret, rawBody);
+		if (!safeEqualString(sig, expected)) {
+			return { ok: false, reason: "signature_mismatch", message: "Shopify: signature mismatch" };
+		}
+		return {
+			ok: true,
+			eventId: headers["x-shopify-webhook-id"] ?? "",
+			eventType: headers["x-shopify-topic"] ?? "unknown",
+		};
+	},
+};
+
+export const svixVerifier: Verifier = {
+	verify({ headers, rawBody, parsedBody, secret, toleranceSec }) {
+		if (!secret) return { ok: false, reason: "missing_secret", message: "Svix: secret not configured" };
+		const webhookId = headers["webhook-id"];
+		const webhookTs = headers["webhook-timestamp"];
+		const webhookSig = headers["webhook-signature"];
+		if (!webhookId || !webhookTs || !webhookSig) {
+			return {
+				ok: false,
+				reason: "missing_signature",
+				message: "Svix/Standard Webhooks: missing webhook-id, webhook-timestamp, or webhook-signature header",
+			};
+		}
+		const tsNum = Number.parseInt(webhookTs, 10);
+		if (!Number.isFinite(tsNum)) {
+			return { ok: false, reason: "bad_format", message: "Svix: webhook-timestamp is not numeric" };
+		}
+		if (!isWithinTolerance(tsNum, toleranceSec || DEFAULT_TOLERANCE_SEC)) {
+			return {
+				ok: false,
+				reason: "timestamp_drift",
+				message: `Svix: timestamp drift exceeds ${toleranceSec || DEFAULT_TOLERANCE_SEC}s tolerance`,
+			};
+		}
+		const signed = `${webhookId}.${webhookTs}.${rawBody}`;
+		// Strip optional `whsec_` prefix Svix recommends for secrets.
+		const rawSecret = secret.startsWith("whsec_") ? secret.slice("whsec_".length) : secret;
+		// Svix encodes the secret as base64 — decode before HMAC.
+		const secretBuf = Buffer.from(rawSecret, "base64");
+		const expected = createHmac("sha256", secretBuf).update(signed).digest("base64");
+		// webhook-signature may include multiple versions: `v1,base64 v1,base64 ...`
+		const sigs = webhookSig.split(" ").map((s) => {
+			const idx = s.indexOf(",");
+			return idx === -1 ? s : s.slice(idx + 1);
+		});
+		const matched = sigs.some((s) => safeEqualString(s, expected));
+		if (!matched) {
+			return { ok: false, reason: "signature_mismatch", message: "Svix: signature mismatch" };
+		}
+		return {
+			ok: true,
+			eventId: webhookId,
+			eventType: getEventTypeFromBody(parsedBody) ?? "unknown",
+		};
+	},
+};
+
+// =============================================================================
+// Custom verifier — built from the workflow's `signature: { ... }` config
+// =============================================================================
+
+export interface CustomSignatureConfig {
+	scheme: "hmac-sha256" | "hmac-sha1" | "hmac-sha512";
+	header: string;
+	format: string;
+	secretEnv: string;
+	tolerance: number;
+	timestampHeader?: string;
+	/**
+	 * Where to read the provider's event id from, for replay-protection dedup.
+	 * `eventIdHeader` takes precedence; otherwise `eventIdPath` reads a
+	 * dot-separated path from the parsed body (e.g. `"id"`, `"data.id"`).
+	 * When neither is set the verifier returns `eventId: ""` and webhook-level
+	 * idempotency is disabled (no key to dedup on) — set one when the provider
+	 * redelivers (most PSPs do).
+	 */
+	eventIdPath?: string;
+	eventIdHeader?: string;
+}
+
+export function buildCustomVerifier(config: CustomSignatureConfig): Verifier {
+	const algo: "sha256" | "sha1" | "sha512" =
+		config.scheme === "hmac-sha1" ? "sha1" : config.scheme === "hmac-sha512" ? "sha512" : "sha256";
+	const headerLower = config.header.toLowerCase();
+	const tsHeaderLower = config.timestampHeader?.toLowerCase();
+	const eventIdHeaderLower = config.eventIdHeader?.toLowerCase();
+
+	return {
+		verify({ headers, rawBody, parsedBody, secret, toleranceSec }) {
+			if (!secret) return { ok: false, reason: "missing_secret", message: `${config.header}: secret not configured` };
+			const sig = headers[headerLower];
+			if (!sig) {
+				return { ok: false, reason: "missing_signature", message: `${config.header}: header missing` };
+			}
+
+			let signedString = rawBody;
+			if (tsHeaderLower) {
+				const ts = headers[tsHeaderLower];
+				if (!ts) {
+					return {
+						ok: false,
+						reason: "missing_timestamp",
+						message: `${config.timestampHeader}: header missing`,
+					};
+				}
+				const tsNum = Number.parseInt(ts, 10);
+				if (!Number.isFinite(tsNum)) {
+					return {
+						ok: false,
+						reason: "bad_format",
+						message: `${config.timestampHeader}: not numeric`,
+					};
+				}
+				if (!isWithinTolerance(tsNum, toleranceSec || config.tolerance)) {
+					return {
+						ok: false,
+						reason: "timestamp_drift",
+						message: `Timestamp drift exceeds ${toleranceSec || config.tolerance}s tolerance`,
+					};
+				}
+				signedString = `${ts}.${rawBody}`;
+			}
+
+			const hex = hmacHex(algo, secret, signedString);
+			const base64 = hmacBase64(algo, secret, signedString);
+			const expected = config.format.replace("{hex}", hex).replace("{base64}", base64);
+
+			if (!safeEqualString(sig, expected)) {
+				return { ok: false, reason: "signature_mismatch", message: `${config.header}: signature mismatch` };
+			}
+			// Resolve the event id for replay-protection: header wins, then body
+			// path, then "" (idempotency disabled — no key to dedup on).
+			let eventId = "";
+			if (eventIdHeaderLower) {
+				eventId = headers[eventIdHeaderLower] ?? "";
+			} else if (config.eventIdPath) {
+				eventId = getByPath(parsedBody, config.eventIdPath) ?? "";
+			}
+			return {
+				ok: true,
+				eventId,
+				eventType: getEventTypeFromBody(parsedBody) ?? "unknown",
+			};
+		},
+	};
+}
+
+export const BUILTIN_VERIFIERS: Record<string, Verifier> = {
+	github: githubVerifier,
+	stripe: stripeVerifier,
+	slack: slackVerifier,
+	shopify: shopifyVerifier,
+	svix: svixVerifier,
+};

package/dist/scaffold-repo/triggers/webhook/tsconfig.json

@@ -0,0 +1,32 @@
+{
+	"ts-node": {
+		"transpileOnly": true
+	},
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "es2022",
+		"lib": ["ES2022"],
+		"declaration": true,
+		"strict": true,
+		"noImplicitAny": true,
+		"strictNullChecks": true,
+		"noImplicitThis": true,
+		"alwaysStrict": true,
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noImplicitReturns": true,
+		"noFallthroughCasesInSwitch": false,
+		"inlineSourceMap": true,
+		"inlineSources": true,
+		"experimentalDecorators": true,
+		"emitDecoratorMetadata": true,
+		"skipLibCheck": true,
+		"esModuleInterop": true,
+		"resolveJsonModule": true,
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"moduleResolution": "bundler"
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/dist/scaffold-repo/triggers/websocket/.env.example

@@ -0,0 +1,8 @@
+PROJECT_NAME=trigger-websocket-server
+PROJECT_VERSION=0.0.1
+PORT=4002
+WORKFLOWS_PATH=PROJECT_PATH/workflows
+NODES_PATH=PROJECT_PATH/src/nodes
+CONSOLE_LOG_ACTIVE=true
+APP_NAME=blok-ws
+DISABLE_TRIGGER_RUN=false # Set to true to disable trigger run and use this project as a module

package/dist/scaffold-repo/triggers/websocket/CHANGELOG.md

@@ -0,0 +1,22 @@
+# @blokjs/trigger-websocket
+
+## 0.2.0
+
+### Minor Changes
+
+- Initial public release of Blok packages.
+
+  This release includes:
+
+  - Core packages: @blokjs/shared, @blokjs/helper, @blokjs/runner
+  - Node packages: @blokjs/api-call, @blokjs/if-else, @blokjs/react
+  - Trigger packages: pubsub, queue, webhook, websocket, worker, cron, grpc
+  - CLI tool: blokctl
+  - Editor support: @blokjs/lsp-server, @blokjs/syntax
+
+### Patch Changes
+
+- Updated dependencies
+  - @blokjs/shared@0.2.0
+  - @blokjs/helper@0.2.0
+  - @blokjs/runner@0.2.0

package/dist/scaffold-repo/triggers/websocket/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@blokjs/trigger-websocket",
+	"version": "1.4.0",
+	"files": ["dist"],
+	"description": "WebSocket trigger for Blok workflows - real-time bidirectional communication",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"scripts": {
+		"build": "rm -rf dist && bun run tsc",
+		"build:dev": "tsc --watch",
+		"test": "vitest run",
+		"test:dev": "vitest"
+	},
+	"author": "Deskree Technologies Inc.",
+	"license": "Apache-2.0",
+	"dependencies": {
+		"@blokjs/helper": "^1.4.0",
+		"@blokjs/runner": "^1.4.0",
+		"@blokjs/shared": "^1.4.0",
+		"@hono/node-ws": "^1.3.1",
+		"@opentelemetry/api": "^1.9.0",
+		"uuid": "^11.1.0"
+	},
+	"peerDependencies": {
+		"@blokjs/trigger-pubsub": "^1.4.0",
+		"ws": "^8.19.0"
+	},
+	"peerDependenciesMeta": {
+		"@blokjs/trigger-pubsub": {
+			"optional": true
+		},
+		"ws": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@blokjs/core": "^1.4.0",
+		"@types/node": "^22.15.21",
+		"@types/uuid": "^11.0.0",
+		"@types/ws": "^8.18.1",
+		"typescript": "^5.8.3",
+		"vitest": "^4.0.18",
+		"ws": "^8.19.0"
+	},
+	"private": false,
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/dist/scaffold-repo/triggers/websocket/src/Backplane.ts

@@ -0,0 +1,167 @@
+/**
+ * WebSocket cross-process broadcast backplane — v0.7 follow-up.
+ *
+ * In single-process deployments the WS trigger's `broadcastToRoom`
+ * iterates its local `rooms` map and is done. In multi-process
+ * deployments (horizontally-scaled WS workers behind a load balancer)
+ * a message published by process A's `broadcastToRoom` ALSO needs to
+ * reach process B's connections in the same workflow-scoped room.
+ *
+ * **Mechanism.** When opted in via `BLOK_WS_BACKPLANE=<provider>`
+ * (or constructor config), the WS trigger:
+ *
+ *   1. **Subscribes** to a well-known pub/sub topic (default
+ *      `__blok_ws_broadcast`) at `listen()` time, via the same
+ *      adapter factory the PubSubTrigger uses (PR 6). Every WS
+ *      worker in the cluster joins the same fan-out topic.
+ *   2. **Publishes** every broadcast envelope to the topic.
+ *      Envelopes carry `workflowName`, `room`, `data` (string or
+ *      base64-encoded binary), `exceptConnectionId`, and `senderId`
+ *      (this process's uuid).
+ *   3. **Receives** envelopes from peers and re-runs the local
+ *      fan-out — skipping its own publishes via the `senderId`
+ *      check so messages don't echo back.
+ *
+ * Provider is picked via the pub/sub factory — supports `nats`,
+ * `redis-streams`, `kafka`, `gcp`, `aws`, `azure` (whichever the
+ * operator's stack runs). For dev / tests / single-process
+ * deployments, leave the env unset and the backplane is a no-op.
+ *
+ * Binary frames (Uint8Array, ArrayBuffer) are encoded base64 in the
+ * envelope so JSON serialization round-trips cleanly across the
+ * broker. Text frames pass through as strings. The receive path
+ * decodes back to the original shape before handing to local
+ * `WSContext.send`.
+ */
+
+import { v4 as uuid } from "uuid";
+
+/**
+ * The publish/subscribe API surface the backplane needs. Compatible
+ * with `@blokjs/trigger-pubsub`'s `PubSubAdapter` interface so any of
+ * the 6 v0.7 adapters can be dropped in.
+ *
+ * Type-loose `unknown` for inputs/outputs because we lazy-import the
+ * pubsub trigger at runtime to keep the WS package free of broker
+ * SDKs in workflows that don't use the backplane.
+ */
+export interface BackplaneAdapter {
+	readonly provider: string;
+	connect(): Promise<void>;
+	disconnect(): Promise<void>;
+	publish(topic: string, payload: unknown, opts?: { partitionKey?: string }): Promise<void>;
+	subscribe(
+		config: { topic: string; consumerGroup?: string },
+		handler: (msg: { body: unknown; topic: string; subscription?: string }) => Promise<void>,
+	): Promise<void>;
+}
+
+/**
+ * Cross-process broadcast envelope. Serialised to JSON on publish,
+ * parsed on receive. Binary frames are base64-encoded so the envelope
+ * is always JSON-safe.
+ */
+export interface BroadcastEnvelope {
+	/** Process uuid of the publishing WS worker; receiver skips its own publishes. */
+	senderId: string;
+	/** Workflow-scoped room key (already includes the `<workflowName>:` prefix). */
+	roomKey: string;
+	/** Optional connection id to skip on the receiving side (`exceptSelf` semantics). */
+	exceptConnectionId?: string;
+	/** Encoded payload — `{kind: "text", value: string}` or `{kind: "binary", base64: string}`. */
+	payload: { kind: "text"; value: string } | { kind: "binary"; base64: string };
+}
+
+export const DEFAULT_BACKPLANE_TOPIC = "__blok_ws_broadcast";
+
+/**
+ * Build the broadcast envelope from a local fan-out call's
+ * arguments. Used by `WebSocketTrigger.broadcastToRoom` on the
+ * publish path.
+ */
+export function encodeEnvelope(
+	senderId: string,
+	roomKey: string,
+	data: string | ArrayBuffer | Uint8Array,
+	exceptConnectionId?: string,
+): BroadcastEnvelope {
+	if (typeof data === "string") {
+		return { senderId, roomKey, exceptConnectionId, payload: { kind: "text", value: data } };
+	}
+	const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+	const base64 = Buffer.from(bytes).toString("base64");
+	return { senderId, roomKey, exceptConnectionId, payload: { kind: "binary", base64 } };
+}
+
+/**
+ * Decode a received envelope back to the WS-ready payload shape.
+ * The receive handler hands this directly to `WSContext.send`.
+ */
+export function decodePayload(envelope: BroadcastEnvelope): string | Uint8Array {
+	if (envelope.payload.kind === "text") return envelope.payload.value;
+	return new Uint8Array(Buffer.from(envelope.payload.base64, "base64"));
+}
+
+/**
+ * Generate this WS worker's senderId. Stable for the lifetime of
+ * the WebSocketTrigger instance; used to skip self-echoes on the
+ * subscribe handler.
+ */
+export function newSenderId(): string {
+	return `ws-${uuid()}`;
+}
+
+/**
+ * Backplane configuration. Resolution order at trigger construction:
+ *
+ *   1. Explicit `BackplaneConfig` passed to the constructor.
+ *   2. `BLOK_WS_BACKPLANE` env var — the provider name (e.g. `nats`).
+ *      Topic + consumerGroup honor `BLOK_WS_BACKPLANE_TOPIC` and
+ *      `BLOK_WS_BACKPLANE_GROUP` when set; otherwise default to
+ *      `__blok_ws_broadcast` and undefined (fan-out).
+ *   3. Disabled — single-process behavior, no backplane connection.
+ */
+export interface BackplaneConfig {
+	provider: "nats" | "redis-streams" | "kafka" | "gcp" | "aws" | "azure";
+	topic?: string;
+	consumerGroup?: string;
+}
+
+export function resolveBackplaneConfig(explicit?: BackplaneConfig): BackplaneConfig | null {
+	if (explicit) return explicit;
+	const envProvider = process.env.BLOK_WS_BACKPLANE;
+	// `process.env.X = undefined` in Node.js stores the literal string
+	// "undefined" instead of unsetting the var — defensive check below.
+	if (!envProvider || envProvider === "undefined") return null;
+	const valid: ReadonlyArray<BackplaneConfig["provider"]> = ["nats", "redis-streams", "kafka", "gcp", "aws", "azure"];
+	if (!(valid as readonly string[]).includes(envProvider)) return null;
+	const topicEnv = process.env.BLOK_WS_BACKPLANE_TOPIC;
+	const groupEnv = process.env.BLOK_WS_BACKPLANE_GROUP;
+	return {
+		provider: envProvider as BackplaneConfig["provider"],
+		topic: topicEnv && topicEnv !== "undefined" ? topicEnv : DEFAULT_BACKPLANE_TOPIC,
+		consumerGroup: groupEnv && groupEnv !== "undefined" ? groupEnv : undefined,
+	};
+}
+
+/**
+ * Lazy-load the v0.7 pub/sub factory and instantiate an adapter for
+ * the chosen provider. Returns the adapter, ready for `connect()`.
+ * Throws if `@blokjs/trigger-pubsub` is not installed.
+ */
+export async function createBackplaneAdapter(config: BackplaneConfig): Promise<BackplaneAdapter> {
+	const moduleName = "@blokjs/trigger-pubsub";
+	interface PubSubModule {
+		getOrCreateAdapter(provider: BackplaneConfig["provider"]): BackplaneAdapter;
+	}
+	let mod: PubSubModule;
+	try {
+		mod = (await import(moduleName)) as PubSubModule;
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(
+			`[blok][ws-backplane] cannot load @blokjs/trigger-pubsub (${msg}). Install it to enable the cross-process WS broadcast backplane.`,
+		);
+	}
+	return mod.getOrCreateAdapter(config.provider);
+}