nextjs-turnstile 0.0.1

package/License

@@ -0,0 +1,19 @@
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# Next.js Turnstile CAPTCHA Package
+![npm](https://img.shields.io/npm/v/nextjs-turnstile)
+![License](https://img.shields.io/npm/l/nextjs-turnstile)
+![npm](https://img.shields.io/npm/dw/nextjs-turnstile)
+
+This package provides components and utilities to integrate Cloudflare Turnstile CAPTCHA into your Next.js applications. It supports both implicit and explicit CAPTCHA modes.
+
+You can find the document of Cloudflare Turnstile [here](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/).
+
+## Installation
+
+```bash
+npm install nextjs-turnstile
+```
+
+## Usage
+
+### Components
+**TurnstileImplicit:**
+
+```javascript
+import React from 'react';
+import { TurnstileImplicit, verifyTurnstile } from 'nextjs-turnstile';
+
+export default function MyForm() {
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    const token1 = e.target['cf-turnstile-response-1'].value;
+    const token2 = e.target['cf-turnstile-response-2'].value;
+
+    // Verify the first CAPTCHA response
+    const success1 = await verifyTurnstile(token1);
+    if (!success1) {
+      alert('First CAPTCHA verification failed');
+      return;
+    }
+
+    // Verify the second CAPTCHA response
+    const success2 = await verifyTurnstile(token2);
+    if (!success2) {
+      alert('Second CAPTCHA verification failed');
+      return;
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <h2>Turnstile Implicit CAPTCHA Example</h2>
+      
+      {/* First CAPTCHA */}
+      <TurnstileImplicit
+        theme="dark"
+        size="normal"
+        responseFieldName="cf-turnstile-response-1"
+      />
+      
+      {/* Second CAPTCHA */}
+      <TurnstileImplicit
+        theme="light"
+        size="compact"
+        responseFieldName="cf-turnstile-response-2"
+      />
+      
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+**TurnstileExplicit:**
+```javascript
+import React from 'react';
+import { TurnstileExplicit, verifyTurnstile } from 'nextjs-turnstile';
+
+export default function MyForm() {
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    const token1 = e.target['cf-turnstile-response-3'].value;
+    const token2 = e.target['cf-turnstile-response-4'].value;
+    
+    // Verify the first CAPTCHA response
+    const success1 = await verifyTurnstile(token1);
+    if (!success1) {
+      alert('First CAPTCHA verification failed');
+      return;
+    }
+
+    // Verify the second CAPTCHA response
+    const success2 = await verifyTurnstile(token2);
+    if (!success2) {
+      alert('Second CAPTCHA verification failed');
+      return;
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <h2>Turnstile Explicit CAPTCHA Example</h2>
+
+      {/* Developers must place the divs in their HTML */}
+      
+      {/* First CAPTCHA */}
+      <div id="cf-turnstile-response-3"></div>
+      <TurnstileExplicit
+        theme="dark"
+        size="normal"
+        responseFieldName="cf-turnstile-response-3"
+      />
+      
+      {/* Second CAPTCHA */}
+      <div id="cf-turnstile-response-4"></div>
+      <TurnstileExplicit
+        theme="light"
+        size="compact"
+        responseFieldName="cf-turnstile-response-4"
+      />
+      
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+### Verification Utility
+In your API routes:
+ß
+```javascript
+import { verifyTurnstile } from 'nextjs-turnstile';
+
+export default async function handler(req, res) {
+  const { token } = req.body;
+
+  const success = await verifyTurnstile(token, false, req);
+  // const success = await verifyTurnstile(token, req.connection.remoteAddress);
+
+  if (success) {
+    return res.status(200).json({ success: true });
+  } else {
+    return res.status(400).json({ success: false, message: 'CAPTCHA verification failed' });
+  }
+}
+```
+
+## Environment Variables
+You need to add the following environment variables to your .env.local file:
+
+```plaintext
+NEXT_PUBLIC_TURNSTILE_SITE_KEY=your_site_key_here
+TURNSTILE_SECRET_KEY=your_secret_key_here
+```
+
+## License
+This project is licensed under the MIT License - see the [License](./License) file for details.
+
+
+## Author
+Davod Mozafari - [Twitter](https://twitter.com/davodmozafari)

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "nextjs-turnstile",
+  "version": "0.0.1",
+  "description": "Integrate Cloudflare Turnstile CAPTCHA in Next.js applications",
+  "main": "src/index.js",
+  "scripts": {
+    "build": "next build",
+    "test": "jest"
+  },
+  "dependencies": {
+    "node-fetch": "^3.3.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "next": "^12.0.0"
+  },
+  "author": "Davod Mozafari",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/davodm/nextjs-turnstile.git"
+  },
+  "bugs": {
+    "url": "https://github.com/davodm/nextjs-turnstile/issues"
+  },
+  "homepage": "https://github.com/davodm/nextjs-turnstile",
+  "keywords": [
+    "nextjs",
+    "cloudflare",
+    "turnstile",
+    "captcha"
+  ]
+}

package/src/components/TurnstileExplicit.js

@@ -0,0 +1,73 @@
+import React, { useEffect } from 'react';
+
+let explicitFields = []; // Array to track the explicit CAPTCHA fields
+
+/**
+ * TurnstileExplicit component registers and initializes the Cloudflare Turnstile CAPTCHA in explicit mode.
+ * 
+ * This component registers CAPTCHA instances, which must be manually initialized using the provided
+ * response field name as the ID for the corresponding `<div>` element. The initialization script will
+ * render the CAPTCHA based on the specified theme and size.
+ *
+ * @component
+ * @param {string} [theme='light'] - The theme of the CAPTCHA widget. Options are 'light' or 'dark'.
+ * @param {string} [size='normal'] - The size of the CAPTCHA widget. Options are 'normal' or 'compact'.
+ * @param {string} [responseFieldName='cf-turnstile-response'] - The name of the hidden input field and the ID of the `<div>` that will contain the CAPTCHA widget.
+ * @param {string} [siteKey=process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY] - The site key for Turnstile CAPTCHA. Defaults to the value in the environment variables.
+ * @returns {null} No visible component is rendered, only registers the field for later initialization.
+ */
+const TurnstileExplicit = ({
+  theme = "light",
+  size = "normal",
+  responseFieldName = "cf-turnstile-response",
+}) => {
+  const siteKey = process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY;
+  const JSUrl = "https://challenges.cloudflare.com/turnstile/v0/api.js?onload=turnstileReady";
+
+  useEffect(() => {
+    // Register the field for later initialization
+    // Check if the field is already registered
+    if (explicitFields.some((field) => field.fieldName === responseFieldName)) {
+      return;
+    }
+    explicitFields.push({
+      fieldName: responseFieldName,
+      size,
+      theme,
+    });
+
+    return () => {
+      // Cleanup: Remove the field if the component unmounts
+      explicitFields = explicitFields.filter(
+        (field) => field.fieldName !== responseFieldName
+      );
+    };
+  }, [responseFieldName, size, theme]);
+
+  useEffect(() => {
+    // Ensure the Turnstile script is loaded only once
+    if (!document.querySelector('script[src="' + JSUrl + '"]')) {
+      const script = document.createElement("script");
+      script.src = JSUrl;
+      script.async = true;
+      document.body.appendChild(script);
+
+      script.onload = () => {
+        window.turnstileReady = function () {
+          explicitFields.forEach(function (field) {
+            window.turnstile.render(`#${field.fieldName}`, {
+              sitekey: siteKey,
+              "response-field-name": field.fieldName,
+              size: field.size,
+              theme: field.theme,
+            });
+          });
+        };
+      };
+    }
+  }, []);
+
+  return null; // No need to render anything, just register the field
+};
+
+export default TurnstileExplicit;

package/src/components/TurnstileImplicit.js

@@ -0,0 +1,47 @@
+import React, { useEffect } from 'react';
+
+/**
+ * TurnstileImplicit component renders the Cloudflare Turnstile CAPTCHA in implicit mode.
+ * 
+ * This component automatically loads the Turnstile script and renders the CAPTCHA based on the specified
+ * theme, size, and response field name.
+ *
+ * @component
+ * @param {string} [theme='light'] - The theme of the CAPTCHA widget. Options are 'light' or 'dark'.
+ * @param {string} [size='normal'] - The size of the CAPTCHA widget. Options are 'normal' or 'compact'.
+ * @param {string} [responseFieldName='cf-turnstile-response'] - The name of the hidden input field that stores the CAPTCHA response token.
+ * @returns {JSX.Element} The TurnstileImplicit component
+ */
+const TurnstileImplicit = ({ theme = 'light', size = 'normal', responseFieldName = 'cf-turnstile-response' }) => {
+  const siteKey = process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY;
+  const JSUrl="https://challenges.cloudflare.com/turnstile/v0/api.js";
+
+  useEffect(() => {
+    // Load the Turnstile script only once
+    if (!document.querySelector('script[src="' + JSUrl + '"]')) {
+      const script = document.createElement('script');
+      script.src = JSUrl;
+      script.async = true;
+      document.body.appendChild(script);
+
+      return () => {
+        document.body.removeChild(script);
+      };
+    }
+  }, []);
+
+  return (
+    <>
+      <div
+        className="cf-turnstile"
+        data-sitekey={siteKey}
+        data-theme={theme}
+        data-size={size}
+        data-response-field={responseFieldName}
+      >
+      </div>
+    </>
+  );
+};
+
+export default TurnstileImplicit;

package/src/index.js

@@ -0,0 +1,3 @@
+export { default as TurnstileImplicit } from './components/TurnstileImplicit';
+export { default as TurnstileExplicit } from './components/TurnstileExplicit';
+export { verifyTurnstile } from './utils/TurnstileVerify';

package/src/utils/TurnstileVerify.js

@@ -0,0 +1,52 @@
+/**
+ * Verifies the Cloudflare Turnstile CAPTCHA response token with the Turnstile API.
+ *
+ * @async
+ * @function verifyTurnstile
+ * @param {string} token - The CAPTCHA response token provided by the client-side Turnstile widget.
+ * @param {string} [userIP] - The IP address of the user. If not provided, the function will attempt to extract it from the request headers.
+ * @param {Object} [req] - The request object (optional). If provided, it is used to extract the user's IP address from headers like 'cf-connecting-ip' or 'x-forwarded-for'.
+ * @returns {Promise<boolean>} - Returns `true` if the CAPTCHA verification was successful, otherwise `false`.
+ *
+ * @throws {Error} If the request to the Turnstile API fails or if the CAPTCHA verification fails, an error is thrown with a descriptive message.
+ */
+export const verifyTurnstile = async (token, userIP, req=undefined) => {
+  const secretKey = process.env.TURNSTILE_SECRET_KEY;
+
+  // Fetch the user's IP address if not provided
+  let userIP = ipAddress;
+  if (!userIP && req?.headers) {
+    userIP = req.headers['cf-connecting-ip'] || req.headers['x-forwarded-for'] || req.connection.remoteAddress;
+  }
+
+  try {
+    const response = await fetch(`https://challenges.cloudflare.com/turnstile/v0/siteverify`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        secret: secretKey,
+        response: token,
+        remoteip: userIP,
+      }),
+    });
+
+    // Check for a successful response
+    if (!response.ok) {
+      throw new Error(`Verification request failed with status ${response.status}`);
+    }
+
+    const data = await response.json();
+
+    // Check if the success field is true
+    if (!data.success) {
+      throw new Error(`Verification failed: ${data['error-codes'] ? data['error-codes'].join(', ') : 'Unknown error'}`);
+    }
+
+    return true;
+  } catch (error) {
+    console.error('Error verifying Turnstile CAPTCHA:', error.message);
+    return false;
+  }
+};