[Challenges] Concepts and Available Types (cloudflare#23085)

* Challenges

* implementation

* remove faq for now

* siteverify

* copy edits

* clearance

* capitalization

* accessibility

Author: patriciasantaana

src/content/docs/cloudflare-challenges/challenge-types/challenge-pages.mdx

@@ -0,0 +1,20 @@
+---
+pcx_content_type: concept
+title: Additional configuration
+sidebar:
+  order: 6
+---
+
+## Multi-language support
+
+Refer to [supported languages](/cloudflare-challenges/reference/supported-languages/) for more information.
+
+## Favicon customization
+
+Cloudflare Challenges take the favicon of your website using `GET /favicon.ico` and displays it on the Challenge Page.
+
+You can customize your favicon by using the HTML snippet below.
+
+```html title="HTML element"
+<link rel="shortcut icon" href="<FAVICON_LINK>" />
+```

src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/additional-configuration.mdx

@@ -0,0 +1,32 @@
+---
+pcx_content_type: concept
+title: Challenge Passage
+sidebar:
+  order: 3
+---
+
+
+When a visitor solves a [Cloudflare Challenge](/cloudflare-challenges/) - as part of a [WAF custom rule](/waf/custom-rules/) or [IP Access rule](/waf/tools/ip-access-rules/) - you can set the **Challenge Passage** to prevent them from having to solve future Challenges for a specified period of time.
+
+### How it works
+
+When a visitor successfully solves a Challenge, Cloudflare sets a [`cf_clearance` cookie](/fundamentals/reference/policies-compliances/cloudflare-cookies/#additional-cookies-used-by-the-challenge-platform) in their browser. This cookie specifies the duration your website is accessible to that visitor.
+
+When that visitor tries to access other parts of your website, Cloudflare evaluates the cookie before presenting another Challenge. If the cookie is still valid, no Challenges will be shown.
+
+When Cloudflare evaluates a `cf_clearance` cookie, a few extra minutes are included to account for clock skew. For XmlHTTP requests, an extra hour is added to the validation time to prevent breaking XmlHTTP requests for pages that set short lifetimes.
+
+### Customize the Challenge Passage
+
+By default, the `cf_clearance` cookie has a lifetime of 30 minutes. Cloudflare recommends a setting between 15 and 45 minutes.
+
+To update the Challenge Passage (and the value of the `cf_clearance` cookie):
+
+1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com).
+2. Select your account and domain.
+3. Go to **Security** > **Settings**.
+4. For **Challenge Passage**, select a duration.
+
+### Limitations
+
+The Challenge Passage does not apply to Challenges issued by [WAF managed rules](/waf/managed-rules/). Also, Challenge Passage does not apply to rate limiting rules unless the rate limit is configured to issue a Challenge.

src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/challenge-passage.mdx

@@ -0,0 +1,14 @@
+---
+pcx_content_type: how-to
+title: Implement a Challenge Page via WAF custom rules
+sidebar:
+  order: 2
+  label: Implementation
+---
+
+import { Render } from "~/components"
+
+<Render file="create-challenge-page" />
+
+- **Bot Management**: You can set the custom rule to challenge a visitor based on the [bot score](/bots/concepts/bot-score/) or [detection ID](/bots/additional-configurations/detection-ids/).
+- **Rate limiting**: You can challenge visitors based on your defined rate limits.

src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/create-custom-rule.mdx

@@ -0,0 +1,30 @@
+---
+pcx_content_type: concept
+title: Detect a Challenge Page response
+sidebar:
+  order: 4
+---
+
+## Detect a Challenge Page response
+
+When a request encounters a Cloudflare Challenge Page instead of the originally anticipated response, the Challenge Page response (regardless of the Challenge Page type) will have the `cf-mitigated` header present and set to `challenge`. This header can be leveraged to detect if a response was challenged when making fetch/XHR requests. This header provides a reliable way to identify whether a response is a Challenge or not, enabling a web application to take appropriate action based on the result. For example, a front-end application encountering a response from the backend may check the presence of this header value to handle cases where Challenge Pages encountered unexpectedly.
+
+:::note
+Regardless of the requested resource-type, the content-type of a Challenge will be `text/html`.
+:::
+
+For the `cf-mitigated` header, `challenge` is the only valid value. The header is set for all Challenge Page types.
+
+To illustrate, here is a JavaScript code snippet that demonstrates how to use the `cf-mitigated` header to detect whether a response was challenged:
+
+```js
+fetch("/my-api-endpoint").then((response) => {
+	if (response.headers.get("cf-mitigated") === "challenge") {
+		// Handle challenged response
+	} else {
+		// Process response as usual
+	}
+});
+```
+
+For additional help, refer to our [FAQ](/cloudflare-challenges/frequently-asked-questions/).

src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/detect-response.mdx

@@ -0,0 +1,45 @@
+---
+pcx_content_type: concept
+title: Interstitial Challenge Pages
+sidebar:
+  order: 1
+---
+import { Render } from "~/components"
+
+An interstitial Challenge Page acts as a gate between the visitor and your website or application while Cloudflare verifies the authenticity of the visitor.
+
+The Challenge Page intercepts the visitor from getting to the destination URL by holding the request and evaluating the browser environment for automated signals, and serving a Challenge. The visitor cannot reach their destination without passing the Challenge. Based on the signals indicated by their browser environment, the visitor may be asked to perform an interaction such as checking a box or selecting a button for further probing.
+
+<Render file="create-challenge-page" />
+
+The level of interactivity and visibility of the Challenge Page depends on the Action that you select when creating the WAF rule for your website or application.
+
+## Actions
+
+The following Challenge types are the available actions when you create a WAF rule for a Challenge Page. 
+
+### Managed Challenge (recommended)
+
+Managed Challenges are where Cloudflare dynamically chooses the appropriate type of Challenge served to the visitor based on the characteristics of a request from the signals indicated by their browser. This helps avoid [CAPTCHAs](https://www.cloudflare.com/learning/bots/how-captchas-work/), which also reduces the lifetimes of human time spent solving CAPTCHAs across the Internet.
+
+Most human visitors are automatically verified and the Challenge Page will display **Successful**. However, if Cloudflare detects non-human attributes from the visitor's browser, they may be required to interact with the Challenge to solve it.
+
+Unless there are specific compatibility issues or other reasons to use other types of Challenges, Cloudflare recommends you to use Managed Challenges for your custom rules.
+
+:::caution
+Using Cloudflare Challenges along with Rules features may cause Challenge loops. Refer to [Rules troubleshooting](/rules/reference/troubleshooting/) for more information.
+:::
+
+### Interactive Challenge
+
+Interactive Challenge Pages offer the highest security for your website or application because it requires a visitor to interact with the Interstitial Challenge Page, presenting the visitor with an Interactive Challenge to solve. 
+
+For more information about why Cloudflare does not recommend using Interactive Challenge, in favor of Managed Challenge, refer to our [blog post](https://blog.cloudflare.com/end-cloudflare-captcha/).
+
+### JavaScript Challenge (non-interactive)
+
+With a JavaScript (JS) Challenge, Cloudflare makes the determination on whether or not the visitor is automated based on the limited information attained from their browser signals via an injected JavaScript. Then, it presents a Challenge Page that requires no interaction from a visitor except the JavaScript processed by their browser. 
+
+The visitor must wait until their browser finishes processing the JavaScript, which typically takes less than five seconds.
+
+If the visitor passes the Challenge, the original request continues to the destination URL. If the Challenge fails or cannot be completed, the visitor is presented with another Interstitial Challenge Page.

src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/index.mdx

@@ -0,0 +1,19 @@
+---
+pcx_content_type: concept
+title: Resolve a Challenge
+sidebar:
+  order: 5
+---
+
+If a visitor encounters a Challenge, Cloudflare employees cannot remove that Challenge. Only the website owner can configure their Cloudflare settings to stop the Challenge being presented.
+
+When observing a Cloudflare Challenge page, a visitor could:
+
+- Successfully pass the Challenge to visit the website.
+- Request the website owner to allow their IP address.
+- Scan their computer for malicious programs (it may be infected).
+- Check their antivirus or firewall service to make sure it is not blocking access to the Challenge resources (for example, images).
+
+:::note
+Visitors must enable JavaScript and cookies on their browser to be able to pass any type of Challenge.
+:::

src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/resolve-challenge.mdx

@@ -1,6 +1,6 @@
 ---
 pcx_content_type: navigation
-title: Challenge types
+title: Available Challenges
 sidebar:
   order: 3
   group: 
@@ -9,6 +9,6 @@ sidebar:
 
 import { DirectoryListing } from "~/components"
 
-Refer to the following pages for more information on available challenge types:
+Refer to the following pages for more information on available Challenge types:
 
 <DirectoryListing />

src/content/docs/cloudflare-challenges/challenge-types/index.mdx

@@ -4,7 +4,7 @@ type: overview
 pcx_content_type: reference
 title: JavaScript detections
 sidebar:
-  order: 6
+  order: 3
 ---
 
 import { Render } from "~/components"

src/content/docs/cloudflare-challenges/challenge-types/javascript-detections.mdx

@@ -0,0 +1,38 @@
+---
+pcx_content_type: concept
+title: Turnstile
+sidebar:
+  order: 2
+---
+
+import { Render } from "~/components";
+
+[Turnstile](/turnstile/) is Cloudflare's CAPTCHA-alternative solution. You can embed Turnstile as a widget on your website or application, where it runs a client-side Challenge directly in the background of the visitor's browser.
+
+Turnstile differs from Challenges Pages in that the Challenge does not pause the request or interrupt the user's experience. Since the widget is embedded onto the webpage and only runs on a specific part of the HTML, the visitor will have already arrived at the destination URL and is viewing the page when they encounter a Turnstile widget. Instead of blocking the visitor from accessing the entire website, the Turnstile widget prevents the visitor from certain actions such as completing login or sign up forms, and more, until the widget is solved.
+
+In most cases, nothing further is required from the visitor. However, if necessary, Turnstile may display a simple checkbox that the visitor must click to proceed.
+
+After the Challenge passes, Turnstile issues a clearance token to the visitor that must be validated via the [Siteverify API](/turnstile/get-started/server-side-validation/) before completing a sensitive action like login, sign up, or other form submissions. 
+
+<Render file="siteverify-warning" product="turnstile" />
+
+## Widget types
+
+While there are three types of widgets that you can choose to implement on your website or application, the Challenge logic behind them remains the same.
+
+- **Managed (recommended)**: Functions similar to a Managed Challenge Page. It selects a Challenge based on the signals gathered from the visitor's browser and presents an interaction only if it detects potentially automated traffic.
+
+- **Non-Interactive**: The widget is displayed, but the visitor does not need to interact with it to verify their identity. 
+
+- **Invisible**: The widget is completely invisible to the visitor, but the Challenge still runs in the background.
+
+## Implementation
+
+When you create a widget for your website or application via the Cloudflare dashboard, you will receive a sitekey. 
+
+The sitekey is used with [client-side rendering](/turnstile/get-started/client-side-rendering/#implicitly-render-the-turnstile-widget) by adding it to the `<div>` container placeholder. You will then place that `<div>` code snippet where you want to add the widget to your site page or form.
+
+## Get started
+
+Refer to the [Turnstile documentation](/turnstile/get-started/) for guidance on implementing a widget to your website or application.