Protocol Bindings

IDProva layers on top of existing agent communication protocols. This section defines how identities, DATs, and receipts are carried over each transport.

---

MCP Binding

IDProva integrates with the Model Context Protocol (MCP) for authenticated tool calls and resource access.

Session Establishment

When an MCP client connects, it presents its IDProva identity in the initialize request:

Step 1 — Client presents DAT:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "idprova": {
        "version": "0.1.0",
        "dat": "eyJhbGciOi..."
      }
    },
    "clientInfo": {
      "name": "kai-lead-agent",
      "version": "2.1.0"
    }
  }
}

Step 2 — Server validates the DAT:

1. Decode the JWS and verify the signature(s).
2. Resolve the issuer’s DID Document.
3. Verify the delegation chain.
4. Check that the sub claim matches the connecting client’s identity.
5. Extract scopes and constraints.

Step 3 — Server responds with acknowledgement:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "idprova": {
        "version": "0.1.0",
        "accepted": true,
        "effectiveScopes": [
          "mcp:tool:filesystem:read",
          "mcp:tool:filesystem:write"
        ],
        "trustLevel": "L1"
      }
    },
    "serverInfo": {
      "name": "secure-mcp-server",
      "version": "1.0.0"
    }
  }
}

Tool Call Authentication

Each tool call includes the DAT reference for per-call authorisation:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "readFile",
    "arguments": {
      "path": "/projects/idprova/README.md"
    },
    "_idprova": {
      "dat": "eyJhbGciOi...",
      "receiptRequested": true
    }
  }
}

The server validates:

1. The DAT grants the required scope (e.g., mcp:tool:filesystem:read).
2. Constraints are satisfied (rate limits, IP, time window).
3. If receiptRequested is true, generates an Action Receipt.

Response with Receipt:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# IDProva\n..."
      }
    ],
    "_idprova": {
      "receipt": {
        "id": "rcpt_01HQ3P9LYCD8ZH3ENQWT6G7F0U",
        "chain": {
          "previousHash": "blake3:7a8b...",
          "sequenceNumber": 42
        },
        "signature": "z4sK7q..."
      }
    }
  }
}

---

A2A Binding

IDProva integrates with the Agent-to-Agent (A2A) protocol for authenticated agent communication.

Agent Card Extension

The A2A Agent Card is extended with IDProva identity information:

{
  "name": "Kai Lead Agent",
  "description": "Primary orchestration agent",
  "url": "https://example.com/agents/kai",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "authentication": {
    "schemes": ["idprova-dat"]
  },
  "idprova": {
    "did": "did:idprova:example.com:kai-lead-agent",
    "trustLevel": "L1",
    "supportedAlgorithms": ["EdDSA", "MLDSA65"]
  }
}

Task Authentication

When sending a task to another agent, the sender includes its DAT:

{
  "jsonrpc": "2.0",
  "id": "task-001",
  "method": "tasks/send",
  "params": {
    "id": "task-001",
    "message": {
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Analyse the security report."
        }
      ]
    },
    "metadata": {
      "idprova": {
        "senderDID": "did:idprova:example.com:kai-lead-agent",
        "dat": "eyJhbGciOi...",
        "receiptRequested": true
      }
    }
  }
}

The receiving agent validates the DAT and checks that the a2a:task:execute scope (or a more specific scope) is granted.

---

HTTP Binding

For direct HTTP-based interactions, IDProva uses standard HTTP headers.

Request Headers

POST /api/v1/action HTTP/1.1
Host: agent.example.com
Content-Type: application/json
Authorization: IDProva eyJhbGciOi...
X-IDProva-DID: did:idprova:example.com:kai-lead-agent
X-IDProva-Receipt-Request: true

Header	Required	Description
Authorization	Yes	IDProva scheme followed by the DAT (JWS compact).
X-IDProva-DID	Yes	The agent’s DID. Must match the DAT’s sub claim.
X-IDProva-Receipt-Request	No	If true, the server returns an Action Receipt.

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-IDProva-Receipt: eyJpZCI6InJjcH...
X-IDProva-Trust-Level: L1

Header	Description
X-IDProva-Receipt	Base64url-encoded Action Receipt (if requested).
X-IDProva-Trust-Level	The server’s assessed trust level of the requesting agent.

Error Responses

IDProva-specific HTTP error codes:

Status	Code	Description
401	idprova:invalid-dat	DAT is malformed, expired, or signature invalid.
401	idprova:unknown-identity	DID could not be resolved.
403	idprova:insufficient-scope	DAT does not grant required scope.
403	idprova:constraint-violation	A DAT constraint was violated (rate limit, IP, etc.).
403	idprova:trust-level-insufficient	Agent’s trust level is below the required minimum.
403	idprova:config-mismatch	Agent’s config attestation does not match.
403	idprova:delegation-revoked	The DAT or a parent in its chain has been revoked.

---

Custom Bindings

Implementers can create custom bindings for other transport protocols. A valid IDProva binding MUST:

1. Carry the DAT — Provide a mechanism to transmit the JWS-encoded DAT from client to server.
2. Carry the agent DID — Transmit the agent’s DID so the server can correlate it with the DAT’s sub claim.
3. Support receipt requests — Provide a signal for the client to request an Action Receipt.
4. Return receipts — Provide a mechanism to return Action Receipts in responses.
5. Define error semantics — Map IDProva error conditions to the transport’s error model.

---

Next Steps

• AID Format & DID Method — DID Document structure
• DAT Structure & Scopes — Token format carried over bindings
• Action Receipts — Receipt format returned in responses