@aegis-fluxion/core 0.5.0 → 0.7.1

package/README.md

@@ -4,7 +4,7 @@ Low-level E2E-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.5.0**
+Version: **0.7.1**
 
 ---
 
@@ -17,6 +17,11 @@ Version: **0.5.0**
 - 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`
+- **Rate limiting & DDoS shield** with per-connection/per-IP controls
+- Optional MCP bridge package: `@aegis-fluxion/mcp-adapter`
 
 ---
 
@@ -28,6 +33,160 @@ npm install @aegis-fluxion/core ws
 
 ---
 
+## Middleware in 0.6.0+
+
+`SecureServer` now supports phase-based middleware for auth, policy enforcement, and payload
+normalization.
+
+```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 === "connection") {
+    const rawApiKey = context.request.headers["x-api-key"];
+    const apiKey = Array.isArray(rawApiKey) ? rawApiKey[0] : rawApiKey;
+
+    if (apiKey !== "dev-secret") {
+      throw new Error("Unauthorized");
+    }
+
+    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`.
+
+---
+
+## Rate Limiting & DDoS Protection (0.7.1)
+
+`SecureServer` can enforce burst limits per connection and per source IP before event handlers run.
+
+```ts
+import { SecureServer } from "@aegis-fluxion/core";
+
+const server = new SecureServer({
+  host: "127.0.0.1",
+  port: 8080,
+  rateLimit: {
+    enabled: true,
+    windowMs: 1_000,
+    maxEventsPerConnection: 120,
+    maxEventsPerIp: 300,
+    action: "throttle",
+    throttleMs: 150,
+    maxThrottleMs: 2_000,
+    disconnectAfterViolations: 4,
+    disconnectCode: 1013,
+    disconnectReason: "Rate limit exceeded. Please retry later."
+  }
+});
+```
+
+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)
+
+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.
@@ -115,6 +274,7 @@ client.on("ready", async () => {
 
 - `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`
@@ -127,11 +287,22 @@ client.on("ready", async () => {
 
 - `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`
@@ -153,6 +324,8 @@ client.on("ready", async () => {
 - 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`.
 
 ---