jiebi/TextFlow huggingface dataset:
Original text:
client instance wants to optimize its calls to the AS before making a request, it MAY send an HTTP OPTIONS request to the grant request endpoint to retrieve the server's discovery information.  The AS MUST <del> respond with a JSON document containing the following information: </del>  The information returned from this method is for optimization purposes only.  The AS MAY deny any request, or any portion of a

Reviewer comments:
The specification can also say a bit stricter A response MUST use the 200 OK (HTTP status code) and return a JSON object using content type.
Deploy Preview for gnap-core-protocol-editors-draft ready! Explore the source changes: 9f7633b4fd5b90bbac20a33ade1e56045a47b3c1 Inspect the deploy log: Browse the preview:

Revised text:
client instance wants to optimize its calls to the AS before making a request, it MAY send an HTTP OPTIONS request to the grant request endpoint to retrieve the server's discovery information.  The AS MUST  <ins> respond with a JSON document with Content-Type "application/json" containing a single object with the following information: </ins> The information returned from this method is for optimization purposes only.  The AS MAY deny any request, or any portion of a
Original text:
Dynamically generated client instance identifiers are string values that MUST be protected by the client instance as secrets.  Instance identifier values MUST be unguessable and MUST NOT contain any <del> sensitive information.  Instance identifier values are opaque to the client instance. </del>  This non-normative example shows an instance identifier along side an issued access token.

Reviewer comments:
Deploy Preview for gnap-core-protocol-editors-draft ready! Explore the source changes: 7e9a352ebd6b48adb5f0a834a94bd083c38cb53c Inspect the deploy log: Browse the preview:
The text says: protected by the client instance as secrets. Instance identifier values MUST be unguessable and MUST NOT contain any sensitive information. This is weird, because we're saying both that they should be treated as secrets and that they are not sensitive. I would suggest instead: protected by the client instance as secrets. Instance identifier values MUST be unguessable and MUST NOT contain any information that would compromise the AS if revealed.
We're not saying that they're not sensitive, we're saying that they can't contain sensitive information. This is like saying your password is sensitive and it also shouldn't contain your medical record number at your hospital, because that's also a sensitive piece of information. Still I think the wording is an improvement, thanks!
I agree the proposed wording is better, thanks !

Revised text:
Dynamically generated client instance identifiers are string values that MUST be protected by the client instance as secrets.  Instance identifier values MUST be unguessable and MUST NOT contain any  <ins> information that would compromise any party if revealed.  Instance identifier values are opaque to the client instance. </ins> This non-normative example shows an instance identifier along side an issued access token.
Original text:
In this example, the AS is returning set of response-subject, simultaneously as an opaque identifier, an email address, and a <del> decentralized identifier URL (DID). </del>  3.1.

Reviewer comments:
updated examples updated examples for httpsig
Deploy Preview for gnap-core-protocol-editors-draft ready! Explore the source changes: a6cdcdcaf974e575a7e246dca7ada0e9b72e25cf Inspect the deploy log: Browse the preview:

Revised text:
In this example, the AS is returning set of response-subject, simultaneously as an opaque identifier, an email address, and a  <ins> decentralized identifier (DID). </ins> 3.1.
Original text:
If the client instance indicates that it can request-interact- usercode and the AS supports this mode for the client instance's <del> request, the AS responds with a "user_code" field.  This field is an object that contains the following members. 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 </del>  function as an authentication factor for the RO. The URI that the end user is intended to enter the code into MUST be

Reviewer comments:
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 .

Revised text:
If the client instance indicates that it can request-interact- usercode and the AS supports this mode for the client instance's  <ins> 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. 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 </ins> function as an authentication factor for the RO. The URI that the end user is intended to enter the code into MUST be
Original text:
error since the client instance will be unable to complete the request without authorization. <del> 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. </del> 2.5.1. This specification defines the following interaction start modes as state, the client instance can repeat the interaction process by sending a continue-modify with new request-interact methods.  4.1. When a grant request is in the 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 <del> method.  The actions of the client instance required for the </del>  interaction start modes defined in this specification are described <del> in the following sections. </del>  4.1.1.

Reviewer comments:
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 aren'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.

Revised text:
error since the client instance will be unable to complete the request without authorization.  2.5.1. This specification defines the following interaction start modes as state, the client instance can repeat the interaction process by sending a continue-modify with new request-interact methods. <ins> 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. </ins> 4.1. When a grant request is in the 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  <ins> start mode.  The actions of the client instance required for the </ins> interaction start modes defined in this specification are described  <ins> in the following sections.  Interaction start modes defined in extensions to this specification MUST define the expected actions of the client software. 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. </ins> 4.1.1.
Original text:
As this interaction mode is designed to facilitate interaction via a secondary device, it is not expected that the client instance <del> redirect the end user to the URL given here at runtime.  If the </del>  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

Reviewer comments:
Requires all URIs to be absolute throughout the protocol.
To edit notification comments on pull requests, go to your ._
While it doesn'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: 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 don'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

Revised text:
As this interaction mode is designed to facilitate interaction via a secondary device, it is not expected that the client instance  <ins> redirect the end user to the URI given here at runtime.  If the </ins> 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
Original text:
9.1. If the client instance calls an RS without an access token, or with <del> an invalid access token, the RS MAY respond to the client instance with an authentication header indicating that GNAP needs to be used to access the resource.  The address of the GNAP endpoint MUST be sent in the "as_uri" parameter.  The RS MAY additionally return a resource reference that the client instance MAY use in its access </del>  token request.  This resource reference MUST be sufficient for at least the action the client instance was attempting to take at the RS and MAY be more powerful.  The means for the RS to determine the

Reviewer comments:
To edit notification comments on pull requests, go to your .
Yaron: "Speculative" access ("Requesting a Resources With Insufficient Access") is not useful if the response is only a MAY. Why would the RC try it if it is unlikely to provide useful information? Justin: I think the MAY is not quite the right normative application here. It’s a MUST if you’re doing it to do it in this way, but it’s not a MUST for all RS’s everywhere to respond in this fashion. If the RC tries calling an RS that doesn’t respond with this, the RC simply doesn’t know, from any programmatic or automated way, what to do to make the request actually work. Yaron: Sounds like a SHOULD to me - then an RC can assume with reasonable confidence that a random RS will implement it.

Revised text:
9.1. If the client instance calls an RS without an access token, or with  <ins> an invalid access token, the RS SHOULD respond to the client instance with a WWW-Authenticate header field indicating that GNAP needs to be used to access the resource.  The address of the GNAP endpoint MUST be sent in the "as_uri" parameter.  The RS MAY additionally return a resource reference that the client instance SHOULD use in its access </ins> token request.  This resource reference MUST be sufficient for at least the action the client instance was attempting to take at the RS and MAY be more powerful.  The means for the RS to determine the
Original text:
The cryptographic methods used by GNAP for key-proofing can support both asymmetric and symmetric cryptography, and can be extended to <del> use a wide variety of mechanisms.  While symmetric cryptographic systems have some benefits in speed and simplicity, they have a distinct drawback that both parties need access to the same key in order to do both signing and verification of the message.  This means that when the client instance calls the AS to request a token, the AS needs to know the exact value of the client instance's key (or be able to derive it) in order to validate the key proof signature. With asymmetric keys, the client needs only to send its public key to the AS to allow for verification that the client holds the associated private key, regardless of whether that key was pre-registered or not with the AS. </del>  When used to bind to an access token, a key value must be known by the RS in order to validate the proof signature on the request.

Reviewer comments:
Built To edit notification comments on pull requests, go to your .
Please take a look a BCP 107 (a.k.a. RFC 4107). You may need a reference here. Originally posted by NAME in URL
Ok but should this text be updated ? In 2005, potential quantum threats were not even anticipated (with impacts on key size for instance)
I think the overall message remains accurate, but you are right that quantum computing was not a concern when RFC 4107 was written. Any updates to RFC 4107 are not part of your task in the GNAP WG.
Sure, thanks for the feedback.

Revised text:
The cryptographic methods used by GNAP for key-proofing can support both asymmetric and symmetric cryptography, and can be extended to  <ins> use a wide variety of mechanisms.  Implementers will find useful the available guidelines on cryptographic key management provided in RFC4107.  While symmetric cryptographic systems have some benefits in speed and simplicity, they have a distinct drawback that both parties need access to the same key in order to do both signing and verification of the message.  This means that when the client instance calls the AS to request a token, the AS needs to know the exact value of the client instance's key (or be able to derive it) in order to validate the key proof signature.  With asymmetric keys, the client needs only to send its public key to the AS to allow for verification that the client holds the associated private key, regardless of whether that key was pre-registered or not with the AS. </ins> When used to bind to an access token, a key value must be known by the RS in order to validate the proof signature on the request.
Original text:
If issued, the resulting access token would contain sufficient access to be used at both referenced resources.  10. The editors would like to thank the feedback of the following

Reviewer comments:
Built To edit notification comments on pull requests, go to your ._
The discovery process defined in GNAP details how to get information about the AS once you know the grant endpoint and can talk directly to it. We do not cover how to get the grant endpoint, except in the one case of it being provided by the RS at runtime in a response. The core document should at least discuss this gap as intentional, and an extension specification (or several) could be written to fill this gap in different circumstances.

Revised text:
If issued, the resulting access token would contain sufficient access to be used at both referenced resources. <ins> 9.2. Additional methods of discovering the appropriate grant endpoint for a given application are outside the scope of this specification. This limitation is intentional, as many applications rely on static configuration between the client instance and AS, as is common in OAuth 2.0.  However, the dynamic nature of GNAP makes it a prime candidate for other extensions defining methods for discovery of the appropriate AS grant endpoint at runtime.  Advanced use cases could define contextual methods for contextually providing this endpoint to the client instance securely.  Furthermore, GNAP's design intentionally requires the client instance to only know the grant endpoint and not additional parameters, since other functions and values can be disclosed and negotiated during the grant process. </ins> 10. The editors would like to thank the feedback of the following
Original text:
12. implementation by David Skyberg.  https://github.com/dskyberg/gnap <del> [2].  Prototype implementation of AS and Client in Rust.  MIT license. </del>  from Interledger Foundation. https://github.com/interledger/rafiki <del> [3] Production implementation of AS in JavaScript.  Apache 2.0 </del>  license. implementation by Aaron Parecki. https://github.com/aaronpk/gnap- <del> client-php [4] Prototype implementation of web application client and </del>  CLI client in PHP, with common support library.  CC0 license. <del> from SUNET. https://github.com/SUNET/sunet-auth-server [5] Production </del>  implementation of AS in Python.  BSD license.  from Bespoke Engineering, implementation by Justin Richer. <del> https://github.com/bspk/oauth.xyz-java [6].  Advanced prototype implementation of AS, Client, and RS in Java, with common support library.  Prototype implementation of SPA Client in pure JavaScript. </del>  Apache 2.0 license. 13. [2] https://github.com/dskyberg/gnap <del> [3] https://github.com/interledger/rafiki </del>  <del> [4] https://github.com/aaronpk/gnap-client-php </del>  <del> [5] https://github.com/SUNET/sunet-auth-server </del>  <del> [6] https://github.com/bspk/oauth.xyz-java </del> 

Reviewer comments:
To edit notification comments on pull requests, go to your .
NAME and NAME -- please check these additions to the implementation section.

Revised text:
12. implementation by David Skyberg.  https://github.com/dskyberg/gnap  <ins> [2] Prototype implementation of AS and client in Rust.  MIT license. from Interop Alliance, implementation by Dmitri Zagidulin. https://github.com/interop-alliance/gnap-client-js [3] Prototype implementation of client in JavaScript.  MIT License. </ins> from Interledger Foundation. https://github.com/interledger/rafiki  <ins> [4] Production implementation of AS in JavaScript.  Apache 2.0 </ins> license. implementation by Aaron Parecki. https://github.com/aaronpk/gnap-  <ins> client-php [5] Prototype implementation of web application client and </ins> CLI client in PHP, with common support library.  CC0 license.  <ins> from SUNET. https://github.com/SUNET/sunet-auth-server [6] Production </ins> implementation of AS in Python.  BSD license. <ins> from SecureKey. https://verified.me/ [7] Production implementation of AS, client and RS.  Proprietary license. </ins> from Bespoke Engineering, implementation by Justin Richer.  <ins> https://github.com/bspk/oauth.xyz-java [8] Advanced prototype implementation of AS, client, and RS in Java, with common support library.  Prototype implementation of SPA client in JavaScript. </ins> Apache 2.0 license. 13. [2] https://github.com/dskyberg/gnap  <ins> [3] https://github.com/interop-alliance/gnap-client-js [4] https://github.com/interledger/rafiki [5] https://github.com/aaronpk/gnap-client-php </ins>  <ins> [6] https://github.com/SUNET/sunet-auth-server </ins>  <ins> [7] https://verified.me/ </ins>  <ins> [8] https://github.com/bspk/oauth.xyz-java </ins>
Original text:
Other message components MAY also be included.  If the signer's key presented is a JWK, the "keyid" parameter of the signature MUST be set to the "kid" value of the JWK, the signing algorithm used MUST be the JWS algorithm denoted by the key's "alg"

Reviewer comments:
To edit notification comments on pull requests, go to your .
From the HTTP message sig spec : "tag: An application-specific tag for the signature as a String value. This value is used by applications to help identify signatures relevant for specific applications or protocols." Fair enough, but does a MUST requirement improve the security of the protocol ?
Yes, because it prevents cross-protocol confusion attacks. Where an attacker tries to use a signed HTTP message from another protocol in GNAP, or vice versa.
This was recently added to HTTP Signatures. Please add a standard value for GNAP messages.
LGTM

Revised text:
Other message components MAY also be included. <ins> The signer MUST include the "tag" signature parameter with the value "gnap", and the verifier MUST verify that the parameter exists with this value.  The signer MUST include the "created" signature parameter with a timestamp of when the signature was created, and the verifier MUST ensure that the creation timestamp is sufficiently close to the current time given expected network delay and clock skew.  The signer SHOULD include the "nonce" parameter with a unique and unguessable value.  When included, the verifier MUST determine that the nonce value is unique within a reasonably short time period such as several minutes. </ins> If the signer's key presented is a JWK, the "keyid" parameter of the signature MUST be set to the "kid" value of the JWK, the signing algorithm used MUST be the JWS algorithm denoted by the key's "alg"
Original text:
attacks as discussed in security-ssrf. When receiving the request, the client instance MUST parse the JSON <del> object and validate the hash value as described in interaction-hash, or else return an "unknown_interaction" error (response-error).  If the hash validates, the client instance sends a continuation request to the AS as described in continue-after-interaction using the interaction reference value received here. </del>  4.2.3.

Reviewer comments:
The current formulation regarding the client instance's validation of a pushed interaction completion notification can be misunderstood as "client instance must either parse JSON & verify hash or return an error", whereas I think the intended meaning is "client instance must parse JSON and verify hash. If either fails, return an error."
Built To edit notification comments on pull requests, go to your .

Revised text:
attacks as discussed in security-ssrf. When receiving the request, the client instance MUST parse the JSON  <ins> object and validate the hash value as described in interaction-hash. If either fails, the client instance MUST return an "unknown_interaction" error (response-error).  If the hash validates, the client instance sends a continuation request to the AS as described in continue-after-interaction using the interaction reference value received here. </ins> 4.2.3.