Applying review suggestions part 2

Author: Oxyjun

src/content/docs/bots/concepts/bot/verified-bots/web-bot-auth.mdx

@@ -40,21 +40,23 @@ You need to generate a signing key which will be used to authenticate your bot's
 
 By following these steps, you have generated a private key and a public key, then converted the public key to a JWK.
 
+:::note
+You can also [generate a JavaScript key using WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey), which will produce a key in the correct JWK format.
+
+Many existing [JWK libraries](https://jwt.io/libraries) support WebCrypto API for generating JavaScript key.
+:::
+
 ## 2. Host a key directory
 
 You need to host a key directory which creates a way for your bot to authenticate its requests to Cloudflare.
 This directory should follow the definition from the active IETF draft [draft-meunier-http-message-signatures-directory-01](https://datatracker.ietf.org/doc/html/draft-meunier-http-message-signatures-directory-01).
 
 <Steps>
-1. Host a key directory at a well known message signatures directory. The key directory should serve a JSON Web Key Set (JWKS) including the public key derived from your signing key.
-
-   An example directory would be:
-   ```txt
-   /.well-known/http-message-signatures-directory/
-   ```
+1. Host a key directory at `/.well-known/http-message-signatures-directory/` (note that this is a requirement). This key directory should serve a JSON Web Key Set (JWKS) including the public key derived from your signing key.
 2. Serve the web page over HTTPS (not HTTP).
 3. [Calculate the base64 URL-encoded JWK thumbprint](https://www.rfc-editor.org/rfc/rfc8037.html#appendix-A.3) associated with your Ed25519 public key.
 4. Sign your HTTP response using the HTTP message signature specification by attaching one signature per key in your key directory. This ensures no one else can mirror your directory and attempt to register on your behalf. Your response must include the following headers:
+   - `Content-Type`: This header must have the value `application/http-message-signatures-directory+json`.
    - `Signature`: Construct a [`Signature` header](https://www.rfc-editor.org/rfc/rfc9421#name-the-signature-http-field) over your chosen components.
    - `Signature-Input`: Construct a [`Signature-Input` header](https://www.rfc-editor.org/rfc/rfc9421#name-the-signature-input-http-fi) over your chosen components. The header must meet the following requirements.
      | Required component parameter | Requirement                                                                                                                 |
@@ -131,7 +133,12 @@ A component is either an HTTP header, or any [derived components](https://www.rf
   :::note[Use components with only ASCII values]
   Cloudflare currently does not support `bs` or `sf` parameter designed to serialize non-ASCII values into ASCII equivalents.
   :::
-  - Add a `Content-Digest` header if you wish to sign your [message content](https://www.rfc-editor.org/rfc/rfc9421#name-message-content), then specify `Content-Digest` as a component to sign.
+
+:::caution[`Content-Digest` header]
+If you wish to sign your [message content](https://www.rfc-editor.org/rfc/rfc9421#name-message-content) using a `Content-Digest` header, note that you should only do so if there is zero risk of a message being altered on the way to Cloudflare.
+
+For example, if the message is unencrypted and proxied to Cloudflare, you should not use `Content-Digest`.
+:::
 
 ### 4.2. Calculate the JWK thumbprint
 
@@ -190,4 +197,5 @@ You may wish to refer to the following resources.
 - Link to new blog TBC.
 - Cloudflare blog: [Forget IPs: using cryptography to verify bot and agent traffic](https://blog.cloudflare.com/web-bot-auth/).
 - Cloudflare's [`web-bot-auth` library in Rust](https://crates.io/crates/web-bot-auth).
-- Cloudflare's [`web-bot-auth` npm package in Typescript](https://www.npmjs.com/package/web-bot-auth).
+- Cloudflare's [`web-bot-auth` npm package in Typescript](https://www.npmjs.com/package/web-bot-auth).
+-

src/content/docs/bots/frequently-asked-questions.mdx

@@ -186,7 +186,7 @@ Cloudflare supports Ed25519 key algorithm.
 
 The following derived components are not supported, and we will fail to verify a message if they are included:
 
-- `@query-params`: Cloudflare recommends signing the whole query instead of an individual parameter.
+- `@query-params`: Cloudflare recommends signing the whole query using the `@query` component instead of signing an individual parameter.
 - `@status`: This is not possible to include in the request path.
 
 The following component parameters defined in IETF RFC 9421 are not supported, and Cloudflare will fail to verify a message if they are included:
@@ -211,13 +211,13 @@ Instead, Cloudflare recommends short `expires` as a protection against replay at
 
 ### How do I know my JSON Web Key set directory will be accepted?
 
-Cloudflare uses [`http-signature-directory` tool](https://crates.io/crates/http-signature-directory) to validate your directory. Please your this works before submitting a verification request.
+Cloudflare uses [`http-signature-directory` tool](https://crates.io/crates/http-signature-directory) to validate your directory. Please ensure this works against your directory before registering with us.
 
 ---
 
 ### My message is failing validation. What could be the cause?
 
-- Ensure you have a [`Signature-Agent` header](/bots/concepts/bot/verified-bots/web-bot-auth/#signature-agent-header), and that its value in double-quotes.
+- Ensure you have a [`Signature-Agent` header](/bots/concepts/bot/verified-bots/web-bot-auth/#signature-agent-header), and that its value is in double-quotes.
 - Ensure you include `signature-agent` in the component list in your [`Signature-Input` header](/bots/concepts/bot/verified-bots/web-bot-auth/#signature-agent-header).
 - Ensure your `expires` timestamp is not too short, such that, by the time it arrives at Cloudflare servers, it has already expired. A minute is often sufficient.
 - Ensure you are not signing components containing non-ASCII values, or on the unsupported list.