feat(captcha): add invisible reCAPTCHA v2, hCaptcha and reCaptcha Enterprise support

Author: SteinGabriel

.changeset/add-captcha-enterprise-invisible.md

@@ -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.

apps/login-app/src/routes/(app)/+layout.svelte

@@ -23,9 +23,14 @@
   <title>Login Application</title>
   <link rel="icon" href="/favicon.ico" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <!--
+    For CAPTCHA-enabled journeys: use enterprise.js, not api.js —
+    new Google keys require the Enterprise namespace.
+  -->
   <script
-    src="https://www.google.com/recaptcha/api.js?render=6LdIqXMoAAAAAP4APBlw7_5WDeMTlAAQJf42rPWz"
+    src="https://www.google.com/recaptcha/enterprise.js"
     async
+    defer
   ></script>
 
   <style>

apps/login-app/src/routes/(app)/+page.svelte

@@ -1,10 +1,10 @@
 <!--
- 
+
  Copyright © 2025-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.
- 
+
  -->
 
 <script lang="ts">
@@ -16,6 +16,7 @@
   import Journey from '$journey/journey.svelte';
   import { initialize as initializeJourney } from '$journey/journey.store';
   import { initialize as initializeContent } from '$core/locale.store';
+  import { initialize as initializeCaptcha } from '$core/captcha.store';
 
   import type { JourneyStore } from '$journey/journey.interfaces';
 
@@ -28,6 +29,7 @@
   const formPostEntryParam = $page.url.searchParams.get('form_post_entry');
   const journeyParam = $page.url.searchParams.get('journey');
   const suspendedIdParam = $page.url.searchParams.get('suspendedId');
+  const captchaModeParam = $page.url.searchParams.get('captchaMode') as 'normal' | 'invisible' | null;
 
   const journeyStore: JourneyStore = initializeJourney({
     serverConfig: {
@@ -44,6 +46,7 @@
    * Sets up locale store with appropriate content
    */
   initializeContent(data.content);
+  initializeCaptcha({ mode: captchaModeParam ?? 'normal' });
 
   // Use if not initializing journey in a "context module"
   onMount(async () => {

apps/login-app/src/routes/e2e/widget/inline/+page.svelte

@@ -23,6 +23,7 @@
   let authIndexValueParam = $page.url.searchParams.get('authIndexValue');
   let journeyParam = $page.url.searchParams.get('journey');
   let recaptchaParam = $page.url.searchParams.get('recaptchaAction');
+  let captchaModeParam = $page.url.searchParams.get('captchaMode') as 'normal' | 'invisible' | null;
   let suspendedIdParam = $page.url.searchParams.get('suspendedId');
   let formEl: HTMLDivElement;
   let userEvent: UserStoreValue | null;
@@ -50,6 +51,7 @@
           wellknown: 'https://openam-sdks.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration',
         },
       },
+      captcha: captchaModeParam ? { mode: captchaModeParam } : undefined,
       forgerock: {
         clientId: 'WebOAuthClient',
         redirectUri: `${window.location.origin}/callback`,

apps/login-app/src/routes/e2e/widget/modal/+page.svelte

@@ -19,6 +19,7 @@
   let authIndexValueParam = $page.url.searchParams.get('authIndexValue');
   let journeyParam = $page.url.searchParams.get('journey');
   let recaptchaParam = $page.url.searchParams.get('recaptchaAction');
+  let captchaModeParam = $page.url.searchParams.get('captchaMode') as 'normal' | 'invisible' | null;
   let suspendedIdParam = $page.url.searchParams.get('suspendedId');
   let showPasswordParam = $page.url.searchParams.get('showPassword') as
     | 'none'
@@ -126,6 +127,7 @@
           header: false,
         },
       },
+      captcha: captchaModeParam ? { mode: captchaModeParam } : undefined,
     });
 
     componentEvents = component();

core/captcha.store.test.ts

@@ -0,0 +1,45 @@
+/**
+ *
+ * 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 { get } from 'svelte/store';
+import { describe, expect, it } from 'vitest';
+
+import { captchaStore, initialize } from './captcha.store';
+
+describe('captcha.store', () => {
+  describe('initialize()', () => {
+    it('should set mode to "normal" when no config is provided', () => {
+      initialize();
+      expect(get(captchaStore).mode).toBe('normal');
+    });
+
+    it('should set mode to "invisible" when configured', () => {
+      initialize({ mode: 'invisible' });
+      expect(get(captchaStore).mode).toBe('invisible');
+    });
+
+    it('should default to "normal" when mode is undefined', () => {
+      initialize({ mode: undefined });
+      expect(get(captchaStore).mode).toBe('normal');
+    });
+
+    it('should return the captcha store', () => {
+      const store = initialize({ mode: 'invisible' });
+      expect(store).toBe(captchaStore);
+    });
+
+    it('should update the store when called again with different config', () => {
+      initialize({ mode: 'invisible' });
+      expect(get(captchaStore).mode).toBe('invisible');
+
+      initialize({ mode: 'normal' });
+      expect(get(captchaStore).mode).toBe('normal');
+    });
+  });
+});

core/captcha.store.ts

@@ -0,0 +1,39 @@
+/**
+ *
+ * Copyright © 2025 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 { writable, type Writable } from 'svelte/store';
+import { z } from 'zod';
+
+export const captchaSchema = z
+  .object({
+    mode: z.union([z.literal('normal'), z.literal('invisible')]).optional(),
+  })
+  .strict();
+
+export const partialCaptchaSchema = captchaSchema.partial();
+
+/** Convenience type alias for the resolved captcha config object. */
+export type CaptchaConfig = z.infer<typeof partialCaptchaSchema>;
+
+const fallbackCaptcha: CaptchaConfig = {
+  mode: 'normal',
+};
+
+export const captchaStore: Writable<CaptchaConfig> = writable(fallbackCaptcha);
+
+/**
+ * @function initialize - Initialize the captcha store
+ * @param {object} customCaptcha - Optional captcha configuration to apply
+ * @returns {object} - The captcha store
+ * @example initialize({ mode: 'invisible' });
+ */
+export function initialize(customCaptcha?: CaptchaConfig) {
+  captchaStore.set({ mode: customCaptcha?.mode ?? 'normal' });
+  return captchaStore;
+}

core/journey/_utilities/callback-mapper.svelte

@@ -42,6 +42,7 @@
   import ValidatedCreateUsername from '$journey/callbacks/username/validated-create-username.svelte';
   import DeviceProfile from '$journey/callbacks/device-profile/device-profile.svelte';
   import Recaptcha from '$journey/callbacks/recaptcha/recaptcha.svelte';
+  import RecaptchaEnterprise from '$journey/callbacks/recaptcha-enterprise/recaptcha-enterprise.svelte';
   import Metadata from '$journey/callbacks/metadata/metadata.svelte';
   import PingProtectEvaluation from '$journey/callbacks/ping-protect-evaluation/ping-protect-evaluation.svelte';
   import PingProtectInitialize from '$journey/callbacks/ping-protect-initialize/ping-protect-initialize.svelte';
@@ -67,6 +68,7 @@
     DeviceProfileCallback,
     MetadataCallback,
     ReCaptchaCallback,
+    ReCaptchaEnterpriseCallback,
     PingOneProtectEvaluationCallback,
     PingOneProtectInitializeCallback,
   } from '@forgerock/journey-client/types';
@@ -113,6 +115,7 @@
   let _MetadataCallback: MetadataCallback;
   let _DeviceProfileCallback: DeviceProfileCallback;
   let _RecaptchaCallback: ReCaptchaCallback;
+  let _RecaptchaEnterpriseCallback: ReCaptchaEnterpriseCallback;
   let _PingProtectEvaluation: PingOneProtectEvaluationCallback;
   let _PingProtectInitialize: PingOneProtectInitializeCallback;
   let _BaseCallback: BaseCallback;
@@ -142,6 +145,9 @@
       case callbackType.ReCaptchaCallback:
         _RecaptchaCallback = props.callback as ReCaptchaCallback;
         break;
+      case callbackType.ReCaptchaEnterpriseCallback:
+        _RecaptchaEnterpriseCallback = props.callback as ReCaptchaEnterpriseCallback;
+        break;
       case callbackType.PasswordCallback:
         _PasswordCallback = props.callback as PasswordCallback;
         break;
@@ -319,6 +325,12 @@
     callback: _RecaptchaCallback,
   }}
   <Recaptcha {...newProps} />
+{:else if cbType === callbackType.ReCaptchaEnterpriseCallback}
+  {@const newProps = {
+    ...props,
+    callback: _RecaptchaEnterpriseCallback,
+  }}
+  <RecaptchaEnterprise {...newProps} />
 {:else if cbType === callbackType.PingOneProtectEvaluationCallback}
   {@const newProps = {
     ...props,

core/journey/callbacks/recaptcha-enterprise/recaptcha-enterprise.mock.ts

@@ -0,0 +1,36 @@
+/**
+ *
+ * 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 { CallbackType } from '@forgerock/javascript-sdk';
+
+export const visibleGrecaptchaEnterprise = {
+  authId: 'test-auth-id',
+  callbacks: [
+    {
+      type: CallbackType.ReCaptchaEnterpriseCallback,
+      output: [
+        { name: 'recaptchaSiteKey', value: 'enterprise-site-key' },
+        { name: 'captchaApiUri', value: 'https://www.google.com/recaptcha/enterprise.js' },
+        { name: 'captchaDivClass', value: 'g-recaptcha' },
+      ],
+      input: [
+        { name: 'IDToken1token', value: '' },
+        { name: 'IDToken1action', value: '' },
+        { name: 'IDToken1clientError', value: '' },
+        { name: 'IDToken1payload', value: '' },
+      ],
+      _id: 0,
+    },
+  ],
+  stage: 'DefaultLogin',
+};
+
+export const invisibleGrecaptchaEnterprise = visibleGrecaptchaEnterprise;
+
+export default visibleGrecaptchaEnterprise;

core/journey/callbacks/recaptcha-enterprise/recaptcha-enterprise.stories.js

@@ -0,0 +1,78 @@
+/**
+ *
+ * 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 { FRStep, CallbackType } from '@forgerock/javascript-sdk';
+import { expect, within } from 'storybook/test';
+
+import {
+  visibleGrecaptchaEnterprise,
+  invisibleGrecaptchaEnterprise,
+} from './recaptcha-enterprise.mock';
+import RecaptchaEnterprise from './recaptcha-enterprise.story.svelte';
+import { captchaStore } from '$core/captcha.store';
+import { journeyStore } from '$journey/journey.store';
+
+function mockGrecaptchaEnterprise() {
+  window.grecaptcha = {
+    enterprise: {
+      ready: (cb) => cb(),
+      render: () => 'widget-id',
+      execute: async () => 'enterprise-token',
+      reset: () => undefined,
+      getResponse: () => 'enterprise-token',
+    },
+  };
+}
+
+export default {
+  argTypes: {
+    callback: { control: false },
+  },
+  component: RecaptchaEnterprise,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  title: 'Callbacks/ReCaptchaEnterprise',
+};
+
+export const VisibleEnterprise = {
+  args: {
+    callback: new FRStep(visibleGrecaptchaEnterprise).getCallbackOfType(
+      CallbackType.ReCaptchaEnterpriseCallback,
+    ),
+  },
+  play: async () => {
+    mockGrecaptchaEnterprise();
+    captchaStore.set({ mode: 'normal' });
+  },
+};
+
+export const InvisibleEnterprise = {
+  args: {
+    callback: new FRStep(invisibleGrecaptchaEnterprise).getCallbackOfType(
+      CallbackType.ReCaptchaEnterpriseCallback,
+    ),
+  },
+  play: async () => {
+    mockGrecaptchaEnterprise();
+    captchaStore.set({ mode: 'invisible' });
+    journeyStore.update((v) => ({ ...v, recaptchaAction: 'LOGIN' }));
+  },
+};
+
+export const InvisibleEnterpriseError = {
+  args: { ...InvisibleEnterprise.args },
+  play: async ({ canvasElement }) => {
+    mockGrecaptchaEnterprise();
+    captchaStore.set({ mode: 'invisible' });
+    window.frHandleCaptchaInvisibleError?.();
+    const canvas = within(canvasElement);
+    await expect(canvas.findByText(/CAPTCHA verification failed/i)).resolves.toBeInTheDocument();
+  },
+};