feat(ca2a): appraise the caller before opening its payload

[imran-siddique]

Finishes the mutual attestation work designed in #89. That PR landed the design and the stateless challenge primitive; this threads it through the transport so it actually runs.

What changed

The callee verified the caller's delegation chain (authorization: what the peer is allowed to ask for) and never appraised what the caller was running. A callee had no way to know whether the peer sending it a task was an enclave or a laptop.

Now: the handshake response carries a callee-issued challenge, the caller binds its own channel key into a report under it (caller_offer in the A2A metadata), and the callee appraises that before open_sealed.

caller                                   callee
  │  GET /channel?nonce=N  ─────────────▶
  │  ◀── ChannelOffer(N) + challenge C
  │  appraise callee, seal payload, attest own key under C
  │  POST /task + caller_offer  ────────▶
  │                                       appraise caller BEFORE opening payload
  │  ◀─── provenance record (readable, so it can be chained)

The ordering is the property

The payload is sealed to the callee's own channel key, so the callee can read it the instant it arrives. Appraising afterwards means an unattested caller has already had its work done, and every guarantee becomes a report on something that already happened.

test_sealed_payload_is_never_opened_when_appraisal_refuses asserts open_sealed is never called when appraisal refuses. I verified the test by making the swap: moving the open-payload block above the appraisal (a valid, plausible refactor) fails exactly those 3 cases with the callee opened the payload before appraising the caller, and nothing else. A first attempt at the mutation failed with an UnboundLocalError instead, which would have proven nothing, so it was redone properly.

Decisions taken (Imran, 2026-08-09)

Decision	Choice
Requirement knob	Three-rung ladder require_caller_attestation: "none" (default) → "any" → "hardware"
Offer present but invalid, at require="none"	Fail closed always
Outcome in the hashed record body	Always, including not_offered

Default demands nothing, because cA2A is alpha, almost no caller can attest, and a control that breaks the common case gets switched off and never switched back on. "hardware" without a caller_verifier is refused at construction rather than on every call.

A present and unappraisable offer is refused at every rung including "none". Demanding nothing means accepting a caller that proves nothing; it does not mean accepting a broken proof, or a misconfigured attestation path becomes indistinguishable from a caller that never had one.

⚠️ Breaking: every record hash changed

caller_attestation is in the hashed DelegationRecord body, always, as one of not_offered / failed / software-only / hardware. Four values, not three: a peer that offered nothing and a peer whose offer did not appraise are different facts, and neither may read as the software-only case.

Records predating the field are read as not_offered. The example DAGs are regenerated.

Two gaps found on the way

• The 1 MiB body bound had no test above it. Now declares an oversized Content-Length over a raw socket, which is what the guard actually inspects (it refuses before reading, so the body is never buffered). Sending a real 1 MiB body races the early refusal and the client sees a connection abort, which is why it went through a socket.
• The committed example DAGs were never verified as committed. The demos regenerate chain.json/dag.json on run, so the existing tests were checking the demo's own fresh output. Not hypothetical: this change left examples/cross-operator-delegation/dag.json broken on disk with the whole suite green and the README still quoting ca2a verify-dag as working. test_committed_examples_verify.py reads the blobs out of git instead.

What this still does not give you

Unchanged, and stated in the spec and LIMITATIONS.md: it is not simultaneous (the caller commits a sealed payload before the callee has appraised it — that needs a commitment step, a larger protocol), it does not make either peer trustworthy, and it is software mode only. Making the protocol mutual does not make the recorded hardware run mutual.

Also: a challenge does not cross instances (per-process secret, the stateless scheme's accepted cost). test_a_challenge_from_another_instance_does_not_verify holds that line.

Tests

367 passed, 3 skipped. 35 new in test_mutual_attestation.py, plus the two guards above. ruff check and mypy clean.

🤖 Generated with Claude Code