jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-gnap-core-protocol

Commentary: Minor typos 
 Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-204 - -gnap - core - protocol - editors- 
 within ( and likely other sections ) , the property names are plural , but the text sometimes refers to the singular property names . This should be cleaned up to be consistent one way or another .
Paragraph (version A):
When neither an access token nor key proof are used, this is an
unsecured request.  This type of used only for calls to the RS
during a discovery phase as described in rs-request-without-token.
Paragraph (version B):
When neither an access token nor key proof are used, this is an
unsecured request.  This type of request is used only for calls to
the RS during a discovery phase as described in rs-request-
without-token.
Paragraph (version A):
While it is expected that many APIs will have its own properties, a
set of common properties are defined here.  Specific API
implementations SHOULD NOT re-use these fields with different
semantics or syntax.  The available values for these properties are
determined by the API being protected at the RS.
Paragraph (version B):
While it is expected that many APIs will have their own properties, a
set of common properties are defined here.  Specific API
implementations SHOULD NOT re-use these fields with different
semantics or syntax.  The available values for these properties are
determined by the API being protected at the RS.
Paragraph (version A):
The access requested for a given object when using these fields is
the cross-product of all fields of the object.  That is to say, the
object represents a request for all "action" values listed within the
object to be used at all "locations" values listed within the object
for all "datatype" values listed within the object.  Assuming the
request above was granted, the client instance could assume that it
would be able to do a "read" action against the "images" on the first
server as well as a "delete" action on the "metadata" of the second
server, or any other combination of these fields, using the same
access token.
Paragraph (version B):
The access requested for a given object when using these fields is
the cross-product of all fields of the object.  That is to say, the
object represents a request for all "action" values listed within the
object to be used at all "location" values listed within the object
for all "datatype" values listed within the object.  Assuming the
request above was granted, the client instance could assume that it
would be able to do a "read" action against the "images" on the first
server as well as a "delete" action on the "metadata" of the second
server, or any other combination of these fields, using the same
access token.
Draft: draft-ietf-gnap-core-protocol

Commentary: The specification does n't mention the Cache - Control header , as well as the Content - Type header for the responses . This is the 1st step to add this information . All examples of responses may also include this header . Right now , it 's true for a few examples . I am unsure if it 's necessary to include a bit obsolete header Pragma . 
 Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-199 - -gnap - core - protocol - editors- 
 This seems like it 's still in progress , so I 've marked it as a draft for now . Would like to see more input on the right behavior around cache control headers here . 
 There is no place for the Pragma header . This header is actually for a request , not a response , and it ’s for backward compatibility for ancient HTTP 1.0 . explains what this header does . There was even about the improper use of this header . The draft for OAuth 2.1 ( which is currently under development ) still suggests using it . Although , I do n’t really think it does it for some particular purpose other than historical reasons . I believe " Cache - Control : no - store ” will be sufficient . 
 do you still want me to provide more inputs on this one ? 
 Roles : Editor 's note : The names for the roles are an area of ongoing discussion within the working group , as is the appropriate precision of what activities and expectations a particular role covers . In particular , the AS might be formally decomposed into delegation components , that the client talks to , and interaction components , that the user talks to . Several alternative names have been proposed for different roles and components , including :   ( for   )   ( for Resource Client ) Operator ( for Requesting Party ) See also 
 Part of the terminology 
 Process comment : I suggest to move the top note over to and close this one as Duplicate . 
 Closing as duplicate
Paragraph (version A):
The request MUST be sent as a JSON object in the body of the HTTP
POST request with Content-Type "application/json", unless otherwise
specified by the signature mechanism.
Paragraph (version B):
The request and response MUST be sent as a JSON object in the body of
the HTTP POST request with Content-Type "application/json", unless
otherwise specified by the signature mechanism.
Paragraph (version B):
The authorization server MUST include the HTTP "Cache-Control"
response header field RFC7234 with a value set to "no-store".
Draft: draft-ietf-gnap-core-protocol

Commentary: Changes field to , adds to DPoP definition for parity with other JOSE signature methods . 
 Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-195 - -gnap - core - protocol - editors- 
 The signature methods all need to cover the access token , but the  method currently does not . We can add the method used in the and methods . 
 The FAPI WG is proposing a similar DPoP profile : This uses the field instead of , and we could align with that . 
 Convergence would be helpful , do we know the status of the document ? 
 Is this something that can be standardized in , even as a best practice or recommendation ? Trying to align with all documents out there is not a long time strategy ... 
 I 've reached out to the OAuth WG on the topic of defining the field in  itself . If that happens we can remove this field from our spec , but until that happens then it makes sense to keep  and GNAP aligned , for now . 
 Regarding alignment between FAPI and GNAP ... DPoP describes " htu " as while GNAP as which obviously is n't the same .
Paragraph (version A):
Digest of the request body as the value of the Digest header
defined in RFC3230.
Paragraph (version B):
Digest of the request body as the value of the Digest header
defined in RFC3230.  When a request contains a message body, such
as a POST or PUT request, this field is REQUIRED.
Draft: draft-ietf-gnap-core-protocol

Commentary: Suggested changes for They could be also simplified to something like 
 Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-183 - -gnap - core - protocol - editors- 
 Sections " 9 Discovery " states that It makes sense to specify that this URL should be using HTTPS . I also do n't think you want to allow using the fragment component in it , as well as query parameters . The query parameters could be arguable though ... 
 This definition should be beyond just the discovery portion -- this endpoint is fundamental to the protocol and it does need to be protected . We can at least mention that it starts with HTTPS here . Prohibiting fragments makes sense , but prohibiting query parameters or any other URL portion does not make sense , though , as that could be important to an AS 's deployment . However , the client instance always takes this string as - is and does n't add or modify anything , and it always makes a POST to it . 
 I 've reused the definition of . That is a very precise one IMO .
Paragraph (version A):
REQUIRED.  The full URL of the AS's grant request endpoint.  This
MUST match the URL the client instance used to make the discovery
request.
Paragraph (version B):
REQUIRED.  The location of the AS's grant request endpoint.  The
location MUST be a URL RFC3986 with a scheme component that MUST
be https, a host component, and optionally, port, path and query
components and no fragment components.  This URL MUST match the
URL the client instance used to make the discovery request.
Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-179 - -gnap - core - protocol - editors- 
 One small change needed ( marked ) but otherwise good !
Paragraph (version A):
protected API (Application Programming Interface) served by a RS
and that can be accessed by a client, if and only if a valid
access token is provided.  Note: to avoid complex sentences, the
specification document may simply refer to resource instead of
protected resource.
Paragraph (version A):
ability given to a subject to perform a given operation on a
resource under the control of a RS.
Paragraph (version B):
protected API (Application Programming Interface) served by an RS
and that can be accessed by a client, if and only if a valid
access token is provided.  Note: to avoid complex sentences, the
specification document may simply refer to resource instead of
protected resource.
Paragraph (version B):
ability given to a subject to perform a given operation on a
resource under the control of an RS.
Paragraph (version A):
the client instance and handle time outs appropriately.
Paragraph (version B):
the client instance and handle timeouts appropriately.
Paragraph (version A):
An identifier this client instance instance can use to identify
itself when making future requests.
Paragraph (version A):
An identifier this client instance instance can use to identify
its current end-user when making future requests.
Paragraph (version B):
An identifier this client instance can use to identify itself when
making future requests.
Paragraph (version B):
An identifier this client instance can use to identify its current
end-user when making future requests.
Draft: draft-ietf-gnap-core-protocol

Commentary: Remove closed links note that is pending close -close when ready for merge 
 Deploy preview for gnap - core - protocol - editors - draft ready ! Built with commit https://deploy - preview-172 - -gnap - core - protocol - editors- 
 Detached  :  's note : It 's not the usual practice to put additional information into the header of a JWS , but this keeps us from having to normalize the body serialization . Alternatively , we could add all these fields to the body of the request , but then it gets awkward for non - body requests like GET / DELETE . Attached JWS :  's note : It 's not the usual practice to put additional information into the header of a JWS , but this keeps us from having to modify the body to use this signature method . Alternatively , we could add all these fields to the body of the request , but then it gets awkward for non - body requests like GET / DELETE . 
 This is a design choice . What ca n't be done or what is made difficult by what is currently in the text ? Please advise or will be closed . 
 Needs to be referenced in - there are definite trade - offs with the different signature options and they need to be considered 
 Receive a Callback After Interaction : Editor 's note : Should we enforce the callback URI to be unique per request ? That helps with some fixation attacks , but not with others , and it would be problematic for an AS that wants to lock down each client instance to a single callback instead of a family / pattern of callbacks . 
 Editors suggest closing as there are valid reasons for an AS to require an exact match of a single callback URI , such as establishing a client 's identity without any pre - registration . 
 What are the attacks that are still possible with a unique callback URL ? AS already lock down from a family or URLs . Or the callback could be a fixed URL with a parameter that makes the URL unique . 
 The question in this issue is whether to require unique URLs , or whether the current text that allows stable URLs as well as unique URLs is okay . Stable redirect URLs have a number of advantages , such as being able to be compared with exact string matching rather than needing to parse the URL and compare host / path / query / etc components . If the AS needs to be able to parse the URL , that opens up a whole world of that are avoided with simple string matching .
Paragraph (version B):
during the interaction phase before redirect.
Draft: draft-ietf-gnap-core-protocol

Commentary: and 
 Thanks , I missed that ! 
 I do n't understand why this mode is needed ? Its also problematic having a boolean or a number as valid parameters for 
 Polymorphism in the protocol is discussed as part of a larger design question in The short redirect was suggested in early WG ( or even pre - WG ) design discussions to allow the client to request a redirect URI with limitations on its final length , to facilitate the client communicating it to the user in limited ways . There are still a lot of questions about this including whether it stays switched like this and what the error / failure modes would be , 
 Thanks for the explanation , it would be good to link this to a documented use case - I could n't see one in the wiki . I 'll leave a comment in as I think that a high level polymorphism is a good fit for the protocol , but it should be used sparingly . I see no reason for it to be used here . 
 If we are to shorten the URL ( which is a valid use case , especially if a user needs to copy paste it manually from a constrained device to some other browsing device ) , then it seems logical to really limit the value instead of defining an " integer indicating the maximum character length of the returned URL " ( 255 in the example ) . For the manual use case , it seems too big to be practical , and there are other conditions besides length that matter ( which set of characters , entropy threshold , etc . ) . See for instance ( it 's not the only way to do that ) , and its demo This means we could avoid parameters , and choose a predefined setting that does the job . ! 
 For things you expect a human to type , you should be using the method with a static URL instead since it allows you to separate the human - memorable part from the URL part . The drive for this mode was for clients that had limited capabilities in display but could still communicate something as long and complex as a URI . For what it 's worth , I personally do n't think we need this mode and would be fine if we dropped this function . 
 Ok makes sense . Also think it could be dropped because it 's a bit confusing . 
 Unless there ’s a specific use case this enables that we can document in the spec I would also be in favor of dropping this mode . 
  to an Arbitrary Shortened URL Or maybe just ignore this part of the interaction request ?
Paragraph (version A):
In this non-normative example, the client instance is indicating that
it can display a request-interact-usercode and direct the RQ to an
request-interact-short 255 characters, but it cannot accept a
callback.
Paragraph (version B):
In this non-normative example, the client instance is indicating that
it can display a request-interact-usercode and direct the RQ to an
request-interact-redirect on a secondary device, but it cannot accept
a callback.
Paragraph (version A):
If this interaction mode is supported for this client instance and
request, the AS returns a redirect interaction response with short
URL response-interact-redirect.
Draft: draft-ietf-gnap-core-protocol

Commentary: iss - sub was renamed to iss_sub in draft -06 of secevent identifiers drop unnecessary hyphenation the initial introduction sentence still might need some more significant rewording
Paragraph (version A):
This protocol allows a piece of software, the resource client, to
request delegated authorization to resource servers and direct
information.  This delegation is facilitated by an authorization
server usually on behalf of a resource owner.  The requesting party
operating the software may interact with the authorization server to
authenticate, provide consent, and authorize the request.
Paragraph (version B):
This protocol allows a piece of software, the resource client, to
request delegated authorization to resource servers and to request
direct information.  This delegation is facilitated by an
authorization server usually on behalf of a resource owner.  The
requesting party operating the software may interact with the
authorization server to authenticate, provide consent, and authorize
the request.
Paragraph (version A):
In some circumstances, the information needed at a given stage is
communicated out-of-band or is pre-configured between the components
or entities performing the roles.  For example, one entity can fulfil
multiple roles, and so explicit communication between the roles is
not necessary within the protocol flow.
Paragraph (version B):
In some circumstances, the information needed at a given stage is
communicated out of band or is preconfigured between the components
or entities performing the roles.  For example, one entity can fulfil
multiple roles, and so explicit communication between the roles is
not necessary within the protocol flow.
Paragraph (version A):
The b (body hash) field MUST be calculated and supplied, unless
there is no entity body (such as a GET, OPTIONS, or DELETE
request).
Paragraph (version B):
The "b" (body hash) field MUST be calculated and supplied, unless
there is no entity body (such as a GET, OPTIONS, or DELETE
request).
Draft: draft-ietf-gnap-core-protocol

Commentary: This fixes up a dangling statement from the design team draft that somehow never got completed . It 's technically a new normative statement but it was clearly intended by the context so this is not a functional or substantive change . Other changes are small formatting issues .
Paragraph (version B):
When used to bind to an access token, the access token MUST be
covered by the signature method.
Draft: draft-ietf-gnap-core-protocol

Commentary: Thanks !
Paragraph (version A):
The process by which a the RC requests and is given delegated
access to the RS by the AS through the authority of the RO.
Paragraph (version B):
The process by which the RC requests and is given delegated access
to the RS by the AS through the authority of the RO.