Early Review of draft-ietf-gnap-resource-servers-06
review-ietf-gnap-resource-servers-06-genart-early-eggert-2024-07-09-00
review-ietf-gnap-resource-servers-06-genart-early-eggert-2024-07-09-00
# genart-early review of draft-ietf-gnap-resource-servers-06 CC @larseggert I am the assigned Gen-ART reviewer for this draft. For background on Gen-ART, please see the [FAQ](https://wiki.ietf.org/group/gen/GenArtFAQ). Please resolve these comments along with any other comments you may receive. ## Comments I don't know much about this area. The doc is well-written and seems basically in good shape. ### Missing RFC status Datatracker does not record an intended RFC status for this document. ### Section 2.1.1, paragraph 1 ``` All access tokens have a unique value. This is the string that is ``` "Unique" in which sense? Between the parties at the time of usage, between the parties at any time, within the entire domain, globally? ### Section 2.1.1, paragraph 3 ``` The format and content of the access token value is opaque to the client software. While the client software needs to be able to carry and present the access token value, the client software is never expected nor intended to be able to understand the token value itself. ``` Will it need to understand it sufficiently to determine that it is unique in some way? (See above.) Also, this concept of opaqueness comes up in other parts of the document, and it would be good to clarify if the various parties involved in this protocol are required to verify that property (and fail operations if it is violated?). ### Section 2.1.2, paragraph 3 ``` In a [JWT] formatted token or a token introspection response, this corresponds to the iss claim. ``` What is an "iss claim"? (A reference may be helpful.) ### Section 2.1.3, paragraph 2 ``` In a [JWT] formatted token or token introspection response, this corresponds to the aud claim. ``` What is an "aud claim"? (A reference may be helpful.) ### Section 5.3, paragraph 4 ``` * the format's definition is sufficiently unique from other formats provided by existing parameters. ``` "sufficiently unique" is pretty vague, and give a lot of leeway to the experts. What would an example of "not sufficiently unique" be? ### Section 5.5, paragraph 4 ``` * the claim's definition is sufficiently orthogonal to other claims defined in the registry so as avoid overlapping functionality. ``` See above, wrt "sufficiently unique". Other registries below have similar verbiage; it would be nice to be a bit more descriptive in what the expert should actually check here. ## Nits All comments below are about very minor potential issues that you may choose to address in some way - or ignore - as you see fit. Some were flagged by automated tools (via https://github.com/larseggert/ietf-reviewtool), so there will likely be some false positives. There is no need to let me know what you did with these suggestions. ### Grammar/style #### Section 2.1.4, paragraph 4 ``` ss_token section of the grant response response in Section 3.2 of [GNAP]. Fo ^^^^^^^^^^^^^^^^^ ``` Possible typo: you repeated a word. #### Section 3.1, paragraph 3 ``` ys by reference or by value in a similar fashion to a client instance callin ^^^^^^^^^^^^^^^^^^^^ ``` Consider replacing this phrase with the adverb "similarly" to avoid wordiness. #### Section 3.3, paragraph 19 ``` oken is no longer valid. Expressed as a integer seconds from UNIX Epoch. iat ^ ``` Use "an" instead of "a" if the following word starts with a vowel sound, e.g. "an article", "an hour". #### Section 3.3, paragraph 20 ``` en was issued by the AS. Expressed as a integer seconds from UNIX Epoch. nbf ^ ``` Use "an" instead of "a" if the following word starts with a vowel sound, e.g. "an article", "an hour". #### Section 3.3, paragraph 20 ``` this token is not valid. Expressed as a integer seconds from UNIX Epoch. aud ^ ``` Use "an" instead of "a" if the following word starts with a vowel sound, e.g. "an article", "an hour". #### Section 6.1, paragraph 1 ``` , a system can follow a principle of least disclosure to each RS. 6.9. Resour ^^^^^ ``` A determiner may be missing. ## Notes This review is in the ["IETF Comments" Markdown format][ICMF], You can use the [`ietf-comments` tool][ICT] to automatically convert this review into individual GitHub issues. Review generated by the [`ietf-reviewtool`][IRT]. [ICMF]: https://github.com/mnot/ietf-comments/blob/main/format.md [ICT]: https://github.com/mnot/ietf-comments [IRT]: https://github.com/larseggert/ietf-reviewtool