@hyperfrontend/network-protocol/node/packetpacket
Node.js-side packet encryption, serialization, and obfuscation pipeline with dynamic-key support.
A packet is the on-the-wire unit produced from a Data<T> envelope after encryption, serialization, and obfuscation. This entry point binds the runtime-agnostic lib/packet factories to @hyperfrontend/cryptography/node (Node webcrypto AES-GCM) and @hyperfrontend/string-utils/node (Buffer-based base64), exposing encryptPacket, decryptPacket, obfuscatePacket, deobfuscatePacket, and the high-level createSerializedEncryptedPacket / createDeserializedEncryptedPacket builders. Used by the /node/v1 and /node/v2 protocols to assemble outgoing wire packets and parse incoming ones. Function signatures match /browser/packet so encoded packets cross runtime boundaries cleanly.
API Reference
ƒ Functions
§function
createDynamicKeyEncryptionFactory<T>(encryptPacket: PacketEncrypter, decryptPacket: PacketDecrypter, firstMessageHandler: FirstMessageHandler<T>): (provider: () => string) => EncryptionSuite<T>
Creates a factory for dynamic key-based encryption suites.
This factory accepts packet encryption and decryption functions and returns a function that creates encryption suites with dynamic key providers. The key provider is evaluated at the time of each encryption/decryption operation, allowing for keys to change dynamically.
First Message Handling: When the key provider returns undefined/empty (first message scenario), the encryption is skipped and the packet is passed through with a special marker. On the receiving end, when no key exists, decryption is skipped and the data is parsed directly.
This factory accepts packet encryption and decryption functions and returns a function that creates encryption suites with dynamic key providers. The key provider is evaluated at the time of each encryption/decryption operation, allowing for keys to change dynamically.
First Message Handling: When the key provider returns undefined/empty (first message scenario), the encryption is skipped and the packet is passed through with a special marker. On the receiving end, when no key exists, decryption is skipped and the data is parsed directly.
Parameters
Returns
(provider: () => string) => EncryptionSuite<T>A factory function that accepts a key provider and returns an encryption suite
Example
Creating a dynamic key encryption suite
const factory = createDynamicKeyEncryptionFactory(encryptPacket, decryptPacket, firstMessageHandler)
let sessionKey: string | undefined
const suite = factory(() => sessionKey)
const encrypted = await suite.packetEncryption(packet)§function
createDynamicKeyObfuscationFactory(obfuscatePacket: PacketObfuscater, deobfuscatePacket: PacketDeobfuscater): (provider: () => string) => ObfuscationSuite
Creates a factory for dynamic key-based obfuscation suites.
This factory accepts packet obfuscation and deobfuscation functions and returns a function that creates obfuscation suites with dynamic key providers. The key provider is evaluated at the time of each obfuscation/deobfuscation operation, allowing for keys to change dynamically.
This factory accepts packet obfuscation and deobfuscation functions and returns a function that creates obfuscation suites with dynamic key providers. The key provider is evaluated at the time of each obfuscation/deobfuscation operation, allowing for keys to change dynamically.
Parameters
Returns
(provider: () => string) => ObfuscationSuiteA factory function that accepts a key provider and returns an obfuscation suite
Example
Creating a dynamic key obfuscation suite
const factory = createDynamicKeyObfuscationFactory(obfuscatePacket, deobfuscatePacket)
let rotatingKey = 'initial-key'
const suite = factory(() => rotatingKey)
const obfuscated = await suite.packetObfuscation(packet)Validates whether the provided value is a valid obfuscated packet. Obfuscated packets must be Uint8Array instances.
Parameters
| Name | Type | Description |
|---|---|---|
§packet | unknown | The value to validate as an obfuscated packet |
Returns
booleanTrue if the value is a Uint8Array, false otherwise
Example
Validating obfuscated packets
isValidObfuscatedPacket(new Uint8Array([1, 2, 3]))
// => true
isValidObfuscatedPacket({ data: 'not binary' })
// => falseValidates whether the provided value is a valid packet origin identifier. The origin must be a 36-character UUID v4 string.
Parameters
| Name | Type | Description |
|---|---|---|
§origin | unknown | The value to validate as a packet origin |
Returns
booleanTrue if the value is a valid UUID v4 string, false otherwise
Example
Validating packet origins
isValidOrigin('550e8400-e29b-41d4-a716-446655440000')
// => true
isValidOrigin('not-a-uuid')
// => falseValidates whether the provided refresh rate is valid for packet obfuscation. The refresh rate must be a number greater than or equal to 1.
Parameters
| Name | Type | Description |
|---|---|---|
§refreshRate | number | The refresh rate value to validate |
Returns
booleanTrue if the refresh rate is a valid number >= 1, false otherwise
Example
Validating refresh rates
isValidRefreshRate(5)
// => true
isValidRefreshRate(0)
// => falseDisambiguation: This methods confirms that value for data property in packet is serialized, it does not confirm that the entire packet is serialized
Parameters
| Name | Type | Description |
|---|---|---|
§packet | unknown | The value to validate as a serialized encrypted packet |
Returns
booleanTrue if the packet has valid structure and serialized data, false otherwise
Example
Validating serialized encrypted packets
isValidSerializedEncryptedPacket({
origin: '550e8400-e29b-41d4-a716-446655440000',
target: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
data: { key: 'abc', message: '{"action":"ping"}' }
})
// => trueValidates whether the provided value is a valid packet target identifier. The target must be a 36-character UUID v4 string.
Parameters
| Name | Type | Description |
|---|---|---|
§target | unknown | The value to validate as a packet target |
Returns
booleanTrue if the value is a valid UUID v4 string, false otherwise
Example
Validating packet targets
isValidTarget('6ba7b810-9dad-11d1-80b4-00c04fd430c8')
// => true
isValidTarget('invalid')
// => falseValidates whether the provided value is a valid unencrypted packet. Checks both the packet structure and that the data payload is unencrypted.
Parameters
| Name | Type | Description |
|---|---|---|
§packet | unknown | The value to validate as an unencrypted packet |
Returns
booleanTrue if the value is a valid unencrypted packet, false otherwise
Example
Validating unencrypted packets
isValidUnencryptedPacket({
origin: '550e8400-e29b-41d4-a716-446655440000',
target: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
data: { key: 'session-abc', message: { action: 'ping' } }
})
// => trueValidates the base structure of an unobfuscated packet. Checks that the packet is an object with valid origin, target, and data properties.
Parameters
| Name | Type | Description |
|---|---|---|
§packet | unknown | The value to validate as an unobfuscated packet base |
Returns
ValidUnobfuscatedPacketBaseResultAn object containing the validation result and the packet cast to UnobfuscatedPacket
Example
Validating packet base structure
const { isValid, pkt } = isValidUnobfuscatedPacketBase({
origin: '550e8400-e29b-41d4-a716-446655440000',
target: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
data: { key: 'abc', message: {} }
})
// => { isValid: true, pkt: { origin, target, data } }Validates whether the provided value is a valid unserialized encrypted packet. Checks that the packet has valid structure and the data is in unserialized format (Uint8Array).
Parameters
| Name | Type | Description |
|---|---|---|
§packet | unknown | The value to validate as an unserialized encrypted packet |
Returns
booleanTrue if the packet has valid structure and unserialized data, false otherwise
Example
Validating unserialized encrypted packets
isValidUnserializedEncryptedPacket({
origin: '550e8400-e29b-41d4-a716-446655440000',
target: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
data: new Uint8Array([1, 2, 3])
})
// => true◈ Interfaces
Base interface for all packet types
Packet with serialized encrypted data as string
Packet containing unencrypted data
Packet before obfuscation, with data in any encryption state
Packet with binary encrypted data before serialization
◆ Types
Union type representing any packet state
type Packet = ObfuscatedPacket | UnobfuscatedPacket<T>Decrypts a packet using a password
type PacketDecrypter = (packet: UnserializedEncryptedPacket, password: string) => Promise<UnencryptedPacket<T>>Password-bound packet decryption function
type PacketDecryption = (packet: UnserializedEncryptedPacket) => Promise<UnencryptedPacket<T>>Deobfuscates an obfuscated packet
type PacketDeobfuscater = (packet: ObfuscatedPacket, password: string) => Promise<SerializedEncryptedPacket>Password-bound packet deobfuscation function
type PacketDeobfuscation = (packet: ObfuscatedPacket) => Promise<SerializedEncryptedPacket>Deserializes a string packet to binary format
type PacketDeserialization = (packet: SerializedEncryptedPacket) => UnserializedEncryptedPacketEncrypts an unencrypted packet using a password
type PacketEncrypter = (packet: UnencryptedPacket<T>, password: string) => Promise<UnserializedEncryptedPacket>Password-bound packet encryption function
type PacketEncryption = (packet: UnencryptedPacket<T>) => Promise<UnserializedEncryptedPacket>Obfuscates a serialized encrypted packet
type PacketObfuscater = (packet: SerializedEncryptedPacket, password: string) => Promise<ObfuscatedPacket>Password-bound packet obfuscation function
type PacketObfuscation = (packet: SerializedEncryptedPacket) => Promise<ObfuscatedPacket>Serializes an encrypted packet to string format
type PacketSerialization = (packet: UnserializedEncryptedPacket) => SerializedEncryptedPacket