@intx/workflow-host 0.2.2

package/dist/ipc/crypto.js

@@ -0,0 +1,126 @@
+// IPC crypto primitives: raw Ed25519 sign/verify and HMAC-SHA256 sign/verify.
+//
+// The control channel uses Ed25519 because the supervisor is the only
+// signer and the child must not be able to forge supervisor commands.
+// The event channel uses HMAC-SHA256 because both sides hold the same
+// 32-byte secret and the cost-per-frame of HMAC over per-frame Ed25519
+// is what keeps the event stream affordable at InferenceEvent rates.
+//
+// Ed25519 sign/verify come from `@intx/crypto`, whose raw
+// `signEd25519`/`verifyEd25519` primitives produce and check the bare
+// 64-byte RFC 8032 signature without the PGP packet framing and ASCII
+// armor the package's envelope helpers add — exactly the wire format
+// this channel wants. HMAC-SHA256 uses the Web Crypto `subtle` API; its
+// tag is verified by recomputing the tag with `subtle.sign` and
+// comparing under an explicit constant-time XOR-accumulate rather than
+// `subtle.verify`, because the Web Crypto spec does not guarantee
+// `verify` runs in constant time and this channel keeps ownership of
+// that property. The wire format here is the raw 64-byte Ed25519
+// signature and the raw 32-byte HMAC-SHA256 tag concatenated with the
+// canonical-JSON payload bytes. Anything fancier would just pay PGP
+// overhead per frame.
+import { signEd25519 as ed25519Sign, verifyEd25519 as ed25519Verify, } from "@intx/crypto";
+import { hexEncode } from "@intx/types";
+const ED25519_SIGNATURE_BYTES = 64;
+const ED25519_KEY_BYTES = 32;
+const HMAC_KEY_BYTES = 32;
+const HMAC_TAG_BYTES = 32;
+const CHANNEL_ID_BYTES = 16;
+/**
+ * Mint a fresh control-channel HMAC key. Used by the supervisor at
+ * spawn time. The child never derives its own key; it receives the
+ * 32-byte secret in spawn-time env and never sees the Ed25519 private
+ * key the supervisor uses on the control channel.
+ */
+export function generateHmacKey() {
+    return crypto.getRandomValues(new Uint8Array(HMAC_KEY_BYTES));
+}
+/**
+ * Mint a fresh channelId per the channel-identity contract: 16 bytes
+ * from `crypto.getRandomValues`, hex-encoded. The supervisor mints one at
+ * every spawn and every recycle, passes it to the child in spawn-time
+ * env, and rotates it on the next respawn. The hex encoding keeps the
+ * value safe to log and round-trips cleanly through JSON.
+ */
+export function generateChannelId() {
+    return hexEncode(crypto.getRandomValues(new Uint8Array(CHANNEL_ID_BYTES)));
+}
+/**
+ * Sign the canonicalized envelope bytes with the supervisor's
+ * Ed25519 private key. Caller is responsible for canonicalization;
+ * this primitive does not see the structured envelope.
+ *
+ * The private-key bytes are the 32-byte Ed25519 seed. The raw signing
+ * primitive lives in `@intx/crypto`; this module wraps it with the
+ * channel's fixed-length validation.
+ */
+export async function signEd25519(bytes, privateKeySeed) {
+    if (privateKeySeed.length !== ED25519_KEY_BYTES) {
+        throw new Error(`IPC Ed25519 private key seed must be ${ED25519_KEY_BYTES} bytes, got ${privateKeySeed.length}`);
+    }
+    return ed25519Sign(privateKeySeed, bytes);
+}
+export async function verifyEd25519(bytes, signature, publicKey) {
+    if (signature.length !== ED25519_SIGNATURE_BYTES) {
+        throw new Error(`IPC Ed25519 signature must be ${ED25519_SIGNATURE_BYTES} bytes, got ${signature.length}`);
+    }
+    if (publicKey.length !== ED25519_KEY_BYTES) {
+        throw new Error(`IPC Ed25519 public key must be ${ED25519_KEY_BYTES} bytes, got ${publicKey.length}`);
+    }
+    return ed25519Verify(bytes, signature, publicKey);
+}
+/**
+ * Produce the 32-byte HMAC-SHA256 tag for the given canonicalized
+ * envelope bytes under the shared key. Same primitive on both sides
+ * of the event channel.
+ */
+export async function signHmac(bytes, key) {
+    if (key.length !== HMAC_KEY_BYTES) {
+        throw new Error(`IPC HMAC key must be ${HMAC_KEY_BYTES} bytes, got ${key.length}`);
+    }
+    const cryptoKey = await crypto.subtle.importKey("raw", 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- ArrayBuffer-backed at the call site; Web Crypto's BufferSource type rejects Uint8Array<ArrayBufferLike> under TS 5.9 (microsoft/TypeScript#62240)
+    key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const tag = await crypto.subtle.sign("HMAC", cryptoKey, 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- ArrayBuffer-backed at the call site; Web Crypto's BufferSource type rejects Uint8Array<ArrayBufferLike> under TS 5.9 (microsoft/TypeScript#62240)
+    bytes);
+    return new Uint8Array(tag);
+}
+/**
+ * Constant-time byte comparison. A non-constant comparison would leak
+ * the position of the first mismatched byte through a timing side
+ * channel. The XOR accumulate is branch-free over the byte range; the
+ * only early return is on a length mismatch, which is not secret-
+ * dependent.
+ */
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let acc = 0;
+    for (let i = 0; i < a.length; i++) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- i is bounds-checked by the loop guard and a.length === b.length above
+        acc |= a[i] ^ b[i];
+    }
+    return acc === 0;
+}
+/**
+ * Verify an HMAC tag by recomputing it and comparing in constant time.
+ * Deliberately avoids `subtle.verify`, whose constant-time behavior the
+ * Web Crypto spec does not guarantee; this channel owns that property
+ * via `constantTimeEqual`.
+ */
+export async function verifyHmac(bytes, tag, key) {
+    if (tag.length !== HMAC_TAG_BYTES) {
+        throw new Error(`IPC HMAC tag must be ${HMAC_TAG_BYTES} bytes, got ${tag.length}`);
+    }
+    const expected = await signHmac(bytes, key);
+    return constantTimeEqual(expected, tag);
+}
+export const IPC_CRYPTO = Object.freeze({
+    ED25519_SIGNATURE_BYTES,
+    ED25519_KEY_BYTES,
+    HMAC_KEY_BYTES,
+    HMAC_TAG_BYTES,
+    CHANNEL_ID_BYTES,
+});

package/dist/ipc/envelope.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Validator for the inner envelope shape. `payload` is `unknown` here
+ * because each channel narrows it further via its own typed schema
+ * (control payload union vs. InferenceEvent forwarded over event).
+ */
+export declare const FrameEnvelope: import("arktype/internal/variants/object.ts").ObjectType<{
+    seq: number;
+    channelId: string;
+    payload: unknown;
+}, {}>;
+export type FrameEnvelope = typeof FrameEnvelope.infer;
+/**
+ * Validator for the signed envelope wire shape. `sig` carries the
+ * hex-encoded Ed25519 signature (128 hex chars / 64 bytes).
+ */
+export declare const SignedEnvelope: import("arktype/internal/variants/object.ts").ObjectType<{
+    envelope: {
+        seq: number;
+        channelId: string;
+        payload: unknown;
+    };
+    sig: string;
+}, {}>;
+export type SignedEnvelope = typeof SignedEnvelope.infer;
+/**
+ * Validator for the MACed envelope wire shape. `mac` carries the
+ * hex-encoded HMAC-SHA256 tag (64 hex chars / 32 bytes).
+ */
+export declare const MacedEnvelope: import("arktype/internal/variants/object.ts").ObjectType<{
+    envelope: {
+        seq: number;
+        channelId: string;
+        payload: unknown;
+    };
+    mac: string;
+}, {}>;
+export type MacedEnvelope = typeof MacedEnvelope.infer;
+/**
+ * Produce the canonical byte serialization of an envelope. The
+ * sender signs these bytes; the receiver verifies against these
+ * bytes. Both sides reach the same bytestring deterministically
+ * because the JSON serialization runs in insertion order over a
+ * fixed-shape object.
+ */
+export declare function encodeEnvelope(envelope: FrameEnvelope): Uint8Array;
+/**
+ * Parse a canonical envelope byte serialization back into the
+ * structured shape. Used on the receiver side after the per-frame
+ * MAC/signature check passes -- a structural failure on a frame
+ * whose authentication tag matched is a programming bug at the
+ * sender, not a tampering signal.
+ */
+export declare function decodeEnvelope(bytes: Uint8Array): FrameEnvelope;

package/dist/ipc/envelope.js

@@ -0,0 +1,88 @@
+// Frame envelope shared by both IPC channels.
+//
+// Every signed/HMACed frame carries `{ seq, channelId, payload }`
+// inside the bytes the receiver authenticates. `seq` is a monotonic
+// u64 counter the sender maintains per channel; `channelId` is the
+// 16-byte hex identity the supervisor mints at every spawn and rotates
+// at every recycle; `payload` is the channel-specific JSON value.
+//
+// Wire shape on disk for the control channel: one NDJSON line per
+// frame, each line `{ envelope: <canonical-json-of-envelope>, sig:
+// <hex Ed25519 signature> }`. For the event channel: a 4-byte big-
+// endian length prefix, then `{ envelope, mac }` JSON in the same
+// shape with `mac` carrying the hex HMAC tag. Both wires sign the
+// canonical-JSON serialization of the envelope as a single bytestring.
+// The on-wire byte representation of the envelope is exactly what the
+// signer signs and the verifier verifies.
+//
+// Canonical JSON: keys appear in fixed insertion order (seq,
+// channelId, payload). The payload's internal structure is preserved
+// as the sender produced it; no recursive canonicalization is
+// performed because the verifier never compares two structurally
+// different serializations of the same logical value. Senders and
+// receivers see the same bytes by construction (sender computes the
+// signature over the exact serialization it then transmits; receiver
+// verifies the signature over the exact bytes it received).
+import { type } from "arktype";
+/**
+ * Validator for the inner envelope shape. `payload` is `unknown` here
+ * because each channel narrows it further via its own typed schema
+ * (control payload union vs. InferenceEvent forwarded over event).
+ */
+export const FrameEnvelope = type({
+    seq: "number",
+    channelId: "string",
+    payload: "unknown",
+});
+/**
+ * Validator for the signed envelope wire shape. `sig` carries the
+ * hex-encoded Ed25519 signature (128 hex chars / 64 bytes).
+ */
+export const SignedEnvelope = type({
+    envelope: FrameEnvelope,
+    sig: "string",
+});
+/**
+ * Validator for the MACed envelope wire shape. `mac` carries the
+ * hex-encoded HMAC-SHA256 tag (64 hex chars / 32 bytes).
+ */
+export const MacedEnvelope = type({
+    envelope: FrameEnvelope,
+    mac: "string",
+});
+/**
+ * Produce the canonical byte serialization of an envelope. The
+ * sender signs these bytes; the receiver verifies against these
+ * bytes. Both sides reach the same bytestring deterministically
+ * because the JSON serialization runs in insertion order over a
+ * fixed-shape object.
+ */
+export function encodeEnvelope(envelope) {
+    const ordered = {
+        seq: envelope.seq,
+        channelId: envelope.channelId,
+        payload: envelope.payload,
+    };
+    return new TextEncoder().encode(JSON.stringify(ordered));
+}
+/**
+ * Parse a canonical envelope byte serialization back into the
+ * structured shape. Used on the receiver side after the per-frame
+ * MAC/signature check passes -- a structural failure on a frame
+ * whose authentication tag matched is a programming bug at the
+ * sender, not a tampering signal.
+ */
+export function decodeEnvelope(bytes) {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch (cause) {
+        throw new Error("IPC envelope bytes are not valid JSON", { cause });
+    }
+    const validated = FrameEnvelope(parsed);
+    if (validated instanceof type.errors) {
+        throw new Error(`IPC envelope failed validation: ${validated.summary}`);
+    }
+    return validated;
+}