[Turnstile] Pre-clearance + Hostname Mgmt overhaul (#19373)

* preclearance cookies

* hostname mgmt

* fix

* get started hostnames

* add link

* spacing

* sme feedback

* revert

* Update src/content/docs/turnstile/concepts/pre-clearance-support.mdx

* remove space

Author: patriciasantaana

src/content/docs/turnstile/concepts/hostname-management.mdx

@@ -6,31 +6,61 @@ sidebar:
 
 ---
 
+You can associate hostnames with your widget to control where it can be used using Hostname Management. Managing your hostnames ensures that Turnstile works seamlessly with your setup, whether you add standalone hostnames or leverage zones registered to your Cloudflare account.
+
+## Hostname limits
+
 By default, all widgets can have up to 10 hostnames associated with a widget. A widget requires at least one hostname to be entered.
 
 Only Enterprise Bot Management and Enterprise Turnstile customers can have this limit increased. Contact your account team to increase your hostname limit.
 
-You must specify a list of hostnames when creating a widget. The widget can only be used on these hostnames and will not work on any other hostnames. You can use subdomains to restrict the widgets further.
+## Add a custom hostname
+
+You can add a hostname to your Turnstile widget even if it is not on the Cloudflare network or registered as a zone. There are no prerequisites for using Turnstile. 
+
+To add a custom hostname:
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
+2. Go to **Turnstile**.
+3. On an existing widget, select **Settings**. 
+4. Select **Add Hostnames** under Hostname Management.
+5. Add a custom hostname or choose from an existing hostname.
+6. Select **Add**.
+
+## Add hostnames with a registered zone
+
+If you already have a zone registered with Cloudflare, you can add hostnames during the Turnstile widget setup. You will see all zones registered to your account, where you can select the relevant hostname from the list, and it will be added to your Turnstile widget seamlessly.
+
+## Hostname requirements
+
+When associating hostnames with a widget, follow these requirements:
 
-The hostname should not contain a scheme `http://` or `https://`, a port `443`, or a path `/`.
+- Hostnames must be fully qualified domain names (FQDNs), such as `example.com` or `subdomain.example.com`.
+- Wildcards are not supported. Specify each hostname you want Turnstile to work on.
+- The hostname should not include:
+  - A scheme (for example, `http://` or `https://`)
+  - A port (for example, `443`)
+  - A path (for example, `/path`)
 
-Specifying a subdomain is optional.
+### Subdomain specification 
 
-For example, using the `www.example.com` value will allow widgets on the following hostnames:
+Specifying a subdomain is optional, but it can be used to further restrict the widget. For example, adding `www.example.com` as a hostname will allow widgets to work on:
 
 - `www.example.com`
 - `abc.www.example.com:8080`
 
-but not on the following hostnames:
+However, it will not work on the following hostnames:
 
 - `example.com`
 - `dash.example.com`
 - `cloudflare.com`
 
-When the widget is embedded on a hostname not listed, it will show an error message.
+:::note
+If the widget is embedded on a hostname not listed, it will display an error message.
+:::
 
-## Optional hostname validation
+## Optional hostname validation (Enterprise only)
 
-Customers with Enterprise Bot Management or Enterprise Turnstile can have the optional `any hostname` validation entitlement. 
+Customers with Enterprise Bot Management or Enterprise Turnstile can have the optional any hostname validation entitlement.
 
-By default, a widget requires at least one hostname to be entered. With this entitlement, you can create and use a widget without entering any hostnames for the widget. Contact your account team to enable this entitlement.
+By default, a widget requires at least one hostname to be entered. With this entitlement, you can create and use a widget without entering any hostnames for the widget. Contact your account team to enable this entitlement.

src/content/docs/turnstile/concepts/pre-clearance-support.mdx

@@ -6,46 +6,36 @@ sidebar:
 
 ---
 
-You can integrate Cloudflare challenges on single-page applications (SPAs) by allowing Turnstile to issue a clearance cookie. The clearance level is set upon widget creation or widget modification using the Turnstile API's `clearance_level`. Possible values for the configuration are `no_clearance`, `jschallenge`, `managed`,  or `interactive`. All widgets are set to `no_clearance` by default.
+Pre-clearance in Turnstile allows websites to streamline user experiences by using clearance cookies. These cookies enable visitors to bypass WAF challenges downstream, based on the security clearance level set by the customer. This can be particularly useful for trusted visitors, enhancing usability while maintaining security. 
 
-For Enterprise customers eligible to toggle off domain checks, Cloudflare recommends issuing clearance cookies on widgets where at least one domain is specified.
+You can integrate Cloudflare challenges by allowing Turnstile to issue a pre-clearance cookie. The pre-clearance level is set upon widget creation or widget modification using the Turnstile API's `clearance_level`. Possible values for the configuration are:
+
+- `no_clearance`
+- `jschallenge`
+- `managed`
+- `interactive` 
+
+All widgets are set to `no_clearance` by default.
+
+For Enterprise customers eligible to toggle off domain checks, Cloudflare recommends issuing pre-clearance cookies on widgets where at least one domain is specified.
 
 :::note
 
 Clearance cookies only support zones that are orange-clouded. 
 :::
 
-Refer to the [blog post](https://blog.cloudflare.com/integrating-turnstile-with-the-cloudflare-waf-to-challenge-fetch-requests) for an example of pre-clearance implementation.
+Refer to the [blog post](https://blog.cloudflare.com/integrating-turnstile-with-the-cloudflare-waf-to-challenge-fetch-requests) for more details on how pre-clearance works with WAF.
 
 ## Pre-clearance level options
 
-- **Interactive**: Interactive Pre-clearance allows a user with a clearance cookie to not be challenged by Interactive, Managed Challenge, or JavaScript Challenge Firewall Rules
-- **Managed**: Managed allows a user with a clearance cookie to not be challenged by Managed Challenge or JavaScript Challenge Firewall Rules
-- **Non-interactive**: Non-interactive allows a user with a clearance cookie to not be challenged by JavaScript Challenge Firewall Rules
+- **Interactive (High)**: Allows a user with a clearance cookie to not be challenged by Interactive, Managed Challenge, or JavaScript Challenge Firewall Rules
+- **Managed (Medium)**: Allows a user with a clearance cookie to not be challenged by Managed Challenge or JavaScript Challenge Firewall Rules
+- **Non-interactive (Low)**: Allows a user with a clearance cookie to not be challenged by JavaScript Challenge Firewall Rules
 
-### Duration
+## Clearance cookie duration
 
 Clearance cookies generated by the Turnstile widget will be valid for the time specified by the zone-level Challenge Passage value. To configure the Challenge Passage setting, refer to the [WAF documentation](/waf/tools/challenge-passage/).
 
-## Enable pre-clearance on a new site
-
-1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
-2. Go to **Turnstile** > **Add widget**.
-3. Under **Would you like to opt for pre-clearance for this site?** select **Yes**.
-4. Choose the pre-clearance level from the select box.
-5. Select **Create**.
-
-## Enable pre-clearance on an existing site
-
-1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
-2. Go to **Turnstile**.
-3. Go to the existing widget or site and select **Settings**.
-4. Under **Would you like to opt for pre-clearance for this site?** select **Yes**.
-5. Choose the pre-clearance level from the select box.
-6. Select **Update**.
-
-## Verified bots
-
-If a [verified bot](/bots/concepts/bot/#verified-bots) encounters a page where a Turnstile widget is implemented, the challenge will fail and the verified bot will see a `403` error from the Turnstile endpoint.
+## Setup
 
-However, if a verified bot is excluded from the rule which pre-clearance will grant clearance for, it will pass. Users can create a [WAF custom rule](/waf/custom-rules/) to exclude verified bots.
+To set up pre-clearance cookies, refer to [Enable pre-clearance cookies](/turnstile/get-started/pre-clearance/). 

src/content/docs/turnstile/get-started/index.mdx

@@ -31,7 +31,7 @@ You can find special sitekeys to be used for testing in the [testing](/turnstile
 
 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/turnstile) and select your account.
 2. Go to **Turnstile**.
-3. Select **Add widget** and fill out the site name and your website's hostname or select from your existing websites on Cloudflare.
+3. Select **Add widget** and fill out the site name and [your website's hostname or select from your existing websites](/turnstile/concepts/hostname-management/) on Cloudflare.
 4. Select the widget mode.
 5. (Optional) Opt in for [pre-clearance support](/turnstile/concepts/pre-clearance-support/).
 6. Copy your sitekey and secret key.
@@ -41,8 +41,9 @@ You can find special sitekeys to be used for testing in the [testing](/turnstile
 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/turnstile) and select your account.
 2. Go to **Turnstile**.
 3. In the widget overview, select **Settings**.
-4. (Optional) Opt in for [pre-clearance support](/turnstile/concepts/pre-clearance-support/).
-5. Copy your sitekey and secret key.
+4. Confirm the [hostnames](/turnstile/concepts/hostname-management/) configured. 
+5. (Optional) Opt in for [pre-clearance support](/turnstile/concepts/pre-clearance-support/).
+6. Copy your sitekey and secret key.
 
 ## Add the Turnstile widget to your site
 

src/content/docs/turnstile/get-started/mobile-implementation.mdx

@@ -2,7 +2,7 @@
 title: Mobile implementation
 pcx_content_type: concept
 sidebar:
-  order: 5
+  order: 6
 
 ---
 

src/content/docs/turnstile/get-started/pre-clearance.mdx

@@ -0,0 +1,33 @@
+---
+title: Enable pre-clearance cookies
+pcx_content_type: get-started
+sidebar:
+  order: 3
+  label: Pre-clearance cookies
+
+---
+
+## Prerequisites
+
+To enable pre-clearance, you must ensure that the hostname of the Turnstile widget matches the zone with the WAF rules. During the Turnstile configuration setup in the Cloudflare dashboard, you can see the registered zones. Select the appropriate hostname from this list.
+
+The prerequisite is crucial for pre-clearance to function properly. If set up correctly, visitors who successfully solve Turnstile will receive a cookie with the security clearance level set by the customer. When encountering a WAF challenge on the same zone, they will bypass additional challenges for the configured clearance level and below. 
+
+For more details on managing hostnames, refer to the [Hostname Management documentation](/turnstile/concepts/hostname-management/).
+
+## Enable pre-clearance on a new site
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
+2. Go to **Turnstile** > **Add widget**.
+3. Under **Would you like to opt for pre-clearance for this site?** select **Yes**.
+4. Choose the pre-clearance level from the select box.
+5. Select **Create**.
+
+## Enable pre-clearance on an existing site
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
+2. Go to **Turnstile**.
+3. Go to the existing widget or site and select **Settings**.
+4. Under **Would you like to opt for pre-clearance for this site?** select **Yes**.
+5. Choose the pre-clearance level from the select box.
+6. Select **Update**.

src/content/docs/turnstile/get-started/supported-browsers.mdx

@@ -3,6 +3,6 @@ pcx_content_type: concept
 title: Supported browsers
 external_link: /waf/reference/cloudflare-challenges/#browser-support
 sidebar:
-  order: 4
+  order: 5
 
 ---

src/content/docs/turnstile/get-started/terraform.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: how-to
 title: Terraform
 sidebar:
-  order: 3
+  order: 4
 ---
 
 :::note[Requirements]