feat: Web Bot Auth (WBA) interop

[igrigorik]

UCP specifies RFC 9421 message signatures. But there are incompatible restrictions and missing guidance for a well-implemented Web Both Auth (WBA) deployment and interop:

• Algorithm (incompatible restriction): the JWK schema accepted only EC keys; Ed25519 was not a valid UCP key type. A UCP signer literally could not publish or produce a WBA-conformant signature.
• Key publication (missing guidance): UCP's canonical field is signing_keys[]; WBA verifiers read RFC 7517 keys[]. UCP didn't forbid adding keys[] to the profile but didn't define its role either — an integrator publishing both arrays had no normative guidance on which was authoritative.
• Header semantics (missing guidance): UCP-Agent points to the UCP profile; Signature-Agent points to a WBA key directory. An integrator could emit both, but UCP didn't define what they meant relative to each other or how verifiers should pick between them.

An integrator could try to compose UCP + WBA on their own, but the algorithm restriction was a hard block, and the semantic gaps meant any composition was bespoke and likely to drift across implementations.

This PR resolves all three. WBA's architecture draft §4.2.3 explicitly permits additional components beyond the WBA-required set, which makes a single-signature dual-audience shape valid under both regimes once the algorithm is supported and the role of each header is normatively defined.

Proposed / staged updates

1. feat: add EdDSA (Ed25519) as an optional algorithm

UCP's JWK schema is split into EC (existing) and OKP (new) branches via oneOf. EdDSA is OPTIONAL for general UCP verifiers; ES256 remains the universal MUST baseline. EC keys gain a tight alg/crv coupling (ES256 with P-256, ES384 with P-384). No spec language about WBA yet — this commit just makes Ed25519 a recognized UCP algorithm.

2. feat: add WBA-compatible signature shape (single-sig dual-audience)

New WBA Interop subsection in signatures.md documents the opt-in:

• Emit a Signature-Agent header (RFC 8941 Dictionary, member key matches the Signature-Input signature label).
• Sign signature-agent;key="<label>" as a component (RFC 9421 §2.1.2 Dictionary-member component selection).
• UCP's existing components (ucp-agent, idempotency-key, content-digest, content-type) stay in the signed list.

3. feat: add top-level keys[] and WBA-interop deployment patterns

Profile schema gains a top-level keys[] field (RFC 7517 JWK Set) that mirrors the canonical signing_keys[]. When both arrays are present they MUST list the same kid set with semantically equivalent JWKs (identical RFC 7638 thumbprints).

• Deployment Patterns for WBA interop — content negotiation, one URL, two media types; two URLs, isolated signing.
• WBA Response Signing — deferred to draft-meunier-http-message-signatures-directory §5.2.
• Identity Resolution Algorithm — per-signature dispatch on the tag parameter; explicit skip semantics; SHOULD-level keyid↔JWK-thumbprint check; transport-identity rule scoped against payload-layer assertions.

On the wire

Default UCP signature (today, unchanged)

POST /checkout-sessions HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
UCP-Agent: profile="https://platform.example/.well-known/ucp"
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
Signature-Input: sig1=("@method" "@authority" "@path" "ucp-agent" "idempotency-key" "content-digest" "content-type");keyid="platform-2026"
Signature: sig1=:base64_ecdsa_signature_value:

{ "line_items": [{"item":{"id":"item_123"},"quantity":2}] }

ES256 signature against a key in signing_keys[]. UCP verifier reads UCP-Agent, fetches profile, verifies. No changes.

WBA-interop opt-in signature (new, opt-in)

POST /checkout-sessions HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
UCP-Agent: profile="https://platform.example/.well-known/ucp"
Signature-Agent: sig1="https://platform.example/.well-known/ucp"
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
Signature-Input: sig1=("@method" "@authority" "@path" "signature-agent";key="sig1" "ucp-agent" "idempotency-key" "content-digest" "content-type");keyid="NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs";created=1738617600;expires=1738621200;tag="web-bot-auth"
Signature: sig1=:base64_ed25519_signature_value:

{ "line_items": [{"item":{"id":"item_123"},"quantity":2}] }

One signature on the wire. UCP-shape verifiers route via UCP-Agent and find their components (ucp-agent, idempotency-key). WBA-shape verifiers route via tag="web-bot-auth" → Signature-Agent, find theirs (@authority, signature-agent, tag, created/expires). Both verify the same bytes against the same key. Both headers can point at the same well-known URL, but implementer is also free to point to separate WBA-compatible directory.

UCP profile as JWKS

The /.well-known/ucp document publishes both arrays as semantic mirrors:

{
  "ucp": { ... },
  "signing_keys": [
    { "kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs", "kty": "OKP", "crv": "Ed25519", "x": "..." },
    { "kid": "merchant-2026", "kty": "EC", "crv": "P-256", "x": "...", "y": "..." }
  ],
  "keys": [
    { "kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs", "kty": "OKP", "crv": "Ed25519", "x": "..." },
    { "kid": "merchant-2026", "kty": "EC", "crv": "P-256", "x": "...", "y": "..." }
  ]
}

RFC 7517 §5 permits additional members alongside keys in a JWK Set, so the document is simultaneously a valid UCP profile and a valid JWK Set. UCP-classic verifiers read signing_keys[]; WBA-shape verifiers (reading via Signature-Agent) read keys[]. I'm proposing this shape as an interim step towards replacing/deprecating signing_keys[] in favor of keys[] in separate PR, which can target next UCP version.

Backwards compatibility

• Default UCP signers and verifiers operate unchanged. ES256 is still the universal baseline.
• Profiles publishing only signing_keys[] remain valid. keys[] is OPTIONAL.
• WBA opt-in is per-signature. Sites that don't opt in emit only UCP-Agent (no Signature-Agent).
• UCP verifiers built only for UCP-default signatures may need to add RFC 9421 §2.1.2 Dictionary-member component selection to verify WBA-shape signatures — but that's RFC 9421 conformance, not a UCP-imposed cost.

---

Where this gets us vs desired state

After this PR lands, a UCP+AP2+WBA-interop merchant operates two keys in the same signing_keys[] array (and mirrors them in keys[] if publishing JWKS-superset form):

• Ed25519 — HTTP transport identity, WBA-compatible.
• ECDSA P-256 — AP2 merchant_authorization JWT, per AP2 v0.2 §Payment Mandate.

Two additional moves collapse this to one key, one artifact:

1. AP2 relaxes the algorithm-class constraint — tracked in AP2 #268. The issue proposes replacing the "MUST be non-deterministic" rule with an entropy-property rule that UCP's required Checkout id field structurally satisfies. Once accepted upstream, a UCP+AP2 merchant can use a single Ed25519 key for both layers.
2. UCP promotes keys[] to canonical and deprecates signing_keys[] — separate follow-up PR (not in scope here). Profiles publish a single keys[] array; the document is a valid JWK Set without dual-publication.

With both in place: one Ed25519 key, one keys[] array, one profile document that's also a valid WBA directory. No mirroring, no dual-keying, no separate signing-key field. The wire format and verifier algorithm in this PR don't change in that future — they're already pointed at it.

---

Checklist

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors.
• I have followed the Contributing Guide
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.