@aegis-fluxion/core 0.7.1 → 0.8.0

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.8.0**
 
 ---
 
@@ -12,16 +10,12 @@ 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
+- TLS 1.3-style session resumption with encrypted one-time tickets
+- **Horizontal scaling hooks** via pluggable `SecureServerAdapter`
 
 ---
 
@@ -33,299 +27,208 @@ npm install @aegis-fluxion/core ws
 
 ---
 
-## Middleware in 0.6.0+
-
-`SecureServer` now supports phase-based middleware for auth, policy enforcement, and payload
-normalization.
+## Session resumption (TLS 1.3-style)
 
-```ts
-import { SecureClient, SecureServer } from "@aegis-fluxion/core";
+`@aegis-fluxion/core@0.8.0` introduces secure resume-first reconnect behavior:
 
-const server = new SecureServer({ host: "127.0.0.1", port: 8080 });
+- Full handshake path uses ephemeral ECDH (`hello` frame).
+- Resume path uses ticket-bound proofs (`resume` / `resume-ack` frames).
+- Successful resumes derive fresh channel keys from ticket secret + client nonce.
+- Servers enforce ticket TTL, bounded cache size, and one-time ticket consumption.
+- Clients automatically fall back to full handshake when resume is rejected.
 
-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;
+### Server configuration
 
-    if (apiKey !== "dev-secret") {
-      throw new Error("Unauthorized");
-    }
+```ts
+import { SecureServer } from "@aegis-fluxion/core";
 
-    context.metadata.set("role", "editor");
+const server = new SecureServer({
+  host: "127.0.0.1",
+  port: 8080,
+  sessionResumption: {
+    enabled: true,
+    ticketTtlMs: 60_000,
+    maxCachedTickets: 10_000
   }
-
-  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();
+### Client configuration
 
-  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
-  };
-});
+```ts
+import { SecureClient } from "@aegis-fluxion/core";
 
 const client = new SecureClient("ws://127.0.0.1:8080", {
-  wsOptions: {
-    headers: {
-      "x-api-key": "dev-secret"
-    }
+  reconnect: true,
+  sessionResumption: {
+    enabled: true,
+    maxAcceptedTicketTtlMs: 60_000
   }
 });
-
-client.on("ready", async () => {
-  const response = await client.emit("post:create", { title: "  Hello  " }, { timeoutMs: 1500 });
-  console.log(response);
-});
 ```
 
-Notes:
+### Security model
 
-- Throwing in `connection` middleware rejects the socket and closes with code `1008`.
-- `metadata` is mutable in middleware (`Map`) and exposed read-only on `SecureServerClient`.
+- Resume proofs are validated with HMAC and constant-time comparison.
+- Resume tickets are encrypted in transit (same channel protections as all payloads).
+- Resume tickets are discarded if expired, policy-invalid, or already consumed.
+- Reserved internal events (e.g., session-ticket transport) cannot be emitted by user code.
 
 ---
 
-## Rate Limiting & DDoS Protection (0.7.1)
+## SecureServer adapter API (horizontal scaling)
 
-`SecureServer` can enforce burst limits per connection and per source IP before event handlers run.
+### Core types
 
 ```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."
-  }
-});
+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>;
+}
 ```
 
-Behavior summary:
+### SecureServer hooks
 
-- 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.
+- constructor option: `new SecureServer({ ..., adapter })`
+- runtime binding: `await server.setAdapter(adapter)`
+- inbound relay: `await server.handleAdapterMessage(message)`
+- instance identity: `server.serverId`
 
----
-
-## MCP Adapter Integration (0.7.0)
-
-Use `@aegis-fluxion/mcp-adapter` to carry MCP JSON-RPC messages through your encrypted core
-transport.
+### Message normalization helper
 
 ```ts
-import { SecureClient, SecureServer } from "@aegis-fluxion/core";
-import { SecureMCPTransport } from "@aegis-fluxion/mcp-adapter";
+import { normalizeSecureServerAdapterMessage } from "@aegis-fluxion/core";
+```
 
-const secureServer = new SecureServer({ host: "127.0.0.1", port: 9091 });
+Use it in adapters before delivering inbound Pub/Sub payloads to `SecureServer`.
 
-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);
-  };
+## Adapter integration example
 
-  await mcpServerTransport.start();
-});
+```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);
+  }
 
-const secureClient = new SecureClient("ws://127.0.0.1:9091");
+  async publish(message: SecureServerAdapterMessage): Promise<void> {
+    for (const peer of InMemoryAdapter.peers) {
+      if (peer === this || !peer.server) {
+        continue;
+      }
 
-const mcpClientTransport = new SecureMCPTransport({
-  mode: "client",
-  client: secureClient
-});
+      await peer.server.handleAdapterMessage(message);
+    }
+  }
 
-await mcpClientTransport.start();
+  async detach(server: SecureServer): Promise<void> {
+    if (this.server !== server) {
+      return;
+    }
 
-await mcpClientTransport.send({
-  jsonrpc: "2.0",
-  id: 100,
-  method: "tools/list",
-  params: {}
+    this.server = null;
+    InMemoryAdapter.peers.delete(this);
+  }
+}
+
+const server = new SecureServer({
+  host: "127.0.0.1",
+  port: 8080,
+  adapter: new InMemoryAdapter()
 });
 ```
 
 ---
 
-## 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
+## Middleware and ACK example
 
 ```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.");
+server.use(async (context, next) => {
+  if (context.phase === "connection") {
+    context.metadata.set("auth.role", "operator");
   }
 
-  socket.emit("image:chunk:ack", chunk);
+  await next();
 });
 
-client.on("ready", () => {
-  const imageChunk = Buffer.from("89504e470d0a", "hex");
-  client.emit("image:chunk", imageChunk);
+server.on("jobs:create", async (payload, client) => {
+  return {
+    ok: true,
+    role: client.metadata.get("auth.role"),
+    payload
+  };
 });
 
-client.on("image:chunk:ack", (payload) => {
-  const echoedChunk = payload as Buffer;
-  console.log("Echoed bytes:", echoedChunk.byteLength);
+const client = new SecureClient("ws://127.0.0.1:8080");
+
+client.on("ready", async () => {
+  const response = await client.emit("jobs:create", { id: "job-42" }, { timeoutMs: 1200 });
+  console.log(response);
 });
 ```
 
 ---
 
-## Example: ACK Roundtrip with Mixed Binary Types
+## Rate limiting and DDoS shield
 
 ```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
-  };
-});
+import { SecureServer } from "@aegis-fluxion/core";
 
-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);
+const server = new SecureServer({
+  host: "127.0.0.1",
+  port: 8080,
+  rateLimit: {
+    enabled: true,
+    windowMs: 1_000,
+    maxEventsPerConnection: 120,
+    maxEventsPerIp: 300,
+    action: "throttle", // or "disconnect"
+    throttleMs: 150,
+    maxThrottleMs: 2_000,
+    disconnectAfterViolations: 4,
+    disconnectCode: 1013,
+    disconnectReason: "Rate limit exceeded. Please retry later."
+  }
 });
 ```
 
 ---
 
-## 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)`
+## Binary payload support
 
----
+Supported encrypted payload types:
 
-## Security Notes
+- `Buffer`
+- `Uint8Array`
+- `Blob`
 
-- 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.
 
 ---