@enclave-vm/stream 0.0.1 → 2.9.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 +159 -0
- package/esm/index.mjs +1052 -0
- package/esm/package.json +6 -0
- package/index.js +1101 -0
- package/package.json +10 -9
- package/src/crypto/aes-gcm.js +0 -293
- package/src/crypto/aes-gcm.js.map +0 -1
- package/src/crypto/ecdh.js +0 -166
- package/src/crypto/ecdh.js.map +0 -1
- package/src/crypto/hkdf.js +0 -123
- package/src/crypto/hkdf.js.map +0 -1
- package/src/crypto/index.js +0 -40
- package/src/crypto/index.js.map +0 -1
- package/src/index.js +0 -63
- package/src/index.js.map +0 -1
- package/src/ndjson.js +0 -263
- package/src/ndjson.js.map +0 -1
- package/src/reconnect.js +0 -372
- package/src/reconnect.js.map +0 -1
- /package/{src/crypto → crypto}/aes-gcm.d.ts +0 -0
- /package/{src/crypto → crypto}/ecdh.d.ts +0 -0
- /package/{src/crypto → crypto}/hkdf.d.ts +0 -0
- /package/{src/crypto → crypto}/index.d.ts +0 -0
- /package/{src/index.d.ts → index.d.ts} +0 -0
- /package/{src/ndjson.d.ts → ndjson.d.ts} +0 -0
- /package/{src/reconnect.d.ts → reconnect.d.ts} +0 -0
package/README.md
ADDED
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
# @enclave-vm/stream
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@enclave-vm/stream)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](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
|