@aegis-fluxion/core 0.4.0 → 0.7.0

package/README.md

@@ -1,20 +1,26 @@
 # @aegis-fluxion/core
 
-Core E2E-encrypted WebSocket primitives for `aegis-fluxion`.
+Low-level E2E-encrypted WebSocket primitives for the `aegis-fluxion` ecosystem.
 
-Version: **0.4.0**
+If you prefer a single user-facing package, use [`aegis-fluxion`](../aegis-fluxion/README.md).
+
+Version: **0.7.0**
 
 ---
 
-## Features
+## Highlights
 
-- ECDH handshake (`prime256v1`) with ephemeral key exchange
-- AES-256-GCM encrypted message envelopes
-- Server/client lifecycle events (`connect`, `ready`, `disconnect`, `error`)
-- Secure room routing (`join`, `leave`, `to(room).emit`)
-- Heartbeat-based zombie cleanup
-- Auto-reconnect with exponential backoff
-- **RPC-style ACK request/response with timeout support**
+- 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(...)`
+- Middleware phases: `connection`, `incoming`, `outgoing`
+- Per-socket middleware metadata available as `SecureServerClient.metadata`
+- Optional MCP bridge package: `@aegis-fluxion/mcp-adapter`
 
 ---
 
@@ -26,135 +32,268 @@ npm install @aegis-fluxion/core ws
 
 ---
 
-## API at a Glance
+## Middleware in 0.6.0+
 
-### `SecureServer`
+`SecureServer` now supports phase-based middleware for auth, policy enforcement, and payload
+normalization.
 
-- `on("connection" | "ready" | "disconnect" | "error", handler)`
-- `on("custom:event", (data, client) => unknown | Promise<unknown>)`
-- `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`
+```ts
+import { SecureClient, SecureServer } from "@aegis-fluxion/core";
 
-### `SecureServerClient`
+const server = new SecureServer({ host: "127.0.0.1", port: 8080 });
 
-- `id: string`
-- `socket: WebSocket`
-- `join(room): boolean`
-- `leave(room): boolean`
-- `leaveAll(): number`
-- `emit(event, data, ...ackArgs): boolean | Promise<unknown>`
+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;
 
-### `SecureClient`
+    if (apiKey !== "dev-secret") {
+      throw new Error("Unauthorized");
+    }
 
-- `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)`
+    context.metadata.set("role", "editor");
+  }
+
+  await next();
+});
+
+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() };
+  }
+
+  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) => {
+  return {
+    ok: true,
+    role: client.metadata.get("role"),
+    payload
+  };
+});
+
+const client = new SecureClient("ws://127.0.0.1:8080", {
+  wsOptions: {
+    headers: {
+      "x-api-key": "dev-secret"
+    }
+  }
+});
+
+client.on("ready", async () => {
+  const response = await client.emit("post:create", { title: "  Hello  " }, { timeoutMs: 1500 });
+  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`.
 
 ---
 
-## ACK (Request-Response) Usage
+## MCP Adapter Integration (0.7.0)
 
-### 1) Client -> Server (Promise ACK)
+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 });
 
-const server = new SecureServer({ port: 8080, host: "127.0.0.1" });
+secureServer.on("connection", async (client) => {
+  const mcpServerTransport = new SecureMCPTransport({
+    mode: "server",
+    server: secureServer,
+    clientId: client.id
+  });
 
-server.on("math:add", ({ a, b }) => {
-  return { total: Number(a) + Number(b) };
+  mcpServerTransport.onmessage = async (message) => {
+    // Forward into your MCP server runtime.
+    console.log("MCP request on server tunnel", message);
+  };
+
+  await mcpServerTransport.start();
 });
 
-const client = new SecureClient("ws://127.0.0.1:8080");
+const secureClient = new SecureClient("ws://127.0.0.1:9091");
 
-client.on("ready", async () => {
-  const response = await client.emit(
-    "math:add",
-    { a: 2, b: 3 },
-    { timeoutMs: 1000 }
-  );
+const mcpClientTransport = new SecureMCPTransport({
+  mode: "client",
+  client: secureClient
+});
+
+await mcpClientTransport.start();
 
-  console.log(response); // { total: 5 }
+await mcpClientTransport.send({
+  jsonrpc: "2.0",
+  id: 100,
+  method: "tools/list",
+  params: {}
 });
 ```
 
-### 2) Client -> Server (Callback ACK)
+---
+
+## Binary Data Support
+
+`@aegis-fluxion/core` supports encrypted binary payload transfer while preserving type fidelity.
+
+Supported send/receive types:
+
+- `Buffer`
+- `Uint8Array`
+- `Blob`
+
+Binary values can be nested in regular objects and arrays.
+
+---
+
+## Example: Encrypted Binary Event
 
 ```ts
-client.emit(
-  "math:add",
-  { a: 4, b: 6 },
-  { timeoutMs: 1000 },
-  (error, response) => {
-    if (error) {
-      console.error("ACK error:", error.message);
-      return;
-    }
+import { SecureClient, SecureServer } from "@aegis-fluxion/core";
 
-    console.log(response); // { total: 10 }
+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);
+});
 ```
 
-### 3) Server -> Client (Promise ACK)
+---
 
-```ts
-server.on("ready", async (clientSocket) => {
-  const response = await clientSocket.emit(
-    "agent:health",
-    { verbose: true },
-    { timeoutMs: 1200 }
-  );
+## Example: ACK Roundtrip with Mixed Binary Types
 
-  console.log(response);
+```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("agent:health", () => {
-  return { ok: true, uptime: process.uptime() };
+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);
 });
 ```
 
-### 4) ACK Timeout Behavior
+---
 
-When no response arrives before `timeoutMs`, ACK request fails:
+## API Snapshot
 
-- Promise form -> rejects with timeout error
-- Callback form -> callback receives `Error`
+### `SecureServer`
 
-```ts
-try {
-  await client.emit("never:respond", { ping: true }, { timeoutMs: 300 });
-} catch (error) {
-  console.error((error as Error).message);
-  // ACK response timed out after 300ms for event "never:respond".
-}
-```
+- `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`
+
+### `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
 
-- ACK request and ACK response frames are encrypted with the same AES-GCM tunnel as normal events.
-- Internal handshake/RPC transport events are reserved and cannot be emitted manually.
-- On disconnect/heartbeat timeout, pending ACK promises are rejected and memory state is cleaned.
+- 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.
+- Middleware-level policy rejection uses WebSocket close code `1008`.
 
 ---
 
 ## Development
 
-From monorepo root:
+From repository root:
 
 ```bash
 npm run typecheck -w @aegis-fluxion/core
@@ -164,16 +303,6 @@ npm run build -w @aegis-fluxion/core
 
 ---
 
-## Publish
-
-From monorepo root:
-
-```bash
-npm publish -w @aegis-fluxion/core --access public
-```
-
----
-
 ## License
 
 MIT