@aegis-fluxion/core 0.7.2 → 0.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 Low-level encrypted WebSocket primitives for the `aegis-fluxion` ecosystem.
 
-Version: **0.7.2**
+Version: **0.9.0**
 
 ---
 
@@ -11,9 +11,11 @@ Version: **0.7.2**
 - Ephemeral ECDH handshake (`prime256v1`)
 - AES-256-GCM encrypted envelopes
 - ACK request/response (Promise + callback styles)
+- Encrypted chunked streaming for large `Buffer`/`Readable` payloads
 - Secure room routing (`join`, `leave`, `leaveAll`, `to(room).emit(...)`)
 - Middleware phases: `connection`, `incoming`, `outgoing`
 - Rate limiting and DDoS controls per connection and IP
+- TLS 1.3-style session resumption with encrypted one-time tickets
 - **Horizontal scaling hooks** via pluggable `SecureServerAdapter`
 
 ---
@@ -26,6 +28,130 @@ npm install @aegis-fluxion/core ws
 
 ---
 
+## Chunked streaming (new in 0.9.0)
+
+`@aegis-fluxion/core@0.9.0` adds secure chunked stream transport for large payloads.
+
+### Supported stream sources
+
+- `Buffer`
+- `Uint8Array`
+- `Readable`
+- `AsyncIterable<Buffer | Uint8Array | ArrayBuffer>`
+
+### Stream APIs
+
+- Client outbound: `client.emitStream(event, source, options?)`
+- Client inbound: `client.onStream(event, handler)`
+- Server outbound: `server.emitStreamTo(clientId, event, source, options?)`
+- Server inbound: `server.onStream(event, handler)`
+- Per-client server outbound helper: `serverClient.emitStream(event, source, options?)`
+
+### Options
+
+- `chunkSizeBytes` (default `64 * 1024`, max `1024 * 1024`)
+- `metadata` (optional object attached to the stream start frame)
+- `totalBytes` (optional size hint; required when source size is unknown and you want announced size)
+- `signal` (`AbortSignal` to cancel transfer)
+
+### Example
+
+```ts
+import { Readable } from "node:stream";
+import { SecureClient, SecureServer } from "@aegis-fluxion/core";
+
+const server = new SecureServer({ host: "127.0.0.1", port: 8080 });
+const client = new SecureClient("ws://127.0.0.1:8080");
+
+server.onStream("media:upload", async (stream, info, peer) => {
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+
+  const uploaded = Buffer.concat(chunks);
+
+  await peer.emitStream("media:download", Readable.from(uploaded), {
+    chunkSizeBytes: 64 * 1024,
+    totalBytes: uploaded.length,
+    metadata: { direction: "server-to-client" }
+  });
+
+  console.log("Server received stream", {
+    streamId: info.streamId,
+    announcedTotalBytes: info.totalBytes,
+    receivedBytes: uploaded.length
+  });
+});
+
+client.on("ready", async () => {
+  const payload = Buffer.from("chunked secure payload");
+
+  const result = await client.emitStream("media:upload", payload, {
+    chunkSizeBytes: 64 * 1024,
+    totalBytes: payload.length,
+    metadata: { direction: "client-to-server" }
+  });
+
+  console.log(result); // { streamId, chunkCount, totalBytes }
+});
+```
+
+Each chunk is delivered inside reserved internal `start/chunk/end/abort` frames and encrypted
+through the same AES-256-GCM channel used by standard events.
+
+---
+
+## Session resumption (TLS 1.3-style)
+
+`@aegis-fluxion/core@0.8.0` introduced secure resume-first reconnect behavior:
+
+- Full handshake path uses ephemeral ECDH (`hello` frame).
+- Resume path uses ticket-bound proofs (`resume` / `resume-ack` frames).
+- Successful resumes derive fresh channel keys from ticket secret + client nonce.
+- Servers enforce ticket TTL, bounded cache size, and one-time ticket consumption.
+- Clients automatically fall back to full handshake when resume is rejected.
+
+### Server configuration
+
+```ts
+import { SecureServer } from "@aegis-fluxion/core";
+
+const server = new SecureServer({
+  host: "127.0.0.1",
+  port: 8080,
+  sessionResumption: {
+    enabled: true,
+    ticketTtlMs: 60_000,
+    maxCachedTickets: 10_000
+  }
+});
+```
+
+### Client configuration
+
+```ts
+import { SecureClient } from "@aegis-fluxion/core";
+
+const client = new SecureClient("ws://127.0.0.1:8080", {
+  reconnect: true,
+  sessionResumption: {
+    enabled: true,
+    maxAcceptedTicketTtlMs: 60_000
+  }
+});
+```
+
+### Security model
+
+- Resume proofs are validated with HMAC and constant-time comparison.
+- Resume tickets are encrypted in transit (same channel protections as all payloads).
+- Resume tickets are discarded if expired, policy-invalid, or already consumed.
+- Reserved internal events (e.g., session-ticket transport) cannot be emitted by user code.
+
+---
+
 ## SecureServer adapter API (horizontal scaling)
 
 ### Core types