jiebi/TextFlow huggingface dataset:
Original text:
The "@method" derived component refers to the HTTP method of a request message.  The component value is canonicalized by taking the value of the method as a string.  Note that the method name is case- <del> sensitive as per HTTP, and conventionally standardized method names are uppercase US-ASCII. </del>  For example, the following request message:

Reviewer comments:
Clarify method case requirements. Add justification for use of empty query string.
Comment by NAME : >If the query string is absent from the request message, the value is the leading ? character alone: When would it make sense to sign this component although empty? Might be good to add some clarification for the reader.
URL I would drop the "and conventionally standardized method names are uppercase US-ASCII". Method names are case-sensitive, that's what is relevant. The second part somewhat weakens that statement.
This is a note to implementors and doesn't change the normative requirements or behaviors -- I think we should leave it in. Note that the text in question appears in section 9.1 as referenced:
Good catch, and I should have objected to that. Anyway; I don't think it makes sense to note it here. It doesn't help at all - the method name is what appears in the request message. The note doesn't add anything useful, but might cause confusion. Take this ticket as proof.
Having seen people try to normalize things by lowercasing because "it made sense", I disagree that the note doesn't add anything useful. I'd like to leave it in.
Just to clarify: my concern is that implementers will take that as a suggestion to uppercase.

Revised text:
The "@method" derived component refers to the HTTP method of a request message.  The component value is canonicalized by taking the value of the method as a string.  Note that the method name is case-  <ins> sensitive as per HTTP.  While conventionally standardized method names are uppercase US-ASCII, no transformation to the input method value's case is performed. </ins> For example, the following request message:
Original text:
And the following signature base line: <del> If the query string is absent from the request message, the value is the leading "?" character alone: </del>  Resulting in the following signature base line:

Reviewer comments:
Clarify method case requirements. Add justification for use of empty query string.
Comment by NAME : >If the query string is absent from the request message, the value is the leading ? character alone: When would it make sense to sign this component although empty? Might be good to add some clarification for the reader.
URL I would drop the "and conventionally standardized method names are uppercase US-ASCII". Method names are case-sensitive, that's what is relevant. The second part somewhat weakens that statement.
This is a note to implementors and doesn't change the normative requirements or behaviors -- I think we should leave it in. Note that the text in question appears in section 9.1 as referenced:
Good catch, and I should have objected to that. Anyway; I don't think it makes sense to note it here. It doesn't help at all - the method name is what appears in the request message. The note doesn't add anything useful, but might cause confusion. Take this ticket as proof.
Having seen people try to normalize things by lowercasing because "it made sense", I disagree that the note doesn't add anything useful. I'd like to leave it in.
Just to clarify: my concern is that implementers will take that as a suggestion to uppercase.

Revised text:
And the following signature base line:  <ins> Just like including an empty path component, the signer can include an empty query component to indicate that this component is not used in the message.  If the query string is absent from the request message, the component value is the leading "?" character alone: </ins> Resulting in the following signature base line:
Original text:
response, it indicates that the server would like the client to provide the respective Integrity field on future requests.  "Want-Content-Digest" and "Want-Repr-Digest" are of type "Dictionary" where each:

Reviewer comments:
And how users of digests are the ones responsible for deciding what to do if something is ignore.
Great NAME , thank you!
Murray asked: on the email thread, I responded with To which Murray confirmed it would be a reasonable resolution. Lets get this fixed as discussed

Revised text:
response, it indicates that the server would like the client to provide the respective Integrity field on future requests. <ins> Integrity preference fields are only a hint.  The receiver of the field can ignore it and send an Integrity field using any algorithm or omit the field entirely, for example see ex-server-selects- unsupported-algorithm.  It is not a protocol error if preferences are ignored.  Applications that use Integrity fields and Integrity preferences can define expectations or constraints that operate in addition to this specification.  How to deal with an ignored preferences is a scenario that should be considered. </ins> "Want-Content-Digest" and "Want-Repr-Digest" are of type "Dictionary" where each:
Original text:
could include additional information known to the application, such as an external host name.  When choosing these parameters, an application of HTTP message signatures has to ensure that the verifier will have access to all required information needed to re-create the signature base.  For

Reviewer comments:
This is a non-normative suggestion for applications to define what to do when a signature is invalid.
This is not necessarily a spec issue, but I thought it should be recorded and maybe discussed here. Is there a recommendation how a server should respond when a request is signed but the signature is invalid. It's likely a 400, unless we want to define a more specific code? Maybe a pointer to the HTTP problem format would be useful?
Good question. If one was using signatures for authentication would 401 be correct? Clearly an additional error message would be useful.
This really depends on how the signature is applied, and I don't think that the signatures spec should really have a strong opinion on the matter.
I agree it depends on signature, but a bit of confrontation is beneficial. Even some non-normative guidance is ok to me. WDYT about: 400 in a generic case (malformed signature) 401/403 if signature is used for authnz This is the case of Content-Encoding and Content-Type. Eg.
Is this the problem format document: URL ?
Almost: URL
I like the approach in PR to make a suggestion on the error codes and leave it up to the application to determine what makes sense in its context.

Revised text:
could include additional information known to the application, such as an external host name. <ins> The error messages and codes that are returned from the verifier to the signer when the signature is invalid, the key material is inappropriate, the validity time window is out of specification, a component value cannot be calculated, or any other errors in the signature verification process.  For example, if a signature is being used as an authentication mechanism, an HTTP status code of 401 Unauthorized or 403 Forbidden could be appropriate.  If the response is from an HTTP API, a response with an HTTP status code of 400 Bad Request could include details as described in RFC7807, such as an indicator that the wrong key material was used. </ins> When choosing these parameters, an application of HTTP message signatures has to ensure that the verifier will have access to all required information needed to re-create the signature base.  For
Original text:
This specification intentionally defines strict parsing and serialization behaviors using step-by-step algorithms; the only error <del> handling defined is to fail the operation altogether. </del>  It is designed to encourage faithful implementation and good interoperability.  Therefore, an implementation that tried to be

Reviewer comments:
... or it's a clarification that aligns the text in the two different sections. Sounds like we should discuss on list.
I still dont understand why we have some of the "strict" stuff in 1.1 and some in 4.2. I would move the paragraph from 4.2 to 1.1 to improve the chance people actually read it.
Disagree; implementers are more likely to look at the parsing section, not what they perceive as boilerplate at the top. 1.1 covers the philosophy and general approach; 4.2 talks about the implementation details.
"This is intentionally strict […]" sounded philosophical to me, but whatever :-)
URL It appears that some read the last sentence: as saying that the generic draconian handling of parsing errors can be relaxed.
It's saying that a generic parser will fail, but the field-specific handling of that failure might do somthing else, including try to parse the field using an alternative method. SF cannot constrain what a field does with the output of parsing.
That sounds like "we require draconian error handling, but if there's an error, you are free to do something else". Of course we can't force anybody not to do that, but we should be clear that this is not what the spec says.

Revised text:
This specification intentionally defines strict parsing and serialization behaviors using step-by-step algorithms; the only error  <ins> handling defined is to fail the entire operation altogether. </ins> It is designed to encourage faithful implementation and good interoperability.  Therefore, an implementation that tried to be
Original text:
most situations, violating field-specific constraints should have the same effect.  Thus, if a header is defined as an Item and required to be an Integer, but a String is received, the field will by default be <del> ignored.  If the field requires different error handling, this should be explicitly specified. </del>  Both Items and Inner Lists allow parameters as an extensibility mechanism; this means that values can later be extended to

Reviewer comments:
... or it's a clarification that aligns the text in the two different sections. Sounds like we should discuss on list.
I still dont understand why we have some of the "strict" stuff in 1.1 and some in 4.2. I would move the paragraph from 4.2 to 1.1 to improve the chance people actually read it.
Disagree; implementers are more likely to look at the parsing section, not what they perceive as boilerplate at the top. 1.1 covers the philosophy and general approach; 4.2 talks about the implementation details.
"This is intentionally strict […]" sounded philosophical to me, but whatever :-)
URL It appears that some read the last sentence: as saying that the generic draconian handling of parsing errors can be relaxed.
It's saying that a generic parser will fail, but the field-specific handling of that failure might do somthing else, including try to parse the field using an alternative method. SF cannot constrain what a field does with the output of parsing.
That sounds like "we require draconian error handling, but if there's an error, you are free to do something else". Of course we can't force anybody not to do that, but we should be clear that this is not what the spec says.

Revised text:
most situations, violating field-specific constraints should have the same effect.  Thus, if a header is defined as an Item and required to be an Integer, but a String is received, the field will by default be  <ins> ignored.  If the field requires different handling for type mismatches it should be explicitly specified, but note that field definitions cannot override how parsing failures are handled. </ins> Both Items and Inner Lists allow parameters as an extensibility mechanism; this means that values can later be extended to
Original text:
defined as an sf-string is allowed to fail when processing this field section: <del> If parsing fails - including when calling another algorithm - the entire field value MUST be ignored (i.e., treated as if the field were not present in the section).  This is intentionally strict, to improve interoperability and safety, and specifications referencing this document are not allowed to loosen this requirement. </del>  Note that this requirement does not apply to an implementation that is not parsing the field; for example, an intermediary is not

Reviewer comments:
... or it's a clarification that aligns the text in the two different sections. Sounds like we should discuss on list.
I still dont understand why we have some of the "strict" stuff in 1.1 and some in 4.2. I would move the paragraph from 4.2 to 1.1 to improve the chance people actually read it.
Disagree; implementers are more likely to look at the parsing section, not what they perceive as boilerplate at the top. 1.1 covers the philosophy and general approach; 4.2 talks about the implementation details.
"This is intentionally strict […]" sounded philosophical to me, but whatever :-)
URL It appears that some read the last sentence: as saying that the generic draconian handling of parsing errors can be relaxed.
It's saying that a generic parser will fail, but the field-specific handling of that failure might do somthing else, including try to parse the field using an alternative method. SF cannot constrain what a field does with the output of parsing.
That sounds like "we require draconian error handling, but if there's an error, you are free to do something else". Of course we can't force anybody not to do that, but we should be clear that this is not what the spec says.

Revised text:
defined as an sf-string is allowed to fail when processing this field section:  <ins> If parsing fails, either the entire field value MUST be ignored (i.e., treated as if the field were not present in the section), or alternatively the complete HTTP message MUST be treated as malformed. This is intentionally strict to improve interoperability and safety, and field specifications that use Structured Fields are not allowed to loosen this requirement. </ins> Note that this requirement does not apply to an implementation that is not parsing the field; for example, an intermediary is not
Original text:
HTTPS over a mutually-authenticated TLS connection.  Use of the header fields outside that intended use case, however, may undermine the protections afforded by TLS client certificate authentication. <del> Therefore, steps MUST be taken to prevent unintended use, both in sending the header field and in relying on its value. </del>  Producing and consuming the "Client-Cert" and "Client-Cert-Chain" header fields SHOULD be configurable options, respectively, in a TTRP

Reviewer comments:
AD review feedback (thread at URL) and some minor editorial updates
thanks Mike, nits have been addressed
Looks good; two nits.

Revised text:
HTTPS over a mutually-authenticated TLS connection.  Use of the header fields outside that intended use case, however, may undermine the protections afforded by TLS client certificate authentication.  <ins> Therefore, steps such as those described below need to be taken to prevent unintended use, both in sending the header field and in relying on its value. </ins> Producing and consuming the "Client-Cert" and "Client-Cert-Chain" header fields SHOULD be configurable options, respectively, in a TTRP
Original text:
The communication between a TTRP and backend server needs to be secured against eavesdropping and modification by unintended parties. <del> The configuration options and request sanitization are necessarily functionally of the respective servers.  The other requirements can </del>  be met in a number of ways, which will vary based on specific deployments.  The communication between a TTRP and backend or origin server, for example, might be authenticated in some way with the

Reviewer comments:
AD review feedback (thread at URL) and some minor editorial updates
thanks Mike, nits have been addressed
Looks good; two nits.

Revised text:
The communication between a TTRP and backend server needs to be secured against eavesdropping and modification by unintended parties.  <ins> The configuration options and request sanitization are necessary functionality of the respective servers.  The other requirements can </ins> be met in a number of ways, which will vary based on specific deployments.  The communication between a TTRP and backend or origin server, for example, might be authenticated in some way with the
Original text:
<del> tus - Resumable Uploads Protocol </del>  draft-ietf-httpbis-resumable-upload-latest Abstract

Reviewer comments:
Closes URL
I suspect a title like "HTTP Resumable Uploads" or "Resumable Uploads for HTTP" would be more clear -- not referring to HTTP will pull in readers looking for other things, and calling it a protocol reinforces that it's separate, when we're trying to make it an extension to an existing protocol.
Good idea to include HTTP in the title! I updated the PR.
Great suggestions, Lucas! Thank you very much!
LGTM, thanks for picking it the pen.
The title of the resumable uploads draft starts with "tus", which is a little weird as the inclusion is entirely unexplained. If the intent is to acknowledge something, might I suggest the Acknowledg[e]ments section.
Agreed. I think this helped during the "pitch period" as a differentiator for this proposal vs others. However, now its an adopted document the lone use of the term is odd. I'll prepare a PR that gives a nod back to the tus v1 spec that inspired this.
+1
I opened a PR for this: URL NAME Let me know if you had something different in mind.

Revised text:
 <ins> Resumable Uploads for HTTP </ins> draft-ietf-httpbis-resumable-upload-latest Abstract
Original text:
6.5. <del> The checksum of an encrypted payload can change between different messages depending on the encryption algorithm used; in those cases its value could not be used to provide a proof of integrity "at rest" unless the whole (e.g. encoded) content is persisted. </del>  6.6.

Reviewer comments:
some content-coding are "not deterministic" ;) not only encryption-related ones.
NAME great! I applied them :) Feel free to merge!
merged, thanks
James Manger wrote:
yeah I think RFC 8188 was the target of the section here. NAME can you recall? What can we add to make this section a bit more clear?
That's correct. And the suggestion wrt different compression levels is correct to! This is worth mentioning and maybe highlight that it applies to a specific kind of content codings.

Revised text:
6.5.  <ins> Content coding mechanisms can support different encoding parameters, meaning that the same input content can produce different outputs. For example, GZIP supports mulitple compression levels.  Such encoding parameters are generally not communicated as representation metadata, for instance different compression levels would all use the same "Content-Encoding: gzip" field.  Other examples include where encoding relies on nonces or timestamps, such as the aes128gcm content coding defined RFC8188. Since it is possible for there to be variation within content coding, the checksum conveyed by the integrity field cannot be used to provide a proof of integrity "at rest" unless the whole (e.g. encoded) content is persisted. </ins> 6.6.
Original text:
examples of Repr-Digest and Want-Repr-Digest fields in message exchanges. <del> algorithms bootstraps a new IANA registry hash algorithms and defines registration procedures for future entries. </del>  1.2.

Reviewer comments:
Murray suggested some things that we could change about the way new IANA registry was being handled. This change: tries to make it clearer that this document uses a new registry that we will need IANA to create moves rote IANA instructions to the IANA considerations better highlights interesting hash algorithm considerations for implmenters clarifies the registration procedure and expands on the expectations for the Designated Expert(s)

Revised text:
examples of Repr-Digest and Want-Repr-Digest fields in message exchanges.  <ins> algorithms presents hash algorithm considerations and defines registration procedures for future entries. </ins> 1.2.
Original text:
the IANA Hash Algorithms for HTTP Digest Fields registry; see establish-hash-algorithm-registry. <del> The "standard" algorithms listed in this document are suitable for many purposes, including adversarial situations where hash functions might need to provide resistance to collision, first-preimage and second-preimage attacks.  Algorithms listed as "insecure" either provide none of these properties, or are known to be weak (see NO-MD5 and NO-SHA). For adversarial situations, which of the "standard" algorithms are acceptable will depend on the level of protection the circumstances demand.  As there is no negotiation, endpoints that depend on a digest for security will be vulnerable to attacks on the weakest algorithm they are willing to accept. </del> Transition from weak algorithms is supported by negotiation of hashing algorithm using "Want-Content-Digest" or "Want-Repr-Digest" (see want-fields) or by sending multiple digests from which the

Reviewer comments:
Murray suggested some things that we could change about the way new IANA registry was being handled. This change: tries to make it clearer that this document uses a new registry that we will need IANA to create moves rote IANA instructions to the IANA considerations better highlights interesting hash algorithm considerations for implmenters clarifies the registration procedure and expands on the expectations for the Designated Expert(s)

Revised text:
the IANA Hash Algorithms for HTTP Digest Fields registry; see establish-hash-algorithm-registry.  Transition from weak algorithms is supported by negotiation of hashing algorithm using "Want-Content-Digest" or "Want-Repr-Digest" (see want-fields) or by sending multiple digests from which the
Original text:
While algorithm agility allows the migration to stronger algorithms it does not prevent the use of weaker algorithms.  Integrity fields <del> do not provide any mitigiations for downgrade or substitution attacks </del>  (see Section 1 of RFC6211) of the hashing algorithm.  To protect against such attacks, endpoints could restrict their set of supported algorithms to stronger ones and protect the fields value by using TLS

Reviewer comments:
Murray suggested some things that we could change about the way new IANA registry was being handled. This change: tries to make it clearer that this document uses a new registry that we will need IANA to create moves rote IANA instructions to the IANA considerations better highlights interesting hash algorithm considerations for implmenters clarifies the registration procedure and expands on the expectations for the Designated Expert(s)

Revised text:
While algorithm agility allows the migration to stronger algorithms it does not prevent the use of weaker algorithms.  Integrity fields  <ins> do not provide any mitigations for downgrade or substitution attacks </ins> (see Section 1 of RFC6211) of the hashing algorithm.  To protect against such attacks, endpoints could restrict their set of supported algorithms to stronger ones and protect the fields value by using TLS