[Turnstile] Documentation refresh v2 pt. 1

src/content/docs/turnstile/additional-configuration/ephemeral-id.mdx

@@ -6,18 +6,64 @@ sidebar:
 
 ---
 
-Ephemeral IDs generate a unique short-lived ID that can link behavior to a specific client instead of an IP address without relying on setting any cookies or using similar client-side storage.
+Ephemeral IDs provide device fingerprinting capabilities to enhance bot detection and abuse prevention beyond traditional IP-based methods. Ephemeral IDs are unique, short-lived identifiers that Turnstile generates to link visitor behavior to a specific client device without relying on cookies or client-side storage. They are temporary device fingerprints that help identify patterns of behavior across multiple interactions. Ephemeral ID is an advanced detection method that persists even when attackers change their IP addresses.
 
-When the same visitor interacts with Turnstile widgets from different Cloudflare customers, they receive different Ephemeral IDs for each contact. In attacks where fraudsters attempt to disguise themselves using different IP addresses, Ephemeral IDs detect abuse patterns more accurately than determining whether the visitor is a human or a bot.
+## Process
 
-Ephemeral IDs are not unique and have a lifespan of up to a few days. They can be useful for identifying a bad actor in acute attacks such as sudden spikes in fake account creations or credential stuffing.
+Ephemeral IDs use advanced analysis techniques to create unique identifiers that help find patterns of behavior across multiple interactions. These identifiers are generated dynamically for each visitor interaction with Turnstile widgets.
+
+No cookies or local storage is required. 
+
+Ephemeral IDs are scoped to your Cloudflare account and cannot be shared across accounts. IDs have a short lifespan and expire within a few days. They cannot be used to identify individual users
+
+Ephemeral IDs provide more accurate abuse detection than IP-based methods by linking behavior to individual clients rather than network addresses. This is particularly effective against acute attacks where bad actors try to evade detection, such as credential stuffing and fake account creation attacks.
 
 Refer to the [blog post](https://blog.cloudflare.com/turnstile-ephemeral-ids-for-fraud-detection/) for more information.
 
-## Availability
+---
+
+## Implementation
+
+### Enable Ephemeral IDs
+
+1. Contact your Cloudflare account team to enable Ephemeral ID entitlement for your account. This feature requires Enterprise-level access and cannot be self-activated.
+2. After entitlement is enabled, activate Ephemeral IDs for specific widgets using the Cloudflare API.
 
-Ephemeral IDs are available to Enterprise Bot Management customers with the Enterprise Turnstile add-on or standalone Enterprise Turnstile customers. Contact your account team for access to Ephemeral IDs.
+    ```bash title="cURL command" wrap
+    curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$WIDGET_ID" \
+      -H "Authorization: Bearer $API_TOKEN" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "ephemeral_id": true
+      }'
+    ```
+3. Confirm Ephemeral IDs are active by checking your widget configuration.
 
-## Enablement
+    ```bash title="cURL command" wrap
+    curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$WIDGET_ID" \
+      -H "Authorization: Bearer $API_TOKEN"
+    ```
+
+### Access Ephemeral IDs
+
+Once enabled, Ephemeral IDs are included in Siteverify API responses.
+
+```json title="Siteverify API response" wrap
+{
+  "success": true,
+  "challenge_ts": "2022-02-28T15:14:30.096Z",
+  "hostname": "example.com",
+  "error-codes": [],
+  "action": "login",
+  "cdata": "sessionid-123456789",
+  "metadata": {
+    "ephemeral_id": "x:9f78e0ed210960d7693b167e"
+  }
+}
+```
+
+---
+
+## Availability
 
-After your account team enables the Ephemeral ID entitlement, you must turn it on for the widget that you want the Ephemeral ID on via the [API call](/api/resources/turnstile/subresources/widgets/methods/update/).
+Ephemeral IDs are available to Enterprise Bot Management customers with the Enterprise Turnstile add-on or standalone Enterprise Turnstile customers. Contact your account team for access to Ephemeral IDs.

src/content/docs/turnstile/additional-configuration/hostname-management/any-hostname.mdx

@@ -0,0 +1,73 @@
+---
+title: Any Hostname (Enterprise only)
+pcx_content_type: reference
+sidebar:
+  order: 4
+  label: Any Hostname
+
+---
+
+The Any Hostname feature removes the requirement to specify hostnames during widget creation, allowing widgets to function on any domain.
+
+By default, hostname validation is a security feature that prevents unauthorized use of your widgets. The Any Hostname entitlement removes this restriction, making the hostname field optional during widget creation.
+
+When enabled, widgets can be created without the required hostname specification and used on any domain without pre-configuration. Hostname validation protection is also removed.
+
+## Implementation
+
+To reduce security risks when using Any Hostname, monitor widget usage through [Turnstile Analytics](/turnstile/turnstile-analytics/) to identify unexpected patterns, implement server-side validation with hostname checking in your application code, and use `action` and `cData` parameters to track widget usage sources and identify where widgets are being deployed.
+
+When using the Any Hostname feature, it is essential to implement additional validation in your server-side code to maintain security controls. Always validate the `hostname` field in Siteverify responses.
+
+```js title="Example response"
+async function validateTurnstileWithHostname(token, expectedHostnames = []) {
+  const response = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      secret: process.env.TURNSTILE_SECRET,
+      response: token
+    })
+  });
+
+  const result = await response.json();
+
+  if (!result.success) {
+    return { valid: false, error: 'Token validation failed' };
+  }
+
+  // Additional hostname validation when using Any Hostname
+  if (expectedHostnames.length > 0 && !expectedHostnames.includes(result.hostname)) {
+    return { 
+      valid: false, 
+      error: 'Hostname not in allowed list',
+      hostname: result.hostname 
+    };
+  }
+
+  return { valid: true, data: result };
+}
+```
+
+You should regularly review Turnstile Analytics for unexpected usage patterns and monitor the hostname field in Siteverify responses. You can set up alerts for widget usage on unexpected domains.
+
+Use `action` and `cData` parameters to track widget usage sources.
+
+```html
+<!-- Widget with tracking information -->
+<div class="cf-turnstile" 
+     data-sitekey="your-site-key"
+     data-action="customer-portal"
+     data-cdata="tenant-123"></div>
+```
+
+---
+
+## Use cases
+
+The Any Hostname feature is particularly valuable for customers with:
+
+- Large domain portfolios with many domains to manage individually.
+- Dynamic subdomain creation and frequently create subdomains or customer-specific domains.
+- Multi-tenant applications such as SaaS platforms serving multiple customer domains.
+- Development environments that test across various staging and development domains.

src/content/docs/turnstile/additional-configuration/hostname-management/index.mdx

@@ -0,0 +1,100 @@
+---
+title: Hostname management
+pcx_content_type: reference
+sidebar:
+  order: 2
+
+---
+
+import { DashButton, Steps, Tabs, TabItem, Details } from "~/components"
+
+Hostname management controls where your Turnstile widgets can be used by specifying which domains are authorized to load and execute your widgets. This security measure prevents unauthorized use of your widgets on domains that you do not control.
+
+You can associate hostnames with your widget to control where it can be used via 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 requirements
+
+### Standard configuration
+
+By default, every widget requires at least one hostname to be configured. You cannot create a widget without specifying at least one authorized hostname.
+
+### Hostname format requirements
+
+When adding hostnames, follow these requirements:
+
+- The hostname must be fully qualified domain names (FQDNs): `example.com` or `subdomain.example.com`
+- No wildcards are supported. You must specify each hostname individually.
+
+:::caution[Invalid formats]
+The following formats are not valid and will not be accepted:
+
+- Schemes such as `http://example.com` or `https://example.com`
+- Ports such as `example.com:443` or `subdomain.example.com:8080`
+- Paths such as `example.com/path` or `subdomain.example.com/login`
+:::
+
+### Subdomain behavior
+
+Specifying a subdomain provides additional security by restricting widget usage. 
+
+For example, adding `www.example.com` as a hostname will allow widgets to work on:
+
+- `www.example.com`
+- `abc.www.example.com:8080` (subdomains of the specified hostname). 
+
+However, it will not work on:
+
+- `example.com` (parent domain)
+- `dash.example.com` (sibling subdomain)
+- `cloudflare.com` (unrelated domain)
+
+## Add hostnames
+
+<Tabs>
+  <TabItem label="Dashboard">
+    <Details header="Existing widget">
+      <Steps>
+          1. In the Cloudflare dashboard, go to the **Turnstile** page.
+
+              <DashButton url="/?to=/:account/turnstile" />
+          2. Select an existing widget.
+          3. Go to **Settings**.
+          4. Under **Hostname Management**, select **Add Hostnames**.
+          5. Add a custom hostname or choose from an existing hostname.
+          6. Select **Add**.
+      </Steps>
+    </Details>
+    <Details header="New widget">
+      <Steps>
+          1. In the Cloudflare dashboard, go to the **Turnstile** page.
+
+                <DashButton url="/?to=/:account/turnstile" />
+          2. Select **Add widget**.
+          3. In the hostname field, enter your domain(s).
+          4. If you have zones registered with Cloudflare, you can select from existing zones
+      </Steps>
+    </Details>
+  </TabItem>
+  <TabItem label="API">
+
+    ```bash title="cURL command" wrap
+      curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$WIDGET_ID" \
+      -H "Authorization: Bearer $API_TOKEN" \
+      -H "Content-Type: application/json" \
+      -d '{
+      "domains": ["example.com", "app.example.com", "api.example.com"]
+      }'
+    ```
+
+  </TabItem>
+</Tabs>
+
+---
+
+## Limitations
+
+Free users are entitled to a maximum of 15 hostnames per widget.
+
+Enterprise customers can have up to 200 hostnames per widget

src/content/docs/turnstile/additional-configuration/hostname-management/pre-clearance.mdx

@@ -0,0 +1,29 @@
+---
+title: Pre-clearance configuration
+pcx_content_type: reference
+sidebar:
+  order: 3
+
+---
+
+[Pre-clearance](/cloudflare-challenges/concepts/clearance/#pre-clearance-support-in-turnstile) allows Turnstile to issue clearance cookies that can be used across your Cloudflare-protected domains. This feature requires specific hostname configuration for proper functionality.
+
+## Prerequisites
+
+For pre-clearance to work correctly, you must:
+
+1. Use a registered Cloudflare zone. 
+
+    The hostname must be a zone registered in your Cloudflare account. When configuring your widget via the dashboard, you can select from existing zones. 
+
+2. Select the registered Cloudflare zone with intended WAF rule to set pre-clearance. 
+
+    The zone you select must contain the WAF rule you wish to set pre-clearance through Turnstile. 
+
+    For example, if you have `example.com` and `app.example.com` as registered zones and you want to have Turnstile issue pre-clearance for `app.example.com`, you must select `app.example.com`. 
+
+## Validation
+
+The clearance cookie `cf_clearance` will only be accepted on domains that match the widget's configured hostnames, are registered as zones in your Cloudflare account, and have challenges enabled through Cloudflare's security settings
+
+If pre-clearance is configured incorrectly, clearance cookies may become invalid and lead to additional challenge requests.