@bifrost-ai/protocol 0.1.1-build.1783029473245

package/README.md

@@ -0,0 +1,177 @@
+# @bifrost-ai/protocol
+
+Signed WebSocket RPC transport for runner ↔ orchestrator communication in Bifrost v2.
+
+This package is the **only** wire interface between runners and the orchestrator. There is no in-process direct-call variant — a co-located runner still dials the orchestrator over WebSocket.
+
+Design background: [docs/protocol.md](../../docs/protocol.md) · Issue [#33](https://github.com/devzeebo/bifrost/issues/33)
+
+## Purpose
+
+v2 splits task execution onto remote runners. This package provides:
+
+1. **ed25519 signing and verification** using Node built-in `crypto`
+2. **Deterministic JSON canonicalization** so signers and verifiers agree on signing material
+3. **WebSocket frame encoding/decoding** with envelope validation
+4. **Peer abstractions** for orchestrator (server) and runner (client) roles
+
+Cryptography is intentionally folded into this package rather than living in a separate `crypto` package.
+
+## Public API
+
+### Key management (`keys.ts`)
+
+```typescript
+generateKeyPair(keyId?: string): PeerIdentity
+loadKeyPair({ privateKeyPem, publicKeyPem, keyId }): PeerIdentity
+exportPublicKeyPem(publicKey): string
+exportPrivateKeyPem(privateKey): string
+fingerprintPublicKey(publicKey): string  // sha256(SPKI) → base64url, 16 chars
+```
+
+`PeerIdentity` is `{ keyId, publicKey, privateKey }`. When `keyId` is omitted from `generateKeyPair`, it defaults to the public key fingerprint.
+
+### Signing (`sign.ts`)
+
+```typescript
+signPayload(payload, identity, timestamp?): SignedEnvelope
+verifyEnvelope(envelope, trustedPublicKeys): boolean
+buildSigningMaterial(unsignedEnvelope): string
+```
+
+`signPayload` wraps a `FramePayload` in a `SignedEnvelope`. `verifyEnvelope` checks the signature against `trustedPublicKeys.get(envelope.keyId)`. Returns `false` on any mismatch — wrong algorithm, unknown keyId, bad base64, or signature failure.
+
+### Canonicalization (`canonicalize.ts`)
+
+```typescript
+canonicalize(value: unknown): string  // JSON.stringify with sorted object keys
+```
+
+Recursively sorts object keys before `JSON.stringify`. This ensures that `{ b: 1, a: 2 }` and `{ a: 2, b: 1 }` produce identical signing material. Arrays preserve element order.
+
+Signing material is the canonical JSON of:
+
+```json
+{ "algorithm": "ed25519", "keyId": "...", "payload": { ... }, "timestamp": 1234567890 }
+```
+
+### Frames (`frames.ts`)
+
+```typescript
+encodeEnvelope(envelope: SignedEnvelope): string   // JSON.stringify
+decodeEnvelope(raw: string): SignedEnvelope | null
+isFramePayload(value: unknown): value is FramePayload
+```
+
+`decodeEnvelope` returns `null` for malformed JSON, missing fields, or invalid payload kinds. It does not verify signatures — that happens in the connection layer.
+
+### Connection (`connection.ts`)
+
+```typescript
+createProtocolConnection(socket, { identity, trustedPublicKeys, onClose? }): ProtocolConnection
+toConnectedPeer(peerId, connection): ConnectedPeer
+```
+
+`createProtocolConnection` wraps a raw `ws` WebSocket:
+
+- **Inbound:** decode envelope → verify signature → validate payload kind → dispatch to subscribers matching their filter.
+- **Outbound:** sign payload with local identity → encode envelope → `socket.send`.
+- Invalid or untrusted frames are silently dropped (no error frame).
+- `onClose` fires once when the socket closes or errors.
+
+### Peers
+
+**Orchestrator** (`orchestrator.ts`):
+
+```typescript
+createOrchestratorPeer({ identity, trustedPublicKeys, host?, port? }): Promise<OrchestratorPeer>
+```
+
+- Creates a `WebSocketServer`. `port: 0` binds an ephemeral port.
+- Assigns each connection an opaque `peerId` (UUID).
+- `onPeerConnect` fires for new and already-connected peers.
+- `onPeerDisconnect` fires when a peer's socket closes.
+- `send(peerId, payload)` throws if peerId is unknown.
+
+**Runner** (`runner.ts`):
+
+```typescript
+createRunnerPeer({ identity, trustedPublicKeys, url }): Promise<RunnerPeer>
+```
+
+- Dials the orchestrator URL.
+- Resolves when the WebSocket `open` event fires.
+- Same subscribe/send/close API as `ProtocolConnection`.
+
+## Frame payload types
+
+```typescript
+type RpcRequest = { kind: "rpc.request"; id: string; method: string; params: unknown };
+type RpcResponse = {
+  kind: "rpc.response";
+  id: string;
+  result?: unknown;
+  error?: { code; message };
+};
+type RpcStreamEvent = {
+  kind: "rpc.stream";
+  id: string;
+  seq: number;
+  event: "data" | "end" | "error";
+  data?;
+  error?;
+};
+type Heartbeat = { kind: "heartbeat"; runnerId: string };
+```
+
+`rpc.stream` supports ordered streaming responses. The orchestrator package does not use streaming today, but the protocol supports it for future methods.
+
+## Trust model
+
+Both sides maintain a `trustedPublicKeys: Map<keyId, KeyObject>`:
+
+- The **orchestrator** trusts runner public keys (loaded from static config).
+- The **runner** trusts the orchestrator's public key.
+
+Every inbound frame is verified against this map. There is no handshake or key exchange at connection time — keys must be pre-shared. An unknown `keyId` causes the frame to be dropped.
+
+## Wire format example
+
+A heartbeat from a runner looks like this on the wire (one WebSocket text frame):
+
+```json
+{
+  "payload": { "kind": "heartbeat", "runnerId": "runner" },
+  "signature": "base64...",
+  "keyId": "runner",
+  "algorithm": "ed25519",
+  "timestamp": 1719900000000
+}
+```
+
+## Module layout
+
+```
+src/
+  canonicalize.ts   Deterministic JSON serialization
+  connection.ts     WebSocket ↔ signed frame bridge
+  frames.ts         Encode/decode/validate envelopes
+  keys.ts           ed25519 keypair generation and PEM export
+  orchestrator.ts   WebSocket server peer
+  runner.ts         WebSocket client peer
+  sign.ts           Sign and verify envelopes
+  types.ts          Frame and peer type definitions
+```
+
+## Tests
+
+- `sign.spec.ts` — round-trip, tamper, wrong key, non-canonical material
+- `canonicalize.spec.ts` — key ordering stability
+- `loopback.spec.ts` — real WebSocket server+client: RPC round-trip, streaming, disconnect, tampered frame rejection
+
+Run with `vp test` from this package directory.
+
+## Dependencies
+
+- `ws` — WebSocket implementation
+- `node:crypto` — ed25519 key generation, sign, verify (no external crypto libraries)

package/dist/index.d.mts

@@ -0,0 +1,138 @@
+import { KeyObject } from "node:crypto";
+import { WebSocket as WebSocket$1 } from "ws";
+
+//#region src/canonicalize.d.ts
+declare function canonicalize(value: unknown): string;
+//#endregion
+//#region src/types.d.ts
+type RpcRequest = {
+  kind: "rpc.request";
+  id: string;
+  method: string;
+  params: unknown;
+};
+type RpcResponse = {
+  kind: "rpc.response";
+  id: string;
+  result?: unknown;
+  error?: {
+    code: string;
+    message: string;
+  };
+};
+type RpcStreamEvent = {
+  kind: "rpc.stream";
+  id: string;
+  seq: number;
+  event: "data" | "end" | "error";
+  data?: unknown;
+  error?: {
+    code: string;
+    message: string;
+  };
+};
+type Heartbeat = {
+  kind: "heartbeat";
+  runnerId: string;
+};
+type FramePayload = RpcRequest | RpcResponse | RpcStreamEvent | Heartbeat;
+declare const SIGNING_ALGORITHM: "ed25519";
+type SignedEnvelope<T = FramePayload> = {
+  payload: T;
+  signature: string;
+  keyId: string;
+  algorithm: typeof SIGNING_ALGORITHM;
+  timestamp: number;
+};
+type UnsignedEnvelope<T = FramePayload> = {
+  payload: T;
+  keyId: string;
+  algorithm: typeof SIGNING_ALGORITHM;
+  timestamp: number;
+};
+type RunnerPeer = {
+  subscribe(filter: (payload: FramePayload) => boolean, callback: (payload: FramePayload) => void): () => void;
+  send(payload: FramePayload): void;
+  close(): void;
+};
+type ConnectedPeer = {
+  readonly peerId: string;
+  subscribe(filter: (payload: FramePayload) => boolean, callback: (payload: FramePayload) => void): () => void;
+  send(payload: FramePayload): void;
+  close(): void;
+};
+type OrchestratorPeer = {
+  readonly address: {
+    host: string;
+    port: number;
+  };
+  onPeerConnect(callback: (peer: ConnectedPeer) => void): () => void;
+  onPeerDisconnect(callback: (peer: ConnectedPeer) => void): () => void;
+  send(peerId: string, payload: FramePayload): void;
+  close(): void;
+};
+type PeerIdentity = {
+  keyId: string;
+  publicKey: import("node:crypto").KeyObject;
+  privateKey: import("node:crypto").KeyObject;
+};
+type PeerOptions = {
+  identity: PeerIdentity;
+  trustedPublicKeys: ReadonlyMap<string, import("node:crypto").KeyObject>;
+};
+type CreateRunnerPeerOptions = PeerOptions & {
+  url: string;
+};
+type CreateOrchestratorPeerOptions = PeerOptions & {
+  port?: number;
+  host?: string;
+};
+//#endregion
+//#region src/connection.d.ts
+type ProtocolConnectionOptions = {
+  identity: PeerIdentity;
+  trustedPublicKeys: ReadonlyMap<string, KeyObject>;
+  onClose?: () => void;
+};
+type ProtocolConnection = {
+  subscribe(filter: (payload: FramePayload) => boolean, callback: (payload: FramePayload) => void): () => void;
+  send(payload: FramePayload): void;
+  close(): void;
+};
+declare function createProtocolConnection(socket: WebSocket$1, options: ProtocolConnectionOptions): ProtocolConnection;
+declare function toConnectedPeer(peerId: string, connection: ProtocolConnection): ConnectedPeer;
+//#endregion
+//#region src/frames.d.ts
+declare function encodeEnvelope(envelope: SignedEnvelope): string;
+declare function decodeEnvelope(raw: string): SignedEnvelope | null;
+declare function isFramePayload(value: unknown): value is FramePayload;
+//#endregion
+//#region src/keys.d.ts
+type LoadKeyPairOptions = {
+  privateKeyPem: string;
+  publicKeyPem: string;
+  keyId: string;
+};
+declare function fingerprintPublicKey(publicKey: KeyObject): string;
+declare function generateKeyPair(keyId?: string): PeerIdentity;
+declare function loadKeyPair(options: LoadKeyPairOptions): PeerIdentity;
+declare function loadTrustedPublicKey(options: {
+  keyId: string;
+  publicKeyPem: string;
+}): ReadonlyMap<string, KeyObject>;
+declare function exportPublicKeyPem(publicKey: KeyObject): string;
+declare function exportPrivateKeyPem(privateKey: KeyObject): string;
+//#endregion
+//#region src/orchestrator.d.ts
+declare function createOrchestratorPeer(options: CreateOrchestratorPeerOptions): Promise<OrchestratorPeer>;
+//#endregion
+//#region src/runner.d.ts
+declare function createRunnerPeer(options: CreateRunnerPeerOptions): Promise<RunnerPeer>;
+//#endregion
+//#region src/sign.d.ts
+declare function buildSigningMaterial(envelope: UnsignedEnvelope): string;
+declare function signPayload(payload: FramePayload, identity: PeerIdentity, timestamp?: number): SignedEnvelope;
+declare function verifyEnvelope(envelope: SignedEnvelope, trustedPublicKeys: ReadonlyMap<string, KeyObject>): boolean;
+declare function signRawMaterial(material: string, identity: PeerIdentity): string;
+//#endregion
+export { type ConnectedPeer, type CreateOrchestratorPeerOptions, type CreateRunnerPeerOptions, type FramePayload, type Heartbeat, type LoadKeyPairOptions, type OrchestratorPeer, type PeerIdentity, type PeerOptions, type ProtocolConnection, type ProtocolConnectionOptions, type RpcRequest, type RpcResponse, type RpcStreamEvent, type RunnerPeer, SIGNING_ALGORITHM, type SignedEnvelope, type UnsignedEnvelope, buildSigningMaterial, canonicalize, createOrchestratorPeer, createProtocolConnection, createRunnerPeer, decodeEnvelope, encodeEnvelope, exportPrivateKeyPem, exportPublicKeyPem, fingerprintPublicKey, generateKeyPair, isFramePayload, loadKeyPair, loadTrustedPublicKey, signPayload, signRawMaterial, toConnectedPeer, verifyEnvelope };

package/dist/index.mjs

@@ -0,0 +1,299 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign, verify } from "node:crypto";
+import WebSocket, { WebSocketServer } from "ws";
+//#region src/canonicalize.ts
+function canonicalize(value) {
+	return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+	if (Array.isArray(value)) return value.map(sortKeys);
+	if (value !== null && typeof value === "object") {
+		const record = value;
+		const sorted = {};
+		for (const key of Object.keys(record).sort()) sorted[key] = sortKeys(record[key]);
+		return sorted;
+	}
+	return value;
+}
+//#endregion
+//#region src/frames.ts
+function encodeEnvelope(envelope) {
+	return JSON.stringify(envelope);
+}
+function decodeEnvelope(raw) {
+	try {
+		const parsed = JSON.parse(raw);
+		if (!isSignedEnvelope(parsed)) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+function isFramePayload(value) {
+	if (value === null || typeof value !== "object" || !("kind" in value)) return false;
+	const record = value;
+	switch (record.kind) {
+		case "rpc.request": return typeof record.id === "string" && typeof record.method === "string" && "params" in record;
+		case "rpc.response": return typeof record.id === "string";
+		case "rpc.stream": return typeof record.id === "string" && typeof record.seq === "number" && (record.event === "data" || record.event === "end" || record.event === "error");
+		case "heartbeat": return typeof record.runnerId === "string";
+		default: return false;
+	}
+}
+function isSignedEnvelope(value) {
+	if (value === null || typeof value !== "object") return false;
+	const envelope = value;
+	return typeof envelope.signature === "string" && typeof envelope.keyId === "string" && envelope.algorithm === "ed25519" && typeof envelope.timestamp === "number" && envelope.payload !== void 0 && isFramePayload(envelope.payload);
+}
+//#endregion
+//#region src/types.ts
+const SIGNING_ALGORITHM = "ed25519";
+//#endregion
+//#region src/sign.ts
+function buildSigningMaterial(envelope) {
+	return canonicalize({
+		algorithm: envelope.algorithm,
+		keyId: envelope.keyId,
+		payload: envelope.payload,
+		timestamp: envelope.timestamp
+	});
+}
+function signPayload(payload, identity, timestamp = Date.now()) {
+	const unsigned = {
+		algorithm: SIGNING_ALGORITHM,
+		keyId: identity.keyId,
+		payload,
+		timestamp
+	};
+	const material = buildSigningMaterial(unsigned);
+	const signature = sign(null, Buffer.from(material, "utf8"), identity.privateKey);
+	return {
+		...unsigned,
+		signature: signature.toString("base64")
+	};
+}
+function verifyEnvelope(envelope, trustedPublicKeys) {
+	if (envelope.algorithm !== "ed25519") return false;
+	const publicKey = trustedPublicKeys.get(envelope.keyId);
+	if (publicKey === void 0) return false;
+	const material = buildSigningMaterial({
+		algorithm: envelope.algorithm,
+		keyId: envelope.keyId,
+		payload: envelope.payload,
+		timestamp: envelope.timestamp
+	});
+	let signature;
+	try {
+		signature = Buffer.from(envelope.signature, "base64");
+	} catch {
+		return false;
+	}
+	return verify(null, Buffer.from(material, "utf8"), publicKey, signature);
+}
+function signRawMaterial(material, identity) {
+	return sign(null, Buffer.from(material, "utf8"), identity.privateKey).toString("base64");
+}
+//#endregion
+//#region src/connection.ts
+function createProtocolConnection(socket, options) {
+	const subscribers = /* @__PURE__ */ new Set();
+	let closed = false;
+	const handleMessage = (data) => {
+		if (closed) return;
+		const envelope = decodeEnvelope(Buffer.isBuffer(data) ? data.toString("utf8") : Buffer.from(data).toString("utf8"));
+		if (envelope === null) return;
+		if (!verifyEnvelope(envelope, options.trustedPublicKeys)) return;
+		if (!isFramePayload(envelope.payload)) return;
+		const payload = envelope.payload;
+		for (const subscriber of subscribers) if (subscriber.filter(payload)) subscriber.callback(payload);
+	};
+	const handleClose = () => {
+		if (closed) return;
+		closed = true;
+		socket.removeListener("message", handleMessage);
+		socket.removeListener("close", handleClose);
+		subscribers.clear();
+		options.onClose?.();
+	};
+	socket.on("message", handleMessage);
+	socket.on("close", handleClose);
+	socket.on("error", () => {
+		handleClose();
+	});
+	return {
+		subscribe(filter, callback) {
+			const subscriber = {
+				filter,
+				callback
+			};
+			subscribers.add(subscriber);
+			return () => {
+				subscribers.delete(subscriber);
+			};
+		},
+		send(payload) {
+			if (closed || socket.readyState !== socket.OPEN) return;
+			const envelope = signPayload(payload, options.identity);
+			socket.send(encodeEnvelope(envelope));
+		},
+		close() {
+			if (closed) return;
+			closed = true;
+			socket.close();
+			handleClose();
+		}
+	};
+}
+function toConnectedPeer(peerId, connection) {
+	return {
+		peerId,
+		subscribe: connection.subscribe.bind(connection),
+		send: connection.send.bind(connection),
+		close: connection.close.bind(connection)
+	};
+}
+//#endregion
+//#region src/keys.ts
+function fingerprintPublicKey(publicKey) {
+	const der = publicKey.export({
+		format: "der",
+		type: "spki"
+	});
+	return createHash("sha256").update(der).digest("base64url").slice(0, 16);
+}
+function generateKeyPair(keyId) {
+	const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+	return {
+		keyId: keyId ?? fingerprintPublicKey(publicKey),
+		publicKey,
+		privateKey
+	};
+}
+function loadKeyPair(options) {
+	return {
+		keyId: options.keyId,
+		publicKey: createPublicKey(options.publicKeyPem),
+		privateKey: createPrivateKey(options.privateKeyPem)
+	};
+}
+function loadTrustedPublicKey(options) {
+	return new Map([[options.keyId, createPublicKey(options.publicKeyPem)]]);
+}
+function exportPublicKeyPem(publicKey) {
+	return publicKey.export({
+		format: "pem",
+		type: "spki"
+	}).toString();
+}
+function exportPrivateKeyPem(privateKey) {
+	return privateKey.export({
+		format: "pem",
+		type: "pkcs8"
+	}).toString();
+}
+//#endregion
+//#region src/orchestrator.ts
+function createOrchestratorPeer(options) {
+	return new Promise((resolve, reject) => {
+		const connectCallbacks = /* @__PURE__ */ new Set();
+		const disconnectCallbacks = /* @__PURE__ */ new Set();
+		const peers = /* @__PURE__ */ new Map();
+		let closed = false;
+		const wss = new WebSocketServer({
+			host: options.host ?? "127.0.0.1",
+			port: options.port ?? 0
+		});
+		wss.on("error", (error) => {
+			if (!closed) reject(error);
+		});
+		wss.on("listening", () => {
+			const address = wss.address();
+			if (address === null || typeof address === "string") {
+				reject(/* @__PURE__ */ new Error("WebSocket server address is unavailable"));
+				return;
+			}
+			resolve({
+				address: {
+					host: address.address === "::" || address.address === "0.0.0.0" ? "127.0.0.1" : address.address,
+					port: address.port
+				},
+				onPeerConnect(callback) {
+					connectCallbacks.add(callback);
+					for (const entry of peers.values()) callback(entry.peer);
+					return () => {
+						connectCallbacks.delete(callback);
+					};
+				},
+				onPeerDisconnect(callback) {
+					disconnectCallbacks.add(callback);
+					return () => {
+						disconnectCallbacks.delete(callback);
+					};
+				},
+				send(peerId, payload) {
+					const entry = peers.get(peerId);
+					if (entry === void 0) throw new Error(`Unknown peer id: ${peerId}`);
+					entry.connection.send(payload);
+				},
+				close() {
+					if (closed) return;
+					closed = true;
+					for (const entry of peers.values()) entry.connection.close();
+					peers.clear();
+					wss.close();
+				}
+			});
+		});
+		wss.on("connection", (socket) => {
+			if (closed) {
+				socket.close();
+				return;
+			}
+			const peerId = randomUUID();
+			const connection = createProtocolConnection(socket, {
+				identity: options.identity,
+				trustedPublicKeys: options.trustedPublicKeys,
+				onClose: () => {
+					const entry = peers.get(peerId);
+					if (entry === void 0) return;
+					peers.delete(peerId);
+					for (const callback of disconnectCallbacks) callback(entry.peer);
+				}
+			});
+			const peer = toConnectedPeer(peerId, connection);
+			peers.set(peerId, {
+				peer,
+				connection
+			});
+			for (const callback of connectCallbacks) callback(peer);
+		});
+	});
+}
+//#endregion
+//#region src/runner.ts
+function createRunnerPeer(options) {
+	return new Promise((resolve, reject) => {
+		const socket = new WebSocket(options.url);
+		const fail = (error) => {
+			socket.removeAllListeners();
+			reject(error);
+		};
+		socket.once("error", fail);
+		socket.once("open", () => {
+			socket.removeListener("error", fail);
+			socket.on("error", () => {
+				connection.close();
+			});
+			const connection = createProtocolConnection(socket, {
+				identity: options.identity,
+				trustedPublicKeys: options.trustedPublicKeys
+			});
+			resolve({
+				subscribe: connection.subscribe.bind(connection),
+				send: connection.send.bind(connection),
+				close: connection.close.bind(connection)
+			});
+		});
+	});
+}
+//#endregion
+export { SIGNING_ALGORITHM, buildSigningMaterial, canonicalize, createOrchestratorPeer, createProtocolConnection, createRunnerPeer, decodeEnvelope, encodeEnvelope, exportPrivateKeyPem, exportPublicKeyPem, fingerprintPublicKey, generateKeyPair, isFramePayload, loadKeyPair, loadTrustedPublicKey, signPayload, signRawMaterial, toConnectedPeer, verifyEnvelope };

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@bifrost-ai/protocol",
+  "version": "0.1.1-build.1783029473245",
+  "description": "Signed WebSocket RPC protocol for runner-orchestrator communication",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "@types/ws": "^8.18.1",
+    "@typescript/native-preview": "latest",
+    "bumpp": "^11.1.0",
+    "typescript": "^6.0.3",
+    "vite-plus": "^0.2.0",
+    "vitest-gwt": "^4.1.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}