Signed Agent Cards: preventing poisoning with JWS

Why unsigned cards are vulnerable

In the A2A protocol specification, discovery is designed to be lightweight, static, and unauthenticated: a client agent performs a simple HTTP GET request to /.well-known/agent-card.json.

While this simplicity enabled rapid ecosystem adoption, it exposes an attack surface that you can call Agent Card poisoning:

1. Endpoint Redirection: An attacker who compromises a DNS entry or an edge proxy can rewrite the supportedInterfaces[].url field, silently sending sensitive prompt payloads to an eavesdropping or impersonation server.
2. Capability & Prompt Injection: By tampering with the skills array or description fields, malicious actors can deceive calling agents into delegating high-privilege financial or administrative tasks to an unvetted model.
3. Identity Spoofing: Without cryptographic verification, anyone can host an agent card claiming that provider.organization is an established financial institution or software vendor.

To defend multi-agent architectures against these risks, the specification maintained in the a2aproject/A2A repository lets a card carry a signatures array of RFC 7515: JSON Web Signature (JWS) objects (spec section 8.4).

Anatomy of the signatures array

In an A2A v1.0 Agent Card, the top-level signatures property holds an array of AgentCardSignature objects. Several entries are allowed, which is how key rotation works: during a rotation a card carries one signature from the old key and one from the new.

{
  "name": "Treasury Reconciliation Agent",
  "version": "1.2.0",
  "supportedInterfaces": [
    {
      "url": "https://agents.acme-finance.com/a2a/v1",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "signatures": [
    {
      "protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vYWNtZS1maW5hbmNlLmNvbS8ud2VsbC1rbm93bi9qd2tzLmpzb24ifQ",
      "signature": "QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ"
    }
  ]
}

Each entry has the fields of a flattened JWS, and nothing else is required:

• protected (required): A Base64URL-encoded JSON object holding the JWS protected header. It must contain:

  • alg: The signing algorithm, such as ES256 or RS256.
  • kid: The key ID, which identifies the signing key.
  • typ: Should be set to JOSE.

  It may also contain jku, the URL of the JSON Web Key Set that holds the public key. The example above decodes to {"alg":"ES256","typ":"JOSE","kid":"key-1","jku":"https://acme-finance.com/.well-known/jwks.json"}.

• signature (required): The Base64URL-encoded signature value.

• header (optional): A JSON object of unprotected header parameters, not Base64URL-encoded.

Signing an agent-card.json with ES256

What is signed is not the file as served but its canonical form. Per section 8.4.1 of the specification, you:

1. Remove the signatures field itself, to avoid a circular dependency.
2. Respect Protocol Buffer field presence: drop fields that hold a default value (an empty array, an empty string) unless they are required or explicitly set optional fields.
3. Canonicalize the result with the JSON Canonicalization Scheme (RFC 8785): object keys sorted, no insignificant whitespace.

The JWS signing input is then BASE64URL(protected header) + "." + BASE64URL(canonical card). Here is a Node.js version that follows those steps with no dependencies. Sorting keys and JSON.stringify is enough to produce the RFC 8785 form for ordinary cards; reach for a vetted JCS library if yours carries exotic numbers.

import crypto from 'node:crypto';
import fs from 'node:fs';

// RFC 8785 (JCS): keys sorted by UTF-16 code units, no whitespace. JSON.stringify
// already serializes strings and numbers the way JCS requires.
const canonicalize = value =>
  Array.isArray(value)
    ? `[${value.map(canonicalize).join(',')}]`
    : value !== null && typeof value === 'object'
      ? `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonicalize(value[key])}`).join(',')}}`
      : JSON.stringify(value);

// 1. Read the card and drop any existing signatures.
const card = JSON.parse(fs.readFileSync('agent-card.json', 'utf8'));
const { signatures, ...unsigned } = card;

// 2. Build the JWS protected header: alg, typ and kid are required.
const header = {
  alg: 'ES256',
  typ: 'JOSE',
  kid: 'key-1',
  jku: 'https://acme-finance.com/.well-known/jwks.json'
};
const protectedB64 = Buffer.from(JSON.stringify(header)).toString('base64url');
const payloadB64 = Buffer.from(canonicalize(unsigned)).toString('base64url');

// 3. Sign with your P-256 private key. A JWS ES256 signature is the raw R||S
//    pair (RFC 7518 section 3.4), not Node's default DER encoding.
const signature = crypto.sign('sha256', Buffer.from(`${protectedB64}.${payloadB64}`), {
  key: fs.readFileSync('private-key.pem'),
  dsaEncoding: 'ieee-p1363'
}).toString('base64url');

// 4. Attach the signature to the card.
const signedCard = { ...unsigned, signatures: [{ protected: protectedB64, signature }] };
fs.writeFileSync('agent-card.signed.json', JSON.stringify(signedCard, null, 2));
console.log('Agent Card signed with ES256');

How client agents verify signatures

When a client agent retrieves an Agent Card from an unvetted peer, verification should happen before it inspects capabilities or invokes interfaces. Section 8.4.3 of the specification gives the steps:

1. Extraction: Take a signature from the signatures array. If there is none, treat the card as unverified, or reject it, according to your security policy.
2. Key retrieval: Fetch the public key named by kid, from the JWKS at jku or from a trusted key store of known providers.
3. Rebuild the payload: Remove default-valued properties and the signatures field from the received card, then canonicalize it with RFC 8785.
4. Verify: Check the signature over BASE64URL(protected) + "." + BASE64URL(canonical card) with the public key.

Beyond the mechanics, the specification is explicit about trust: clients SHOULD verify at least one signature before trusting a card, public keys SHOULD be fetched over HTTPS, and expired or revoked keys MUST NOT be used. Multiple signatures are allowed so that rotation does not break verification.

Two policies are worth adding on top, even though the specification does not require them: reject algorithms below your security baseline (always none, and symmetric ones), and check that the key's origin matches the provider.url the card declares, so that a signature from one organization cannot vouch for another's name.

Key rotation and security checklist

Follow these operational guidelines when managing signed Agent Cards in production:

• Decouple Key Lifecycle from Deployments: Name keys with kid and publish them in a JWKS (/.well-known/jwks.json) that jku points at, rather than hardcoding static keys. To rotate, add the new key to the JWKS, sign with both keys for a while, then retire the old one.
• Re-sign on every change: The signature covers the whole card. Make signing a build step, so the version bump and the new signature ship together.
• Enforce HTTPS Everywhere: Every interface listed under supportedInterfaces and every key endpoint must be served over HTTPS with a valid certificate.
• Bind Domain to Provider: Keep the domain that hosts the Agent Card, the provider.url, and the origin of the JWKS aligned.
• Pre-flight Audit: Run your completed card through the validator before publishing it to your public root, and replace any scaffold signature the generator emitted.