Gateway and Stream

Expose and route LIOP traffic with hybrid and stream bridges

The SDK includes transport components for routing MCP traffic across local and mesh environments.

LiopHybridGateway

LiopHybridGateway multiplexes HTTP/1.1 and HTTP/2 (gRPC) over a single TCP port and delegates MCP requests through LiopMcpRouter.

import { LiopHybridGateway, LiopServer } from "@nekzus/liop";

const server = new LiopServer({ name: "gateway-node", version: "1.0.0" });
const gateway = new LiopHybridGateway(server, null, 50051);

await gateway.listen(3000);
// ... serve traffic
await gateway.stop();

LiopMcpRouter & Dual-Era Compliance

LiopMcpRouter is the request dispatcher used by the gateway and CLI agents. It provides Dual-Era MCP Protocol Compliance:

• Modern MCP v2 Era (2026-07-28): Supports stateless routing, non-polling resource updates via subscriptions/listen, dynamic resource template discovery (resources/templates/list), SEP-2243 header routing, and deterministically sorted results (SEP-2549).
• Legacy MCP Era (2025-11-25): Automatically negotiates handshake capabilities and strips unsupported fields via adaptResponseForLegacyClient() for legacy MCP clients (Claude Desktop, Cursor).
• In-Situ Dispatch: Routes calls to local tool definitions or discovers remote data providers across the Kademlia DHT mesh.
• ZK Verification: Automatically verifies HMAC-SHA256 ZK-Receipt commitments on incoming remote responses before returning results to the LLM.

HTTP/1.1 gRPC-Web Framing Adapter

For edge networks, web browsers, and environments where native HTTP/2 gRPC framing is restricted by corporate firewalls or reverse proxies, LiopHybridGateway integrates an automatic gRPC-Web framing adapter:

• Emulates gRPC 5-byte length-prefixed binary frames ([flags (1B)][length (4B BE)][payload]) over standard HTTP/1.1 POST streams.
• Encodes gRPC status trailers in HTTP response headers (grpc-status, grpc-message).

Observability & Health Probes

LiopHybridGateway natively serves standard Kubernetes and Prometheus endpoints:

Endpoint	Protocol	Purpose
GET /healthz	HTTP/1.1	Liveness probe returning immediate JSON status ({ status: "ok" })
GET /readyz	HTTP/1.1	Readiness probe checking active DHT mesh connections and bootstrap sync
GET /metrics	HTTP/1.1	Prometheus scraper endpoint reporting instantaneous connection gauges and latency histograms
POST /mcp	HTTP/1.1 (JSON-RPC)	Streamable MCP interface with session isolation and Zero-Trust bearer auth

Graceful Draining

When terminating nodes in production clusters:

// Closes active listening sockets and allows in-flight RPCs to complete safely
await gateway.drain(5000); // 5-second graceful drain timeout

LiopStreamBridge

LiopStreamBridge exposes a LiopServer over Streamable HTTP transport with session isolation.

import { LiopServer, LiopStreamBridge } from "@nekzus/liop";

const server = new LiopServer({ name: "stream-node", version: "1.0.0" });
const stream = new LiopStreamBridge(server, {
  port: 3000,
  maxSessionsPerIp: 10,
  sessionTimeoutMs: 30 * 60 * 1000
});

await stream.start();
// ... streamable MCP traffic on /mcp
await stream.stop();

Border LIO Gateway (BLG) & Perimeter Defense

In production topologies with multi-tier security domains, the Border LIO Gateway (blg) acts as the protocol boundary between external untrusted networks and Tier 1 sovereign enclaves:

// Client invocation targeting Border LIO Gateway with OAuth 2.1 Bearer authentication
const tokenResponse = await fetch("http://nexus:3000/oidc/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: "border-gateway-client",
    client_secret: process.env.LIOP_BLG_SECRET || "default-secret"
  })
});

const { access_token, expires_in } = await tokenResponse.json();
// Bearer token is cached in memory with a 30s pre-expiration margin

Gateway Responsibilities

1. OAuth 2.1 Token Verification: Asserts Bearer tokens signed by Nexus OIDC before proxying JSON-RPC requests to internal services.
2. Swarm Key Bridge: Possesses the private 256-bit PSK required to communicate directly with Tier 1 enclaves (The Bank, The Vault) across the isolated pnet subnet.
3. Defense-in-Depth Inspection: Runs preflight validation on AST logic payloads before dispatching to destination enclaves.

---

Sliding-Window Rate Limiter (InMemoryRateLimiter)

To defend edge gateways, MCP endpoints, and worker pools against Denial of Service (DoS) attacks and brute-force token enumeration, the SDK provides a high-throughput, zero-dependency InMemoryRateLimiter.

It strictly adheres to OWASP API Security Top 10 (API4:2023 - Unrestricted Resource Consumption) by enforcing per-client sliding-window quotas.

import { InMemoryRateLimiter } from "@nekzus/liop";

const limiter = new InMemoryRateLimiter({
  windowMs: 60_000,    // 1-minute evaluation window
  maxRequests: 120     // Up to 120 requests per window
});

// Middleware evaluation per incoming client IP or OAuth client ID
const status = limiter.check(req.socket.remoteAddress || "anonymous");
if (!status.allowed) {
  res.writeHead(429, {
    "Content-Type": "application/json",
    "Retry-After": Math.ceil(status.resetMs / 1000).toString(),
    "X-RateLimit-Limit": status.limit.toString(),
    "X-RateLimit-Remaining": status.remaining.toString(),
    "X-RateLimit-Reset": Math.ceil(status.resetMs / 1000).toString()
  });
  res.end(JSON.stringify({ error: "Too Many Requests", retryAfterMs: status.resetMs }));
  return;
}

RateLimiter API Reference

Method	Signature	Description
check(key)	(key: string) => RateLimitStatus	Evaluates whether the client quota allows another request. Returns remaining quota, status, and reset millisecond countdown.
reset(key)	(key: string) => void	Manually clears the bucket counter for a specific client key (useful post-successful MFA/OIDC challenge).
cleanup()	() => void	Prunes expired client records from the internal Map to prevent memory leaks during long-running sessions.
close()	() => void	Clears internal interval timers and destroys all cached quota buckets during graceful node shutdown.

The internal cleanup timer runs every 30 seconds and invokes unref(). This ensures the background maintenance loop never prevents the Node.js event loop from terminating cleanly during process exits or testing suites.

---

Security Notes

• LiopStreamBridge supports Zero-Trust bearer enforcement via ZERO_TRUST_TOKEN.
• Sessions are isolated and evicted when idle to reduce long-lived attack surfaces.
• Gateway/router components preserve full MCP JSON-RPC compatibility while maintaining mesh-native routing behavior.
• The Border LIO Gateway caches RFC 6749 credentials in-memory with automatic refresh 30 seconds prior to expiration, eliminating transient 401 Unauthorized errors during high-frequency batch executions.
• For semantic perimeter filtering, see Gateway Interceptor.