← Back to @hyperfrontend/network-protocol

@hyperfrontend/network-protocol/browser/v1

v1

Browser-side V1 protocol: dynamic key exchange with time-based packet obfuscation.

V1 establishes per-channel encryption keys with a FirstMessageHandler handshake — neither end needs a pre-shared secret. Once established, the dynamic key encrypts the application payload while the obfuscation layer rotates a time-derived password (getTimeBasedPassword / getTimeBasedPasswords) on a configurable interval to harden against passive replay analysis. This entry point composes the lib/protocol/v1 factory with browser-specific cryptography and string-encoding adapters and exposes createProtocol plus the supporting type surface. Use V1 when you need a zero-config secure channel and can tolerate the handshake round-trip; use /browser/v2 when both ends share a long-lived secret.

API Reference

ƒ Functions

§function

createObfuscatedHandshakeProtocolFactory<T>(createDynamicKeyEncryption: (provider: () => string) => EncryptionSuite<T>, createTimeIntervalObfuscation: (refreshRate: number) => ObfuscationSuite): (logger: Logger, refreshRate: number) => ProtocolProvider<T>

Creates a protocol factory function with obfuscation-only handshake encryption.
This is the Obfuscation-Only Handshake protocol model (V1):

First message: NO encryption (obfuscation only) - key transmitted in payload
Key capture: Dynamic key extracted from packet.data.key on receive
Subsequent messages: Encrypted with dynamically captured keys

Handshake Flow:

First outbound message: Obfuscated but NOT encrypted (no key exists yet)
First inbound message: Deobfuscated, key extracted from packet.data.key
Subsequent messages: Both obfuscated AND encrypted with dynamic keys

Security Note: The first message's encryption key is visible after deobfuscation. This is acceptable when time-based obfuscation provides sufficient protection for the handshake. For stronger first-message protection, use V2 (PSK Handshake) instead.
Both protocols use time-based obfuscation as an additional security layer.

Parameters

Name	Type	Description
§createDynamicKeyEncryption	`(provider: () => string) => EncryptionSuite<T>`	Factory for dynamic key-based encryption
§createTimeIntervalObfuscation	`(refreshRate: number) => ObfuscationSuite`	Factory for time-based obfuscation

Returns

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

A function that creates protocol providers

Example

Creating a protocol provider with obfuscated handshake

const createProvider = createObfuscatedHandshakeProtocolFactory(
  createDynamicKeyEncryption,
  createTimeIntervalObfuscation
)
const protocolProvider = createProvider(logger, 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 dynamic key encryption. Keys are exchanged in-band via packet.data.key during the handshake.
First Message Handling: The first message (before key exchange) is sent with obfuscation only. When received, the key is extracted and used for subsequent encrypted messages.

§type

createProtocolFactory

Use createObfuscatedHandshakeProtocolFactory instead. This alias exists for backward compatibility.