Skip to content

Commit 67245e0

Browse files
google-labs-jules[bot]google-labs-jules[bot]
committed
feat: Integrate reCAPTCHA into Login Form
Integrates Google reCAPTCHA v3 into the login form located at `apps/web/app/(with-contexts)/(with-layout)/login/login-form.tsx`. This change utilizes the existing reCAPTCHA framework: - The `useRecaptcha` hook is used to generate a token for the 'login_code_request' action. - The token is verified by the `/api/recaptcha` endpoint. - If reCAPTCHA verification is successful and the score is adequate, the request to generate a login code proceeds. - If verification fails or the score is too low, an error message is displayed to you via a toast notification, and the login code request is blocked. - Loading states and error handling have been updated to incorporate the reCAPTCHA verification step.
1 parent 65e136b commit 67245e0

6 files changed

Lines changed: 403 additions & 6 deletions

File tree

‎apps/web/RECAPTCHA_INTEGRATION_NOTES.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Google reCAPTCHA v3 Integration Notes
2+
3+
## 1. Overview
4+
5+
This document outlines the integration of Google reCAPTCHA v3 into the web application. reCAPTCHA v3 works by returning a score for each request without user friction. This score can be used to take appropriate action, such as requiring additional verification steps or blocking suspected bot traffic. It helps protect user actions like form submissions from abuse.
6+
7+
## 2. Environment Variables
8+
9+
The following environment variables are required for the reCAPTCHA integration to function correctly:
10+
11+
- `NEXT_PUBLIC_RECAPTCHA_SITE_KEY`: This is the client-side site key obtained from the Google reCAPTCHA Admin Console. It's prefixed with `NEXT_PUBLIC_` because it needs to be accessible in the browser.
12+
- `RECAPTCHA_SECRET_KEY`: This is the server-side secret key obtained from the Google reCAPTCHA Admin Console. **This key must be kept confidential and should only be used on the server.**
13+
14+
Ensure these variables are set in your local development environment (e.g., in an `.env.local` file at the root of the `apps/web` project) and in your deployment environments.
15+
16+
## 3. How it Works
17+
18+
The integration consists of three main parts:
19+
20+
### a. Client-side Script Loading (`app/layout.tsx`)
21+
22+
- The root layout file (`apps/web/app/layout.tsx`) includes a Next.js `Script` component to load the Google reCAPTCHA API script.
23+
- The script source URL includes the `NEXT_PUBLIC_RECAPTCHA_SITE_KEY`.
24+
- The script is loaded only if `NEXT_PUBLIC_RECAPTCHA_SITE_KEY` is present, preventing errors if the key is not configured.
25+
- The `strategy="afterInteractive"` attribute is used to load the script after the page becomes interactive, minimizing impact on initial page load performance.
26+
27+
### b. `useRecaptcha` Hook (`hooks/use-recaptcha.ts`)
28+
29+
- The custom React hook `useRecaptcha` (located in `apps/web/hooks/use-recaptcha.ts`) provides a convenient way to trigger reCAPTCHA verification.
30+
- It exports an `executeRecaptcha` function that takes an `action` string as an argument. This `action` helps you identify which part of your site is being protected when viewing results in the Google reCAPTCHA Admin Console.
31+
- When called, `executeRecaptcha`:
32+
1. Checks if `NEXT_PUBLIC_RECAPTCHA_SITE_KEY` is available. If not, it logs an error and returns `null`.
33+
2. Checks if `window.grecaptcha` and `window.grecaptcha.ready` are available (i.e., if the Google script has loaded).
34+
3. Calls `window.grecaptcha.ready()` to ensure the API is ready.
35+
4. Calls `window.grecaptcha.execute()` with the site key and the provided `action` to get a reCAPTCHA token.
36+
5. Returns a Promise that resolves with the token, or `null` if an error occurs.
37+
- The `executeRecaptcha` function is wrapped in `useCallback` for performance optimization.
38+
39+
### c. `/api/recaptcha` Server-side Endpoint (`app/api/recaptcha/route.ts`)
40+
41+
- This API route (located at `apps/web/app/api/recaptcha/route.ts`) handles the server-side verification of the reCAPTCHA token.
42+
- It expects a `POST` request with a JSON body containing the `token` received from the client-side.
43+
- **Verification Steps**:
44+
1. Retrieves the `RECAPTCHA_SECRET_KEY` from server environment variables. Returns a 500 error if not set.
45+
2. Checks if the `token` is present in the request body. Returns a 400 error if not.
46+
3. Makes a `POST` request to Google's `https://www.google.com/recaptcha/api/siteverify` endpoint.
47+
4. The request to Google includes the `secret` (your `RECAPTCHA_SECRET_KEY`) and `response` (the client's `token`).
48+
5. Parses the JSON response from Google.
49+
6. Returns relevant information from Google's response to the client, including `success`, `score`, `action`, `challenge_ts`, `hostname`, and `error-codes`.
50+
- Includes error handling for the fetch request to Google and other potential issues.
51+
52+
## 4. Using the `recaptcha-example-form.tsx`
53+
54+
- An example component `RecaptchaExampleForm` (located in `apps/web/components/recaptcha-example-form.tsx`) demonstrates the end-to-end reCAPTCHA flow.
55+
- It renders a simple form. On submission:
56+
1. It calls `executeRecaptcha` from the `useRecaptcha` hook.
57+
2. If a token is received, it sends this token to the `/api/recaptcha` endpoint.
58+
3. It then logs the verification response from the API and displays a status message to the user, indicating whether the action would be allowed based on the `success` status and `score` (e.g., score > 0.5).
59+
- **To test the integration**: Temporarily import and render this component on any page within the `apps/web` application.
60+
61+
## 5. Testing Steps
62+
63+
1. **Set Environment Variables**:
64+
* Ensure `NEXT_PUBLIC_RECAPTCHA_SITE_KEY` and `RECAPTCHA_SECRET_KEY` are correctly set in your local environment (e.g., in an `.env.local` file at the root of `apps/web`). Use valid keys from your Google reCAPTCHA admin console for a specific domain (localhost can be registered for testing).
65+
66+
2. **Render the Example Form**:
67+
* Modify an existing page (e.g., the homepage) in `apps/web` to import and render the `RecaptchaExampleForm` component.
68+
```tsx
69+
// Example: in apps/web/app/page.tsx
70+
import { RecaptchaExampleForm } from "@/components/recaptcha-example-form";
71+
72+
export default function HomePage() {
73+
return (
74+
<div>
75+
{/* ... other page content ... */}
76+
<RecaptchaExampleForm />
77+
</div>
78+
);
79+
}
80+
```
81+
82+
3. **Open Browser Developer Tools**:
83+
* Access the page where `RecaptchaExampleForm` is rendered.
84+
* Open your browser's developer tools (usually by pressing F12).
85+
86+
4. **Monitor Console**:
87+
* Check the **Console** tab for logs:
88+
* From `useRecaptcha` if the site key is missing or reCAPTCHA isn't ready.
89+
* From `RecaptchaExampleForm` showing the token received (if any), the call to `/api/recaptcha`, the verification response, and status messages.
90+
91+
5. **Check Network Tab**:
92+
* Switch to the **Network** tab in developer tools.
93+
* Submit the example form.
94+
* Look for the `POST` request to `/api/recaptcha`. Inspect its payload (the token) and response (Google's verification result).
95+
* Note: The call to Google's `siteverify` endpoint happens server-to-server, so you won't see it directly in the browser's network tab, but its outcome is returned by your `/api/recaptcha` endpoint.
96+
97+
6. **Google reCAPTCHA Admin Console (Post-Deployment)**:
98+
* After deploying the application to a staging or test environment with valid production/test reCAPTCHA keys:
99+
* Visit your Google reCAPTCHA Admin Console.
100+
* Select the site key you configured.
101+
* You should see traffic data, including the number of requests, scores, and the distribution of actions (e.g., 'example_form_submit'). This helps verify that reCAPTCHA is actively processing requests for your site.
102+
103+
7. **Test Missing Keys**:
104+
* Temporarily unset or comment out `NEXT_PUBLIC_RECAPTCHA_SITE_KEY` in your `.env.local` and restart the development server. The reCAPTCHA script should not load, and `executeRecaptcha` should return `null` or handle it gracefully.
105+
* Temporarily unset `RECAPTCHA_SECRET_KEY`. The `/api/recaptcha` endpoint should return a 500 error, which the example form should handle.
106+
107+
By following these steps, you can thoroughly test the reCAPTCHA v3 integration. Remember to remove the `RecaptchaExampleForm` from any public pages after testing.

‎apps/web/app/(with-contexts)/(with-layout)/login/login-form.tsx‎

Lines changed: 58 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ import {
3232
} from "@/ui-config/strings";
3333
import Link from "next/link";
3434
import { TriangleAlert } from "lucide-react";
35+
import { useRecaptcha } from "@/hooks/use-recaptcha";
3536
import { useRouter } from "next/navigation";
3637

3738
export default function LoginForm({ redirectTo }: { redirectTo?: string }) {
@@ -42,27 +43,78 @@ export default function LoginForm({ redirectTo }: { redirectTo?: string }) {
4243
const [error, setError] = useState("");
4344
const [loading, setLoading] = useState(false);
4445
const { toast } = useToast();
46+
const { executeRecaptcha } = useRecaptcha();
4547
const router = useRouter();
4648

4749
const requestCode = async function (e: FormEvent) {
4850
e.preventDefault();
49-
const url = `/api/auth/code/generate?email=${encodeURIComponent(
50-
email,
51-
)}`;
51+
setLoading(true);
52+
setError("");
53+
54+
if (!executeRecaptcha) {
55+
toast({
56+
title: TOAST_TITLE_ERROR,
57+
description: "reCAPTCHA service not available. Please try again later.",
58+
variant: "destructive",
59+
});
60+
setLoading(false);
61+
return;
62+
}
63+
64+
const recaptchaToken = await executeRecaptcha("login_code_request");
65+
if (!recaptchaToken) {
66+
toast({
67+
title: TOAST_TITLE_ERROR,
68+
description: "reCAPTCHA validation failed. Please try again.",
69+
variant: "destructive",
70+
});
71+
setLoading(false);
72+
return;
73+
}
74+
5275
try {
53-
setLoading(true);
76+
const recaptchaVerificationResponse = await fetch("/api/recaptcha", {
77+
method: "POST",
78+
headers: { "Content-Type": "application/json" },
79+
body: JSON.stringify({ token: recaptchaToken }),
80+
});
81+
82+
const recaptchaData = await recaptchaVerificationResponse.json();
83+
84+
if (!recaptchaVerificationResponse.ok || !recaptchaData.success || (recaptchaData.score && recaptchaData.score < 0.5)) {
85+
toast({
86+
title: TOAST_TITLE_ERROR,
87+
description: `reCAPTCHA verification failed. ${recaptchaData.score ? `Score: ${recaptchaData.score.toFixed(2)}.` : ''} Please try again.`,
88+
variant: "destructive",
89+
});
90+
setLoading(false);
91+
return;
92+
}
93+
94+
// Proceed with code generation if reCAPTCHA is successful
95+
const url = `/api/auth/code/generate?email=${encodeURIComponent(
96+
email,
97+
)}`;
5498
const response = await fetch(url);
5599
const resp = await response.json();
56100
if (response.ok) {
57101
setShowCode(true);
58102
} else {
59103
toast({
60104
title: TOAST_TITLE_ERROR,
61-
description: resp.error,
105+
description: resp.error || "Failed to request code.",
62106
variant: "destructive",
63107
});
64108
}
65-
} finally {
109+
} catch (err) {
110+
console.error("Error during requestCode:", err);
111+
toast({
112+
title: TOAST_TITLE_ERROR,
113+
description: "An unexpected error occurred. Please try again.",
114+
variant: "destructive",
115+
});
116+
}
117+
finally {
66118
setLoading(false);
67119
}
68120
};

‎apps/web/app/api/recaptcha/route.ts‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
import { NextRequest, NextResponse } from "next/server";
2+
3+
/**
4+
* API route handler for verifying a Google reCAPTCHA v3 token.
5+
* Expects a POST request with a JSON body containing a `token` property.
6+
*
7+
* @param {NextRequest} request - The incoming Next.js API request object.
8+
* @returns {Promise<NextResponse>} A Next.js API response object.
9+
*/
10+
export async function POST(request: NextRequest) {
11+
const secretKey = process.env.RECAPTCHA_SECRET_KEY;
12+
if (!secretKey) {
13+
console.error("reCAPTCHA secret key not found.");
14+
return NextResponse.json(
15+
{ error: "Internal server error" },
16+
{ status: 500 }
17+
);
18+
}
19+
20+
let requestBody;
21+
try {
22+
requestBody = await request.json();
23+
} catch (error) {
24+
return NextResponse.json(
25+
{ error: "Invalid request body" },
26+
{ status: 400 }
27+
);
28+
}
29+
30+
const { token } = requestBody;
31+
32+
if (!token) {
33+
return NextResponse.json(
34+
{ error: "reCAPTCHA token not found" },
35+
{ status: 400 }
36+
);
37+
}
38+
39+
const formData = `secret=${secretKey}&response=${token}`;
40+
41+
try {
42+
const response = await fetch(
43+
"https://www.google.com/recaptcha/api/siteverify",
44+
{
45+
method: "POST",
46+
headers: {
47+
"Content-Type": "application/x-www-form-urlencoded",
48+
},
49+
body: formData,
50+
}
51+
);
52+
53+
if (!response.ok) {
54+
console.error("Failed to verify reCAPTCHA token with Google");
55+
return NextResponse.json(
56+
{ error: "Failed to verify reCAPTCHA token" },
57+
{ status: 500 }
58+
);
59+
}
60+
61+
const googleResponse = await response.json();
62+
return NextResponse.json({
63+
success: googleResponse.success,
64+
score: googleResponse.score,
65+
action: googleResponse.action,
66+
challenge_ts: googleResponse.challenge_ts,
67+
hostname: googleResponse.hostname,
68+
"error-codes": googleResponse["error-codes"],
69+
});
70+
} catch (error) {
71+
console.error("Error verifying reCAPTCHA token:", error);
72+
return NextResponse.json(
73+
{ error: "Error verifying reCAPTCHA token" },
74+
{ status: 500 }
75+
);
76+
}
77+
}

‎apps/web/app/layout.tsx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import "@courselit/page-blocks/styles.css";
33
import "@courselit/components-library/styles.css";
44
import "@courselit/page-primitives/styles.css";
55
import "../styles/globals.css";
6+
import Script from "next/script";
67
import type { Metadata } from "next";
78
import { headers } from "next/headers";
89
import {
@@ -69,6 +70,13 @@ export default async function RootLayout({ children }: RootLayoutProps) {
6970
className={`${fonts.openSans.variable} ${fonts.montserrat.variable} ${fonts.lato.variable} ${fonts.poppins.variable} ${fonts.sourceSans3.variable} ${fonts.raleway.variable} ${fonts.notoSans.variable} ${fonts.merriweather.variable} ${fonts.inter.variable} ${fonts.alegreya.variable} ${fonts.roboto.variable} ${fonts.mulish.variable} ${fonts.nunito.variable} ${fonts.rubik.variable} ${fonts.playfairDisplay.variable} ${fonts.oswald.variable} ${fonts.ptSans.variable} ${fonts.workSans.variable} ${fonts.robotoSlab.variable} ${fonts.sourceSerif4.variable} ${fonts.bebasNeue.variable} ${fonts.quicksand.variable} font-sans ${inter.className}`}
7071
>
7172
{children}
73+
{/* Conditionally load the Google reCAPTCHA v3 script. Only loads if the site key is set in environment variables. */}
74+
{process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY && (
75+
<Script
76+
src={`https://www.google.com/recaptcha/api.js?render=${process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY}`}
77+
strategy="afterInteractive" // Load after the page becomes interactive to avoid blocking initial render.
78+
/>
79+
)}
7280
</body>
7381
</html>
7482
);

0 commit comments

Comments
 (0)