@aegis-fluxion/core 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -5,6 +5,7 @@ interface SecureEnvelope<TData = unknown> {
     event: string;
     data: TData;
 }
+type SecureBinaryPayload = Buffer | Uint8Array | Blob;
 interface SecureAckOptions {
     timeoutMs?: number;
 }
@@ -199,4 +200,4 @@ declare class SecureClient {
     private flushPendingPayloadQueue;
 }
 
-export { type SecureAckCallback, type SecureAckOptions, SecureClient, type SecureClientConnectHandler, type SecureClientDisconnectHandler, type SecureClientEventHandler, type SecureClientEventMap, type SecureClientLifecycleEvent, type SecureClientOptions, type SecureClientReadyHandler, type SecureClientReconnectOptions, type SecureEnvelope, type SecureErrorHandler, SecureServer, type SecureServerClient, type SecureServerConnectionHandler, type SecureServerDisconnectHandler, type SecureServerEventHandler, type SecureServerEventMap, type SecureServerHeartbeatOptions, type SecureServerLifecycleEvent, type SecureServerOptions, type SecureServerReadyHandler, type SecureServerRoomOperator };
+export { type SecureAckCallback, type SecureAckOptions, type SecureBinaryPayload, SecureClient, type SecureClientConnectHandler, type SecureClientDisconnectHandler, type SecureClientEventHandler, type SecureClientEventMap, type SecureClientLifecycleEvent, type SecureClientOptions, type SecureClientReadyHandler, type SecureClientReconnectOptions, type SecureEnvelope, type SecureErrorHandler, SecureServer, type SecureServerClient, type SecureServerConnectionHandler, type SecureServerDisconnectHandler, type SecureServerEventHandler, type SecureServerEventMap, type SecureServerHeartbeatOptions, type SecureServerLifecycleEvent, type SecureServerOptions, type SecureServerReadyHandler, type SecureServerRoomOperator };

package/dist/index.d.ts

@@ -5,6 +5,7 @@ interface SecureEnvelope<TData = unknown> {
     event: string;
     data: TData;
 }
+type SecureBinaryPayload = Buffer | Uint8Array | Blob;
 interface SecureAckOptions {
     timeoutMs?: number;
 }
@@ -199,4 +200,4 @@ declare class SecureClient {
     private flushPendingPayloadQueue;
 }
 
-export { type SecureAckCallback, type SecureAckOptions, SecureClient, type SecureClientConnectHandler, type SecureClientDisconnectHandler, type SecureClientEventHandler, type SecureClientEventMap, type SecureClientLifecycleEvent, type SecureClientOptions, type SecureClientReadyHandler, type SecureClientReconnectOptions, type SecureEnvelope, type SecureErrorHandler, SecureServer, type SecureServerClient, type SecureServerConnectionHandler, type SecureServerDisconnectHandler, type SecureServerEventHandler, type SecureServerEventMap, type SecureServerHeartbeatOptions, type SecureServerLifecycleEvent, type SecureServerOptions, type SecureServerReadyHandler, type SecureServerRoomOperator };
+export { type SecureAckCallback, type SecureAckOptions, type SecureBinaryPayload, SecureClient, type SecureClientConnectHandler, type SecureClientDisconnectHandler, type SecureClientEventHandler, type SecureClientEventMap, type SecureClientLifecycleEvent, type SecureClientOptions, type SecureClientReadyHandler, type SecureClientReconnectOptions, type SecureEnvelope, type SecureErrorHandler, SecureServer, type SecureServerClient, type SecureServerConnectionHandler, type SecureServerDisconnectHandler, type SecureServerEventHandler, type SecureServerEventMap, type SecureServerHeartbeatOptions, type SecureServerLifecycleEvent, type SecureServerOptions, type SecureServerReadyHandler, type SecureServerRoomOperator };

package/dist/index.js

@@ -15,6 +15,8 @@ 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 BINARY_PAYLOAD_MARKER = "__afxBinaryPayload";
+var BINARY_PAYLOAD_VERSION = 1;
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 15e3;
 var DEFAULT_HEARTBEAT_TIMEOUT_MS = 15e3;
 var DEFAULT_RECONNECT_INITIAL_DELAY_MS = 250;
@@ -55,7 +57,103 @@ function rawDataToBuffer(rawData) {
   }
   return Buffer.from(rawData);
 }
-function serializeEnvelope(event, data) {
+function isBlobValue(value) {
+  return typeof Blob !== "undefined" && value instanceof Blob;
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function encodeBinaryPayload(kind, payloadBuffer, mimeType) {
+  const encodedPayload = {
+    [BINARY_PAYLOAD_MARKER]: BINARY_PAYLOAD_VERSION,
+    kind,
+    base64: payloadBuffer.toString("base64")
+  };
+  if (mimeType !== void 0 && mimeType.length > 0) {
+    encodedPayload.mimeType = mimeType;
+  }
+  return encodedPayload;
+}
+async function encodeEnvelopeData(value) {
+  if (Buffer.isBuffer(value)) {
+    return encodeBinaryPayload("buffer", value);
+  }
+  if (value instanceof Uint8Array) {
+    const typedArrayBuffer = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    return encodeBinaryPayload("uint8array", typedArrayBuffer);
+  }
+  if (isBlobValue(value)) {
+    const blobBuffer = Buffer.from(await value.arrayBuffer());
+    return encodeBinaryPayload("blob", blobBuffer, value.type);
+  }
+  if (Array.isArray(value)) {
+    return Promise.all(value.map((item) => encodeEnvelopeData(item)));
+  }
+  if (isPlainObject(value)) {
+    const encodedEntries = await Promise.all(
+      Object.entries(value).map(async ([key, entryValue]) => {
+        return [key, await encodeEnvelopeData(entryValue)];
+      })
+    );
+    return Object.fromEntries(encodedEntries);
+  }
+  return value;
+}
+function isEncodedBinaryPayload(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  if (value[BINARY_PAYLOAD_MARKER] !== BINARY_PAYLOAD_VERSION) {
+    return false;
+  }
+  if (value.kind !== "buffer" && value.kind !== "uint8array" && value.kind !== "blob") {
+    return false;
+  }
+  if (typeof value.base64 !== "string") {
+    return false;
+  }
+  if (value.mimeType !== void 0 && typeof value.mimeType !== "string") {
+    return false;
+  }
+  return true;
+}
+function decodeEnvelopeData(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => decodeEnvelopeData(item));
+  }
+  if (isEncodedBinaryPayload(value)) {
+    const binaryBuffer = Buffer.from(value.base64, "base64");
+    if (value.kind === "buffer") {
+      return binaryBuffer;
+    }
+    if (value.kind === "uint8array") {
+      return Uint8Array.from(binaryBuffer);
+    }
+    if (typeof Blob === "undefined") {
+      return binaryBuffer;
+    }
+    return new Blob([binaryBuffer], {
+      type: value.mimeType ?? ""
+    });
+  }
+  if (isPlainObject(value)) {
+    const decodedEntries = Object.entries(value).map(([key, entryValue]) => {
+      return [key, decodeEnvelopeData(entryValue)];
+    });
+    return Object.fromEntries(decodedEntries);
+  }
+  return value;
+}
+async function serializeEnvelope(event, data) {
+  const encodedData = await encodeEnvelopeData(data);
+  const envelope = { event, data: encodedData };
+  return JSON.stringify(envelope);
+}
+function serializePlainEnvelope(event, data) {
   const envelope = { event, data };
   return JSON.stringify(envelope);
 }
@@ -67,7 +165,7 @@ function parseEnvelope(rawData) {
   }
   return {
     event: parsed.event,
-    data: parsed.data
+    data: decodeEnvelopeData(parsed.data)
   };
 }
 function parseEnvelopeFromText(decodedPayload) {
@@ -77,7 +175,7 @@ function parseEnvelopeFromText(decodedPayload) {
   }
   return {
     event: parsed.event,
-    data: parsed.data
+    data: decodeEnvelopeData(parsed.data)
   };
 }
 function decodeCloseReason(reason) {
@@ -355,7 +453,9 @@ var SecureServer = class {
       }
       const envelope = { event, data };
       for (const client of this.clientsById.values()) {
-        this.sendOrQueuePayload(client.socket, envelope);
+        void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
+          return void 0;
+        });
       }
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to emit server event."));
@@ -373,7 +473,9 @@ var SecureServer = class {
         throw new Error(`Client with id ${clientId} was not found.`);
       }
       if (!ackArgs.expectsAck) {
-        this.sendOrQueuePayload(client.socket, { event, data });
+        void this.sendOrQueuePayload(client.socket, { event, data }).catch(() => {
+          return void 0;
+        });
         return true;
       }
       const ackPromise = this.sendRpcRequest(
@@ -686,22 +788,24 @@ var SecureServer = class {
       this.notifyError(normalizeToError(error, "Failed to send server payload."));
     }
   }
-  sendEncryptedEnvelope(socket, envelope) {
+  async sendEncryptedEnvelope(socket, envelope) {
+    if (socket.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    const encryptionKey = this.encryptionKeyBySocket.get(socket);
+    if (!encryptionKey) {
+      const missingKeyError = new Error("Missing encryption key for connected socket.");
+      this.notifyError(missingKeyError);
+      throw missingKeyError;
+    }
     try {
-      if (socket.readyState !== WebSocket.OPEN) {
-        return;
-      }
-      const encryptionKey = this.encryptionKeyBySocket.get(socket);
-      if (!encryptionKey) {
-        throw new Error("Missing encryption key for connected socket.");
-      }
-      const encryptedPayload = encryptSerializedEnvelope(
-        serializeEnvelope(envelope.event, envelope.data),
-        encryptionKey
-      );
+      const serializedEnvelope = await serializeEnvelope(envelope.event, envelope.data);
+      const encryptedPayload = encryptSerializedEnvelope(serializedEnvelope, encryptionKey);
       socket.send(encryptedPayload);
     } catch (error) {
-      this.notifyError(normalizeToError(error, "Failed to send encrypted server payload."));
+      const normalizedError = normalizeToError(error, "Failed to send encrypted server payload.");
+      this.notifyError(normalizedError);
+      throw normalizedError;
     }
   }
   sendRpcRequest(socket, event, data, timeoutMs) {
@@ -722,13 +826,19 @@ var SecureServer = class {
         reject,
         timeoutHandle
       });
-      this.sendOrQueuePayload(socket, {
+      void this.sendOrQueuePayload(socket, {
         event: INTERNAL_RPC_REQUEST_EVENT,
         data: {
           id: requestId,
           event,
           data
         }
+      }).catch((error) => {
+        clearTimeout(timeoutHandle);
+        pendingRequests.delete(requestId);
+        reject(
+          normalizeToError(error, `Failed to dispatch ACK request for event "${event}".`)
+        );
       });
     });
   }
@@ -770,7 +880,7 @@ var SecureServer = class {
         rpcRequestPayload.data,
         client
       );
-      this.sendEncryptedEnvelope(client.socket, {
+      await this.sendEncryptedEnvelope(client.socket, {
         event: INTERNAL_RPC_RESPONSE_EVENT,
         data: {
           id: rpcRequestPayload.id,
@@ -780,7 +890,7 @@ var SecureServer = class {
       });
     } catch (error) {
       const normalizedError = normalizeToError(error, "Server ACK request handler failed.");
-      this.sendEncryptedEnvelope(client.socket, {
+      await this.sendEncryptedEnvelope(client.socket, {
         event: INTERNAL_RPC_RESPONSE_EVENT,
         data: {
           id: rpcRequestPayload.id,
@@ -854,7 +964,7 @@ var SecureServer = class {
   sendInternalHandshake(socket, localPublicKey) {
     this.sendRaw(
       socket,
-      serializeEnvelope(INTERNAL_HANDSHAKE_EVENT, {
+      serializePlainEnvelope(INTERNAL_HANDSHAKE_EVENT, {
         publicKey: localPublicKey
       })
     );
@@ -887,23 +997,23 @@ var SecureServer = class {
   sendOrQueuePayload(socket, envelope) {
     if (!this.isClientHandshakeReady(socket)) {
       this.queuePayload(socket, envelope);
-      return;
+      return Promise.resolve();
     }
-    this.sendEncryptedEnvelope(socket, envelope);
+    return this.sendEncryptedEnvelope(socket, envelope);
   }
   queuePayload(socket, envelope) {
     const pendingPayloads = this.pendingPayloadsBySocket.get(socket) ?? [];
     pendingPayloads.push(envelope);
     this.pendingPayloadsBySocket.set(socket, pendingPayloads);
   }
-  flushQueuedPayloads(socket) {
+  async flushQueuedPayloads(socket) {
     const pendingPayloads = this.pendingPayloadsBySocket.get(socket);
     if (!pendingPayloads || pendingPayloads.length === 0) {
       return;
     }
     this.pendingPayloadsBySocket.delete(socket);
     for (const envelope of pendingPayloads) {
-      this.sendEncryptedEnvelope(socket, envelope);
+      await this.sendEncryptedEnvelope(socket, envelope);
     }
   }
   createSecureServerClient(clientId, socket, request) {
@@ -1013,7 +1123,9 @@ var SecureServer = class {
       if (!client) {
         continue;
       }
-      this.sendOrQueuePayload(client.socket, envelope);
+      void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
+        return void 0;
+      });
     }
   }
 };
@@ -1177,7 +1289,9 @@ var SecureClient = class {
         this.pendingPayloadQueue.push(envelope);
         return true;
       }
-      this.sendEncryptedEnvelope(envelope);
+      void this.sendEncryptedEnvelope(envelope).catch(() => {
+        return void 0;
+      });
       return true;
     } catch (error) {
       const normalizedError = normalizeToError(error, "Failed to emit client event.");
@@ -1423,22 +1537,26 @@ var SecureClient = class {
       }
     }
   }
-  sendEncryptedEnvelope(envelope) {
+  async sendEncryptedEnvelope(envelope) {
+    if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+      const socketStateError = new Error("Client socket is not connected.");
+      this.notifyError(socketStateError);
+      throw socketStateError;
+    }
+    const encryptionKey = this.handshakeState?.encryptionKey;
+    if (!encryptionKey) {
+      const missingKeyError = new Error("Missing encryption key for client payload encryption.");
+      this.notifyError(missingKeyError);
+      throw missingKeyError;
+    }
     try {
-      if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
-        throw new Error("Client socket is not connected.");
-      }
-      const encryptionKey = this.handshakeState?.encryptionKey;
-      if (!encryptionKey) {
-        throw new Error("Missing encryption key for client payload encryption.");
-      }
-      const encryptedPayload = encryptSerializedEnvelope(
-        serializeEnvelope(envelope.event, envelope.data),
-        encryptionKey
-      );
+      const serializedEnvelope = await serializeEnvelope(envelope.event, envelope.data);
+      const encryptedPayload = encryptSerializedEnvelope(serializedEnvelope, encryptionKey);
       this.socket.send(encryptedPayload);
     } catch (error) {
-      this.notifyError(normalizeToError(error, "Failed to send encrypted client payload."));
+      const normalizedError = normalizeToError(error, "Failed to send encrypted client payload.");
+      this.notifyError(normalizedError);
+      throw normalizedError;
     }
   }
   sendRpcRequest(event, data, timeoutMs) {
@@ -1469,7 +1587,13 @@ var SecureClient = class {
         this.pendingPayloadQueue.push(rpcRequestEnvelope);
         return;
       }
-      this.sendEncryptedEnvelope(rpcRequestEnvelope);
+      void this.sendEncryptedEnvelope(rpcRequestEnvelope).catch((error) => {
+        clearTimeout(timeoutHandle);
+        this.pendingRpcRequests.delete(requestId);
+        reject(
+          normalizeToError(error, `Failed to dispatch ACK request for event "${event}".`)
+        );
+      });
     });
   }
   handleRpcResponse(data) {
@@ -1505,7 +1629,7 @@ var SecureClient = class {
         rpcRequestPayload.event,
         rpcRequestPayload.data
       );
-      this.sendEncryptedEnvelope({
+      await this.sendEncryptedEnvelope({
         event: INTERNAL_RPC_RESPONSE_EVENT,
         data: {
           id: rpcRequestPayload.id,
@@ -1515,7 +1639,7 @@ var SecureClient = class {
       });
     } catch (error) {
       const normalizedError = normalizeToError(error, "Client ACK request handler failed.");
-      this.sendEncryptedEnvelope({
+      await this.sendEncryptedEnvelope({
         event: INTERNAL_RPC_RESPONSE_EVENT,
         data: {
           id: rpcRequestPayload.id,
@@ -1560,7 +1684,7 @@ var SecureClient = class {
         throw new Error("Missing client handshake state.");
       }
       this.socket.send(
-        serializeEnvelope(INTERNAL_HANDSHAKE_EVENT, {
+        serializePlainEnvelope(INTERNAL_HANDSHAKE_EVENT, {
           publicKey: this.handshakeState.localPublicKey
         })
       );
@@ -1582,7 +1706,7 @@ var SecureClient = class {
       this.handshakeState.sharedSecret = sharedSecret;
       this.handshakeState.encryptionKey = deriveEncryptionKey(sharedSecret);
       this.handshakeState.isReady = true;
-      this.flushPendingPayloadQueue();
+      void this.flushPendingPayloadQueue();
       this.notifyReady();
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to complete client handshake."));
@@ -1591,14 +1715,14 @@ var SecureClient = class {
   isHandshakeReady() {
     return this.handshakeState?.isReady ?? false;
   }
-  flushPendingPayloadQueue() {
+  async flushPendingPayloadQueue() {
     if (!this.socket || this.socket.readyState !== WebSocket.OPEN || !this.isHandshakeReady()) {
       return;
     }
     const pendingPayloads = this.pendingPayloadQueue;
     this.pendingPayloadQueue = [];
     for (const envelope of pendingPayloads) {
-      this.sendEncryptedEnvelope(envelope);
+      await this.sendEncryptedEnvelope(envelope);
     }
   }
 };