Skip to main content

ADR-012: Unsigned Error Response Handling

Status: Accepted Date: 2026-03-25 Relates to: ADR-007

Context​

Error responses (4xx, 5xx) from the trust authority are not signed — they contain no trust data. Because they are unsigned, a man-in-the-middle can forge them. An injected 404 entityNotFound suppresses a valid entity. An injected 500 internalError blocks trust evaluation entirely.

If error handling is left advisory ("agents SHOULD retry or use cached data for high-stakes transactions"), agents may treat a single forged error as a definitive "not found" result, enabling suppression attacks without breaking the transport layer.

Decision​

Keep errors unsigned. Make agent error handling mandatory with concrete fallback semantics.

Agents MUST:

  1. Retry before acting on a 404, 500, or network error (at least once, minimum 1-second delay)
  2. Prefer cached signed responses over unsigned errors when a valid cache entry exists
  3. Treat unresolved errors as "trust unknown" — not "entity not found" or "entity untrusted"
  4. Escalate in high-risk contexts — when context is high-value, agents MUST NOT conclude an entity is unknown based solely on unsigned errors

The key semantic distinction: the protocol cannot make negative assertions without a signed response. An unsigned error means evaluation failed, not that the entity lacks trust.

Options Considered​

A. Sign error responses with a small signed error envelope. Eliminates the suppression attack entirely. Adds implementation cost: the authority must sign every error, agents must verify error signatures, and the key management scope grows. Error signature verification failures create ambiguous states. Deferred — see roadmap. May be revisited if the attack surface proves significant in practice.

B. Keep errors unsigned, make failure semantics stricter (chosen). Leaves the transport layer unchanged. Shifts the defense to agent behavior: mandatory retries, cache preference, and "trust unknown" semantics. Does not eliminate the attack — a persistent MITM that blocks all retries still succeeds. Sufficient today because HTTPS prevents most MITM scenarios; the normative rules address the residual risk.

C. Accept this as a transport-layer concern. Relies entirely on HTTPS. Fails when TLS termination is compromised or when agents operate in degraded network environments. Insufficient — the protocol should define agent behavior for threats it acknowledges.

Consequences​

  • Agents must implement retry logic and cache fallback for error responses
  • "Trust unknown" becomes a distinct state that agents must handle separately from "not found"
  • The protocol makes a clear semantic distinction between signed assertions and unsigned failures
  • A persistent MITM that blocks all retries can still suppress trust evaluation — signed errors (Option A, on the roadmap) would address this
  • Existing agent implementations that treated 404 as "not found" must update their error handling

References​

  • ADR-007 — Security and Anti-Gaming (response signatures)
  • architecture/api.md — Agent Error Handling section
  • architecture/security.md — Error response discussion