Trust Tokens: Comment changes making it easier to keep docs in sync

This CL contains some comment changes that should make it somewhat
easier to keep the docs in sync with protocol changes:
- it adds warnings to the signing helper and to the key commitment
parser, advising authors of code changes to make sure the docs agree
with their changes;
- it removes a large comment that basically reproduced the design doc's
example key commitment result, which is pretty brittle and could easily
go out of sync.

R=svaldez
CC=ykevin@google.com

Bug: None
Change-Id: I217d199997da04b19a3b339918af3da2aead0b88
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2565282
Auto-Submit: David Van Cleve <davidvc@chromium.org>
Commit-Queue: Steven Valdez <svaldez@chromium.org>
Reviewed-by: Steven Valdez <svaldez@chromium.org>
Cr-Commit-Position: refs/heads/master@{#832395}

services/network/trust_tokens/trust_token_key_commitment_parser.cc

@@ -242,31 +242,6 @@ mojom::TrustTokenKeyCommitmentResultPtr& commitment(Entry& e) {
 
 }  // namespace
 
-// https://docs.google.com/document/d/1TNnya6B8pyomDK2F1R9CL3dY10OAmqWlnCxsWyOBDVQ/edit#bookmark=id.6wh9crbxdizi
-// {
-//   "protocol_version" : ..., // Protocol Version; value of type string.
-//   "id" : ...,               // ID; value of type int.
-//   "batchsize" : ...,        // Batch size; value of type int.
-//
-//   // Optional operating systems on which to request issuance via system
-//   // mediation (valid values are: "android"), and (required if at least one
-//   // OS is specified) fallback behavior on other operating systems:
-//   "request_issuance_locally_on": [<os 1>, ..., <os N>],
-//   "unavailable_local_issuance_fallback": "web_issuance" | "return_with_error"
-//
-//   "1" : {                   // Key label, a number in uint32_t range; ignored
-//                             // except for checking that it is present and
-//                             // type-safe.
-//     "Y" : ...,              // Required token issuance verification key, in
-//                             // base64.
-//     "expiry" : ...,         // Required token issuance key expiry time, in
-//                             // microseconds since the Unix epoch.
-//   },
-//   "17" : {                  // No guarantee that key labels (1, 7) are dense.
-//     "Y" : ...,
-//     "expiry" : ...,
-//   }
-// }
 mojom::TrustTokenKeyCommitmentResultPtr TrustTokenKeyCommitmentParser::Parse(
     base::StringPiece response_body) {
   base::Optional<base::Value> maybe_value =

services/network/trust_tokens/trust_token_key_commitment_parser.h

@@ -41,6 +41,10 @@ extern const char
 extern const char kTrustTokenLocalIssuanceFallbackWebIssuance[];
 extern const char kTrustTokenLocalIssuanceFallbackReturnWithError[];
 
+// WARNING WARNING WARNING: When updating the parser implementation, please make
+// sure the normative source(s) of the key commitment result data structure's
+// format (as of writing, the design doc and perhaps ISSUER_PROTOCOL.md in the
+// WICG repository) have been updated to reflect the change.
 class TrustTokenKeyCommitmentParser
     : public TrustTokenKeyCommitmentController::Parser {
  public:

services/network/trust_tokens/trust_token_request_signing_helper.h

@@ -68,6 +68,10 @@ class TrustTokenRequestSigningHelper : public TrustTokenRequestHelper {
   // request's canonical representation. This allows rendering otherwise valid
   // signatures forwards-incompatible, which is useful in case the signing
   // data's semantics change across protocol versions but its syntax does not.
+  //
+  // NOTE: When changing this constant, please make sure it stays in sync with
+  // the normative source of the domain separator's value (currently the design
+  // doc).
   static constexpr uint8_t kRequestSigningDomainSeparator[] = {
       'T', 'r', 'u', 's', 't', 'T', 'o', 'k', 'e', 'n', 'V', '2'};