Tier 2 commercial-identity gate: latency / headers / side-effects parity contract

[bokelley]

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_DENIED envelope).
• 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 PermissionDeniedReason internal enum/struct with (scope, status) fields. The dispatch layer raises a single PermissionDeniedError carrying a reason; the wire-level translator emits the spec-correct PERMISSION_DENIED envelope with details populated 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:

1. Single emit point. Move all four denial paths in _resolve_buyer_agent (and the validate_billing_for_agent path) through one common projection — an internal PermissionDeniedError wrapping a PermissionDeniedReason struct, projected to the wire envelope by a single translator. Today four call sites build the envelope inline.
2. 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).
3. Audit / metric parity. Today the recognized branches log details.agent_url and details.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).
4. 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 details size). 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 details shape 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.json line 10 — the elevation note.
• Spec uniform-response MUST list: error-handling.mdx (Per-Agent Authorization Gate).

🤖 Generated with Claude Code

[bokelley]

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_agent remains and is a real timing/side-channel issue per the spec's observability MUST.

Scope (medium, ~400-600 LoC):

1. Internal PermissionDeniedError(reason: PermissionDeniedReason) — one raise site, one translator
2. Unify the 4 inline denial paths in _resolve_buyer_agent + validate_billing_for_agent
3. Explicit latency budget (50-100ms) on all denial paths
4. Audit/metric parity: same operation label, same fields with discriminator hashed-or-absent
5. Header parity: Content-Length within tolerance (consider padding)

Reviewers 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]

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_DENIED with different details payloads — that was the world before #748 (merged 2026-05-20) migrated the recognized-but-denied paths to dedicated AGENT_SUSPENDED / AGENT_BLOCKED codes per AdCP 3.1.0-beta.1.

Status of each design item under the post-#748 world:

1. Single emit point through one translator — no longer applicable. Suspended/blocked correctly emit dedicated codes; only the two PERMISSION_DENIED branches (unrecognized + unknown-status) share a translator, which is structurally trivial.
2. Latency budget — still valuable, but only between the two remaining PERMISSION_DENIED branches. 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.
3. Audit / metric parity — still valuable across all four branches for SecOps telemetry. Moved to Tier 2 PERMISSION_DENIED: side-effect parity + timing budget (narrow follow-up to #392/#735) #772 with a typed DenialAuditRecord and HMAC-or-documented-threat-model for agent_url.
4. Header parity (Content-Length padding) — obsoleted by feat(decisioning): emit AGENT_SUSPENDED / AGENT_BLOCKED dedicated codes (closes #409) #748. Recognized branches no longer use PERMISSION_DENIED; the two remaining PERMISSION_DENIED branches both have empty details and 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.