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

Commentary: Requires all URIs to be absolute throughout the protocol . 
 To edit notification comments on pull requests , go to your . _ 
 While it does n't say so in the spec and the example suggest otherwise , are relative URLs allowed for properties such as the response . Scenario , an implementation is deployed at a URL : The root of the server handles grant requests : to The application code that builds the response must be able to construct the full URL and therefor have knowledge of the host at which the application is deployed including any path prefix . This is not impossible , but in complex cloud deployments with load balancers and ingress services etc between the application code and the public endpoint this can get ugly . The current example from Section 3.1 of the spec . Implementations would be significantly easier to build if they could simply return : 
 To be clear , the base URL for any relative URL response would be the request URL . 
 Things get really tricky if you start to allow for things like directory ascension ( .. / .. /continue ) and other such things . Lots of attacks in the past stem from exploitation of devices like this . Application deployments that deal with external urls already have techniques for managing such urls , from proxy rewrites to internal configuration . With these together I do n't see a good argument for this being anything but an absolute uri . 
 Is it necessary to state somewhere that all URIs are absolute ? 
 Yes , we should say exactly that , that 's why I am keeping this issue open . Thanks for pointing this out ! 
 Makes sense
Paragraph (version A):
As this interaction mode is designed to facilitate interaction via a
secondary device, it is not expected that the client instance
redirect the end user to the URL given here at runtime.  If the
client instance is capable of communicating an short arbitrary URI to
the end user for use with the user code, the client instance can
instead use the request-interact-usercodeuri method instead.  If the
client instance is capable of communicating a long arbitrary URI to
the end user, such as through a scannable code, the client instance
can use the request-interact-redirect mode for this purpose instead
of or in addition to the user code mode.
Paragraph (version B):
As this interaction mode is designed to facilitate interaction via a
secondary device, it is not expected that the client instance
redirect the end user to the URI given here at runtime.  If the
client instance is capable of communicating an short arbitrary URI to
the end user for use with the user code, the client instance can
instead use the request-interact-usercodeuri method instead.  If the
client instance is capable of communicating a long arbitrary URI to
the end user, such as through a scannable code, the client instance
can use the request-interact-redirect mode for this purpose instead
of or in addition to the user code mode.
Draft: draft-ietf-gnap-core-protocol

Commentary: To edit notification comments on pull requests , go to your . _
Paragraph (version B):
Finally, the editors want to acknowledge the immense contributions of
Aaron Parecki to the content of this document.  We thank him for his
insight, input, and hard work, without which GNAP would not have
grown to what it is.
Draft: draft-ietf-gnap-core-protocol

Commentary: Prepare the draft text for a new release . 
 To edit notification comments on pull requests , go to your . 
 Modifying an Existing Request :  's note : This might be subject to the " multi_token " flag , but since we 're creating a NEW access token and not rotating an existing one , this seems to be a different use case . There is a solid argument to be made for always revoking old access tokens here , but we need more discussion on the boundaries for such a requirement . If they stick around , it does make a " read " request weird because now we 've got multiple access tokens sticking around associated with a grant request and no good place to put them . 
 I do n't think we should put a strict requirement on revoking old access tokens , since it may be difficult or impossible in some implementations . At most this could be a " SHOULD " or " RECOMMENDED " .
Paragraph (version B):
Subject identifiers are hints to the AS in determining the RO and
MUST NOT be taken as declarative statements that a particular RO is
present at the client instance and acting as the end user.
Assertions SHOULD be validated by the AS.
Paragraph (version A):
The "hash_method" value MUST be one of the hash name strings defined
in the IANA Named Information Hash Algorithm Registry [11].
Paragraph (version B):
The "hash_method" value MUST be one of the hash name strings defined
in the IANA Named Information Hash Algorithm Registry [7].
Paragraph (version B):
The client instance MAY include the "access_token" and "subject"
fields as described in request-token and request-subject.  Inclusion
of these fields override any values in the initial request, which MAY
trigger additional requirements and policies by the AS.  For example,
if the client instance is asking for more access, the AS could
require additional interaction with the RO to gather additional
consent.  If the client instance is asking for more limited access,
the AS could determine that sufficient authorization has been granted
to the client instance and return the more limited access rights
immediately.
Paragraph (version B):
The client instance MAY include the "user" field as described in
request-user to present new assertions or information about the end
user.  The AS SHOULD check that this presented user information is
consistent with any user information previously presented by the
client instance for this grant request.
Paragraph (version B):
The client instance MUST NOT include the "client" section of the
request, since the client instance is assumed not to have changed.
Paragraph (version B):
The client instance MUST NOT include post-interaction responses such
as described in continue-after-interaction.
Paragraph (version B):
Modification requests MUST NOT alter previously-issued access tokens.
Instead, any access tokens issued from a continuation are considered
new, separate access tokens.  The AS MAY revoke previously-issued
access tokens after a modification has occurred.
Draft: draft-ietf-gnap-core-protocol

Commentary: To edit notification comments on pull requests , go to your . _ 
 Receive a Callback After Interaction : Editor 's note : This should be expandable via a registry of cryptographic options , and it would be good if we did n't define our own identifiers here . Calculating the interaction hash :  's note : These hash algorithms should be pluggable , and ideally we should n't redefine yet another crypto registry for this purpose , but I 'm not convinced an appropriate one already exists . Furthermore , we should be following best practices here whether it 's a plain hash , a keyed MAC , an HMAC , or some other form of cryptographic function . I 'm not sure what the defaults and options ought to be , but SHA512 and SHA3 were picked based on what was available to early developers . 
 This is probably the right registry to reference : 
 Please add a changelog , but this looks good to me !
Paragraph (version A):
The party then hashes this string with the appropriate algorithm
based on the "hash_method" parameter under the "finish" key.  If the
"hash_method" value is not present in the client instance's request,
the algorithm defaults to "sha3".
Paragraph (version A):
The "sha3" hash method consists of hashing the input string with the
512-bit SHA3 algorithm.  The byte array is then encoded using URL
Safe Base64 with no padding RFC4648.  The resulting string is the
hash value.
Paragraph (version A):
The "sha2" hash method consists of hashing the input string with the
512-bit SHA2 algorithm.  The byte array is then encoded using URL
Safe Base64 with no padding RFC4648.  The resulting string is the
hash value.
Paragraph (version B):
The party then hashes this string with the appropriate algorithm
based on the "hash_method" parameter under the "finish" key.  The
resulting byte array from the hash function is then encoded using
URL-Safe Base64 with no padding RFC4648.  The resulting string is the
hash value.
Paragraph (version B):
The "hash_method" value MUST be one of the hash name strings defined
in the IANA Named Information Hash Algorithm Registry [11].
Paragraph (version B):
If the "hash_method" value is not present in the client instance's
request, the algorithm defaults to "sha3-512".
Paragraph (version B):
For example, the "sha3-512" hash method consists of hashing the input
string with the 512-bit SHA3 algorithm.  The byte array is then
encoded using URL-Safe Base64 with no padding RFC4648.  The resulting
string is the hash value.
Paragraph (version B):
The "sha2-512" hash method consists of hashing the input string with
the 512-bit SHA2 algorithm.  The byte array is then encoded using
URL-Safe Base64 with no padding RFC4648.  The resulting string is the
hash value.
Draft: draft-ietf-gnap-core-protocol

Commentary: Allows interaction responses from the AS to have an explicit timeout , with instructions on how the client instance can recover ( do a modification ) . 
 To edit notification comments on pull requests , go to your . 
 When an AS creates a set of of interaction artifacts , like a user code or interaction URI , these artifacts are n't likely to be available perpetually . The AS will likely want to purge these after some time . It might be useful for the AS to indicate to the client a timeout for the " interact " return block so that the client has some idea of how much time it has to use the interaction methods .
Paragraph (version A):
The AS SHOULD handle any interact request as a one-time-use mechanism
and SHOULD apply suitable timeouts to any interaction mechanisms
provided, including user codes and redirection URIs.  The client
instance SHOULD apply suitable timeouts to any callback URIs.
Paragraph (version B):
The AS SHOULD handle any interact request as a one-time-use mechanism
and SHOULD apply suitable timeouts to any interaction start methods
provided, including user codes and redirection URIs.  The client
instance SHOULD apply suitable timeouts to any interaction finish
method.
Paragraph (version A):
state, the interaction start methods sent by the client instance can
be used to facilitate interaction with the end user.  To initiate an
interaction start method indicated by the response-interact from the
AS, the client instance follows the steps defined by that interaction
method.  The actions of the client instance required for the
interaction start modes defined in this specification are described
in the following sections.
Paragraph (version B):
state, the interaction start methods sent by the client instance can
be used to facilitate interaction with the end user.  To initiate an
interaction start method indicated by the response-interact from the
AS, the client instance follows the steps defined by that interaction
start mode.  The actions of the client instance required for the
interaction start modes defined in this specification are described
in the following sections.  Interaction start modes defined in
extensions to this specification MUST define the expected actions of
the client software.
Paragraph (version B):
If the client instance does not start an interaction start mode
within an AS-determined amount of time, the AS SHOULD reject attempts
to use the interaction start modes.  If the client instance has
already begun one interaction start mode, the AS SHOULD reject
attempts to use other interaction start modes.
Draft: draft-ietf-gnap-core-protocol

Commentary: to update section 4 to provide an additional use case ( RO 's policy ) . I do n't think we need to update the definitions or 
 To edit notification comments on pull requests , go to your . 
 please run on this PR to clean up the line end spaces , otherwise looks good to me . Thanks ! 
 will do ! ( btw , I that to the wiki ) 
 Following the discussion on the mailing list , will plan a rewording to clarify
Mailing list commentary: Thanks for the feedback . There was a rewrite of section 4 ( gathering consent and authorization ) that sought to update this , so if that ’s still not entirely clear that definitely needs another pass . — Justin
Paragraph (version A):
The AS is also allowed to request authorization from more than one
RO, if the AS deems fit.  For example, a medical record might need to
be released by both an attending nurse and a physician, or both
owners of a bank account need to sign off on a transfer request.
Alternatively, the AS could require N of M possible RO's to approve a
given request in order.  The AS could also determine that the end
user is not the appropriate RO for a given request and reach out to
the appropriate RO asynchronously.  The details of determining which
RO's are required for a given request are out of scope for this
specification.
Paragraph (version B):
The AS is also allowed to request authorization from more than one
RO, if the AS deems fit.  For example, a medical record might need to
be released by both an attending nurse and a physician, or both
owners of a bank account need to sign off on a transfer request.
Alternatively, the AS could require N of M possible RO's to approve a
given request in order.  The AS could also determine that the end
user is not the appropriate RO for a given request and reach out to
the appropriate RO asynchronously.
Paragraph (version B):
The RO is also allowed to define a policy at the AS to determine
which kind of end user can get access to the resource, and under
which condition.  For instance, such a condition might require the
end user login and the acceptance of the RO's legal provisions.
Alternatively, client software could be acting without an end user,
and the RO's policy allows issuance of access tokens to instances of
that client software without human interaction.
Paragraph (version B):
The details of determining which RO's or related policies are
required for a given request are out of scope for this specification.
Draft: draft-ietf-gnap-core-protocol

Commentary: Removes the normative suggestion that access right string values be always expandable to objects , but instead adds an example of one way to do it . 
 To edit notification comments on pull requests , go to your . 
 We say : But then we give examples like " some other thing " that clearly do not correspond to anything . We also do n't specify any kind of semantics , such as if I request the reference string , I might get back the expanded access right representation . I suggest to remove or weaken that sentence : 
 I do n't see a reason for it not being a SHOULD -- it provides guidance to API developers that the strings a short - hand for the expanded objects . And since it 's only a SHOULD , the AS is still free to treat it differently . 
 No , this would be a MAY . With a SHOULD , you 're supposed to have a good , documented reason to do something else . Quoting the original , may exist valid reasons in particular circumstances to ignore a particular item , but the full implications must be understood and carefully weighed before choosing a different course . If we keep the SHOULD , our examples in the text should reflect that . 
 Probably we could improve the examples . But as an implementer , I would n't understand what you mean by MAY . Because then it suggests there can be reasonable alternatives to something known to the AS , which I do n't think we have . 
 I 've proposed a change to the text in question in . Also , please note that the example string of is intended to be an actual value , with spaces and all . If it 's not clear that this is a real and valid value in this context , please suggest an alternative that might fit here . We do n't want people to assume that it has the same restrictions as OAuth scopes ( which ca n't have spaces ) .
Paragraph (version A):
Instead of sending an resource-access-rights, access rights MAY be
communicated as a string known to the AS or RS representing the
access being requested.  Each string SHOULD correspond to a specific
expanded object representation at the AS.
Paragraph (version B):
Instead of sending an resource-access-rights, access rights MAY be
communicated as a string known to the AS representing the access
being requested.  Just like access rights communicated as an object,
access rights communicated as reference strings indicate a specific
access at a protected resource.  In the following non-normative
example, three distinct resource access rights are being requested.
Paragraph (version B):
The exact mechanisms for relating reference strings is up to the API
designer.  These are enforced by the AS, and the details are out of
scope for this specification.
Draft: draft-ietf-gnap-core-protocol

Commentary: Expands the key parameter to allow it to be an object or a string , to facilitate methods with multiple parameters such as HTTPSig . 
 To edit notification comments on pull requests , go to your . 
 Some key proofing methods have additional options that could be signaled in the GNAP protocol structure . Notable , HTTP Message Signatures has the ability to use different HTTP   and different HTTP   . The field could be changed to an object to accomodate this kind of use , allowing each proofing method to define its own parameters : Each method can also define " Default " values for missing parameters , allowing this to collapse in the simple case back to a string as it is today : These string values would have a deterministic expansion defined in the core protocol . 
 Note that the httpsig document itself wavers between and and does not require either of them . Though maybe this is OK if the current document makes mandatory for the appropriate cases . 
 There are some updates pending in the Digest draft -- once that 's out , we 'll reference using as that 's the most appropriate for our use case , and examples will be updated .
Paragraph (version B):
Individual methods MAY define additional parameters as members in
this object.
Paragraph (version A):
This method is indicated by "httpsig" in the "proof" field.  The
signer creates an HTTP Message Signature as described in I-D.ietf-
httpbis-message-signatures.
Paragraph (version A):
This method is indicated by "mtls" in the "proof" field.  The signer
presents its TLS client certificate during TLS negotiation with the
verifier.
Paragraph (version B):
This method is indicated by the method value "mtls".  This method
defines no additional parameters.  The signer presents its TLS client
certificate during TLS negotiation with the verifier.
Draft: draft-ietf-gnap-core-protocol

Commentary: Update all diagrams to use AASVG for rendering in HTML . 
 To edit notification comments on pull requests , go to your . _
Paragraph (version A):
The AS determines that interaction is needed and response with a
response-interact-usercode.  This could optionally include a URI
to direct the user to, but this URI should be static and so could
be configured in the client instance's documentation.  The AS also
includes information the client instance will need to response-
continue in (8) and (10).  The AS associates this continuation
information with an ongoing request that will be referenced in
(4), (6), (8), and (10).
Paragraph (version B):
The AS determines that interaction is needed and response with a
response-interact-usercode.  The AS also includes information the
client instance will need to response-continue in (8) and (10).
The AS associates this continuation information with an ongoing
request that will be referenced in (4), (6), (8), and (10).
Paragraph (version A):
The client instance request.  The client instance does not send
any interaction modes to the server, indicating that it does not
expect to interact with the RO.  The client instance can also
signal which RO it requires authorization from, if known, by using
the request-user.
Paragraph (version B):
The client instance request.  The client instance does not send
any interaction modes to the server, indicating that it does not
expect to interact with the RO.  The client instance can also
signal which RO it requires authorization from, if known, by using
the request-user.  It's also possible for the AS to determine
which RO needs to be contacted by the nature of what access is
being requested.
Draft: draft-ietf-gnap-core-protocol

Commentary: Instead of using an object with a single member , the interaction start method now uses a simple string , in line with the and methods . 
 To edit notification comments on pull requests , go to your .
Paragraph (version A):
If the client instance indicates that it can request-interact-
usercode and the AS supports this mode for the client instance's
request, the AS responds with a "user_code" field.  This field is an
object that contains the following members.
Paragraph (version A):
The client instance MUST communicate the "code" to the end user in
some fashion, such as displaying it on a screen or reading it out
audibly.  This code is used by the interaction component of the AS as
a means of identifying the pending grant request and does not
function as an authentication factor for the RO.
Paragraph (version B):
If the client instance indicates that it can request-interact-
usercode and the AS supports this mode for the client instance's
request, the AS responds with a "user_code" field.  This field is
string containing a unique short code that the user can type into a
web page.  This string MUST be case-insensitive, MUST consist of only
easily typeable characters (such as letters or numbers).  The time in
which this code will be accepted SHOULD be short lived, such as
several minutes.  It is RECOMMENDED that this code be no more than
eight characters in length.  REQUIRED.
Paragraph (version B):
The client instance MUST communicate the "user_code" value to the end
user in some fashion, such as displaying it on a screen or reading it
out audibly.  This code is used by the interaction component of the
AS as a means of identifying the pending grant request and does not
function as an authentication factor for the RO.
Draft: draft-ietf-gnap-core-protocol

Commentary: To edit notification comments on pull requests , go to your .
Paragraph (version B):
The calculation of the interaction hash value provides defence in
depth, allowing a client instance to protect itself from spurious
injection of interaction references when using a callback finish
method.  The AS is protected during this attack through the
continuation access token being bound to the expected interaction
reference, but without hash calculation, the attacker could cause the
client to make an HTTP request on command.  With both of these in
place, an attacker attempting to substitute the interaction reference
is stopped in several places.
Paragraph (version B):
Prerequesits: The client instance can allow multiple end users to
access the same AS.  The attacker is attempting to associate their
rights with the target user's session.
Draft: draft-ietf-gnap-core-protocol

Commentary: updated examples updated examples for httpsig 
 Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview :
Paragraph (version A):
In this example, the AS is returning set of response-subject,
simultaneously as an opaque identifier, an email address, and a
decentralized identifier URL (DID).
Paragraph (version B):
In this example, the AS is returning set of response-subject,
simultaneously as an opaque identifier, an email address, and a
decentralized identifier (DID).