@hyperfrontend/network-protocol§

What is @hyperfrontend/network-protocol?

You already have a transport: a WebSocket, postMessage to another window or a worker, a Node IPC pipe. What you do not have is the envelope to put on it. That is this library. Hand it a function that transmits bytes, a callback for delivered messages, a protocol provider, and the session the two ends agreed on, and you get a channel back.

Each end mints a random nonce and an ephemeral P-256 key pair, advertises them in a 99-byte hello frame, and derives two AES-GCM-256 keys from the agreement, one per direction. Every message is sealed under the sending key with a counter that serves as the nonce and as the replay check; every inbound frame is opened under the receiving key and arrives as a typed packet with an origin, a target, and a payload that has already been checked for the fields it claims to have.

Two protocols share that wire format. v3 keys the session from the agreement alone, which defeats anything that can only listen. v4 mixes a pre-shared key into the schedule, stretched once per session, so a script without the key can neither read frames nor produce frames the counterpart accepts.

Outbound and inbound are each one FIFO stage that finishes a frame before pulling the next, so the async crypto cannot reorder your sends, and either direction can be stopped and resumed. A frame that fails to open (replayed, forged, malformed, from another session) is dropped inside its stage, reported through onDrop with a machine-readable code, and leaves the rest of the pipeline running.

Most projects should not start here. For typed, contract-checked messages between windows, use @hyperfrontend/nexus, which registers this library's exports as a security provider and owns the handshake, the origin policy, the hello retries, and the connection lifecycle. To compose whole applications into a host page, use @hyperfrontend/features, which sits above nexus. Come here directly when you own the transport and want the envelope on your own terms.

At a glance, the page side of a page-to-worker link:

import { logger } from '@hyperfrontend/logging'
import { createChannel } from '@hyperfrontend/network-protocol/browser/channel'
import { createData, deserializeData } from '@hyperfrontend/network-protocol/browser/data'
import { createProtocol } from '@hyperfrontend/network-protocol/browser/v3'

const worker = new Worker('./peer.js')
const pageId = crypto.randomUUID()
const workerId = crypto.randomUUID()

const channel = createChannel('worker-bridge', {
  send: (frame) => worker.postMessage(frame, [frame.buffer]), // your transport, outbound
  receive: (packet) => render(packet.origin, packet.data.message), // opened, validated, in order
  protocolProvider: createProtocol(logger),
  session: {
    protocol: 'v3',
    role: 'initiator',
    localId: pageId,
    peerId: workerId,
  },
})

worker.addEventListener('message', ({ data }) => {
  if (channel.isHello(data))
    channel.acceptHello(data) // the worker's public material keys the session
  else channel.receive(data) // everything else is a sealed frame
})
worker.postMessage(await channel.hello()) // this side's public material, in the clear by design

// pid is a UUID v4 naming the conversation, 1 is the step number within it
const pid = crypto.randomUUID()
const data = deserializeData(await createData(pid, 1, { type: 'PING' }))
channel.send(pageId, workerId, data) // waits inside the seal stage until the worker's hello has arrived

The worker mirrors this with role: 'responder' and the two identities swapped; how the identities reach it is up to your transport (nexus carries them in its handshake).

Key Features

Why Use @hyperfrontend/network-protocol?

You own the transport and do not want to invent the envelope

Raw postMessage and IPC give you bytes and nothing else. Everything above them is yours to build: a key exchange, a framing format, replay protection, something that stops two overlapping crypto calls from delivering your messages out of order, and a shape check so a malformed payload never reaches a handler. That layer is small enough to write and easy to get subtly wrong. It is the part this library ships, and it is the only part it ships. Your socket, your window, your pipe stays yours.

A real key schedule, and you can read all of it

Each side contributes a 32-byte nonce and an ephemeral P-256 public key in its hello. The salt is the two nonces in role order, the input key material is the ECDH shared secret (v3) or the shared secret followed by a PBKDF2 stretch of the pre-shared key (v4), and two keys come out of HKDF-SHA256 under info strings that name the protocol and both identities. Each side seals with its own direction's key and opens with the other's, raw material is zeroed after derivation, and the AES-GCM nonce is the frame counter, unique by construction. What each protocol promises is stated claim by claim in the architecture guide; neither hides the hello, because public keys and nonces are public by design.

Ordering and backpressure come from the queues, not from a promise

Each direction is one FIFO stage that awaits one frame before pulling the next, so crypto timing cannot shuffle your sends and the replay counter stays exact. channel.stop() pauses both directions, channel.resume() drains them, and channel.outbound.queue.size tells you how far behind you are. Failures are contained: a packet that will not seal or a frame that will not open fails inside its stage, goes to the logger you injected and to onDrop, and the channel keeps running.

The same code in a browser and in Node

/browser/* and /node/* export the same functions with the same signatures. Only the crypto and text-codec injection differ, so an Electron main process and its renderer, or a page and a worker, can share channel and routing code and swap one import. A session keyed by a browser-composed initiator and a Node-composed responder works, because both sides derive the same keys from the same bytes.

Installation

npm install @hyperfrontend/network-protocol

Requirements

• Node.js: 18.0.0 or higher (19+ recommended for stable Web Crypto API support)
• npm: 8.0.0 or higher
• Browser: Modern browsers with Web Crypto API support

Note: The /node/* entry points depend on @hyperfrontend/cryptography which uses webcrypto.subtle. This API was experimental in Node.js 18.x. For production use with Node.js entry points, Node.js 19+ is recommended.

Quick Start

A session needs two things agreed before it starts: which side is the initiator and which the responder, and the two identities (localId on one side is peerId on the other). Both are bound into the derived keys. Identities are public; here the host picks them and tells the guest in plaintext.

Browser: cross-window messages with v4

The host, in the top window:

import { logger } from '@hyperfrontend/logging'
import { createChannel } from '@hyperfrontend/network-protocol/browser/channel'
import { createData, deserializeData } from '@hyperfrontend/network-protocol/browser/data'
import { createProtocol } from '@hyperfrontend/network-protocol/browser/v4'

const guest = document.querySelector('iframe').contentWindow
const guestOrigin = 'https://app.example.com'
const hostId = crypto.randomUUID()
const guestId = crypto.randomUUID()

// createProtocol(logger, sharedKey) returns a provider; the key must be at least 16 characters and should be generated, not chosen
const channel = createChannel('window-link', {
  send: (frame) => guest.postMessage(frame, guestOrigin, [frame.buffer]),
  receive: (packet) => console.log('from', packet.origin, packet.data.message),
  protocolProvider: createProtocol(logger, sharedKey),
  session: {
    protocol: 'v4',
    role: 'initiator',
    localId: hostId,
    peerId: guestId,
  },
})

window.addEventListener('message', ({ origin, data }) => {
  if (origin !== guestOrigin) return
  if (channel.isHello(data)) channel.acceptHello(data)
  else channel.receive(data)
})

guest.postMessage({ hostId, guestId }, guestOrigin) // identities, in the clear
guest.postMessage(await channel.hello(), guestOrigin) // public material, in the clear

// the pid stays the same across the steps of one conversation, the sequence number counts them
const pid = crypto.randomUUID()
const data = deserializeData(await createData(pid, 1, { greeting: 'Hello' }))
channel.send(hostId, guestId, data) // sealed once the guest's hello has keyed the session

// pause and drain either direction
channel.stop()
channel.resume()

The guest, inside the iframe:

import type { Channel } from '@hyperfrontend/network-protocol/browser/channel'
import { logger } from '@hyperfrontend/logging'
import { createChannel } from '@hyperfrontend/network-protocol/browser/channel'
import { createProtocol } from '@hyperfrontend/network-protocol/browser/v4'

const hostOrigin = 'https://host.example.com'
let channel: Channel | null = null

window.addEventListener('message', ({ origin, data }) => {
  if (origin !== hostOrigin) return
  if (channel === null) {
    // the first message carries the identities; everything after it is a frame
    const { hostId, guestId } = data
    channel = createChannel('window-link', {
      send: (frame) => window.parent.postMessage(frame, hostOrigin, [frame.buffer]),
      receive: (packet) => console.log('from', packet.origin, packet.data.message),
      protocolProvider: createProtocol(logger, sharedKey),
      session: {
        protocol: 'v4',
        role: 'responder',
        localId: guestId,
        peerId: hostId,
      },
    })
    channel.hello().then((hello) => window.parent.postMessage(hello, hostOrigin))
    return
  }
  if (channel.isHello(data)) channel.acceptHello(data)
  else channel.receive(data)
})

A guest holding a different key derives different keys: every frame from the host fails to authenticate and is reported through onDrop with code authentication-failed, and nothing is delivered.

Node.js: the same channel between threads with v3

The main thread:

import { randomUUID } from 'node:crypto'
import { Worker } from 'node:worker_threads'
import { logger } from '@hyperfrontend/logging'
import { createChannel } from '@hyperfrontend/network-protocol/node/channel'
import { createData, deserializeData } from '@hyperfrontend/network-protocol/node/data'
import { createProtocol } from '@hyperfrontend/network-protocol/node/v3'

const mainId = randomUUID()
const workerId = randomUUID()
const worker = new Worker('./worker.js', { workerData: { mainId, workerId } })

const channel = createChannel('thread-link', {
  send: (frame) => worker.postMessage(frame, [frame.buffer]),
  receive: (packet) => handle(packet.data.message),
  protocolProvider: createProtocol(logger),
  session: {
    protocol: 'v3',
    role: 'initiator',
    localId: mainId,
    peerId: workerId,
  },
})

worker.on('message', (frame: Uint8Array) => (channel.isHello(frame) ? channel.acceptHello(frame) : channel.receive(frame)))
worker.postMessage(await channel.hello())

const data = deserializeData(
  await createData(randomUUID(), 1, {
    job: 'resize',
    file: 'a.png',
  })
)
channel.send(mainId, workerId, data)

The worker (worker.js):

import { parentPort, workerData } from 'node:worker_threads'
import { logger } from '@hyperfrontend/logging'
import { createChannel } from '@hyperfrontend/network-protocol/node/channel'
import { createProtocol } from '@hyperfrontend/network-protocol/node/v3'

const { mainId, workerId } = workerData

const channel = createChannel('thread-link', {
  send: (frame) => parentPort.postMessage(frame, [frame.buffer]),
  receive: (packet) => handle(packet.data.message),
  protocolProvider: createProtocol(logger),
  session: {
    protocol: 'v3',
    role: 'responder',
    localId: workerId,
    peerId: mainId,
  },
})

parentPort.on('message', (frame: Uint8Array) => (channel.isHello(frame) ? channel.acceptHello(frame) : channel.receive(frame)))
parentPort.postMessage(await channel.hello())

Hello frames are posted by copy and sealed frames by transfer: the protocol hands out the same hello bytes on every call, so a transport may re-post it until the counterpart answers, while each sealed frame owns its buffer and is never needed again once sent.

API Overview

Nothing is exported from the package root: every import names a subpath, and the subpaths sit on two axes. One is the platform that supplies the crypto and text primitives, /browser or /node. The other is the protocol version that keys the session, /v3 or /v4. A browser subpath and its Node twin export the same names with the same signatures, and a session between the two works because both sides derive their keys from the same bytes, so moving code between a page and a worker, or between a renderer and a main process, is an edit to the import path and nothing else.

Two calls get a link running. createProtocol takes your logger, and on /v4 the pre-shared key as well, and hands back a provider. createChannel takes a label and an options object holding the send and receive callbacks that reach your transport, that provider, and the session the two ends agreed on.

const channel = createChannel(label, {
  send,
  receive,
  protocolProvider,
  session,
  onDrop,
})
// session: { protocol: 'v3' | 'v4', role: 'initiator' | 'responder', localId, peerId }

What comes back is a Channel, and for most code it is the only object in play: the hello exchange your transport carries, send(origin, target, data) for traffic, stop and resume for both directions at once, and outbound and inbound for per-direction queue depth. Nothing rejects. A frame that will not seal or will not open is dropped inside its own stage and reported to your onDrop as a PacketDrop, while the rest of the pipeline keeps running.

The version is the security decision, and it is the only thing that differs between /v3 and /v4. v3 keys the session from the ephemeral agreement alone, which defeats anything that can only listen but says nothing about who the counterpart is. v4 mixes in a pre-shared key, stretched once when the session is keyed, so a script without that key can neither read frames nor produce frames the far side accepts; it carries two extra exports for that key, isValidSharedKey and MIN_SHARED_KEY_LENGTH, and otherwise mirrors /v3. Both are built on the same session protocol: the hello exchange, the key schedule, and the seal and open pipeline.

Four subpaths name no platform because they hold no crypto. /queue is the FIFO stage both pipelines are built from, /routing and /topic are the pub/sub layer that names message categories and decides which channels a topic's messages reach, and /security holds the session types and the six ProtocolErrorCode values a drop can carry. The remaining per-platform subpaths are for taking one piece rather than a whole channel: /data builds the message envelope, stamping a conversation id, a sequence number and a schema hash onto your payload, /packet holds the packet builders and validators, and /sender and /receiver are the outbound and inbound halves on their own.

Every option, type and validator is in the API reference. The claims above are exercised end to end by the session envelope integration test, which wires two channels in memory over v3 and v4 and checks delivery in both directions, sealed bytes only on the wire, order across a burst, replay and foreign-session rejection reported as drops, a key mismatch delivering nothing, and a browser-composed side talking to a Node-composed side.

Compatibility

CDN Usage

This library provides separate bundles for each protocol; the package's default CDN file is the v4 UMD bundle:

<!-- v4 (the package default) -->
<script src="https://unpkg.com/@hyperfrontend/network-protocol/bundle/v4/index.umd.min.js"></script>

<!-- v3 -->
<script src="https://unpkg.com/@hyperfrontend/network-protocol/bundle/v3/index.umd.min.js"></script>

<script>
  // v4
  const { createProtocol: createV4 } = HyperfrontendNetworkProtocolV4

  // v3
  const { createProtocol: createV3 } = HyperfrontendNetworkProtocolV3
</script>

Global variables: HyperfrontendNetworkProtocolV3, HyperfrontendNetworkProtocolV4