UAP-protocol

 ██╗   ██╗ █████╗ ██████╗
 ██║   ██║██╔══██╗██╔══██╗
 ██║   ██║███████║██████╔╝
 ██║   ██║██╔══██║██╔═══╝
 ╚██████╔╝██║  ██║██║
  ╚═════╝ ╚═╝  ╚═╝╚═╝

Universal Agent Protocol

Un protocolo de comunicación unificado y centrado en la seguridad para el acceso a herramientas, la coordinación de agentes y RPC estructurado. Creado para cerrar CVE-2025-49596 y la clase de vulnerabilidades de envenenamiento de herramientas y escape de sandbox que MCP dejó estructuralmente abiertas.

---

Inicio rápido en 30 segundos

git clone https://github.com/RajSidwadkar/UAP-protocol
cd UAP-protocol
npm install
npx tsx scripts/generate-keypair.ts
docker compose -f docker-compose.dev.yml up -d

curl http://localhost:3000/health
# {"status":"ok","version":"1.0.0"}

Eso inicia Keycloak en :8080 y la Puerta de Enlace UAP en :3000. La puerta de enlace aplica mTLS, verifica las CapabilityCards firmadas con Ed25519 y ejecuta cada llamada de herramienta en un contenedor Docker efímero. No se requiere configuración más allá del par de claves generado.

---

Arquitectura

graph TD
    A[Client / Agent SDK] -->|mTLS + JWT + card_sig| B[UAP Gateway<br/>Fastify · port 3000]

    B --> C{8-Stage Pipeline}

    C --> C1[1 · Frame parse<br/>UapMessageFactory]
    C1 --> C2[2 · Schema validate<br/>AJV against schema_ref]
    C2 --> C3[3 · Token verify<br/>Keycloak JWKS · max 15 min]
    C3 --> C4[4 · Scope enforce<br/>PermissionEnforcer]
    C4 --> C5[5 · Card verify<br/>Ed25519 signature check]
    C5 --> C6[6 · Sandbox execute<br/>Docker · CapDrop ALL · 128 MB]
    C6 --> C7[7 · Audit emit<br/>AuditEventBus · non-blocking]
    C7 --> C8[8 · Response<br/>UapResponseEnvelope]

    B --> R[(Service Registry<br/>InMemory · Redis)]
    B --> KC[(Keycloak IdP<br/>OAuth 2.1 · PKCE)]
    B --> OT[(OpenTelemetry<br/>W3C TraceContext)]
    B --> AU[(Audit Log<br/>append-only NDJSON)]

Capas hexagonales — el dominio tiene cero dependencias de E/S. Cada preocupación de infraestructura se sitúa detrás de una interfaz de puerto tipada. Cambia Docker por WASM, Keycloak por Auth0, Pino por un exportador SIEM — impacto nulo en el dominio.

Capa	Contenido	Dependencias
Dominio	UapEnvelope, CapabilityCard, AuditEvent, Task	Ninguna — solo stdlib
Aplicación	InvokeToolUseCase, DelegateTaskUseCase, ValidateCardUseCase	Solo puertos de dominio
Infraestructura	KeycloakAuthAdapter, DockerSandboxAdapter, Ed25519SignerAdapter, PinoAuditAdapter	Puertos de la aplicación + librerías externas
Transporte	Analizador de tramas UAP-RPC, puerta de enlace Fastify, manejadores SSE/WebSocket	Serializadores de infraestructura + dominio

---

UAP vs MCP vs A2A vs JSON-RPC 2.0

Característica	UAP	MCP	A2A	JSON-RPC 2.0
Autenticación obligatoria	✅ mTLS + JWT siempre	❌ Opcional	⚠️ Solo clave API	❌ Ninguna
Integridad de metadatos de herramientas	✅ Carga útil firmada con Ed25519	❌ Mutación posterior a la publicación posible	❌ Sin firma	❌ Sin firma
Modelo de sandbox	✅ Docker efímero por llamada	⚠️ Solo a nivel de servidor	❌ Ninguno	❌ Ninguno
Descubrimiento de agentes	✅ Hub-and-spoke · N conexiones	❌ HTTP directo N²	⚠️ Basado en DNS	❌ Ninguno
Registro de auditoría	✅ Registro de solo-apéndice nativo del protocolo	❌ Ninguno	❌ Ninguno	❌ Ninguno
Trazado distribuido	✅ W3C TraceContext obligatorio	❌ Ninguno	❌ Ninguno	❌ Ninguno
Validación de esquema	✅ AJV en la capa de transporte	⚠️ Zod opcional	❌ Ninguna	❌ Ninguna
Límite de vida del token	✅ 15 min aplicado	❌ No aplicado	❌ No aplicado	❌ N/A
Semántica de lotes	✅ serial · paralelo · transaccional	❌ Indefinida	❌ Ninguna	⚠️ Ambigua
Cargas útiles binarias	✅ Tramas nativas	❌ Solo Base64	❌ Solo Base64	❌ Solo Base64
Modelo de IdP	✅ Solo IdP externo	❌ El servidor es su propio proveedor OAuth	⚠️ Varía	❌ Ninguno
Adaptadores de puente	✅ Los puentes MCP + A2A se incluyen en la Fase 2	❌ Sin puente	❌ Sin puente	❌ Sin puente
Escalado horizontal	✅ Sin estado · cualquier balanceador de carga	❌ Sticky sessions	⚠️ Varía	❌ Ninguno

---

Por qué existe UAP

• CVE-2025-49596 (envenenamiento de herramientas mediante metadatos sin firmar). Las descripciones de herramientas de MCP son mutables después de su publicación. Un atacante puede inyectar instrucciones maliciosas en los nombres o descripciones de las herramientas después del despliegue: el cliente no tiene forma de detectar la manipulación. UAP coloca todos los metadatos de las herramientas dentro de la carga útil de la CapabilityCard firmada con Ed25519. Cualquier mutación posterior a la firma invalida la firma y la puerta de enlace rechaza la tarjeta antes de ejecutar nada.

• CWE-284 / clase de escape de sandbox. MCP ejecuta las herramientas a nivel del proceso del servidor. Un path traversal o una inyección de procesos en cualquier herramienta alcanza el sistema de archivos y la red del host. UAP crea un contenedor Docker nuevo por llamada — rootfs de solo lectura, CapDrop: ALL, límite de 128 MB de RAM, red deshabilitada por defecto. El contenedor se destruye después de la respuesta. No hay superficie de ataque persistente entre llamadas.

• CWE-287 / autenticación de diputado confundido. MCP actúa como su propio proveedor OAuth, convirtiéndose a la vez en servidor de recursos y servidor de autorización. Este es el patrón clásico de diputado confundido. UAP separa estos roles: la puerta de enlace es un servidor de recursos puro. Keycloak (o cualquier IdP externo) es la única autoridad. Los JWT se verifican contra un endpoint JWKS remoto y tienen un tope máximo de 15 minutos.

---

Formato de mensajes

Cada mensaje UAP usa el mismo envelope. El bloque auth transporta un JWT con alcance y una referencia a la CapabilityCard firmada del agente. La puerta de enlace verifica ambos antes de que la solicitud llegue a cualquier código de aplicación.

{
  "uap": {
    "version": "1.0",
    "type": "tool_call",
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "trace": {
      "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
    },
    "auth": {
      "token": "eyJhbGciOiJSUzI1NiJ9...",
      "scope": ["tool:read"],
      "card_sig": "ed25519:a1b2c3d4..."
    }
  },
  "method": "tools/invoke",
  "schema_ref": "uap:tool.invoke/v1",
  "params": {
    "tool_id": "db:query",
    "input": { "sql": "SELECT 1" }
  },
  "ack": true
}

---

Paquetes

UAP-protocol/
├── packages/
│   ├── gateway/      @uap/gateway   — Puerta de Enlace UAP basada en Fastify
│   ├── sdk-ts/       @uap/sdk-ts    — SDK de cliente + servidor TypeScript
│   └── sdk-py/       uap-sdk        — SDK asíncrono de Python (httpx + FastAPI)
├── scripts/
│   ├── generate-keypair.ts          — Par de claves Ed25519 para desarrollo local
│   └── keycloak-bootstrap.ts        — Configuración idempotente del realm de Keycloak
└── docker/
    └── sandbox/                     — Imagen base para ejecución de herramientas de confianza cero

---

Cliente TypeScript

import { UapClient, ClientCredentialsTokenProvider } from "@uap/sdk-ts";