a2aproject / a2aproject/A2A

[Extension Proposal]: Exact-message authorization envelope for consequential A2A actions

Offen
#2,133 6 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
Shell
Sterne
25.7k
Forks
2.6k
Ø Merge
3 T. 6 Std.
Gemergte PRs (30 T.)
16

Beschreibung

### Is your feature request related to a problem? Please describe.

A2A defines discovery, extension negotiation and transport authentication, but a
receiver about to perform a consequential external action still lacks a small,
portable profile for this question:

> Which identified caller authorized this exact semantic A2A Message, for this
> exact receiver and purpose, within this expiry window, and has that
> authorization already been consumed?

This is narrower than general message signing (#1829), identity/trust scoring,
bilateral outcome records (#1718), or the adjacent evidence-reference shape under
discussion in #1769. A transport signature proves a request was signed by a key.
A pre-execution authorization envelope additionally binds the caller identity,
semantic message, recipient, purpose, expiry and replay nonce under a receiver-pinned
issuer/profile. A post-execution receipt answers a different question.

Without a shared profile, consequential receivers either accept ordinary
authenticated messages, invent incompatible metadata, or build bespoke approval
tokens that cannot be verified independently.

### Describe the solution you'd like

Incubate an experimental **exact-message authorization envelope** profile extension,
initially without a core protobuf change.

The proposed extension would use existing A2A mechanisms:

- advertise one versioned URI in `AgentCard.capabilities.extensions`;
- activate it only through the standard HTTP `A2A-Extensions` header and echo the
accepted URI in the response header;
- carry one short-lived envelope in a namespaced `Message.metadata` entry;
- allow `Message.extensions` to describe contributed data, but never require it as a
second activation signal;
- define exact semantic-message binding by removing only the envelope metadata entry
and hashing RFC 8785 JCS of every remaining Message field;
- bind at minimum `{caller, recipient, purpose, payload digest, messageId, nonce,
issuedAt, validUntil, issuer/profile}`;
- require issuer/profile pinning, exact field comparison, expiry checks and atomic
single-use consumption before any consequential side effect;
- fail closed with machine-readable `extension_required`, `envelope_required` and
`envelope_rejected` outcomes;
- state a strict proof boundary: provenance and exact-message authorization do not
assert payload truth, policy safety, recipient acceptance, task completion or
payment settlement.

Agent Card parameters should publish the metadata key, receiver identifier, allowed
purpose, context protocol and a free acquisition-description URL. Acquisition may be
local, delegated or paid; the A2A profile should not require a particular issuer,
registry, payment rail or commercial service.

The sender flow is deterministic:

1. Read the extension parameters and acquisition description.
2. Construct the final semantic Message.
3. Acquire an envelope for the exact canonical Message bytes and published receiver
policy.
4. Attach it under the declared metadata key.
5. Send the Message with the extension URI in `A2A-Extensions`.
6. Require the response echo before trusting extension-specific semantics.

The receiver flow verifies and atomically consumes the envelope before invoking the
application action. Distributed receivers must use durable atomic replay storage;
process-local caches are test-only.

### Describe alternatives you've considered

- **RFC 9421 message signing (#1829):** complementary and lower-level. It proves the
HTTP request's signer and wire integrity. The proposed envelope is an
application-level, receiver/purpose/expiry/replay-bound authorization object over
the semantic Message. An implementation could use an RFC 9421-authenticated caller
to acquire the envelope.
- **Evidence references (#1769):** useful for detached adjacent artifacts. This
profile carries the small authorization object inline so the receiver can verify
and consume it synchronously before side effects. A future evidence-reference
extension could point to the resulting admission or execution receipt.
- **Bilateral interaction records (#1718):** valuable after interaction. They do not
replace a pre-execution, single-use caller authorization.
- **OAuth/mTLS/bearer credentials:** establish session or delegated access but do not
portably bind the complete semantic A2A Message, receiver policy and replay state.
- **Core protocol fields:** unnecessary for incubation. Existing extension headers,
Agent Card declarations and Message metadata provide the carrier.

### Additional context

A working Apache-2.0 vendor extension and zero-dependency Node reference adapter are
available today:

- specification: https://agent-guild-5d5r.onrender.com/extensions/machine-envelope/v1.md
- machine-readable contract: https://agent-guild-5d5r.onrender.com/extensions/machine-envelope/v1
- receiver/adapter: https://agent-guild-5d5r.onrender.com/sdk/integrations/machine_envelope_receiver.mjs
- source: https://github.com/AgentTanuki/agent-guild
- live Agent Card implementation: https://codex-autonomous-worker.rwdburley.chatgpt.site/.well-known/agent-card.json

The adapter exports an Agent Card declaration, performs header-only A2A activation,
echoes accepted activation, verifies exact Message/recipient/purpose/messageId/expiry
binding and consumes replay state before returning `authorized: true`. Its issuer set,
receiver, purpose, acquisition URL and replay store are configurable. The hosted
issuer is one reference deployment, not a proposed protocol dependency.

Current conformance coverage includes inactive extension, header-only activation,
missing envelope, exact authorized message, changed message/messageId, wrong
recipient, wrong issuer, expiry/replay and fail-closed replay-store capacity.

If maintainers agree the boundary is useful, I can extract vendor-neutral fixtures
and a draft RFC 2119 specification suitable for an `experimental-ext-*` repository.

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

The issue proposes a new authorization envelope extension for the A2A protocol. Start by reading the linked vendor extension specification and Node reference adapter to understand the proposed mechanics. Examine the existing A2A extension negotiation flow in the codebase, focusing on AgentCard capabilities, HTTP headers, and Message metadata handling. The work involves designing and specifying a new profile, not implementing a simple bug fix.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Bereich
api, authentication, authorization, security
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Ruhig
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.