docs: add authorization, delegation & audit evidence extension proposal#1583
docs: add authorization, delegation & audit evidence extension proposal#1583knuckles-stack wants to merge 1 commit intoa2aproject:mainfrom
Conversation
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a comprehensive extension to the A2A protocol, addressing critical gaps in authorization, delegation, and auditability for multi-agent systems. It provides a robust framework for managing agent permissions, enabling secure multi-hop delegation, and ensuring transparent, verifiable records of agent activities, all while maintaining backward compatibility and supporting incremental adoption. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
knuckles-stack
changed the title
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive and well-structured proposal for adding authorization, delegation, and audit evidence capabilities to the A2A protocol as an extension. The proposal is thorough and covers many important aspects. My review includes suggestions to improve clarity, fix minor bugs in the pseudocode, ensure consistency with protocol conventions, and enhance the completeness of examples.
Note: Security Review has been skipped due to the limited scope of the PR.
| matched = true | ||
| else if req starts with g + ".": | ||
| matched = true // g is a parent scope | ||
| else if g ends with ".*" and req starts with g[:-2]: |
There was a problem hiding this comment.
The wildcard matching logic req starts with g[:-2] appears to be incorrect for the described behavior. If g is trade.*, g[:-2] would be trade. A check like req.startswith('trade') would incorrectly match scopes like trade-report which are not sub-scopes. The logic should check if req starts with the prefix of g before the .*, which is trade.. In Python-like slicing, this would be g[:-1].
| else if g ends with ".*" and req starts with g[:-2]: | |
| else if g ends with ".*" and req starts with g[:-1]: |
| return VerificationResult( | ||
| valid: true, | ||
| chain_length: len(chain), | ||
| effective_scopes: chain[last].scopes, |
There was a problem hiding this comment.
The variable last is used here but is not defined in the pseudocode. To get the scopes of the final link in the chain, you should reference the last element directly, for example using chain[-1].scopes (in Python-like syntax) or chain[len(chain) - 1].scopes.
| effective_scopes: chain[last].scopes, | |
| effective_scopes: chain[-1].scopes, |
| score = score - 0.5 | ||
|
|
||
| // Penalty 2: Outcome failures (up to -0.4) | ||
| outcomes = [r for r in records where r.outcome_status is not null] |
There was a problem hiding this comment.
The outcomes list includes all records where outcome_status is not null, which includes "PENDING". The failure rate calculation then treats pending outcomes as failures. It would be more accurate to exclude records with a "PENDING" status from the trust score calculation until they reach a terminal state (ACHIEVED, FAILED, or PARTIAL). You could filter the outcomes list to exclude the "PENDING" status.
| | `timestamp_utc` | `string` (ISO 8601) | Yes | When the action occurred, in UTC. | | ||
| | `prev_record_hash` | `string` (hex) | Yes | SHA-256 hash of the previous record (or `"0"*64` for the first record). | | ||
| | `record_hash` | `string` (hex) | Yes | SHA-256 hash of this record (see Section 7.2). | | ||
| | `signature` | `string` (base64url) | No | Cryptographic signature over the record. | |
There was a problem hiding this comment.
The description for signature states it is a "Cryptographic signature over the record." However, the verification pseudocode in section 7.3 (verify_signature(..., expected_hash, ...) on line 587) indicates the signature is computed over the record_hash. This is a significant ambiguity. Please clarify the description to match the verification logic, for example, by stating it's a "Cryptographic signature over the record_hash."
| | `signature` | `string` (base64url) | No | Cryptographic signature over the record. | | |
| | `signature` | `string` (base64url) | No | Cryptographic signature over the `record_hash`. | |
|
|
||
| | Field | Type | Required | Description | | ||
| |-------|------|----------|-------------| | ||
| | `authorization_model` | `string` | Yes | One of `"capability"`, `"role"`, or `"attribute"`. | |
There was a problem hiding this comment.
The values for authorization_model ("capability", "role", "attribute") should be in SCREAMING_SNAKE_CASE (e.g., "CAPABILITY") to align with the A2A protocol's convention for enum values, as specified in the general rules. This change should be applied consistently throughout the document, including in the example on line 110 and the descriptions on lines 138-145.
| | `authorization_model` | `string` | Yes | One of `"capability"`, `"role"`, or `"attribute"`. | | |
| | `authorization_model` | `string` | Yes | One of `"CAPABILITY"`, `"ROLE"`, or `"ATTRIBUTE"`. | |
References
- Enum values in the A2A protocol should be in
SCREAMING_SNAKE_CASEto comply with the ProtoJSON specification.
| if len(chain) > max_delegation_depth: | ||
| return VerificationResult( | ||
| valid: false, | ||
| failure_point: i, | ||
| reason: "exceeds_max_depth" | ||
| ) |
There was a problem hiding this comment.
The chain depth check is performed on every iteration within the loop. For efficiency, it's better to perform this check once before the loop starts.
| | | |-- delegation(B->C, | | ||
| | | | narrowed scopes) | |
There was a problem hiding this comment.
There's a minor formatting issue in the ASCII art for the delegated authorization flow. The line for the delegation(B->C) is broken across two lines and misaligned, which affects readability.
| | | |-- delegation(B->C, | | |
| | | | narrowed scopes) | | |
| | | |-- delegation(B->C, narrowed scopes) -->| |
| 1. The orchestration agent evaluates each vendor agent's trust score. | ||
| Vendor agents with HIGH trust (>= 0.9) may proceed with standard | ||
| authorization. Vendor agents with MODERATE trust (>= 0.5) require | ||
| additional scope restrictions. |
There was a problem hiding this comment.
The worked example for Trust-Gated Authorization only covers HIGH and MODERATE trust levels. For completeness, it would be helpful to briefly describe the expected handling for agents with LOW and NONE trust levels as well (e.g., are they rejected, or restricted to even more limited scopes?).
knuckles-stack
force-pushed
the
sep-authorization-delegation-evidence
branch
2 times, most recently
from
293ae08 to
346b34e
Compare
knuckles-stack
force-pushed
the
sep-authorization-delegation-evidence
branch
from
346b34e to
101f918
Compare
|
This proposal addresses something we've wrestled with hands-on while building Agenium Messenger — a messenger where AI agents receive messages via A2A. A few observations from our implementation: On delegation chains: The scope-narrowing requirement is critical. We found that without explicit scope constraints at each hop, agents tend to delegate the full permission set "just to be safe" — which defeats the purpose entirely. Your temporal bounds approach is clean. On audit evidence: One thing we'd add to the audit trail: distinguishing between capability possession and capability use. An agent might hold a write-scope but only ever exercise read-operations. The delta is useful signal for trust scoring downstream. On revocation propagation: Have you considered lazy revocation with a TTL? Eager propagation across multi-hop chains can create latency spikes in long delegation trees. A short TTL (e.g., 30s) with a re-verification endpoint might balance responsiveness vs. overhead. Happy to share our implementation notes if useful — we've been running this in production for a few weeks. |
|
Scope narrowing. The monotonic reduction requirement exists for exactly the failure mode you describe. Section 4.2 enforces Possession vs. use. Valid point. The current audit schema (Section 7.1) captures exercised operations but does not distinguish granted-but-unused capabilities. Adding a Lazy revocation. The proposal specifies eager propagation as normative (Section 5, MUST behavior). A TTL-based re-verification endpoint is a sound optimization for deep trees. The risk is a bounded window where revoked capabilities remain honored. I would frame this as a MAY optimization with a normative maximum window (e.g., Implementation notes welcome. |
|
The authorization extension addresses a gap that also exists one step earlier — at discovery time. When an agent queries a registry to find a capable peer, it currently gets capabilities (what the agent can do) but not authorization topology (what scopes it accepts, whether it supports delegation chains, what audit evidence it can produce). Session initialization is required before any of this is negotiated. For compliance-sensitive deployments (EU AI Act, HIPAA), that means starting a session just to find out the peer's authorization model is incompatible. The extension schema defined here — authorization types, scope grammar, delegation support flag, evidence format — could serve as a discoverable field in AgentCard. Discovery-time authorization negotiation would let orchestrators pre-screen peers for compliance requirements without initiating a session. A peer that can't produce EU AI Act Article 50 audit evidence gets filtered at the discovery layer, not after task assignment. This connects to work being done on the Agenium registry (https://agenium.net) — we're mapping AgentCard fields to registry format specifically to make pre-session capability + authorization negotiation possible. The 'what scopes does this agent accept' question is one we're trying to answer from the directory, not from the session handshake. |
2 participants
Addresses outstanding work items on authorization schemes (#19, #71) and
capability-based authorization (#1404).
Summary
This proposal adds three interconnected capabilities to the A2A specification
as an extension:
extension mechanism, replacing ambient authority with explicit, verifiable
scopes and a hierarchical scope grammar
narrowing, temporal bounds, chain continuity verification, and revocation
propagation
action records with hash-chained integrity, enabling independent third-party
verification
Additionally includes a penalty-based trust scoring model, three normative
authorization flows (direct, delegated, trust-gated), worked examples
(financial services, healthcare, supply chain), and security considerations
including post-quantum signature readiness.
Design Decisions
parameters using the existing A2A extension mechanism. No core data
structures are modified. Existing implementations continue to work.
be adopted independently.
Ed25519,ES256,ML-DSA-87), not hardcoded choices.Evidence write failures trigger action suspension.
Motivation
visibility into multi-agent permission chains
Compatibility
A2A-Extensionsheader activationFile
docs/topics/authorization-delegation-evidence.md(~4,200 words)Closes #19, closes #71, closes #1404