Repository navigation
feat(a2a): store the Agent Card as fetched when registering an agent - #7378
Conversation
628d2b1 to
8ddb40f
Compare
8ddb40f to
4d50b55
Compare
| A2AAgentCard( | ||
| a2a_agent_id=agent.id, | ||
| version=(latest or 0) + 1, | ||
| card=fetched.raw_card, |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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) |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
4985033 to
b721c08
Compare
Lang-Akshay
left a comment
There was a problem hiding this comment.
| # | 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. |
|
@Lang-Akshay - Thank you for the review. Both findings are addressed. 1. Stored card visibility (CWE-200). I chose to document the behavior. The 2. Credentials sent to |
73e014d to
9b7535d
Compare
Lang-Akshay
left a comment
There was a problem hiding this comment.
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. |
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>
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>
da81083 to
bf47d40
Compare
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-cardcommit.What changed
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.0or0.3),etag,max_age, andfetched_at. The highestversionof an agent is its current card. Rows are deleted with their agent.POST /a2aaccepts an optionalcard_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-cardreturns the current stored card. It needsa2a.readand applies the same visibility check as the agent read. It returns 404 when the agent has no stored card.POST /a2a/fetch-cardalso returnsetagandmaxAge.a4c8e2f1b7d9creates the table. It is idempotent and has a downgrade.Design decisions
a2a_agents.nameremains the local display name. The card name stays inside the stored document, so a name collision never rewrites what the agent published.Security
a2a.readand agent visibility. Tests cover a caller withouta2a.readand an agent the caller cannot see.Not in this PR
PUT /a2a/{agent_id}.