SDKS-2810: Add Invisible reCAPTCHA, hCaptcha, and Enterprise #478
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| --- | ||
| '@forgerock/login-widget': minor | ||
| --- | ||
|
|
||
| Add invisible reCAPTCHA v2, invisible hCaptcha, and reCAPTCHA Enterprise support. | ||
|
|
||
| - Support invisible mode for both Google reCAPTCHA v2 and hCaptcha via `configuration({ captcha: { mode: 'invisible' } })`. | ||
| - Add `ReCaptchaEnterpriseCallback` handler for AM journeys using the Enterprise CAPTCHA node — renders visible checkbox or score-based invisible flow automatically from callback data. | ||
| - Add `resolveGrecaptcha()` helper that prefers `window.grecaptcha.enterprise` and falls back to classic `window.grecaptcha`, keeping existing consumers with migrated keys working without changes. | ||
| - Show inline `<Alert type="error">` on CAPTCHA failure or expiry for invisible modes. | ||
| - Fix `renderCaptcha` to accept an optional `elementId` param to avoid DOM id collisions between classic and Enterprise components. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,106 @@ | ||
| /** | ||
| * | ||
| * Copyright © 2026 Ping Identity Corporation. All right reserved. | ||
| * | ||
| * This software may be modified and distributed under the terms | ||
| * of the MIT license. See the LICENSE file for details. | ||
| * | ||
| **/ | ||
|
|
||
| import { beforeEach, describe, expect, it, vi } from 'vitest'; | ||
|
|
||
| import { loadCaptchaScript, resolveGrecaptcha } from './captcha.utilities'; | ||
|
|
||
| vi.stubGlobal('window', globalThis); | ||
|
|
||
| describe('resolveGrecaptcha', () => { | ||
| beforeEach(() => { | ||
| vi.stubGlobal('grecaptcha', undefined); | ||
| }); | ||
|
|
||
| it('returns grecaptcha.enterprise when enterprise namespace is present', () => { | ||
| const enterprise = { ready: vi.fn(), render: vi.fn(), execute: vi.fn() }; | ||
| vi.stubGlobal('grecaptcha', { enterprise }); | ||
| expect(resolveGrecaptcha()).toBe(enterprise); | ||
| }); | ||
|
|
||
| it('falls back to window.grecaptcha when enterprise namespace is absent', () => { | ||
| const classic = { ready: vi.fn(), render: vi.fn(), execute: vi.fn() }; | ||
| vi.stubGlobal('grecaptcha', classic); | ||
| expect(resolveGrecaptcha()).toBe(classic); | ||
| }); | ||
| }); | ||
|
|
||
| describe('loadCaptchaScript', () => { | ||
| let appendedScript: { | ||
| src: string; | ||
| async: boolean; | ||
| onload: (() => void) | null; | ||
| onerror: (() => void) | null; | ||
| }; | ||
| let mockQuerySelector: ReturnType<typeof vi.fn>; | ||
| let mockAppendChild: ReturnType<typeof vi.fn>; | ||
|
|
||
| beforeEach(() => { | ||
| vi.stubGlobal('grecaptcha', undefined); | ||
| appendedScript = { src: '', async: false, onload: null, onerror: null }; | ||
| mockAppendChild = vi.fn(); | ||
| mockQuerySelector = vi.fn().mockReturnValue(null); | ||
| vi.stubGlobal('document', { | ||
| querySelector: mockQuerySelector, | ||
| createElement: () => appendedScript, | ||
| head: { appendChild: mockAppendChild }, | ||
| }); | ||
| }); | ||
|
|
||
| it('injects a new script tag and resolves on load for hcaptcha', async () => { | ||
| const promise = loadCaptchaScript({ | ||
| src: 'https://js.hcaptcha.com/1/api.js', | ||
| provider: 'hcaptcha', | ||
| }); | ||
| expect(appendedScript.src).toBe('https://js.hcaptcha.com/1/api.js'); | ||
| expect(mockAppendChild).toHaveBeenCalledOnce(); | ||
| appendedScript.onload?.(); | ||
| await promise; | ||
| }); | ||
|
|
||
| it('injects a new script tag and waits for grecaptcha.ready on load', async () => { | ||
| const mockReady = vi.fn((fn: () => void) => fn()); | ||
| const promise = loadCaptchaScript({ | ||
| src: 'https://www.google.com/recaptcha/api.js', | ||
| provider: 'grecaptcha', | ||
| }); | ||
| expect(appendedScript.src).toBe('https://www.google.com/recaptcha/api.js'); | ||
| vi.stubGlobal('grecaptcha', { ready: mockReady }); | ||
| appendedScript.onload?.(); | ||
| await promise; | ||
| expect(mockReady).toHaveBeenCalledOnce(); | ||
| }); | ||
|
|
||
| it('reuses existing script and resolves immediately for hcaptcha', async () => { | ||
| mockQuerySelector.mockReturnValue({ addEventListener: vi.fn() }); | ||
| await loadCaptchaScript({ src: 'https://js.hcaptcha.com/1/api.js', provider: 'hcaptcha' }); | ||
| expect(mockAppendChild).not.toHaveBeenCalled(); | ||
| }); | ||
|
|
||
| it('reuses existing script and calls grecaptcha.ready when already present', async () => { | ||
| const mockReady = vi.fn((fn: () => void) => fn()); | ||
| vi.stubGlobal('grecaptcha', { ready: mockReady }); | ||
| mockQuerySelector.mockReturnValue({ addEventListener: vi.fn() }); | ||
| await loadCaptchaScript({ | ||
| src: 'https://www.google.com/recaptcha/api.js', | ||
| provider: 'grecaptcha', | ||
| }); | ||
| expect(mockAppendChild).not.toHaveBeenCalled(); | ||
| expect(mockReady).toHaveBeenCalledOnce(); | ||
| }); | ||
|
|
||
| it('rejects when the script fails to load', async () => { | ||
| const promise = loadCaptchaScript({ | ||
| src: 'https://bad.example.com/api.js', | ||
| provider: 'hcaptcha', | ||
| }); | ||
| appendedScript.onerror?.(); | ||
| await expect(promise).rejects.toThrow('Failed to load CAPTCHA script'); | ||
| }); | ||
| }); |
|
Contributor
There was a problem hiding this comment. Since this is a new file, I'd like to move towards the pattern of |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| /** | ||
| * | ||
| * Copyright © 2026 Ping Identity Corporation. All right reserved. | ||
| * | ||
| * This software may be modified and distributed under the terms | ||
| * of the MIT license. See the LICENSE file for details. | ||
| * | ||
| **/ | ||
|
|
||
| /** | ||
| * Resolves the active reCAPTCHA namespace. Prefers `grecaptcha.enterprise` | ||
| * (loaded by enterprise.js) and falls back to the classic `grecaptcha` global | ||
| * (loaded by api.js or auto-migrated keys). This makes all call sites | ||
| * transparent to which script the consumer loaded. | ||
| */ | ||
| export function resolveGrecaptcha(): ReCaptchaV2.ReCaptcha { | ||
| const grecaptcha = window.grecaptcha as ReCaptchaV2.ReCaptcha & { | ||
| enterprise?: ReCaptchaV2.ReCaptcha; | ||
| }; | ||
| return grecaptcha?.enterprise ?? window.grecaptcha; | ||
| } | ||
|
|
||
| /** | ||
| * Injects a CAPTCHA script tag into <head> and resolves when the provider API | ||
| * is ready to use. No-ops if the provider API is already present on window (e.g. | ||
| * pre-loaded by consumer or stubbed in tests), or if a script with the same src | ||
| * is already in the document. For grecaptcha, waits for grecaptcha.ready(). | ||
| */ | ||
| export function loadCaptchaScript({ | ||
| src, | ||
| provider, | ||
| }: { | ||
| src: string; | ||
| provider: 'grecaptcha' | 'hcaptcha'; | ||
| }): Promise<void> { | ||
| if (provider === 'hcaptcha') { | ||
| const hc = (window as Window & { hcaptcha?: unknown }).hcaptcha; | ||
| if (hc) return Promise.resolve(); | ||
| } else { | ||
| const grc = resolveGrecaptcha(); | ||
| if (grc) return new Promise((resolve) => grc.ready(() => resolve())); | ||
| } | ||
|
|
||
| const existing = document.querySelector<HTMLScriptElement>(`script[src="${src}"]`); | ||
| if (existing) { | ||
| return new Promise((resolve) => { | ||
| if (provider === 'hcaptcha') { | ||
| resolve(); | ||
| } else { | ||
| const grc = resolveGrecaptcha(); | ||
| if (grc) { | ||
| grc.ready(() => resolve()); | ||
| } else { | ||
| existing.addEventListener('load', () => resolve(), { once: true }); | ||
| } | ||
| } | ||
| }); | ||
| } | ||
| return new Promise((resolve, reject) => { | ||
| const script = document.createElement('script'); | ||
| script.src = src; | ||
| script.async = true; | ||
| script.onerror = () => reject(new Error(`Failed to load CAPTCHA script: ${src}`)); | ||
| script.onload = () => { | ||
| if (provider === 'hcaptcha') { | ||
| resolve(); | ||
| } else { | ||
| const grc = resolveGrecaptcha(); | ||
| grc ? grc.ready(() => resolve()) : resolve(); | ||
| } | ||
| }; | ||
| document.head.appendChild(script); | ||
| }); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So we're now creating a distinct
ReCaptchaEnterpriseCallback.Because now in the new "Recaptcha world" there is no significant difference between this for google, this feels like we're diverting our structure away from the actual core Domain (ReCaptcha)
I think maybe what we need to do is align more against HCaptcha vs Google ReCaptcha.
Since GoogleReCaptcha has Enterprise, and others, but they are all under the domain of Enterprise Recaptcha, it can be a bit more resilient to future changes from Google. If they rename, add something, we have just Google based ReCaptcha component that handles that logic, we operate there.
HCaptcha being distinct creates the same separation.
My Concern is that we are creating the separation "Enterprise" vs not, and then if HCaptcha has or adds an Enterprise, are we going to put all Enterprise based logic in the
recaptcha-enterprisecomponent?It feels like the abstraction may be on the wrong thing and should be on the Google vs HCaptcha.
This may help clean up some of the mess I originally created when writing this because now the logic for each is coupled (correctly) to the component that it is.
The issue this does create is in this file, since we check the type, we'd need one more layer of logic which says "Which type" of Recaptcha is this.
I think in this case, this second "check" is worth doing for the separation we can create.
Thoughts?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fair point. The component split follows AM's callback structure, not our design. AM sends
ReCaptchaEnterpriseCallback(different fromReCaptchaCallback) for the Enterprise captcha node, and it has a different API too. One component for both would need duck-typing or internal branching, which can be harder to read and test.hCaptchaonly usesReCaptchaCallback, no Enterprise variant, so it stays in the classic component. If AM adds an hCaptcha Enterprise callback later, it could get its own component or reuse the enterprise one.If AM is our source of truth for callback components, which it mostly is (one exception aside), a dedicated
ReCaptchaEnterpriseCallbackmakes more sense. That said, I get your point about the abstraction belonging at the ReCaptcha vs. hCaptcha level. It really comes down to following AM's structure or creating our own for captcha callbacks.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I hear this, but i'm not sure that following AM nodes here is the right decision since the real implementation is more specific to the provider. I'm not hard set on this but just my thoughts