Extended cards and signatures

The planner holds a bearer token and reads the public card of deployer. That card carries a signature, and its extendedAgentCard flag says that an authenticated caller sees more.

When you finish this section, you can fetch an extended card, and sign and verify a card as the spec prescribes.

GetExtendedAgentCard

Extended card: the fuller card an agent returns to an authenticated caller through GetExtendedAgentCard, with more details or skills than the public card has.

The call needs credentials. The client must authenticate the request with one of the schemes that the public card declares in AgentCard.securitySchemes and AgentCard.security. That rule still names security, which 1.0 replaced with securityRequirements (conflict D6). PR #2046 fixed the §8.5 sample on main, and the §3.1.11 prose still says security.

Appendix A.2.2 calls the 0.3 flag supportsExtendedAgentCard, and the migration guide says supportsAuthenticatedExtendedCard (conflict D40). It gives the new flag field 5, and the proto uses 4 (conflict D7).

Figure 2.3 shows deployer refusing the call without a token, then returning the public card plus a second skill, without signatures.

### 2 · GetExtendedAgentCard: with a token
…
Authorization: Bearer dpl_test_7c1e4b
…
HTTP/1.1 200 OK
…
      {
        "id": "rollback",
        "name": "Roll back a deploy",
        "description": "Return staging to the previous build. Shown only to authenticated callers.",
        "tags": [
          "deploy",
          "rollback"
        ]
      }

A client should use the extended card in place of its cached public card. That holds for the rest of the authenticated session, or until the version of the card changes. Such a card should not hold sensitive information that an attacker could use after a leak. A declared flag with no card behind it answers ExtendedAgentCardNotConfiguredError, -32007.

The official SDKs leave the credential check to the host, and the table says who receives the card when the host adds nothing.

Signing a card

Card signature: an optional entry in signatures that holds a JSON Web Signature, as RFC 7515 defines it, over the card.

Each entry holds a base64url protected header and signature, and a verifier rebuilds the signed bytes from the received card under three rules:

1. Field presence. A field marked REQUIRED must always be present, even when its value is the default. A field with the optional keyword stays whenever it was set, and any other field at its default value is dropped.
2. RFC 8785. The JSON Canonicalization Scheme sorts object keys, fixes one form for each value, and removes whitespace.
3. No signatures. The signatures field must be left out of the signed content, because a signature cannot cover itself.

The protected header holds alg, typ, and kid, and the line for typ says SHOULD under a MUST heading (conflict D20). An optional jku points to a JSON Web Key Set with the public key.

To sign, join the base64url header and canonical payload with a period, and sign that input with the key that kid names.

# 1. canonical payload (RFC 8785): the card without signatures, keys sorted, no spaces
{"capabilities":{"extendedAgentCard":true,"streaming":true},…"version":"1.4.1"}

# 2. protected header, decoded
{"alg": "HS256", "typ": "JOSE", "kid": "deployer-key-1"}

# 3. JWS signing input: BASE64URL(header) '.' BASE64URL(payload)
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJkZXBsb3llci1rZXktMSJ9.eyJjYXBhYmlsaXRpZXMiOnsi…

# 4. the signature entry published in the card
{
  "protected": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJkZXBsb3llci1rZXktMSJ9",
  "signature": "yPk834ji_dOVmxElhzV3yTYBT9NVp8Bx1j5K0LQmOww"
}

# 5. verify the published card: True
# 6. verify after changing the description to name production: False

The kit signs with HS256, as the kit README lists. Real cards use ES256 or RS256, because an HMAC verifier holds the signing key.

Verifying a card

Verification has six MUST steps. They take a signature, fetch the public key by kid and jku or from a trusted store, and check it against the rebuilt payload.

Apply rule 1 when you rebuild. The signing and verifying steps both say to remove properties that have default values (conflict D21, open as issue #2249).

The kit's check passes on the published card and fails on a copy whose description names production, because the canonical bytes change. Figure 2.4 shows both checks.

A client should verify at least one signature before it trusts an Agent Card, and never with an expired or revoked key. Give your verifier an explicit list of allowed algorithms, as the reference SDK does, to prevent algorithm confusion attacks. Security requirements covers card spoofing.