Review of Controller Document draft 20240817

I read https://www.w3.org/TR/2024/WD-controller-document-20240817/ in its entirety.  What follows are issues identified that I believe should be addresses, listed in the order that they occur in the document.  I am NOT expecting a discussion of these issues in this thread.  Rather, I plan to file GitHub issues so they can be considered individually.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#introduction
This section should be normative, since it contains a testable normative statement using RFC 2119 language.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#conformance
The key word NOT RECOMMENDED is missing.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#terminology
This section should be normative, since applying the definitions of the terms is necessary to correctly implement the specification.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#terminology
In the "authentication" definition, I believe that "to a verifier" should be deleted.  An entity can authenticate to parties other than a verifier.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#terminology
In the "cryptographic suite" definition, I suggest changing "A specification defining how to use" to "A means of using".  It being in a specification is superfluous.  Also, there may be multiple cryptographic suites defined in a single specification.

In the "verification method" definition, I suggest changing "A set of parameters that can be used together with a process to independently verify a proof" to "A method of independently verifying a proof."  Keep it simple.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#data-model
The inline issue says "Add examples of common Controller documents."  I don't know that we can judge what is "common" or whether it's relevant.  Maybe just add some Controller Document examples here?

https://www.w3.org/TR/2024/WD-controller-document-20240817/#data-model
Also, let's please replace all inline issues with actual GitHub issues so we can more easily track progress on them.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#controller-documents
The spec says "The property names in the tables are linked to the normative definitions and more detailed descriptions of each property" but this isn't the case.  "id", "alsoKnownAs", etc. in the table are not hyperlinks.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#controller-documents
Many of the definitions in the table are not particularly useful.  For instance, "id" is defined as "A string that conforms to the URL syntax defined in Section 2.1.1 Subjects."  But no description is present of what an "id" is used for.  Oh, wait - the definition is at 2.1.1 but what the text says is that the URL syntax is defined in 2.1.1.  I suggest adding a fourth column titled "Definition Reference" and move all the section references to that column and out of the "Value Constraints" column.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#example-controller-document-with-a-controller-property
Some of the examples imply that a `@context` property is needed in Controller Documents, which isn't the case.  The `@context` property should be deleted from the examples.  Or if there isn't consensus to do that, let's at least delete it from every other example.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#controllers
The note on "Authorization vs authentication" is confusing and not particularly actionable.  In particular, the meaning of phrase "authorization provided by the value of controller" is fairly inscrutable.  What is the "authorization provided" and to what?  This note needs to be reworked to be comprehensible and actionable or removed.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#verification-methods
The "type" definition says "The value of the type property MUST be a string that references exactly one verification method type." but there is no link to the definition of verification method types.  Instead, the verification method link goes to a place that doesn't define the types.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#verification-methods
The note "Verification method controller(s) and controller(s)" is pretty opaque. To steal a phrase from the game Adventure, "You're in a twisty maze of words, all alike." The confusion evoked here is perhaps related to that described at https://github.com/w3c/controller-document/pull/42#discussion_r1721008946 ?  This needs to be much clearer.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#verification-material
The use of "type" here is also not an actionable hyperlink.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#verification-material
Change "The fewer formats that implementers have to implement, the more likely it will be that they will support all of them." to "The fewer formats that implementers have to choose from, the more likely interoperability will be achieved."  We don't want to take a position, even implicitly, on whether it's a virtue to implement all of them or not.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#jsonwebkey
Change "public key fingerprint [RFC7638]" to "the JWK Thumbprint [RFC7638] using the SHA-256 hash function".

https://www.w3.org/TR/2024/WD-controller-document-20240817/#jsonwebkey
Change "alongside the x property, which still specifies the point on the Ed25519 curve that is associated with the public key" to "alongside the x and y properties, which still specify the point on the P-384 curve that is associated with the public key" to match the example.  And likewise change "The x property specifies the point" to "The x and y properties specify the point" in the previous example.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#verification-relationships
There's incorrect respec syntax used in "the value of the [=authentication=] property" resulting in "authentication" not being a hyperlink.  Likewise, there's incorrect syntax resulting in "the `keyAgreement` property".

https://www.w3.org/TR/2024/WD-controller-document-20240817/#verification-relationships
Delete "global" from "To maximize global interoperability".

https://www.w3.org/TR/2024/WD-controller-document-20240817/#authentication
Delete everything starting with the comma in this sentence: "The authentication verification relationship is used to specify how the controller is expected to be authenticated, for purposes such as logging into a website or engaging in any sort of challenge-response protocol."  Defining a login protocol is *way* out of scope here.  And the second clause is also about protocols.  The first part of the sentence will work fine on its own.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#authentication
This sentence doesn't provide actionable information: "If authentication is established, it is up to the application to decide what to do with that information."  It should either be deleted or updated to do so.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#authentication
The term "authentication verifier" is used without being defined.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#assertion
In "The assertionMethod verification relationship is used to specify how the controller is expected to express claims, such as for the purposes of issuing a verifiable credential.", it's not clear what it means to "specify how the controller is expected to express claims".  A normal reading of the English text in this context might lead one to believe this is saying something about the JWT claims that might be contained in a credential, but I doubt that's what it's about.  What is it about?

https://www.w3.org/TR/2024/WD-controller-document-20240817/#key-agreement
In "The keyAgreement verification relationship is used to specify how an entity can generate encryption material in order to transmit confidential information intended for the controller", change "encryption material" to "a content encryption key".

https://www.w3.org/TR/2024/WD-controller-document-20240817/#capability-delegation
The description doesn't say how the capability being delegated is represented.  For instance, how does a developer know to which HTTP API authority to access is being delegated?

https://www.w3.org/TR/2024/WD-controller-document-20240817/#multihash
This section says that "2) the length of the cryptographic hash" is included but it doesn't define the representation of the length used.  For instance, is a single-byte binary value representing the number of bytes used?  A two-byte value representing the number of bits?  Please specify.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#processing-errors
The spec says "The type value of the error object MUST be a URL that starts with the value https://w3id.org/security# and ends with the value in the section listed below."  To my understanding, w3id.org is not a domain controlled by the W3C or another standards organization, and so is inappropriate to include in a normative requirement.  Please change this reference to a domain and path controlled by the W3C, for instance https://w3.org/controller-document/security#.

An alternate resolution to this issue that would be acceptable would be for the current owner of w3id.org to transfer ownership to the W3C and for the W3C to create a change control process for the content at the domain that is approved by the TAG.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#contexts-and-vocabularies
The text in Section 4 (Context and Vocabularies) reiterates content defined elsewhere - hashes of contexts - that is not needed for Controller Documents.  Even when the controller document uses JSON-LD, which is optional, this at-risk content can be obtained from its primary sources.  Please delete this heading and all the text before Section 4.1.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#context-injection
Since Controller Documents have no requirement to use JSON-LD, describing treatment of @context values is inappropriate and unnecessary in this specification.  Please delete this section.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#multibase
As in a previous comment, please change the use of https://w3id.org/security#multibase to a URL controlled by the W3C, for the same reasons.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#multibase
The term "multibase character" is used without being defined and without the term being a hyperlink to a definition.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#proving-control-and-binding
Delete the comma in "requires, the use".

https://www.w3.org/TR/2024/WD-controller-document-20240817/#proving-control-of-an-identifier-and-or-controller-document
A respec syntax error seems to have been made, because this subsection and the next one are missing the section number.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#key-and-signature-expiration
Change "cryptographic material were not expired" to "cryptographic materials were not expired".

https://www.w3.org/TR/2024/WD-controller-document-20240817/#verification-method-rotation
Change "A controller performs a rotation when they add" to "A controller performs a rotation when it adds".

https://www.w3.org/TR/2024/WD-controller-document-20240817/#revocation-semantics
This section is also missing a section number.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#content-integrity-protection
Change "Controller documents which include" to "Controller documents that include".

https://www.w3.org/TR/2024/WD-controller-document-20240817/#content-integrity-protection
Either delete the JSON-LD paragraph or qualify the statement by changing "consumers" to "consumers using JSON-LD".

https://www.w3.org/TR/2024/WD-controller-document-20240817/#identifier-correlation-risks
Change "Globally unambiguous identifiers" to "Identifiers".

https://www.w3.org/TR/2024/WD-controller-document-20240817/#example-a-bls12-381-g2-group-public-key-encoded-as-a-jsonwebkey-using-okp
The JWK representation of BLS keys uses both x and y coordinate and "kty":"EC", per https://www.ietf.org/archive/id/draft-ietf-cose-bls-key-representations-05.html#name-json-web-key-representation.  Please update the example accordingly.

https://www.w3.org/TR/2024/WD-controller-document-20240817/#acknowledgements
Capitalize "We" in "we would also like to thank".

I hope that the working group finds this review helpful in improving the specification.  I look forward to its publication as a Candidate Recommendation and eventually a Recommendation and its widespread use!

                                                                Best wishes,
                                                                -- Mike