UAP-protocol

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

Universal Agent Protocol

Un protocollo wire unificato e security-first per l'accesso agli strumenti, il coordinamento degli agenti e RPC strutturato. Progettato per chiudere CVE-2025-49596 e la classe di vulnerabilità di tool-poisoning e sandbox-escape che MCP ha lasciato strutturalmente aperte.

Guida rapida in 30 secondi

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

Questo avvia Keycloak sulla porta :8080 e il gateway UAP sulla porta :3000. Il gateway impone mTLS, verifica le CapabilityCard firmate Ed25519 ed esegue ogni chiamata di strumento in un container Docker effimero. Nessuna configurazione richiesta oltre alla coppia di chiavi generata.

Architettura

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

Layers esagonali — il dominio ha zero dipendenze I/O. Ogni aspetto infrastrutturale si trova dietro un'interfaccia port tipizzata. Sostituisci Docker con WASM, Keycloak con Auth0, Pino con un exporter SIEM — impatto zero sul dominio.

UAP vs MCP vs A2A vs JSON-RPC 2.0

Perché esiste UAP

• CVE-2025-49596 (tool-poisoning tramite metadati non firmati). Le descrizioni degli strumenti MCP sono mutabili dopo la pubblicazione. Un attaccante può iniettare istruzioni dannose nei nomi o nelle descrizioni degli strumenti dopo il deployment — il client non ha alcun modo di rilevare la manomissione. UAP inserisce tutti i metadati degli strumenti nel payload della CapabilityCard firmata Ed25519. Qualsiasi mutazione dopo la firma invalida la firma e il gateway rifiuta la card prima di eseguire qualsiasi cosa.

• CWE-284 / classe sandbox-escape. MCP esegue gli strumenti a livello di processo del server. Un path traversal o un'iniezione di processo in qualsiasi strumento raggiunge il filesystem e la rete dell'host. UAP crea un nuovo container Docker per ogni chiamata — rootfs di sola lettura, CapDrop: ALL, limite di 128 MB di RAM, rete disabilitata per impostazione predefinita. Il container viene distrutto dopo la risposta. Non esiste una superficie d'attacco persistente tra le chiamate.

• CWE-287 / autenticazione confused-deputy. MCP agisce come proprio provider OAuth, rendendosi sia server delle risorse che server di autorizzazione. Questo è il classico schema confused-deputy. UAP separa questi ruoli: il gateway è un puro server delle risorse. Keycloak (o qualsiasi IdP esterno) è l'unica autorità. I JWT vengono verificati contro un endpoint JWKS remoto e hanno un tetto massimo di 15 minuti.

Formato wire

Ogni messaggio UAP utilizza lo stesso envelope. Il blocco auth trasporta un JWT con scope e un riferimento alla CapabilityCard firmata dell'agente. Il gateway verifica entrambi prima che la richiesta raggiunga qualsiasi codice applicativo.

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

Pacchetti

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

Client 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"]
);

Client 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
    ...

Migrare un server MCP esistente

La CLI uap-migrate incapsula qualsiasi server MCP come una CapabilityCard UAP firmata in meno di 5 minuti. Idempotente — rieseguirla su un server già migrato non ha alcun effetto.

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

Firma della CapabilityCard

Nomi, descrizioni e schemi dei parametri degli strumenti fanno parte del payload firmato Ed25519. Mutare qualsiasi campo dopo la firma invalida la firma — sconfiggendo strutturalmente il tool-poisoning.

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..."

Variabili d'ambiente

Dipendenze principali

Contribuire

Naming dei branch: feat/<sprint>-<task>-<slug> — es. feat/s2-2.1-mtls-keycloak

Ogni modifica segue: branch → npx tsc --noEmit + npx vitest run in locale → commit → PR → squash merge → eliminazione del branch. Nessuna dipendenza dalla CI per lo sviluppo locale.

# 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 (schema + firma + RPC) → Sprint 2 (nucleo di sicurezza) → Sprint 3 (gateway + registry) → Sprint 4 (adattatori bridge) → Sprint 5 (SDK + immagine Docker).

UAP · Universal Agent Protocol · 2026

SPDX-License-Identifier: Apache-2.0