# v4 Node.js-side v4 protocol: the session-keyed envelope with a shared secret mixed in, wired to the Node.js crypto module. ## Overview `createProtocol(logger, sharedKey)` returns a [`ProtocolProvider`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/#api-ProtocolProvider) used exactly like [`/node/v3`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/node/v3.md)'s: the same hello exchange, the same frames, the same replay rule. The difference is the key schedule: the shared key is stretched once per session with PBKDF2-SHA256 (600,000 iterations, salted with both hellos' nonces) and appended to the ECDH shared secret before the HKDF-SHA256 expansion, so the session is bound to the key. Without it a party can neither read frames nor produce frames the counterpart accepts, a key mismatch is detected because no frame ever authenticates, and a key that leaks later does not expose earlier sessions, whose ephemeral agreements are gone. [`V4`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/node/v4/#api-V4) is the protocol's definition, `{ id: 'v4', version: 4 }`: the identifier a session names and the byte every frame starts with. ## The shared key The key must be a string of at least [`MIN_SHARED_KEY_LENGTH`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/node/v4/#api-MIN_SHARED_KEY_LENGTH) (16) characters; `isValidSharedKey(value)` checks exactly that, and [`createProtocol`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/node/v4/#api-createProtocol) throws for a shorter key. The guarantee holds for a generated key of 128 bits or more (for example 32 hex characters from a secure random source). A party that can run a hello exchange against this side can test key guesses offline afterwards, so a human-chosen passphrase is not a substitute. ## Usage ```typescript import { parentPort } from 'node:worker_threads' import { createProtocol } from '@hyperfrontend/network-protocol/node/v4' 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' }), sharedKey), session: { protocol: 'v4', 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, one PBKDF2-SHA256 stretch, and one HKDF expansion per direction; each frame costs one AES-GCM operation. The stretch is paid once per session, not per message, so it lands on the handshake rather than on traffic. - A side holding a different key derives different keys: every frame from it is reported through [`onDrop`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/#api-ChannelOptions-prop-onDrop) with code `authentication-failed` and nothing is delivered. - The browser counterpart lives at [`/browser/v4`](https://www.hyperfrontend.dev/docs/libraries/network-protocol/browser/v4.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') ``` #### createV4ProtocolFactory ```typescript function createV4ProtocolFactory(crypto: SessionCrypto): (logger: Logger, sharedKey: string) => ProtocolProvider ``` Creates the v4 protocol factory for a platform. v4 keys each session from the same ephemeral key agreement as v3 with the shared key stretched once and mixed in, so a party without the key cannot complete the agreement: product traffic is confidential and authentic against anyone who lacks the key, and a key that leaks later does not expose earlier sessions. A party that can run a hello exchange against this side can test key guesses offline afterwards, which is why the key must be generated, not chosen. **Parameters** | Name | Type | Description | | --- | --- | --- | | `crypto` | `SessionCrypto` | The platform primitives | **Returns** `(logger: Logger, sharedKey: string) => ProtocolProvider`: `createProtocol(logger, sharedKey)`, which returns the provider a channel binds to a session **Example: Composing v4 in a browser entry** ```typescript export const createProtocol = createV4ProtocolFactory(crypto) const protocolProvider = createProtocol(logger, sharedKey) ``` #### 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 ``` #### isValidSharedKey ```typescript function isValidSharedKey(sharedKey: unknown): unknown ``` Checks that a value can serve as a v4 shared key. **Parameters** | Name | Type | Description | | --- | --- | --- | | `sharedKey` | `unknown` | The value to check | **Returns** `unknown`: True for a string of at least 16 characters **Example: Validating a key before creating the provider** ```typescript isValidSharedKey('k3y-that-is-long-enough') // => true ``` ### 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, sharedKey: string) => ProtocolProvider ``` **Value** `...` #### MIN_SHARED_KEY_LENGTH The shortest shared key v4 accepts; the guarantee needs a generated key of 128 bits or more ```typescript const MIN_SHARED_KEY_LENGTH: 16 ``` **Value** `16` #### V4 The v4 protocol's negotiated identifier and frame version byte ```typescript const V4: Readonly<{ id: "v4"; version: 4 }> ``` **Value** `...` --- Canonical page: https://www.hyperfrontend.dev/docs/libraries/network-protocol/node/v4/ This file: https://www.hyperfrontend.dev/docs/libraries/network-protocol/node/v4.md Documentation index: https://www.hyperfrontend.dev/llms.txt