Skip to content

feat(a2a): store the Agent Card as fetched when registering an agent - #7378

Merged
Lang-Akshay merged 9 commits into
mainfrom
4734-a2a-agent-card-storage
Nov 16, 2026
Merged

Lang-Akshay merged 9 commits into
mainfrom
4734-a2a-agent-card-storage

Conversation

@marekdano

Copy link
Copy Markdown
Collaborator

Summary

Slice 2 of #4734. Stores an A2A Agent Card as fetched, separate from the deployment settings of the agent. This is the storage that re-sync and drift reporting (slice 3) will compare against.

Refs #4734

Depends on #7377. Review the commits after the POST /a2a/fetch-card commit.

What changed

  • New table a2a_agent_cards, with one row per fetched card version. Each row holds the card document as fetched, the source URL, the detected card version (1.0 or 0.3), etag, max_age, and fetched_at. The highest version of an agent is its current card. Rows are deleted with their agent.
  • POST /a2a accepts an optional card_url. The gateway fetches the card itself and stores it as version 1. The fetch happens before any write, so a missing card fails the registration with 400 and creates nothing.
  • GET /a2a/{agent_id}/stored-card returns the current stored card. It needs a2a.read and applies the same visibility check as the agent read. It returns 404 when the agent has no stored card.
  • POST /a2a/fetch-card also returns etag and maxAge.
  • Alembic revision a4c8e2f1b7d9 creates the table. It is idempotent and has a downgrade.

Design decisions

  • Separate table, not columns. The stored document keeps fields ContextForge does not model, so a later re-sync can compare the whole card.
  • One row per version. A drift report can then show more than the previous version.
  • Local name and card name stay apart. a2a_agents.name remains the local display name. The card name stays inside the stored document, so a name collision never rewrites what the agent published.
  • The server fetches the card. A card document sent by the client is never accepted. A test asserts that the create schema has no such field.
  • A failed card store does not undo the agent. The agent commits first. A storage error is logged.

Security

Not in this PR

  • Linking a hand-registered agent to a card later.
  • Updating a card through PUT /a2a/{agent_id}.
  • Showing the stored card in the agent read model.
  • Re-sync, drift reporting, and the confirmation gate (slice 3).

@marekdano marekdano self-assigned this Oct 29, 2026
@marekdano
marekdano force-pushed the 4734-a2a-agent-card-storage branch 2 times, most recently from 628d2b1 to 8ddb40f Compare October 30, 2026 14:57
@marekdano
marekdano force-pushed the 4734-a2a-agent-card-storage branch from 8ddb40f to 4d50b55 Compare November 12, 2026 11:28
@marekdano
marekdano marked this pull request as ready for review November 12, 2026 11:28
Comment thread mcpgateway/services/a2a_service.py Outdated
A2AAgentCard(
a2a_agent_id=agent.id,
version=(latest or 0) + 1,
card=fetched.raw_card,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this writes card=fetched.raw_card. But [a2a_card_import.py:738] sets raw_card to None whenever the card is already 1.0 format, which is the current spec. SQLAlchemy's JSON type serializes Python None as the literal null, so the non-nullable column does not reject it and the row commits with no document. A later GET ``/a2a/{id}/stored-card fails pydantic validation on card, which the route does not catch, so the client gets 500. Only legacy 0.3 cards store correctly.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. You are right: _build_found_response sets raw_card to None for a card already in the 1.0 shape, and _store_agent_card wrote that value. The row held JSON null, so the stored-card route would fail validation.

"""Build a successful fetch result."""
values = dict(found=True, outcome="found", source_url="https://agent.example.com/.well-known/agent-card.json", detected_version="1.0", card=RAW_CARD, raw_card=RAW_CARD, etag='"v1"', max_age=300)
values.update(overrides)
return A2AFetchCardResponse(**values)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hardcodes a fetch result with raw_card populated for a 1.0 card, a shape the fetcher never emits. The registration test mocks the store helper and only asserts it was called. Build the fixture from the real _build_found_response and assert on the row written to the in-memory DB.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed! _fetched() now builds its result with the real _build_found_response, from a 1.0 card and a 0.3 card. A 1.0 card gives raw_card=None, as the fetcher does.

@madhu-mohan-jaishankar madhu-mohan-jaishankar left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@Lang-Akshay Lang-Akshay left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

# Area File Line Non-blocking observation Suggested improvement
1 Security (Medium, CWE-200) mcpgateway/services/a2a_service.py 1127–1155, 1185–1208 A card fetched with the registrant's credentials is stored whole and served by GET /a2a/{id}/stored-card to any caller with a2a.read who can see the agent. For a team or public agent, a credential-gated card (the case #4734 designs for) becomes readable by every viewer. Decide explicitly: restrict stored-card to owner / a2a.update when the card needed credentials, or document that stored cards are readable by all viewers.
2 Security (Medium, CWE-522) mcpgateway/services/a2a_service.py 1146–1150 basic / bearer / authheaders registration credentials go to the card_url host with no same-origin check against endpoint_url. A mistyped or hostile card_url receives the credential. The outbound policy and no-redirect rule limit the reach, and the CHANGELOG documents the behavior. Forward credentials only when card_url shares an origin with endpoint_url, or require an explicit opt-in.

@marekdano

Copy link
Copy Markdown
Collaborator Author

@Lang-Akshay - Thank you for the review. Both findings are addressed.

1. Stored card visibility (CWE-200). I chose to document the behavior. The stored-card route returns the card to every caller with a2a.read who can see the agent. This includes a card fetched with credentials. The new "Stored Agent Cards" section in docs/docs/using/agents/a2a.md, the CHANGELOG entry, and the route docstring state this. The docs advise private visibility for a confidential card. A restriction needs a fetched_with_credentials column and a migration change. I left it out of this slice and can track it in a follow-up issue if you want it.

2. Credentials sent to card_url (CWE-522). _fetch_registration_card() now takes endpoint_url. It sends basic, bearer, and authheaders credentials only when card_url has the same scheme, host, and port as endpoint_url. On another origin, the card is fetched without credentials. A keyed card then fails with the "requires credentials" error. A new test checks that the credential is withheld from another origin.

@marekdano
marekdano force-pushed the 4734-a2a-agent-card-storage branch from 73e014d to 9b7535d Compare November 13, 2026 11:16

@Lang-Akshay Lang-Akshay left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking Changes

# Area File Line Blocking reason Required change
1 Security (High, CWE-436 / CWE-522 / CWE-918) mcpgateway/services/a2a_service.py 402–424, 1235–1238 _same_origin() parses the raw card_url with urllib.parse.urlparse. The fetch then uses A2AFetchCardRequest.base_url (AnyHttpUrl, WHATWG rules). The parsers disagree on a backslash. Verified: for https://evil.example\@a.example.com/card.json, urlparse(...).hostname is a.example.com (check passes against endpoint https://a.example.com/rpc), while AnyHttpUrl normalises it to https://evil.example/@a.example.com/card.json with host evil.example. The basic/bearer/authheaders credentials then go to evil.example. The origin-only credential control, which resolves the earlier CWE-522 review finding and is documented in docs/docs/using/agents/a2a.md and CHANGELOG.md, does not hold. Validate card_url through A2AFetchCardRequest first. Compare scheme, host, and port of the normalised base_url with the normalised endpoint_url. Then pass the same normalised URL to fetch_agent_card. Add a deny-path regression test for the \@ form.

Lang-Akshay
Lang-Akshay previously approved these changes Nov 13, 2026

@Lang-Akshay Lang-Akshay left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM ✅

Refs #4734 (slice 2: card storage).

Add the a2a_agent_cards table. Store the Agent Card exactly as fetched,
separate from the deployment settings on a2a_agents.

  - Add one row per fetched card version. Keep the source URL, detected
    card version, ETag, Cache-Control max-age, and fetch time.
  - Accept an optional card_url on POST /a2a. Fetch the card on the
    server before any write. Fail the registration when no card is found.
    Never accept a card document from the client.
  - Add GET /a2a/{agent_id}/stored-card. It returns the current stored
    card and applies the same visibility check as the agent read.
  - Return etag and maxAge from POST /a2a/fetch-card.
  - Add Alembic revision a4c8e2f1b7d9 for the new table.

Registration without card_url is unchanged.

Signed-off-by: Marek Dano <mk.dano@gmail.com>
  POST /a2a with card_url fetched the card without headers. An agent that
  publishes its card behind a key could not register.

  - Send the basic, bearer, or authheaders credentials of the registration
    to the card URL.
  - Validate the headers with A2AFetchCardRequest. A Host override or
    header injection is rejected before the fetch.
  - Raise a specific error for the auth_required, unreachable, and no_card
    outcomes of fetch_agent_card.
  - Add etag and max_age to CardResponse after the challenge field. The
    field order keeps the slice 1 tests valid.

Signed-off-by: Marek Dano <mk.dano@gmail.com>
Signed-off-by: Marek Dano <mk.dano@gmail.com>
…istration

Signed-off-by: Marek Dano <mk.dano@gmail.com>
- Store `card` when `raw_card` is `None`. A card already in the 1.0 shape
  has no separate raw copy. The row held JSON `null` and the stored-card
  route failed validation.
- Build the storage test fixtures with `_build_found_response`, and write
  the registration test to an in-memory database.
- Point `down_revision` at the new head `4a7d9e2c6b18`.

Signed-off-by: Marek Dano <mk.dano@gmail.com>
  Send registration credentials to `card_url` only when it shares scheme,
  host, and port with `endpoint_url`. A card URL on another origin is
  fetched without credentials.

  Document that `GET /a2a/{agent_id}/stored-card` returns the card to
  every caller with `a2a.read` who can see the agent, including a card
  fetched with credentials.

Signed-off-by: Marek Dano <mk.dano@gmail.com>
  `_same_origin()` parsed `card_url` with `urlparse`, while the card fetch
  parses it as `AnyHttpUrl`. The parsers disagree on a backslash: for
  `https://evil.example\@a.example.com/card.json`, `urlparse` reports host
  `a.example.com` and `AnyHttpUrl` reports host `evil.example`. The origin
  check passed and the credentials went to `evil.example`.

  Validate `card_url` through `A2AFetchCardRequest` first. Compare scheme,
  host, and port of the normalized `base_url` with the parsed
  `endpoint_url`. Build the fetch request from the same normalized URL.

  Add deny-path tests for the backslash form, another port, and another
  scheme.

Signed-off-by: Marek Dano <mk.dano@gmail.com>
Signed-off-by: Marek Dano <mk.dano@gmail.com>
@Lang-Akshay
Lang-Akshay added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit b2bc747 Nov 16, 2026
41 checks passed
@Lang-Akshay
Lang-Akshay deleted the 4734-a2a-agent-card-storage branch November 16, 2026 17:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants