@aegis-fluxion/core 0.7.2 → 0.9.0

package/dist/index.js

@@ -1,4 +1,5 @@
-import { randomUUID, createDecipheriv, randomBytes, createCipheriv, createECDH, createHash } from 'crypto';
+import { randomUUID, randomBytes, createHmac, createDecipheriv, createCipheriv, createECDH, timingSafeEqual, createHash } from 'crypto';
+import { PassThrough, Readable } from 'stream';
 import WebSocket, { WebSocketServer } from 'ws';
 
 // src/index.ts
@@ -7,20 +8,31 @@ var DEFAULT_CLOSE_REASON = "";
 var POLICY_VIOLATION_CLOSE_CODE = 1008;
 var POLICY_VIOLATION_CLOSE_REASON = "Connection rejected by middleware.";
 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;
 var ENCRYPTION_ALGORITHM = "aes-256-gcm";
 var GCM_IV_LENGTH = 12;
 var GCM_AUTH_TAG_LENGTH = 16;
 var ENCRYPTION_KEY_LENGTH = 32;
 var ENCRYPTED_PACKET_VERSION = 1;
 var ENCRYPTED_PACKET_PREFIX_LENGTH = 1 + GCM_IV_LENGTH + GCM_AUTH_TAG_LENGTH;
+var SESSION_TICKET_VERSION = 1;
 var BINARY_PAYLOAD_MARKER = "__afxBinaryPayload";
 var BINARY_PAYLOAD_VERSION = 1;
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 15e3;
 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;
 var DEFAULT_RECONNECT_FACTOR = 2;
@@ -242,7 +254,7 @@ function decodeCloseReason(reason) {
   return reason.toString("utf8");
 }
 function isReservedEmitEvent(event) {
-  return event === INTERNAL_HANDSHAKE_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;
@@ -254,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.");
@@ -333,16 +579,149 @@ function createEphemeralHandshakeState() {
     localPublicKey: ecdh.getPublicKey("base64")
   };
 }
+function decodeBase64ToBuffer(value, fieldName) {
+  if (typeof value !== "string") {
+    throw new Error(`${fieldName} must be a base64 string.`);
+  }
+  const normalizedValue = value.trim();
+  if (normalizedValue.length === 0) {
+    throw new Error(`${fieldName} must be a non-empty base64 string.`);
+  }
+  const decodedBuffer = Buffer.from(normalizedValue, "base64");
+  if (decodedBuffer.length === 0) {
+    throw new Error(`${fieldName} could not be decoded from base64.`);
+  }
+  const canonicalInput = normalizedValue.replace(/=+$/u, "");
+  const canonicalDecoded = decodedBuffer.toString("base64").replace(/=+$/u, "");
+  if (canonicalInput !== canonicalDecoded) {
+    throw new Error(`${fieldName} is not valid base64 content.`);
+  }
+  return decodedBuffer;
+}
+function equalsConstantTime(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  return timingSafeEqual(left, right);
+}
+function createResumeClientProof(sessionSecret, sessionId, clientNonce) {
+  return createHmac("sha256", sessionSecret).update("afx-resume-client-proof:v1").update(sessionId).update(clientNonce).digest();
+}
+function createResumeServerProof(resumedKey, sessionId, clientNonce) {
+  return createHmac("sha256", resumedKey).update("afx-resume-server-proof:v1").update(sessionId).update(clientNonce).digest();
+}
+function deriveSessionTicketSecret(baseKey) {
+  return createHmac("sha256", baseKey).update("afx-session-ticket:v1").digest();
+}
+function deriveResumedEncryptionKey(sessionSecret, clientNonce) {
+  const derivedKey = createHash("sha256").update("afx-resume-encryption-key:v1").update(sessionSecret).update(clientNonce).digest();
+  if (derivedKey.length !== ENCRYPTION_KEY_LENGTH) {
+    throw new Error("Failed to derive a valid resumed AES-256 key.");
+  }
+  return derivedKey;
+}
 function parseHandshakePayload(data) {
   if (typeof data !== "object" || data === null) {
     throw new Error("Invalid handshake payload format.");
   }
   const payload = data;
-  if (typeof payload.publicKey !== "string" || payload.publicKey.length === 0) {
-    throw new Error("Handshake payload must include a non-empty public key.");
+  if (typeof payload.type !== "string") {
+    if (typeof payload.publicKey === "string" && payload.publicKey.length > 0) {
+      return {
+        type: "hello",
+        protocolVersion: HANDSHAKE_PROTOCOL_VERSION,
+        publicKey: payload.publicKey
+      };
+    }
+    throw new Error("Handshake payload must include a valid type.");
+  }
+  const protocolVersion = payload.protocolVersion === void 0 ? HANDSHAKE_PROTOCOL_VERSION : payload.protocolVersion;
+  if (protocolVersion !== HANDSHAKE_PROTOCOL_VERSION) {
+    throw new Error(
+      `Unsupported handshake protocol version: ${String(protocolVersion)}.`
+    );
+  }
+  if (payload.type === "hello") {
+    if (typeof payload.publicKey !== "string" || payload.publicKey.length === 0) {
+      throw new Error("Handshake hello payload must include a non-empty public key.");
+    }
+    return {
+      type: "hello",
+      protocolVersion: HANDSHAKE_PROTOCOL_VERSION,
+      publicKey: payload.publicKey
+    };
+  }
+  if (payload.type === "resume") {
+    if (typeof payload.sessionId !== "string" || payload.sessionId.trim().length === 0) {
+      throw new Error("Handshake resume payload must include a non-empty sessionId.");
+    }
+    if (typeof payload.clientNonce !== "string" || payload.clientNonce.length === 0) {
+      throw new Error("Handshake resume payload must include a non-empty clientNonce.");
+    }
+    if (typeof payload.clientProof !== "string" || payload.clientProof.length === 0) {
+      throw new Error("Handshake resume payload must include a non-empty clientProof.");
+    }
+    return {
+      type: "resume",
+      protocolVersion: HANDSHAKE_PROTOCOL_VERSION,
+      sessionId: payload.sessionId.trim(),
+      clientNonce: payload.clientNonce,
+      clientProof: payload.clientProof
+    };
+  }
+  if (payload.type === "resume-ack") {
+    if (typeof payload.ok !== "boolean") {
+      throw new Error("Handshake resume-ack payload must include boolean ok.");
+    }
+    const normalizedPayload = {
+      type: "resume-ack",
+      protocolVersion: HANDSHAKE_PROTOCOL_VERSION,
+      ok: payload.ok
+    };
+    if (typeof payload.sessionId === "string" && payload.sessionId.trim().length > 0) {
+      normalizedPayload.sessionId = payload.sessionId.trim();
+    }
+    if (typeof payload.serverProof === "string" && payload.serverProof.length > 0) {
+      normalizedPayload.serverProof = payload.serverProof;
+    }
+    if (typeof payload.reason === "string" && payload.reason.trim().length > 0) {
+      normalizedPayload.reason = payload.reason.trim();
+    }
+    return normalizedPayload;
+  }
+  throw new Error(`Unsupported handshake payload type: ${payload.type}.`);
+}
+function parseSessionTicketPayload(data) {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("Invalid session ticket payload format.");
+  }
+  const payload = data;
+  if (payload.version !== SESSION_TICKET_VERSION) {
+    throw new Error(
+      `Unsupported session ticket payload version: ${String(payload.version)}.`
+    );
+  }
+  if (typeof payload.sessionId !== "string" || payload.sessionId.trim().length === 0) {
+    throw new Error("Session ticket payload must include a non-empty sessionId.");
+  }
+  if (typeof payload.secret !== "string" || payload.secret.length === 0) {
+    throw new Error("Session ticket payload must include a non-empty secret.");
+  }
+  if (typeof payload.issuedAt !== "number" || !Number.isFinite(payload.issuedAt)) {
+    throw new Error("Session ticket payload issuedAt must be a finite number.");
+  }
+  if (typeof payload.expiresAt !== "number" || !Number.isFinite(payload.expiresAt)) {
+    throw new Error("Session ticket payload expiresAt must be a finite number.");
+  }
+  if (payload.expiresAt <= payload.issuedAt) {
+    throw new Error("Session ticket payload expiresAt must be greater than issuedAt.");
   }
   return {
-    publicKey: payload.publicKey
+    version: SESSION_TICKET_VERSION,
+    sessionId: payload.sessionId.trim(),
+    secret: payload.secret,
+    issuedAt: payload.issuedAt,
+    expiresAt: payload.expiresAt
   };
 }
 function deriveEncryptionKey(sharedSecret) {
@@ -412,10 +791,12 @@ var SecureServer = class {
   adapter = null;
   heartbeatConfig;
   rateLimitConfig;
+  sessionResumptionConfig;
   heartbeatIntervalHandle = null;
   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();
@@ -426,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();
@@ -433,10 +815,12 @@ var SecureServer = class {
   clientIpByClientId = /* @__PURE__ */ new Map();
   rateLimitBucketsByClientId = /* @__PURE__ */ new Map();
   rateLimitBucketsByIp = /* @__PURE__ */ new Map();
+  sessionTicketStore = /* @__PURE__ */ new Map();
   constructor(options) {
-    const { heartbeat, rateLimit, adapter, ...socketServerOptions } = options;
+    const { heartbeat, rateLimit, sessionResumption, adapter, ...socketServerOptions } = options;
     this.heartbeatConfig = this.resolveHeartbeatConfig(heartbeat);
     this.rateLimitConfig = this.resolveRateLimitConfig(rateLimit);
+    this.sessionResumptionConfig = this.resolveSessionResumptionConfig(sessionResumption);
     this.socketServer = new WebSocketServer(socketServerOptions);
     this.bindSocketServerEvents();
     this.startHeartbeatLoop();
@@ -522,8 +906,8 @@ var SecureServer = class {
         this.errorHandlers.add(handler);
         return this;
       }
-      if (event === INTERNAL_HANDSHAKE_EVENT) {
-        throw new Error(`The event "${INTERNAL_HANDSHAKE_EVENT}" is reserved for internal use.`);
+      if (event === INTERNAL_HANDSHAKE_EVENT || event === INTERNAL_SESSION_TICKET_EVENT) {
+        throw new Error(`The event "${event}" is reserved for internal use.`);
       }
       const typedHandler = handler;
       const listeners = this.customEventHandlers.get(event) ?? /* @__PURE__ */ new Set();
@@ -554,7 +938,7 @@ var SecureServer = class {
         this.errorHandlers.delete(handler);
         return this;
       }
-      if (event === INTERNAL_HANDSHAKE_EVENT) {
+      if (event === INTERNAL_HANDSHAKE_EVENT || event === INTERNAL_SESSION_TICKET_EVENT) {
         return this;
       }
       const listeners = this.customEventHandlers.get(event);
@@ -572,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") {
@@ -647,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 {
@@ -679,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);
@@ -687,6 +1141,7 @@ var SecureServer = class {
       this.rateLimitBucketsByClientId.clear();
       this.rateLimitBucketsByIp.clear();
       this.clientIpByClientId.clear();
+      this.sessionTicketStore.clear();
       this.socketServer.close();
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to close server."));
@@ -763,6 +1218,94 @@ var SecureServer = class {
       disconnectReason
     };
   }
+  resolveSessionResumptionConfig(sessionResumptionOptions) {
+    const ticketTtlMs = sessionResumptionOptions?.ticketTtlMs ?? DEFAULT_SESSION_TICKET_TTL_MS;
+    const maxCachedTickets = sessionResumptionOptions?.maxCachedTickets ?? DEFAULT_SESSION_TICKET_MAX_CACHE_SIZE;
+    if (!Number.isFinite(ticketTtlMs) || ticketTtlMs <= 0) {
+      throw new Error(
+        "Server sessionResumption ticketTtlMs must be a positive number."
+      );
+    }
+    if (!Number.isInteger(maxCachedTickets) || maxCachedTickets <= 0) {
+      throw new Error(
+        "Server sessionResumption maxCachedTickets must be a positive integer."
+      );
+    }
+    return {
+      enabled: sessionResumptionOptions?.enabled ?? DEFAULT_SESSION_RESUMPTION_ENABLED,
+      ticketTtlMs,
+      maxCachedTickets
+    };
+  }
+  pruneExpiredSessionTickets(now) {
+    for (const [sessionId, ticketRecord] of this.sessionTicketStore.entries()) {
+      if (ticketRecord.expiresAt <= now) {
+        this.sessionTicketStore.delete(sessionId);
+      }
+    }
+  }
+  evictSessionTicketsIfNeeded() {
+    while (this.sessionTicketStore.size > this.sessionResumptionConfig.maxCachedTickets) {
+      let oldestSessionId = null;
+      let oldestIssuedAt = Number.POSITIVE_INFINITY;
+      for (const [sessionId, ticketRecord] of this.sessionTicketStore.entries()) {
+        if (ticketRecord.issuedAt < oldestIssuedAt) {
+          oldestIssuedAt = ticketRecord.issuedAt;
+          oldestSessionId = sessionId;
+        }
+      }
+      if (!oldestSessionId) {
+        break;
+      }
+      this.sessionTicketStore.delete(oldestSessionId);
+    }
+  }
+  getSessionTicket(sessionId) {
+    const now = Date.now();
+    this.pruneExpiredSessionTickets(now);
+    const ticketRecord = this.sessionTicketStore.get(sessionId);
+    if (!ticketRecord) {
+      return null;
+    }
+    if (ticketRecord.expiresAt <= now) {
+      this.sessionTicketStore.delete(sessionId);
+      return null;
+    }
+    return ticketRecord;
+  }
+  issueSessionTicket(socket, baseKey) {
+    if (!this.sessionResumptionConfig.enabled) {
+      return;
+    }
+    const now = Date.now();
+    this.pruneExpiredSessionTickets(now);
+    const sessionId = randomUUID();
+    const sessionSecret = deriveSessionTicketSecret(baseKey);
+    const expiresAt = now + this.sessionResumptionConfig.ticketTtlMs;
+    const ticketRecord = {
+      sessionId,
+      secret: sessionSecret,
+      issuedAt: now,
+      expiresAt
+    };
+    this.sessionTicketStore.set(sessionId, ticketRecord);
+    this.evictSessionTicketsIfNeeded();
+    const ticketPayload = {
+      version: SESSION_TICKET_VERSION,
+      sessionId,
+      secret: sessionSecret.toString("base64"),
+      issuedAt: now,
+      expiresAt
+    };
+    void this.sendOrQueuePayload(socket, {
+      event: INTERNAL_SESSION_TICKET_EVENT,
+      data: ticketPayload
+    }).catch((error) => {
+      this.notifyError(
+        normalizeToError(error, "Failed to deliver secure session ticket.")
+      );
+    });
+  }
   createRateLimitBucket(now) {
     return {
       windowStartedAt: now,
@@ -1133,6 +1676,18 @@ 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(
+            `Client ${client.id} attempted to send reserved internal session ticket event.`
+          )
+        );
+        return;
+      }
       const interceptedData = await this.applyMessageMiddleware(
         "incoming",
         client,
@@ -1166,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 {
@@ -1211,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;
@@ -1446,10 +2196,104 @@ var SecureServer = class {
     this.sendRaw(
       socket,
       serializePlainEnvelope(INTERNAL_HANDSHAKE_EVENT, {
+        type: "hello",
+        protocolVersion: HANDSHAKE_PROTOCOL_VERSION,
         publicKey: localPublicKey
       })
     );
   }
+  sendResumeAck(socket, payload) {
+    const responsePayload = {
+      type: "resume-ack",
+      protocolVersion: HANDSHAKE_PROTOCOL_VERSION,
+      ok: payload.ok
+    };
+    if (payload.sessionId !== void 0 && payload.sessionId.length > 0) {
+      responsePayload.sessionId = payload.sessionId;
+    }
+    if (payload.serverProof !== void 0 && payload.serverProof.length > 0) {
+      responsePayload.serverProof = payload.serverProof;
+    }
+    if (payload.reason !== void 0 && payload.reason.length > 0) {
+      responsePayload.reason = payload.reason;
+    }
+    this.sendRaw(
+      socket,
+      serializePlainEnvelope(INTERNAL_HANDSHAKE_EVENT, responsePayload)
+    );
+  }
+  handleResumeHandshake(client, payload) {
+    if (!this.sessionResumptionConfig.enabled) {
+      this.sendResumeAck(client.socket, {
+        ok: false,
+        reason: "Session resumption is disabled."
+      });
+      return;
+    }
+    const ticketRecord = this.getSessionTicket(payload.sessionId);
+    if (!ticketRecord) {
+      this.sendResumeAck(client.socket, {
+        ok: false,
+        reason: "Session ticket is unknown or expired."
+      });
+      return;
+    }
+    try {
+      const clientNonce = decodeBase64ToBuffer(
+        payload.clientNonce,
+        "Handshake resume clientNonce"
+      );
+      if (clientNonce.length !== RESUMPTION_NONCE_LENGTH) {
+        throw new Error(
+          `Handshake resume clientNonce must be ${RESUMPTION_NONCE_LENGTH} bytes.`
+        );
+      }
+      const receivedProof = decodeBase64ToBuffer(
+        payload.clientProof,
+        "Handshake resume clientProof"
+      );
+      const expectedProof = createResumeClientProof(
+        ticketRecord.secret,
+        ticketRecord.sessionId,
+        clientNonce
+      );
+      if (!equalsConstantTime(receivedProof, expectedProof)) {
+        this.sendResumeAck(client.socket, {
+          ok: false,
+          reason: "Session resumption proof validation failed."
+        });
+        return;
+      }
+      this.sessionTicketStore.delete(ticketRecord.sessionId);
+      const resumedKey = deriveResumedEncryptionKey(ticketRecord.secret, clientNonce);
+      const serverProof = createResumeServerProof(
+        resumedKey,
+        ticketRecord.sessionId,
+        clientNonce
+      ).toString("base64");
+      const handshakeState = this.handshakeStateBySocket.get(client.socket);
+      if (!handshakeState) {
+        throw new Error(`Missing handshake state for client ${client.id}.`);
+      }
+      this.sharedSecretBySocket.set(client.socket, resumedKey);
+      this.encryptionKeyBySocket.set(client.socket, resumedKey);
+      handshakeState.isReady = true;
+      this.sendResumeAck(client.socket, {
+        ok: true,
+        sessionId: ticketRecord.sessionId,
+        serverProof
+      });
+      void this.flushQueuedPayloads(client.socket);
+      this.notifyReady(client);
+      this.issueSessionTicket(client.socket, resumedKey);
+    } catch (error) {
+      this.sendResumeAck(client.socket, {
+        ok: false,
+        reason: "Session resumption payload was invalid."
+      });
+      this.notifyError(normalizeToError(error, "Failed to resume secure server session."));
+    }
+  }
   handleInternalHandshake(client, data) {
     try {
       const payload = parseHandshakePayload(data);
@@ -1460,14 +2304,22 @@ var SecureServer = class {
       if (handshakeState.isReady) {
         return;
       }
+      if (payload.type === "resume") {
+        this.handleResumeHandshake(client, payload);
+        return;
+      }
+      if (payload.type === "resume-ack") {
+        throw new Error("SecureServer received unexpected resume-ack handshake payload.");
+      }
       const remotePublicKey = Buffer.from(payload.publicKey, "base64");
       const sharedSecret = handshakeState.ecdh.computeSecret(remotePublicKey);
       const encryptionKey = deriveEncryptionKey(sharedSecret);
       this.sharedSecretBySocket.set(client.socket, sharedSecret);
       this.encryptionKeyBySocket.set(client.socket, encryptionKey);
       handshakeState.isReady = true;
-      this.flushQueuedPayloads(client.socket);
+      void this.flushQueuedPayloads(client.socket);
       this.notifyReady(client);
+      this.issueSessionTicket(client.socket, encryptionKey);
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to complete server handshake."));
     }
@@ -1537,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)
@@ -1681,6 +2536,9 @@ var SecureClient = class {
     this.url = url;
     this.options = options;
     this.reconnectConfig = this.resolveReconnectConfig(this.options.reconnect);
+    this.sessionResumptionConfig = this.resolveSessionResumptionConfig(
+      this.options.sessionResumption
+    );
     if (this.options.autoConnect ?? true) {
       this.connect();
     }
@@ -1689,10 +2547,12 @@ var SecureClient = class {
   options;
   socket = null;
   reconnectConfig;
+  sessionResumptionConfig;
   reconnectAttemptCount = 0;
   reconnectTimer = null;
   isManualDisconnectRequested = false;
   customEventHandlers = /* @__PURE__ */ new Map();
+  streamEventHandlers = /* @__PURE__ */ new Map();
   connectHandlers = /* @__PURE__ */ new Set();
   disconnectHandlers = /* @__PURE__ */ new Set();
   readyHandlers = /* @__PURE__ */ new Set();
@@ -1700,6 +2560,8 @@ var SecureClient = class {
   handshakeState = null;
   pendingPayloadQueue = [];
   pendingRpcRequests = /* @__PURE__ */ new Map();
+  incomingStreams = /* @__PURE__ */ new Map();
+  sessionTicket = null;
   get readyState() {
     return this.socket?.readyState ?? null;
   }
@@ -1758,8 +2620,8 @@ var SecureClient = class {
         this.errorHandlers.add(handler);
         return this;
       }
-      if (event === INTERNAL_HANDSHAKE_EVENT) {
-        throw new Error(`The event "${INTERNAL_HANDSHAKE_EVENT}" is reserved for internal use.`);
+      if (event === INTERNAL_HANDSHAKE_EVENT || event === INTERNAL_SESSION_TICKET_EVENT) {
+        throw new Error(`The event "${event}" is reserved for internal use.`);
       }
       const typedHandler = handler;
       const listeners = this.customEventHandlers.get(event) ?? /* @__PURE__ */ new Set();
@@ -1790,7 +2652,7 @@ var SecureClient = class {
         this.errorHandlers.delete(handler);
         return this;
       }
-      if (event === INTERNAL_HANDSHAKE_EVENT) {
+      if (event === INTERNAL_HANDSHAKE_EVENT || event === INTERNAL_SESSION_TICKET_EVENT) {
         return this;
       }
       const listeners = this.customEventHandlers.get(event);
@@ -1808,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 {
@@ -1853,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 {
@@ -1896,6 +2823,24 @@ var SecureClient = class {
       maxAttempts
     };
   }
+  resolveSessionResumptionConfig(sessionResumptionOptions) {
+    if (typeof sessionResumptionOptions === "boolean") {
+      return {
+        enabled: sessionResumptionOptions,
+        maxAcceptedTicketTtlMs: DEFAULT_SESSION_TICKET_TTL_MS
+      };
+    }
+    const maxAcceptedTicketTtlMs = sessionResumptionOptions?.maxAcceptedTicketTtlMs ?? DEFAULT_SESSION_TICKET_TTL_MS;
+    if (!Number.isFinite(maxAcceptedTicketTtlMs) || maxAcceptedTicketTtlMs <= 0) {
+      throw new Error(
+        "Client sessionResumption maxAcceptedTicketTtlMs must be a positive number."
+      );
+    }
+    return {
+      enabled: sessionResumptionOptions?.enabled ?? DEFAULT_SESSION_RESUMPTION_ENABLED,
+      maxAcceptedTicketTtlMs
+    };
+  }
   scheduleReconnect() {
     if (!this.reconnectConfig.enabled || this.reconnectTimer) {
       return;
@@ -1943,7 +2888,6 @@ var SecureClient = class {
     socket.on("open", () => {
       this.clearReconnectTimer();
       this.reconnectAttemptCount = 0;
-      this.sendInternalHandshake();
       this.notifyConnect();
     });
     socket.on("message", (rawData) => {
@@ -1999,6 +2943,14 @@ 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;
+      }
       this.dispatchCustomEvent(decryptedEnvelope.event, decryptedEnvelope.data);
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to process incoming client message."));
@@ -2009,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.")
       );
@@ -2055,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 {
@@ -2212,11 +3312,45 @@ var SecureClient = class {
     }
     this.pendingRpcRequests.clear();
   }
+  handleSessionTicket(data) {
+    if (!this.sessionResumptionConfig.enabled) {
+      return;
+    }
+    try {
+      const ticketPayload = parseSessionTicketPayload(data);
+      const now = Date.now();
+      if (ticketPayload.expiresAt <= now) {
+        return;
+      }
+      const ticketTtlMs = ticketPayload.expiresAt - ticketPayload.issuedAt;
+      if (ticketTtlMs > this.sessionResumptionConfig.maxAcceptedTicketTtlMs) {
+        throw new Error("Session ticket TTL exceeds client trust policy.");
+      }
+      const sessionSecret = decodeBase64ToBuffer(
+        ticketPayload.secret,
+        "Session ticket secret"
+      );
+      if (sessionSecret.length !== ENCRYPTION_KEY_LENGTH) {
+        throw new Error("Session ticket secret has invalid length.");
+      }
+      this.sessionTicket = {
+        sessionId: ticketPayload.sessionId,
+        secret: sessionSecret,
+        issuedAt: ticketPayload.issuedAt,
+        expiresAt: ticketPayload.expiresAt
+      };
+    } catch (error) {
+      this.notifyError(normalizeToError(error, "Failed to process session ticket payload."));
+    }
+  }
   createClientHandshakeState() {
     const { ecdh, localPublicKey } = createEphemeralHandshakeState();
     return {
       ecdh,
       localPublicKey,
+      clientHelloSent: false,
+      pendingServerPublicKey: null,
+      resumeAttempt: null,
       isReady: false,
       sharedSecret: null,
       encryptionKey: null
@@ -2230,15 +3364,171 @@ var SecureClient = class {
       if (!this.handshakeState) {
         throw new Error("Missing client handshake state.");
       }
+      if (this.handshakeState.clientHelloSent) {
+        return;
+      }
       this.socket.send(
         serializePlainEnvelope(INTERNAL_HANDSHAKE_EVENT, {
+          type: "hello",
+          protocolVersion: HANDSHAKE_PROTOCOL_VERSION,
           publicKey: this.handshakeState.localPublicKey
         })
       );
+      this.handshakeState.clientHelloSent = true;
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to send client handshake payload."));
     }
   }
+  shouldAttemptSessionResumption() {
+    if (!this.sessionResumptionConfig.enabled) {
+      return false;
+    }
+    const sessionTicket = this.sessionTicket;
+    if (!sessionTicket) {
+      return false;
+    }
+    const now = Date.now();
+    if (sessionTicket.expiresAt <= now) {
+      this.sessionTicket = null;
+      return false;
+    }
+    const ticketTtlMs = sessionTicket.expiresAt - sessionTicket.issuedAt;
+    if (ticketTtlMs > this.sessionResumptionConfig.maxAcceptedTicketTtlMs) {
+      this.sessionTicket = null;
+      return false;
+    }
+    return true;
+  }
+  sendResumeHandshake() {
+    if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+      return false;
+    }
+    if (!this.handshakeState || !this.sessionTicket) {
+      return false;
+    }
+    if (this.handshakeState.clientHelloSent) {
+      return false;
+    }
+    if (this.handshakeState.resumeAttempt?.status === "pending") {
+      return true;
+    }
+    try {
+      const clientNonce = randomBytes(RESUMPTION_NONCE_LENGTH);
+      const resumedKey = deriveResumedEncryptionKey(this.sessionTicket.secret, clientNonce);
+      const clientProof = createResumeClientProof(
+        this.sessionTicket.secret,
+        this.sessionTicket.sessionId,
+        clientNonce
+      );
+      this.socket.send(
+        serializePlainEnvelope(INTERNAL_HANDSHAKE_EVENT, {
+          type: "resume",
+          protocolVersion: HANDSHAKE_PROTOCOL_VERSION,
+          sessionId: this.sessionTicket.sessionId,
+          clientNonce: clientNonce.toString("base64"),
+          clientProof: clientProof.toString("base64")
+        })
+      );
+      this.handshakeState.resumeAttempt = {
+        status: "pending",
+        sessionId: this.sessionTicket.sessionId,
+        clientNonce,
+        resumedKey
+      };
+      return true;
+    } catch (error) {
+      this.notifyError(normalizeToError(error, "Failed to dispatch resume handshake payload."));
+      this.sessionTicket = null;
+      this.handshakeState.resumeAttempt = null;
+      return false;
+    }
+  }
+  completeFullHandshake(serverPublicKey) {
+    if (!this.handshakeState) {
+      throw new Error("Missing client handshake state.");
+    }
+    if (this.handshakeState.isReady) {
+      return;
+    }
+    this.sendInternalHandshake();
+    const remotePublicKey = Buffer.from(serverPublicKey, "base64");
+    const sharedSecret = this.handshakeState.ecdh.computeSecret(remotePublicKey);
+    this.handshakeState.sharedSecret = sharedSecret;
+    this.handshakeState.encryptionKey = deriveEncryptionKey(sharedSecret);
+    this.handshakeState.resumeAttempt = null;
+    this.handshakeState.pendingServerPublicKey = null;
+    this.handshakeState.isReady = true;
+    void this.flushPendingPayloadQueue();
+    this.notifyReady();
+  }
+  fallbackToFullHandshake() {
+    if (!this.handshakeState || this.handshakeState.isReady) {
+      return;
+    }
+    if (this.handshakeState.resumeAttempt) {
+      this.handshakeState.resumeAttempt.status = "failed";
+    }
+    const pendingServerPublicKey = this.handshakeState.pendingServerPublicKey;
+    if (pendingServerPublicKey) {
+      this.completeFullHandshake(pendingServerPublicKey);
+      return;
+    }
+    this.sendInternalHandshake();
+  }
+  handleServerHelloHandshake(payload) {
+    if (!this.handshakeState || this.handshakeState.isReady) {
+      return;
+    }
+    this.handshakeState.pendingServerPublicKey = payload.publicKey;
+    if (this.shouldAttemptSessionResumption() && this.sendResumeHandshake()) {
+      return;
+    }
+    this.completeFullHandshake(payload.publicKey);
+  }
+  handleResumeAckHandshake(payload) {
+    if (!this.handshakeState || this.handshakeState.isReady) {
+      return;
+    }
+    const resumeAttempt = this.handshakeState.resumeAttempt;
+    if (!resumeAttempt || resumeAttempt.status !== "pending") {
+      return;
+    }
+    if (!payload.ok) {
+      this.sessionTicket = null;
+      this.fallbackToFullHandshake();
+      return;
+    }
+    if (payload.sessionId !== resumeAttempt.sessionId || !payload.serverProof) {
+      this.sessionTicket = null;
+      this.fallbackToFullHandshake();
+      return;
+    }
+    try {
+      const receivedServerProof = decodeBase64ToBuffer(
+        payload.serverProof,
+        "Handshake resume-ack serverProof"
+      );
+      const expectedServerProof = createResumeServerProof(
+        resumeAttempt.resumedKey,
+        resumeAttempt.sessionId,
+        resumeAttempt.clientNonce
+      );
+      if (!equalsConstantTime(receivedServerProof, expectedServerProof)) {
+        throw new Error("Resume server proof validation failed.");
+      }
+      this.handshakeState.sharedSecret = resumeAttempt.resumedKey;
+      this.handshakeState.encryptionKey = resumeAttempt.resumedKey;
+      this.handshakeState.pendingServerPublicKey = null;
+      resumeAttempt.status = "accepted";
+      this.handshakeState.isReady = true;
+      void this.flushPendingPayloadQueue();
+      this.notifyReady();
+    } catch (error) {
+      this.notifyError(normalizeToError(error, "Failed to verify resume server proof."));
+      this.sessionTicket = null;
+      this.fallbackToFullHandshake();
+    }
+  }
   handleInternalHandshake(data) {
     try {
       const payload = parseHandshakePayload(data);
@@ -2248,13 +3538,15 @@ var SecureClient = class {
       if (this.handshakeState.isReady) {
         return;
       }
-      const remotePublicKey = Buffer.from(payload.publicKey, "base64");
-      const sharedSecret = this.handshakeState.ecdh.computeSecret(remotePublicKey);
-      this.handshakeState.sharedSecret = sharedSecret;
-      this.handshakeState.encryptionKey = deriveEncryptionKey(sharedSecret);
-      this.handshakeState.isReady = true;
-      void this.flushPendingPayloadQueue();
-      this.notifyReady();
+      if (payload.type === "hello") {
+        this.handleServerHelloHandshake(payload);
+        return;
+      }
+      if (payload.type === "resume-ack") {
+        this.handleResumeAckHandshake(payload);
+        return;
+      }
+      throw new Error("SecureClient received unexpected resume request handshake payload.");
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to complete client handshake."));
     }