{"id":18321432,"url":"https://github.com/bitarmory/turnstile","last_synced_at":"2025-04-05T22:32:23.213Z","repository":{"id":192146085,"uuid":"686154611","full_name":"BitArmory/Turnstile","owner":"BitArmory","description":":recycle: A friction-less C# HTTP verification client for Cloudflare's Turnstile API.","archived":false,"fork":false,"pushed_at":"2024-09-02T20:58:54.000Z","size":74,"stargazers_count":13,"open_issues_count":4,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-21T13:13:42.185Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BitArmory.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":"bchavez"}},"created_at":"2023-09-01T22:15:27.000Z","updated_at":"2025-01-22T15:12:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"68b0f343-5c13-4c97-b65b-f430604f871a","html_url":"https://github.com/BitArmory/Turnstile","commit_stats":null,"previous_names":["bitarmory/turnstile"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitArmory%2FTurnstile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitArmory%2FTurnstile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitArmory%2FTurnstile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitArmory%2FTurnstile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BitArmory","download_url":"https://codeload.github.com/BitArmory/Turnstile/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247411234,"owners_count":20934650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T18:19:32.440Z","updated_at":"2025-04-05T22:32:22.978Z","avatar_url":"https://github.com/BitArmory.png","language":"C#","funding_links":["https://github.com/sponsors/bchavez"],"categories":[],"sub_categories":[],"readme":"[![Build status](https://ci.appveyor.com/api/projects/status/sng4ogpbuhu3fc9e/branch/master?svg=true)](https://ci.appveyor.com/project/BitArmory/Turnstile/branch/master) [![Nuget](https://img.shields.io/nuget/v/BitArmory.Turnstile.svg)](https://www.nuget.org/packages/BitArmory.Turnstile/) [![Users](https://img.shields.io/nuget/dt/BitArmory.Turnstile.svg)](https://www.nuget.org/packages/BitArmory.Turnstile/) \u003cimg src=\"https://raw.githubusercontent.com/BitArmory/Turnstile/master/docs/turnstile.png\" align='right' /\u003e\r\n\r\nBitArmory.Turnstile for .NET and C#\r\n===================================\r\n\r\nProject Description\r\n-------------------\r\nA minimal, no-drama, friction-less **C#** **HTTP** verification client for **Cloudflare**'s [**Turnstile** API](https://developers.cloudflare.com/turnstile/).\r\n\r\nThe problem with current **Turnstile** libraries in **.NET** is that all of them take a hard dependency on the underlying web framework like **ASP.NET WebForms**, **ASP.NET MVC 5**, **ASP.NET Core**, or **ASP.NET Razor Pages**. \r\n\r\nFurthermore, current **Turnstile** libraries for **.NET** are hard coded against the `HttpContext.Request` to retrieve the remote IP address of the visitor. Unfortunately, this method doesn't work if your website is behind a service like **Cloudflare** where the [`CF-Connecting-IP` header value](https://support.cloudflare.com/hc/en-us/articles/200170986-How-does-Cloudflare-handle-HTTP-Request-headers) is the ***real*** IP address of the visitor on your site.\r\n\r\n**BitArmory.Turnstile** is a minimal library that works across all **.NET** web frameworks without taking a hard dependency on any web framework. If you want to leverage platform specific features, like **MVC** ***Action Filters***, you'll need to implement your own `ActionFilter` that leverages the functionality in this library.\r\n\r\n#### Supported Platforms\r\n* **.NET Standard 1.3** or later\r\n* **.NET Framework 4.5** or later\r\n\r\n#### Supported Turnstile Widgets\r\n* **Managed**\r\n* **Non-interactive**\r\n* **Invisible**\r\n\r\n\r\n#### Crypto Tip Jar\r\n\u003ca href=\"https://commerce.coinbase.com/checkout/52bb1ce7-58c2-4df3-8ac7-58b5289c99d0\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/BitArmory/Turnstile/master/docs/tipjar.png\" /\u003e\u003c/a\u003e\r\n* :dog2: **Dogecoin**: `DGVC2drEMt41sEzEHSsiE3VTrgsQxGn5qe`\r\n\r\n\r\n### Download \u0026 Install\r\n**NuGet Package [BitArmory.Turnstile](https://www.nuget.org/packages/BitArmory.Turnstile/)**\r\n\r\n```powershell\r\nInstall-Package BitArmory.Turnstile\r\n```\r\n\r\n\r\nGeneral Usage\r\n-------------\r\n### Getting Started\r\nYou'll need a **Cloudflare** account. Get started by following the directions [here](https://developers.cloudflare.com/turnstile/get-started/)! After you sign up and you're signed into the dashboard; you'll need two important pieces of information:\r\n1. Your `site` key\r\n2. Your `secret` key\r\n\r\nThis library supports all widget types: \r\n* **Managed**\r\n* **Non-interactive**\r\n* **Invisible**\r\n\r\n\r\n## Turnstile\r\n### Client-side Setup\r\n\r\nBe sure to [read the documentation](https://developers.cloudflare.com/turnstile/) before implementing.\r\n\r\nThen, to protect an **HTML** form submission on your website, add the following:\r\n```html\r\n\u003chtml\u003e\r\n  \u003chead\u003e\r\n    \u003cscript src=\"https://challenges.cloudflare.com/turnstile/v0/api.js\" async defer\u003e\u003c/script\u003e\r\n  \u003c/head\u003e\r\n  \u003cbody\u003e\r\n    \u003cform method='POST' action='/my-form-post-endpoint'\u003e\r\n        ...\r\n        \u003cdiv class=\"cf-turnstile\" data-sitekey=\"your_site_key\"\u003e\u003c/div\u003e\r\n        \u003cinput type=\"submit\" value=\"Submit\"\u003e\r\n    \u003c/form\u003e\r\n  \u003c/body\u003e\r\n\u003c/html\u003e\r\n```\r\nWhen the user visits the **HTML** form, a hidden form field `cf-turnstile-response` will be added to the **HTML** form above. The `cf-turnstile-response` represents a token of the captcha challenge result and will need to be verified server-side when the **HTML** form is posted to your server.\r\n\r\n### Verifying the POST Server-side\r\nWhen the **HTML** form `POST` is received on the server:\r\n1. Get the client's IP address. If you're using **Cloudflare**, be sure to use the [`CF-Connecting-IP` header value][0].\r\n2. Extract the hidden form field `cf-turnstile-response` from the browser's form POST submission.\r\n3. Use the `TurnstileService` to verify that the client's **Turnstile** `cf-turnstile-response` challenge is valid.\r\n\r\nThe following example shows how to verify the captcha during an **HTTP** form `POST` back in **ASP.NET Core: Razor Pages**.\r\n\r\n```csharp\r\n//1. Get the client IP address in your chosen web framework\r\nstring secret = \"your_secret_key\";\r\nstring clientIp = GetClientIpAddress();\r\nstring browserChallengeToken = null;\r\n\r\n//2. Extract the `cf-turnstile-response` hidden field from the HTML form in your chosen web framework\r\n//Tip: You can also use Constants.ClientResponseFormKey instead of the magic string below\r\nif( this.Request.Form.TryGetValue(\"cf-turnstile-response\", out var hiddenFormField) )\r\n{\r\n   browserChallengeToken = hiddenFormField;\r\n}\r\n\r\n//3. Validate the Turnstile challenge with Cloudflare\r\nvar turnstileApi = new TurnstileService();\r\nvar verifyResult = await turnstileApi.VerifyAsync(browserChallengeToken, secret, clientIp);\r\nif( verifyResult.IsSuccess is false )\r\n{\r\n   this.ModelState.AddModelError(\"captcha\", \"The Cloudflare challenge is not valid.\");\r\n   return new BadRequestResult();\r\n}\r\nelse{\r\n   //continue processing, everything is okay!\r\n}\r\n```\r\n\r\n**Notes:**\r\n* The `TurnstileService.VerifyAsync` supports an optional idempotency parameter; you can read more about that [here](https://developers.cloudflare.com/turnstile/get-started/server-side-validation/#accepted-parameters).\r\n* The `clientIp` is technically optional but providing the client's IP address prevents abuses by ensuring that the current HTTP request is the one that received the token.\r\n\r\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eGetClientIpAddress() in ASP.NET Core\u003c/b\u003e\u003c/summary\u003e\r\n\u003cp\u003e\r\n\r\n**Note:** If your site is behind Cloudflare, be sure you're using the [`CF-Connecting-IP` header value][0] instead.\r\n\r\n```csharp\r\npublic string GetClientIpAddress(){\r\n   return this.HttpContext.Connection.RemoteIpAddress.ToString();\r\n}\r\n```\r\n\u003c/p\u003e\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eGetClientIpAddress() in ASP.NET WebForms\u003c/b\u003e\u003c/summary\u003e\r\n\u003cp\u003e\r\n\r\n**Note:** If your site is behind Cloudflare, be sure you're using the [`CF-Connecting-IP` header value][0] instead.\r\n\r\n```csharp\r\npublic string GetClientIpAddress(){\r\n   return this.Request.UserHostAddress;\r\n}\r\n```\r\n\u003c/p\u003e\r\n\u003c/details\u003e \r\n\r\nThat's it! **Happy verifying!** :tada:\r\n\r\nTesting and Development Environment\r\n--------\r\n**Cloudflare Turnstile** has some convenient testing keys and secrets that respond/behave differently for various UI interactions and server-side verification responses to help test your website. Be sure to read the following testing documentation [here](https://developers.cloudflare.com/turnstile/reference/testing/).\r\n\r\nThe testing keys and secrets can be used from the `TestingSiteKeys` and `TestingSecretKeys` constant classes:\r\n\r\nhttps://github.com/BitArmory/Turnstile/blob/1d59d2696526a7fafaacb55dcdac918bb1c895e5/BitArmory.Turnstile/Constants.cs#L30-L73\r\n\r\nBuilding\r\n--------\r\n* Download the source code.\r\n* Run `build.cmd`.\r\n\r\nUpon successful build, the results will be in the `\\__compile` directory. If you want to build NuGet packages, run `build.cmd pack` and the NuGet packages will be in `__package`.\r\n\r\n\r\n\r\n[0]:https://support.cloudflare.com/hc/en-us/articles/200170986-How-does-Cloudflare-handle-HTTP-Request-headers\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitarmory%2Fturnstile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitarmory%2Fturnstile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitarmory%2Fturnstile/lists"}