# v3 Node.js-side v3 protocol: a session-keyed envelope with no shared secret, wired to the Node.js crypto module. ## Overview `createProtocol(logger)` returns a [`ProtocolProvider`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/#api-ProtocolProvider). Bound to a session by [`createChannel`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/#api-createChannel), each instance mints a random 32-byte nonce and an ephemeral P-256 key pair and advertises them in a 99-byte hello frame (`channel.hello()`); the peer's hello goes to `channel.acceptHello(frame)`, after which two AES-GCM-256 keys, one per direction, are derived from the agreement with HKDF-SHA256 under info strings that name the protocol and both identities. The first hello keys the session, a byte-for-byte repeat of it is a duplicate, anything else is rejected, and a live session is never rekeyed. Every sealed frame carries its counter in the clear as the nonce and authenticates its ten-byte header; a frame whose counter is not above the last accepted one is rejected before decryption, and a frame from any other session fails to authenticate. [`V3`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/node/v3/#api-V3) is the protocol's definition, `{ id: 'v3', version: 3 }`: the identifier a session names and the byte every frame starts with. ## What v3 protects against A party that can only listen to the hello exchange and the traffic cannot read or forge frames. A party that can post its own hello before the peer's arrives can complete a v3 handshake as that peer, because nothing authenticates who said hello. Choose [`/node/v4`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/node/v4.md) when the counterpart must be authenticated. Neither protocol hides the hello: nonces and public keys are public by design. ## Usage ```typescript import { parentPort } from 'node:worker_threads' import { createProtocol } from '@hyperfrontend/network-protocol/node/v3' import { createChannel } from '@hyperfrontend/network-protocol/node/channel' import { createLogger } from '@hyperfrontend/logging' const channel = createChannel('main-to-worker', { send: (frame) => parentPort.postMessage(frame, [frame.buffer]), receive: (packet) => handle(packet.data.message), protocolProvider: createProtocol(createLogger({ level: 'info' })), session: { protocol: 'v3', role: 'responder', localId, peerId }, }) parentPort.postMessage(await channel.hello()) parentPort.on('message', (frame: Uint8Array) => (channel.isHello(frame) ? channel.acceptHello(frame) : channel.receive(frame))) ``` ## Notes - Session setup costs one ECDH agreement plus one HKDF expansion per direction; each frame costs one AES-GCM operation. Keys are derived once, on the first seal or open after the peer's hello is accepted, and product traffic sent before then waits inside the seal stage. - A rejected frame reaches [`onDrop`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/#api-ChannelOptions-prop-onDrop) with a [`ProtocolError`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/security/#api-ProtocolError) as [`cause`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/#api-PacketDrop-prop-cause); `getProtocolErrorCode(drop.cause)` from [`/security`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/security.md) names the reason (`unsupported-version`, [`replayed`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/security/#api-ProtocolErrorCode), `authentication-failed`, [`malformed`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/security/#api-ProtocolErrorCode), `counter-exhausted`, or `invalid-session`). - The browser counterpart lives at [`/browser/v3`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/browser/v3.md) and produces identical frames. ## API Reference ### Functions #### createProtocolProviderStore ```typescript function createProtocolProviderStore(): ProtocolProviderStore ``` Creates a store for managing protocol provider registrations. Provides methods to register, retrieve, and list protocol providers. **Returns** `ProtocolProviderStore`: A ProtocolProviderStore with methods for managing protocol providers **Example: Creating and using a protocol provider store** ```typescript const store = createProtocolProviderStore() store.add('websocket', myProtocolProvider) const provider = store.getByName('websocket') ``` #### createV3ProtocolFactory ```typescript function createV3ProtocolFactory(crypto: SessionCrypto): (logger: Logger) => ProtocolProvider ``` Creates the v3 protocol factory for a platform. v3 keys each session from an ephemeral key agreement alone: a party that only listens to the hello exchange and the traffic cannot read it, while a party that can post its own hello to a window before the peer's arrives can stand in for the peer. It authenticates frames, rejects replays, and binds traffic to one session, but does not authenticate the peer. **Parameters** | Name | Type | Description | | --- | --- | --- | | `crypto` | `SessionCrypto` | The platform primitives | **Returns** `(logger: Logger) => ProtocolProvider`: `createProtocol(logger)`, which returns the provider a channel binds to a session **Example: Composing v3 in a browser entry** ```typescript export const createProtocol = createV3ProtocolFactory(crypto) const protocolProvider = createProtocol(logger) ``` #### isValidName ```typescript function isValidName(name: string): boolean ``` Validates whether the provided name is valid for protocol registration. The name must be a non-empty string. **Parameters** | Name | Type | Description | | --- | --- | --- | | `name` | `string` | The name to validate | **Returns** `boolean`: True if the name is a non-empty string, false otherwise **Example: Validating protocol names** ```typescript isValidName('websocket') // => true isValidName('') // => false ``` #### isValidProtocol ```typescript function isValidProtocol(protocol: unknown): ValidProtocolResult ``` Validates whether a protocol object contains all required function properties, stopping at the first that is missing or not a function. **Parameters** | Name | Type | Description | | --- | --- | --- | | `protocol` | `unknown` | The protocol object to validate | **Returns** `ValidProtocolResult`: An object mapping each protocol property to its validation status (true if valid, false if invalid, undefined if not yet checked) **Example: Validating a protocol object** ```typescript const result = isValidProtocol(myProtocol) // => { seal: true, open: true, hello: true, isHello: true, acceptHello: true, send: true, receive: true, getLogger: true } const invalid = isValidProtocol({}) // => { seal: false, open: undefined, ... } ``` #### isValidProtocolProvider ```typescript function isValidProtocolProvider(protocolProvider: unknown): boolean ``` Validates whether the provided value is a valid protocol provider. A protocol provider must be a function that creates protocol instances. **Parameters** | Name | Type | Description | | --- | --- | --- | | `protocolProvider` | `unknown` | The value to validate as a protocol provider | **Returns** `boolean`: True if the value is a function, false otherwise **Example: Validating a protocol provider function** ```typescript isValidProtocolProvider(() => protocol) // => true isValidProtocolProvider('not-a-function') // => false ``` #### isValidReceiveFn ```typescript function isValidReceiveFn(receive: unknown): boolean ``` Validates whether the provided value is a valid receive function. The receive function must be callable. **Parameters** | Name | Type | Description | | --- | --- | --- | | `receive` | `unknown` | The value to validate as a receive function | **Returns** `boolean`: True if the value is a function, false otherwise **Example: Validating a receive function** ```typescript isValidReceiveFn((packet) => console.log(packet)) // => true isValidReceiveFn(null) // => false ``` #### isValidSendFn ```typescript function isValidSendFn(send: unknown): boolean ``` Validates whether the provided value is a valid send function. The send function must be callable. **Parameters** | Name | Type | Description | | --- | --- | --- | | `send` | `unknown` | The value to validate as a send function | **Returns** `boolean`: True if the value is a function, false otherwise **Example: Validating a send function** ```typescript isValidSendFn((packet) => websocket.send(packet)) // => true isValidSendFn('not-a-function') // => false ``` ### Interfaces #### ProtocolProviderEntry Entry in a protocol provider store, associating a provider with identifiers. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly id` | `string` | Unique identifier for this entry | | `readonly name` | `string` | Human-readable name for this provider | | `readonly provider` | `ProtocolProvider` | The protocol provider instance | #### ProtocolProviderStore Store for managing protocol providers with lookup by name or ID. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly add` | `(name: string, protocolProvider: ProtocolProvider) => void` | Registers a new provider with the given name | | `readonly existsByName` | `(name: string) => boolean` | Checks if a provider exists by name | | `readonly existsById` | `(id: string) => boolean` | Checks if a provider exists by ID | | `readonly removeByName` | `(name: string[]) => void` | Removes providers by name | | `readonly removeById` | `(id: string[]) => void` | Removes providers by ID | | `readonly clear` | `() => void` | Removes all providers | | `readonly getByName` | `(name: string) => ProtocolProvider` | Retrieves a provider by name | | `readonly getById` | `(id: string) => ProtocolProvider` | Retrieves a provider by ID | | `readonly list` | `unknown` | List of all registered provider entries | #### SessionCrypto The platform primitives a session protocol is composed from **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly getRandomValues` | `(byteLength: number) => Uint8Array` | Cryptographically secure random bytes | | `readonly createKeyAgreement` | `() => Promise` | Mints an ephemeral key agreement | | `readonly stretchPassword` | `(password: string, salt: Uint8Array, options?: StretchOptions) => Promise>` | PBKDF2 password stretching into raw bits | | `readonly expandKey` | `(ikm: Uint8Array, salt: Uint8Array, info: Uint8Array, usages: unknown) => Promise` | HKDF expansion into a usage-restricted AES-GCM key | | `readonly seal` | `(key: CryptoKey, nonce: Uint8Array, additionalData: Uint8Array, plaintext: Uint8Array) => Promise>` | AES-GCM seal under a key, nonce, and additional data | | `readonly open` | `(key: CryptoKey, nonce: Uint8Array, additionalData: Uint8Array, sealed: Uint8Array) => Promise>` | AES-GCM open under a key, nonce, and additional data | | `readonly utf8Encode` | `(text: string) => Uint8Array` | UTF-8 text to bytes | | `readonly utf8Decode` | `(bytes: Uint8Array) => string` | UTF-8 bytes to text | ### Types #### ValidProtocolResult Result object mapping each protocol property to its validation status. ```typescript type ValidProtocolResult = mapped ``` ### Variables #### createProtocol ```typescript const createProtocol: (logger: Logger) => ProtocolProvider ``` **Value** `...` #### V3 The v3 protocol's negotiated identifier and frame version byte ```typescript const V3: Readonly<{ id: "v3"; version: 3 }> ``` **Value** `...` --- Canonical page: https://www.hyperfrontend.dev/docs/libraries/network-protocol/node/v3/ This file: https://www.hyperfrontend.dev/docs/libraries/network-protocol/node/v3.md Documentation index: https://www.hyperfrontend.dev/llms.txt