docs(ap2): clarify ES512 signature scope

[ShuoRen-TT]

Summary

• separate AP2 JWS algorithm requirements from UCP HTTP Message Signatures
• document the ES256/P-256, ES384/P-384, and ES512/P-521 pairings
• require verifiers to bind the protected JWS alg to the selected key's
  curve and optional JWK alg
• add a schema-annotated P-521/ES512 profile key example
• clarify that AP2's accepted algorithms do not expand the universal HTTP
  signature baseline

Motivation

AP2 currently accepts ES512 for its JWS objects, while the shared HTTP
Message Signatures table stops at P-384/ES384. That can be read as either
an omitted global requirement or an AP2-specific extension.

This change takes the AP2-scoped interpretation already implied by the current
specification: AP2 owns its JWS algorithm policy, while reusing UCP's JWK
publication, discovery, and rotation mechanisms.

Scope

This is a documentation clarification only. It does not:

• add P-521/ES512 to UCP HTTP Message Signatures
• change the universal ES256 implementation baseline
• modify profile.json or any generated schema

The existing profile JWK vocabulary is open, so the annotated P-521 example is
schema-compatible without a core schema change.

Validation

• git diff --check
• focused check that the new example parses and is admitted by the current
  open JWK vocabulary
• scripts/test_validate_examples.py: 34 contract checks passed; its single
  integration check could not run locally because the ucp-schema binary is
  unavailable
• strict MkDocs build was attempted and reached the AP2 page, then stopped for
  the same missing local ucp-schema dependency

The PR Docs workflow will run schema example validation and the strict site
build with the repository's complete CI toolchain.

Closes #571

[vishkaty]

Really like the alg↔curve binding you added here — that's the right safeguard. One thing I noticed while checking it against the schema: profile.json already machine-enforces that binding with if/then rules for P-256, P-384, and Ed25519, but there's no P-521 rule, so a P-521 key published with a mismatched alg currently passes validation (I confirmed with ucp-schema; the same mistake on a P-256 key is rejected).

I opened #625 with the one-line P-521 pairs with ES512 rule so the binding your PR documents is also enforced at the schema layer — different file, no conflict, and I checked that your P-521 example JWK validates against it. Purely complementary; happy to fold it in here instead if you'd prefer to keep it in one place.

[ShuoRen-TT]

Thanks for digging into this and for validating the example against #625 — I
really appreciate it. I agree that the schema asymmetry is real, and that the
algorithm-to-curve binding should be machine-enforced wherever P-521 is
recognized.

For now, I would prefer to keep #625 separate rather than fold it into this
draft. #618 is intentionally AP2-scoped and documentation-only while
maintainers confirm the intended layering. #625 also adds P-521/ES512 to the
profile's well-known values, examples, and descriptions, so it carries a
broader schema-level decision that is useful to triage independently.

One small consistency point for that review: the top-level
jwk_public_key description still lists EC well-known keys as P-256 and
P-384. If maintainers choose to make P-521/ES512 a UCP-wide well-known pairing,
that description should be aligned as well; if the pairing remains
AP2-specific, it may be clearer to qualify it that way.

The two changes remain technically compatible, and your confirmation that the
example here validates against #625 is very helpful. Thanks again for catching
the gap and preparing the focused validation.

[ShuoRen-TT]

A concise review handoff:

• the scope remains AP2-specific and documentation-only;
• it does not modify profile.json, the universal ES256 baseline, or the UCP HTTP Message Signatures algorithm requirements;
• fix(schema): machine-enforce the P-521/ES512 key pairing in profile.json #625 remains a separate schema-level/TC decision, and the two changes are technically compatible but independently reviewable;
• the PR is currently mergeable, and the CLA and check-changes checks pass;
• the external-contributor Docs/Lint/Spelling/Conventional Commits workflows are still awaiting maintainer approval to run.

I will respond promptly to any scope or wording feedback.

[GarethCOliver]

worth noting that we are likely to remove this restriction in FIDO in 0.3 (and just mandate randomness in the Checkout. But this seems fine for now.

[ShuoRen-TT]

Thanks for the heads-up, Gareth. That makes sense. This PR keeps the
requirement explicitly scoped to AP2 v0.2 and retains the note pointing to
google-agentic-commerce/AP2#268. Once FIDO 0.3 publishes the normative Checkout
payload entropy requirement, we can follow up to align UCP with it rather than
anticipating the final wording here.

[GarethCOliver]

I'd just mandate this be set, it's best practices.

[ShuoRen-TT]

Thanks for the suggestion - agreed. I updated this so keys used with the AP2
extension MUST include the JWK alg, and a missing or mismatched value makes
the AP2 signature invalid. The requirement remains AP2-scoped and does not
change the global profile JWK schema.

[ShuoRen-TT]

Thanks again @GarethCOliver for the review. I pushed 119ffd4 to adopt the
alg suggestion:

• AP2 signing JWKs now MUST include alg;
• a missing or mismatched value makes the AP2 signature invalid; and
• the requirement remains AP2-scoped without changing the global profile JWK
  schema.

The focused cspell, markdownlint, and git diff --check validations pass. The
example validator remains unavailable locally because ucp-schema is not
installed; the repository CI provides that full validation once the
external-contributor workflows are approved.

@amithanda, could you please help approve the pending workflow runs and route
this documentation change to two eligible maintainers for review when
convenient? Thank you!