@aegis-fluxion/core 0.8.0 → 0.9.0

package/dist/index.js

@@ -1,4 +1,5 @@
 import { randomUUID, randomBytes, createHmac, createDecipheriv, createCipheriv, createECDH, timingSafeEqual, createHash } from 'crypto';
+import { PassThrough, Readable } from 'stream';
 import WebSocket, { WebSocketServer } from 'ws';
 
 // src/index.ts
@@ -10,6 +11,7 @@ var INTERNAL_HANDSHAKE_EVENT = "__handshake";
 var INTERNAL_SESSION_TICKET_EVENT = "__session:ticket";
 var INTERNAL_RPC_REQUEST_EVENT = "__rpc:req";
 var INTERNAL_RPC_RESPONSE_EVENT = "__rpc:res";
+var INTERNAL_STREAM_FRAME_EVENT = "__stream:frame";
 var READY_EVENT = "ready";
 var HANDSHAKE_CURVE = "prime256v1";
 var HANDSHAKE_PROTOCOL_VERSION = 1;
@@ -27,6 +29,9 @@ var DEFAULT_HEARTBEAT_TIMEOUT_MS = 15e3;
 var DEFAULT_SESSION_RESUMPTION_ENABLED = true;
 var DEFAULT_SESSION_TICKET_TTL_MS = 10 * 6e4;
 var DEFAULT_SESSION_TICKET_MAX_CACHE_SIZE = 1e4;
+var STREAM_FRAME_VERSION = 1;
+var DEFAULT_STREAM_CHUNK_SIZE_BYTES = 64 * 1024;
+var MAX_STREAM_CHUNK_SIZE_BYTES = 1024 * 1024;
 var RESUMPTION_NONCE_LENGTH = 16;
 var DEFAULT_RECONNECT_INITIAL_DELAY_MS = 250;
 var DEFAULT_RECONNECT_MAX_DELAY_MS = 1e4;
@@ -249,7 +254,7 @@ function decodeCloseReason(reason) {
   return reason.toString("utf8");
 }
 function isReservedEmitEvent(event) {
-  return event === INTERNAL_HANDSHAKE_EVENT || event === INTERNAL_SESSION_TICKET_EVENT || event === INTERNAL_RPC_REQUEST_EVENT || event === INTERNAL_RPC_RESPONSE_EVENT || event === READY_EVENT;
+  return event === INTERNAL_HANDSHAKE_EVENT || event === INTERNAL_SESSION_TICKET_EVENT || event === INTERNAL_RPC_REQUEST_EVENT || event === INTERNAL_RPC_RESPONSE_EVENT || event === INTERNAL_STREAM_FRAME_EVENT || event === READY_EVENT;
 }
 function isPromiseLike(value) {
   return typeof value === "object" && value !== null && "then" in value;
@@ -261,6 +266,240 @@ function normalizeRpcTimeout(timeoutMs) {
   }
   return resolvedTimeoutMs;
 }
+function normalizeStreamChunkSize(chunkSizeBytes) {
+  const resolvedChunkSize = chunkSizeBytes ?? DEFAULT_STREAM_CHUNK_SIZE_BYTES;
+  if (!Number.isInteger(resolvedChunkSize) || resolvedChunkSize <= 0) {
+    throw new Error("Stream chunkSizeBytes must be a positive integer.");
+  }
+  if (resolvedChunkSize > MAX_STREAM_CHUNK_SIZE_BYTES) {
+    throw new Error(
+      `Stream chunkSizeBytes cannot exceed ${MAX_STREAM_CHUNK_SIZE_BYTES} bytes.`
+    );
+  }
+  return resolvedChunkSize;
+}
+function resolveKnownStreamSourceSize(source, hint) {
+  if (hint !== void 0) {
+    if (!Number.isInteger(hint) || hint < 0) {
+      throw new Error("Stream totalBytes must be a non-negative integer.");
+    }
+    return hint;
+  }
+  if (Buffer.isBuffer(source)) {
+    return source.length;
+  }
+  if (source instanceof Uint8Array) {
+    return source.byteLength;
+  }
+  return void 0;
+}
+function normalizeChunkSourceValue(value) {
+  if (Buffer.isBuffer(value)) {
+    return value;
+  }
+  if (value instanceof Uint8Array) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (value instanceof ArrayBuffer) {
+    return Buffer.from(value);
+  }
+  if (typeof value === "string") {
+    return Buffer.from(value, "utf8");
+  }
+  throw new Error("Stream source yielded an unsupported chunk value.");
+}
+function isAsyncIterableValue(value) {
+  return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+}
+function isReadableSource(value) {
+  return value instanceof Readable;
+}
+function splitChunkBuffer(chunk, chunkSizeBytes) {
+  if (chunk.length <= chunkSizeBytes) {
+    return [chunk];
+  }
+  const splitChunks = [];
+  for (let offset = 0; offset < chunk.length; offset += chunkSizeBytes) {
+    splitChunks.push(chunk.subarray(offset, offset + chunkSizeBytes));
+  }
+  return splitChunks;
+}
+async function* createChunkStreamIterator(source, chunkSizeBytes) {
+  if (Buffer.isBuffer(source)) {
+    yield* splitChunkBuffer(source, chunkSizeBytes);
+    return;
+  }
+  if (source instanceof Uint8Array) {
+    yield* splitChunkBuffer(
+      Buffer.from(source.buffer, source.byteOffset, source.byteLength),
+      chunkSizeBytes
+    );
+    return;
+  }
+  if (isReadableSource(source) || isAsyncIterableValue(source)) {
+    for await (const chunkValue of source) {
+      const normalizedChunk = normalizeChunkSourceValue(chunkValue);
+      if (normalizedChunk.length === 0) {
+        continue;
+      }
+      yield* splitChunkBuffer(normalizedChunk, chunkSizeBytes);
+    }
+    return;
+  }
+  throw new Error("Unsupported stream source type.");
+}
+function parseStreamFramePayload(data) {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("Invalid stream frame payload format.");
+  }
+  const payload = data;
+  if (payload.version !== STREAM_FRAME_VERSION) {
+    throw new Error(`Unsupported stream frame version: ${String(payload.version)}.`);
+  }
+  if (typeof payload.streamId !== "string" || payload.streamId.trim().length === 0) {
+    throw new Error("Stream frame streamId must be a non-empty string.");
+  }
+  if (payload.type === "start") {
+    if (typeof payload.event !== "string" || payload.event.trim().length === 0) {
+      throw new Error("Stream start frame event must be a non-empty string.");
+    }
+    if (payload.totalBytes !== void 0 && (!Number.isInteger(payload.totalBytes) || payload.totalBytes < 0)) {
+      throw new Error("Stream start frame totalBytes must be a non-negative integer.");
+    }
+    if (payload.metadata !== void 0 && !isPlainObject(payload.metadata)) {
+      throw new Error("Stream start frame metadata must be a plain object when provided.");
+    }
+    return {
+      version: STREAM_FRAME_VERSION,
+      type: "start",
+      streamId: payload.streamId.trim(),
+      event: payload.event.trim(),
+      ...payload.metadata ? { metadata: payload.metadata } : {},
+      ...payload.totalBytes !== void 0 ? { totalBytes: payload.totalBytes } : {}
+    };
+  }
+  if (payload.type === "chunk") {
+    const { index, byteLength } = payload;
+    if (typeof index !== "number" || !Number.isInteger(index) || index < 0) {
+      throw new Error("Stream chunk frame index must be a non-negative integer.");
+    }
+    if (typeof payload.payload !== "string" || payload.payload.length === 0) {
+      throw new Error("Stream chunk frame payload must be a non-empty base64 string.");
+    }
+    if (typeof byteLength !== "number" || !Number.isInteger(byteLength) || byteLength <= 0) {
+      throw new Error("Stream chunk frame byteLength must be a positive integer.");
+    }
+    return {
+      version: STREAM_FRAME_VERSION,
+      type: "chunk",
+      streamId: payload.streamId.trim(),
+      index,
+      payload: payload.payload,
+      byteLength
+    };
+  }
+  if (payload.type === "end") {
+    const { chunkCount, totalBytes } = payload;
+    if (typeof chunkCount !== "number" || !Number.isInteger(chunkCount) || chunkCount < 0) {
+      throw new Error("Stream end frame chunkCount must be a non-negative integer.");
+    }
+    if (typeof totalBytes !== "number" || !Number.isInteger(totalBytes) || totalBytes < 0) {
+      throw new Error("Stream end frame totalBytes must be a non-negative integer.");
+    }
+    return {
+      version: STREAM_FRAME_VERSION,
+      type: "end",
+      streamId: payload.streamId.trim(),
+      chunkCount,
+      totalBytes
+    };
+  }
+  if (payload.type === "abort") {
+    if (typeof payload.reason !== "string" || payload.reason.trim().length === 0) {
+      throw new Error("Stream abort frame reason must be a non-empty string.");
+    }
+    return {
+      version: STREAM_FRAME_VERSION,
+      type: "abort",
+      streamId: payload.streamId.trim(),
+      reason: payload.reason.trim()
+    };
+  }
+  throw new Error("Unsupported stream frame type.");
+}
+async function transmitChunkedStreamFrames(event, source, options, sendFrame) {
+  const chunkSizeBytes = normalizeStreamChunkSize(options?.chunkSizeBytes);
+  const totalBytesHint = resolveKnownStreamSourceSize(source, options?.totalBytes);
+  if (options?.metadata !== void 0 && !isPlainObject(options.metadata)) {
+    throw new Error("Stream metadata must be a plain object when provided.");
+  }
+  if (options?.signal?.aborted) {
+    throw new Error("Stream transfer aborted before dispatch.");
+  }
+  const streamId = randomUUID();
+  let chunkCount = 0;
+  let totalBytes = 0;
+  await sendFrame({
+    version: STREAM_FRAME_VERSION,
+    type: "start",
+    streamId,
+    event,
+    ...options?.metadata ? { metadata: options.metadata } : {},
+    ...totalBytesHint !== void 0 ? { totalBytes: totalBytesHint } : {}
+  });
+  try {
+    for await (const chunkBuffer of createChunkStreamIterator(source, chunkSizeBytes)) {
+      if (options?.signal?.aborted) {
+        throw new Error("Stream transfer aborted by caller signal.");
+      }
+      if (chunkBuffer.length === 0) {
+        continue;
+      }
+      await sendFrame({
+        version: STREAM_FRAME_VERSION,
+        type: "chunk",
+        streamId,
+        index: chunkCount,
+        payload: chunkBuffer.toString("base64"),
+        byteLength: chunkBuffer.length
+      });
+      chunkCount += 1;
+      totalBytes += chunkBuffer.length;
+    }
+    if (totalBytesHint !== void 0 && totalBytes !== totalBytesHint) {
+      throw new Error(
+        `Stream totalBytes mismatch. Expected ${totalBytesHint}, received ${totalBytes}.`
+      );
+    }
+    await sendFrame({
+      version: STREAM_FRAME_VERSION,
+      type: "end",
+      streamId,
+      chunkCount,
+      totalBytes
+    });
+    return {
+      streamId,
+      chunkCount,
+      totalBytes
+    };
+  } catch (error) {
+    const normalizedError = normalizeToError(
+      error,
+      `Chunked stream transfer failed for event "${event}".`
+    );
+    try {
+      await sendFrame({
+        version: STREAM_FRAME_VERSION,
+        type: "abort",
+        streamId,
+        reason: normalizedError.message
+      });
+    } catch {
+    }
+    throw normalizedError;
+  }
+}
 function parseRpcRequestPayload(data) {
   if (typeof data !== "object" || data === null) {
     throw new Error("Invalid RPC request payload format.");
@@ -557,6 +796,7 @@ var SecureServer = class {
   clientsById = /* @__PURE__ */ new Map();
   clientIdBySocket = /* @__PURE__ */ new Map();
   customEventHandlers = /* @__PURE__ */ new Map();
+  streamEventHandlers = /* @__PURE__ */ new Map();
   connectionHandlers = /* @__PURE__ */ new Set();
   disconnectHandlers = /* @__PURE__ */ new Set();
   readyHandlers = /* @__PURE__ */ new Set();
@@ -567,6 +807,7 @@ var SecureServer = class {
   sharedSecretBySocket = /* @__PURE__ */ new WeakMap();
   encryptionKeyBySocket = /* @__PURE__ */ new WeakMap();
   pendingPayloadsBySocket = /* @__PURE__ */ new WeakMap();
+  incomingStreamsBySocket = /* @__PURE__ */ new WeakMap();
   pendingRpcRequestsBySocket = /* @__PURE__ */ new WeakMap();
   heartbeatStateBySocket = /* @__PURE__ */ new WeakMap();
   roomMembersByName = /* @__PURE__ */ new Map();
@@ -715,6 +956,38 @@ var SecureServer = class {
     }
     return this;
   }
+  onStream(event, handler) {
+    try {
+      if (isReservedEmitEvent(event)) {
+        throw new Error(`The event "${event}" is reserved and cannot be used as a stream event.`);
+      }
+      const listeners = this.streamEventHandlers.get(event) ?? /* @__PURE__ */ new Set();
+      listeners.add(handler);
+      this.streamEventHandlers.set(event, listeners);
+    } catch (error) {
+      this.notifyError(
+        normalizeToError(error, "Failed to register server stream handler.")
+      );
+    }
+    return this;
+  }
+  offStream(event, handler) {
+    try {
+      const listeners = this.streamEventHandlers.get(event);
+      if (!listeners) {
+        return this;
+      }
+      listeners.delete(handler);
+      if (listeners.size === 0) {
+        this.streamEventHandlers.delete(event);
+      }
+    } catch (error) {
+      this.notifyError(
+        normalizeToError(error, "Failed to remove server stream handler.")
+      );
+    }
+    return this;
+  }
   use(middleware) {
     try {
       if (typeof middleware !== "function") {
@@ -790,6 +1063,40 @@ var SecureServer = class {
       return false;
     }
   }
+  async emitStreamTo(clientId, event, source, options) {
+    try {
+      if (isReservedEmitEvent(event)) {
+        throw new Error(`The event "${event}" is reserved and cannot be emitted manually.`);
+      }
+      const client = this.clientsById.get(clientId);
+      if (!client) {
+        throw new Error(`Client with id ${clientId} was not found.`);
+      }
+      if (!this.isClientHandshakeReady(client.socket)) {
+        throw new Error(
+          `Cannot stream event "${event}" before secure handshake completion for client ${client.id}.`
+        );
+      }
+      return await transmitChunkedStreamFrames(
+        event,
+        source,
+        options,
+        async (framePayload) => {
+          await this.sendEncryptedEnvelope(client.socket, {
+            event: INTERNAL_STREAM_FRAME_EVENT,
+            data: framePayload
+          });
+        }
+      );
+    } catch (error) {
+      const normalizedError = normalizeToError(
+        error,
+        `Failed to emit chunked stream event "${event}" to client ${clientId}.`
+      );
+      this.notifyError(normalizedError);
+      throw normalizedError;
+    }
+  }
   to(room) {
     const normalizedRoom = this.normalizeRoomName(room);
     return {
@@ -822,6 +1129,10 @@ var SecureServer = class {
           client.socket,
           new Error("Server closed before ACK response was received.")
         );
+        this.cleanupIncomingStreamsForSocket(
+          client.socket,
+          "Server closed before stream transfer completed."
+        );
         this.middlewareMetadataBySocket.delete(client.socket);
         if (client.socket.readyState === WebSocket.OPEN || client.socket.readyState === WebSocket.CONNECTING) {
           client.socket.close(code, reason);
@@ -1365,6 +1676,10 @@ var SecureServer = class {
         await this.handleRpcRequest(client, decryptedEnvelope.data);
         return;
       }
+      if (decryptedEnvelope.event === INTERNAL_STREAM_FRAME_EVENT) {
+        this.handleIncomingStreamFrame(client, decryptedEnvelope.data);
+        return;
+      }
       if (decryptedEnvelope.event === INTERNAL_SESSION_TICKET_EVENT) {
         this.notifyError(
           new Error(
@@ -1406,6 +1721,10 @@ var SecureServer = class {
       this.pendingRpcRequestsBySocket.delete(client.socket);
       this.heartbeatStateBySocket.delete(client.socket);
       this.middlewareMetadataBySocket.delete(client.socket);
+      this.cleanupIncomingStreamsForSocket(
+        client.socket,
+        `Client ${client.id} disconnected before stream transfer completed.`
+      );
       const decodedReason = decodeCloseReason(reason);
       for (const handler of this.disconnectHandlers) {
         try {
@@ -1451,6 +1770,197 @@ var SecureServer = class {
       }
     }
   }
+  getOrCreateIncomingServerStreams(socket) {
+    const existingStreams = this.incomingStreamsBySocket.get(socket);
+    if (existingStreams) {
+      return existingStreams;
+    }
+    const streamMap = /* @__PURE__ */ new Map();
+    this.incomingStreamsBySocket.set(socket, streamMap);
+    return streamMap;
+  }
+  cleanupIncomingStreamsForSocket(socket, reason) {
+    const streamMap = this.incomingStreamsBySocket.get(socket);
+    if (!streamMap) {
+      return;
+    }
+    for (const streamState of streamMap.values()) {
+      streamState.stream.destroy(new Error(reason));
+    }
+    streamMap.clear();
+    this.incomingStreamsBySocket.delete(socket);
+  }
+  abortIncomingServerStream(socket, streamId, reason) {
+    const streamMap = this.incomingStreamsBySocket.get(socket);
+    if (!streamMap) {
+      return;
+    }
+    const streamState = streamMap.get(streamId);
+    if (!streamState) {
+      return;
+    }
+    streamState.stream.destroy(new Error(reason));
+    streamMap.delete(streamId);
+    if (streamMap.size === 0) {
+      this.incomingStreamsBySocket.delete(socket);
+    }
+  }
+  dispatchServerStreamEvent(event, stream, info, client) {
+    const handlers = this.streamEventHandlers.get(event);
+    if (!handlers || handlers.size === 0) {
+      stream.resume();
+      this.notifyError(
+        new Error(
+          `No stream handler is registered for event "${event}" on server client ${client.id}.`
+        )
+      );
+      return;
+    }
+    for (const handler of handlers) {
+      try {
+        const handlerResult = handler(stream, info, client);
+        if (isPromiseLike(handlerResult)) {
+          void Promise.resolve(handlerResult).catch((error) => {
+            this.notifyError(
+              normalizeToError(
+                error,
+                `Server stream handler failed for event ${event}.`
+              )
+            );
+          });
+        }
+      } catch (error) {
+        this.notifyError(
+          normalizeToError(
+            error,
+            `Server stream handler failed for event ${event}.`
+          )
+        );
+      }
+    }
+  }
+  handleIncomingStreamStartFrame(client, framePayload) {
+    if (isReservedEmitEvent(framePayload.event)) {
+      throw new Error(
+        `Reserved event "${framePayload.event}" cannot be used for stream transport.`
+      );
+    }
+    const incomingStreams = this.getOrCreateIncomingServerStreams(client.socket);
+    if (incomingStreams.has(framePayload.streamId)) {
+      throw new Error(
+        `Stream ${framePayload.streamId} already exists for client ${client.id}.`
+      );
+    }
+    const stream = new PassThrough();
+    const streamInfo = {
+      streamId: framePayload.streamId,
+      event: framePayload.event,
+      startedAt: Date.now(),
+      ...framePayload.metadata !== void 0 ? { metadata: framePayload.metadata } : {},
+      ...framePayload.totalBytes !== void 0 ? { totalBytes: framePayload.totalBytes } : {}
+    };
+    incomingStreams.set(framePayload.streamId, {
+      info: streamInfo,
+      stream,
+      expectedChunkIndex: 0,
+      receivedBytes: 0
+    });
+    this.dispatchServerStreamEvent(framePayload.event, stream, streamInfo, client);
+  }
+  handleIncomingStreamChunkFrame(client, framePayload) {
+    const incomingStreams = this.incomingStreamsBySocket.get(client.socket);
+    const streamState = incomingStreams?.get(framePayload.streamId);
+    if (!incomingStreams || !streamState) {
+      throw new Error(
+        `Stream ${framePayload.streamId} is unknown for client ${client.id}.`
+      );
+    }
+    if (framePayload.index !== streamState.expectedChunkIndex) {
+      throw new Error(
+        `Out-of-order chunk index for stream ${framePayload.streamId}. Expected ${streamState.expectedChunkIndex}, received ${framePayload.index}.`
+      );
+    }
+    const chunkBuffer = decodeBase64ToBuffer(
+      framePayload.payload,
+      `Stream chunk payload (${framePayload.streamId})`
+    );
+    if (chunkBuffer.length !== framePayload.byteLength) {
+      throw new Error(
+        `Stream ${framePayload.streamId} byteLength mismatch. Expected ${framePayload.byteLength}, received ${chunkBuffer.length}.`
+      );
+    }
+    streamState.expectedChunkIndex += 1;
+    streamState.receivedBytes += chunkBuffer.length;
+    streamState.stream.write(chunkBuffer);
+  }
+  handleIncomingStreamEndFrame(client, framePayload) {
+    const incomingStreams = this.incomingStreamsBySocket.get(client.socket);
+    const streamState = incomingStreams?.get(framePayload.streamId);
+    if (!incomingStreams || !streamState) {
+      throw new Error(
+        `Stream ${framePayload.streamId} is unknown for client ${client.id}.`
+      );
+    }
+    if (framePayload.chunkCount !== streamState.expectedChunkIndex) {
+      throw new Error(
+        `Stream ${framePayload.streamId} chunkCount mismatch. Expected ${streamState.expectedChunkIndex}, received ${framePayload.chunkCount}.`
+      );
+    }
+    if (framePayload.totalBytes !== streamState.receivedBytes) {
+      throw new Error(
+        `Stream ${framePayload.streamId} totalBytes mismatch. Expected ${streamState.receivedBytes}, received ${framePayload.totalBytes}.`
+      );
+    }
+    if (streamState.info.totalBytes !== void 0 && streamState.info.totalBytes !== streamState.receivedBytes) {
+      throw new Error(
+        `Stream ${framePayload.streamId} violated announced totalBytes (${streamState.info.totalBytes}).`
+      );
+    }
+    streamState.stream.end();
+    incomingStreams.delete(framePayload.streamId);
+    if (incomingStreams.size === 0) {
+      this.incomingStreamsBySocket.delete(client.socket);
+    }
+  }
+  handleIncomingStreamAbortFrame(client, framePayload) {
+    this.abortIncomingServerStream(
+      client.socket,
+      framePayload.streamId,
+      framePayload.reason
+    );
+  }
+  handleIncomingStreamFrame(client, data) {
+    let framePayload = null;
+    try {
+      framePayload = parseStreamFramePayload(data);
+      if (framePayload.type === "start") {
+        this.handleIncomingStreamStartFrame(client, framePayload);
+        return;
+      }
+      if (framePayload.type === "chunk") {
+        this.handleIncomingStreamChunkFrame(client, framePayload);
+        return;
+      }
+      if (framePayload.type === "end") {
+        this.handleIncomingStreamEndFrame(client, framePayload);
+        return;
+      }
+      this.handleIncomingStreamAbortFrame(client, framePayload);
+    } catch (error) {
+      const normalizedError = normalizeToError(
+        error,
+        `Failed to process incoming stream frame for client ${client.id}.`
+      );
+      if (framePayload) {
+        this.abortIncomingServerStream(
+          client.socket,
+          framePayload.streamId,
+          normalizedError.message
+        );
+      }
+      this.notifyError(normalizedError);
+    }
+  }
   async executeServerMiddleware(context) {
     if (this.middlewareHandlers.length === 0) {
       return;
@@ -1879,6 +2389,9 @@ var SecureServer = class {
         }
         return this.emitTo(clientId, event, data, callbackOrOptions ?? {});
       },
+      emitStream: (event, source, options) => {
+        return this.emitStreamTo(clientId, event, source, options);
+      },
       join: (room) => this.joinClientToRoom(clientId, room),
       leave: (room) => this.leaveClientFromRoom(clientId, room),
       leaveAll: () => this.leaveClientFromAllRooms(clientId)
@@ -2039,6 +2552,7 @@ var SecureClient = class {
   reconnectTimer = null;
   isManualDisconnectRequested = false;
   customEventHandlers = /* @__PURE__ */ new Map();
+  streamEventHandlers = /* @__PURE__ */ new Map();
   connectHandlers = /* @__PURE__ */ new Set();
   disconnectHandlers = /* @__PURE__ */ new Set();
   readyHandlers = /* @__PURE__ */ new Set();
@@ -2046,6 +2560,7 @@ var SecureClient = class {
   handshakeState = null;
   pendingPayloadQueue = [];
   pendingRpcRequests = /* @__PURE__ */ new Map();
+  incomingStreams = /* @__PURE__ */ new Map();
   sessionTicket = null;
   get readyState() {
     return this.socket?.readyState ?? null;
@@ -2155,6 +2670,38 @@ var SecureClient = class {
     }
     return this;
   }
+  onStream(event, handler) {
+    try {
+      if (isReservedEmitEvent(event)) {
+        throw new Error(`The event "${event}" is reserved and cannot be used as a stream event.`);
+      }
+      const listeners = this.streamEventHandlers.get(event) ?? /* @__PURE__ */ new Set();
+      listeners.add(handler);
+      this.streamEventHandlers.set(event, listeners);
+    } catch (error) {
+      this.notifyError(
+        normalizeToError(error, "Failed to register client stream handler.")
+      );
+    }
+    return this;
+  }
+  offStream(event, handler) {
+    try {
+      const listeners = this.streamEventHandlers.get(event);
+      if (!listeners) {
+        return this;
+      }
+      listeners.delete(handler);
+      if (listeners.size === 0) {
+        this.streamEventHandlers.delete(event);
+      }
+    } catch (error) {
+      this.notifyError(
+        normalizeToError(error, "Failed to remove client stream handler.")
+      );
+    }
+    return this;
+  }
   emit(event, data, callbackOrOptions, maybeCallback) {
     const ackArgs = resolveAckArguments(callbackOrOptions, maybeCallback);
     try {
@@ -2200,6 +2747,39 @@ var SecureClient = class {
       return false;
     }
   }
+  async emitStream(event, source, options) {
+    try {
+      if (isReservedEmitEvent(event)) {
+        throw new Error(`The event "${event}" is reserved and cannot be emitted manually.`);
+      }
+      if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+        throw new Error("Client socket is not connected.");
+      }
+      if (!this.isHandshakeReady()) {
+        throw new Error(
+          `Cannot stream event "${event}" before secure handshake completion.`
+        );
+      }
+      return await transmitChunkedStreamFrames(
+        event,
+        source,
+        options,
+        async (framePayload) => {
+          await this.sendEncryptedEnvelope({
+            event: INTERNAL_STREAM_FRAME_EVENT,
+            data: framePayload
+          });
+        }
+      );
+    } catch (error) {
+      const normalizedError = normalizeToError(
+        error,
+        `Failed to emit chunked stream event "${event}".`
+      );
+      this.notifyError(normalizedError);
+      throw normalizedError;
+    }
+  }
   resolveReconnectConfig(reconnectOptions) {
     if (typeof reconnectOptions === "boolean") {
       return {
@@ -2363,6 +2943,10 @@ var SecureClient = class {
         void this.handleRpcRequest(decryptedEnvelope.data);
         return;
       }
+      if (decryptedEnvelope.event === INTERNAL_STREAM_FRAME_EVENT) {
+        this.handleIncomingStreamFrame(decryptedEnvelope.data);
+        return;
+      }
       if (decryptedEnvelope.event === INTERNAL_SESSION_TICKET_EVENT) {
         this.handleSessionTicket(decryptedEnvelope.data);
         return;
@@ -2377,6 +2961,9 @@ var SecureClient = class {
       this.socket = null;
       this.handshakeState = null;
       this.pendingPayloadQueue = [];
+      this.cleanupIncomingStreams(
+        "Client disconnected before stream transfer completed."
+      );
       this.rejectPendingRpcRequests(
         new Error("Client disconnected before ACK response was received.")
       );
@@ -2423,6 +3010,151 @@ var SecureClient = class {
       }
     }
   }
+  cleanupIncomingStreams(reason) {
+    for (const streamState of this.incomingStreams.values()) {
+      streamState.stream.destroy(new Error(reason));
+    }
+    this.incomingStreams.clear();
+  }
+  abortIncomingClientStream(streamId, reason) {
+    const streamState = this.incomingStreams.get(streamId);
+    if (!streamState) {
+      return;
+    }
+    streamState.stream.destroy(new Error(reason));
+    this.incomingStreams.delete(streamId);
+  }
+  dispatchClientStreamEvent(event, stream, info) {
+    const handlers = this.streamEventHandlers.get(event);
+    if (!handlers || handlers.size === 0) {
+      stream.resume();
+      this.notifyError(
+        new Error(`No stream handler is registered for event "${event}" on client.`)
+      );
+      return;
+    }
+    for (const handler of handlers) {
+      try {
+        const handlerResult = handler(stream, info);
+        if (isPromiseLike(handlerResult)) {
+          void Promise.resolve(handlerResult).catch((error) => {
+            this.notifyError(
+              normalizeToError(
+                error,
+                `Client stream handler failed for event ${event}.`
+              )
+            );
+          });
+        }
+      } catch (error) {
+        this.notifyError(
+          normalizeToError(error, `Client stream handler failed for event ${event}.`)
+        );
+      }
+    }
+  }
+  handleIncomingClientStreamStartFrame(framePayload) {
+    if (isReservedEmitEvent(framePayload.event)) {
+      throw new Error(
+        `Reserved event "${framePayload.event}" cannot be used for stream transport.`
+      );
+    }
+    if (this.incomingStreams.has(framePayload.streamId)) {
+      throw new Error(`Stream ${framePayload.streamId} already exists on client.`);
+    }
+    const stream = new PassThrough();
+    const streamInfo = {
+      streamId: framePayload.streamId,
+      event: framePayload.event,
+      startedAt: Date.now(),
+      ...framePayload.metadata !== void 0 ? { metadata: framePayload.metadata } : {},
+      ...framePayload.totalBytes !== void 0 ? { totalBytes: framePayload.totalBytes } : {}
+    };
+    this.incomingStreams.set(framePayload.streamId, {
+      info: streamInfo,
+      stream,
+      expectedChunkIndex: 0,
+      receivedBytes: 0
+    });
+    this.dispatchClientStreamEvent(framePayload.event, stream, streamInfo);
+  }
+  handleIncomingClientStreamChunkFrame(framePayload) {
+    const streamState = this.incomingStreams.get(framePayload.streamId);
+    if (!streamState) {
+      throw new Error(`Stream ${framePayload.streamId} is unknown on client.`);
+    }
+    if (framePayload.index !== streamState.expectedChunkIndex) {
+      throw new Error(
+        `Out-of-order chunk index for stream ${framePayload.streamId}. Expected ${streamState.expectedChunkIndex}, received ${framePayload.index}.`
+      );
+    }
+    const chunkBuffer = decodeBase64ToBuffer(
+      framePayload.payload,
+      `Stream chunk payload (${framePayload.streamId})`
+    );
+    if (chunkBuffer.length !== framePayload.byteLength) {
+      throw new Error(
+        `Stream ${framePayload.streamId} byteLength mismatch. Expected ${framePayload.byteLength}, received ${chunkBuffer.length}.`
+      );
+    }
+    streamState.expectedChunkIndex += 1;
+    streamState.receivedBytes += chunkBuffer.length;
+    streamState.stream.write(chunkBuffer);
+  }
+  handleIncomingClientStreamEndFrame(framePayload) {
+    const streamState = this.incomingStreams.get(framePayload.streamId);
+    if (!streamState) {
+      throw new Error(`Stream ${framePayload.streamId} is unknown on client.`);
+    }
+    if (framePayload.chunkCount !== streamState.expectedChunkIndex) {
+      throw new Error(
+        `Stream ${framePayload.streamId} chunkCount mismatch. Expected ${streamState.expectedChunkIndex}, received ${framePayload.chunkCount}.`
+      );
+    }
+    if (framePayload.totalBytes !== streamState.receivedBytes) {
+      throw new Error(
+        `Stream ${framePayload.streamId} totalBytes mismatch. Expected ${streamState.receivedBytes}, received ${framePayload.totalBytes}.`
+      );
+    }
+    if (streamState.info.totalBytes !== void 0 && streamState.info.totalBytes !== streamState.receivedBytes) {
+      throw new Error(
+        `Stream ${framePayload.streamId} violated announced totalBytes (${streamState.info.totalBytes}).`
+      );
+    }
+    streamState.stream.end();
+    this.incomingStreams.delete(framePayload.streamId);
+  }
+  handleIncomingClientStreamAbortFrame(framePayload) {
+    this.abortIncomingClientStream(framePayload.streamId, framePayload.reason);
+  }
+  handleIncomingStreamFrame(data) {
+    let framePayload = null;
+    try {
+      framePayload = parseStreamFramePayload(data);
+      if (framePayload.type === "start") {
+        this.handleIncomingClientStreamStartFrame(framePayload);
+        return;
+      }
+      if (framePayload.type === "chunk") {
+        this.handleIncomingClientStreamChunkFrame(framePayload);
+        return;
+      }
+      if (framePayload.type === "end") {
+        this.handleIncomingClientStreamEndFrame(framePayload);
+        return;
+      }
+      this.handleIncomingClientStreamAbortFrame(framePayload);
+    } catch (error) {
+      const normalizedError = normalizeToError(
+        error,
+        "Failed to process incoming stream frame on client."
+      );
+      if (framePayload) {
+        this.abortIncomingClientStream(framePayload.streamId, normalizedError.message);
+      }
+      this.notifyError(normalizedError);
+    }
+  }
   notifyConnect() {
     for (const handler of this.connectHandlers) {
       try {