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

fix(captcha): replace javascript-sdk imports with journey-client in story/mock files and restore vitest coverage-v8 dep

refactor(captcha): replace captcha.store with initOptions in buildCallbackMetadata

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,10 +23,11 @@
   <title>Login Application</title>
   <link rel="icon" href="/favicon.ico" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <script
-    src="https://www.google.com/recaptcha/api.js?render=6LdIqXMoAAAAAP4APBlw7_5WDeMTlAAQJf42rPWz"
-    async
-  ></script>
+  <!--
+    For CAPTCHA-enabled journeys: use enterprise.js, not api.js —
+    new Google keys require the Enterprise namespace.
+  -->
+  <script 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">
@@ -28,12 +28,15 @@
   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: {
-      wellknown: data.wellknown,
-    },
-  });
+  const journeyStore: JourneyStore = initializeJourney(
+    { serverConfig: { wellknown: data.wellknown } },
+    captchaModeParam ? { captcha: { mode: captchaModeParam } } : null,
+  );
 
   let hasSubmitted = false;
   let redirectForm: HTMLFormElement | null = null;

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

@@ -24,6 +24,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;
@@ -52,6 +53,7 @@
             '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'
@@ -127,6 +128,7 @@
           header: false,
         },
       },
+      captcha: captchaModeParam ? { mode: captchaModeParam } : undefined,
     });
 
     componentEvents = component();

core/journey/_utilities/callback-mapper.svelte

@@ -32,6 +32,7 @@
   import PingProtectInitialize from '$journey/callbacks/ping-protect-initialize/ping-protect-initialize.svelte';
   import PollingWait from '$journey/callbacks/polling-wait/polling-wait.svelte';
   import Recaptcha from '$journey/callbacks/recaptcha/recaptcha.svelte';
+  import RecaptchaEnterprise from '$journey/callbacks/recaptcha-enterprise/recaptcha-enterprise.svelte';
   import Redirect from '$journey/callbacks/redirect/redirect.svelte';
   import SelectIdp from '$journey/callbacks/select-idp/select-idp.svelte';
   import StringAttributeInput from '$journey/callbacks/string-attribute/string-attribute-input.svelte';
@@ -58,6 +59,7 @@
     PingOneProtectInitializeCallback,
     PollingWaitCallback,
     ReCaptchaCallback,
+    ReCaptchaEnterpriseCallback,
     RedirectCallback,
     SelectIdPCallback,
     SuspendedTextOutputCallback,
@@ -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/_utilities/metadata.utilities.ts

@@ -21,25 +21,30 @@ import type { BaseCallback, JourneyStep } from '@forgerock/journey-client/types'
 
 import type { CallbackMetadata } from '$journey/journey.interfaces';
 
+const captchaCallbackTypes = new Set(['ReCaptchaCallback', 'ReCaptchaEnterpriseCallback']);
+
 /**
  * @function buildCallbackMetadata - Constructs an array of callback metadata that matches to original callback array
  * @param {object} step - The modified Widget step object
  * @param {function} checkValidation - function that checks if current callback is the first invalid callback
+ * @param {object} stageJson - Optional stage JSON from AM
+ * @param {object} initializationOptions - Optional widget-level initialization options (e.g. captcha config)
  * @returns {array}
  */
 export function buildCallbackMetadata(
   step: JourneyStep,
   checkValidation: (callback: BaseCallback) => boolean,
   stageJson?: Record<string, unknown> | null,
+  initializationOptions?: Record<string, unknown> | null,
 ) {
   const callbackCount: Record<string, number> = {};
   const isPasskeyAutofillEligible = isMixedLoginWebAuthnStep(step);
 
   return step?.callbacks.map((callback, idx) => {
-    const cb = callback;
-    const callbackType = cb.getType();
+    const callbackType = callback.getType();
 
     let stageCbMetadata;
+    let initOptions;
 
     if (callbackCount[callbackType]) {
       callbackCount[callbackType] = callbackCount[callbackType] + 1;
@@ -52,6 +57,10 @@ export function buildCallbackMetadata(
       stageCbMetadata = stageCbArray[callbackCount[callbackType] - 1];
     }
 
+    if (captchaCallbackTypes.has(callbackType) && initializationOptions?.captcha) {
+      initOptions = initializationOptions.captcha as Record<string, unknown>;
+    }
+
     return {
       derived: {
         canForceUserInputOptionality: canForceUserInputOptionality(callback),
@@ -68,6 +77,7 @@ export function buildCallbackMetadata(
           ...stageCbMetadata,
         },
       }),
+      ...(initOptions && { initOptions }),
     };
   });
 }

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/journey-client';
+
+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,93 @@
+/**
+ *
+ * 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/journey-client';
+import { expect, within } from 'storybook/test';
+
+import { createJourneyStep } from '$journey/_utilities/step.mock';
+import { journeyStore } from '$journey/journey.store';
+import {
+  invisibleGrecaptchaEnterprise,
+  visibleGrecaptchaEnterprise,
+} from './recaptcha-enterprise.mock';
+import RecaptchaEnterprise from './recaptcha-enterprise.story.svelte';
+
+function mockGrecaptchaEnterprise() {
+  window.grecaptcha = {
+    enterprise: {
+      ready: (cb) => cb(),
+      render: () => 'widget-id',
+      execute: async () => 'enterprise-token',
+      reset: () => undefined,
+      getResponse: () => 'enterprise-token',
+    },
+  };
+}
+
+function makeCallbackMetadata(mode) {
+  return {
+    derived: {
+      canForceUserInputOptionality: false,
+      isFirstInvalidInput: false,
+      isReadyForSubmission: false,
+      isSelfSubmitting: false,
+      isUserInputRequired: false,
+      isPasskeyAutofillEligible: false,
+    },
+    idx: 0,
+    initOptions: { mode },
+  };
+}
+
+export default {
+  argTypes: {
+    callback: { control: false },
+    callbackMetadata: { control: false },
+  },
+  component: RecaptchaEnterprise,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  title: 'Callbacks/ReCaptchaEnterprise',
+};
+
+export const VisibleEnterprise = {
+  args: {
+    callback: createJourneyStep(visibleGrecaptchaEnterprise).getCallbackOfType(
+      callbackType.ReCaptchaEnterpriseCallback,
+    ),
+    callbackMetadata: makeCallbackMetadata('normal'),
+  },
+  play: async () => {
+    mockGrecaptchaEnterprise();
+  },
+};
+
+export const InvisibleEnterprise = {
+  args: {
+    callback: createJourneyStep(invisibleGrecaptchaEnterprise).getCallbackOfType(
+      callbackType.ReCaptchaEnterpriseCallback,
+    ),
+    callbackMetadata: makeCallbackMetadata('invisible'),
+  },
+  play: async () => {
+    mockGrecaptchaEnterprise();
+    journeyStore.update((v) => ({ ...v, recaptchaAction: 'LOGIN' }));
+  },
+};
+
+export const InvisibleEnterpriseError = {
+  args: { ...InvisibleEnterprise.args },
+  play: async ({ canvasElement }) => {
+    mockGrecaptchaEnterprise();
+    window.frHandleCaptchaInvisibleError?.();
+    const canvas = within(canvasElement);
+    await expect(canvas.findByText(/CAPTCHA verification failed/i)).resolves.toBeInTheDocument();
+  },
+};

core/journey/callbacks/recaptcha-enterprise/recaptcha-enterprise.story.svelte

@@ -0,0 +1,25 @@
+<!--
+
+ 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.
+
+ -->
+
+<script lang="ts">
+  import Centered from '$components/primitives/box/centered.svelte';
+  import RecaptchaEnterprise from './recaptcha-enterprise.svelte';
+
+  import type { ReCaptchaEnterpriseCallback } from '@forgerock/journey-client/types';
+
+  import type { Maybe } from '$core/interfaces';
+  import type { CallbackMetadata } from '$journey/journey.interfaces';
+
+  export let callback: ReCaptchaEnterpriseCallback;
+  export let callbackMetadata: Maybe<CallbackMetadata> = null;
+</script>
+
+<Centered>
+  <RecaptchaEnterprise {callback} {callbackMetadata} />
+</Centered>