@aegis-fluxion/core 0.7.1 → 0.7.2

package/README.md

@@ -1,10 +1,8 @@
 # @aegis-fluxion/core
 
-Low-level E2E-encrypted WebSocket primitives for the `aegis-fluxion` ecosystem.
+Low-level encrypted WebSocket primitives for the `aegis-fluxion` ecosystem.
 
-If you prefer a single user-facing package, use [`aegis-fluxion`](../aegis-fluxion/README.md).
-
-Version: **0.7.1**
+Version: **0.7.2**
 
 ---
 
@@ -12,16 +10,11 @@ Version: **0.7.1**
 
 - Ephemeral ECDH handshake (`prime256v1`)
 - AES-256-GCM encrypted envelopes
-- Encrypted ACK request/response (`Promise` and callback)
-- Secure room routing (`join`, `leave`, `leaveAll`, `to(room).emit`)
-- Heartbeat and zombie socket cleanup
-- Auto-reconnect with fresh re-handshake
-- **Binary payload support**: `Buffer`, `Uint8Array`, `Blob`
-- **Server middleware pipeline** via `SecureServer.use(...)`
+- ACK request/response (Promise + callback styles)
+- Secure room routing (`join`, `leave`, `leaveAll`, `to(room).emit(...)`)
 - Middleware phases: `connection`, `incoming`, `outgoing`
-- Per-socket middleware metadata available as `SecureServerClient.metadata`
-- **Rate limiting & DDoS shield** with per-connection/per-IP controls
-- Optional MCP bridge package: `@aegis-fluxion/mcp-adapter`
+- Rate limiting and DDoS controls per connection and IP
+- **Horizontal scaling hooks** via pluggable `SecureServerAdapter`
 
 ---
 
@@ -33,84 +26,126 @@ npm install @aegis-fluxion/core ws
 
 ---
 
-## Middleware in 0.6.0+
+## SecureServer adapter API (horizontal scaling)
 
-`SecureServer` now supports phase-based middleware for auth, policy enforcement, and payload
-normalization.
+### Core types
 
 ```ts
-import { SecureClient, SecureServer } from "@aegis-fluxion/core";
+export interface SecureServerAdapterMessage {
+  version: 1;
+  originServerId: string;
+  scope: "broadcast" | "room";
+  event: string;
+  data: unknown;
+  emittedAt: number;
+  room?: string;
+}
+
+export interface SecureServerAdapter {
+  attach(server: SecureServer): void | Promise<void>;
+  publish(message: SecureServerAdapterMessage): void | Promise<void>;
+  detach?(server: SecureServer): void | Promise<void>;
+}
+```
 
-const server = new SecureServer({ host: "127.0.0.1", port: 8080 });
+### SecureServer hooks
 
-server.use(async (context, next) => {
-  if (context.phase === "connection") {
-    const rawApiKey = context.request.headers["x-api-key"];
-    const apiKey = Array.isArray(rawApiKey) ? rawApiKey[0] : rawApiKey;
+- constructor option: `new SecureServer({ ..., adapter })`
+- runtime binding: `await server.setAdapter(adapter)`
+- inbound relay: `await server.handleAdapterMessage(message)`
+- instance identity: `server.serverId`
+
+### Message normalization helper
+
+```ts
+import { normalizeSecureServerAdapterMessage } from "@aegis-fluxion/core";
+```
+
+Use it in adapters before delivering inbound Pub/Sub payloads to `SecureServer`.
+
+---
+
+## Adapter integration example
 
-    if (apiKey !== "dev-secret") {
-      throw new Error("Unauthorized");
+```ts
+import {
+  SecureServer,
+  type SecureServerAdapter,
+  type SecureServerAdapterMessage
+} from "@aegis-fluxion/core";
+
+class InMemoryAdapter implements SecureServerAdapter {
+  private static readonly peers = new Set<InMemoryAdapter>();
+  private server: SecureServer | null = null;
+
+  async attach(server: SecureServer): Promise<void> {
+    this.server = server;
+    InMemoryAdapter.peers.add(this);
+  }
+
+  async publish(message: SecureServerAdapterMessage): Promise<void> {
+    for (const peer of InMemoryAdapter.peers) {
+      if (peer === this || !peer.server) {
+        continue;
+      }
+
+      await peer.server.handleAdapterMessage(message);
+    }
+  }
+
+  async detach(server: SecureServer): Promise<void> {
+    if (this.server !== server) {
+      return;
     }
 
-    context.metadata.set("role", "editor");
+    this.server = null;
+    InMemoryAdapter.peers.delete(this);
   }
+}
 
-  await next();
+const server = new SecureServer({
+  host: "127.0.0.1",
+  port: 8080,
+  adapter: new InMemoryAdapter()
 });
+```
+
+---
+
+## Middleware and ACK example
+
+```ts
+import { SecureClient, SecureServer } from "@aegis-fluxion/core";
+
+const server = new SecureServer({ host: "127.0.0.1", port: 8080 });
 
 server.use(async (context, next) => {
-  if (
-    context.phase === "incoming" &&
-    context.event === "post:create" &&
-    typeof context.data === "object" &&
-    context.data !== null
-  ) {
-    const payload = context.data as { title?: string };
-    context.data = { title: String(payload.title ?? "").trim() };
+  if (context.phase === "connection") {
+    context.metadata.set("auth.role", "operator");
   }
 
   await next();
-
-  if (context.phase === "outgoing" && context.event === "post:create") {
-    context.data = {
-      ...(context.data as Record<string, unknown>),
-      middleware: true
-    };
-  }
 });
 
-server.on("post:create", async (payload, client) => {
+server.on("jobs:create", async (payload, client) => {
   return {
     ok: true,
-    role: client.metadata.get("role"),
+    role: client.metadata.get("auth.role"),
     payload
   };
 });
 
-const client = new SecureClient("ws://127.0.0.1:8080", {
-  wsOptions: {
-    headers: {
-      "x-api-key": "dev-secret"
-    }
-  }
-});
+const client = new SecureClient("ws://127.0.0.1:8080");
 
 client.on("ready", async () => {
-  const response = await client.emit("post:create", { title: "  Hello  " }, { timeoutMs: 1500 });
+  const response = await client.emit("jobs:create", { id: "job-42" }, { timeoutMs: 1200 });
   console.log(response);
 });
 ```
 
-Notes:
-
-- Throwing in `connection` middleware rejects the socket and closes with code `1008`.
-- `metadata` is mutable in middleware (`Map`) and exposed read-only on `SecureServerClient`.
-
 ---
 
-## Rate Limiting & DDoS Protection (0.7.1)
-
-`SecureServer` can enforce burst limits per connection and per source IP before event handlers run.
+## Rate limiting and DDoS shield
 
 ```ts
 import { SecureServer } from "@aegis-fluxion/core";
@@ -123,7 +158,7 @@ const server = new SecureServer({
     windowMs: 1_000,
     maxEventsPerConnection: 120,
     maxEventsPerIp: 300,
-    action: "throttle",
+    action: "throttle", // or "disconnect"
     throttleMs: 150,
     maxThrottleMs: 2_000,
     disconnectAfterViolations: 4,
@@ -133,199 +168,17 @@ const server = new SecureServer({
 });
 ```
 
-Behavior summary:
-
-- When limits are exceeded, the server can **throttle** or **disconnect** the peer.
-- Throttle mode delays the first over-limit message and drops subsequent flood packets during the throttle window.
-- Disconnect mode closes abusive sockets with your configured close code/reason.
-- Source IP is resolved from `x-forwarded-for` (first hop) or socket remote address.
-
 ---
 
-## MCP Adapter Integration (0.7.0)
+## Binary payload support
 
-Use `@aegis-fluxion/mcp-adapter` to carry MCP JSON-RPC messages through your encrypted core
-transport.
-
-```ts
-import { SecureClient, SecureServer } from "@aegis-fluxion/core";
-import { SecureMCPTransport } from "@aegis-fluxion/mcp-adapter";
-
-const secureServer = new SecureServer({ host: "127.0.0.1", port: 9091 });
-
-secureServer.on("connection", async (client) => {
-  const mcpServerTransport = new SecureMCPTransport({
-    mode: "server",
-    server: secureServer,
-    clientId: client.id
-  });
-
-  mcpServerTransport.onmessage = async (message) => {
-    // Forward into your MCP server runtime.
-    console.log("MCP request on server tunnel", message);
-  };
-
-  await mcpServerTransport.start();
-});
-
-const secureClient = new SecureClient("ws://127.0.0.1:9091");
-
-const mcpClientTransport = new SecureMCPTransport({
-  mode: "client",
-  client: secureClient
-});
-
-await mcpClientTransport.start();
-
-await mcpClientTransport.send({
-  jsonrpc: "2.0",
-  id: 100,
-  method: "tools/list",
-  params: {}
-});
-```
-
----
-
-## Binary Data Support
-
-`@aegis-fluxion/core` supports encrypted binary payload transfer while preserving type fidelity.
-
-Supported send/receive types:
+Supported encrypted payload types:
 
 - `Buffer`
 - `Uint8Array`
 - `Blob`
 
-Binary values can be nested in regular objects and arrays.
-
----
-
-## Example: Encrypted Binary Event
-
-```ts
-import { SecureClient, SecureServer } from "@aegis-fluxion/core";
-
-const server = new SecureServer({ host: "127.0.0.1", port: 8080 });
-const client = new SecureClient("ws://127.0.0.1:8080");
-
-server.on("image:chunk", (data, socket) => {
-  const chunk = data as Buffer;
-
-  if (!Buffer.isBuffer(chunk)) {
-    throw new Error("Expected Buffer payload.");
-  }
-
-  socket.emit("image:chunk:ack", chunk);
-});
-
-client.on("ready", () => {
-  const imageChunk = Buffer.from("89504e470d0a", "hex");
-  client.emit("image:chunk", imageChunk);
-});
-
-client.on("image:chunk:ack", (payload) => {
-  const echoedChunk = payload as Buffer;
-  console.log("Echoed bytes:", echoedChunk.byteLength);
-});
-```
-
----
-
-## Example: ACK Roundtrip with Mixed Binary Types
-
-```ts
-server.on("binary:inspect", async (payload) => {
-  const { file, bytes, blob } = payload as {
-    file: Buffer;
-    bytes: Uint8Array;
-    blob: Blob;
-  };
-
-  return {
-    fileBytes: file.byteLength,
-    bytesBytes: bytes.byteLength,
-    blobBytes: blob.size
-  };
-});
-
-client.on("ready", async () => {
-  const result = await client.emit(
-    "binary:inspect",
-    {
-      file: Buffer.from("file-binary"),
-      bytes: Uint8Array.from([1, 2, 3, 4]),
-      blob: new Blob([Buffer.from("blob-binary")], {
-        type: "application/octet-stream"
-      })
-    },
-    { timeoutMs: 1500 }
-  );
-
-  console.log(result);
-});
-```
-
----
-
-## API Snapshot
-
-### `SecureServer`
-
-- `on("connection" | "ready" | "disconnect" | "error", handler)`
-- `on("custom:event", (data, client) => unknown | Promise<unknown>)`
-- `use((context, next) => void | Promise<void>)`
-- `emit(event, data): SecureServer`
-- `emitTo(clientId, event, data): boolean`
-- `emitTo(clientId, event, data, callback): boolean`
-- `emitTo(clientId, event, data, options): Promise<unknown>`
-- `emitTo(clientId, event, data, options, callback): boolean`
-- `to(room).emit(event, data): SecureServer`
-- `close(code?, reason?): void`
-
-### `SecureServerClient`
-
-- `id: string`
-- `socket: WebSocket`
-- `metadata: ReadonlyMap<string, unknown>`
-- `emit(event, data, ...ackArgs): boolean | Promise<unknown>`
-- `join(room): boolean`
-- `leave(room): boolean`
-- `leaveAll(): number`
-
-### Middleware Types
-
-- `SecureServerMiddleware`
-- `SecureServerMiddlewareContext`
-- `SecureServerConnectionMiddlewareContext`
-- `SecureServerMessageMiddlewareContext`
-- `SecureServerMiddlewareNext`
-- `SecureServerRateLimitOptions`
-- `SecureServerRateLimitAction`
-
-### `SecureClient`
-
-- `connect(): void`
-- `disconnect(code?, reason?): void`
-- `isConnected(): boolean`
-- `readyState: number | null`
-- `emit(event, data): boolean`
-- `emit(event, data, callback): boolean`
-- `emit(event, data, options): Promise<unknown>`
-- `emit(event, data, options, callback): boolean`
-- `on("connect" | "ready" | "disconnect" | "error", handler)`
-- `on("custom:event", handler)`
-
----
-
-## Security Notes
-
-- All payloads (including binary) are encrypted end-to-end with AES-256-GCM.
-- Authentication tags are verified on every packet (tampered packets are dropped).
-- Internal transport events are reserved (`__handshake`, `__rpc:req`, `__rpc:res`).
-- Pending ACK requests are rejected on timeout/disconnect.
-- Overload traffic can be throttled or disconnected before custom handlers are invoked.
-- Middleware-level policy rejection uses WebSocket close code `1008`.
+Binary fields can be nested in standard JSON objects and arrays.
 
 ---
 

package/dist/index.cjs

@@ -40,6 +40,51 @@ var DEFAULT_RATE_LIMIT_MAX_THROTTLE_MS = 2e3;
 var DEFAULT_RATE_LIMIT_DISCONNECT_AFTER_VIOLATIONS = 4;
 var DEFAULT_RATE_LIMIT_CLOSE_CODE = 1013;
 var DEFAULT_RATE_LIMIT_CLOSE_REASON = "Rate limit exceeded. Please retry later.";
+var SECURE_SERVER_ADAPTER_MESSAGE_VERSION = 1;
+function normalizeSecureServerAdapterMessage(value) {
+  if (!isPlainObject(value)) {
+    throw new Error("SecureServer adapter message must be a plain object.");
+  }
+  if (value.version !== SECURE_SERVER_ADAPTER_MESSAGE_VERSION) {
+    throw new Error(
+      `Unsupported SecureServer adapter message version: ${String(value.version)}.`
+    );
+  }
+  if (typeof value.originServerId !== "string" || value.originServerId.trim().length === 0) {
+    throw new Error("SecureServer adapter message originServerId must be a non-empty string.");
+  }
+  if (value.scope !== "broadcast" && value.scope !== "room") {
+    throw new Error('SecureServer adapter message scope must be either "broadcast" or "room".');
+  }
+  if (typeof value.event !== "string" || value.event.trim().length === 0) {
+    throw new Error("SecureServer adapter message event must be a non-empty string.");
+  }
+  if (typeof value.emittedAt !== "number" || !Number.isFinite(value.emittedAt)) {
+    throw new Error("SecureServer adapter message emittedAt must be a finite number.");
+  }
+  if (value.scope === "room") {
+    if (typeof value.room !== "string" || value.room.trim().length === 0) {
+      throw new Error("SecureServer adapter message room must be a non-empty string.");
+    }
+    return {
+      version: SECURE_SERVER_ADAPTER_MESSAGE_VERSION,
+      originServerId: value.originServerId,
+      scope: value.scope,
+      event: value.event,
+      data: value.data,
+      emittedAt: value.emittedAt,
+      room: value.room.trim()
+    };
+  }
+  return {
+    version: SECURE_SERVER_ADAPTER_MESSAGE_VERSION,
+    originServerId: value.originServerId,
+    scope: value.scope,
+    event: value.event,
+    data: value.data,
+    emittedAt: value.emittedAt
+  };
+}
 function normalizeToError(error, fallbackMessage) {
   if (error instanceof Error) {
     return error;
@@ -368,7 +413,9 @@ function decryptSerializedEnvelope(rawData, encryptionKey) {
   return plaintext.toString("utf8");
 }
 var SecureServer = class {
+  instanceId = crypto.randomUUID();
   socketServer;
+  adapter = null;
   heartbeatConfig;
   rateLimitConfig;
   heartbeatIntervalHandle = null;
@@ -393,19 +440,76 @@ var SecureServer = class {
   rateLimitBucketsByClientId = /* @__PURE__ */ new Map();
   rateLimitBucketsByIp = /* @__PURE__ */ new Map();
   constructor(options) {
-    const { heartbeat, rateLimit, ...socketServerOptions } = options;
+    const { heartbeat, rateLimit, adapter, ...socketServerOptions } = options;
     this.heartbeatConfig = this.resolveHeartbeatConfig(heartbeat);
     this.rateLimitConfig = this.resolveRateLimitConfig(rateLimit);
     this.socketServer = new WebSocket.WebSocketServer(socketServerOptions);
     this.bindSocketServerEvents();
     this.startHeartbeatLoop();
+    if (adapter) {
+      void this.setAdapter(adapter).catch(() => {
+        return void 0;
+      });
+    }
   }
   get clientCount() {
     return this.clientsById.size;
   }
+  get serverId() {
+    return this.instanceId;
+  }
   get clients() {
     return this.clientsById;
   }
+  async setAdapter(adapter) {
+    const previousAdapter = this.adapter;
+    if (previousAdapter === adapter) {
+      return;
+    }
+    try {
+      if (previousAdapter?.detach) {
+        await Promise.resolve(previousAdapter.detach(this));
+      }
+      this.adapter = null;
+      if (!adapter) {
+        return;
+      }
+      await Promise.resolve(adapter.attach(this));
+      this.adapter = adapter;
+    } catch (error) {
+      const normalizedError = normalizeToError(
+        error,
+        "Failed to set SecureServer adapter."
+      );
+      this.notifyError(normalizedError);
+      throw normalizedError;
+    }
+  }
+  async handleAdapterMessage(message) {
+    try {
+      const normalizedMessage = normalizeSecureServerAdapterMessage(message);
+      if (normalizedMessage.originServerId === this.instanceId) {
+        return;
+      }
+      if (normalizedMessage.scope === "broadcast") {
+        this.emitLocally(normalizedMessage.event, normalizedMessage.data);
+        return;
+      }
+      if (!normalizedMessage.room) {
+        return;
+      }
+      this.emitToRoom(
+        normalizedMessage.room,
+        normalizedMessage.event,
+        normalizedMessage.data,
+        false
+      );
+    } catch (error) {
+      this.notifyError(
+        normalizeToError(error, "Failed to process SecureServer adapter message.")
+      );
+    }
+  }
   on(event, handler) {
     try {
       if (event === "connection") {
@@ -492,12 +596,12 @@ var SecureServer = class {
       if (isReservedEmitEvent(event)) {
         throw new Error(`The event "${event}" is reserved and cannot be emitted manually.`);
       }
-      const envelope = { event, data };
-      for (const client of this.clientsById.values()) {
-        void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
-          return void 0;
-        });
-      }
+      this.emitLocally(event, data);
+      this.publishAdapterMessage({
+        scope: "broadcast",
+        event,
+        data
+      });
     } catch (error) {
       this.notifyError(normalizeToError(error, "Failed to emit server event."));
     }
@@ -554,7 +658,7 @@ var SecureServer = class {
     return {
       emit: (event, data) => {
         try {
-          this.emitToRoom(normalizedRoom, event, data);
+          this.emitToRoom(normalizedRoom, event, data, true);
         } catch (error) {
           this.notifyError(
             normalizeToError(error, `Failed to emit event to room ${normalizedRoom}.`)
@@ -567,6 +671,15 @@ var SecureServer = class {
   close(code = DEFAULT_CLOSE_CODE, reason = DEFAULT_CLOSE_REASON) {
     try {
       this.stopHeartbeatLoop();
+      const activeAdapter = this.adapter;
+      this.adapter = null;
+      if (activeAdapter?.detach) {
+        void Promise.resolve(activeAdapter.detach(this)).catch((error) => {
+          this.notifyError(
+            normalizeToError(error, "Failed to detach SecureServer adapter during close.")
+          );
+        });
+      }
       for (const client of this.clientsById.values()) {
         this.rejectPendingRpcRequests(
           client.socket,
@@ -1435,6 +1548,48 @@ var SecureServer = class {
       leaveAll: () => this.leaveClientFromAllRooms(clientId)
     };
   }
+  emitLocally(event, data) {
+    const envelope = { event, data };
+    for (const client of this.clientsById.values()) {
+      void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
+        return void 0;
+      });
+    }
+  }
+  publishAdapterMessage(message) {
+    if (!this.adapter) {
+      return;
+    }
+    let adapterMessage;
+    if (message.scope === "room") {
+      if (!message.room) {
+        return;
+      }
+      adapterMessage = {
+        version: SECURE_SERVER_ADAPTER_MESSAGE_VERSION,
+        originServerId: this.instanceId,
+        scope: "room",
+        event: message.event,
+        data: message.data,
+        emittedAt: Date.now(),
+        room: message.room
+      };
+    } else {
+      adapterMessage = {
+        version: SECURE_SERVER_ADAPTER_MESSAGE_VERSION,
+        originServerId: this.instanceId,
+        scope: "broadcast",
+        event: message.event,
+        data: message.data,
+        emittedAt: Date.now()
+      };
+    }
+    void Promise.resolve(this.adapter.publish(adapterMessage)).catch((error) => {
+      this.notifyError(
+        normalizeToError(error, "Failed to publish SecureServer adapter message.")
+      );
+    });
+  }
   normalizeRoomName(room) {
     if (typeof room !== "string") {
       throw new Error("Room name must be a string.");
@@ -1500,22 +1655,29 @@ var SecureServer = class {
     }
     return roomNames.length;
   }
-  emitToRoom(room, event, data) {
+  emitToRoom(room, event, data, replicate) {
     if (isReservedEmitEvent(event)) {
       throw new Error(`The event "${event}" is reserved and cannot be emitted manually.`);
     }
     const roomMembers = this.roomMembersByName.get(room);
-    if (!roomMembers || roomMembers.size === 0) {
-      return;
-    }
-    const envelope = { event, data };
-    for (const clientId of roomMembers) {
-      const client = this.clientsById.get(clientId);
-      if (!client) {
-        continue;
+    if (roomMembers && roomMembers.size > 0) {
+      const envelope = { event, data };
+      for (const clientId of roomMembers) {
+        const client = this.clientsById.get(clientId);
+        if (!client) {
+          continue;
+        }
+        void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
+          return void 0;
+        });
       }
-      void this.sendOrQueuePayload(client.socket, envelope).catch(() => {
-        return void 0;
+    }
+    if (replicate) {
+      this.publishAdapterMessage({
+        scope: "room",
+        room,
+        event,
+        data
       });
     }
   }
@@ -2120,5 +2282,6 @@ var SecureClient = class {
 
 exports.SecureClient = SecureClient;
 exports.SecureServer = SecureServer;
+exports.normalizeSecureServerAdapterMessage = normalizeSecureServerAdapterMessage;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map