UAP-protocol

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

Universal Agent Protocol

Um protocolo de comunicação unificado, que prioriza a segurança, para acesso a ferramentas, coordenação de agentes e RPC estruturado. Construído para fechar a CVE-2025-49596 e a classe de vulnerabilidades de envenenamento de ferramentas e escape de sandbox que o MCP deixou estruturalmente abertas.

Quickstart em 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"}

Isso inicia o Keycloak na :8080 e o UAP Gateway na :3000. O gateway aplica mTLS, verifica CapabilityCards assinados com Ed25519 e executa cada chamada de ferramenta em um contêiner Docker efêmero. Nenhuma configuração é necessária além do par de chaves gerado.

Arquitetura

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)]

Camadas hexagonais — o domínio tem zero dependências de I/O. Toda preocupação de infraestrutura fica atrás de uma interface de porta tipada. Troque Docker por WASM, Keycloak por Auth0, Pino por um exportador de SIEM — zero impacto no domínio.

UAP vs MCP vs A2A vs JSON-RPC 2.0

Por que o UAP existe

• CVE-2025-49596 (envenenamento de ferramentas por meio de metadados não assinados). As descrições de ferramentas do MCP são mutáveis após a publicação. Um atacante pode injetar instruções maliciosas em nomes ou descrições de ferramentas após a implantação — o cliente não tem como detectar adulteração. O UAP coloca todos os metadados de ferramentas dentro do payload do CapabilityCard assinado com Ed25519. Qualquer mutação após a assinatura invalida a assinatura e o gateway rejeita o cartão antes de executar qualquer coisa.

• CWE-284 / classe de escape de sandbox. O MCP executa ferramentas no nível do processo do servidor. Um path traversal ou injeção de processo em qualquer ferramenta alcança o sistema de arquivos e a rede do host. O UAP cria um contêiner Docker novo por chamada — rootfs somente leitura, CapDrop: ALL, limite de 128 MB de RAM, rede desabilitada por padrão. O contêiner é destruído após a resposta. Não há superfície de ataque persistente entre chamadas.

• CWE-287 / autenticação de representante confuso (confused-deputy). O MCP atua como seu próprio provedor OAuth, tornando-o tanto o servidor de recursos quanto o servidor de autorização. Esse é o clássico padrão confused-deputy. O UAP separa esses papéis: o gateway é um servidor de recursos puro. O Keycloak (ou qualquer IdP externo) é a única autoridade. Os JWTs são verificados contra um endpoint JWKS remoto e têm limite rígido de 15 minutos.

Formato do protocolo

Toda mensagem UAP usa o mesmo envelope. O bloco auth carrega um JWT com escopo e uma referência ao CapabilityCard assinado do agente. O gateway verifica ambos antes que a requisição chegue a qualquer código de aplicação.

{
  "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
}

Pacotes

UAP-protocol/
├── packages/
│   ├── gateway/      @uap/gateway   — Fastify-based UAP Gateway
│   ├── sdk-ts/       @uap/sdk-ts    — TypeScript client + server SDK
│   └── sdk-py/       uap-sdk        — Python async SDK (httpx + FastAPI)
├── scripts/
│   ├── generate-keypair.ts          — Ed25519 keypair for local dev
│   └── keycloak-bootstrap.ts        — Idempotent Keycloak realm setup
└── docker/
    └── sandbox/                     — Base image for zero-trust tool execution

Cliente TypeScript

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

const client = new UapClient({
  gatewayUrl: "https://gateway.example.com",
  tokenProvider: new ClientCredentialsTokenProvider({
    tokenUrl: process.env.TOKEN_URL!,
    clientId: process.env.CLIENT_ID!,
    clientSecret: process.env.CLIENT_SECRET!,
  }),
});

const result = await client.invokeTool(
  "db:query",
  { sql: "SELECT * FROM users LIMIT 10" },
  ["tool:read"]
);

const task = await client.delegateTask(
  "summarizer",
  { text: "..." },
  ["task:submit"]
);

Cliente Python

from uap_sdk.client import UapClient, UapClientOptions
from uap_sdk.token import ClientCredentialsTokenProvider

async with UapClient(UapClientOptions(
    gateway_url="https://gateway.example.com",
    token_provider=ClientCredentialsTokenProvider(
        token_url=os.environ["TOKEN_URL"],
        client_id=os.environ["CLIENT_ID"],
        client_secret=os.environ["CLIENT_SECRET"],
    )
)) as client:
    result = await client.invoke_tool("db:query", {"sql": "SELECT 1"}, ["tool:read"])

Middleware FastAPI

from uap_sdk.middleware import uap_auth

@app.post("/summarize")
@uap_auth(scope=["task:submit"])
async def summarize(request: Request):
    claims = request.state.uap_claims  # typed AuthClaims
    ...

Migre um servidor MCP existente

O CLI uap-migrate envolve qualquer servidor MCP como um CapabilityCard UAP assinado em menos de 5 minutos. Idempotente — executá-lo novamente em um servidor já migrado é um no-op.

node dist/cli/migrate.js mcp http://localhost:3001 \
  --issuer did:uap:my-org \
  --key config/dev.privkey.hex \
  --out ./uap-cards

# → ./uap-cards/did:uap:my-org.card.json

Assinatura de CapabilityCard

Nomes de ferramentas, descrições e esquemas de parâmetros fazem parte do payload assinado com Ed25519. Mutar qualquer campo após a assinatura invalida a assinatura — derrotando estruturalmente o envenenamento de ferramentas.

const signed = await signer.sign({
  issuer: "did:uap:my-agent",
  version: "1.0.0",
  tools: [{
    id: "db:query",
    description: "Run a read-only SQL query",
    inputSchema: { type: "object", required: ["sql"] },
    scopes: ["tool:read"]
  }],
  scopes: ["tool:read"],
  issuedAt: Date.now(),
  expiresAt: Date.now() + 86_400_000 * 30
});
// signed.signature === "ed25519:a1b2c3..."

Variáveis de ambiente

Dependências principais

Contribuindo

Nomenclatura de branches: feat/<sprint>-<task>-<slug> — ex.: feat/s2-2.1-mtls-keycloak

Toda alteração segue: branch → npx tsc --noEmit + npx vitest run localmente → commit → PR → squash merge → exclusão da branch. Sem dependência de CI para desenvolvimento local.

# Run all tests before committing
cd packages/gateway && npx vitest run
cd packages/sdk-ts  && npx vitest run
cd packages/sdk-py  && python -m pytest tests/ -v

Roadmap: Sprint 0 (scaffold) → Sprint 1 (esquema + assinatura + RPC) → Sprint 2 (núcleo de segurança) → Sprint 3 (gateway + registro) → Sprint 4 (adaptadores de ponte) → Sprint 5 (SDKs + imagem Docker).

UAP · Universal Agent Protocol · 2026

SPDX-License-Identifier: Apache-2.0