SDKS-2810: Add Invisible reCAPTCHA, hCaptcha, and Enterprise

.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

@@ -1,6 +1,6 @@
 <!--
 
- Copyright © 2025 Ping Identity Corporation. All right reserved.
+ 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.
@@ -23,11 +23,6 @@
   <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>
-
   <style>
     /**
      * Self-hosting Open Sans for better privacy, potential performance and control

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,14 @@
   const formPostEntryParam = $page.url.searchParams.get('form_post_entry');
   const journeyParam = $page.url.searchParams.get('journey');
   const suspendedIdParam = $page.url.searchParams.get('suspendedId');
+  const captchaModeRaw = $page.url.searchParams.get('captchaMode');
+  const captchaModeParam =
+    captchaModeRaw === 'visible' || captchaModeRaw === 'invisible' ? captchaModeRaw : 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;
@@ -67,7 +69,6 @@
       journeyStore.start({
         journey: journeyParam || authIndexValue || '',
         query,
-        // recaptchaAction: 'MyTestAction',
       });
     }
   });

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

@@ -24,6 +24,9 @@
   let authIndexValueParam = $page.url.searchParams.get('authIndexValue');
   let journeyParam = $page.url.searchParams.get('journey');
   let recaptchaParam = $page.url.searchParams.get('recaptchaAction');
+  const captchaModeRaw = $page.url.searchParams.get('captchaMode');
+  const captchaModeParam =
+    captchaModeRaw === 'visible' || captchaModeRaw === 'invisible' ? captchaModeRaw : null;
   let suspendedIdParam = $page.url.searchParams.get('suspendedId');
   let formEl: HTMLDivElement;
   let userEvent: UserStoreValue | null;
@@ -52,6 +55,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,9 @@
   let authIndexValueParam = $page.url.searchParams.get('authIndexValue');
   let journeyParam = $page.url.searchParams.get('journey');
   let recaptchaParam = $page.url.searchParams.get('recaptchaAction');
+  const captchaModeRaw = $page.url.searchParams.get('captchaMode');
+  const captchaModeParam =
+    captchaModeRaw === 'visible' || captchaModeRaw === 'invisible' ? captchaModeRaw : null;
   let suspendedIdParam = $page.url.searchParams.get('suspendedId');
   let showPasswordParam = $page.url.searchParams.get('showPassword') as
     | 'none'
@@ -127,6 +130,7 @@
           header: false,
         },
       },
+      captcha: captchaModeParam ? { mode: captchaModeParam } : undefined,
     });
 
     componentEvents = component();

core/captcha.config.ts

@@ -0,0 +1,16 @@
+/**
+ *
+ * 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 { z } from 'zod';
+
+export const captchaConfigSchema = z
+  .object({
+    mode: z.enum(['visible', 'invisible']).optional(),
+  })
+  .strict();

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.test.ts

@@ -10,7 +10,7 @@
 import { describe, expect, it } from 'vitest';
 
 import { buildCallbackMetadata, buildStepMetadata } from './metadata.utilities';
-import { step1, step2 } from './step.mock';
+import { createJourneyStep, step1, step2 } from './step.mock';
 
 describe('Test metadata builder function for callbacks', () => {
   it('should have metadata without stage attributes', () => {
@@ -138,6 +138,88 @@ describe('Test metadata builder function for callbacks', () => {
   });
 });
 
+describe('Test metadata builder function for callbacks with initializationOptions', () => {
+  const captchaStep = createJourneyStep({
+    authId: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9',
+    callbacks: [
+      {
+        type: 'ReCaptchaCallback',
+        output: [{ name: 'recaptchaSiteKey', value: 'test-site-key' }],
+        input: [{ name: 'IDToken1', value: '' }],
+        _id: 0,
+      },
+    ],
+    status: 200,
+  });
+
+  const enterpriseStep = createJourneyStep({
+    authId: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9',
+    callbacks: [
+      {
+        type: '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: '' },
+        ],
+        _id: 0,
+      },
+    ],
+    status: 200,
+  });
+
+  it('should attach initOptions.mode to ReCaptchaCallback when captcha config provided', () => {
+    const result = buildCallbackMetadata(captchaStep, () => false, null, {
+      captcha: { mode: 'invisible' },
+    });
+
+    expect(result[0].initOptions).toStrictEqual({ mode: 'invisible' });
+  });
+
+  it('should attach initOptions.mode to ReCaptchaEnterpriseCallback when captcha config provided', () => {
+    const result = buildCallbackMetadata(enterpriseStep, () => false, null, {
+      captcha: { mode: 'visible' },
+    });
+
+    expect(result[0].initOptions).toStrictEqual({ mode: 'visible' });
+  });
+
+  it('should attach initOptions.recaptchaAction when provided', () => {
+    const result = buildCallbackMetadata(captchaStep, () => false, null, {
+      recaptchaAction: 'LOGIN',
+    });
+
+    expect(result[0].initOptions).toStrictEqual({ recaptchaAction: 'LOGIN' });
+  });
+
+  it('should merge captcha config and recaptchaAction into initOptions', () => {
+    const result = buildCallbackMetadata(captchaStep, () => false, null, {
+      captcha: { mode: 'invisible' },
+      recaptchaAction: 'SIGNUP',
+    });
+
+    expect(result[0].initOptions).toStrictEqual({ mode: 'invisible', recaptchaAction: 'SIGNUP' });
+  });
+
+  it('should not attach initOptions when initializationOptions is null', () => {
+    const result = buildCallbackMetadata(captchaStep, () => false, null, null);
+
+    expect(result[0].initOptions).toBeUndefined();
+  });
+
+  it('should not attach initOptions when captcha config and recaptchaAction are absent', () => {
+    const result = buildCallbackMetadata(captchaStep, () => false, null, {
+      someOtherOption: true,
+    });
+
+    expect(result[0].initOptions).toBeUndefined();
+  });
+});
+
 describe('Test metadata builder function for step', () => {
   it('should have metadata without stage attributes', () => {
     const callbackMetadata = [

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,14 @@ export function buildCallbackMetadata(
       stageCbMetadata = stageCbArray[callbackCount[callbackType] - 1];
     }
 
+    if (captchaCallbackTypes.has(callbackType)) {
+      const captchaConfig = initializationOptions?.captcha as Record<string, unknown> | undefined;
+      const recaptchaAction = initializationOptions?.recaptchaAction as string | null | undefined;
+      if (captchaConfig || recaptchaAction) {
+        initOptions = { ...captchaConfig, ...(recaptchaAction && { recaptchaAction }) };
+      }
+    }
+
     return {
       derived: {
         canForceUserInputOptionality: canForceUserInputOptionality(callback),
@@ -68,6 +81,7 @@ export function buildCallbackMetadata(
           ...stageCbMetadata,
         },
       }),
+      ...(initOptions && { initOptions }),
     };
   });
 }