@enclave-vm/stream
Streaming protocol building blocks for the EnclaveJS runtime. Provides NDJSON serialization and parsing, reconnection helpers, and encryption primitives.Installation
NDJSON Protocol
EnclaveJS uses NDJSON (Newline-Delimited JSON) for streaming events. Each line is a complete JSON object representing a stream event.Serialization
Parsing
Lines are validated against the event schemas of@enclave-vm/types.
Web Streams
createNdjsonParseStream and parseNdjsonStream skip a line that is not a valid event. Use NdjsonStreamParser to be told about such lines.
Line Length Limit
The incremental parsers never hold more thanmaxLineLength characters of a line that has not ended. The default is DEFAULT_MAX_LINE_LENGTH (8 MiB).
maxLineLength that is not a positive integer throws a RangeError.
Encryption Primitives
The package exports the pieces of an encrypted channel: ECDH P-256 key exchange helpers, HKDF-SHA-256 key derivation, AES-256-GCM, and theenc envelope of the protocol.
Key Exchange (ECDH)
generateKeyPair returns a private key that cannot be exported. processClientHello and processServerHello throw EcdhError for a protocol version, curve, algorithm or key derivation that is not implemented. exportPublicKey, importPublicKey and createServerHello are available for a handshake with its own message format.
Key Derivation (HKDF)
Encryption/Decryption (AES-GCM)
- Envelopes authenticate their header.
createEncryptedEnvelopeandcontext.createEnvelopeauthenticate the protocol version, session id, sequence number and key id together with the event. Read envelopes withopenEncryptedEnvelopeorcontext.openEnvelope. decryptJsondoes not open an envelope.decryptJson(key, payload)andcontext.decryptJson(payload)read payloads made byencryptJson. Both forms ofencryptJsonanddecryptJsontake optional additional authenticated data.- Replays are for the receiver to detect. Opening an envelope does not tell whether its sequence number was seen before. Compare it with the last one received, for example with
SequenceTracker. - A context has a message limit.
SessionEncryptionContextuses a counter nonce (8 random bytes per context and a 32-bit counter) and refuses to encrypt after 2^30 messages;needsRotation()then returnstrue. There is no rotation: exchange keys again. toKeyInfo()returns the raw key bytes. Treat its result as the key itself.
encrypt, decrypt, generateNonce, generateCounterNonce, toBase64, fromBase64 and encodeEnvelopeHeader are exported as well. generateCounterNonce throws for a counter outside 0 to 2^32 - 1, and fromBase64 throws AesGcmError on malformed input.
Encryption Constants
Reconnection Handling
Helpers for a connection that the application opens itself: a state machine with exponential backoff, sequence tracking, an event buffer and a heartbeat monitor. They keep state and compute delays; they do not open connections.Connection State Machine
Connecting.
Reconnection Configuration
Sequence Tracking
receive() takes the first sequence number as the starting point, and answers { gap: false } for a number at or below the last one. To detect a duplicate, compare the number with getLastSeq() before calling receive().
Event Buffering
Heartbeat Monitoring
Re-exported Types
This package re-exports all types from@enclave-vm/types for convenience: