← Back to @hyperfrontend/network-protocol

@hyperfrontend/network-protocol/browser/v2

v2

Browser-side V2 protocol: pre-shared-key handshake encryption with time-based packet obfuscation.

V2 assumes both ends already share a long-lived secret (a PSK), so there is no first-message key-exchange round-trip; the encryption key is derived directly from the PSK at channel construction time. The obfuscation layer still rotates a time-derived password (getTimeBasedPassword / getTimeBasedPasswords) on a configurable interval. This entry point composes the lib/protocol/v2 createPSKHandshakeProtocolFactory with browser-specific cryptography adapters and exposes createProtocol. Use V2 when both endpoints can be provisioned with the same secret; use /browser/v1 when you need zero-config dynamic key exchange.

API Reference

ƒ Functions

§function

createPSKHandshakeProtocolFactory<T>(encryptPacket: PacketEncrypter, decryptPacket: PacketDecrypter, createTimeIntervalObfuscation: (refreshRate: number) => ObfuscationSuite): (logger: Logger, sharedKey: string, refreshRate: number) => ProtocolProvider<T>

Creates a protocol factory function with PSK-based handshake encryption.
This is the Pre-Shared Key (PSK) Handshake protocol model (V2):

First message: Encrypted with PSK (both endpoints share key beforehand)
Key capture: Dynamic key extracted from packet.data.key on receive
Subsequent messages: Encrypted with dynamically captured keys

Comparison with V1 (Obfuscation-Only Handshake):

V1: First message has NO encryption (obfuscation only) - key visible after deobfuscation
V2: First message IS encrypted with PSK - key never exposed, even after deobfuscation

Security Benefit: The PSK handshake provides encryption from the very first message, preventing the encryption key from being exposed even to attackers who can deobfuscate.
Both protocols use time-based obfuscation as an additional security layer.

Parameters

Name	Type	Description
§encryptPacket	`PacketEncrypter`	Function to encrypt a packet with password
§decryptPacket	`PacketDecrypter`	Function to decrypt a packet with password
§createTimeIntervalObfuscation	`(refreshRate: number) => ObfuscationSuite`	Factory for time-based obfuscation

Returns

(logger: Logger, sharedKey: string, refreshRate: number) => ProtocolProvider<T>

A function that creates protocol providers

Example

Creating a protocol provider with PSK handshake

const createProvider = createPSKHandshakeProtocolFactory(
  encryptPacket,
  decryptPacket,
  createTimeIntervalObfuscation
)
const protocolProvider = createProvider(logger, 'shared-secret-key', 5)
const protocol = protocolProvider(sendFn, receiveFn)

§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

const store = createProtocolProviderStore()
store.add('websocket', myProtocolProvider)
const provider = store.getByName('websocket')

§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

isValidName('websocket')
// => true

isValidName('')
// => false

§function

isValidProtocol(protocol: unknown): ValidProtocolResult

Validates whether the provided value is a valid protocol object. Checks that all required protocol methods (encryption, obfuscation, send, receive) are present.

Parameters

Name	Type	Description
§protocol	`unknown`	The value to validate as a protocol

Returns

ValidProtocolResult

A ValidProtocolResult object containing validation details for each protocol component

Example

Validating a protocol object

const result = isValidProtocol(myProtocol)
// => { packetEncryption: true, packetDecryption: true, ... }

const invalid = isValidProtocol({})
// => { packetEncryption: false, packetDecryption: undefined, ... }

§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

isValidProtocolProvider(() => protocol)
// => true

isValidProtocolProvider('not-a-function')
// => false

§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

isValidReceiveFn((packet) => console.log(packet))
// => true

isValidReceiveFn(null)
// => false

§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

isValidSendFn((packet) => websocket.send(packet))
// => true

isValidSendFn('not-a-function')
// => false

◈ Interfaces

§interface

ProtocolProviderEntry

Entry in a protocol provider store, associating a provider with identifiers.

Properties

§readonly id:string—

Unique identifier for this entry

§readonly name:string—

Human-readable name for this provider

§readonly provider:ProtocolProvider<T>—

The protocol provider instance

§interface

ProtocolProviderStore

Store for managing protocol providers with lookup by name or ID.

Properties

§readonly add:(name: string, protocolProvider: ProtocolProvider<T>) => void—

Registers a new provider with the given name

§readonly clear:() => void—

Removes all providers

§readonly existsById:(id: string) => boolean—

Checks if a provider exists by ID

§readonly existsByName:(name: string) => boolean—

Checks if a provider exists by name

§readonly getById:(id: string) => ProtocolProvider<T>—

Retrieves a provider by ID

§readonly getByName:(name: string) => ProtocolProvider<T>—

Retrieves a provider by name

§readonly list:unknown—

List of all registered provider entries

§readonly removeById:(id: string[]) => void—

Removes providers by ID

§readonly removeByName:(name: string[]) => void—

Removes providers by name

◆ Types

§type

ValidProtocolResult

Result object mapping each protocol property to its validation status.

type ValidProtocolResult = mapped

● Variables

§type

createProtocol

Creates a protocol with PSK handshake encryption.
V2 Protocol - PSK Handshake:

First message: Encrypted with pre-shared key (PSK)
Key capture: Dynamic key extracted from packet.data.key
Subsequent messages: Encrypted with dynamically captured keys

Security Benefit: Unlike V1, the encryption key is never exposed - even the first message is encrypted. Both endpoints must share the PSK beforehand (out-of-band key exchange).
All messages also use time-based obfuscation for an additional security layer.