Skip to main content

@enclave-vm/stream

Streaming protocol building blocks for the EnclaveJS runtime. Provides NDJSON serialization and parsing, reconnection helpers, and encryption primitives.
No EnclaveJS package uses the encryption primitives. @enclave-vm/client, @enclave-vm/react, @enclave-vm/broker and @enclave-vm/runtime do not encrypt, perform no handshake and have no encryption option. A session between the client and the broker is plain JSON protected only by the transport, so serve it over HTTPS. See 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 than maxLineLength characters of a line that has not ended. The default is DEFAULT_MAX_LINE_LENGTH (8 MiB).
A 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 the enc envelope of the protocol.
Nothing in EnclaveJS calls these functions, and new EnclaveClient({ encryption }) throws. An application that wants payload encryption has to implement both ends itself, exchange the hello messages and the envelopes over its own endpoints, and keep using TLS. The Encrypted Sessions example shows the wiring.

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.
The key exchange is not authenticated. ServerHello.signatureB64 is neither created nor verified, and there is no key confirmation. The exchange protects against a party that can only read the connection. A party that can change messages can replace both public keys. An application that needs more has to authenticate the hello messages itself (for example by signing them with a key the client pins) or rely on TLS for the identity of the server.

Key Derivation (HKDF)

Use each key for one direction only.

Encryption/Decryption (AES-GCM)

  • Envelopes authenticate their header. createEncryptedEnvelope and context.createEnvelope authenticate the protocol version, session id, sequence number and key id together with the event. Read envelopes with openEncryptedEnvelope or context.openEnvelope.
  • decryptJson does not open an envelope. decryptJson(key, payload) and context.decryptJson(payload) read payloads made by encryptJson. Both forms of encryptJson and decryptJson take 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. SessionEncryptionContext uses a counter nonce (8 random bytes per context and a 32-bit counter) and refuses to encrypt after 2^30 messages; needsRotation() then returns true. There is no rotation: exchange keys again.
  • toKeyInfo() returns the raw key bytes. Treat its result as the key itself.
The lower-level functions 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

Open the connection when the state changes to 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: