[Spec] Clarify Request-Signature for Checkout REST binding (define signing/verification; RFC 9421 discussion)

[ACSchil]

Description

I’m working on the HTTP bindings for UCP and hit an ambiguity around Request-Signature in the Checkout REST spec.

In https://ucp.dev/specification/checkout-rest/ the Request-Signature header is required, but the documentation doesn’t say how the signature is computed or verified (what bytes are signed, what format/alg, how kid/key lookup works, expected failure behavior, etc.). The Shopping REST OpenAPI has the same short description for Request-Signature (no normative details): https://ucp.dev/services/shopping/rest.openapi.json

By contrast, the Order capability has a concrete definition using a detached JWT/JWS (RFC 7797) for webhook signing/verification and also uses Request-Signature: https://ucp.dev/2026-01-23/specification/order/

It feels like Checkout REST probably intended to reuse that same signing scheme, but it’s not stated.

Why this matters

Implementers can’t reliably interop without the “how” here. Right now different clients could sign:

• body only vs body + method/path/headers
• different canonicalization / serialization
• different key selection / kid conventions
  …while still “matching” the current description.

Proposed doc update (minimum)

If the intent is to match the Order capability approach, I think Checkout REST should explicitly say:

• Request-Signature is a detached JWS/JWT per RFC 7797 (same as Order webhook guidance)
• what exactly is signed (at minimum: request body)
• required JOSE header params (kid, alg, etc.)
• key discovery/verification: verifier matches kid to a key in the sender’s published signing_keys
• expected error behavior when missing/invalid

Discussion: should HTTP bindings use RFC 9421 instead?

Separately, I’d like to open discussion on using RFC 9421 HTTP Message Signatures for HTTP bindings.

Reason: detached JWS over only the body doesn’t naturally bind the request to method + target URI + important headers. RFC 9421 is designed to sign those HTTP components directly, which avoids replay/endpoint swap issues unless every implementation reinvents “what else to include” on top of a body signature.

If UCP wanted to go this direction, it likely means adopting:

• Signature-Input + Signature headers (RFC 9421)
• a UCP profile: required covered components (e.g. @method, @target-uri or @path+query, content-digest, and any UCP-specific headers)
• mapping keyid/kid to published signing_keys
• a migration plan (support both for a window, clarify precedence if both are present)

Questions

1. Is Checkout REST intended to use the same RFC 7797 detached JWS/JWT mechanism described in the Order capability?
2. If yes: should it be body-only, or should it bind method/path/headers as well (and if so, how)?
3. If not: what is the intended on-wire format and verification process for Request-Signature?
4. Is the project open to standardizing on RFC 9421 for HTTP bindings, either as a replacement or an option?

References

• Checkout REST spec: https://ucp.dev/specification/checkout-rest/
• Shopping REST OpenAPI: https://ucp.dev/services/shopping/rest.openapi.json
• Order capability signing/verification (RFC 7797): https://ucp.dev/2026-01-23/specification/order/
• RFC 9421 (HTTP Message Signatures): https://www.rfc-editor.org/rfc/rfc9421

[igrigorik]

Definitely a gap and great points -- ty!

Squinting at the macro problem, a sketch for how we can bring consistency across transports and req+resp flows:

  ┌─────────────────────────────────────────────────────────────────┐
  │                     SHARED FOUNDATION                           │
  ├─────────────────────────────────────────────────────────────────┤
  │  Canonicalization: JCS (RFC 8785)                               │
  │  Algorithms: ES256 (required), ES384, ES512                     │
  │  Key Format: JWK (RFC 7517)                                     │
  │  Key Discovery: signing_keys[] in /.well-known/ucp              │
  │  Key ID: kid claim/parameter                                    │
  └─────────────────────────────────────────────────────────────────┘
                                │
                ┌───────────────┴───────────────┐
                ▼                               ▼
  ┌─────────────────────────┐     ┌─────────────────────────┐
  │      REST BINDING       │     │      MCP BINDING        │
  ├─────────────────────────┤     ├─────────────────────────┤
  │ Format: RFC 9421        │     │ Format: RFC 7515 App F  │
  │ Headers:                │     │ Location:               │
  │   Signature             │     │   Request: meta.sig*    │
  │   Signature-Input       │     │   Response: meta.sig*   │
  │   UCP-Content-Digest-JCS│     │ Signed:                 │
  │ Signed:                 │     │   JSON-RPC envelope     │
  │   @method, @path,       │     │   + timestamp + nonce   │
  │   @status, content-type │     │                         │
  │   + body digest         │     │                         │
  └─────────────────────────┘     └─────────────────────────┘

1)All JSON signatures use JCS (RFC 8785) canonicalization

• AP2 already requires /uses it
• Order webhooks don't (bug)
• Without it, JSON serialization differences cause verification failures

2) Protocol-appropriate signature formats

• REST: RFC 9421 (HTTP Message Signatures), binding for @method, @path, @status, ...
• MCP: RFC 7515 Appendix F (Detached JWS)
• Same crypto underneath (JCS, ES256, JWK)

3) Standard HTTP headers

• Deprecate Request-Signature and X-Detached-JWT.
• Switch to RFC 9421's Signature + Signature-Input: standard headers, work for request and response