Repository navigation
Description
Summary
Follow-up from #375 (PR for the wire-code rename portion). This issue tracks the parity-contract refactor that was deferred from that PR per the user's stop-rule ("if the parity contract turns out to be more complex than fits in a single PR, file a separate issue for the parity-contract follow-up").
Why
The cross-tenant onboarding-oracle clamp in the AdCP spec requires the unrecognized-agent path and the recognized-but-denied path to be observably indistinguishable to an external attacker — across:
- HTTP status code (already aligned via shared
PERMISSION_DENIEDenvelope). - Response headers (Content-Type, Content-Length within negligible tolerance).
- Side effects (audit emission, metric increment with the same operation label).
- Latency (cannot shortcut the unrecognized path; needs a deliberate budget).
- Observability (logs, APM spans, third-party error telemetry).
#375's rename portion closed the code mismatch but left the eager-raise structural difference — see the docstring on _resolve_buyer_agent (the "Note on parity" paragraph) and the test-file docstring on tests/test_tier2_spec_conformance.py.
Required design
Per the issue body of #375:
Approach: introduce a
PermissionDeniedReasoninternal enum/struct with(scope, status)fields. The dispatch layer raises a singlePermissionDeniedErrorcarrying a reason; the wire-level translator emits the spec-correctPERMISSION_DENIEDenvelope withdetailspopulated only when scope is set. The unrecognized path still does the same audit-emission + metric increment as the denied path. Latency parity may require an explicit small delay budget — document the tradeoff.
Concretely:
- Single emit point. Move all four denial paths in
_resolve_buyer_agent(and thevalidate_billing_for_agentpath) through one common projection — an internalPermissionDeniedErrorwrapping aPermissionDeniedReasonstruct, projected to the wire envelope by a single translator. Today four call sites build the envelope inline. - Latency budget. The unrecognized path needs to do equivalent resolution work to the recognized-but-denied path before raising. The simplest design is an explicit small delay (50–100 ms?) on every denial path so the variance between branches is dominated by the budget rather than the code path. Document the budget tradeoff (extra latency on every denial vs. closing the side channel).
- Audit / metric parity. Today the recognized branches log
details.agent_urlanddetails.status; the unrecognized branch logs nothing. Need to converge on a uniform log shape — same operation label, same fields (with the discriminator either missing or hashed-then-truncated to prevent log scraping from becoming the side channel). - Header parity. A2A and MCP transports both go through the framework's wire serializer. Verify Content-Length is within tolerance (the message strings are already identical post-Tier 2 commercial-identity error codes don't conform to AdCP spec — cross-tenant oracle risk #375; the variance is
detailssize). Consider padding the unrecognized envelope to match a fixed byte count.
Tests
- Latency parity test: assert p99 difference between unrecognized-agent and recognized-but-suspended paths is < 5 ms over N requests (with the explicit budget set high enough that branch-comparison variance is negligible).
- Header parity test: same Content-Type, Content-Length within ±N bytes (where N covers the
detailsshape variance). - Side-effects parity test: same audit-sink writes, same metric increments with the same operation label.
- Status code parity test: same HTTP status across all four denial paths.
Refs
- Tier 2 commercial-identity error codes don't conform to AdCP spec — cross-tenant oracle risk #375 (rename portion shipped here).
- Spec source (when available):
static/schemas/source/error-details/agent-permission-denied.jsonline 10 — the elevation note. - Spec uniform-response MUST list:
error-handling.mdx(Per-Agent Authorization Gate).
🤖 Generated with Claude Code
Activity
bokelley commentedon May 14, 2026
Manual triage (triage bot didn't post on this issue).
Verdict: ready-to-draft. Real follow-up from #375; the eager-raise structural difference in
_resolve_buyer_agentremains and is a real timing/side-channel issue per the spec's observability MUST.Scope (medium, ~400-600 LoC):
PermissionDeniedError(reason: PermissionDeniedReason)— one raise site, one translator_resolve_buyer_agent+validate_billing_for_agentReviewers needed: security-reviewer (primary — timing side channels), ad-tech-protocol-expert (spec invariants), code-reviewer.
Tests already specified in issue body — latency parity (p99 < 5ms), header parity, side-effects, status code.
Not blocked by anything. Sized for a single PR.
bokelley commentedon May 21, 2026
Closing as superseded by #748, with residual scope re-extracted to #772.
This issue's 4-numbered required-design list assumed all four denial branches would funnel through
PERMISSION_DENIEDwith differentdetailspayloads — that was the world before #748 (merged 2026-05-20) migrated the recognized-but-denied paths to dedicatedAGENT_SUSPENDED/AGENT_BLOCKEDcodes per AdCP 3.1.0-beta.1.Status of each design item under the post-#748 world:
PERMISSION_DENIEDbranches (unrecognized + unknown-status) share a translator, which is structurally trivial.PERMISSION_DENIEDbranches. Moved to Tier 2 PERMISSION_DENIED: side-effect parity + timing budget (narrow follow-up to #392/#735) #772 with hardening (math.isfinite, no silent disable) that PR fix(server): Tier 2 permission-denied parity contract (#392) #735 was missing.DenialAuditRecordand HMAC-or-documented-threat-model foragent_url.PERMISSION_DENIED; the two remainingPERMISSION_DENIEDbranches both have emptydetailsand are already byte-equivalent.PR #735 (the attempt at this issue's design) is also closed — see the closing comment there for the security and protocol findings that would have blocked merge independently of the supersession.
Tracking residual work at #772.