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 AP2 signing JWKs to include alg, and require verifiers to bind the
  protected JWS alg to the selected key's curve and 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.

[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!

[ShuoRen-TT]

Hi @amithanda, @jingyli, and @DanielFalconGuedes — I hope you're doing well.
I wanted to leave a gentle follow-up whenever you have a moment.

This PR remains explicitly scoped to AP2 v0.2 and is documentation-only.
Gareth's two non-blocking review comments have both been addressed:

• AP2 signing JWKs now MUST include alg, with the protected JWS alg
  bound to the JWK alg and curve.
• The possible FIDO 0.3 entropy-based change remains documented as future
  work, without anticipating normative wording that has not yet been
  published.

I have resolved both review conversations now that the feedback is incorporated
and documented. The branch remains cleanly mergeable, and the CLA and
check-changes checks pass. #625 remains a separate TC-level schema decision
and is not a dependency of this documentation clarification.

@amithanda, could you please approve the pending external-contributor workflow
runs when convenient?

@jingyli and @DanielFalconGuedes, I would greatly appreciate your review when
time permits.

Thank you very much for your time and help.

[vishkaty]

I filed #571, so I wanted to give this a real verification pass rather than just a thumbs-up. I fetched the branch (119ffd4), merged it onto current main (5a5d9e1) locally, and checked it mechanically:

• Composes cleanly with current main, including the #657 addition to ap2-mandates.md — it lands in the Canonicalization subsection, well below the section-intro and pseudocode hunks this PR edits, so nothing overlaps. The merged section intro (table → scoping note → binding requirement → example → algorithm note) reads coherently.
• Example validation passes. scripts/validate_examples.py --schema-base source/schemas --docs docs on the merged tree: 303 passed, 0 failed — versus 302 on main alone, so the new P-521 example is genuinely exercised and admitted by the open profile JWK vocabulary, as the PR describes. (This covers the validation that couldn't run locally without ucp-schema.)
• The example key is real. The x/y coordinates decode to 66-byte values forming a valid point on P-521 — worth stating because invalid example points are a classic spec pitfall that copy-paste propagates.
• Tree-wide consistency. I grepped the merged docs+schemas for ES256/ES384/ES512/EdDSA/P-521. Every site is consistent with the AP2-scoped layering: the HTTP Message Signatures table is unchanged with the new explicit non-extension sentence, ap2_mandate.json's description already listed all three algorithms, the pseudocode's new key_supports_jws_algorithm assert matches the prose MUST, and signatures.md's "excludes Ed25519" cross-reference matches the ECDSA-only AP2 table.

The alg↔curve binding (RFC 8725 §3.1) plus the mandatory JWK alg is the right verifier guardrail for a multi-algorithm key set. And as a data point from the #571 thread: the AP2 reference stack signs and verifies ES256 only today, so this clarification breaks nothing deployed while making an ES512-signed mandate verifiable by implementations built from the spec.

The one residual — the well-known EC vocabulary in signatures.md's key-format section and profile.json still stops at P-384, so the P-521↔ES512 pairing documented here isn't yet machine-enforced — is exactly the scope split already discussed above, tracked in #625, which remains compatible with this PR (the example JWK here validates against that rule too). Non-blocking for this documentation change.

This resolves #571 as filed: the divergence is now explicitly documented on both sides of the boundary. LGTM — thanks for taking the AP2-scoped interpretation to a clean landing.

[ShuoRen-TT]

Hi @mmohades and @yanheChen — a quick follow-up on #618 when convenient.

As of 2026-08-20, this PR is still mergeable, has two approvals, and all review conversations are resolved. I am not seeing any remaining technical feedback to address on my side.

If there is still a blocker, could you please point me to the specific change needed? Otherwise, I would appreciate a review or approval when time permits.

If maintainer action is still needed for the remaining governance or workflow gating, I would also appreciate help routing or clearing that final step. Thank you.

[ShuoRen-TT]

Hi @damaz91, thank you for helping route reviews on this PR.

The merge conflicts with the latest main have now been resolved, and the PR is mergeable again. The change checks and CLA pass; the remaining blocker is the required maintainer approval. @mmohades and @yanheChen have been requested for some time, but I understand they may be busy.

If they are unavailable, could you please help assign or route this to another eligible maintainer for review when convenient? I would be happy to address any feedback promptly. Thank you.