@enclave-vm/stream 0.0.1 → 2.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,159 @@
1
+ # @enclave-vm/stream
2
+
3
+ [![npm version](https://img.shields.io/npm/v/@enclave-vm/stream.svg)](https://www.npmjs.com/package/@enclave-vm/stream)
4
+ [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
5
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
6
+
7
+ > Streaming protocol implementation for EnclaveJS runtime (NDJSON, encryption, reconnection)
8
+
9
+ The @enclave-vm/stream package provides the core streaming protocol implementation for EnclaveJS. It handles NDJSON serialization, end-to-end encryption using ECDH/AES-GCM, and automatic reconnection with state recovery.
10
+
11
+ ## Features
12
+
13
+ - **NDJSON Streaming**: Newline-delimited JSON for efficient message streaming
14
+ - **End-to-End Encryption**: ECDH key exchange with AES-GCM encryption
15
+ - **Automatic Reconnection**: Built-in reconnection with exponential backoff
16
+ - **State Recovery**: Resume sessions after disconnection
17
+ - **Backpressure Handling**: Flow control for high-throughput scenarios
18
+ - **Cross-Platform**: Works in Node.js and browsers
19
+
20
+ ## Installation
21
+
22
+ ```bash
23
+ npm install @enclave-vm/stream
24
+ # or
25
+ yarn add @enclave-vm/stream
26
+ # or
27
+ pnpm add @enclave-vm/stream
28
+ ```
29
+
30
+ ## Quick Start
31
+
32
+ ```typescript
33
+ import { StreamEncoder, StreamDecoder, createEncryptedChannel } from '@enclave-vm/stream';
34
+
35
+ // Basic NDJSON encoding/decoding
36
+ const encoder = new StreamEncoder();
37
+ const decoder = new StreamDecoder();
38
+
39
+ // Encode messages
40
+ const encoded = encoder.encode({ type: 'tool_call', name: 'getData', args: {} });
41
+
42
+ // Decode messages
43
+ decoder.on('message', (message) => {
44
+ console.log('Received:', message);
45
+ });
46
+ decoder.write(encoded);
47
+ ```
48
+
49
+ ## Encrypted Channels
50
+
51
+ Create end-to-end encrypted communication channels:
52
+
53
+ ```typescript
54
+ import { createEncryptedChannel } from '@enclave-vm/stream';
55
+
56
+ // Server side
57
+ const serverChannel = await createEncryptedChannel({
58
+ role: 'server',
59
+ onMessage: (message) => {
60
+ console.log('Decrypted message:', message);
61
+ },
62
+ });
63
+
64
+ // Get server's public key to send to client
65
+ const serverPublicKey = serverChannel.getPublicKey();
66
+
67
+ // Client side
68
+ const clientChannel = await createEncryptedChannel({
69
+ role: 'client',
70
+ remotePublicKey: serverPublicKey,
71
+ onMessage: (message) => {
72
+ console.log('Decrypted message:', message);
73
+ },
74
+ });
75
+
76
+ // Send encrypted messages
77
+ await clientChannel.send({ type: 'tool_call', name: 'secretOp', args: {} });
78
+ ```
79
+
80
+ ## Reconnection
81
+
82
+ Handle connection drops gracefully:
83
+
84
+ ```typescript
85
+ import { ReconnectingStream } from '@enclave-vm/stream';
86
+
87
+ const stream = new ReconnectingStream({
88
+ url: 'wss://runtime.example.com',
89
+ sessionId: 'session_123',
90
+ reconnect: {
91
+ maxAttempts: 5,
92
+ initialDelay: 1000,
93
+ maxDelay: 30000,
94
+ backoffMultiplier: 2,
95
+ },
96
+ onReconnect: (attempt) => {
97
+ console.log(`Reconnecting (attempt ${attempt})...`);
98
+ },
99
+ onMessage: (message) => {
100
+ handleMessage(message);
101
+ },
102
+ });
103
+
104
+ await stream.connect();
105
+ ```
106
+
107
+ ## NDJSON Utilities
108
+
109
+ ```typescript
110
+ import { parseNDJSON, stringifyNDJSON } from '@enclave-vm/stream';
111
+
112
+ // Parse NDJSON string
113
+ const messages = parseNDJSON(ndjsonString);
114
+
115
+ // Stringify to NDJSON
116
+ const ndjson = stringifyNDJSON([
117
+ { type: 'start', sessionId: '123' },
118
+ { type: 'tool_call', name: 'getData', args: {} },
119
+ { type: 'end' },
120
+ ]);
121
+ ```
122
+
123
+ ## Encryption Details
124
+
125
+ The encryption implementation uses:
126
+
127
+ - **Key Exchange**: ECDH (Elliptic Curve Diffie-Hellman) with P-256 curve
128
+ - **Symmetric Encryption**: AES-256-GCM with random IV per message
129
+ - **Key Derivation**: HKDF for deriving encryption keys from shared secret
130
+
131
+ ```typescript
132
+ import { generateKeyPair, deriveSharedSecret, encrypt, decrypt } from '@enclave-vm/stream';
133
+
134
+ // Generate key pairs
135
+ const serverKeys = await generateKeyPair();
136
+ const clientKeys = await generateKeyPair();
137
+
138
+ // Derive shared secret
139
+ const serverSecret = await deriveSharedSecret(serverKeys.privateKey, clientKeys.publicKey);
140
+ const clientSecret = await deriveSharedSecret(clientKeys.privateKey, serverKeys.publicKey);
141
+
142
+ // Encrypt/decrypt messages
143
+ const encrypted = await encrypt(serverSecret, JSON.stringify(message));
144
+ const decrypted = await decrypt(clientSecret, encrypted);
145
+ ```
146
+
147
+ ## Related Packages
148
+
149
+ | Package | Description |
150
+ | ------------------------------------------- | ---------------------------------- |
151
+ | [@enclave-vm/types](../enclavejs-types) | Type definitions and Zod schemas |
152
+ | [@enclave-vm/broker](../enclavejs-broker) | Tool broker and session management |
153
+ | [@enclave-vm/client](../enclavejs-client) | Browser/Node.js client SDK |
154
+ | [@enclave-vm/react](../enclavejs-react) | React hooks and components |
155
+ | [@enclave-vm/runtime](../enclavejs-runtime) | Standalone runtime worker |
156
+
157
+ ## License
158
+
159
+ Apache-2.0