LiopClient

Orquestación de alto nivel para enrutamiento de intenciones, descubrimiento de pares y ejecución de lógica in-situ

La clase LiopClient actúa como el coordinador principal de despacho para los Nodos Agente en el protocolo Logic-Injection-on-Origin. Administra la negociación de transporte a través de topologías heterogéneas (pasarelas directas HTTP/JSON-RPC, proxies perimetrales autenticados y canales gRPC punto a punto soberanos), ejecuta acuerdos criptográficos y despacha módulos de lógica WebAssembly o JavaScript hacia Nodos de Datos remotos.

A diferencia de los clientes tradicionales del Model Context Protocol (MCP) que extraen volúmenes masivos de datos crudos a través de la red mediante sondeos o conexiones continuas, LiopClient empaqueta la intención analítica en micro-módulos aislados y los transmite directamente hacia el origen físico donde residen los datos.

---

​

Constructor y Configuración

El constructor configura las credenciales TLS a nivel de transporte que aplican a todas las conexiones gRPC subyacentes.

import { LiopClient } from "@nekzus/liop";
import type { LiopTlsOptions } from "@nekzus/liop";

const tls: LiopTlsOptions = {
  rootCertPath: "/etc/ssl/certs/liop-ca.pem",
  clientCertPath: "/etc/ssl/certs/agent-client.pem",
  clientKeyPath: "/etc/ssl/private/agent-key.pem",
  serverNameOverride: "mesh.enclave.internal",
};

const client = new LiopClient(tls);

​

Parámetros del Constructor

tls · LiopTlsOptions

Credenciales criptográficas para TLS mutuo (mTLS) o verificación de identidad de servidor sobre el transporte gRPC.

Mostrar Propiedades de LiopTlsOptions

rootCertPath · string

Ruta en el sistema de archivos al certificado CA raíz utilizado para validar la identidad del servidor.

clientCertPath · string

Ruta en el sistema de archivos al certificado del cliente para autenticación mutua mTLS.

clientKeyPath · string

Ruta en el sistema de archivos a la clave privada correspondiente a clientCertPath.

serverNameOverride · string

Sobrescribe el nombre SNI del servidor esperado al conectar a través de proxies internos o redes de contenedores.

---

​

Conexión a la Malla (connect)

El método connect() establece la identidad del nodo, aprovisiona tokens OAuth 2.1 de máquina a máquina (M2M) y monta un canal gRPC directo punto a punto o un nodo distribuido libp2p.

// Patrón A: Conexión directa a una pasarela o enclave específico
await client.connect("127.0.0.1:15021", {
  auth: {
    clientId: "analytics-agent-01",
    clientSecret: process.env.LIOP_CLIENT_SECRET,
    nexusUrl: "http://127.0.0.1:15000",
    audience: "urn:liop:mesh:api",
    scope: "liop:tools:call liop:tools:list",
  },
});

// Patrón B: Conexión dinámica al dorsal P2P de la malla
await client.connect(undefined, {
  meshConfig: {
    bootstrapNodes: [
      "/ip4/198.51.100.10/tcp/15001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN"
    ],
    listenAddresses: ["/ip4/0.0.0.0/tcp/0"],
  },
});

​

Opciones de Conexión

address · string

Dirección de destino en formato host:puerto. Cuando se define, crea un cliente LiopRpcClient directo de alta velocidad orientado a dicho destino. Si se omite, LiopClient enruta las peticiones de manera dinámica mediante la tabla DHT peer-to-peer.

options · object

Ajustes avanzados de conexión que abarcan autenticación y descubrimiento distribuido.

Mostrar Propiedades de Opciones de Conexión

auth.clientId · string

Identificador de cliente OAuth 2.1 registrado en el servidor de autorización Nexus OIDC. Si se omite, consulta process.env.LIOP_OAUTH_CLIENT_ID.

auth.clientSecret · string

Secreto de cliente para el flujo Client Credentials conforme a RFC 6749. Si se omite, consulta process.env.LIOP_OAUTH_CLIENT_SECRET.

auth.nexusUrl · string

Dirección base del proveedor de identidad OIDC (ej. http://127.0.0.1:15000). Normaliza automáticamente el endpoint /oidc/token.

auth.audience · string

Indicador de recurso RFC 8707 orientado al enclave de destino (por defecto: urn:liop:mesh:api).

auth.scope · string

Ámbitos OAuth 2.1 delimitados por espacios requeridos para la ejecución. Aplica alcances de capacidades estándar por omisión.

auth.token · string

Token Bearer estático precalculado. Omite la negociación dinámica de TokenManager cuando se suministra.

meshConfig · MeshNodeConfig

Objeto de configuración para la instancia subyacente de libp2p que comprende multiaddrs de arranque y claves de enjambre (swarm keys).

---

​

Descubrimiento de Capacidades e Invocación de Herramientas

LiopClient unifica el descubrimiento y ejecución de herramientas bajo las estructuras estándar de MCP y asegura el transporte post-cuántico en cada llamada.

// 1. Descubrir herramientas registradas en los nodos conectados
const tools = await client.discoverTools();
console.log(`Herramientas descubiertas en la malla: ${tools.length}`);

// 2. Resolver el nodo que aloja la capacidad deseada
const targetPeer = await client.resolveCapability("Analyze_Bank_Ledger");

// 3. Invocar la herramienta con lógica in-situ
const response = await client.callTool({
  name: "Analyze_Bank_Ledger",
  arguments: {
    account_id: "ACC-88219",
    currency: "USD",
    min_amount: 10000,
  },
});

for (const item of response.content) {
  if (item.type === "text") {
    console.log("Resultado analítico:", item.text);
  }
}

​

Inyección de Lógica In-Situ (Bytecode WASM)

En flujos donde el movimiento de datos está prohibido por normativas de privacidad, envíe directamente el bytecode compilado de WebAssembly en el segundo parámetro opcional de callTool(). El enclave remoto inspecciona el código mediante Guardian AST antes de ejecutarlo en un sandbox aislado V8.

import { readFileSync } from "node:fs";

const wasmBinary = readFileSync("./aggregators/p99_latency.wasm");

const result = await client.callTool(
  {
    name: "Query_Telemetry_Logs",
    arguments: { service: "auth-gateway", window: "1h" },
  },
  wasmBinary, // Lógica inyectada que se ejecuta en el origen de los datos
);

---

​

Verificación Matemática (Recibos ZK)

Cada carga analítica procesada por un Nodo de Datos LIOP conforme genera un recibo criptográfico ZK. El verificador del cliente inspecciona automáticamente los recibos devueltos durante la invocación de callTool(), dando soporte completo a los tres modos del protocolo:

• Modo 0 (Versión 1): Compromiso de sesión HMAC-SHA256 negociado mediante ML-KEM-768.
• Modo 2 (Versión 2): Prueba matemática de conocimiento cero SNARK Groth16 sobre la curva de emparejamiento BN254.
• Modo 3 (Versión 2.1): Recibo híbrido de doble capa que combina una prueba Groth16 BN254 con una firma digital post-cuántica ML-DSA-65.

Para verificar manualmente recibos obtenidos fuera de banda:

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

const verifier = new LiopVerifier();

const isValid = await verifier.verifyZkReceipt(
  wasmPayload,          // Buffer con el código exacto que fue inyectado
  remoteImageIdHex,     // Identificador hexadecimal de 32 bytes de la imagen huésped
  zkReceiptBuffer,      // Recibo criptográfico entregado por el servidor
  { zkPolicy: "required" } // "none" | "optimistic" | "required"
);

if (!isValid) {
  throw new Error("Fallo de Verificación Zero-Trust: Alteración de cómputo detectada");
}

​

Atestación de Hardware TEE Pre-Vuelo

Al establecer comunicación con máquinas virtuales confidenciales desplegadas en centros de datos no confiables, el cliente puede verificar la evidencia de la raíz de confianza de hardware antes de iniciar acuerdos criptográficos:

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

const attestationResult = await verifyTeeAttestationDetailed(
  attestationEvidenceBytes,
  expectedSessionNonce,
  {
    allowedMeasurements: ["b7f8c9..."],
    requireHardwareSigned: true,
  }
);

if (!attestationResult.valid) {
  throw new Error(`Validación de hardware confidencial fallida: ${attestationResult.reason}`);
}

El verificador previo valida los siguientes entornos:

• AMD SEV-SNP: Inspecciona la cabecera snp_report_t de 1.184 bytes, valida REPORT_DATA en el desplazamiento 0x50 contra SHA-256(publicKey || nonce), verifica las firmas de certificados VCEK y corrobora la desactivación del modo de depuración.
• AWS Nitro Enclaves: Decodifica documentos COSE_Sign1 en formato CBOR, valida los registros PCR (PCR0, PCR1, PCR2), comprueba la vinculación de user_data y verifica los certificados hasta la CA raíz de AWS Nitro.

---

​

Transporte gRPC de Bajo Nivel (LiopRpcClient)

Para aplicaciones que demandan control granular sobre canales gRPC, streaming de metadatos o inyección de credenciales sin instanciar un nodo P2P, utilice LiopRpcClient de forma directa:

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

const rpc = new LiopRpcClient(
  "127.0.0.1:15021",
  tlsConfig,
  async () => tokenManager.getToken(), // Resolvedor asíncrono dinámico de tokens
);

// Paso 1: Negociar intención y adquirir la clave pública efímera de Kyber
const intent = await rpc.negotiateIntent({
  capabilityName: "Analyze_Bank_Ledger",
  requesterPeerId: "12D3KooW...",
  clearanceLevel: 3,
});

// Paso 2: Transmitir ejecución de lógica
const stream = rpc.executeLogic(encryptedLogicRequest);

stream.on("data", (response) => {
  console.log("Fragmento recibido:", response.payload);
});
stream.on("error", (err) => {
  console.error("Error en flujo RPC:", err);
});

​

Invariantes de Canales gRPC

LiopRpcClient implementa opciones simétricas de canal para impedir que consultas analíticas extensas se desconecten ante cortafuegos corporativos o tablas de estado NAT agresivas:

Opción de Canal	Valor	Propósito
grpc.keepalive_time_ms	30000 (30s)	Emite paquetes de sondeo TCP cada 30 segundos para mantener el canal abierto.
grpc.keepalive_timeout_ms	10000 (10s)	Tolera hasta 10 segundos de espera de respuesta antes de declarar rota la conexión.
grpc.keepalive_permit_without_calls	1	Permite sondeos keepalive incluso cuando no existen llamadas RPC activas.
grpc.http2.max_pings_without_data	0	Elimina límites de ráfaga en paquetes de sondeo para prevenir reinicios del proxy.

---

​

Referencia de Métodos Públicos

Método	Parámetros	Tipo Retornado	Descripción
connect(address?, options?)	address?: string, options?: ConnectOptions	Promise<void>	Inicia el descubrimiento, obtiene credenciales M2M y monta los canales de transporte.
callTool(request, wasmBuffer?)	request: CallToolRequest, wasmBuffer?: Buffer	Promise<CallToolResult>	Despacha la invocación de la herramienta junto con el bytecode de lógica in-situ opcional.
discoverTools()	Ninguno	Promise<ToolDefinition[]>	Consulta a los pares conectados y recopila todas las definiciones de herramientas declaradas.
listTools()	Ninguno	Promise<ToolDefinition[]>	Alias de discoverTools() para compatibilidad estricta con clientes MCP.
resolveCapability(name)	name: string	Promise<string | undefined>	Resuelve la dirección o multiaddr del nodo que anuncia la herramienta indicada.
getRoutingTable()	Ninguno	RoutingTable | undefined	Devuelve la instancia interna de la tabla de enrutamiento híbrido activo.
getMeshNode()	Ninguno	MeshNode | null	Devuelve el nodo libp2p subyacente cuando opera en modalidad de malla.
getServerInfo()	Ninguno	{ name: string; version: string } | undefined	Proporciona las cabeceras de identificación negociadas durante el protocolo de inicio.
close()	Ninguno	Promise<void>	Concluye ordenadamente todos los canales gRPC activos, pools de workers y sockets P2P.

---

​

Catálogo de Excepciones y Códigos de Error

LiopClient emite excepciones estructuradas cuando las políticas de seguridad, las verificaciones de acceso o los límites del sandbox bloquean una ejecución.

import { LiopError, ErrorCode } from "@nekzus/liop";

try {
  await client.callTool({
    name: "Analyze_Bank_Ledger",
    arguments: { query: "DROP TABLE users;" },
  });
} catch (error) {
  if (error instanceof LiopError) {
    switch (error.code) {
      case ErrorCode.AST_SECURITY_VIOLATION:
        console.error("Rechazo en Capa 1: El código intentó acceder a variables globales restringidas");
        break;
      case ErrorCode.UNAUTHENTICATED:
        console.error("Token expirado o inválido: Compruebe las credenciales OAuth 2.1");
        break;
      case ErrorCode.CIRCUIT_BREAKER_OPEN:
        console.warn("Nodo degradado. Enrutando hacia el enclave de respaldo");
        break;
      default:
        console.error(`Error de Protocolo [${error.code}]:`, error.message);
    }
  }
}

​

Códigos de Error del Protocolo

Código de Error	Equivalencia HTTP / RPC	Causa	Acción Recomendada
UNAUTHENTICATED	HTTP 401 / gRPC 16	Token Bearer de OAuth 2.1 ausente, expirado o con firma incorrecta.	Renueve credenciales llamando a TokenManager.invalidate().
FORBIDDEN	HTTP 403 / gRPC 7	El nivel de autorización del cliente no alcanza la clasificación requerida por el recurso.	Solicite elevación de permisos en la consola Nexus OIDC.
AST_SECURITY_VIOLATION	RPC -32099 / gRPC 3	Guardian AST detectó importaciones prohibidas o variables globales envenenadas.	Asegure que el código solo use funciones de la lista permitida de WASI Preview 1.
SANDBOX_HALTED	RPC -32098 / gRPC 9	El Isolate de V8 superó la cuota de instrucciones CPU asignada o el tope de memoria heap.	Optimice bucles internos o incremente el límite de maxHeapMb.
CIRCUIT_BREAKER_OPEN	HTTP 503 / gRPC 14	El destino acumuló 5 fallos consecutivos (MAX_FAILURES = 5).	Espere el periodo de decaimiento o utilice una ruta perimetral alternativa.
ZK_VERIFICATION_FAILED	RPC -32097 / gRPC 10	La prueba matemática falló la comprobación de emparejamiento Groth16, el sello HMAC o la firma post-cuántica ML-DSA-65.	Posible manipulación de red en tránsito o imagen huésped no autorizada. Descarte la respuesta de inmediato.