--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/jwt_review.txt	Thu May 01 16:50:41 2025 +0100
@@ -0,0 +1,233 @@
+*Summary*
+
+*Minor points*
+[this actually borders on the 'substantive', see the discussion under
+Appendix B.]
+
+ 4.2.1
+     This bullet
+
+      "JSON-encode the array, producing [a] UTF-8 string"
+
+     looks simple, but ended up confusing me for over an hour.
+     
+     For the rest of things to work, you must mean "Serialize the array
+     to the corresponding utf-8-encoded byte sequence", but that's not
+     exactly trivial in the JSON-native context you've adopted in this
+     document.
+
+     That is, at first I thought you should just include one extra
+     step in the Disclosure construction, example, namely what the
+     UTF-8 (byte) string looks like as (what RFC8259 calls) "UTF-8
+     encoded JSON text", immediately after the array creation
+     display:
+
+   ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"]                   (1)
+
+  "[\"_26bc4LT-ac6q2KI6cBW5es\", \"family_name\", \"M\u00c3\u00b6bius\"]" (2)
+
+     but that's really ugly and would be more likely to confuse than clarify.
+
+     Note that in only the first 64bitURL Disclosure
+     samples that you offer decodes to my guess (2)!  And indeed
+     what they _do_ decode to, that is
+
+     '["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"]'   # 4d c3 b6 62 69 75 73
+
+     '["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\\u00f6bius"]'
+
+     respectively, are non-trivially distinct, as in both Python and
+     node.js these, as strings, correspond to two _different_
+     byte-sequences (the second is 4 bytes longer than the first and,
+     if both are decoded as utf-8, to 5 more characters).  It's true
+     that they are both valid JSON texts, per RFC8259, but you have to
+     apply a JSON parser to them to get to indistinguishable JSON objects.
+
+     Apologies for this lengthy attempt to show where I think you've
+     gotten in to trouble by specifying _algorithms_ in informal
+     english, while more-or-less assuming, I'm guessing, some library
+     functions in whatever language you're used to using.
+
+     To address this problem, since you use "JSON-encode" a number of
+     times in later sections, I would _strongly recommend_ that you
+
+      a) Add the following to section 1.2, immediately after the
+         definition of *base64url*:
+
+         *JSON-encode* denotes the conversion of a JSON object to
+         "JSON text" and encoding that text in UTF-8, as defined in
+         RFC 8529.  That is, mapping a JSON object to a UTF-8 byte
+         sequence which when decoded and parsed will reconstruct an
+         object indistinguishable from the original.
+
+      b) Replace that problematic bullet, and the next, with
+
+         * JSON-encode the array, producing a UTF-8 encoded byte sequence.
+
+         * base64url-encode the resulting byte sequence. The resulting
+           string is the Disclosure.
+
+      c) Be careful never to use "string" when "(UTF-8) byte sequence"
+         is meant, starting in 4.2.2 with
+
+           The Disclosure string is created by JSON-encoding this array
+           and base64url-encoding the resulting byte sequence as
+           described in Section 4.2.1
+
+      d) In the second media type registration in 12.2
+           "represented as a JSON Object" ->
+           'represented as UTF-8 encoded "JSON text" as defined in RFC 8529'
+
+      e) Include RFC 8529 in 13.1
+
+ Appendix B.
+
+     The above problem resurfaces here, with confusion between three
+     possible interpretations, in the terms of RFC 8529, of what is
+     displayed:
+
+        * a JSON object, that is, structured data composed of
+          instances of the six primitive types which JSON can
+          represent.  It is _not_ to be understood as string, byte
+          sequence or file contents;
+   
+       * a possible JSON text for some JSON object.
+
+       * a UTF-8 encoding of some JSON text, aka a "JSON encoding".
+
+     The first figure is labelled as a JSON object, which is OK.
+
+     But it is indistinguishable from one of the possible
+     JSON texts corresponding to that object.
+
+     The next figure purports to present two alternative "JSON
+     encodings", the second of which is problematic.
+
+     Its first line appears indistinguishable from that shown for the
+     JSON object in the preceding figure, but is in fact different.
+
+     In the first figure, construed as a "JSON text", the o-umlaut
+     glyph denotes a single Unicode character in a six-character
+     representation of a six-character object member string value.
+
+     However in the second figure, second alternative, the o-umlaut
+     corresponds to a _two_-byte UTF-8 sub-part of the JSON encoding of
+     that value as a seven-byte UTF-8 byte sequence, either in some
+     internal representation or an external stream or file.
+
+     What to do?  First, add something similar to
+     https://www.ietf.org/archive/id/draft-bray-unichars-14.html#name-notation
+     Then, whenever presenting JSON, always indicate whether what is
+     being shown is JSON text or JSON-encoded text (i.e. UTF-8 encoded
+     JSON text).  In JSON text, always include a version using the
+     U+xxxx notation whenever the underlying string contains non-ASCII
+     characters.  In JSON-encoded text, _always_ use the %xnn notation
+     for non-ASCII characters.  
+
+     Some examples of a possible way of indicating JSON text and
+     JSON-encoded text, from section 4.2.1
+
+     Replace the first figure with these two:
+
+     _________________________________________________________
+     |*JT*                                                    |
+     |                                                        |
+     |  ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"]  |
+     |                                               ^        |
+     |                                               |        |
+     |                                             X+00F6     |
+     |                                                        |
+     |________________________________________________________|
+
+     _______________________________________________________________
+     |*J-ET*                                                         |
+     |                                                               |
+     |  ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M%xc3%xb6bius"]  |
+     |                                                               |
+     |_______________________________________________________________|
+
+  and the first bullet of the three alternatives which follow with
+
+     * A different way to encode the unicode o-umlaut:
+
+     ______________________________________________________________
+     |*JT*                                                         |
+     |                                                             |
+     |  ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\x00f6bius"]  |
+     |                                                             |
+     |_____________________________________________________________|
+
+     ______________________________________________________________
+     |*J-ET*                                                       |
+     |                                                             |
+     |  ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\x00f6bius"]  |
+     |                                                             |
+     |_____________________________________________________________|
+
+      WyJfMjZiYzRMVC1hYzZxMktJNmNCVzVlcyIsICJmYW1pbHlfbmFtZSIsICJNX
+      HUwMGY2Yml1cyJd
+
+  And throughout the examples in Appendices A and B, label the initial
+  figure with *JT* and the 'Content' boxes with *J-ET*.  You don't
+  need to gloss every Chinese/German string with their U+xxxx version,
+  but saying something at the top of A that where non-ASCII characters
+  appear in any of the initial examples that the actual Unicode
+  character is what is meant.
+
+  The Appendix B example then looks like this, along with some small
+  changes to the text:
+
+     Usually, JSON-based formats transport claim values as simple
+     properties of a JSON object such as this:
+
+     _________________________________________
+     |*JT*                                    |
+     |                                        |
+     |  ...                                   |
+     |    "family_name": "Möbius",            |
+     |    "address": {                        |
+     |      "street_address": "Schulstr. 12", |
+     |      "locality": "Schulpforta"         |
+     |     }                                  |
+     |  ...                                   |
+     |________________________________________|
+
+
+
+*Nits*
+
+ 4. "(for those who celebrate)" will be anywhere from obscure to
+     confusing for many readers from many cultures -- best to remove it.
+
+ 4.2.1. "an UTF-8" -> "a UTF-8" [overtaken by 4.2.1 above]
+
+        "However, the digest is calculated over the respective
+         base64url-encoded value itself, which effectively signs"
+
+         ->
+
+        "Because the digest is calculated over the respective
+         base64url-encoded value itself, this effectively signs"
+
+ 4.3.1.  I'd recommend
+        "The bytes of the digest MUST" -> "The bytes of the sd_hash value MUST"
+
+ 6. I have decoded a few of the Disclosures and they're fine, but you
+    might want to ask a friendly 3rd party to double-check all the
+    Disclosures and digests, at least here and in Appendix A.
+
+ 9. "Security considerations in this section help achieve the
+     following properties:"
+
+    This confused me for a while.  I think what you mean to say here
+    is something like
+
+      This spec aims to provide two security guarantees:
+
+      *Selective Disclosure*: ...
+
+      *Integrity*: ...
+
+    The following sub-sections show how the various aspects of the
+    design presented here combine to achieve this.
+