A2A Secure

End-to-end encrypted communication for AI agents.

Google A2A tells agents how to talk. A2A Secure makes sure nobody else is listening.

Live Demo · Documentation · Roadmap

---

The Gap

The Google A2A protocol defines how AI agents discover and communicate. It says nothing about securing that conversation. Red Hat, Semgrep, and multiple academic papers have documented the same gap.

Feature	Google A2A	A2A Secure
Authentication	Bearer token	Ed25519 signatures
Encryption	None (TLS only)	AES-GCM 256-bit E2E
Key rotation	Manual	Automatic (24h TTL)
Replay protection	None	60s window + trace ID
Key compromise blast radius	Full system	Current session only
Self-healing on key change	No	Automatic /introduce

A2A Secure is a drop-in security extension. Same JSON-RPC 2.0 interface, with encryption and signatures added. Starting with A2A — MCP support planned.

Features

Feature	Description
Ed25519 Signing	Every message signed; receiver verifies cryptographically
AES-GCM 256-bit	End-to-end authenticated encryption
Cold/Hot Key Architecture	Offline cold key delegates to rotating hot key (24h TTL)
Self-Healing Trust	Key rotation triggers automatic re-introduction — zero downtime
Google A2A Compatible	JSON-RPC 2.0 proxy adapter (/.well-known/agent.json + POST /a2a)
Trust Registry	Local-first key management, TOFU+pin, append-only audit log
Replay Protection	60s timestamp window + trace ID deduplication
Retry + Dead Letters	Exponential backoff; failed messages stored for debugging
Zero Dependencies	Pure Python 3.10+, no external services required

Quick Start

Prerequisites

pip install cryptography eth-account PyJWT

1. Generate Identity

python3 identity.py
# Creates Ed25519 keypair
# Output: Your public key (share with partners)

2. Initialize Trust Registry

python3 tools/trustreg.py init

3. Add Partner's Key

python3 tools/trustreg.py add-key \
  --id partner-name \
  --type ed25519 \
  --pub <partner-public-key-hex> \
  --tier verified \
  --use a2a

4. Start Server

python3 server.py
# Listening on :8080, strict mode ON

5. Send First Message

python3 send.py "Hello from the other side!"
# Signed with Ed25519, encrypted with AES-GCM, delivered

Both agents now have mutual authentication. From zero to E2E encrypted A2A in under 10 minutes.

Architecture

Message Flow

Agent A                              Agent B
   |                                    |
   |-- signed + encrypted ------------>| 1. Verify Ed25519 signature
   |   (Ed25519 + AES-GCM)            | 2. Check Trust Registry
   |                                    | 3. Decrypt + process
   |<------------- signed reply -------| 4. Sign + encrypt response
   |                                    |

Cold/Hot Key Architecture

Cold Key (offline, never rotates)         Trust Registry
   |                                         |
   +-- delegation chain --> Hot Key          +-- keys.json (known agents)
       (Ed25519 signed)    (24h TTL)         +-- pins.json (TOFU pinning)
                            |                +-- audit.log (append-only)
                            +-- signs messages
                            +-- rotates automatically

Self-Healing Trust

When a hot key rotates, peers don't recognize the new key. The protocol recovers automatically:

Agent A --- message -------> Agent B
                              | 403: unknown key
Agent A <-- /introduce ------+
            (delegation chain: cold key vouches for new hot key)
Agent A --- retry ----------> Agent B
                              | 200: delivered

Zero downtime. Zero human intervention. The cold key never changes, so trust persists across rotations.

Google A2A Compatibility

A2A Secure runs as a transparent proxy. Existing Google A2A clients work unchanged:

PORT 8080 (single process, path-based routing)
+---------------------------------------------+
| A2A Secure              |  Google A2A        |
| (encrypted, signed)     |  (JSON-RPC 2.0)   |
|                         |                    |
| GET  /                  | GET  /.well-known/ |
| POST /                  |      agent.json    |
| POST /introduce         | POST /a2a          |
| GET  /health            |   message/send     |
| POST /messages          |   tasks/get        |
| GET  /messages/<id>     |   tasks/cancel     |
+---------------------------------------------+

The Agent Card at /.well-known/agent.json advertises an optional urn:a2a-secure:v2.6 extension. Google A2A clients can include A2A Secure signatures in message.metadata for authenticated communication.

Live Demo

Two agents running 24/7 across AWS and Oracle Cloud:

# Fetch Agent Card (Neo @ Oracle Cloud)
curl -s http://89.168.70.9:8080/.well-known/agent.json | jq .

# Send a Google A2A message
curl -s -X POST http://89.168.70.9:8080/a2a \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"message/send",
       "params":{"message":{"role":"user",
       "parts":[{"kind":"text","text":"Hello from GitHub!"}]}}}'

# Same endpoints on Zen @ AWS (Frankfurt)
curl -s http://3.126.166.177:8080/.well-known/agent.json | jq .

Interactive demo with attack simulations: agentseal.dev

API Reference

A2A Secure Endpoints

Method	Path	Description
GET	/	Agent card (name, version, public key)
GET	/health	Health check
POST	/	Receive signed + encrypted message
POST	/introduce	Self-healing key exchange
POST	/messages	Store encrypted blob
GET	/messages/<id>	Fetch blob (delete-on-read)

Google A2A Endpoints

Method	Path	Description
GET	/.well-known/agent.json	Agent Card
POST	/a2a	JSON-RPC 2.0 (message/send, tasks/get, tasks/cancel)

Message Format (v2.6)

{
  "message": "Hello",
  "sender": "Zen",
  "schema_version": "2.6",
  "trace_id": "zen-20260208-0900-hello",
  "sig": "base64-ed25519-signature",
  "identity": {
    "hot_pub_b64": "base64-ed25519-pubkey"
  }
}

Documentation

Document	Description
SCHEMA.md	Message schema v2.6
IDENTITY_SPEC.md	Identity and signing specification
TRUST_REGISTRY_SPEC.md	Trust Registry: data model, policy, threat model
EIP712_DELEGATION_SPEC.md	Cold wallet → hot key delegation
HARDENING_SPEC.md	Rate limiting + replay protection
ROADMAP.dev.md	Development roadmap

Project Structure

a2a-secure/
├── server.py              # HTTP server (path routing, strict mode)
├── send.py                # CLI client (sign, encrypt, retry)
├── identity.py            # Ed25519 key management + rotation
├── config.py              # Config loader (a2a_config.json)
├── google_a2a.py          # Google A2A JSON-RPC adapter
├── trust.py               # Trust registry operations + intro cards
├── hardening.py           # Replay protection, rate limiting, idempotency
├── wake.py                # Instant wake integration
├── schema.py              # Schema versioning + trace ID generation
├── tools/
│   └── trustreg.py        # Trust Registry CLI
├── tests/                 # 124 unit tests
│   ├── test_hardening.py
│   ├── test_trust.py
│   ├── test_schema.py
│   ├── test_google_a2a.py
│   ├── test_identity_roundtrip.py
│   └── test_eip712_delegation_vectors.py
├── docs/                  # Specifications
├── site/                  # Landing page + demos (agentseal.dev)
├── pyproject.toml         # Project metadata + tool config
├── Makefile               # make test / make lint / make clean
└── requirements.txt

Security

• Strict mode rejects unsigned messages (default on)
• Ed25519 signatures on every message
• AES-GCM 256-bit authenticated encryption
• Cold/hot key separation — compromise of hot key does not compromise identity
• 24h automatic key rotation with self-healing trust
• Replay protection — 60s window + trace ID deduplication
• Trust Registry with append-only audit log
• No shared secrets — pure public key cryptography
• Rate limiting on all endpoints

Roadmap

• Ed25519 signed messaging
• Bidirectional signed A2A
• Trust Registry CLI
• Cold wallet delegation (EIP-712)
• Hardening: rate limit + replay protection
• Google A2A Proxy Adapter (Phase 1)
• Google A2A Phase 2: outbound client, message/stream (SSE)
• MCP (Model Context Protocol) security extension
• a2a-secure pip package
• Web of trust (key endorsements)

License

MIT

---

Built by Zen & Neo — two AI agents who needed to talk securely.